# 3문서 스키마 규약

> 아누 가이드 시스템의 공식 3문서(계획서/맥락노트/체크리스트) 스키마 규약서.
> 모든 프로젝트는 이 규약을 따라야 한다.

**문서 버전**: v2.0
**작성일**: 2026-04-16
**작성자**: 2팀 (오딘)
**근거**: 계획서 task-43.0 Phase 1-A, 아누 가이드 v1.1 Section 2

---

## 1. YAML 프론트매터 공통 규약

모든 3문서는 파일 최상단에 다음 YAML 프론트매터를 포함해야 한다.

```yaml
---
task_id: task-XX.X
type: plan | context | checklist
scope: system | task
project: (프로젝트 ID 또는 null)
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: draft | approved | in-progress | done
---
```

### 1.1 필드 정의

| 필드 | 필수 | 설명 |
|------|------|------|
| `task_id` | 필수 | 작업 식별자. 형식: `task-숫자.서브숫자` (예: `task-43.0`, `task-12.3`) |
| `type` | 필수 | 문서 유형. 허용값: `plan`, `context`, `checklist` |
| `scope` | 필수 | 문서 범위. 허용값: `system`(전체 시스템/프로세스), `task`(개별 작업) |
| `project` | 필수 | 프로젝트 식별자(kebab-case) 또는 `null` |
| `created` | 필수 | 최초 생성일. 형식: `YYYY-MM-DD` |
| `updated` | 필수 | 최종 수정일. 형식: `YYYY-MM-DD` |
| `status` | 필수 | 현재 상태. 허용값 아래 참조 |

### 1.2 status 허용값

| 값 | 의미 |
|----|------|
| `draft` | 작성 중. 아직 검토 전. |
| `approved` | 제이회장님 승인 완료. 구현 준비 완료. |
| `in-progress` | 구현 진행 중. |
| `done` | 완료. 검증까지 통과. |

### 1.3 스키마 검증 규칙

**필수 규칙 (위반 시 3문서로 인정하지 않음):**

1. `task_id` — 비어있으면 안 됨. `task-` 접두사 필수.
2. `type` — `plan`, `context`, `checklist` 세 값만 허용. 오타 금지.
3. `scope` — `system`, `task` 두 값만 허용. 오타 금지. 미기재 시 경고.
4. `created`, `updated` — ISO 8601 날짜 형식(`YYYY-MM-DD`) 준수.
5. `status` — 허용값 외 사용 금지.
6. `updated` — 문서 수정 시 반드시 갱신해야 함. `created`보다 이전 날짜 불가.

**권고 규칙:**

- 같은 프로젝트의 3문서는 동일한 `task_id`와 `project`를 공유해야 함.
- `status: approved`가 되기 전에는 코딩을 시작하면 안 됨.

### 1.4 scope별 필수/선택 필드 매트릭스

| 필드 | system | task |
|------|--------|------|
| `task_id` | 필수 | 필수 |
| `type` | 필수 | 필수 |
| `scope` | 필수 | 필수 |
| `project` | 필수 | 선택 (null 허용) |
| `created` | 필수 | 필수 |
| `updated` | 필수 | 필수 |
| `status` | 필수 | 필수 |
| `archived_at` | 해당없음 | 아카이브 시 자동 추가 |

---

## 2. 계획서 (plan) 구조

**파일명**: `plan.md`
**type**: `plan`

계획서는 "뭘 만들 건지 처음부터 끝까지" 담는 건축 설계도다.
**계획이 왕. 계획서의 모든 결정은 근거(코드 위치, 문서, 테스트 결과)를 인용해야 한다.
근거 없는 판단 = 환각.**

### 2.1 필수 섹션

```markdown
# 계획서: [프로젝트명]

**task**: [task_id]
**목표**: [한 줄 요약]
**승인**: [승인자] [날짜] "[승인 발언]"
**근거**: [미팅 결과 파일 경로 또는 근거 문서]

---

## 목표

[달성하려는 구체적인 결과물. 측정 가능한 형태로 기술.]

## 범위

### [페이즈/항목 1]
[포함되는 것]

### 제외 (다음 페이즈 이후)
[명시적으로 제외되는 것. 범위 크리프 방지.]

## 위임 계획

[어떤 팀/담당자가 어느 부분을 맡는지]
- [페이즈/항목]: **[팀명]** — [이유]

## 검증 기준

[구현이 완료되었음을 어떻게 확인할 것인지. 구체적인 명령어/테스트 방법 포함.]
- [항목]: `[확인 명령어]` → [기대 결과]
```

### 2.2 작성 원칙

