ドキュメント作成に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スキルを理解する

ドキュメントスキルとは？

Claude Codeスキルは、Claude Codeのドキュメント機能を拡張するカスタムの再利用可能なAIワークフローです。これらは、次のようなインテリジェントなドキュメント監査人として考えてください。

ドキュメントリポジトリ全体を読み込み、コンテキストを理解する
仕様と実装およびガイドを相互参照する
欠落しているセクション、不明瞭な記述、不整合を特定する
ファイル場所と行番号とともに具体的な改善を提案する
修正をファイルに直接適用し、変更を検証する

構文をチェックする従来のリンターとは異なり、スキルはClaudeの推論を活用して、曖昧な説明、欠落しているエラーのドキュメント、一貫性のない例など、意味上の問題を理解します。

スキルの仕組み

スキルはいくつかのメカニズムを通じて機能します。

1. ユーザー呼び出し可能なコマンド

# スラッシュコマンドでスキルを実行する
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples

2. 許可されたツール

スキルは使用できるツールを指定します。

Bash: 検証コマンドを実行する
Read, Write, Edit: ドキュメントファイルを管理する
Glob, Grep: ドキュメント全体を検索する
WebFetch: 外部参照を取得する
Task: 複雑なレビューのためにサブタスクを生成する

3. プランニングファイル

スキルは、レビューの進捗状況、特定された問題、適用された修正を追跡するためにMarkdownファイルを使用して状態を維持します。

なぜスキルはドキュメントレビューに優れているのか

従来のドキュメントレビューは手作業で一貫性がありませんでした。スキルはインテリジェンスと規模をもたらします。

全体的な理解: すべてのファイルをレビューし、ファイル間のパターンを把握します。
一貫した標準: すべてのファイルに同じ品質基準を適用します。
文脈に応じた提案: 何かが間違っているだけでなく、なぜ間違っているのかを理解します。
自動化: ドキュメントの進化に合わせて継続的にレビューできます。
速度: 手動レビューの何時間分もの作業を、数分で何百ページもの分析を行います。

コアドキュメントレビュー機能

1. 完全性分析

プロンプト: 「APIドキュメントの完全性を監査してください。各エンドポイントについて、パラメータ、リクエスト例、すべてのエラーレスポンス、レート制限をチェックしてください。」 Claudeが生成する内容:

POST /usersエンドポイントから欠落:
- [ ] リクエストボディパラメータの説明
- [ ] エラーレスポンスのドキュメント (400, 401, 409)
- [ ] レート制限情報
- [ ] セキュリティ/認証要件

2. 一貫性検出

プロンプト: 「/docs/の用語の一貫性をレビューしてください。異なる意味で複数回出現する用語にフラグを立ててください。」 Claudeが特定する内容:

一貫性のない用語が見つかりました:
- "API key" 対 "access token" 対 "auth token" (いずれか1つを使用)
- "endpoint" 対 "route" 対 "method" (いずれか1つを使用)
- "user object" 対 "user resource" (いずれか1つを使用)

3. 相互参照検証

プロンプト: 「/api/openapi.yamlのOpenAPI仕様と/docs/api/のドキュメントを比較してください。コードに文書化されていないエンドポイント、または文書化されているがコードにないエンドポイントにフラグを立ててください。」 Claudeが検出する内容:

不一致が見つかりました:
- POST /api/webhooks は文書化されているが openapi.yaml にない
- PATCH /api/users はコードにあるがドキュメントにない
- レスポンススキーマは変更されているが、例が更新されていない

4. 明瞭性評価

プロンプト: 「明瞭性をレビューしてください。曖昧な説明、未定義の用語、不明瞭な指示にフラグを立ててください。」 Claudeが特定する内容:

明瞭性の問題:
- 45行目: 「configを適切な値に設定する」 - どのような値か？
- 120行目: 「user object」がスキーマ定義なしで使用されている
- 200行目: 「必須フィールド」 - どれか？

5. 例の検証

プロンプト: 「すべてのコード例をレビューしてください。現在のAPIスキーマに対してテストし、壊れているか古くなった例にフラグを立ててください。」 Claudeが更新する内容:

更新された例:
- curlの例: レスポンス形式が変更されたためペイロードを更新
- Pythonの例: 非推奨のパラメータを使用していたため修正
- JavaScriptの例: エラー処理が欠けていたため追加

ドキュメントスキルの構成

ディレクトリ構造

ドキュメントスキルは、.claude/skills/内に次のレイアウトで配置されます。

