project-docs-setup

Files (1)

• SKILL.md

SKILL.md (first lines)

# Project Documentation System Setup

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

## 왜 이 구조인가

| 파일 | 독자 | 목적 |
|------|------|------|
| `README.md` | 사람 (개발자) | 프로젝트 전체 구조를 한눈에 파악 |
| `AGENTS.md` | AI 에이전트 | 이 프로젝트에서 무엇을 해야 하고 하면 안 되는지 |
| `CLAUDE.md` | Claude Code | `@AGENTS.md`만 써서 진입점 단일화 |
| `ai-context/` | AI 에이전트 | AGENTS.md가 위임한 상세 문서 전용 공간 |

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 작성

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

**필수 섹션:**

```markdown
# {프로젝트명}

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

## 기능

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

## 아키텍처 트리

\`\`\`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/로 위임.

**필수 섹션:**

```markdown
# AGENTS.md

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

## 프로젝트 개요와 목적

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

## 기능

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

## 에이전트 핵심 규칙

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

## 중요한 메모

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

## 먼저 읽을 문서

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

From ureca-corp/claude, MIT.

More from ureca-corp/claude