Project Docs Setup

Project Documentation System Setup

프로젝트 문서를 사람과 AI 에이전트가 각자 필요한 정보를 빠르게 찾을 수 있도록 4개 파일로 분리하는 체계입니다.

왜 이 구조인가

AGENTS.md는 짧고 핵심만 담아야 한다. 깊이 있는 내용은 ai-context/ 파일에 위임하고 TOC.md로 색인한다.

Step 1: 프로젝트 탐색

파일을 쓰기 전에 프로젝트를 이해한다. 병렬로 읽어라.

읽어야 할 것들:

• 빌드 설정: settings.gradle.kts, package.json, pyproject.toml, build.gradle.kts 등
• 기존 문서: README.md, AGENTS.md, ai-context/TOC.md, docs/TOC.md
• 루트 디렉터리 구조 (ls 또는 Glob)
• 핵심 모듈 디렉터리 목록

파악해야 할 것:

• 프로젝트명, 기술 스택, 언어/프레임워크
• 모듈 목록과 각각의 책임
• 기존 아키텍처 다이어그램
• 기존 규칙, 제약사항, 금지 패턴
• Claude memory나 CLAUDE.md에 있는 프로젝트별 메모

Step 2: README.md 작성

사람이 처음 저장소에 들어왔을 때 빠르게 파악할 수 있도록. 간결하게.

필수 섹션:

# {프로젝트명}

{한 줄 설명 — 무엇이고 왜 존재하는가}

## 기능

- `{모듈명}` — {한 줄 설명}
- ...

## 아키텍처 트리

\`\`\`text
{프로젝트 루트}
├── {모듈1}
├── {모듈2}
└── ...
\`\`\`

## 아키텍처 흐름

\`\`\`mermaid
flowchart LR
    {노드1}["{한글 레이블}"] --> {노드2}["{한글 레이블}"]
    ...
\`\`\`

## 빠른 시작   ← 있으면 추가

## 문서   ← 있으면 추가

Mermaid 다이어그램 규칙:

• flowchart LR (좌→우) 사용, 노드 5~8개 이하로 단순하게
• 레이블은 한글로, 의존 방향(→)이 명확하게
• 복잡한 다이어그램은 ai-context/02_architecture-principles.md에 위임

Step 3: AGENTS.md 작성

AI 에이전트용. 핵심 규칙과 제약만 담고, 상세는 ai-context/로 위임.

필수 섹션:

# AGENTS.md

이 문서는 {프로젝트명} 에이전트용 루트 가이드입니다.
상세 기준은 항상 [ai-context/TOC.md](./ai-context/TOC.md)부터 읽습니다.

## 프로젝트 개요와 목적

- {한 줄 설명}
- {중요한 맥락 — 마이그레이션 중이라면 "X에서 Y로", 소유권 경계가 있다면 명시}

## 기능

- `{모듈명}` — {한 줄 설명}
- ...

## 에이전트 핵심 규칙

- {하면 안 되는 것들 — DDL 변경, 기존 계약 파괴 등}
- {아키텍처 불변 규칙 — 의존 방향, 금지 패턴}
- {마이그레이션/전환 제약}

## 중요한 메모

- {테스트 정책, 커버리지 기준}
- {환경 전제조건}
- {문서 갱신 규칙}

## 먼저 읽을 문서

- [ai-context/TOC.md](./ai-context/TOC.md)
- {기타 중요 상태 문서}

AGENTS.md가 60줄을 넘어가면 내용을 ai-context/ 파일로 옮겨라.

Step 4: CLAUDE.md 작성

딱 한 줄만:

@AGENTS.md

다른 내용 없음. Claude Code의 @파일 임포트 문법으로 AGENTS.md를 자동 로드하게 한다.

Step 5: ai-context/ 설정

TOC.md 작성/갱신

ai-context/의 첫 번째 규칙: 다른 파일을 보기 전에 항상 TOC.md를 먼저 읽는다.

# TOC

이 디렉터리는 {프로젝트명} 에이전트 상세 문서 전용 공간입니다.
다른 문서를 보기 전에 항상 이 목차부터 읽습니다.

## 읽는 순서

1. [01_north-star.md](./01_north-star.md) — 프로젝트 방향성과 핵심 원칙
2. [02_architecture-principles.md](./02_architecture-principles.md) — 아키텍처 원칙과 의존 규칙
...

## 보조 문서

- [docs/...] — 상태 문서, 체크리스트 등

신규 프로젝트라면 스타터 파일 생성

• 01_north-star.md — 프로젝트가 무엇이고 무엇이 아닌지, 성공 기준
• 02_architecture-principles.md — 모듈 경계, 의존 방향 규칙, 금지 패턴

파일 네이밍: {두 자리 번호}_{kebab-title}.md (예: 03_decision-checklist.md)

Step 6: 일관성 검증

모든 파일을 쓴 후 확인:

• 프로젝트명, 모듈 목록, 기술 스택이 README.md와 AGENTS.md에서 일치하는가
• AGENTS.md와 TOC.md의 모든 링크가 실제 파일을 가리키는가
• CLAUDE.md가 @AGENTS.md 한 줄인가
• ai-context/TOC.md가 디렉터리에 실제 존재하는 모든 파일을 나열하는가

유지보수 규칙

프로젝트 구조나 정책이 바뀌면:

• README.md, AGENTS.md, ai-context/TOC.md를 함께 갱신
• 세 파일이 서로 어긋나도록 두지 않는다
• ai-context/에 새 파일을 추가하면 즉시 TOC.md에도 추가

언어 규칙

• 한국어 프로젝트 → 한국어로 작성 (기존 파일 언어를 따른다)
• 영어 프로젝트 → 영어로 작성
• Mermaid 노드 레이블은 프로젝트 언어로