Doc Framework

3. Change Class → 영향 문서 매핑

코드 변경을 분류하고, 각 class에 필수/조건부 갱신 문서를 매핑한다.

이식 프로세스

Step 1: 문서 구조 생성

프로젝트 루트에 아래 구조를 만든다:

docs/
├── status/
│   ├── PROJECT-STATUS.md    ← 현재 상태 (Tier 1)
│   └── DECISION-LOG.md      ← 경계 결정 기록
├── ref/
│   ├── ARCHITECTURE.md      ← 시스템 구조 (Tier 1)
│   ├── SCHEMA.md            ← 데이터 모델
│   └── (도메인별 ref 문서)
└── archive/
    └── decisions-resolved.md ← 해결된 결정 보관

Step 2: PROJECT-STATUS.md 템플릿

# [프로젝트명] Project Status

## Current Phase
- 현재 단계 설명

## Active Tracks
- 기능A: done (YYYY-MM-DD) — 한 줄 설명
- 기능B: in progress
- 기능C: planned

## Execution Checklist
### P0 — Immediate
- [ ] 항목

### P1 — Core
- [ ] 항목

### P2 — Enhancement
- [ ] 항목

규칙:

• done 항목은 반드시 날짜 포함: - 항목: done (YYYY-MM-DD)
• 14일 이상 된 done 항목은 자동 정리 대상
• in progress 항목은 현재 작업만

Step 3: DECISION-LOG.md 템플릿

# Decision Log

## Pending
### DEC-001: [결정 제목]
- **Context**: 왜 이 결정이 필요한가
- **Options**: A vs B vs C
- **Decision**: 선택한 옵션
- **Rationale**: 선택 이유
- **Date**: YYYY-MM-DD

## (해결된 결정은 docs/archive/decisions-resolved.md로 이동)

Step 4: Change Class 매핑 테이블 작성

프로젝트에 맞게 아래 테이블을 커스터마이즈한다:

| 변경 영역 | 필수 갱신 | 조건부 갱신 |
|-----------|----------|-----------|
| 어떤 코드든 | PROJECT-STATUS.md | — |
| UI/화면 | ROUTE-SPECS.md | PRD.md |
| DB/모델 | SCHEMA.md | ARCHITECTURE.md |
| 로직/워커 | ARCHITECTURE.md | — |
| 설정/배포 | — | ARCHITECTURE.md |
| 경계 결정 | DECISION-LOG.md | → resolved 시 archive |

로봇/Unity/ROS 예시:

Step 5: /doc-update 커맨드 생성

.claude/commands/doc-update.md에 아래 프로세스를 등록한다:

# /doc-update

## 프로세스
1. `git diff --name-only` 로 변경 파일 수집
2. Change Class 매핑 테이블로 영향 문서 판별
3. 필수 문서를 실제 수정 (최소 변경, 정본 1곳)
4. DECISION-LOG: pending → resolved 시 archive 이동
5. PROJECT-STATUS: done 항목에 날짜 포함 확인
6. 검증 보고 출력

Step 6: /doc-sync 스킬 생성 (점검 전용)

/doc-update가 실제 수정이라면, /doc-sync는 점검만 한다:

• 변경 파일 → change class 분류
• 필수 문서 누락 여부 체크
• ✅ all docs updated 또는 ⚠️ N doc(s) need update 판정

Step 7: 상태 자동 정리 스크립트

tools/prune-status.sh:

#!/bin/bash
# done (YYYY-MM-DD) 형식의 항목 중 14일 이상 된 것을 제거
FILE="docs/status/PROJECT-STATUS.md"
DAYS=14
TODAY=$(date +%s)

# --dry-run 지원
DRY_RUN=false
[[ "$1" == "--dry-run" ]] && DRY_RUN=true

while IFS= read -r line; do
  if echo "$line" | grep -qE 'done \(([0-9]{4}-[0-9]{2}-[0-9]{2})\)'; then
    date_str=$(echo "$line" | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}')
    item_ts=$(date -j -f "%Y-%m-%d" "$date_str" +%s 2>/dev/null || date -d "$date_str" +%s 2>/dev/null)
    diff_days=$(( (TODAY - item_ts) / 86400 ))
    if [ "$diff_days" -gt "$DAYS" ]; then
      echo "PRUNE ($diff_days days): $line"
      $DRY_RUN || sed -i '' "/$(echo "$line" | sed 's/[[\.*^$()+?{|]/\\&/g')/d" "$FILE"
    fi
  fi
done < "$FILE"

서브에이전트 모델 배분

규칙

• trivial 변경(주석, 오탈자, 테스트만)이면 "문서 갱신 불필요"로 종료
• 구현과 문서가 충돌하면 구현 우선 → status 문서부터 맞춤
• 같은 사실을 여러 문서에 반복하지 않음
• DECISION-LOG에는 pending만 유지, resolved는 archive로
• done 항목에 날짜 없으면 영구 잔류 → 반드시 날짜 포함

이 스킬의 사용법

/doc-framework

실행하면:

1. 현재 프로젝트에 문서 구조가 있는지 확인
2. 없으면 Step 1~7 순서로 scaffolding 제안
3. 있으면 현재 체계의 건강성 점검 (누락 문서, 오래된 상태, pending 결정)