name: dev-doc-system
description: 개발 문서 통합 관리 시스템. 개발 방향, 진행 상황, 계획, 변경 사항, 피드백을 체계적으로 기록하고 관리. "문서 시스템", "개발 기록", "방향 설정", "회고", "변경 이력" 키워드에 반응.

Dev Doc System - 개발 문서 통합 관리 시스템

프로젝트의 개발 방향성, 진행 상황, 변경 사항, 피드백을 체계적으로 기록하고 일관성을 유지하는 통합 문서 관리 시스템입니다.

핵심 가치

• 일관성: 개발 방향과 결정 사항을 기록하여 방향성 유지
• 추적성: 모든 변경과 결정의 이유를 기록하여 맥락 보존
• 투명성: 현재 상황과 계획을 명확히 공유
• 학습: 문제와 피드백을 기록하여 반복 실수 방지

문서 구조

docs/
├── direction/           # 개발 방향 (왜, 무엇을)
│   ├── VISION.md        # 프로젝트 비전 및 목표
│   ├── ROADMAP.md       # 개발 로드맵
│   └── DECISIONS.md     # 주요 결정 사항 기록 (ADR)
│
├── status/              # 현재 상황 (지금 무엇을)
│   ├── CURRENT.md       # 현재 진행 중인 작업
│   └── CHANGELOG.md     # 변경 이력
│
├── planning/            # 앞으로의 계획 (다음에 무엇을)
│   ├── BACKLOG.md       # 백로그 및 우선순위
│   └── NEXT-SPRINT.md   # 다음 스프린트/마일스톤
│
├── changes/             # 중간 변경 사항 (무엇이 바뀌었나)
│   ├── SCOPE-CHANGES.md # 스코프 변경 기록
│   └── PIVOT-LOG.md     # 방향 전환 기록
│
├── feedback/            # 문제 및 피드백 (무엇을 배웠나)
│   ├── ISSUES.md        # 이슈 및 블로커 기록
│   ├── RETRO.md         # 스프린트/마일스톤 회고
│   └── LEARNINGS.md     # 교훈 및 베스트 프랙티스
│
├── prd/                 # PRD 문서 (기존)
├── tech-specs/          # 기술 설계서 (기존)
├── progress/            # 진행상황 체크 (기존)
│
└── README.md            # 문서 인덱스 + 프로젝트 상태 헤더

문서 유형별 가이드

1. Direction (개발 방향)

VISION.md - 프로젝트 비전

# 프로젝트 비전

## 미션
{한 문장으로 프로젝트의 존재 이유}

## 핵심 가치
1. {가치 1}: {설명}
2. {가치 2}: {설명}
3. {가치 3}: {설명}

## 성공 지표 (KPI)
| 지표 | 목표 | 현재 | 상태 |
|------|------|------|------|
| {지표 1} | {목표값} | {현재값} | 🔄 |

## 비전 변경 이력
| 날짜 | 변경 내용 | 이유 |
|------|----------|------|

ROADMAP.md - 개발 로드맵

# 개발 로드맵

## 현재 Phase: {Phase N} - {Phase 이름}

### Phase 1: {이름} ✅
- 기간: YYYY-MM-DD ~ YYYY-MM-DD
- 목표: {목표}
- 결과: {결과 요약}

### Phase 2: {이름} 🔄
- 기간: YYYY-MM-DD ~ YYYY-MM-DD
- 목표: {목표}
- 진행률: `████████░░░░░░░░░░░░` 40%

### Phase 3: {이름} ⏳
- 기간: YYYY-MM-DD ~ (예정)
- 목표: {목표}
- 의존성: Phase 2 완료 필요

DECISIONS.md - 아키텍처 결정 기록 (ADR)

# 아키텍처 결정 기록 (ADR)

## ADR-001: {결정 제목}
- **날짜**: YYYY-MM-DD
- **상태**: 승인됨 | 대체됨 | 폐기됨
- **결정자**: {이름}

### 맥락
{이 결정이 필요한 배경}

### 결정
{내린 결정}

### 대안
1. {대안 1}: {장단점}
2. {대안 2}: {장단점}

### 결과
{예상되는 결과 및 영향}

### 변경 이력
| 날짜 | 변경 | 이유 |
|------|------|------|

2. Status (현재 상황)

CURRENT.md - 현재 진행 작업

# 현재 진행 상황

**마지막 업데이트**: YYYY-MM-DD HH:MM

