파싱 규칙을 늘리기 전에, 실패 사례부터 - 오탐 2연쇄 경험담

기술 문서 수백 건을 마크다운으로 바꾼 뒤 ## 제목을 기준으로 본문을 정해진 칸(개요·원인·해결방법 등)에 나눠 담는 파서를 만들다가, 오탐을 잡으려던 로직이 더 큰 오탐을 만드는 경험을 함.

첫 번째 문제

리눅스 명령 예시 안의 # 설정 확인 같은 셸 주석 줄이 마크다운 제목(#)과 문법이 같아 제목으로 오인됨. 엉뚱한 내용이 개요 칸에 섞여 들어가는 오류가 16건 발생.

두 번째 문제 - 고치려다 더 크게 틀어짐

이를 막으려고 “지금 읽는 줄이 코드블록 안인지 밖인지” 추적하는 로직을 넣었는데, 본문에 남아 있던 백틱 세 개(```) 조각을 코드블록 시작으로 오인해 그 뒤 전부를 코드블록 안으로 간주해버림. 오탐 16건을 잡으려다 문서 전체를 날릴 뻔한 로직이 된 것.

배운 것

• 파싱 규칙을 정교하게 만들수록, 예상 못 한 입력에서 더 크게 틀어진다
• 규칙을 늘리기 전에 실패 사례를 먼저 모으는 순서가 맞다. 실패 사례 없이 추가한 규칙은 “무엇을 막는지”는 알아도 “무엇을 부수는지”는 모른다
• 결국 변형 섹션명은 별칭 사전으로, 셸 주석 오탐은 실패 사례를 모은 뒤 조건을 좁혀서 해소함