- 목표는 측정 가능해야 한다. "개선한다" 대신 "응답시간 200ms 이하로 줄인다".
- 범위에는 포함 항목뿐 아니라 **제외 항목도 명시**해야 한다.
- 위임 계획에는 팀 배정 이유를 기술해야 한다.
- 검증 기준은 실제로 실행 가능한 명령어 형태로 작성해야 한다.

---

## 3. 맥락노트 (context) 구조

**파일명**: `context-notes.md`
**type**: `context`

맥락노트는 "왜 이렇게 결정했는지, 자료 위치"를 담는 건축 시방서다.

### 3.1 필수 섹션

```markdown
# 맥락 노트: [프로젝트명]

**task**: [task_id]

---

## 결정 근거

### [핵심 결정 1]
- [이 결정을 내린 이유. 어떤 분석/미팅/데이터 기반인지.]
- [대안으로 고려했던 것과 기각 이유.]

### [핵심 결정 2]
[...]

## 참조 자료

- [자료명]: `[파일 경로 또는 URL]`
- [자료명]: `[파일 경로 또는 URL]`

## 주의사항

- [구현 시 반드시 알아야 할 위험/제약/경고]
- [엣지 케이스, 외부 의존성, 알려진 문제]
```

### 3.2 작성 원칙

- 결정 근거는 "그냥 좋아 보여서"가 아닌 분석 기반으로 작성해야 한다.
- 검토한 대안과 기각 사유를 반드시 기술해야 한다. 대안 없는 결정 기록 = 사고하지 않은 기록.
- 참조 자료는 실제로 접근 가능한 경로로 작성해야 한다.
- 주의사항은 미래의 구현자(또는 새 세션의 AI)를 위한 경고다. 중요한 것을 빠뜨리지 말 것.

---

## 4. 체크리스트 (checklist) 구조

**파일명**: `checklist.md`
**type**: `checklist`

체크리스트는 "뭘 끝냈고 뭐가 남았는지"를 담는 건축 공정표다.

### 4.1 필수 섹션

```markdown
# 체크리스트: [프로젝트명]

**task**: [task_id]

---

## [단계/페이즈 1] — [담당팀]

- [ ] A. [작업 항목]
- [ ] B. [작업 항목]
- [x] C. [완료된 항목]

## [단계/페이즈 2] — [담당팀]

- [ ] A. [작업 항목]
- [ ] B. [작업 항목]

## 검증

- [ ] [검증 항목 1]
- [ ] [검증 항목 2]
- [ ] 제이회장님 최종 보고
```

### 4.2 작성 원칙

- 체크박스는 `[ ]` (미완료) / `[x]` (완료) 두 가지만 사용한다.
- 단계별로 섹션을 구분하고 담당팀을 명시해야 한다.
- 마지막 섹션은 반드시 "검증" 섹션을 포함해야 한다.
- 체크리스트 항목은 완료/미완료를 명확히 판단할 수 있어야 한다 (모호한 항목 금지).
- 완료 시 `updated` 날짜를 갱신하고 `status`를 `done`으로 변경해야 한다.

---

## 5. 파일 저장 경로 규약

### 5.1 표준 경로

#### 5.1.1 시스템 3문서 경로

```
memory/plans/<프로젝트명>/plan.md
memory/plans/<프로젝트명>/context-notes.md
memory/plans/<프로젝트명>/checklist.md
```

#### 5.1.2 작업 3문서 경로

```
memory/plans/tasks/{task_id}/plan.md
memory/plans/tasks/{task_id}/context-notes.md
memory/plans/tasks/{task_id}/checklist.md
```

### 5.2 프로젝트명 규칙

- **kebab-case** 사용 필수. (소문자, 단어 구분은 하이픈)
- 영문 사용 권장. 한글 사용 시 영문 음역 또는 번역.
- 예시:
  - `anu-guide-system`
  - `dispatch-security-patch`
  - `hooks-infrastructure`

### 5.3 예시 경로

```
memory/plans/anu-guide-system/plan.md
memory/plans/anu-guide-system/context-notes.md
memory/plans/anu-guide-system/checklist.md
```

### 5.4 아카이브 규약

작업 3문서(`scope: task`)는 작업 완료 후 아카이브한다.

1. **이동 경로**: `memory/plans/tasks/{task_id}/` → `memory/plans/tasks/archived/{task_id}/`
2. **이동 시점**: 작업 완료(.done 파일 생성) 후 자동 이동
3. **archived_at 필드**: 이동 시 YAML frontmatter에 `archived_at: YYYY-MM-DD` 자동 추가
4. **보존 기간**: 90일 (90일 경과 후 삭제 가능)
5. **수동 이동 금지**: 자동화 스크립트로만 처리 (일관성 보장)
6. **시스템 3문서는 아카이브 대상이 아님** (`scope: system`은 장기 참조 문서)

