AI 코딩 도구에 주는 설명서는 짧아야 한다
프로젝트 설명 파일이 27만 자까지 불어난 일을 겪은 뒤, 저희는 모든 파일을 500줄 안팎으로 유지합니다. 그 이유와 관리 방법을 적었습니다.
Claude Code 같은 AI 코딩 도구는 프로젝트 폴더에 있는 CLAUDE.md 등의 마크다운 파일을 읽고 일을 시작합니다. 프로젝트를 안내하는 설명서인 셈입니다. 설명이 자세할수록 도구가 알아서 일을 더 잘할 것 같지만, 저희가 겪은 결과는 반대였습니다.
27만 자가 된 설명서
저희 앱 중 하나인 Pilofy의 설명서는 작업 기록이 계속 쌓이면서 27만 자까지 불어났습니다. 그 무렵 API 529 오류가 반복해서 났습니다.
529는 서버가 혼잡할 때 나오는 오류라서 설명서 크기만이 원인이라고 단정할 수는 없습니다. 다만 도구가 파일을 열 때마다 전체를 다시 읽는 만큼, 파일 하나가 27만 자까지 커진 것은 그 자체로 바로잡아야 할 문제였습니다. 줄 수가 늘어날수록 읽는 양이 많아지고, 그만큼 속도는 느려지고 비용은 커집니다.
그래서 정한 규칙
모든 프로젝트에 같은 규칙을 적용합니다.
- 코드든 마크다운이든 한 파일은 500줄 안팎. 넘으면 관심사 단위로 쪼갭니다. 코드는
파일명+관심사.확장자로, 문서는 주제별 새 파일로 나눕니다. CLAUDE.md는 200줄 안팎. 세션을 열 때마다 도구가 파일 전체를 읽어 들이므로 더 짧게 유지하고, 현재 상태를 보여 주는 "스냅샷"만 적습니다.- 끝난 작업 기록은 따로 옮깁니다. 완료된 내용은
CLAUDE_HISTORY.md같은 별도 파일로 보냅니다. - 문서 지도. 설명서 윗부분에 "어떤 파일을 언제 열어 보나"를 표로 정리해 두어, 모든 내용을 미리 읽지 않고 필요할 때만 찾아 열게 합니다.
쪼개기만 해서는 소용이 없다
파일을 나누기만 하고 완료된 항목을 지우지 않으면, 새로 나눈 파일에서 같은 문제가 그대로 반복됩니다. 그래서 쪼갠 뒤 끝난 내용은 보관용 파일로 보내고 본문에서는 지운다는 것까지 규칙에 넣었습니다.
하위 프로젝트 세션을 열 때 상위 폴더의 설명서까지 자동으로 불러오는 점도 문제였습니다. 개별 프로젝트 세션을 열었을 뿐인데 전체 프로젝트 현황표 11KB까지 함께 읽고 있었습니다. 그 뒤로는 상위 설명서에 모든 프로젝트에 공통으로 필요한 내용만 남기고, 현황표처럼 부피가 큰 문서는 별도 폴더로 빼서 문서 지도에 한 줄만 적어 둡니다.
규칙이 적혀 있다고 지켜지지는 않는다
이 규칙은 한 번 누락된 적도 있습니다. 새 프로젝트를 만들면서 최상단에 규칙을 넣는 것을 빠뜨렸다가 지적을 받았습니다. 그 뒤로는 작업을 마무리할 때마다 줄 수를 직접 확인하고, 새 프로젝트를 만들 때 설명서 맨 위에 이 규칙부터 적기로 절차를 정했습니다.
지금 적용하기 쉬운 방법
- 설명서 줄 수부터 세어 보세요. 500줄이 넘으면 이미 늦었을 수 있습니다.
- "지금 하는 일"과 "끝난 일"을 나눕니다. 끝난 일은 다른 파일로 옮깁니다.
- 자주 안 보는 내용은 별도 파일로 빼고, 설명서에는 언제 열어 보면 되는지 한 줄만 적습니다.
- 설명서에 같은 내용을 반복해서 적지 않았는지 확인합니다.
- 일을 마칠 때 줄 수를 다시 확인하는 습관을 만듭니다.
설명서는 AI에게 주는 지시서이면서 우리가 매번 읽는 문서이기도 합니다. 길게 쓰는 것보다 필요한 것만 남기고 계속 정리하는 쪽이 오래 갑니다.