comprehensive-docs

name	comprehensive-docs
description	기술 스택·프레임워크·API의 모든 기능을 실전 예제와 함께 체계적으로 문서화하는 스킬. Hook, API, CLI, 설정 파일 등 모든 옵션을 빠짐없이 정리하고 실제 동작하는 코드 예제를 생성합니다.

Comprehensive Documentation Generator

API, 프레임워크, 설정 파일의 모든 기능을 빠짐없이 정리하고 실제 동작하는 예제를 생성하는 문서화 스킬입니다.

이 스킬을 사용하는 경우

• 새로운 API/프레임워크를 프로젝트에 도입할 때 전체 기능 파악
• 설정 파일(.json, .yaml, frontmatter)의 모든 옵션 문서화
• 팀원들을 위한 실전 예제 생성
• 레거시 코드의 기능 목록 역공학
• "이 기술의 모든 기능이 뭐야?"라는 질문에 답변

작업 프로세스

1단계: 기능 목록 완전 파악

목표: 빠뜨린 기능이 없도록 전체 스펙 확인

방법:

1. 공식 문서 조회 (Context7 MCP 활용)

   @context7-docs [라이브러리명] all features
   

2. 타입 정의 확인 (TypeScript/Python)

   // 인터페이스에서 모든 필드 추출
   interface HookConfig {
     type: string;
     command: string;
     windows?: string;
     timeout?: number;
   }
   

3. 기존 코드 검색

   grep -r "hookEventName" --include="*.ts" --include="*.js"
   

4. 체크리스트 작성

   ✅ SessionStart
   ✅ UserPromptSubmit
   ✅ PreToolUse
   ✅ PostToolUse
   ✅ PreCompact
   ✅ SubagentStart
   ✅ SubagentStop
   ✅ Stop
   

---

2단계: 기능별 예제 설계

원칙:

• 실제 동작하는 코드 (복붙하면 바로 실행 가능)
• 주석으로 상세 설명 (용도, 환경변수, 출력 형식)
• 에러 처리 포함 (실패해도 무시하는 경우 명시)

예제 구조:

#!/usr/bin/env node
/**
 * [기능명] 예제
 * 
 * 용도: [한 줄 설명]
 * 
 * 환경변수:
 * - VAR_NAME: 설명
 */

// ═══════════════════════════════════════════════════════════════════
// 1. [첫 번째 기능]
// ═══════════════════════════════════════════════════════════════════
const example1 = () => {
  // 구현
};

// ═══════════════════════════════════════════════════════════════════
// 2. [두 번째 기능]
// ═══════════════════════════════════════════════════════════════════
const example2 = () => {
  // 구현
};

// 최종 출력
console.log(JSON.stringify({ result: 'success' }));

---

3단계: 파일 구조 설계

원칙:

• 설정 파일과 스크립트를 쌍으로 관리
• 번호 prefix로 순서 명확히
• examples/ 폴더로 실제 사용과 분리

예시 구조:

.github/hooks/
├── quality.json                     ← 실제 사용 중
├── _OPTIONS.md                      ← 전체 옵션 가이드
└── examples/                        ← 예제 모음
    ├── README.md                    ← 종합 가이드
    ├── 1-session-start.json
    ├── 2-user-prompt-submit.json
    ├── ...
    └── scripts/
        ├── session-start.js
        ├── user-prompt-submit.js
        └── ...

---

4단계: 종합 가이드 작성 (README)

필수 포함 내용:

1. 기능 비교 테이블

   | 기능 | 타이밍 | 용도 |
   |---|---|---|
   | SessionStart | 세션 시작 | 환경 정보 주입 |
   

