Context Engineering — CLAUDE.md·AGENTS.md 설계기

도입 배경

Claude Code·Cursor·Copilot을 도입한 직후, 컴포넌트팀은 의외의 문제에 부딪혔습니다. 같은 모델, 같은 프롬프트인데 프로젝트마다 결과 품질이 천차만별이었던 겁니다.

원인을 추적해보니 모델 성능이 아니라 컨텍스트의 설계 차이였습니다. 한 프로젝트는 CLAUDE.md가 빈 파일이었고, 다른 프로젝트는 1,200줄짜리 위키 덤프가 들어 있었습니다. 어느 쪽도 모델이 제대로 활용하지 못했습니다.

2024년이 프롬프트 엔지니어의 해, 2025년이 RAG 아키텍트의 해였다면, 2026년은 컨텍스트 엔지니어가 인텔리전스를 행동으로 연결하는 인프라를 만드는 해라는 흐름과 정확히 일치하는 문제였습니다. 즉, "AI가 똑똑한가"보다 "AI에게 무엇을 어떻게 보여주는가"가 결과를 결정하는 단계로 들어선 것이었습니다. (Essamamdani)

이를 해결하기 위해 다음 4가지 요구사항을 만족하는 컨텍스트 파일 표준이 필요했습니다.

1. 클라이언트별 코딩 컨벤션·도메인 용어를 한 파일에서 관리
2. Claude Code, Cursor, Copilot 등 여러 도구가 같은 규칙을 따르도록 동기화
3. 토큰 효율성을 고려한 계층 구조 (모델이 매번 1만 줄을 다 읽지 않아도 되도록)
4. 신규 합류 개발자가 5분 안에 프로젝트 컨벤션을 이해할 수 있는 가독성

여러 패턴을 검토한 결과 AGENTS.md를 SSOT로 두고 도구별 파일을 자동 생성하는 구조가 가장 적합했습니다.

컨텍스트 파일 아키텍처

파일 구조는 다음과 같이 정리했습니다.

• AGENTS.md — 단일 진실 공급원(Single Source of Truth), 사람이 직접 편집하는 유일한 파일
• CLAUDE.md — Claude Code용, AGENTS.md에서 자동 생성
• .cursorrules — Cursor용, AGENTS.md에서 자동 생성
• .github/copilot-instructions.md — Copilot용, AGENTS.md에서 자동 생성
• docs/context/ — 도메인 용어 사전, 아키텍처 결정 기록(ADR), 외부 API 스펙 등 참조 문서
• tools/sync-agent-rules.ts — 동기화 스크립트, pre-commit 훅에서 실행

AGENTS.md 자체는 다음과 같은 5개 섹션으로 표준화했습니다.

1. 프로젝트 개요 — 1문단, 무엇을 만드는지·누가 쓰는지·핵심 제약
2. 기술 스택과 컨벤션 — 패키지 매니저, 린터 규칙, 디렉터리 구조, 금지 패턴
3. 도메인 용어 사전 — 한글 비즈니스 용어 ↔ 영문 코드 식별자 매핑
4. 워크플로 규칙 — PR 형식, 커밋 메시지, 테스트 요구사항, 배포 체크리스트
5. 참조 링크 — docs/context/ 하위 상세 문서로의 포인터

핵심 의사결정 3가지

1. 계층화된 컨텍스트로 토큰 비용 최적화

AGENTS.md 본체는 800줄 이내로 유지하고, 상세 ADR·API 스펙은 docs/context/에 분리해 모델이 필요할 때만 참조하도록 했습니다. Cloudflare가 "Code Mode"라 부르는 패턴 — 도구 정의를 처음부터 모두 로드하지 않고 에이전트가 필요할 때 코드로 호출하는 방식 — 이 일부 배포에서 98% 이상의 토큰 절감을 달성한 흐름과 같은 원리입니다. (Pento)

2. 도메인 용어 사전을 한글·영문 양방향으로 정의

의료 클라이언트의 "수가" → medicalFeeSchedule처럼 단방향 번역만 두면 모델이 영문 코드에서 한글로 역추적할 때 의미를 잃어버렸습니다. 양방향 매핑과 1줄 정의를 같이 적었습니다.