## 이번 주 목표
- [ ] {목표 1}
- [ ] {목표 2}

## 진행 중인 작업
| 작업 | 담당 | 시작일 | 상태 | 블로커 |
|------|------|--------|------|--------|
| {작업} | {담당} | {날짜} | 🔄 | {없음/있음} |

## 완료된 작업 (이번 주)
| 작업 | 담당 | 완료일 |
|------|------|--------|
| {작업} | {담당} | {날짜} |

## 블로커/이슈
| 이슈 | 영향 | 해결책 | 상태 |
|------|------|--------|------|
| {이슈} | {영향} | {해결책} | 🔴 |

CHANGELOG.md - 변경 이력

# 변경 이력

모든 주요 변경 사항을 기록합니다.

## [Unreleased]

### Added
- {새로 추가된 기능}

### Changed
- {변경된 기능}

### Fixed
- {수정된 버그}

### Removed
- {제거된 기능}

## [1.0.0] - YYYY-MM-DD
...

3. Planning (앞으로의 계획)

BACKLOG.md - 백로그

# 백로그

## 우선순위 정의
- **P0**: 크리티컬 - 즉시 처리
- **P1**: 높음 - 이번 스프린트
- **P2**: 중간 - 다음 스프린트
- **P3**: 낮음 - 백로그

## 백로그 항목

### P0 - 크리티컬
| ID | 항목 | 예상 공수 | 의존성 |
|----|------|----------|--------|
| BL-001 | {항목} | {공수} | {의존성} |

### P1 - 높음
...

### P2 - 중간
...

### P3 - 낮음
...

### Ice Box (보류)
| ID | 항목 | 보류 이유 |
|----|------|----------|

NEXT-SPRINT.md - 다음 스프린트

# 다음 스프린트 계획

## 스프린트 정보
- **스프린트**: #{번호}
- **기간**: YYYY-MM-DD ~ YYYY-MM-DD
- **목표**: {스프린트 목표}

## 스프린트 범위
| 항목 | 우선순위 | 예상 공수 | 담당 |
|------|----------|----------|------|
| {항목} | P1 | {공수} | {담당} |

## 리스크
| 리스크 | 확률 | 영향 | 대응책 |
|--------|------|------|--------|

## 성공 기준
- [ ] {기준 1}
- [ ] {기준 2}

4. Changes (중간 변경 사항)

SCOPE-CHANGES.md - 스코프 변경

# 스코프 변경 기록

## SC-001: {변경 제목}
- **날짜**: YYYY-MM-DD
- **요청자**: {이름}
- **유형**: 추가 | 제거 | 수정

### 원래 스코프
{변경 전 내용}

### 변경된 스코프
{변경 후 내용}

### 변경 이유
{왜 변경이 필요한가}

### 영향 분석
- **일정**: {영향}
- **비용**: {영향}
- **품질**: {영향}
- **리스크**: {영향}

### 승인
- [ ] PM 승인
- [ ] 기술 리드 승인
- [ ] 이해관계자 승인

PIVOT-LOG.md - 방향 전환 기록

# 방향 전환 기록

## PV-001: {전환 제목}
- **날짜**: YYYY-MM-DD
- **전환 유형**: 기술 | 제품 | 비즈니스

### 이전 방향
{이전 접근 방식}

### 새 방향
{새로운 접근 방식}

### 전환 이유
{데이터, 피드백, 학습 등}

### 폐기되는 것
- {폐기 항목 1}
- {폐기 항목 2}

### 새로 필요한 것
- {신규 항목 1}
- {신규 항목 2}

### 교훈
{이 전환에서 배운 것}

5. Feedback (문제 및 피드백)

ISSUES.md - 이슈 기록

# 이슈 기록

## 활성 이슈

### ISS-001: {이슈 제목} 🔴
- **발견일**: YYYY-MM-DD
- **심각도**: 크리티컬 | 높음 | 중간 | 낮음
- **영향**: {영향 범위}

#### 증상
{어떻게 발견되었나}

#### 근본 원인
{왜 발생했나}

#### 해결 방안
1. {방안 1}
2. {방안 2}

#### 진행 상황
- [ ] 원인 분석
- [ ] 해결책 구현
- [ ] 테스트
- [ ] 배포

---

## 해결된 이슈

### ISS-000: {이슈 제목} ✅
- **발견일**: YYYY-MM-DD
- **해결일**: YYYY-MM-DD
- **해결 방법**: {요약}
- **교훈**: {배운 점}

