tech-docs-generator

技術ドキュメント生成ツール

概要

実際のコードベースを分析して、包括的な技術ドキュメントを生成します。プロジェクトのコードから抽出した実例を使って、API リファレンス、アーキテクチャ概要、スタートガイド、コンポーネントのドキュメントを作成します。例を捏造することはありません。

開始時に次のように伝えます：「技術ドキュメント生成スキルを使ってドキュメントを作成します。」

フェーズ 1：コードベースの分析

コードベースをスキャンして、ドキュメント化が必要な内容を特定します。Agent ツールを使って、subagent_type="Explore" を指定した並列サブエージェント（最大 500 個）を起動し、次の項目を分析します。

分析対象	取得する情報
エクスポートされた関数／クラス	公開 API の範囲、シグネチャ、戻り値の型
API ルート／エンドポイント	REST、GraphQL、tRPC の定義とメソッド
設定	環境変数、設定ファイル、機能フラグ
データベーススキーマ	モデル、マイグレーション、リレーションシップ
コンポーネント階層	UI コンポーネントとその props／インターフェース
型定義	インターフェース、型、Zod スキーマ、列挙型
エントリーポイント	CLI コマンド、メインファイル、サーバーのブートストラップ
依存関係	外部パッケージとその役割

分析後に停止し、見つかった内容の概要を提示して、必要なドキュメントの種類を尋ねます。

フェーズ 2：ドキュメントの種類を選択

種類	使用する場面	出力先	一般的なサイズ
API リファレンス	エンドポイントや公開関数を文書化する場合	docs/api-reference.md	200～1000 行
アーキテクチャ概要	システム設計とデータフローを説明する場合	docs/architecture.md	100～300 行
スタートガイド	新しい開発者のオンボーディング	docs/getting-started.md	50～150 行
コンポーネントドキュメント	UI コンポーネントを文書化する場合	docs/components/[name].md	50～200 行
コントリビューションガイド	コントリビューションの方法を説明する場合	docs/contributing.md	50～100 行
設定ガイド	設定オプションを文書化する場合	docs/configuration.md	50～200 行
マイグレーションガイド	バージョンアップを文書化する場合	docs/migration/v[X]-to-v[Y].md	50～150 行

指定がない場合は、必要な種類をユーザーに尋ねます。複数の種類が指定された場合は、ドキュメントの種類ごとに 1 つずつ、Agent ツールで並列サブエージェントを起動します。

フェーズ 3：ドキュメントの生成

次の情報を添えて、doc-generator エージェントを起動します。

• フェーズ 1 で得られたファイル分析の結果
• フェーズ 2 で選択したドキュメントの種類
• 既存のドキュメント（置き換えずに更新）
• メモリファイルにあるプロジェクトのコンテキスト

生成後に停止し、保存前に各セクションをレビュー用に提示します。

ドキュメント形式の標準

API リファレンスの形式：

## `functionName(param1, param2)`

Description of what this function does.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| param1 | `string` | Yes | What it does |
| param2 | `Options` | No | Configuration options |

**Returns:** `Promise<Result>`

**Example:**
```typescript
const result = await functionName('value', { option: true });

スローする例外： param1 が空の場合は ValidationError

**Architecture Overview format:**

```markdown
## System Architecture

### Overview
[High-level description with ASCII diagram]

### Components
| Component | Responsibility | Key Files |
|-----------|---------------|-----------|

### Data Flow
[How data moves through the system — request lifecycle]

### Key Decisions
| Decision | Rationale | Alternatives Considered |
|----------|-----------|------------------------|

スタートガイドの形式：

## Prerequisites
[Required tools, versions, accounts]

## Installation
[Step-by-step with copy-pasteable commands]

## Configuration
[Required env vars and config]

## First Run
[How to start the app and verify it works]

## Next Steps
[Links to deeper documentation]

フェーズ 4：レビューと保存

ドキュメントをセクションごとに提示します。