.claude/
├── skills/
│   ├── docs-completeness/
│   │   ├── SKILL.md              # スキルマニフェスト
│   │   ├── planning.md           # レビューの進捗
│   │   └── criteria.md           # 品質チェックリスト
│   ├── api-validation/
│   │   ├── SKILL.md
│   │   └── schemas/              # APIスキーマ
│   └── consistency-check/
│       └── SKILL.md
└── skills.md                     # すべてのスキルのインデックス

SKILL.md マニフェスト

すべてのドキュメントスキルはYAMLフロントマターから始まります。

---
name: docs-completeness
version: "1.0.0"
description: ドキュメントの完全性と明確性をレビューします
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
  - Edit
hooks:
  SessionStart:
    - matcher: command
      command: "echo '[Docs Review] ドキュメント監査を開始します...'"
  Stop:
    - matcher: command
      command: "echo '[Docs Review] 監査完了。上記の結果を確認してください。'"
---

# ドキュメント完全性スキル

技術ドキュメントの完全性と明確性をレビューします。

## 使用方法

```bash
/docs-completeness                # リポジトリ全体の監査
/docs-completeness --api-only    # APIドキュメントのみ
/docs-completeness --section api/endpoints.md  # 特定のファイル

Claudeへの指示

呼び出された際:

スコープ検出 → ターゲットファイルまたはリポジトリ全体を決定
完全性分析 → チェックリストに対して各セクションをチェック
問題収集 → 場所とともにすべての問題を収集
優先順位付け → 影響度別にソート（欠落 vs. 不明確 vs. 不整合）
レポート生成 → 構造化された結果を出力
修正提案 → 具体的な改善案を提示
検証 → 適用前に修正を検証

最初のドキュメントスキルを作成する

実践してみましょう。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: APIドキュメントの完全性をレビューします
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Edit
---

# APIドキュメントレビュー スキル

APIドキュメントの完全性、明確性、正確性を監査します。

## レビュー基準

各エンドポイントには以下が必要です:

**基本情報**
* エンドポイントの機能に関する明確な説明
* HTTPメソッドとパス
* 認証要件

**リクエストドキュメント**
* 型と説明を含むすべてのパスパラメータ
* デフォルト値と制約を含むすべてのクエリパラメータ
* リクエストボディのスキーマ (POST/PUT/PATCH用)
* Content-Typeヘッダーの要件
* リクエスト例 (curlまたは言語固有)

**レスポンスドキュメント**
* スキーマと例を含む成功レスポンス (200/201)
* 例を含むすべてのエラーレスポンス (400, 401, 403, 404, 409, 429, 500)
* レート制限情報
* レスポンスヘッダー (関連する場合)

**追加**
* 関連するエンドポイントまたはガイド
* 該当する場合はバージョン履歴
* 非推奨の警告 (非推奨の場合)

## 指示

呼び出された際:

1. **/docs/api/にあるエンドポイントファイルをスキャン**します
2. レビュー基準に対して**各エンドポイントをチェック**します
3. 特定のファイル/行参照とともに**欠落している項目をログに記録**します
4. **明確性の問題** (曖昧な説明、未定義の用語) を特定します
5. **一貫性の問題** (用語のずれ、形式の違い) にフラグを立てます
6. 必要な修正の**チェックリストを生成**します
7. 例とともに**修正を適用するかどうかを提案**します

レポート形式:

ENDPOINT: POST /api/users File: docs/api/users.md Status: 65% Complete

Missing:

[ ] エラーレスポンスのドキュメント (400, 401, 409)
[ ] レート制限情報
[ ] リクエストボディのスキーマ定義

Issues:

45行目: 「user object」未定義 - スキーマへのリンクを追加
60行目: 例が古い - レスポンス形式が変更された

Fixes available: Yes (ask to apply)

ステップ3: スキルを登録する

.claude/skills.mdに追加します。

# 利用可能なドキュメントスキル

## APIドキュメント

### /api-docs-review
標準基準に対してAPIドキュメントの完全性を監査します。
- **バージョン**: 1.0.0
- **使用方法**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **使用時期**: APIリリース前、コード変更後
- **時間**: 中規模APIで5〜10分

ステップ4: スキルをテストする

# 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: ドキュメントチェック

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: Apidog CLIをインストール
        run: npm install -g apidog-cli

      - name: OpenAPI仕様を検証
        run: |
          apidog lint api/openapi.yaml
          apidog check-completeness api/openapi.yaml --min-score 85

      - name: リンク切れをチェック
        run: |
          npm install -g markdown-link-check
          find docs -name "*.md" -exec markdown-link-check {} \;

      - name: 例が有効であることを確認
        run: |
          # curlの例が機能するかテスト
          bash scripts/test-curl-examples.sh

      - name: 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: '❌ ドキュメントの検証に失敗しました。ワークフローログを確認してください。'
            })

現実世界のシナリオ: APIドキュメントの完全性

実際のAPIドキュメントセットを完全性のために監査し、改善を適用しましょう。

シナリオ

6ヶ月前のREST APIドキュメントがあり、部分的に完了していますが、エラーのドキュメントが欠落しており、不明瞭な箇所があり、古い例が含まれています。

監査

Claudeへのプロンプト: 「/docs/api/のドキュメントを監査してください。各エンドポイントについて、説明、リクエストパラメータ、レスポンス例、およびすべてのエラーレスポンスをチェックしてください。影響度で修正の優先順位を付けてください。」

監査結果
=============

CRITICAL (エラーのドキュメントが欠落):
├── POST /api/users - 400, 401, 409エラーレスポンスが欠落
├── POST /api/auth/login - 429 (レート制限) レスポンスが欠落
└── DELETE /api/resources/{id} - 403 (アクセス禁止) レスポンスが欠落

HIGH (明確性の問題):
├── users.md:45 - 「user object」が未定義
├── auth.md:60 - 「expirationを適切な値に設定」 - 曖昧すぎる
└── resources.md:30 - ページネーションカーソル形式の説明が欠落

MEDIUM (古い例):
├── products.md:120 - cURLの例が古い形式を返す
├── orders.md:80 - Python SDKの例が非推奨のパラメータを使用
└── webhooks.md:60 - Node.jsの例でエラー処理が欠落

一貫性:
├── 「API key」対「access token」- 5箇所で不整合
├── リクエストボディ形式 - エンドポイント間で3つの異なるスタイル
└── エラーレスポンススキーマ - 1つではなく2つのバリエーション

優先順位の高い修正: 合計15件
推定作業量: 手作業で2〜3時間、Claude Codeを使用すれば15分

改善点

修正を体系的に適用する: Before - POST /api/users (不完全):

## ユーザー作成

POST /api/users

新しいユーザーを作成します。

**パラメータ:**
- name: ユーザー名
- email: ユーザーのメールアドレス

**レスポンス:**
```json
{
  "id": "usr_123",
  "name": "Alice",
  "email": "alice@example.com"
}