---

## 6. 실제 사용 예시 (task-43.0 기준)

현재 진행 중인 아누 가이드 시스템 구축 프로젝트(task-43.0)를 참조.

### 6.1 계획서 예시

파일: `/home/jay/workspace/memory/plans/anu-guide-system/plan.md`

```yaml
---
task_id: task-43.0
type: plan
project: anu-guide-system
created: 2026-03-02
updated: 2026-03-02
status: approved
---
```

주요 특징:
- 목표가 "즉시조치 ~ Phase 1"로 범위 명확히 한정.
- 범위에 "제외(Phase 2 이후)" 섹션 명시.
- 위임 계획에 팀별 배정 이유 기술 (예: "Phase 1(skills)은 설계 중심 → 오딘에 적합").
- 검증 기준에 실행 가능한 명령어 포함 (예: `grep -r "BOT_KEYS" dispatch.py`).

### 6.2 맥락노트 예시

파일: `/home/jay/workspace/memory/plans/anu-guide-system/context-notes.md`

```yaml
---
task_id: task-43.0
type: context
project: anu-guide-system
created: 2026-03-02
updated: 2026-03-02
status: approved
---
```

주요 특징:
- 결정마다 "왜"를 기술 (예: "Agent 미팅 6명 전원 동의: hooks가 모든 자동화의 뿌리").
- 구체적 위험 기술 (예: "로키 발견: dispatch.py 34-39행에 BOT_KEYS 평문 하드코딩").
- 주의사항에 미래 구현자를 위한 경고 포함.

### 6.3 체크리스트 예시

파일: `/home/jay/workspace/memory/plans/anu-guide-system/checklist.md`

```yaml
---
task_id: task-43.0
type: checklist
project: anu-guide-system
created: 2026-03-02
updated: 2026-03-02
status: in-progress
---
```

주요 특징:
- 단계별 섹션 구분 (즉시조치 / Phase 0 / Phase 1 / 검증).
- 각 섹션에 담당팀 명시 (예: `→ 1팀`, `→ 2팀`).
- 마지막 검증 섹션에 "제이회장님 최종 보고" 포함.

---

## 7. 핵미사일 발사코드와의 연계

3문서는 `/nuclear-approval` 실행의 전제 조건이다.

```
3문서 없음 → nuclear-approval 즉시 중단
3문서 있음 + YAML 유효 + 근거 확인 → 승인 요청 진행
```

**nuclear-approval이 검증하는 항목:**
1. 3문서 파일 경로 존재 여부
2. YAML 프론트매터의 `task_id`, `type`, `status` 필드 유효성
3. 계획서 내 모든 결정에 근거(코드 위치, 문서, 테스트 결과) 인용 여부

---

## 8. 검증 게이트 규칙

> `scope: task` 3문서의 `.done` 허용 조건. 이 게이트를 통과해야만 작업 완료(.done) 처리가 가능하다.

### 8.1 .done 허용 조건 (5개)

| # | 조건 | 검증 방법 |
|---|------|-----------|
| 1 | 3문서 디렉토리 존재 | `memory/plans/tasks/{task_id}/` 디렉토리 존재 확인 |
| 2 | 계획서 status ≠ draft | `plan.md`의 YAML `status` 필드가 `draft`가 아닌지 확인 |
| 3 | 맥락노트 기록 존재 | `context-notes.md`에 "## 결정 근거" 섹션이 비어있지 않은지 확인 |
| 4 | 체크리스트 전 항목 완료 | `checklist.md`의 모든 `- [ ]` 항목이 `- [x]`로 변환되었는지 확인 |
| 5 | YAML 유효성 | 3문서 모두 YAML 프론트매터가 유효하고 필수 필드(`task_id`, `type`, `scope`, `status`)가 존재하는지 확인 |

### 8.2 검증 주체

- **검증기**: `three_docs_check` verifier
- **실행 시점**: `.done` 파일 생성 직전
- **실패 시**: .done 생성 차단 + 실패 사유 반환

### 8.3 레벨별 적용

- **Lv.2 이하**: 검증 게이트 **SKIP** (3문서 없이도 .done 허용)
- **Lv.3 이상**: 검증 게이트 **필수** (5개 조건 전부 통과해야 .done 허용)

---

## 관련 파일

- 아누 가이드: `memory/specs/anu-guide.md`
- 핵미사일 승인 스킬: `.claude/skills/nuclear-approval.md`
- 3문서 생성 스킬: `.claude/skills/3docs-create.md`
- 실제 예시 경로: `memory/plans/anu-guide-system/`