AI 코딩 컨텍스트 예산과 지침 파일 다이어트

핵심 요약

3편의 목표는 매 턴 반복되는 지침과 파일을 줄이되 완료 품질을 유지하는 컨텍스트 예산을 만드는 것임
공통 불변 규칙, 작업별 계약, 조사 증거를 서로 다른 파일로 분리해야 정보 수명에 맞춰 읽을 수 있음
AGENTS.md·CLAUDE.md·GEMINI.md에 같은 긴 문장을 복제하면 세 도구의 시작 컨텍스트와 유지 비용이 함께 늘어남
파일 수보다 중요한 지표는 현재 작업과 무관한 입력의 비율과 줄인 뒤 발생한 재질문·재작업임
이 편의 산출물인 context-profile.md와 얇은 지침 파일은 4편의 세션 인계 규칙에 사용됨

기준선에서 반복 입력을 먼저 찾음

2편의 실패 작업 중 시작부터 잘못된 파일을 읽은 사례를 우선 분류해야 함
- 지침 부족으로 범위를 놓친 실패와 지침 과다로 핵심 조건을 놓친 실패를 구분함
- 컨텍스트를 줄인 뒤 품질이 나빠졌다면 절감이 아니라 비용의 지연일 수 있음
컨텍스트를 세 수명으로 나누면 삭제 기준이 명확해짐
- 저장소 수명은 패키지 관리자·금지 명령·검증 계약처럼 자주 바뀌지 않는 규칙임
- 작업 수명은 목표·허용 경로·완료 조건처럼 한 작업이 끝나면 폐기되는 사실임
- 조사 수명은 로그 조각·가설·실패한 접근처럼 다음 판단까지만 필요한 증거임
OpenAI는 좋은 작업 지시에 목표·컨텍스트·제약·완료 조건을 포함하고 지속 지침은 AGENTS.md에 두도록 권장함¹
- 이 권장은 모든 사실을 AGENTS.md에 넣으라는 뜻이 아님
- 작업마다 달라지는 목표와 로그는 짧은 작업 계약으로 분리하는 편이 같은 구조에 부합함

공통 규칙은 한 번만 정의함

저장소의 canonical 규칙은 루트 AGENTS.md 하나에 두는 편이 적절함
- OpenAI 문서는 AGENTS.md를 전역에서 현재 디렉터리까지 계층적으로 발견하고 가까운 파일이 뒤의 지침으로 적용된다고 설명함²
- 큰 모노레포에서는 하위 AGENTS.md에 해당 영역의 예외만 추가해 전체 규칙 복사를 피함
도구별 지침 파일은 canonical 문서의 위치와 도구에만 필요한 차이만 담아야 함
- CLAUDE.md에는 공통 규칙 경로, Claude 전용 명령과 메모리 범위만 둠
- GEMINI.md에는 공통 규칙 경로, Gemini 전용 컨텍스트 파일과 도구 제한만 둠
- 도구가 다른 파일을 자동으로 읽지 못하면 ‘먼저 이 파일을 읽음’이라는 한 줄 어댑터를 사용함

AGENTS.md                # canonical repository rules
apps/web/AGENTS.md       # only web-specific overrides
CLAUDE.md                # read AGENTS.md + Claude-only notes
GEMINI.md                # read AGENTS.md + Gemini-only notes
docs/ai/task.md          # one task contract
docs/ai/context.md       # temporary evidence

규칙 하나에는 행동과 검증 가능한 결과를 함께 써야 함
- ‘조심해서 수정함’보다 ‘apps/web만 수정하고 해당 workspace test를 실행함’이 짧고 판정 가능함
- 배경 설명이 필요하면 규칙 본문이 아니라 링크된 설계 문서에 두고 필요할 때만 읽게 함

작업 계약은 8줄 안팎으로 닫음

한 작업의 첫 입력은 목적과 경계를 스스로 설명해야 함
- 목표, 현재 증상, 허용 경로, 금지 경로, 검증 명령, 완료 조건을 포함함
- 이미 확인한 사실 한두 개와 아직 모르는 질문 하나만 추가함

# WEB-41

- Goal: 검색 결과의 동점 정렬을 안정화함
- Symptom: 같은 점수 문서의 순서가 실행마다 달라짐
- Allowed: apps/web/lib/tech/search*
- Protected: UI와 콘텐츠 파일
- Verify: bun run --filter @jongminchung/web test
- Done: 회귀 테스트 통과와 기존 검색 benchmark 유지
- Known: 점수 계산은 안정적임
- Unknown: 최종 tie-breaker의 locale 영향

파일은 ‘전체 저장소’가 아니라 검색에서 좁혀진 후보만 읽혀야 함
- 먼저 파일명과 심볼을 검색하고 상위 후보의 관련 범위만 엶
- 구현이 다른 경계를 건드린다는 증거가 생길 때만 읽기 범위를 한 단계 넓힘
Gemini CLI는 컨텍스트 파일명과 검색할 디렉터리 수를 설정할 수 있음³
- context.fileName과 context.discoveryMaxDirs는 자동 발견 범위를 통제하는 수단임
- 무조건 작은 값이 정답은 아니며 모노레포의 실제 깊이에 맞춰 누락 여부를 검증해야 함

컨텍스트 다이어트는 A/B로 검증함

2편의 20건 중 난이도가 비슷한 짝을 만들어 기존 방식과 예산 방식에 배정함
- 기존 방식은 현재 지침과 자연스러운 탐색을 유지함
- 예산 방식은 얇은 지침, 8줄 작업 계약, 첫 읽기 후보 제한을 적용함
입력 감소만으로 성공을 선언하면 안 됨
- 공급자 내부 완료 작업당 소진량과 턴 수를 비교함
- 잘못된 파일 수정, 규칙 재질문, 사람 힌트, 재작업 시간을 함께 기록함
작성자의 권장 유지 기준은 중앙값 15% 이상 감소와 품질 하한 유지임
- 15%는 공급자 보장치가 아니라 작은 개인 실험에서 잡음보다 큰 변화를 보기 위한 운영 기준임
- 수용률이 5%p 넘게 낮아지면 지침을 더 줄이지 말고 빠진 규칙을 복구함

다음 편으로 컨텍스트 프로필을 넘김

context-profile.md에는 항상 읽기·조건부 읽기·금지 입력을 구분해 기록함
- 항상 읽기는 루트 규칙과 현재 task.md임
- 조건부 읽기는 관련 설계 문서·테스트·최근 diff임
- 금지 입력은 전체 대화 전문·전체 빌드 로그·무관한 디렉터리임
4편에서는 이 프로필을 유지한 채 세션만 새로 시작하거나 압축함
- 새 작업과 같은 작업의 경계를 구분해야 컨텍스트 감소 효과와 세션 관리 효과가 섞이지 않음
- 작업이 바뀔 때는 handoff.md만 넘기고 대화 전문은 넘기지 않음