3. AGENTS.md 변경을 PR 필수 항목으로 강제

새 컨벤션이 코드에는 반영됐는데 컨텍스트 파일에는 빠지는 경우가 누적됐습니다. PR 템플릿에 "AGENTS.md 업데이트 필요 여부" 체크박스를 추가하고, CI에서 라벨 검증을 걸었습니다.

트러블슈팅: 컨텍스트 파일 운영 중 만난 4가지 함정

1. AGENTS.md 비대화로 인한 컨텍스트 윈도 낭비

6개월간 규칙이 누적되면서 한 프로젝트의 AGENTS.md가 2,400줄로 불어났습니다. Claude Code 세션 시작 때마다 약 12,000 토큰이 컨텍스트로 들어가, 정작 작업 코드를 위한 윈도가 줄어드는 현상이 발생했습니다.

원인: "한 번 추가한 규칙은 안 지운다"는 무의식적 합의가 누적된 결과였습니다. 이미 deprecated된 라이브러리에 대한 규칙도 그대로 남아 있었습니다.

해결: 분기마다 AGENTS.md 정리 세션을 의무화하고, 사용 빈도가 낮은 규칙은 docs/context/legacy.md로 이동시켰습니다. 본체 파일은 800줄 상한선을 lint 규칙으로 강제했습니다.

2. 한글·영문 혼용 시 모델의 컨텍스트 분리 실패

AGENTS.md에 한글 도메인 설명과 영문 코드 컨벤션을 섞어 적었더니, Claude Code가 한글 비즈니스 설명을 코드 주석으로 직접 복사해 넣는 케이스가 발생했습니다.

원인: 모델이 "이 문서의 내용은 모두 코드에 반영해야 할 지시사항"으로 해석하면서, 설명과 지시를 구분하지 못했습니다.

해결: 섹션마다 명시적 마커를 추가했습니다. ## 📖 설명 (참고용, 코드 반영 X) vs ## ⚙️ 규칙 (코드에 반드시 반영)처럼 시각적·의미적 구분을 두고, 모델 동작이 안정화됐습니다.

3. sync 스크립트의 도구별 포맷 차이 무시

단순히 AGENTS.md를 복사해 .cursorrules와 CLAUDE.md를 만들었더니, Cursor에서는 일부 규칙이 무시되는 현상이 있었습니다.

원인: Cursor의 .cursorrules는 짧고 명령형 문장을 선호하며, MCP 기반 도구 호출을 명시할 때 별도 포맷을 요구합니다. Claude Code의 CLAUDE.md는 마크다운 구조와 코드 블록을 더 풍부하게 활용할 수 있어, 단순 복사는 두 도구 모두에서 sub-optimal한 결과를 냈습니다. (Thoughtworks)

해결: sync-agent-rules.ts에 도구별 변환 로직을 추가했습니다. Cursor 출력은 명령형 단문으로 압축, Claude Code 출력은 섹션·예시 코드 블록을 보존, Copilot 출력은 인라인 힌트 형태로 가공했습니다.

4. 컨텍스트 파일 자체에 대한 보안 검토 누락

한 프로젝트에서 AGENTS.md에 클라이언트 내부 시스템 IP·DB 스키마 일부가 그대로 적혀 있었고, 이게 외부 MCP 서버를 통해 모델에 노출될 뻔한 상황이 있었습니다.

원인: 컨텍스트 파일을 "개발 문서"로 인식하면서 보안 검토 대상에서 제외해뒀습니다. 하지만 실제로는 매 세션마다 외부 모델에 송신되는 데이터였습니다.

해결: AGENTS.md와 docs/context/를 보안 리뷰 대상에 정식 포함하고, 민감 정보는 .env.example 패턴처럼 플레이스홀더(<DB_HOST>)로 치환하는 규칙을 도입했습니다. PR에 신규 식별자가 들어올 때 secret scanner가 함께 검사하도록 CI를 보강했습니다.

#ContextEngineering #ClaudeCode #Cursor #AGENTS.md