reference-documentation

リファレンスドキュメント

API、設定、システムインターフェースの信頼できる唯一の情報源となる、網羅的で検索しやすく、正確に整理された技術リファレンスドキュメントを作成します。

このスキルを使用する場面

• API リファレンスドキュメント（REST、GraphQL、gRPC）を作成するとき
• すべてのパラメーターを記載した設定ガイドを作成するとき
• データベースやデータモデルのスキーマドキュメントを作成するとき
• すべてのコマンド、フラグ、使用例を記載した CLI リファレンスを作成するとき
• 完全な技術仕様書を作成するとき
• エラーコード、ステータスコード、例外の一覧を文書化するとき
• バージョンアップのための移行ガイドを作成するとき

クイックリファレンス

リソース	目的	読み込むタイミング
references/documentation-patterns.md	API ドキュメントの構成、用語集のパターン、相互参照、バージョン管理されたドキュメント、パラメーターテーブル、設定ガイド	リファレンスドキュメントを構成するとき

---

ワークフローの概要

Phase 1: Inventory    → Catalog all public interfaces, parameters, and constraints
Phase 2: Author       → Draft structured entries with examples and cross-links
Phase 3: Verify       → Validate against implementation and tests
Phase 4: Organize     → Structure for optimal retrieval and searchability
Phase 5: Maintain     → Version tracking, deprecation, and update cadence

---

フェーズ 1：項目の洗い出し

何かを書く前に、ドキュメント化が必要なものをすべて列挙します。

項目洗い出しチェックリスト

• すべての公開 API エンドポイント／メソッド／関数
• すべての設定パラメーターとそのデフォルト値
• すべてのエラーコードと例外の種類
• すべての環境変数
• すべての CLI コマンドとフラグ
• すべてのスキーマフィールドと制約
• すべてのイベントの種類とペイロード
• 削除された機能の非推奨化スケジュール

情報源の優先順位

1. 実装コード（実際の動作）
2. テスト（アサーションで示される期待される動作）
3. 型定義／スキーマ（宣言された契約）
4. 既存のドキュメント（古くなっている可能性があるため、要確認）

---

フェーズ 2：執筆

項目の形式

ドキュメントに記載する各項目は、一貫した形式を使用します。

### methodName

**Type**: `(param1: string, param2?: number) => Promise<Result>`
**Since**: v2.1.0
**Deprecated**: No

**Description**:
Brief explanation of purpose and behavior.

**Parameters**:

| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `param1` | `string` | Yes | — | What this parameter controls |
| `param2` | `number` | No | `10` | What this parameter controls |

**Returns**: `Promise<Result>` — description of return value

**Throws**:
- `ValidationError` — when param1 is empty
- `TimeoutError` — when operation exceeds 30s

**Examples**:

Basic usage:
\`\`\`typescript
const result = await methodName("value");
\`\`\`

With options:
\`\`\`typescript
const result = await methodName("value", 20);
\`\`\`

**See Also**: [relatedMethod](#relatedmethod), [Configuration Guide](#configuration)

執筆ルール

1. 実装ではなく動作を記載する — どのように実装されているかではなく、何をするかを記載します
2. すべてのパラメーターに行を設ける — 明白なものも含め、例外はありません
3. すべての項目に例を付ける — 少なくとも1つの動作するコードサンプルを記載します
4. 制約を明示する — 有効範囲、長さ制限、形式要件を記載します
5. 関連項目を相互参照する — 関連するメソッド、設定、エラーコードへのリンクを記載します

---

フェーズ 3：検証

検証方法

検証対象	方法
メソッドのシグネチャ	ソースコードの型定義と照合します
デフォルト値	ソースコードの初期化処理を確認します
エラー条件	実装とテストのアサーションを確認します
例	実行するか、コードに照らして動作を追跡します
非推奨項目	ソースコード内の非推奨マーカーを確認します

正確性チェックリスト

• すべてのシグネチャが現在の実装と一致している
• すべてのデフォルト値が正しい
• すべてのエラー条件が記載されている
• すべての例が現在のバージョンで動作する
• 削除済みの機能が記載されたままになっていない
• 新機能に記載漏れがない

---

フェーズ 4：整理

ドキュメントの階層

1. Overview          — What this API/system does, quick orientation
2. Quick Reference   — Cheat sheet of common operations with examples
3. Authentication    — How to authenticate (if applicable)
4. Detailed Reference — Complete documentation, grouped logically
5. Error Reference   — All error codes with causes and fixes
6. Glossary          — Terms specific to this system
7. Changelog         — What changed in each version

ナビゲーション補助

• 目次を冒頭に配置し、各項目へのディープリンクを設定します
• 大規模なリファレンスにはアルファベット順の索引を用意します
• 論理的に探しやすいよう、カテゴリごとに分類します
• 見出しや説明に検索キーワードを埋め込みます
• 最近のバージョンで追加または変更された項目にバージョンバッジを付けます

---

フェーズ 5：保守

バージョン管理方針

• 各項目に導入されたバージョンを付記します（**Since**: v2.1.0）
• 非推奨化には移行方法を記載します（**Deprecated**: v3.0 — use newMethod instead）
• リファレンスドキュメントの末尾に変更履歴のセクションを設けます
• 破壊的変更が蓄積した場合は、メジャーバージョンごとにドキュメントを分けます

更新の契機

次の場合は、リファレンスドキュメントを更新する必要があります。

• 公開 API のシグネチャが変更された
• 新しいパラメーター、エンドポイント、またはコマンドが追加された
• デフォルト値や制約が変更された
• 機能が非推奨または削除された
• エラーコードや動作が変更された

---

コンテンツのパターン

パラメータテーブル

パラメータには必ずテーブルを使用してください。インラインリストは使用しないでください。

Name	Type	Required	Default	Description
timeout	number	いいえ	30000	リクエストのタイムアウト（ミリ秒）
retries	number	いいえ	3	再試行回数

ステータスコードテーブル

Code	Name	Description	Resolution
400	Bad Request	入力パラメータが無効です	リクエスト本文がスキーマに適合しているか確認してください
401	Unauthorized	認証トークンがないか、無効です	再認証してから再試行してください
429	Rate Limited	リクエストが多すぎます	間隔を空け、Retry-After ヘッダーの後に再試行してください

設定ブロック

# config.yaml
server:
  port: 3000          # Port to listen on (1024-65535)
  host: "0.0.0.0"     # Bind address
  timeout: 30000      # Request timeout in ms
  max_body_size: "1mb" # Maximum request body size

避けるべきパターン

• 通知なく変更される可能性のある内部／非公開インターフェースを文書化する
• 実際の説明を書く代わりに、「明らか」や「説明不要」とする
• 「型を見れば明らか」という理由でエラーの説明を省略する
• 動作するか確認せずにサンプルをコピー＆ペーストする
• リファレンス項目にチュートリアル形式の説明を混在させる（分けてください）
• ドキュメントを実装に追随させず、1 回以上のリリースにわたって放置する