예전에는 제가 배운 방식대로 docs/ 폴더를 작성하곤 했습니다. 서술적인 단락, 약간의 배경 설명, 그리고 신입사원에게 건네주는 '왜 이것을 했는지'에 대한 내러티브 같은 것이었죠. 그러다 문득 무언가를 알아차렸습니다. 매일 이 파일들을 열어보는 유일한 독자는 인간이 아니었습니다. 그것은 에이전트였고, 세션 시작 시마다 새롭게 로드하며, 토큰 예산과 어제에 대한 기억이 전혀 없었죠.

그것은 '좋은 문서'의 의미를 변화시켰고, 실제로 제가 글쓰기 스타일을 업데이트한 것은 이 파일들 중 하나에 있는 오래된 한 줄 때문에 실제 버그가 발생했을 때였습니다.

설정 방법

제 my-git-manager 저장소에서, CLAUDE.md는 매 세션 시작 시 에이전트를 docs/project_notes/로 연결합니다:

## 프로젝트 메모리 시스템

기관 지식은 `docs/project_notes/`에 있습니다. 변경 사항을 제안하기 전에 확인하세요.
...

저 '프로토콜' 블록은 문서에 대한 설명이 아닙니다. 그것은 라우팅 로직입니다. 마치 if/else와 같은 형태인데,

읽기에는 아무 문제가 없었습니다. 사람이 훑어보기에는 잘못된 부분이 없어 보였죠. 하지만 2026년 6월 23일, 실제 OSS(Open Source Software) 포크 및 PR 작업이 workflow 스코프도 필요하게 되면서 (.github/workflows/*.yml을 건드리는 브랜치를 푸시하려면 필요함), bugs.md에 실패를 문서화하는 항목이 생겼습니다. 하지만 아무도 돌아가서 에이전트가 세션 시작 시 실제로 읽는 key_facts.md의 요약(summary) 라인을 고치지 않았습니다. 6주 후, 에이전트는 그 오래된 정보를 신뢰하고 비슷한 푸시를 시도했고, 다시 같은 403 오류에 부딪혔습니다. 수정 사항은 코드베이스 안에 존재했습니다. 단지 에이전트가 실제로 열게 될 파일에는 없었을 뿐입니다.

- 필요한 토큰 스코프: `repo`, `user` — API를 통해 리포지토리를 삭제해야 한다면 `delete_repo`를 추가하고, 상위(upstream)의 `.github/workflows/*.yml` 변경 사항을 가져오는 브랜치를 푸시할 일이 있다면 `workflow`를 추가하세요 (OSS 기여 포크).
...

여기서 얻은 교훈은

사실(Facts)과 근거(rationale)는 의도적으로 다른 파일에 존재합니다. key_facts.md는 현재 상태(current-state)-전용입니다: 지금 무엇이 사실인지, 역사는 없습니다. decisions.md는 추가 전용 아키텍처 결정 기록(ADR) 항목입니다: 왜 무언가가 그렇게 구축되었는지, 시도하지 않은 경로까지 포함합니다. bugs.md는 사건 기반(incident-shaped)입니다: 증상, 근본 원인, 수정 사항. 저는 이 세 가지를 모두 담는 하나의 파일을 작성하려는 노력을 멈췄습니다. 왜

당신을 완전히 문자 그대로 받아들이고 '잠깐, 이게 아직도 사실인가?'라고 물어보지 않는 독자를 위해 글을 쓰는 것은 동료를 위해 글을 쓰는 것과는 다른 분야입니다. 이는 위키 페이지라기보다는 API 계약서를 작성하는 것에 가깝습니다. 저는 이것이 실제로 'AI 지원 개발'이 제 문서화 습관에 강요할 변화가 될 것이라고 예상하지 못했지만, 지금까지 실제 버그들을 잡아낸 것은 바로 이 점입니다.