RETRO.md - 회고

# 스프린트/마일스톤 회고

## 회고: {Phase/Sprint} #{번호}
- **날짜**: YYYY-MM-DD
- **참여자**: {참여자 목록}

### 잘한 것 (Keep)
- {항목 1}
- {항목 2}

### 개선할 것 (Problem)
- {항목 1}
- {항목 2}

### 시도할 것 (Try)
- {항목 1}
- {항목 2}

### 액션 아이템
| 액션 | 담당 | 기한 | 상태 |
|------|------|------|------|
| {액션} | {담당} | {기한} | ⏳ |

### 핵심 교훈
> {이번 회고의 가장 중요한 교훈 한 줄}

LEARNINGS.md - 교훈 및 베스트 프랙티스

# 교훈 및 베스트 프랙티스

## 기술적 교훈

### LRN-001: {교훈 제목}
- **날짜**: YYYY-MM-DD
- **카테고리**: 아키텍처 | 코드 | 테스트 | 배포 | 기타

#### 상황
{어떤 상황에서 배웠나}

#### 교훈
{무엇을 배웠나}

#### 적용 방법
{앞으로 어떻게 적용할 것인가}

---

## 프로세스 교훈

### LRN-002: {교훈 제목}
...

---

## 커뮤니케이션 교훈

### LRN-003: {교훈 제목}
...

도구 조합 (Tool Combinations)

워크플로우별 도구 매핑

Hook 통합

# .claude/hooks/doc-update.sh
# 커밋 후 자동 문서 업데이트 트리거

on_commit:
  - update: status/CURRENT.md
  - update: status/CHANGELOG.md

on_milestone:
  - create: feedback/RETRO.md
  - update: direction/ROADMAP.md

on_scope_change:
  - create: changes/SCOPE-CHANGES.md entry
  - update: planning/BACKLOG.md

명령어

초기화

# 전체 문서 구조 초기화
/dev-doc-system init

# 특정 카테고리만 초기화
/dev-doc-system init --category direction

문서 생성/업데이트

# 비전 문서 작성
/dev-doc-system vision "프로젝트 설명"

# 로드맵 업데이트
/dev-doc-system roadmap --phase 2 --status 40%

# 결정 기록 추가
/dev-doc-system decision "결정 제목"

# 현재 상황 업데이트
/dev-doc-system current

# 스코프 변경 기록
/dev-doc-system scope-change "변경 제목"

# 회고 생성
/dev-doc-system retro --sprint 3

# 교훈 기록
/dev-doc-system learning "교훈 제목"

문서 조회

# 문서 상태 요약
/dev-doc-system status

# 특정 문서 조회
/dev-doc-system show direction/ROADMAP.md

자동화 워크플로우

1. 일일 업데이트

매일 아침:
1. status/CURRENT.md 자동 갱신 (git log 기반)
2. feedback/ISSUES.md 활성 이슈 체크
3. planning/NEXT-SPRINT.md 진행률 업데이트

2. 주간 정리

매주 금요일:
1. status/CHANGELOG.md 주간 변경사항 정리
2. direction/ROADMAP.md 진행률 업데이트
3. planning/BACKLOG.md 우선순위 재검토

3. 마일스톤 완료

마일스톤 완료 시:
1. feedback/RETRO.md 회고 문서 생성
2. feedback/LEARNINGS.md 교훈 추가
3. direction/ROADMAP.md Phase 완료 표시
4. docs/README.md 헤더 업데이트

Best Practices

DO

• ✅ 결정할 때마다 DECISIONS.md에 기록
• ✅ 스코프 변경 시 SCOPE-CHANGES.md에 기록
• ✅ 문제 해결 후 LEARNINGS.md에 교훈 기록
• ✅ 마일스톤마다 RETRO.md 작성
• ✅ 문서 간 상호 참조 링크 유지

DON'T

• ❌ 결정 이유 없이 변경
• ❌ 스코프 변경을 기록 없이 진행
• ❌ 같은 실수 반복 (LEARNINGS.md 참조)
• ❌ 회고 없이 다음 단계 진행
• ❌ 문서 업데이트 미루기

관련 도구

참조 문서

• references/document-templates.md - 모든 템플릿
• references/workflow-diagrams.md - 워크플로우 다이어그램
• references/integration-guide.md - 도구 통합 가이드