docs-organize

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).

절차

1. docs/, README, AGENTS.md, CLAUDE.md, .claude/notes/, .codex/notes/ 트리를 스캔한다.
2. 문서별로 다음을 라벨링한다.
   • 주제 영역(rules, project-map, build/test, review, design-review, runbook, FAQ, 도메인 지식 등)
   • SSOT 여부(이 주제의 1차 출처인지, 다른 문서에서 참조되는지)
   • 상태(현행, stale, 중복, 고아)
3. 중복·모순을 식별한다.
   • 같은 주제가 두 곳 이상이면 SSOT 한 곳으로 모은다.
   • 모순이 있으면 사용자에게 어느 쪽이 맞는지 묻는다.
4. 재배치 계획을 세운다.
   • 위치 변경: <기존 경로> → <새 경로> 와 이유
   • 통합: <문서 A, B> → <문서 C> 와 이유
   • 분할: <문서 A> → <문서 A1, A2> 와 이유
   • 삭제: <문서> 와 이유
5. 사용자 승인을 받는다(영향 범위가 크면 변경 전에 한 번 확인).
6. 재배치 실행.
7. docs/README.md 라우터를 갱신한다.
   • 모든 활성 문서 경로와 한 줄 설명
   • 주제별 그룹화
   • stale/보류 문서는 명시
8. 참조 링크를 수정한다(다른 문서나 코드 주석에서 옛 경로를 가리키는 것).

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
- 옛 참조 수정: <대상 파일과 라인>
- 확인 필요: <사용자 질문 또는 미검증 항목>