doc-framework

name	doc-framework
description	프로젝트 독립적 문서 관리 프레임워크 — 정본 1곳 원칙, change-class 기반 자동 갱신, 상태 자동 정리를 다른 프로젝트에 이식할 때 사용
user_invocable	true

Doc Management Framework — 범용 이식 스킬

프로젝트의 언어, 프레임워크, 도메인에 관계없이 적용 가능한 문서 관리 체계. 새 프로젝트에 이 프레임워크를 도입하거나, 기존 프로젝트의 문서 체계를 점검할 때 사용한다.

핵심 원칙

1. 정본 1곳 원칙 (Single Source of Truth)

• 하나의 사실은 하나의 문서에만 기록한다
• 나머지 문서는 링크로 참조하거나 "done" 한 줄만
• 구현과 문서가 충돌하면 구현을 먼저 확인하고 문서를 맞춘다

2. 문서 계층 (Loading Order)

Tier	역할	예시	읽는 시점
Tier 1: Always	진입점 + 현재 상태	CLAUDE.md, PROJECT-STATUS, ARCHITECTURE	매 세션
Tier 2: On-Demand	해당 영역 작업 시	SCHEMA, ROUTE-SPECS, PIPELINE-MODEL	관련 작업 시
Tier 3: Reference	필요 시 검색	DECISION-LOG, POLICY, EVALUATION	판단 필요 시

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 예시:

변경 영역	필수 갱신	조건부 갱신
어떤 코드든	PROJECT-STATUS.md	—
ROS node/topic	NODE-TOPOLOGY.md	ARCHITECTURE.md
Unity scene/prefab	SCENE-SPECS.md	ASSET-GUIDE.md
C# MonoBehaviour	ARCHITECTURE.md	—
URDF/모델	ROBOT-MODEL.md	SCHEMA.md
launch file	LAUNCH-SPECS.md	NODE-TOPOLOGY.md
메시지 타입(.msg/.srv)	MESSAGE-CATALOG.md	NODE-TOPOLOGY.md
시뮬레이션 설정	SIM-CONFIG.md	—
하드웨어 인터페이스	HW-INTERFACE.md	SAFETY-CONSTRAINTS.md
경계 결정	DECISION-LOG.md	→ resolved 시 archive

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"

서브에이전트 모델 배분

작업	모델	이유
상태 한 줄 추가	haiku	단순 삽입
섹션 수정	sonnet	맥락 파악 필요
drift 감지	sonnet	change class 분류
아키텍처 결정	opus	근거/영향 분석 (예외)

규칙

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

이 스킬의 사용법

/doc-framework

실행하면:

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