1. 各セクションの後に「これはコードを正確に説明していますか？」と尋ねます。
2. 実際のコードと照合して、正確性を確認します。
3. コードベースの実例を含めます。例を捏造してはいけません。
4. 承認後、docs/ ディレクトリに保存します。
5. 次のメッセージでコミットします：docs(<scope>): add/update <doc-type>

正確性の検証チェックリスト

チェック項目	検証方法
関数シグネチャがコードと一致している	ソースファイルを読む
例が実際に動作する	コードパスをたどる
設定オプションが最新である	実際の設定ファイルを確認する
記載された依存関係がインストールされている	package.json / requirements を確認する
参照先のファイルパスが存在する	ファイルを glob で検索する

アンチパターン／よくある間違い

間違い	問題である理由	代わりにすべきこと
コード例をでっち上げる	読者がコピーして実行し、エラーになります	コードベースから実際の例を抜き出します
内部／非公開 API をドキュメント化する	実装との結合を生みます	公開／エクスポートされている範囲のみをドキュメント化します
ソースコードと重複するドキュメントを書く	すぐに古くなります	実装ではなく動作を説明します
巨大で一枚岩のドキュメントファイル	ナビゲーションやメンテナンスが困難です	関心事ごと（API、アーキテクチャ、設定）に分割します
目指しているだけの動作をドキュメント化する	現在の機能についてユーザーに誤解を与えます	現時点で実際に動作する内容をドキュメント化します
分析フェーズを省略する	重要な API を見落としたり、シグネチャを誤ったりします	必ず最初にコードを分析します
例がコンパイル／実行できるか確認しない	壊れたドキュメントは、ドキュメントがないよりも悪い状態です	すべてのコード例をテストします

不適切な正当化を防ぐルール

• 実際のコードを分析する前にドキュメントを生成してはなりません
• 例をでっち上げてはなりません — すべてのコードスニペットは、コードベースから取得するか、コードベースと照合して検証する必要があります
• 明示的に依頼されない限り、非公開／内部 API をドキュメント化してはなりません
• レビューフェーズを省略してはなりません — 各セクションをユーザーに提示し、確認を受けてください
• 他のドキュメントですでに説明されている情報を重複して記載してはなりません — 代わりに参照してください

統合ポイント

スキル	関係
prd-generation	上流：PRD でドキュメント化が必要な内容を定義します
self-learning	並行：どちらもコードベースを分析します。self-learning は、ここで使用するメモリファイルを作成します
api-design	上流：API 設計仕様が API リファレンスドキュメントの情報源になります
spec-writing	並行：仕様書は動作を定義し、ドキュメントは使用方法を説明します
reverse-engineering-specs	上流：リバースエンジニアリングで作成した仕様書が、動作の理解に役立ちます
code-review	下流：レビュアーが、コード変更とあわせてドキュメントが更新されたか確認します

検証ゲート

ドキュメントが完成したと判断する前に：

1. すべての公開 API が正しいシグネチャでドキュメント化されていることを確認します
2. コード例が実際に動作することを確認します（でっち上げではないこと）
3. 相互参照が既存のコンテンツにリンクしていることを確認します
4. ドキュメントが現在のコードの状態と一致していることを確認します
5. 各セクションについてユーザーの承認を得ていることを確認します
6. 記載されているコマンドを実行し、動作することを確認します

具体例：API リファレンスの項目

次のソースコードがある場合：

export async function createUser(data: CreateUserInput): Promise<User> {
  // validates, hashes password, inserts into DB
}

次のドキュメントを生成します：

## `createUser(data)`

Create a new user account with the provided details.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| data | `CreateUserInput` | Yes | User registration data |

**`CreateUserInput` shape:**
| Field | Type | Required | Constraints |
|-------|------|----------|-------------|
| email | `string` | Yes | Valid email format |
| password | `string` | Yes | Minimum 8 characters |
| name | `string` | Yes | 1-100 characters |

**Returns:** `Promise<User>` — the created user object (password excluded)

**Throws:**
- `ValidationError` — if input fails validation
- `ConflictError` — if email already exists

スキルの種類

柔軟 — まず分析する原則と正確性の検証を維持しながら、プロジェクトのニーズに合わせてドキュメントの詳しさや形式を調整します。