Blog

Claude Code Skills 활용법: 문서 작성 가이드

Herve Kom

22 January 2026

Claude Code Skills 활용법: 문서 작성 가이드

불완전하고 일관성 없으며 오래된 문서를 물려받은 적이 있다면 이 문제를 아실 것입니다. 팀은 좋은 의도로 문서를 만들지만, 철저한 검토 없이는 명확성이 저해됩니다. API 매개변수는 문서화되지 않고, 오류 응답에는 지침이 부족하며, 예시는 소리 없이 깨지고, 용어는 파일마다 달라집니다.

💡
기술 문서 작업이 더디게 느껴지시나요? Claude Code와 Apidog를 결합하여 AI 기반의 산문 검토와 시각적 API 유효성 검사를 통해 완전한 문서 커버리지를 확보하세요. 두 가지 모두 무료로 사용해 보세요: claude.ai 및 apidog.com. 더 스마트하게 문서화하세요.

Claude Code Skills는 이 문제를 체계적으로 해결합니다. 이 AI 기반 워크플로우는 전체 문서 저장소를 검토하고, 누락된 부분과 불일치를 식별하며, 수정 사항을 직접 적용합니다. 검토할 내용을 설명하면 Claude는 터미널에서 구조화된 감사를 생성하고, 개선 사항을 적용하며, 완전성을 검증합니다.

기술 문서는 API 사양, 사용자 가이드, 배포 가이드 및 릴리스 노트를 포괄합니다. Claude Code는 이 모든 것의 검토를 자동화합니다. 특히 API 문서의 경우, Apidog와 결합하여 시각적 유효성 검사 및 완전성 점수 매기기를 수행할 수 있습니다.

문서화를 위한 Claude Code Skills 이해

문서화 스킬이란 무엇인가요?

Claude Code Skills는 Claude Code의 문서화 기능을 확장하는 맞춤형 재사용 가능한 AI 워크플로우입니다. 이들을 다음과 같은 기능을 수행할 수 있는 지능형 문서 감사관으로 생각할 수 있습니다:

구문을 확인하는 기존 린터와 달리, 스킬은 Claude의 추론을 활용하여 모호한 설명, 누락된 오류 문서화, 일관성 없는 예시와 같은 의미론적 문제를 이해합니다.

스킬 작동 방식

스킬은 여러 메커니즘을 통해 작동합니다:

1. 사용자 호출 가능 명령어

# Run a skill with a slash command
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples

2. 허용된 도구

스킬은 사용할 수 있는 도구를 지정합니다:

3. 계획 파일

스킬은 마크다운 파일을 사용하여 검토 진행 상황, 식별된 문제 및 적용된 수정 사항을 추적하여 상태를 유지합니다.

스킬이 문서 검토에 뛰어난 이유

기존의 문서 검토는 수동적이고 일관성이 없습니다. 스킬은 지능과 규모를 제공합니다:

핵심 문서 검토 기능

1. 완전성 분석

프롬프트: "API 문서의 완전성을 감사합니다. 각 엔드포인트에 대해 다음을 확인하세요: 매개변수, 요청 예시, 모든 오류 응답 및 속도 제한."

Claude 생성:

Missing from POST /users endpoint:
- [ ] Request body parameter descriptions
- [ ] Error response documentation (400, 401, 409)
- [ ] Rate limiting information
- [ ] Security/authentication requirements

2. 일관성 감지

프롬프트: "/docs/에서 용어 일관성을 검토합니다. 다른 의미로 여러 번 나타나는 용어에 플래그를 지정합니다."

Claude 식별:

Inconsistent terminology found:
- "API key" vs "access token" vs "auth token" (use one)
- "endpoint" vs "route" vs "method" (use one)
- "user object" vs "user resource" (use one)

3. 교차 참조 유효성 검사

프롬프트: "/api/openapi.yaml의 OpenAPI 사양을 /docs/api/의 문서와 비교합니다. 코드에 문서화되지 않았거나 문서화되었지만 코드에 없는 모든 엔드포인트에 플래그를 지정합니다."

Claude 감지:

Discrepancies found:
- POST /api/webhooks documented but not in openapi.yaml
- PATCH /api/users exists in code but missing from docs
- Response schema changed but example not updated

4. 명확성 평가

프롬프트: "명확성을 검토합니다. 모호한 설명, 정의되지 않은 용어 및 모호한 지침에 플래그를 지정합니다."

Claude 식별:

Clarity issues:
- Line 45: "Set config to appropriate values" - what values?
- Line 120: "user object" used without schema definition
- Line 200: "required fields" - which ones?

5. 예시 유효성 검사

프롬프트: "모든 코드 예시를 검토합니다. 현재 API 스키마에 대해 테스트합니다. 깨지거나 오래된 예시에 플래그를 지정합니다."