2. 빠른 시작 가이드

   # 전체 활성화
   cp examples/*.json ./
   

3. 실전 조합 예시

   ### 보안 강화
   - PreToolUse (파일 접근 차단)
   - UserPromptSubmit (위험 프롬프트 차단)
   

4. 커스터마이징 방법

   // scripts/pre-tool-use.js 수정
   const sensitivePatterns = [
     /\.env$/,
     /your-custom-pattern/  // 여기 추가
   ];
   

5. 트러블슈팅

   ## 작동하지 않으면
   1. 설정 확인
   2. 권한 확인
   3. 직접 실행해보기
   

---

5단계: 옵션 문서화 (_OPTIONS.md)

구조:

1. 개요 (한 줄 설명)
2. 전체 옵션 테이블
3. 옵션 상세 설명
4. 전체 예시 템플릿
5. 실제 사용 예시
6. 주의사항

예시:

# [기능명] 설정 옵션 완전 가이드

## 지원되는 옵션

| 옵션 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| type | string | ✅ | - | 항상 "command" |
| command | string | ✅ | - | 실행 명령어 |
| timeout | number | ❌ | 30 | 타임아웃(초) |

## 출력 형식

### 기본 응답
\`\`\`json
{"continue": true}
\`\`\`

### 추가 컨텍스트 주입
\`\`\`json
{
  "continue": true,
  "hookSpecificOutput": {...}
}
\`\`\`

---

실전 적용 예시

케이스 1: GitHub Copilot Hooks (방금 작업)

요구사항: 8가지 Hook 이벤트의 모든 기능 정리

산출물:

.github/hooks/examples/
├── README.md                        ← 종합 가이드
├── _OPTIONS.md                      ← 옵션 문서
├── 1-session-start.json             ← 7개 설정 파일
├── 2-user-prompt-submit.json
├── ...
└── scripts/
    ├── session-start.js             ← 8개 실행 스크립트
    ├── user-prompt-submit.js
    └── ...

특징:

• ✅ 8가지 이벤트 모두 커버
• ✅ 각 이벤트마다 실제 동작하는 Node.js 스크립트
• ✅ 보안 차단, 자동 포맷팅, 메트릭 수집 등 실전 기능
• ✅ 조합 가이드 (보안/자동화/메트릭)

---

케이스 2: REST API 클라이언트 문서화

요구사항: API 엔드포인트 전체 + 사용 예제

작업:

// 1단계: 모든 엔드포인트 파악
GET  /users
POST /users
GET  /users/:id
PUT  /users/:id
DELETE /users/:id

// 2단계: 예제 생성
// examples/
// ├── 1-list-users.ts
// ├── 2-create-user.ts
// ├── 3-get-user.ts
// ├── 4-update-user.ts
// ├── 5-delete-user.ts
// └── README.md

---

케이스 3: CLI 도구 문서화

요구사항: git 명령어 체계적 정리

작업:

# 1단계: 명령어 분류
git clone    # 1. 저장소 관리
git init
git add      # 2. 스테이징
git commit   # 3. 커밋
git push     # 4. 원격 동기화
git pull

# 2단계: 카테고리별 예제
examples/
├── 1-repository-management.sh
├── 2-staging-and-committing.sh
├── 3-branching.sh
├── 4-remote-sync.sh
└── README.md

---

품질 체크리스트

문서화 작업 후 다음을 확인:

• 완전성: 모든 기능/옵션을 빠짐없이 포함했는가?
• 실행 가능성: 예제 코드를 복붙하면 바로 실행되는가?
• 명확성: 각 예제의 용도가 주석으로 명확한가?
• 구조화: 파일 이름/폴더 구조가 직관적인가?
• 조합 가이드: 여러 기능을 함께 쓰는 법이 설명되어 있는가?
• 트러블슈팅: 안 될 때 해결 방법이 있는가?
• 커스터마이징: 수정 포인트가 명확히 표시되어 있는가?

---

도구 활용

Context7 MCP로 최신 문서 조회

1. resolve-library-id로 라이브러리 ID 확인
2. query-docs로 "all configuration options" 조회
3. query-docs로 "advanced examples" 조회

코드 검색으로 실제 사용 패턴 찾기

# 특정 API 호출 패턴
grep -r "hookSpecificOutput" --include="*.ts"

# 설정 파일 패턴
find . -name "*.json" -exec grep -l "hooks" {} \;

타입 정의에서 옵션 추출

// TypeScript 인터페이스 → 옵션 목록
interface Config {
  name: string;        // 필수
  description?: string; // 선택
  timeout?: number;     // 선택, 기본값 30
}

---

템플릿: README 구조

# [기능명] 예제 모음

[한 줄 설명]

## 📁 파일 구조
[트리 다이어그램]

## 🚀 사용 방법
### 1. 전체 활성화
### 2. 개별 테스트
### 3. 설정 확인

## 📚 각 기능 상세 설명
### 1️⃣ [기능 1]
### 2️⃣ [기능 2]
...

## 🎯 실전 조합 예시
### [조합 1]
### [조합 2]

## 🔧 커스터마이징
[수정 포인트]

## 🐛 디버깅
[트러블슈팅]

## 📖 참고 문서
[링크]

---

사용 예시

호출 방법 1: Prompt로 빠르게

/document-feature

대상: Prisma Client API

호출 방법 2: Documenter Agent 직접 호출

@Documenter

GitHub Copilot Hooks의 모든 기능을 실전 예제와 함께 정리해줘.

호출 방법 3: 자동화 스크립트

# 파일 구조만 먼저 생성
node .github/scripts/create-docs-structure.js \
  --target "docs/hooks/examples" \
  --features "SessionStart,PreToolUse,PostToolUse" \
  --extension "json" \
  --script-extension "js"

# 그 다음 Documenter Agent가 내용 채우기

호출 방법 4: 다른 Agent에서 참조

---
name: API Documentation Agent
tools: [read, edit, search, 'context7/*']
---

새로운 API/프레임워크를 문서화할 때는 comprehensive-docs 스킬의
5단계 프로세스를 따른다:
1. 기능 목록 완전 파악
2. 기능별 예제 설계
3. 파일 구조 설계
4. 종합 가이드 작성
5. 옵션 문서화

---

이 스킬의 강점

1. 빠짐없는 커버리지: 전체 스펙을 체계적으로 파악
2. 실행 가능한 예제: 복붙하면 바로 동작하는 코드
3. 재사용 가능한 구조: 다른 프로젝트에 복사해서 사용
4. 팀원 온보딩: 새 팀원이 보고 바로 이해 가능
5. 미래의 나를 위한 기록: 6개월 후에도 이해 가능

---

관련 리소스

Agents

• Documenter (.github/agents/documenter.agent.md) - 이 스킬을 자동 실행하는 전문 agent
• Context7 Docs Agent - 최신 공식 문서 조회

Prompts

• /document-feature (.github/prompts/document-feature.prompt.md) - 빠른 호출용 슬래시 커맨드

Scripts

• create-docs-structure.js (.github/scripts/create-docs-structure.js) - 파일 구조 자동 생성

Other Skills

• context7-docs: 공식 문서 조회
• agent-customization: VS Code Agent 커스터마이제이션

---

버전 히스토리

• v1.1: 자동화 추가 (Documenter Agent, 스크립트, Prompt)
• v1.0: 초기 버전 (GitHub Copilot Hooks 예제 작업 기반)