# 3문서 사용 가이드

> 3문서 2유형 체계를 실무에서 활용하기 위한 팀장/팀원용 안내서.

**문서 버전**: v1.0
**작성일**: 2026-04-16
**작성자**: 개발6팀 라다
**관련 문서**: `memory/specs/3docs-schema.md`

---

## 1. 3문서란?

3문서는 Lv.3 이상 작업에서 계획, 맥락, 진행 상태를 체계적으로 관리하기 위한 세 개의 마크다운 파일 세트다.

| 파일 | 유형 | 역할 | 비유 |
|------|------|------|------|
| `plan.md` | 계획서 | 무엇을 만들 것인지, 목표/범위/검증 기준 | 건축 설계도 |
| `context-notes.md` | 맥락 노트 | 왜 그렇게 결정했는지, 자료 위치, 주의사항 | 건축 시방서 |
| `checklist.md` | 체크리스트 | 무엇을 끝냈고 무엇이 남았는지 | 건축 공정표 |

세 파일은 항상 함께 존재해야 한다. 하나라도 빠지면 3문서로 인정하지 않는다.

---

## 2. 2유형: 시스템 3문서 vs 작업 3문서

3문서에는 두 가지 유형(scope)이 있다.

### 시스템 3문서 (scope: system)

- **대상**: 프로젝트 또는 프로세스 레벨의 장기 작업
- **저장 경로**: `memory/plans/{project}/`
  - 예: `memory/plans/cross-verification-workflow/`
- **특징**: 작업 완료 후에도 아카이브하지 않음. 장기 참조 문서로 유지.

### 작업 3문서 (scope: task)

- **대상**: 개별 작업 단위 (dispatch.py가 자동 생성)
- **저장 경로**: `memory/plans/tasks/{task_id}/`
  - 예: `memory/plans/tasks/task-1872_6.6/`
- **특징**: 작업 완료 후 아카이브 대상. 90일 보존 후 삭제 가능.
- **아카이브 경로**: `memory/plans/tasks/archived/{task_id}/`

### 두 유형의 차이점 요약

| 항목 | 시스템 3문서 | 작업 3문서 |
|------|-------------|-----------|
| scope 값 | `system` | `task` |
| 경로 | `memory/plans/{project}/` | `memory/plans/tasks/{task_id}/` |
| 생성 방식 | 수동 생성 | dispatch.py 자동 생성 |
| 완료 후 처리 | 유지 (장기 참조) | 아카이브 (90일 보존) |

---

## 3. 자동 생성 조건

작업 3문서는 dispatch.py가 자동으로 생성한다.

- **생성 조건**: 작업 레벨이 Lv.3 이상 (critical/security)일 때만 생성
- **담당 함수**: `dispatch.py`의 `_create_task_docs(task_id, level)`
- **판단 로직**: `level >= 3`이면 3문서 생성, `level < 3`이면 미생성

```
Lv.1 (low)      → 3문서 미생성
Lv.2 (medium)   → 3문서 미생성
Lv.3 (critical) → 3문서 자동 생성
Lv.4 (security) → 3문서 자동 생성
```

Lv.2 이하 작업에서는 3문서가 존재하지 않는 것이 정상이다.

---

## 4. 팀장 의무

Lv.3 이상 작업에서 팀장은 다음 의무를 이행해야 한다.

1. **작업 시작 시**: `plan.md`의 목표와 범위를 확인하고 팀원에게 공유한다.
2. **주요 결정 시**: `context-notes.md`에 결정 근거를 기록한다. "그냥 좋아 보여서"는 기록으로 인정하지 않는다.
3. **각 단계 완료 시**: `checklist.md`에서 해당 항목을 `[ ]`에서 `[x]`로 체크한다.
4. **작업 완료 시**: 3문서를 최종 업데이트한다.
   - YAML frontmatter의 `updated` 날짜 갱신
   - `status`를 `draft` 또는 `in-progress`에서 `done`으로 변경

---

## 5. QC 검증

`three_docs_check.py` verifier가 3문서의 유효성을 자동 검증한다.

### 검증 항목

| 항목 | 설명 |
|------|------|
| 파일 존재 | plan.md, context-notes.md, checklist.md 세 파일 모두 존재하는지 확인 |
| YAML frontmatter 필수 필드 | task_id, type, scope, created, updated, status 모두 포함 여부 확인 |
| plan.md status | 적절한 status 값인지 확인 |
| 플레이스홀더 미치환 | `[TODO]`, `[작업명]` 등 미치환 플레이스홀더 잔존 여부 확인 |
| checklist 완료율 | 전체 체크박스 중 완료(`[x]`) 비율이 50% 이상인지 확인 |

### 판정 결과

| 결과 | 의미 |
|------|------|
| `PASS` | 검증 통과. 문제 없음. |
| `WARN` | 경고. 즉시 수정 권고. |
| `FAIL` | 검증 실패. 작업 진행 불가. |
| `SKIP` | 해당 없음 (Lv.2 이하 등 3문서 미적용 대상). |

---

## 6. 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
---
```

### 필수 필드

| 필드 | 허용값 | 설명 |
|------|--------|------|
| `task_id` | `task-숫자.서브숫자` | 작업 식별자. `task-` 접두사 필수. |
| `type` | `plan`, `context`, `checklist` | 문서 유형. 정확히 이 세 값만 허용. |
| `scope` | `system`, `task` | 문서 범위. |
| `created` | `YYYY-MM-DD` | 최초 생성일. |
| `updated` | `YYYY-MM-DD` | 최종 수정일. 수정 시 반드시 갱신. |
| `status` | `draft`, `approved`, `in-progress`, `done` | 현재 상태. |

스키마 상세 규칙은 `memory/specs/3docs-schema.md` 참조.

---

## 7. 경로 규약

### 시스템 3문서 경로

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

예시:
```
memory/plans/cross-verification-workflow/plan.md
memory/plans/cross-verification-workflow/context-notes.md
memory/plans/cross-verification-workflow/checklist.md
```

### 작업 3문서 경로

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

예시:
```
memory/plans/tasks/task-1872_6.6/plan.md
memory/plans/tasks/task-1872_6.6/context-notes.md
memory/plans/tasks/task-1872_6.6/checklist.md
```

### 아카이브 경로

작업 3문서 완료 후 자동 이동 경로:

```
memory/plans/tasks/archived/{task_id}/
```

아카이브는 자동화 스크립트로만 처리한다. 수동 이동 금지.

---

## 8. 워크플로우 내 3문서 단계

3문서는 워크플로우의 세 시점에서 처리된다.

| 단계 | 내용 | 적용 조건 |
|------|------|-----------|
| Step 1.2 | 3문서 확인 — 작업 시작 전 plan.md 목표/범위 확인 | Lv.3 이상 |
| Step 5.2 | 3문서 업데이트 — 작업 완료 후 updated, status 갱신, checklist 체크 | Lv.3 이상 |
| Step 5.3 | 3문서 검증 강제 — `three_docs_check.py` 실행, FAIL이면 작업 완료 처리 불가 | Lv.3 이상 |

Lv.2 이하 작업은 이 세 단계를 모두 건너뛴다 (SKIP 처리).

---

## 관련 파일

- 스키마 규약: `memory/specs/3docs-schema.md`
- 아누 가이드: `memory/specs/anu-guide.md`
- 3문서 생성 스킬: `.claude/skills/3docs-create.md`
- QC 검증기: `three_docs_check.py`
- 작업 레벨 기준: `memory/specs/work-level-system.md`