여러분은 AI로 코딩할 때 다양한 문서, skills, md를 참조하고 계실 것입니다. 특히 OpenSpec 등을 이용한 사양 주도 개발(Specification-driven development)에서는 문서가 쌓여 사일로화(Silo)되는 경우가 많습니다. 제 주변에서도 오랫동안 방치되어 시간이 오래 걸리니 의욕이 생기지 않는다는 목소리를 자주 듣습니다.

이번 글은 그러한 분들에게 문서 정리의 중요성을 알리고 정리를 시작하게 만들고 싶어서!! 작성하는 글입니다.

먼저 당연한 이야기지만, 왜 AI의 컨텍스트 파일은 반드시 부패하는가에 대해 말씀드리겠습니다.

사양 주도 개발의 문서는 작성자 수 × 시간으로 층층이 쌓이는 구조를 가지고 있습니다.

또한, 대부분의 사람은 skills 등의 문서를 AI에게 쓰게 할 것입니다. (그것이 나쁘다는 뜻은 아니며, 저 또한 그렇습니다만) 그렇게 되면 처음부터 끝까지 인간이 리뷰하지 않는 경우가 많기 때문에 다음과 같은 현상이 증가합니다.

증가하는 이유	결과
PBI를 겹칠 때마다 「보충 규칙」이 추가됨	단락이 늘어나 300행, 500행, 1000행으로!
...	[link](old-path.md)와 같은 데드 링크(Dead link)가 남음
「2025-XX 최근에」와 같은 상대적 표현이 1년이 지나 낡아짐	오래된 날짜 + 「최근」, 「최신」의 조합이 의미 반전

위와 같이 쓰레기가 된 문서가 장기간 방치되면...

관리되지 않는 문서의 증가 → AI의 할루시네이션 (Hallucination) → 재작업으로 인한 토큰(Token) 수 증가로 이어져 비용이 증대되고 결과물의 품질이 저하될 수 있습니다.

특히 최근의 LLM 모델은 토큰 소비가 심한 경우가 많아, 정액제 플랜에서 상한선에 걸려 개발 효율이 현저히 저하되는 일도 빈번합니다.

서두에서도 언급했듯이, 「오랫동안 방치되어 시간이 걸리니 의욕이 생기지 않는다」고 느끼는 분들이 많을지도 모릅니다. 이는 인간이 문서를 반드시 리뷰해야 한다고 무겁게 생각하기 때문이라고 생각합니다.

하지만 이 또한 AI에게 대부분을 맡기면 됩니다. 매우 당연한 이야기지만, 의외로 「인간이 문서 리뷰를 해야 한다」는 고정관념에 얽매이기 쉽다고 느낍니다.

AI가 메인으로 문서를 정리함으로써 지금까지 쌓아온 지식이나 구현 규칙 등이 제대로 작동하지 않을까 걱정될 수도 있습니다. 물론 그럴 가능성도 있습니다.

하지만 설령 실패한다 하더라도 대상이 되는 것은 원래부터 파탄 나 있었던 문서입니다. 그렇게 생각하면 심리적 장벽이 낮아지지 않을까 합니다.

또한, Git으로 관리하고 있다면 즉시 되돌릴 수 있으므로 잘못 작성되었더라도 바로 복구할 수 있습니다. 그렇게 두려워할 일은 아닙니다.

현재 저는 탐지 → 대화(Wall-hitting) → 적용(apply)을 일괄적으로 수행하는 skills를 2주에 한 번씩 실행하고 있습니다. 이 skills는 사일로화되어 있어 처음에는 정리하는 데 반나절 정도 시간이 걸렸지만, 이후에는 1시간 정도로 완료할 수 있어 상당히 간편하게 운용하고 있습니다.

1. 스캔 (Scan)

/cleanup-context를 입력하면, skill은 allowlist 내의 파일을 열거하여 다음에 설명할 R1~R6를 전건 적용하여 검사한다.

2. 리포트 출력 (Report Output)

검출 결과는 stdout과 pending md에 동일한 내용으로 출력된다.

예시

# cleanup-context 리포트
- 실행 일시: 2026-06-11 16:28 JST
- 스캔 대상: 약 20개 파일
...

3. 대화 단계 (이 부분이 skill의 핵심)

여기서 AI는 항목별로 인간에게 확인을 요청한다. 판단은 반드시 다음 3가지 중 하나로 수렴시킨다.

apply 확정: 「R1 데드 링크 3건, 삭제해도 될까요?」 → 인간 「OK」 → pending md는 그대로 -
방침 변경: 「R2에서 XLINKRE-XXX를 진행형으로 판정했는데, 이것을 이력으로 남길까요?」 → 인간 「남기는 형태로 수정해줘」 → pending md를 Edit로 업데이트 -
보류: 「R4에서 CLAUDE.md 529행을 검출했는데, 이것은 설계상(by design) 집약된 것인가요?」 → 인간 「집약 의도 설명」 → pending md에서 삭제

4. 최종 승인 + 적용 (Final Approval + apply)

대화가 끝나면 AskUserQuestion으로 최종 승인을 받습니다.

대화 완료. 확정된 수정은 N건(R1=a / R2=b / ...). 이 내용으로 apply 해도 될까요?

OK → Edit를 순차적으로 실행 (NG: 벽치기(Wall-hitting)로 돌아감) → 다시 하기 (NG: 중단) → skill 종료. pending md는 남겨둠

• 플로우는 OpenSpec의 플로우를 기반으로 하고 있습니다.

ID	검출 내용	예
R1	데드 링크 (Dead Link)	[guide](docs/old-guide.md)의 참조 대상이 test -f에서 fail
R2	완료된 PBI에 대한 현재 진행형 참조	완료된 PBI 번호 + 동일 단락의 「진행 중」, 「대응 중」
R3	스냅샷 금지 문구	「총 18 Phase」, 「Item 1~8」과 같이 업데이트가 필요한 수치 표현
R4	행 수 비대화	wc -l로 300행 초과
R5	중복 섹션	동일한 헤더가 여러 파일에 존재, 본문 유사도 80% 초과
R6	오래된 날짜 + 현재 진행형	6개월 이상 전의 날짜 + 「최근」, 「최신」

AI를 활용한 문서 정리는 사람이 전부 읽고 리뷰한다는 전제하에 진행하면 번거롭지만, 검출과 정리 초안 작성을 AI에게 맡기고 사람은 벽치기(Wall-hitting)와 최종 승인만 담당하는 분업 체계로 만든다면 2주에 한 번, 1시간 만에 처리할 수 있습니다.

특히 사양 주도 개발 (Specification-driven development)을 하고 있어 skills나 md 파일이 늘어난 분들은, 처음 한 번만 기운을 내어 정리해 두고 이후에는 정기 실행 프로세스에 태우는 것을 추천합니다. 첫 번째 고비만 넘기면 그다음부터는 차이(diff)만 정리하면 되므로 가벼워집니다.

또한 그 첫 번째 과정도 AI를 사용할 수 있으므로 상상하는 것보다 훨씬 적은 공수로 끝낼 수 있습니다.

「이 문서가 썩어 있다는 건 알고 있지만, 손을 대지 못하고 있다」는 분들의 무거운 몸을 일으키는 계기가 된다면 좋겠습니다.