Claude 업데이트:

Updated examples:
- curl example: Response format changed, updated payload
- Python example: Using deprecated parameter, fixed
- JavaScript example: Missing error handling, added

문서화 스킬 해부

디렉토리 구조

문서화 스킬은 .claude/skills/에 다음 레이아웃으로 존재합니다:

.claude/
├── skills/
│   ├── docs-completeness/
│   │   ├── SKILL.md              # Skill manifest
│   │   ├── planning.md           # Review progress
│   │   └── criteria.md           # Quality checklist
│   ├── api-validation/
│   │   ├── SKILL.md
│   │   └── schemas/              # API schemas
│   └── consistency-check/
│       └── SKILL.md
└── skills.md                     # Index of all skills

SKILL.md 매니페스트

모든 문서화 스킬은 YAML 프론트매터로 시작합니다:

---
name: docs-completeness
version: "1.0.0"
description: Review documentation for completeness and clarity
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
  - Edit
hooks:
  SessionStart:
    - matcher: command
      command: "echo '[Docs Review] Starting documentation audit...'"
  Stop:
    - matcher: command
      command: "echo '[Docs Review] Audit complete. Review findings above.'"
---

# Documentation Completeness Skill

Reviews technical documentation for completeness and clarity.

## Usage

```bash
/docs-completeness                # Full repository audit
/docs-completeness --api-only    # API docs only
/docs-completeness --section api/endpoints.md  # Specific file

Claude를 위한 지침

호출 시:

  1. 범위 감지 → 대상 파일 또는 전체 저장소 결정
  2. 완전성 분석 → 각 섹션을 체크리스트와 대조하여 확인
  3. 문제 수집 → 위치가 포함된 모든 문제 수집
  4. 우선순위 지정 → 영향도(누락 vs. 불분명 vs. 불일치)에 따라 정렬
  5. 보고서 생성 → 구조화된 결과 출력
  6. 수정 제안 → 구체적인 개선 사항 제공
  7. 유효성 검사 → 적용 전 수정 사항 확인

첫 번째 문서화 스킬 만들기

실습에 뛰어들어 보세요: API 문서의 누락된 부분을 감사하여 포괄적이고 개발 준비가 완료되었는지 확인하는 유용한 도구를 만들 것입니다. 이를 개인 문서 관리 도우미라고 생각하세요.

1단계: 스킬 폴더 설정

간단한 명령으로 구조를 부트스트랩합니다. Claude의 스킬은 쉽게 찾을 수 있도록 전용 공간에 있습니다.

Bash

mkdir -p .claude/skills/api-docs-review

2단계: 스킬 매니페스트 작성

.claude/skills/api-docs-review/SKILL.md 생성:

---
name: api-docs-review
version: "1.0.0"
description: Review API documentation for completeness
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Edit
---

# API Documentation Review Skill

Audits API documentation for completeness, clarity, and accuracy.

## Review Criteria

Each endpoint must have:

**Basic Information**
* Clear description of what the endpoint does
* HTTP method and path
* Authentication requirements

**Request Documentation**
* All path parameters with types and descriptions
* All query parameters with defaults and constraints
* Request body schema (for POST/PUT/PATCH)
* Content-Type header requirements
* Example request (curl or language-specific)

**Response Documentation**
* Success response (200/201) with schema and example
* All error responses (400, 401, 403, 404, 409, 429, 500) with examples
* Rate limiting information
* Response headers (if relevant)

**Additional**
* Related endpoints or guides
* Version history if applicable
* Deprecation warnings (if deprecated)

## Instructions

When invoked:

1. **Scan endpoint files** in /docs/api/
2. **Check each endpoint** against review criteria
3. **Log missing items** with specific file/line references
4. **Identify clarity issues** (vague descriptions, undefined terms)
5. **Flag consistency issues** (terminology drift, format differences)
6. **Generate checklist** of fixes needed
7. **Offer to apply fixes** with examples

Report format:

엔드포인트: POST /api/users 파일: docs/api/users.md 상태: 65% 완료

누락:

문제:

수정 가능: 예 (적용 요청)

3단계: 스킬 등록

.claude/skills.md에 추가:

# 사용 가능한 문서화 스킬

## API 문서

### /api-docs-review
표준 기준에 따라 API 문서의 완전성을 감사합니다.
- **버전**: 1.0.0
- **사용법**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **사용 시점**: API 릴리스 전, 코드 변경 후
- **시간**: 중간 규모 API의 경우 5-10분

4단계: 스킬 테스트

# In Claude Code
/api-docs-review

이제 Claude가 API 문서를 체계적으로 감사할 것입니다.

고급 문서화 패턴

패턴 1: 버전별 문서 추적

스킬은 여러 버전에서 문서 품질을 추적할 수 있습니다:

## 버전 기록

### v2.0.0 [2026-01-22]
완전성: 95% ✅
- 모든 엔드포인트 문서화됨
- 오류 응답 완료
- 예시 업데이트됨
- 사용 중단된 /v1 엔드포인트 표시됨

### v1.0.0 [2025-12-01]
완전성: 70%
- 누락된 오류 문서
- 오래된 예시
- 사용 중단 경고 없음

Claude는 시간이 지남에 따른 개선 사항을 감지합니다.

패턴 2: 코드에 대한 API 사양 유효성 검사

스킬은 OpenAPI 사양이 구현과 일치하는지 유효성을 검사할 수 있습니다:

## 사양 유효성 검사

/api/openapi.yaml을 코드와 비교:

1. **모든 경로에 대한 구현 스캔**
2. **각 경로에 대한 OpenAPI 사양 확인**
3. **누락된 엔드포인트 플래그 지정**
4. **매개변수가 구현과 일치하는지 확인**
5. **현재 스키마와 일치하도록 예시 업데이트**

결과: 사양이 코드와 100% 동기화됨

CI/CD로 자동화

문서 유효성 검사 파이프라인

모든 문서 업데이트에 대한 자동 검사를 설정하세요:

# .github/workflows/docs-check.yml
name: Documentation Check

on:
  push:
    paths:
      - 'docs/**'
      - 'api/openapi.yaml'
  pull_request:
    paths:
      - 'docs/**'
      - 'api/openapi.yaml'

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install Apidog CLI
        run: npm install -g apidog-cli

      - name: Validate OpenAPI Spec
        run: |
          apidog lint api/openapi.yaml
          apidog check-completeness api/openapi.yaml --min-score 85

      - name: Check for broken links
        run: |
          npm install -g markdown-link-check
          find docs -name "*.md" -exec markdown-link-check {} \;

      - name: Verify examples are valid
        run: |
          # Test curl examples work
          bash scripts/test-curl-examples.sh

      - name: Comment on PR
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '❌ Documentation validation failed. Review the workflow logs.'
            })

실제 시나리오: API 문서 완전성

현실적인 API 문서 세트의 완전성을 감사하고 개선 사항을 적용해 보겠습니다.

시나리오

6개월 된 REST API 문서가 있습니다. 부분적으로 완성되었지만 오류 문서가 누락되어 있고, 일부는 불분명하며, 오래된 예시가 포함되어 있습니다.

감사

Claude에게 프롬프트: "/docs/api/의 문서를 감사합니다. 각 엔드포인트에 대해 다음을 확인하세요: 설명, 요청 매개변수, 응답 예시 및 모든 오류 응답. 영향도에 따라 수정 사항의 우선순위를 지정하세요."

AUDIT RESULTS
=============

CRITICAL (Missing error docs):
├── POST /api/users - Missing 400, 401, 409 error responses
├── POST /api/auth/login - Missing 429 (rate limit) response
└── DELETE /api/resources/{id} - Missing 403 (forbidden) response

HIGH (Clarity issues):
├── users.md:45 - "user object" undefined
├── auth.md:60 - "Set expiration to appropriate value" - too vague
└── resources.md:30 - Missing description of pagination cursor format

MEDIUM (Outdated examples):
├── products.md:120 - cURL example returns old format
├── orders.md:80 - Python SDK example uses deprecated parameter
└── webhooks.md:60 - Node.js example missing error handling

CONSISTENCY:
├── "API key" vs "access token" - 5 instances inconsistent
├── Request body format - 3 different styles across endpoints
└── Error response schema - 2 variations instead of 1

Priority fixes: 15 total
Estimated effort: 2-3 hours manual, 15 minutes with Claude Code

개선 사항

수정 사항 체계적으로 적용:

이전 - POST /api/users (불완전):

## 사용자 생성

POST /api/users

새로운 사용자를 생성합니다.

**매개변수:**
- name: 사용자의 이름
- email: 사용자의 이메일

**응답:**
```json
{
  "id": "usr_123",
  "name": "Alice",
  "email": "alice@example.com"
}


