docs

name	docs
description	현재 프로젝트의 코드 변경사항을 분석하여 /docs/ 폴더에 문서를 자동 생성합니다. "문서화", "docs", "문서 생성" 키워드에 활성화.

자동 문서 생성

코드를 읽고 개발자를 위한 실용적인 문서를 /docs/ 폴더에 자동 생성합니다.

핵심 철학

"코드를 읽으면 아는 것은 쓰지 않는다. 코드만으로는 알 수 없는 것을 쓴다."

• 함수 시그니처 나열 X → 왜 이런 설계인지, 어떻게 써야 하는지
• 코드 복붙 X → 사용 예시와 주의사항
• 모든 것 문서화 X → 변경된 것, 중요한 것만

호출 방식

인자 없이: $docs

• git diff로 최근 변경된 파일 기준으로 문서 생성/업데이트

특정 유형: $docs api, $docs components

• 특정 유형의 문서만 생성/업데이트

전체 생성: $docs all

• 프로젝트 전체 코드를 분석하여 /docs/ 일괄 생성

실행 프로세스

Step 1: 변경사항 파악

git diff --name-only HEAD~5..HEAD 2>/dev/null
git diff --name-only
git diff --name-only --cached

인자가 all이면 전체 소스 파일을 대상으로 합니다.

Step 2: 파일 유형별 분류

파일 패턴	문서 유형	출력 위치
**/api/**, **/routes/**, **/endpoints/**	API 문서	docs/api.md
**/components/**/*.tsx	컴포넌트 문서	docs/components.md
**/hooks/**	훅 문서	docs/hooks.md
**/utils/**, **/lib/**, **/helpers/**	유틸리티 문서	docs/utils.md
**/models/**, **/schema/**, **/types/**	데이터 모델 문서	docs/models.md
**/services/**	서비스 문서	docs/services.md
*.config.*, docker*, .env.example	설정 문서	docs/setup.md

Step 3: 문서 생성

변경된 파일이 많으면 유형별로 서브에이전트를 병렬 실행:

파일 수가 10개 이하: 단일로 처리 파일 수가 10개 초과: 유형별 병렬 실행

Step 4: 인덱스 업데이트

docs/README.md와 docs/CHANGELOG.md를 업데이트합니다.

문서 유형별 형식

API 문서 (docs/api.md)

## `METHOD /path`
[한 줄 설명]

**요청**
| 파라미터 | 타입 | 필수 | 설명 |

**응답**
| 상태 | 설명 |

**사용 예시**

컴포넌트 문서 (docs/components.md)

## ComponentName
[한 줄 설명]

**Props**
| Prop | 타입 | 기본값 | 설명 |

**사용 예시**
**주의사항**

유틸리티 문서 (docs/utils.md)

## `functionName(params)`
[한 줄 설명]

**파라미터** | **반환값** | **사용 예시** | **엣지 케이스**

데이터 모델 문서 (docs/models.md)

## ModelName
[이 모델이 나타내는 것]

**필드**
| 필드 | 타입 | 필수 | 설명 |

**관계**

문서 작성 규칙

1. 코드를 읽으면 아는 것은 생략 — 타입 시그니처 나열 금지
2. "왜"와 "언제"를 쓴다 — 이 함수를 왜 만들었고, 언제 써야 하는지
3. 사용 예시 필수 — 모든 public API에 복붙 가능한 예시
4. 주의사항/함정 — 이걸 모르면 실수하는 것
5. 한국어로 작성 — 설명은 한국어, 코드/변수명은 원문 유지
6. 기존 문서 있으면 업데이트 — 새 파일 생성보다 기존 파일 수정 우선
7. 없는 유형은 스킵 — API가 없으면 api.md 안 만듦
8. /docs/ 폴더만 수정 — 소스 코드 절대 수정 금지