code-documenter

コードドキュメント作成スキル

コードベースを分析し、プロジェクトの種類や読者のニーズに合わせた、詳細で包括的なドキュメントを生成するインテリジェントなドキュメントシステムです。

基本理念

ドキュメントは作成者ではなく、読者のためのものです。 構成、詳しさ、内容に関するあらゆる判断を、読者の視点から評価します。

• 読者の理解に役立つか？
• 読者の成功に役立つか？
• 読者の疑問に答えられるか？
• それを含めるだけの価値があるか？

網羅的でありながら、圧倒させない。 重要な内容は徹底的に網羅し、重要でない内容は容赦なく削ります。目指すのは、コードのすべての行を余すところなく説明するドキュメントではなく、完全で正確かつ役立つドキュメントです。

コード成果物としてのドキュメント。 ドキュメントはコードと同じ厳密さで、バージョン管理、テスト、保守を行う必要があります。後回しにするものではなく、欠かせないものです。

このスキルを使う場面

主な用途：

• 大規模な新規作業（エピック、主要機能、新しいアプリ）の完了後
• オープンソースプロジェクトを公開するとき
• ドキュメントがコードと同期しなくなったとき
• より良いドキュメントがオンボーディングに必要なとき
• 新しいプロジェクトを適切に立ち上げるとき

対象外：

• 開発中の機能（安定するまで待ちます）
• コードコメントや docstring（外部向けドキュメントを生成します）
• コードからの API リファレンス生成（その用途には言語固有のツールを使用します）

セッションの流れ

モードの選択

このスキルは、次の 2 つのモードで動作します。

モード	使用する場面	動作
クイックモード	新機能追加後の段階的な更新	自律的かつ迅速に、変更点に集中します
包括モード	新規プロジェクト、大規模な刷新、初回セットアップ	協調的かつ徹底的に進め、全工程で品質を確認します

このスキルは次のように質問します：「クイック更新と包括的なドキュメント作成のどちらにしますか？」

フェーズ 1：マルチエージェントによるプロジェクト分析

このスキルは、プロジェクトを理解するために、専門の分析エージェントを配置します。

Analysis Phase:
├─ Agent 1: Project Structure
│  └─ Scanning file tree, identifying project type, tech stack
├─ Agent 2: Code Surface Analysis
│  └─ Finding APIs, components, commands, exports
├─ Agent 3: Dependency Analysis
│  └─ Reviewing packages, frameworks, key dependencies
├─ Agent 4: Git History Analysis
│  └─ Analyzing commits since last doc update
├─ Agent 5: Existing Documentation Review
│  └─ Reading current docs, assessing state
└─ Synthesis: Generating documentation plan...

クイックモード： 前回の更新以降の変更点に絞って分析します
包括モード： プロジェクト全体を詳細に分析します

各エージェントは、構造化された形式で調査結果を報告します。進行状況はすべて確認できます。

フェーズ 2：ドキュメントの状態評価

このスキルは、コードの状態とドキュメントの状態を比較します。

マニフェスト（.doc-state.json）がある場合：

• 前回実行時のドキュメント状態を読み込みます
• 現在のコードと、最後にドキュメント化した状態を比較します
• 追加、変更、削除された内容を特定します
• ドキュメントの負債を提示します

マニフェストがない場合：

• このプロジェクトを初めてドキュメント化します
• 完了後に新しいマニフェストを作成します

表示される主な指標：

• 健全性スコア： 現在のドキュメントの健全性（0～100）
• カバレッジ： 公開インターフェースのうち、ドキュメント化されている割合
• 鮮度： コードに対するドキュメントの最新度
• 負債： 対応が必要な項目（優先順位付き）

フェーズ 3：読者と範囲の確認

このスキルは次のように質問します。

1. 「このドキュメントを必要としているのは誰ですか？」

   • 開発者のみ
   • ユーザーのみ
   • 開発者とユーザーの両方

2. 「どの程度の詳しさのドキュメントが必要ですか？」

   • 標準： 適切な範囲をカバー（4,000～7,000 語）
   • 詳細： 内部の仕組みまで包括的に説明（8,000～12,000 語）

クイックモード： マニフェストに保存された設定を使用します
包括モード： 明示的に質問し、例を提示します

フェーズ 4：ドキュメントの範囲

このスキルは、ドキュメント化する内容を提案します。

Based on my analysis of your Express + PostgreSQL API:

PUBLIC SURFACE (Always Document)
├─ 12 API endpoints in /routes
├─ Database schema (3 tables)
├─ 14 environment variables
└─ Authentication flow

INTERNAL IMPLEMENTATION (Recommended for Deep)
├─ 6 middleware functions
├─ Error handling patterns
└─ Database migration strategy

INFRASTRUCTURE (Essential for all levels)
├─ Docker setup
├─ CI/CD pipeline
└─ Deployment process