**이후 - POST /api/users (완료):**
```markdown
## 사용자 생성

`POST /api/users`

제공된 세부 정보로 새 사용자 계정을 생성합니다. 이메일은 고유해야 합니다.

### 인증

`Authorization` 헤더에 API 키가 필요합니다: `Bearer YOUR_API_KEY`

### 요청 매개변수

| 매개변수 | 유형 | 필수 | 설명 |
|-----------|------|----------|-------------|
| `name` | string | 예 | 전체 이름 (2-100자) |
| `email` | string | 예 | 유효한 이메일 (고유해야 함) |
| `role` | string | 아니요 | 역할: `admin`, `developer`, `viewer`. 기본값: `viewer` |

### 요청 예시

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Smith",
    "email": "alice@example.com",
    "role": "developer"
  }'

응답 (201 생성됨)

{
  "id": "usr_abc123",
  "name": "Alice Smith",
  "email": "alice@example.com",
  "role": "developer",
  "created_at": "2026-01-22T10:30:00Z"
}

오류 응답

400 Bad Request - 잘못된 입력

{
  "error": "validation_error",
  "message": "Invalid email format",
  "field": "email",
  "request_id": "req_xyz789"
}

401 Unauthorized - 누락/잘못된 API 키

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "request_id": "req_xyz789"
}

409 Conflict - 이메일이 이미 존재함

{
  "error": "conflict",
  "message": "User with this email already exists",
  "request_id": "req_xyz789"
}

429 Too Many Requests - 속도 제한됨

{
  "error": "rate_limited",
  "message": "Too many requests. Try again in 60 seconds.",
  "retry_after": 60,
  "request_id": "req_xyz789"
}

속도 제한

API 키당 분당 100회 요청. 속도 제한 참조.


**적용된 개선 사항:**
- 인증 요구 사항 추가됨
- 제약 조건이 있는 모든 매개변수 문서화됨
- 완전한 성공 + 모든 오류 응답
- 운영 환경에 적합한 cURL 예시
- 속도 제한 정보
- 일관된 형식

탁월한 API 문서를 위한 Claude와 Apidog 통합

💡 전문가 팁: Claude를 활용하여 서술형 문서에 대한 통찰력 있는 검토를 수행하고, Apidog는 API 사양이 견고하게 유지되고 실용적인 예시로 누락된 부분을 자동으로 채우도록 보장합니다.

Claude를 위한 제안 프롬프트:"/docs/api/의 전반적인 명확성과 가독성을 검토합니다. 다음으로 Apidog를 사용하여 /api/openapi.yaml 파일의 완전성을 교차 확인합니다. 불일치하거나 누락된 요소가 있으면 강조 표시하여 진행하기 전에 Apidog에서 직접 해결할 수 있도록 합니다."

Bash

# 1단계: Claude를 통한 초기 산문 검토
> /docs-completeness  # 더 명확한 언어와 구조를 위한 제안 출력

# 2단계: Apidog에서의 API 사양 유효성 검사
apidog check-completeness api/openapi.yaml  # 불완전한 스키마 또는 누락된 응답과 같은 문제 플래그 지정

# 3단계: Apidog AI로 콘텐츠 자동 생성
# (Apidog UI를 통해: 설정 → AI → 설명, 예시, 요약 자동 생성)

# 4단계: Claude를 통한 최종 일관성 확인
> /consistency-check  # 문서와 사양이 완벽하게 정렬되도록 보장

이것은 Apidog가 구조화된 사양 유효성 검사를 처리하고 Claude Code가 산문 품질을 처리하는 워크플로우를 생성합니다.

문서 검토 모범 사례

청중을 파악하세요

독자에 따라 문서 깊이를 조정하세요:

청중 스타일 예시
개발자 다국어 코드 예시 cURL, Python, JS
DevOps 배포 단계, 구성 Kubernetes YAML 예시
제품 팀 상위 수준 워크플로우, 다이어그램 스크린샷이 포함된 기능 흐름
지원 문제 해결, 일반적인 문제 "오류 429는 ...을 의미합니다."

명확성 우선

능동태로 작성하고, 빠르게 훑어볼 수 있도록 구조화하세요:

❌ 이전: "요청은 POST를 통해 제출됩니다. 응답에는 사용자가 포함됩니다."
✅ 이후: "사용자를 생성하려면 POST 요청을 제출하세요. API는 새 사용자를 반환합니다."

항상 예시 포함

추상적인 개념에는 기반이 필요합니다. 모든 API 엔드포인트에는 다음이 필요합니다:

# ✅ 복사-붙여넣기 준비 완료
curl -X GET https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

흔한 실수

실수 해결책
전문 용어 과부하 처음 사용할 때 용어 정의
오래된 예시 CI/CD에서 테스트
오류 문서 누락 모든 오류 코드 문서화
일관성 없는 형식 템플릿 사용
끊어진 링크 CI/CD에서 확인

결론

Claude Code Skills는 기술 문서 검토를 지루한 수동 프로세스에서 지능적이고 자동화된 워크플로우로 전환합니다. 검토할 내용을 설명하면 Claude는 전체 문서 저장소를 감사하고, 누락된 부분과 불일치를 식별하며, 품질 표준을 유지하면서 수정 사항을 적용합니다.

API 사양 유효성 검사를 위한 Apidog와 결합하면 포괄적인 문서 커버리지를 달성할 수 있습니다.

button

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드