| name | docs-organize |
| description | 기존 docs/와 README, 인접 문서를 읽고 재배치·구조화한다. 라우터 docs/README.md를 정비하고 중복·모순·고아 문서를 정리한다. 새 본문을 만들기보다 기존 문서의 정리가 우선이다. |
| disable-model-invocation | true |
docs-organize
이 skill은 이미 있는 문서를 다시 정리하는 데 쓴다.
새 문서를 만드는 것은 보조 작업이고, 본 작업은 분류·재배치·인덱싱이다.
파일 생성/수정 workflow이므로 수동 호출 전용이다.
사용 시점
- 기존
docs/ 트리에 파일은 많은데 라우팅이 없어서 새 작업자가 어디부터 봐야 할지 모른다.
- 한 문서가 비대해져서 SSOT가 흐릿하다.
- 같은 주제가 여러 곳에 흩어져 있다(예: 빌드 명령이 README, AGENTS.md, docs/setup.md에 각각 있음).
- 하네스 적용 후
docs/README.md를 라우터로 정비해야 한다.
- 코드는 그대로인데 문서가 시간이 지나 stale 상태다.
사용하지 않는 경우
- 코드는 있는데 문서가 아예 없다(이 경우는
code-to-docs를 쓴다).
- 단일 문서의 본문만 다듬으면 된다(직접 편집).
- 문서가 부족한 게 아니라 설계 결정이 빠져 있다(이 경우는
pdr).
절차
docs/, README, AGENTS.md, CLAUDE.md, .claude/notes/, .codex/notes/ 트리를 스캔한다.- 문서별로 다음을 라벨링한다.
- 주제 영역(rules, project-map, build/test, review, design-review, runbook, FAQ, 도메인 지식 등)
- SSOT 여부(이 주제의 1차 출처인지, 다른 문서에서 참조되는지)
- 상태(현행, stale, 중복, 고아)
- 중복·모순을 식별한다.
- 같은 주제가 두 곳 이상이면 SSOT 한 곳으로 모은다.
- 모순이 있으면 사용자에게 어느 쪽이 맞는지 묻는다.
- 재배치 계획을 세운다.
- 위치 변경: <기존 경로> → <새 경로> 와 이유
- 통합: <문서 A, B> → <문서 C> 와 이유
- 분할: <문서 A> → <문서 A1, A2> 와 이유
- 삭제: <문서> 와 이유
- 사용자 승인을 받는다(영향 범위가 크면 변경 전에 한 번 확인).
- 재배치 실행.
docs/README.md 라우터를 갱신한다.
- 모든 활성 문서 경로와 한 줄 설명
- 주제별 그룹화
- stale/보류 문서는 명시
- 참조 링크를 수정한다(다른 문서나 코드 주석에서 옛 경로를 가리키는 것).
docs/README.md 라우터 형식
# Docs
이 폴더는 프로젝트 문서의 진입점이다.
## 문서 라우팅
### 작업 기준
- 프로젝트 규칙 → <경로>
- 빌드/테스트 → <경로>
- 리뷰 기준 → <경로>
### 구조 이해
- 프로젝트 맵 → <경로>
- 아키텍처 → <경로>
- 모듈별 문서 → <경로>
### 결정 기록
- 설계 리뷰 → docs/design-reviews/
- ADR/RFC → <경로>
- 하네스 결정 → .claude/notes/harness-decisions.md(생성된 경우)
### skill / MCP
- skill 추천 결과 → docs/skill-recommendations.md(생성된 경우)
- Context7 MCP → .claude/notes/context7-mcp.md
## 운영 원칙
- 같은 주제는 한 문서에 모은다.
- 새 문서를 만들기 전에 기존 문서에 추가할 자리가 있는지 본다.
- stale/보류 문서는 라우터에서 명시한다.
self-check
- 같은 주제가 두 곳 이상에 본문으로 남아 있지 않은가
docs/README.md만 보고도 새 작업자가 필요한 문서를 30초 안에 찾을 수 있는가- 옛 경로를 가리키는 stale 참조가 없는가
- SSOT가 깨끗하고, 모순이 있을 때 어느 쪽이 맞는지 명시했는가
- 임의로 본문을 통째 복제하지 않았는가
출력 형식
## docs-organize 결과
- 스캔 대상: <트리 요약>
- 라벨링 요약: <주제별 문서 수, SSOT 분포>
- 재배치: <변경 목록>
- 통합/분할/삭제: <목록과 이유>
- 라우터 갱신: docs/README.md
- 옛 참조 수정: <대상 파일과 라인>
- 확인 필요: <사용자 질문 또는 미검증 항목>