After - 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": "無効なメール形式です",
  "field": "email",
  "request_id": "req_xyz789"
}

401 Unauthorized - APIキーの欠落/無効

{
  "error": "unauthorized",
  "message": "無効なAPIキーです",
  "request_id": "req_xyz789"
}

409 Conflict - メールアドレスはすでに存在します

{
  "error": "conflict",
  "message": "このメールアドレスを持つユーザーはすでに存在します",
  "request_id": "req_xyz789"
}

429 Too Many Requests - レート制限

{
  "error": "rate_limited",
  "message": "リクエストが多すぎます。60秒後に再試行してください。",
  "retry_after": 60,
  "request_id": "req_xyz789"
}

レート制限

APIキーあたり1分間に100リクエスト。詳細はレート制限を参照してください。


**適用された改善:**
- 認証要件を追加
- 制約付きのすべてのパラメータを文書化
- 完全な成功レスポンスとすべてのエラーレスポンス
- 実稼働対応のcURL例
- レート制限情報
- 一貫したフォーマット

ClaudeとApidogを統合して優れたAPIドキュメントを作成する

💡 プロのヒント: Claudeを活用して物語形式のドキュメントを洞察力豊かにレビューし、ApidogでAPI仕様が堅牢であることを保証し、実用的な例でギャップを自動的に埋めましょう。 Claudeへの提案プロンプト:「/docs/api/の全体的な明確さとエンゲージメントを調べてください。次に、/api/openapi.yamlファイルの完全性をApidogを使用して相互チェックしてください。矛盾点や欠落している要素があれば強調表示し、先に進む前に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は...を意味します」

明確性を優先する

能動態で書き、スキャンしやすいように構成します。

❌ Before: "The request is submitted via POST. The response will contain the user."
✅ After: "Submit a POST request to create a user. The API returns the new user."

常に例を含める

抽象的な概念には根拠が必要です。すべての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