EXCLUDED (Recommend skip)
├─ Test files (obvious from names)
├─ Build scripts (standard tooling)
└─ Internal helpers (<10 lines each)

Adjust these boundaries? [approve/modify]

ドキュメントの生成を始める前に、内容を承認または調整できます。

フェーズ 5：ドキュメント作成計画の提示

このスキルは、完全な計画を提示します。

DOCUMENTATION PLAN

Structure:
└─ /docs
   ├─ developers/
   │  ├─ api.md (API endpoint reference)
   │  ├─ architecture.md (System design + diagrams)
   │  ├─ contributing.md (How to contribute)
   │  ├─ deployment.md (Deploy & operate)
   │  ├─ troubleshooting.md (Common issues)
   │  ├─ examples/ (12 runnable examples)
   │  └─ adr/ (4 architecture decisions)
   ├─ users/
   │  ├─ getting-started.md (Quick start guide)
   │  ├─ features.md (Feature overview)
   │  ├─ troubleshooting.md (User-facing issues)
   │  └─ examples/ (5 user examples)
   ├─ CHANGELOG.md (Documentation change log)
   └─ documentation-map.md (Navigation guide)

Files to update:
- README.md (complete rewrite, progressive disclosure)
- docs/developers/api.md (2 new endpoints, 1 modified)
- docs/CHANGELOG.md (new entry)

Files to create:
- docs/adr/004-caching-strategy.md (new decision)
- docs/developers/examples/pagination.js (new example)

Files to remove:
- docs/developers/legacy-auth.md (endpoint removed)

Estimated scope: ~5,200 words total
Target health score: 92/100

Proceed? [yes/adjust scope/abort]

包括モード： 生成前に計画を確認して承認します
クイックモード： 概要を確認し、計画を見直すか、そのまま進めるかを選択できます

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

包括モード（品質ゲート付き）

このスキルは、レビューのために一時停止しながら、段階的にドキュメントを作成します。

ゲート 1：コアドキュメント（README ＋ はじめに）

• プログレッシブディスクロージャーを取り入れた README を生成します
• はじめにガイドを作成します
• 品質チェック：関心を引き、効果的に導入できていますか？
• レビューして、承認するか変更を依頼します

ゲート 2：リファレンスドキュメント（API／コマンド／コンポーネント）

• リファレンスドキュメントを生成します
• 動作するサンプルを作成します
• 品質チェック：すべて網羅されていますか？サンプルは明確ですか？
• レビューして、承認するか変更を依頼します

ゲート 3：アーキテクチャと意思決定

• Mermaid 図を使ってアーキテクチャを文書化します
• 重要な意思決定について ADR を作成します
• 品質チェック：理由（WHY）が説明されていますか？
• レビューして、承認するか変更を依頼します

ゲート 4：補足ドキュメント

• トラブルシューティングガイドを生成します
• コントリビューションガイドラインを作成します
• ナビゲーション用のドキュメントマップを作成します
• 品質チェック：完全で役に立つ内容ですか？
• レビューして、承認するか変更を依頼します

ゲート 5：仕上げと検証

• サンプル用のテストスクリプトを生成します
• リンク検証スクリプトを作成します
• アクセシビリティチェックを実行します
• 最終的なヘルススコアを計算します
• 最終レビュー

クイックモード（自律実行）

このスキルは、計画を効率的に実行します。

• 変更されたセクションのみを更新します
• 変更されていない箇所の手動編集を保持します
• 必要に応じて新しいコンテンツを生成します
• マニフェストと変更履歴を更新します
• 最終結果を報告します

フェーズ 7：セッションの完了

このスキルは、以下を生成します。

作成／更新されるファイル：

• 計画されたすべてのドキュメントファイル
• .doc-state.json（更新されたマニフェスト）
• docs/CHANGELOG.md（新しいエントリー）
• テストおよび検証スクリプト

ドキュメントの健全性レポート：

DOCUMENTATION HEALTH REPORT

Overall Health Score: 92/100 (↑ from 78)

Component Scores:
├─ Coverage Health: 95/100 (↑ from 82)
│  └─ 97% of public surface documented
├─ Freshness Health: 98/100 (↑ from 65)
│  └─ All docs current as of commit a3f2b1c
├─ Quality Health: 88/100 (↑ from 81)
│  └─ 12 examples, 4 ADRs, troubleshooting complete
└─ Consistency Health: 90/100 (↑ from 84)
   └─ Tone consistent, terminology standardized

Debt Status:
├─ Critical: 0 items (was 2)
├─ Important: 1 item (was 4)
└─ Minor: 3 items (unchanged)

Next session recommendations:
- Document the new webhook system (flagged as potential)
- Add performance troubleshooting section
- Consider hosting docs on GitHub Pages

セッションのメモ：

