큰 프로덕션 코드베이스에서 Claude Code가 헤매지 않게 만드는 문서 구조
Svelte + Express/Knex 스택에 Oracle에서 로 옮긴 이력이 있고 테스트 약 150개, 기능 모듈 약 30개인 큰 프로덕션 앱에서, Claude Code를 매일 사용하면서 겪은 문제를 다룬다. 매 세션마다 Claude가 코드를 grep으로 여기저기 뒤지며 구조를 처음부터 다시 파악하고 같은 실수를 반복했다. 이를 해결하려고 Claude가 코드를 건드리기 전에 먼저 읽는 마크다운 '컨텍스트 팩'을 만들었다.
구성은 다음과 같다: 매 세션 자동으로 불러오는 (작업 규칙), 그리고 docs/claude/ 폴더 아래 AI 전용 문서들 — 어떤 작업이면 어떤 파일을 읽어야 하는지 알려주는 진입점 INDEX.md, 한 페이지짜리 전체 구조 요약 .md, 기능별로 파일·라우트·DB 테이블을 매핑한 MAP.md, 업계 약어를 DB 필드에 대응시킨 GLOSSARY.md, 비동기 작업·다국어 처리 같은 재사용 패턴을 담은 CONVENTIONS.md, 모범 컴포넌트와 자체 점검 체크리스트를 담은 S.md, 여러 영역에 걸친 함정만 모은 GOTCHAS.md, 기능 영역별 파일이 약 30개 있는 flows/ 폴더, 일회성 점검 기록을 담은 reports/, 알려진 에러 개수 같은 기준선을 담은 s/ 폴더다. 에는 문서 내용 자체가 아니라 작업 규칙이 담겨 있으며, 핵심 규칙은 Grep이나 Glob, Read로 코드를 뒤지기 전에 먼저 관련 문서를 읽으라는 것이다.
핵심 포인트
- Svelte + Express/Knex, Oracle→ 이관, 테스트 약 150개, 기능 모듈 약 30개 규모의 프로덕션 앱에서 검증됨
- 는 매 세션 자동 로드되며 문서 자체가 아니라 작업 규칙을 담음
- docs/claude/ 아래 INDEX, , MAP, GLOSSARY, CONVENTIONS, S, GOTCHAS로 문서를 역할별로 분리
- 핵심 규칙: Grep/Glob/Read로 코드를 뒤지기 전에 관련 문서를 먼저 읽게 함
- 기능 영역별로 flows/ 폴더에 약 30개 파일을 두어 세부 컨텍스트를 나눠 관리