프로젝트 규모가 어느 정도 커지면 AI 에이전트가 코드를 수정할 때 가장 큰 어려움은 "코드를 작성하지 못하는 것"이 아니라 "어떤 규칙을 따라야 하고 어떤 파일을 수정해야 하는지 모르는 것"입니다. 이 글에서는 실제 대규모 프로젝트에서 검증된 계층형 내비게이션 문서 체계를 소개합니다. 이 체계를 통해 AI 에이전트가 스스로 컨텍스트를 확보하고, 아키텍처 제약을 준수하며, 도메인 간 수정 시 파일을 빠뜨리지 않을 수 있습니다.
문제: AI 에이전트의 컨텍스트 딜레마
대규모 프로젝트에서 AI 프로그래밍 에이전트(GitHub Copilot, Claude, Cursor 등)를 사용할 때 흔히 겪는 문제점은 다음과 같습니다.
- 규칙 망각: "반드시 특정 비동기 프레임워크를 사용하라"고 알려줬는데, 다른 파일에서 금지된 방식으로 작성합니다.
- 잘못된 파일 수정: 동시에 3개 모듈의 코드를 수정해야 하는데, 1개만 수정합니다.
- 도메인 지식 부족: 초기화 순서, 이벤트 버스 규칙, 데이터 필드 명명 규칙을 이해하지 못합니다.
- 반복 설명: 새 대화를 시작할 때마다 프로젝트 아키텍처를 처음부터 설명해야 합니다.
근본 원인은 AI 에이전트가 구조화되고 스스로 검색할 수 있는 프로젝트 지식 베이스를 갖추지 못했기 때문입니다.
우리의 해결책은 4계층 문서 체계입니다: Constitution → Root Router → Domain Routers → Cookbook, 여기에 AI 에이전트 자체의 메모리 시스템을 다섯 번째 계층으로 추가합니다.
제1계층: Constitution — 헌법(철칙)
파일: .github/copilot-instructions.md
이 계층은 전체 체계의 기초입니다. 어떤 상황에서도 위반할 수 없는 전역 하드 규칙을 정의합니다.
GitHub Copilot은 이 파일을 매 대화 컨텍스트에 자동으로 주입합니다(GitHub의 기본 기능). 다른 에이전트(예: Claude Code)는 시작 시 수동으로 읽어야 합니다.
Constitution의 내용은 카테고리별로 정리됩니다. 다음은 몇 가지 대표적인 항목입니다(비식별화됨).
설계 원칙:
- "무엇을 하면 안 되는지"만 작성하며, 내비게이션이나 구체적인 구현은 다루지 않음
- 각 규칙은 실제 버그나 재작업에서 비롯됨 — 예를 들어 "DTO 필드명은
id이지entityId가 아님"은 AI 에이전트가 필드명을 여러 번 잘못 사용했기 때문에 추가됨 - 형식은 간결하게 유지하여 토큰 제한 내에서 완전히 로드될 수 있도록 함
Constitution은 법 체계에서의 헌법과 같습니다. 무엇을 해야 하는지 알려주지 않지만, 무엇을 절대 해서는 안 되는지 명확히 알려줍니다.
제2계층: Root CLAUDE.md — 프로젝트 라우터
파일: 프로젝트 루트 디렉터리의 CLAUDE.md
Constitution이 "법"이라면, Root CLAUDE.md는 "지도"입니다. 프로젝트의 전체 개요와 작업 라우팅 테이블을 제공합니다.
AI 에이전트가 작업을 받으면 먼저 이 표를 확인하여 어떤 도메인 문서를 읽어야 할지 파악합니다. 코드베이스 전체를 무작정 검색할 필요가 없습니다.
Root CLAUDE.md에는 다음도 포함됩니다.
- 프로젝트 개요 및 핵심 비즈니스 루프 설명
- 기술 스택 퀵 레퍼런스
- 디렉터리 구조도
- 주요 아키텍처 패턴 개요(이벤트 기반, 의존성 주입, 인터페이스 분리 등)
설계 원칙: 내비게이션만 제공하고 규칙은 정의하지 않음. 모든 규칙은 Constitution에 있습니다. Root는 단지 "어디를 봐야 하는지" 알려줄 뿐입니다.
제3계층: Domain CLAUDE.md — 도메인 라우터
분포: 각 주요 하위 디렉터리에 하나씩, 프로젝트 전체에 18개.
이 계층이 체계의 핵심 작업 계층입니다. 각 도메인 라우터는 다음을 포함합니다.
3.1 상위 선언
각 파일은 자신의 상위 항목과 최종 권위 소스를 명시적으로 선언하여 명확한 참조 체인을 형성합니다.
3.2 파일 역할 테이블
해당 디렉터리에 있는 각 파일이 무엇이고 어떤 역할을 하는지 나열합니다.
이를 통해 AI 에이전트는 모든 파일을 열어 코드를 읽지 않고도 "어떤 파일을 수정해야 하는지" 판단할 수 있습니다.
3.3 초기화 순서 및 의존성 제약
3.4 하위 도메인 라우팅
큰 도메인(예: Core)은 계속해서 하위 계층으로 나뉩니다.
트리형 참조 네트워크
모든 CLAUDE.md는 참조 트리를 형성합니다.
참조 방향:
- 상향: 각 파일이 상위 + Constitution을 선언
- 하향: 상위가 하위 도메인을 나열
- 수평: 작업 라우팅 테이블이 형제 도메인을 가리킴
- 교차 도메인: Cookbook을 가리킴
설계 원칙: 각 CLAUDE.md는 독립적인 컨텍스트 패키지입니다. 읽고 나면 해당 디렉터리에서 무엇을 할 수 있고, 무엇을 할 수 없으며, 다른 것을 수정하려면 어디로 가야 하는지 알 수 있습니다.
제4계층: Cookbook — 교차 도메인 작업 매뉴얼
디렉터리: Docs/Cookbook/
앞의 세 계층은 "한 도메인 내에서 어떻게 수정할지"에 대한 문제를 해결합니다. 하지만 현실에서는 많은 작업이 여러 도메인을 동시에 수정해야 합니다. 예를 들어:
- 새 런타임 서비스 추가 → DI 등록, 시작 시퀀스, 저장 시스템, UI까지 수정해야 함
- 새 데이터 모델 유형 추가 → 모델 정의, 인터페이스, 데이터 관리자, UGC 모드 지원까지 수정해야 함
Cookbook은 이러한 일반적인 작업에 대해 단계별 체크리스트를 제공합니다.
각 Cookbook 항목은 다음을 표시합니다.
- 수정해야 할 파일(여러 도메인에 걸쳐 있음)
- 수정 순서
- 준수해야 할 제약 조건(Constitution에서)
- 자주 실수하는 부분
설계 원칙: Cookbook은 절차 지식이지 구조 지식이 아닙니다. Domain CLAUDE.md는 "여기에 무엇이 있는지" 알려주고, Cookbook은 "이 작업을 수행하려면 어떤 절차를 따라야 하는지" 알려줍니다.
제5계층: AI 메모리 시스템 — 임시 및 영구
문서 체계는 프로젝트 지식 문제를 해결하지만, AI 에이전트는 작업 기억도 필요합니다. 우리는 에이전트 자체의 메모리 메커니즘을 세 가지 범위로 활용합니다.
| 범위 | 경로 | 수명 | 용도 |
|---|---|---|---|
| Session Memory | /memories/session/ | 현재 대화 | 작업 진행 상황, 중간 발견, 임시 메모 |
| User Memory | /memories/ | 모든 대화에 걸쳐 | 사용자 선호도, 자주 사용하는 명령어, 경험 교훈 |
| Repo Memory | /memories/repo/ | 대화를 넘어, 저장소에 바인딩 | 코드베이스 규칙, 검증된 빌드 명령어 |
Session Memory는 특히 중요합니다. 작업을 여러 단계로 완료해야 할 때 AI 에이전트는 Session Memory에 "어디까지 했는지, 무엇을 발견했는지, 무엇이 남았는지"를 기록하여 중간에 중단되더라도 컨텍스트를 복원할 수 있습니다.
실제 워크플로
AI 에이전트가 "엔터티에 새 속성 차원을 추가하라"는 작업을 받았을 때의 전체 워크플로는 다음과 같습니다.
전체 과정에서 AI 에이전트는 인간의 단계별 지도가 필요하지 않으며, 코드베이스 전체를 운에 맡겨 검색할 필요도 없습니다.
설계 노하우
왜 코드 주석 대신 Markdown을 선택했는가?
코드 주석은 국소적입니다. 해당 파일을 열어야만 볼 수 있습니다. 반면 AI 에이전트는 파일을 열기 전에 어떤 파일을 열어야 하는지 알 필요가 있습니다. CLAUDE.md는 메타정보를 제공하며, 이는 어떤 단일 소스 파일의 범위를 넘어섭니다.
왜 하나의 큰 문서가 아니라 계층 구조로 설계했는가?
10,000줄짜리 문서는 AI의 컨텍스트 창을 폭발시킵니다. 계층 구조는 현재 작업과 관련된 컨텍스트만 로드되도록 보장합니다. Constitution(~100줄) + Root(~150줄) + 1-2개 도메인(각 ~100줄) = 총 약 500줄로, 토큰 예산 내에 충분히 들어옵니다.
왜 Constitution을 .github/ 아래에 두는가?
GitHub Copilot이 .github/copilot-instructions.md를 기본적으로 자동 로드하기 때문입니다. 즉, 가장 중요한 규칙이 별도의 작업 없이 매 대화에 주입됩니다. 다른 에이전트도 유사한 메커니즘(예: Claude Code의 CLAUDE.md, Cursor의 .cursorrules)을 통해 해당 파일을 자동 로드할 수 있습니다.
각 Constitution 규칙 뒤에는 이야기가 있다
우리는 "예방적으로" 규칙을 추가하지 않습니다. 모든 철칙은 실제 버그, 재작업, 또는 AI 에이전트의 잘못된 출력에서 비롯됩니다. 예를 들어:
- "DTO 필드명은
id이지entityId가 아님" — AI 에이전트가 필드명을 세 번 잘못 추측했기 때문 - "저장 데이터에서 참조 형식 리스트는 깊은 복사" — 얕은 복사로 인해 발견하기 어려운 저장 데이터 손상이 발생했기 때문
- "애니메이션 트윈은 반드시 생명주기에 바인딩" — 장면 전환 시 트윈이 정리되지 않아 null 참조 오류가 발생했기 때문
CLAUDE.md 명명법에 관하여
CLAUDE.md라는 이름은 Anthropic의 Claude Code 규칙에서 비롯되었습니다. Claude Code는 작업 디렉터리의 CLAUDE.md 파일을 자동으로 읽습니다. 하지만 우리 체계에서 그 역할은 특정 AI 도구를 넘어섰습니다. 어떤 AI 에이전트(심지어 인간 개발자)라도 이 내비게이션 체계를 따라 필요한 컨텍스트를 찾을 수 있습니다. AGENTS.md, CONTEXT.md 또는 원하는 다른 이름으로 자유롭게 변경해도 됩니다. 중요한 것은 파일 이름이 아니라 계층형 내비게이션 구조 자체입니다.
요약
| 계층 | 파일 | 역할 | 로드 방식 |
|---|---|---|---|
| Constitution | .github/copilot-instructions.md | 위반할 수 없는 전역 철칙 | Copilot 자동 / 다른 에이전트 수동 |
| Root Router | CLAUDE.md(루트 디렉터리) | 프로젝트 개요 + 작업 라우팅 테이블 | 에이전트가 규칙에 따라 자동 로드 |
| Domain Router | 각 하위 디렉터리 CLAUDE.md(×18) | 도메인 지식 + 파일 역할 + 하위 도메인 라우팅 | 필요 시 로드 |
| Cookbook | Docs/Cookbook/*.md | 교차 도메인 작업 단계별 체크리스트 | 필요 시 로드 |
| Memory | /memories/session/ 등 | 작업 기억 + 지속적 경험 | 에이전트 자체 관리 |
이 체계의 핵심 철학은 AI 에이전트를 입사 교육이 필요한 새 동료로 대우하라는 것입니다. Constitution은 회사 규정집, Root CLAUDE.md는 조직도, Domain CLAUDE.md는 부서 가이드, Cookbook은 표준 운영 절차(SOP), Memory는 개인 노트입니다.
이러한 계층들이 잘 조화를 이루면 AI 에이전트는 거의 인간의 개입 없이도 안전하고 정확하게 복잡한 교차 도메인 코드 수정을 수행할 수 있습니다.