• 決定事項
• スコープの調整
• 含めた内容／除外した内容とその理由
• 次のステップ

ファイル出力

コアドキュメントの構成

開発者向けプロジェクト：

/docs
├── CHANGELOG.md
├── api.md / commands.md / components.md
├── architecture.md
├── contributing.md
├── deployment.md
├── troubleshooting.md
├── examples/
│   ├── example-1.js
│   ├── example-2.js
│   └── test-examples.sh
├── adr/
│   ├── 001-initial-decisions.md
│   ├── 002-database-choice.md
│   └── ...
└── scripts/
    ├── validate-links.sh
    └── accessibility-check.md

複数の対象読者がいるプロジェクト：

/docs
├── CHANGELOG.md
├── documentation-map.md
├── users/
│   ├── getting-started.md
│   ├── features.md
│   ├── troubleshooting.md
│   └── examples/
│       ├── basic-usage.js
│       └── advanced-usage.js
├── developers/
│   ├── api.md / architecture.md
│   ├── contributing.md
│   ├── deployment.md
│   ├── troubleshooting.md
│   ├── examples/
│   │   ├── integration.js
│   │   ├── extending.js
│   │   └── test-examples.sh
│   └── adr/
│       ├── 001-framework-choice.md
│       └── ...
└── scripts/
    ├── validate-links.sh
    └── accessibility-check.md

ドキュメントマニフェスト（.doc-state.json）

ドキュメントの完全な状態を追跡します。

{
  "version": "1.0",
  "project": {
    "name": "my-api",
    "type": "express-api",
    "lastScanned": "2025-01-10T14:30:00Z",
    "gitCommit": "a3f2b1c"
  },
  "preferences": {
    "audiences": ["developers", "users"],
    "depthLevel": "standard",
    "tone": "professional"
  },
  "healthScore": {
    "overall": 92,
    "components": {
      "coverage": 95,
      "freshness": 98,
      "quality": 88,
      "consistency": 90
    },
    "trend": [78, 85, 92]
  },
  "coverage": {
    "endpoints": { "total": 12, "documented": 12, "changed": 0 },
    "components": { "total": 8, "documented": 8, "changed": 0 },
    "schemas": { "total": 3, "documented": 3, "changed": 0 }
  },
  "debt": {
    "critical": [],
    "important": [
      {
        "item": "Document webhook system",
        "effort": "medium",
        "status": "to-fix"
      }
    ],
    "minor": [
      {
        "item": "Add performance troubleshooting",
        "effort": "low",
        "status": "accepted"
      }
    ]
  },
  "documentationMap": {
    "README.md": {
      "lastUpdated": "2025-01-10T14:30:00Z",
      "covers": ["overview", "quickstart"],
      "wordCount": 850
    },
    "docs/developers/api.md": {
      "lastUpdated": "2025-01-10T14:30:00Z",
      "covers": ["endpoints"],
      "wordCount": 2400
    }
  }
}

コラボレーション時の振る舞い

包括モードの場合

積極的な提案：

• 「Redis を使用しているようですが、その理由を説明する ADR がありません。決定事項を文書化しましょうか？」
• 「エラー処理が高度に作り込まれています。アーキテクチャドキュメントで説明する価値があります。」
• 「認証フローが一般的なものとは異なります。ユーザーから質問が出るはずです。こちらで説明しましょう。」

前提への問いかけ：

• 「『標準的な深さ』とのことですが、エンドポイントが 47 個あります。これは詳細なドキュメントが必要です。」
• 「この『はじめに』ガイドは前提が多すぎます。ユーザーは X を知らないでしょう。」
• 「この概念は複雑です。サンプルが 3 つでは足りません。」

知見の提示：

• 「Git の履歴を見ると、認証を 3 回リファクタリングしています。これは ADR に記録すべき内容です。」
• 「この 3 つのファイルがすべてのビジネスロジックを担っていますが、まったく文書化されていません。抜けがあります。」
• 「インライン JSDoc がありますが、Markdown ドキュメントの内容と矛盾しています。一貫性に問題があります。」

クイックモードの場合

効率的な実行：

• 「コミット a3f2b1c の変更に基づいて 3 つのファイルを更新しています……」
• 「新しいエンドポイントを 2 つ検出しました。api.md に追加しています……」
• 「削除された legacy-auth エンドポイントのドキュメントを削除しました……」

懸念事項の通知：

• 「警告：architecture.md に手動の変更が見つかりました。編集内容は保持します」
• 「注：新たに文書化されていない機能が追加されたため、ヘルススコアが 92 から 85 に下がりました」

品質基準

このスキルは、以下を通じて高品質なドキュメントを維持します。

明確さ

• 概念は、使用する前に説明されています
• 技術用語は、初出時に定義されています
• 概念の前、または直後にサンプルが示されています
• プログレッシブディスクロージャー（簡単な内容から複雑な内容へ）

