길게 쓸수록 안심했지만, 봇은 덜 읽었다
처음엔 불안해서 CLAUDE.md에 전부 적었다. 말투, 폴더 위치, 금지 사항, 지난 실수 기록까지 130줄. 그런데 아침마다 Claude Code가 분명히 적어둔 내용을 다시 물었다. 「이 폴더는 어디에 두나요?」 같은 질문이 하루 평균 7번이었다.
설명서는 길이가 아니라 첫 40줄의 밀도가 승부였다.
일주일 실험
같은 종류의 작업을 두 버전으로 돌렸다. 윈도우 디바이스에는 긴 버전, 맥미니에는 짧은 버전이다. 짧은 버전은 이렇게 만들었다.
1. 규칙을 「항상」「가끔」「기록용」 세 칸으로 나눈다.
2. 「항상」 규칙만 40줄 안에 남긴다.
3. 나머지는 docs 폴더의 별도 파일로 옮기고, 본문에는 파일 위치 한 줄만 적는다.
결과
• 되묻기: 하루 평균 7번에서 2번
• 같은 실수의 재발: 눈에 띄게 줄었다 (기록용 파일은 필요할 때만 열어보게 했다)
• 설명서 고치는 시간: 줄이 적으니 수정도 빨랐다
오늘 바로 따라하기
# 프로젝트 규칙 (40줄 이하)
항상
• 답은 한국어로 한다
• 파일을 지우기 전에 먼저 묻는다
자세한 건 여기
• 말투 가이드: docs/voice.md
• 지난 실수 기록: docs/incidents.md
하나 더
현황이나 진행 상태는 설명서에 쓰지 않는 편이 좋다. 상태는 금방 낡고, 낡은 문장이 섞이면 봇이 오래된 정보를 믿는다. 설명서에는 구조와 규칙만 두고, 오늘 할 일은 대화에서 말해주자.