docs
목적
문서화 수명 주기 관리자. 초기 프로젝트 문서를 생성하고, 문서를 코드 변경 사항과 동기화하며, API 참조를 생성하고, 변경 로그를 자동 생성합니다. 문서화의 가장 큰 문제인 "문서는 존재하지만 구식인" 문제를 해결합니다.
<하드-게이트> 문서는 반드시 실제 코드에서 생성되어야 하며, 지어내서는 안 됩니다. 생성된 문서의 모든 진술은 코드베이스의 특정 파일, 함수 또는 구성으로 추적 가능해야 합니다. 코드가 아직 존재하지 않는다면, 문서는 구현이 아닌 계획을 설명해야 합니다. </하드-게이트>
트리거
scaffold의 7단계에서 초기 문서 생성을 위해 호출됨cook의 7단계 이후 기능 구현 후 문서 업데이트를 위해 호출됨launch의 배포 전 문서 최신 상태 확인을 위해 호출됨/rune docs init— 최초 문서 생성/rune docs update— 최근 코드 변경 사항과 문서 동기화/rune docs api— API 문서 생성/rune docs changelog— git 기록에서 변경 로그 자동 생성
호출 (아웃바운드)
scout(L2): 문서 대상(라우트, 익스포트, 컴포넌트, 설정)을 위해 코드베이스 스캔doc-processor(L3): 요청 시 PDF/DOCX 내보내기 생성git(L3): 변경 로그 생성을 위해 커밋 기록 읽기
호출자 (인바운드)
scaffold(L1): 7단계 — 새 프로젝트의 초기 문서 생성cook(L1): 구현 후 — 변경된 모듈의 문서 업데이트launch(L1): 배포 전 — 문서 최신 상태 확인mcp-builder(L2): MCP 서버 문서 생성- 사용자:
/rune docs직접 호출
모드
초기화 모드 — /rune docs init
프로젝트의 최초 문서 생성.
업데이트 모드 — /rune docs update
증분 동기화 — 최근 코드 변경 사항의 영향을 받은 문서만 업데이트.
API 모드 — /rune docs api
API 문서를 특별히 생성하거나 업데이트.
변경 로그 모드 — /rune docs changelog
git 커밋 기록에서 변경 로그 자동 생성.
실행 가능 단계
초기화 모드
1단계 — 코드베이스 스캔
rune:scout을 호출하여 다음을 추출:
- 프로젝트 이름, 설명, 기술 스택
- 디렉토리 구조 및 주요 파일
- 진입점 (main, index, app)
- 공개 API 표면 (익스포트, 라우트, 컴포넌트)
- 설정 파일 (.env.example, 설정 패턴)
- 기존 문서 (있는 경우 — 병합, 덮어쓰지 않음)
2단계 — README.md 생성
구조:
# [프로젝트 이름]
[한 줄 설명]
## 빠른 시작
[실행을 위한 3-5개 명령어: 설치, 설정, 시작]
## 기능
[코드에서 추출한 불릿 목록 — 라우트, 컴포넌트, 기능]
## 기술 스택
[package.json, requirements.txt, Cargo.toml 등에서 감지]
## 프로젝트 구조
[한 줄 설명이 포함된 주요 디렉토리]
## 설정
[설명이 포함된 .env.example의 환경 변수]
## 개발
[개발 서버, 테스트, 린트, 빌드 명령어]
## API 참조
[해당하는 경우 API.md 링크 또는 인라인 요약]
## 라이선스
[LICENSE 파일 또는 package.json에서 감지]
3단계 — ARCHITECTURE.md 생성 (프로젝트 파일이 10개 이상인 경우)
구조:
# 아키텍처
## 개요
[텍스트/머메이드의 시스템 다이어그램 — 컴포넌트 및 데이터 흐름]
> ARCHITECTURE 개요는 원시 Mermaid 대신 설계된 시스템 그림(유형 `architecture`)을 위해 `rune:diagram`을 호출할 수 있습니다 — `suggested_next: diagram`.
## 주요 결정 사항
[감지된 패턴: 프레임워크 선택, 상태 관리, DB, 인증 방식]
## 모듈 맵
[각 최상위 디렉토리: 목적, 주요 파일, 종속성]
## 데이터 흐름
[요청 수명 주기 또는 데이터 파이프라인 설명]
4단계 — API.md 생성 (라우트/엔드포인트가 감지된 경우)
라우트 파일을 스캔하여 추출:
- HTTP 메서드 + 경로
- 요청 매개변수 (경로, 쿼리, 본문)
- 응답 형태
- 인증 요구 사항
- 오류 응답
마크다운 테이블 또는 OpenAPI 호환 참조로 형식화.
5단계 — 보고
생성된 문서를 요약과 함께 사용자에게 제시:
- 생성된 파일: [목록]
- 적용 범위: [문서화된 것과 존재하는 것]
- 격차: [문서가 없는 코드 영역 — 다음 단계 제안]
업데이트 모드
1단계 — 변경 사항 감지
마지막 문서 업데이트 이후 git diff 읽기 (문서 파일의 git 로그 또는 .rune/docs-sync.json을 통해 추적).
식별:
- 새 파일/모듈 → 새 문서 섹션 필요
- 변경된 함수/라우트 → 문서 업데이트 필요
- 삭제된 코드 → 문서 제거 필요
- 새 설정 → 설정 문서 업데이트 필요
2단계 — 영향받은 섹션 업데이트
변경된 각 영역에 대해:
- 변경된 코드 읽기
- 해당 문서 섹션 찾기
- 현재 코드와 일치하도록 문서 업데이트
- 문서 섹션이 없으면 → 생성
- 코드가 삭제되었으면 → 문서에서 제거하거나 사용 중단으로 표시
<하드-게이트> 문서 콘텐츠를 조용히 제거하지 마십시오. 코드가 삭제된 경우 문서 섹션을 "[커밋]에서 제거됨"으로 표시하거나 문서 섹션을 삭제하기 전에 사용자에게 물어보십시오. </하드-게이트>
3단계 — 변경 로그 항목 생성
마지막 문서 업데이트 이후 커밋에서 변경 로그 항목을 생성하기 위해 rune:git changelog에 위임.
4단계 — 교차 문서 일관성 검사
교차 문서 일관성은 두 번째로 흔한 문서 문제(문서는 존재하지만 서로 모순됨)를 방지합니다.
문서를 업데이트한 후 모든 프로젝트 문서의 일관성을 확인:
| 검사 | 파일 | 비교할 내용 |
|---|---|---|
| 버전 번호 | README, CLAUDE.md, package.json, CHANGELOG | 모두 현재 버전과 일치해야 함 |
| 기능 목록 | README, 랜딩 페이지, CLAUDE.md | 동일한 기능 목록 (세부 수준은 다를 수 있음) |
| 통계 | README, CLAUDE.md, 랜딩 페이지, 대시보드 | 스킬 수, 테스트 수, 시그널 수가 일치해야 함 |
| 명령어 | README, CLAUDE.md, docs/ | 동일한 플래그를 가진 동일한 명령어 |
| 기술 스택 | README, ARCHITECTURE.md, CLAUDE.md | 일관된 프레임워크/라이브러리 참조 |
교차 문서 일관성:
- [x] README.md ↔ CLAUDE.md: 버전 일치, 명령어 일치
- [x] README.md ↔ docs/index.html: 통계 일치, 기능 일치
- [ ] README.md에 "62개 스킬"이라고 되어 있지만 CLAUDE.md에는 "59개" → CLAUDE.md 수정
불일치 사항을 즉시 수정 — 보고만 하지 마십시오. 진실 공급원(일반적으로 코드 또는 가장 최근에 업데이트된 문서)과 일치하도록 오래된 문서를 업데이트하십시오.
5단계 — 보고
사용자에게 표시: 업데이트된 내용, 추가된 내용, 검토가 필요한 내용. 교차 문서 일관성 결과를 포함합니다.
API 모드
1단계 — API 프레임워크 감지
| 프레임워크 | 라우트 패턴 | 파일 패턴 |
|---|---|---|
| Express | router.get/post/put/delete | routes/*.ts, *.router.ts |
| FastAPI | @app.get/post/put/delete | routers/*.py, main.py |
| NestJS | @Get/@Post/@Put/@Delete | *.controller.ts |
| Next.js App | export async function GET/POST | app/**/route.ts |
| Next.js Pages | export default function handler | pages/api/**/*.ts |
| SvelteKit | export function GET/POST | src/routes/**/+server.ts |
| Hono | app.get/post/put/delete | src/*.ts |
2단계 — 엔드포인트 추출
감지된 각 라우트에 대해:
- 메서드 (GET, POST, PUT, DELETE, PATCH)
- 경로 (매개변수 강조 표시)
- 요청: params, query, body 형태 (Zod 스키마, TypeScript 타입, Pydantic 모델에서)
- 응답: 형태 (반환 타입 또는 응답 헬퍼에서)
- 인증: 필요? (authMiddleware, @UseGuards와 같은 미들웨어 감지)
- 설명: 사용 가능한 경우 JSDoc/docstring에서
3단계 — API 참조 생성
마크다운으로 형식화:
# API 참조
## 인증
[인증 메커니즘 설명]
## 엔드포인트
### `POST /api/auth/login`
**설명**: 사용자 인증 및 토큰 반환
**인증**: 없음
**요청 본문**:
| 필드 | 유형 | 필수 | 설명 |
|-------|------|----------|-------------|
| email | string | 예 | 사용자 이메일 |
| password | string | 예 | 사용자 비밀번호 |
**응답** (200):
```json
{ "token": "string", "refreshToken": "string" }
오류:
- 401: 잘못된 자격 증명
- 422: 유효성 검사 오류
#### 4단계 — 출력
`docs/API.md` 또는 프로젝트별 위치에 저장. OpenAPI가 요청되면 `openapi.yaml` 생성.
### 변경 로그 모드
#### 1단계 — Git에 위임
커밋을 유형별로 그룹화하고 Keep a Changelog 형식으로 지정하기 위해 `rune:git changelog` 호출.
#### 2단계 — 향상
원시 변경 로그에 컨텍스트 추가:
- PR 번호를 실제 설명에 연결
- 관련 변경 사항을 기능 헤더 아래에 그룹화
- 호환성을 깨는 변경 사항을 눈에 띄게 강조
#### 3단계 — 출력
`CHANGELOG.md`에 추가 또는 업데이트.
## 출력 형식
### 초기화 모드 출력
프로젝트 루트에 생성된 파일:
- `README.md` — 빠른 시작, 기능, 기술 스택, 구조, 설정, 개발 명령어
- `ARCHITECTURE.md` — 개요 다이어그램, 주요 결정 사항, 모듈 맵, 데이터 흐름 (파일이 10개 이상인 경우)
- `docs/API.md` — 메서드, 경로, 매개변수, 응답, 인증이 포함된 엔드포인트 참조 (라우트가 감지된 경우)
### 업데이트 모드 출력
변경 요약과 함께 수정된 문서 섹션:
문서 업데이트 보고:
- 업데이트됨: [수정된 문서 섹션 목록]
- 추가됨: [새 코드에 대한 새 섹션]
- 플래그 지정됨: [삭제된 코드를 참조하는 오래된 섹션]
- 변경 로그: [CHANGELOG.md에 추가된 항목]
### API 모드 출력
`docs/API.md` — 엔드포인트당 마크다운 참조:
METHOD /path/:param
설명: [JSDoc/docstring에서] 인증: [필요/없음] 요청: [params, query, body 테이블] 응답: [상태 코드가 포함된 형태] 오류: [오류 코드 및 설명]
### 변경 로그 모드 출력
`CHANGELOG.md` — Keep a Changelog 형식으로 그룹화: 추가됨, 수정됨, 변경됨, 제거됨.
## 제약 조건
1. 실제 코드에서 문서를 생성해야 함 — 존재하지 않는 기능이나 API를 절대 지어내지 않음
2. 기존 문서를 보존해야 함 — 섹션을 업데이트하고 전체 파일을 덮어쓰지 않음
3. 문서의 노후화를 감지해야 함 — 삭제/변경된 코드를 참조하는 섹션에 플래그 지정
4. 모든 README에 빠른 시작을 포함해야 함 — 사용자가 2분 이내에 실행 가능해야 함
5. 아직 존재하지 않는 코드에 대한 문서를 생성해서는 안 됨 (명시적으로 사양 문서를 생성하는 경우 제외)
6. API 문서는 실제 라우트 시그니처와 일치해야 함 — 잘못된 API 문서는 문서가 없는 것보다 더 나쁨
## 반환 값
| 산출물 | 형식 | 위치 |
|----------|--------|--------|
| README.md | 마크다운 | 프로젝트 루트 |
| ARCHITECTURE.md | 마크다운 | 프로젝트 루트 (파일이 10개 이상인 경우) |
| API 참조 | 마크다운 | `docs/API.md` |
| 변경 로그 항목 | 마크다운 (Keep a Changelog) | `CHANGELOG.md` |
| 문서 업데이트 보고서 | 마크다운 | 인라인 (채팅 출력) |
**범위 가드레일:** 코드베이스에 존재하는 것만 문서화 — 기능, 엔드포인트 또는 API를 절대 지어내지 않음.
## 예리한 모서리
| 실패 모드 | 심각도 | 완화 |
|---|---|---|
| 존재하지 않는 API 엔드포인트를 지어냄 | 치명적 | 제약 조건 1: 추측하지 말고 실제 라우트 파일 스캔 |
| 사용자가 작성한 README 섹션을 덮어씀 | 높음 | 제약 조건 2: 병합, 덮어쓰지 않음 — 사용자 정의 섹션 감지 |
| 코드 변경 후 오래된 문서 | 높음 | 업데이트 모드가 diff를 감지하고 영향받은 섹션 업데이트 |
| 잘못된 요청/응답 형태를 가진 API 문서 | 높음 | 메모리에서가 아닌 Zod/Pydantic/TypeScript 타입에서 추출 |
| 빠른 시작 섹션 누락 | 중간 | 제약 조건 4: 모든 README에 빠른 시작 포함 |
| 연결이 끊긴 PR 링크가 있는 변경 로그 | 낮음 | 연결하기 전에 PR 번호가 존재하는지 확인 |
| 문서 간 불일치 (README에 X, CLAUDE.md에 Y) | 높음 | 7단계: 교차 문서 일관성 검사 — 모든 문서에서 통계, 버전, 기능 목록 일치 확인 |
| 한 문서는 업데이트했지만 다른 문서는 업데이트하지 않음 (통계 드리프트) | 높음 | 문서 업데이트 후 모든 관련 문서에서 오래된 통계를 정리 — 특히 README ↔ CLAUDE.md ↔ 랜딩 페이지 |
## 완료 조건
### 초기화 모드
- 코드베이스가 scout으로 스캔됨
- 빠른 시작, 기능, 기술 스택, 구조가 포함된 README.md 생성됨
- ARCHITECTURE.md 생성됨 (파일이 10개 이상인 경우)
- API.md 생성됨 (라우트가 감지된 경우)
- 적용 범위 보고서가 사용자에게 제시됨
### 업데이트 모드
- 마지막 문서 업데이트 이후 변경 사항이 감지됨
- 영향받은 문서 섹션이 업데이트됨
- 변경 로그 항목이 생성됨
- 업데이트 보고서가 사용자에게 제시됨
### API 모드
- API 프레임워크가 감지됨
- 모든 엔드포인트가 메서드, 경로, 요청, 응답과 함께 추출됨
- API 참조가 마크다운으로 생성됨
- docs/API.md에 저장됨
### 변경 로그 모드
- 커밋이 유형별로 그룹화됨
- Keep a Changelog 형식으로 지정됨
- CHANGELOG.md가 업데이트됨
## 비용 프로필
~2000-5000 토큰 입력, ~1000-3000 토큰 출력. Sonnet — 문서화에는 깊은 아키텍처 추론보다는 코드 패턴 이해가 필요합니다.