저는 대규모 프로덕션 앱(Svelte + Express/Knex, Oracle→Postgres 포팅, ~150 Cypress 스펙, ~30 기능 모듈)에서 매일 Claude Code를 사용해 왔습니다. 초기에는 모든 세션이 똑같이 시작되었습니다. 즉, Claude가 주변을 무차별적으로 검색하고(grepping), 아키텍처를 재발견하며, 같은 함정에 빠지는 것이었습니다. 그래서 저는 Markdown 형식의 '컨텍스트 팩(context pack)'을 만들었는데, 이 컨텍스트 팩은 코드를 건드리기 전에 Claude가 읽게 하는 것입니다. 그리고 이것이 모든 것을 바꿔 놓았습니다.
구조는 다음과 같습니다: CLAUDE.md ← 매 세션마다 자동 로드되는 파일 (작업 규칙) docs/
└── claude/ ← AI 전용 문서만 포함 ├── INDEX.md ← 진입점(entry point): 의사 결정표 형식으로 작성됨 (
이 부분이 지속 가능하게 만드는 핵심입니다. 에이전트가 에이전트를 위해 작성하고, 위키처럼 방치되는 것이 아니라 각 작업의 자연스러운 일부로 업데이트하는 문서들입니다. GOTCHAS.md가 쓰레기장이 되는 것을 막은 규칙은 다음과 같습니다: 영역별 트랩(area-specific traps)은 해당 영역의 플로우 파일에 넣고, GOTCHAS에는 넣지 마십시오. GOTCHAS는 오직 교차 관심사(cross-cutting stuff)만을 위한 것입니다 (Windows에서의 CRLF, process.cwd(), Oracle 대 PG 방언, 타입 검사기 기준선 등). 제가 이 규칙을 적용하기 전에는, GOTCHAS가 읽을 수 없는 덤프 파일로 부풀어 올라서 Claude가 훑어보고 무시했습니다. 크기 예산(Size budgets)이 강제됩니다: 플로우 파일 ≤ ~250줄, GOTCHAS ≤ ~200줄. 서술문은 금지하고, 불릿 포인트, 테이블, 파일:라인 참조만 허용합니다. 초과 시 → 분할해야 합니다. 큐레이션된 250줄짜리 파일이 50개의 grep 결과보다 훨씬 좋고 컨텍스트 비용도 적게 듭니다. 중요하지만 작은 추가 사항들: MD 파일 간의 상대 링크(tiny script로 검사됨) (깨진 경우: 0개 또는 배포되지 않음). Claude가 기존 오류 개수를 알 수 있도록 baselines/ 폴더를 만듭니다 (저희는 ~6000개의 레거시 svelte-check 오류가 있는데, 기준선이 없으면 패닉하거나 이를 수정하려고 시도할 것입니다). 사용자 문서(user guides 등)는 별도의 폴더에 보관합니다. 컨텍스트 팩은 AI를 위해 작성됩니다: 간결하고 밀도가 높아야 합니다. 청중을 혼합하면 둘 다 망가집니다. 결과적으로, 세션이 시작될 때 Claude는 필요한 테이블, 컴포넌트, 트랩이 무엇인지 이미 알고 시작하며, 처음 20개의 도구 호출로 이를 재발견하느라 에너지를 소모하지 않습니다. /u/Short_Regular_7191 제출 [링크] [댓글]