code-to-docs

name	code-to-docs
description	코드를 읽고 docs/를 생성·구조화한다. 코드만 있고 문서가 없는 영역에서 프로젝트 맵, 모듈 문서, API 개요, 아키텍처 메모를 만든다.
disable-model-invocation	true

code-to-docs

이 skill은 문서가 비어 있는 코드 영역에서 사람 읽기 좋은 문서를 만드는 데 쓴다. 코드 동작을 추정해 단정하지 않는다. 확인 가능한 사실과 추정을 분리한다. 파일 생성/수정 workflow이므로 수동 호출 전용이다.

사용 시점

• 신규 합류자가 코드 구조를 한눈에 볼 수 있는 문서가 없다.
• 모듈은 있는데 책임·의존·공개 인터페이스를 모은 문서가 없다.
• 신규 모듈을 통합한 직후 아키텍처 개관 갱신이 필요하다.
• 코드만 있고 빌드/테스트/배포 절차가 어디에도 정리돼 있지 않다.

사용하지 않는 경우

• 이미 문서가 있는데 어지러운 상태(이 경우는 docs-organize).
• 새 기능을 만들기 전에 설계가 필요한 경우(이 경우는 pdr).
• 변경 사항 단건 설명이면 PR 설명에 둔다.

우선순위 (작업 대상 문서)

1. docs/project-map.md — 폴더/모듈 트리와 책임
2. docs/build-and-test.md — 빌드/테스트/린트/실행 명령 (package.json, Makefile, build.gradle 등 SSOT 참조)
3. docs/architecture.md — 데이터 흐름, 의존 방향, 외부 시스템 연결
4. docs/modules/<name>.md — 큰 모듈별 책임·공개 인터페이스·확장 포인트
5. docs/api/<area>.md — 외부에 노출되는 API 개요 (실제 스펙은 OpenAPI 등 SSOT 참조)
6. docs/runbook.md — 운영/배포/장애 대응 절차(필요 시)

후보를 전부 만들지 않는다. 코드에서 확인 가능한 사실이 있는 것만 만든다.

절차

1. 대상 코드 트리를 스캔한다.
   • 패키지 매니저 파일(package.json, pyproject.toml, build.gradle, go.mod 등)
   • 진입점 파일(main, index, app)
   • 폴더 구조와 명명 규칙
2. 모듈별로 다음을 추출한다.
   • 책임 (코드의 공개 함수/클래스/엔드포인트가 어떤 일을 하는가)
   • 의존 (import/require, 외부 서비스 호출)
   • 공개 인터페이스 (export, public, 라우터)
   • 데이터 모델 (스키마, 마이그레이션, ORM 엔티티)
3. 확인 가능한 사실과 추정을 분리한다.
   • 코드에서 직접 보이는 것은 사실로 쓴다.
   • 의도·이유는 사용자에게 묻거나 "추정"으로 표시한다.
4. 문서 골격을 만든다.
5. 사용자에게 보여주고 사실 검증을 받는다.
6. 검증 후 문서를 채우고 docs/README.md 라우터에 연결한다.

문서 작성 원칙

• 코드 인용은 짧게(파일:라인). 본문을 통째로 복사하지 않는다.
• "이 함수는 X를 한다"는 코드를 읽으면 보이는 사실로만 쓴다.
• 의도·트레이드오프는 별도 섹션 "설계 메모"에 두고 사용자 확인 후 작성.
• 외부 SSOT(스펙 파일, OpenAPI, schema)가 있으면 본문 복제하지 말고 경로 참조.

project-map.md 예시 형식

# Project Map

## 루트 구조
- `src/` — <한 줄 설명>
- `tests/` — <한 줄 설명>
- ...

## 모듈
### `<module-name>`
- 위치: `<path>`
- 책임: <한 문장>
- 공개 인터페이스: <export/router/CLI 진입점>
- 주요 의존: <내부 모듈, 외부 라이브러리>
- 관련 문서: <docs 경로>

modules/.md 예시 형식

# <module-name>

## 책임
- <코드에서 보이는 사실>

## 공개 인터페이스
- `<symbol>` (`<path>:L<line>`) — <역할>

## 데이터 모델
- <스키마, 타입>

## 외부 의존
- <서비스, 라이브러리>

## 확장 포인트
- <플러그인, 콜백, 설정>

## 설계 메모 (사용자 확인 후 채움)
- 의도: <추정 또는 사용자 확인 필요>
- 트레이드오프: <추정 또는 사용자 확인 필요>

self-check

• 코드 인용이 짧고 출처(파일:라인)가 있는가
• 추정과 사실이 섞이지 않았는가
• 외부 SSOT 본문을 복제하지 않았는가
• 문서가 사람 읽기 순서(개관 → 모듈 → 세부)로 정렬되어 있는가
• docs/README.md 라우터에 새 문서가 연결되었는가

출력 형식

## code-to-docs 결과

- 스캔 대상: <경로>
- 생성: <문서 목록과 이유>
- 추정으로 분리한 항목: <목록>
- 사용자 확인 필요: <질문>
- 라우터 갱신: docs/README.md