完全性

• 公開されているすべての要素が文書化されています
• エッジケースや注意点が扱われています
• 予測可能な失敗に対するトラブルシューティングがあります
• 一般的なユースケースのサンプルがあります

正確性

• すべての事実がコードと照合して検証されています
• サンプルはテスト済みで、動作します
• リンクは検証済みです
• 古い情報はありません

アクセシビリティ

• 図には代替テキストを含めます
• リンクには説明的なテキストを付けます
• 見出し階層を論理的にします
• コードスニペットには言語ラベルを付けます

一貫性

• 用語を統一して使用します
• 全体を通して文体を維持します
• 書式を標準化します
• 構成を予測しやすくします

特別な機能

アーキテクチャ決定記録（ADR）

決定の理由を記録します。

このスキルは、次の項目から決定が必要なポイントを特定します。

• 主要な依存関係の追加（Git の履歴）
• 標準的でないアーキテクチャパターン（コード分析）
• フレームワークやライブラリの選択
• 「decision」に関する表現を含む、フラグが付けられたコミット
• 明示的な特定

各 ADR には次の内容を記録します。

• コンテキスト（どのような状況だったか）
• 決定（何を決めたか）
• 根拠（なぜその選択をしたか）
• 結果（受け入れたトレードオフ）
• 検討した代替案

常に最新でテスト済みのサンプル

サンプルは /examples にある実行可能なコードです。

• 実際に動作します（疑似コードではありません）
• よくあるユースケースを網羅します
• 実行を検証するテストスクリプトを含みます
• ドキュメントから参照されます
• コードの進化に合わせて保守されます

トラブルシューティングデータベース

次の 2 種類があります。

• ユーザー向けトラブルシューティング： よくあるエラーとその修正方法
• 開発者向けトラブルシューティング： デバッグガイド、エッジケース、注意点

このスキルは、包括モードでは初期コンテンツを用意し、クイックモードでは実際のトラブルシューティングコンテンツを追加するたびに内容を拡充します。

ドキュメントマップ

大規模なプロジェクト向けのナビゲーションガイドです。

• 初心者向けと上級者向けの異なる学習経路
• ドキュメント同士の関連性
• 読むべきタイミング
• 視覚的またはテキスト形式のナビゲーション補助

Mermaid 図

このスキルは、コードで記述する図を生成します。

• アーキテクチャ図
• シーケンス図
• ER 図
• 状態図
• フローチャート

すべてバージョン管理でき、GitHub 上でレンダリングされます。

ドキュメントホスティングとの連携

次のサービスを利用しているかどうかを検出します。

• GitHub Pages
• ReadTheDocs
• GitBook
• MkDocs

適切な設定ファイルを生成し、静的サイト生成に合わせて構成を最適化します。

参考ドキュメント

必要に応じて、状況に合わせて読み込みます。

• references/project-types-guide.md — さまざまな種類のプロジェクトのドキュメント作成方法
• references/documentation-patterns.md — 一般的なドキュメントのパターンと構成
• references/quality-standards.md — 詳細な品質基準と例
• references/manifest-spec.md — .doc-state.json の技術仕様
• references/depth-levels-guide.md — 標準と詳細の違いを例とともに説明
• references/health-score-formula.md — ヘルススコアの計算方法
• references/adr-guide.md — 効果的なアーキテクチャ決定記録の作成方法

テンプレート

templates/ に次のテンプレートがあります。

• README-template.md — 段階的に詳細を示す README の構成
• api-docs-template.md — API エンドポイントのドキュメント
• component-docs-template.md — コンポーネント／モジュールのドキュメント
• troubleshooting-template.md — トラブルシューティングガイドの構成
• contributing-template.md — コントリビューションガイドライン
• documentation-map-template.md — ナビゲーションガイドのテンプレート

成功基準

次の条件を満たすと、ドキュメントは完成です。

✓ ヘルススコア ≥ 85
✓ 重大および重要な負債をすべて解消
✓ サンプルがエラーなく実行できる
✓ リンクの検証に成功する
✓ アクセシビリティチェックに合格する
✓ 全体を通して文体に一貫性がある
✓ ドキュメントだけで、誰かがプロジェクトを使えると確信できる

主な注意事項

• 常に読者を第一に： あらゆる判断は読者のために行います
• Git を考慮： 再生成ではなく、変更箇所を賢く段階的に更新します
• 透明性： 分析と判断のすべてを確認できます
• 品質を維持： 適切な手動編集を上書きしません
• サンプルをテスト： 動作するコードにはテストスクリプトを生成します
• 健全性を追跡： ヘルススコアの経時的な推移を追跡します
• 負債に優先順位を付ける： すべての負債が同じ重要度ではありません
• 網羅的に、しかし過剰にならず： 重要なことを記録します