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)
워크플로우별 도구 매핑
| 워크플로우 |
문서 |
도구 조합 |
| 프로젝트 시작 |
VISION.md, ROADMAP.md |
prd-writer + dev-doc-system |
| 기능 기획 |
PRD, BACKLOG.md |
prd-writer |
| 기술 설계 |
DECISIONS.md, tech-spec |
tech-spec-writer |
| 개발 진행 |
CURRENT.md, progress |
progress-tracker |
| 스코프 변경 |
SCOPE-CHANGES.md |
dev-doc-system |
| 이슈 발생 |
ISSUES.md |
dev-doc-system + git-troubleshooter |
| 스프린트 완료 |
RETRO.md, CHANGELOG.md |
dev-doc-system + commit-helper |
| 문서 검증 |
전체 |
doc-validator |
| README 업데이트 |
README.md |
skill-manager (update-header) |
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 참조)
- ❌ 회고 없이 다음 단계 진행
- ❌ 문서 업데이트 미루기
관련 도구
| 도구 |
유형 |
용도 |
prd-writer |
Agent |
PRD 작성 |
tech-spec-writer |
Agent |
기술 설계서 작성 |
progress-tracker |
Agent |
진행상황 추적 |
doc-validator |
Agent |
문서 완성도 검증 |
commit-helper |
Agent |
커밋 메시지 및 CHANGELOG |
skill-manager |
Skill |
README 헤더 업데이트 |
dev-doc-planner |
Command |
문서 플래닝 |
git-workflow |
Command |
Git 워크플로우 |
참조 문서
references/document-templates.md - 모든 템플릿references/workflow-diagrams.md - 워크플로우 다이어그램references/integration-guide.md - 도구 통합 가이드
tygwan