ドキュメント自動生成

ドキュメントはクライアントが最初に求めるものでありながら、エンジニアが最後に書くものです。アウトソーシングでは、このギャップは特にコストが高くつきます。引き継ぎが止まり、新しいチームメンバーは機能を提供する代わりにコードを逆解析するために数日を費やし、クライアントは自分たちで運用できないシステムを抱えることになります。Sun Agent Kit はコードベースから直接、本番品質のドキュメントを生成します。API リファレンス、アーキテクチャガイド、README ファイル、構造化されたクライアントハンドオフパッケージです。これにより、納品物が機能するだけでなく、完結したものになります。

概要

目的: クライアント納品、チームローテーション、またはコンプライアンスのために、ソースコードから完全で正確かつメンテナンス可能なドキュメントを生成する
所要時間: 10〜30分（手動作成の場合は2〜4時間）
使用エージェント: doc-writer、scout、reviewer
コマンド: /sk:docs init、/sk:docs update、/sk:docs summarize

前提条件

• Sun Agent Kit がインストール・認証済みであること（インストールガイド）
• git にコミットされたソースコード（エージェントは開いているファイルではなくリポジトリを読み取ります）
• API ドキュメントの場合: 一貫したパターンを持つルートまたはコントローラーファイル（Express、FastAPI、Laravel、Spring Boot すべてサポート）
• アーキテクチャドキュメントの場合: 少なくとも1つの識別可能なレイヤーを持つコードベース（コントローラー、サービス、リポジトリ、または同等物）
• 任意: エージェントが置き換えるのではなく拡張できる /docs の既存の部分的なドキュメント

ステップ別ワークフロー

ステップ 1: プロジェクトの初期ドキュメントを生成する

最初の実行でコードベース全体をスキャンし、包括的なドキュメントセットを作成します。

/sk:docs init

実行内容: エージェントが以下を実行します：

1. プロジェクト構造をスキャンしてフレームワーク・データベース・認証方式・デプロイ設定を検出する
2. 設定サーフェスを抽出する（環境変数、npm スクリプト、Docker 設定）
3. 既存の部分的なドキュメントを読み取り、保持する
4. README・API 概要・セットアップガイド・アーキテクチャサマリーを docs/ ディレクトリに書き出す

ステップ 2: API リファレンスドキュメントを生成する

エージェントをルートまたはコントローラーに向けると、エンドポイント・パラメーター・リクエスト/レスポンスの形式・エラーコードを含む完全な API リファレンスが生成されます。

/sk:docs "generate API reference documentation from the route files in src/routes/"

実行内容: エージェントが以下を実行します：

1. ルートファイルをスキャンし、HTTP メソッドとパスを含むすべてのエンドポイントを検出する
2. バリデーションスキーマ（Zod、Joi など）からリクエストボディの形式を抽出する
3. コントローラーのリターン文とエラーハンドラーからレスポンスの形式を推測する
4. 構造化された API リファレンスドキュメントを docs/ に書き出す

ステップ 3: アーキテクチャドキュメントを生成する

システム構造を説明する技術アーキテクチャガイドを作成します。新しいチームメンバーやクライアントの技術レビューに役立ちます。

/sk:docs "generate architecture guide — include system overview, layer diagram, data flow, and key design decisions"

実行内容: エージェントが以下を実行します：

1. コードベースのレイヤー構造（コントローラー、サービス、リポジトリなど）を分析する
2. 外部統合とバックグラウンドジョブ処理をマッピングする
3. 推測されたデザインパターンとアーキテクチャ上の決定を文書化する
4. 図を含むアーキテクチャガイドを docs/ に書き出す

ステップ 4: スプリント後に既存のドキュメントを更新する

機能が追加または API が変更された後、すべてを書き直すことなく現在のコードベースに合わせてドキュメントを更新します。

/sk:docs update

実行内容: エージェントが以下を実行します：

1. コードベースを再分析し、既存のドキュメントと比較する
2. 新しいエンドポイント・変更されたインターフェース・削除された機能を特定する
3. 手動で書かれたセクションを保持しながら影響を受けるドキュメントファイルを更新する
4. 更新内容の変更点を報告する

ステップ 5: クライアントハンドオフパッケージを生成する

これが案件の正式な終了を示す納品物です。クライアントがシステムを独立して運用・保守・拡張するために必要なすべてのものです。

/sk:docs "generate complete handoff documentation — include system overview, operations guide, runbook, and known issues"

実行内容: エージェントが以下を実行します：

1. 既存のすべてのドキュメントを収集し、ギャップを特定する
2. 運用ランブックを生成する（デプロイ、ロールバック、環境設定、ヘルスチェック）
3. GitHub イシューまたはコード内の TODO コメントから既知の問題を文書化する
4. docs/ 内のインデックス付きハンドオフパッケージにすべてを集約する

完全な例: 日本のクライアント向けハンドオフドキュメントの生成

シナリオ

チームは日本の物流会社向けに B2B SaaS プラットフォームを構築する6か月の案件を完了しました。納品日は金曜日です。クライアントの社内チーム（ビルドに関与していなかったエンジニア2名）が月曜日から運用を引き継ぎます。クライアントの PM から要件チェックリストが届いています: システム概要、API ドキュメント、環境設定ガイド、デプロイ手順、一般的な運用タスクのランブック。引き継ぎミーティングまで3時間あります。

連鎖コマンド

# 1. Generate the README if it is out of date
/sk:docs "Refresh README.md — verify all setup steps are accurate, add Docker deployment section, add troubleshooting for common local setup issues"

# 2. Full API reference for the client's engineering team
/sk:docs "Generate complete API reference from src/routes/ — all endpoints, authentication requirements, request/response examples, error codes"

# 3. Architecture guide — the client's team needs to understand the system
/sk:docs "Generate architecture overview for client handoff — plain language descriptions, focus on how to extend the system"

# 4. Generate the operations runbook
/sk:docs "Generate operations runbook — daily health checks, how to deploy, rollback procedure, database backup verification, monitoring alerts guide"

# 5. Assemble the complete handoff package
/sk:docs "Assemble complete handoff package — include all docs generated today"

# 6. Review for completeness and accuracy
/sk:code-review --pending

結果

引き継ぎミーティングの2時間半前に、クライアントのチェックリストのすべての項目をカバーする包括的なドキュメントパッケージが揃います。アーキテクチャガイドは平易な言葉を使用しています。運用ランブックには正確な CLI コマンドが含まれています。API リファレンスにはすべてのエンドポイントのサンプルがあります。クライアントのエンジニアは引き継ぎミーティングを、ドキュメントをどこで探すかやアプリケーションをどうデプロイするかではなく、ビジネスロジックとエッジケースについて質問することに費やします。

時間比較

ドキュメントタイプリファレンス

ベストプラクティス

1. 納品時だけでなく、毎スプリントの終わりに /sk:docs update を実行する ✅

継続的に更新されるドキュメントは正確さを保ちます。一度書かれてプロジェクト終了時に更新されるドキュメントは、クライアントに届く頃には30〜40%陳腐化していることがよくあります。スプリントレビューでの短いドキュメント同期はわずかなコストです。しかし、ハンドオフ前の数時間の追いつき作業はそうではありません。

2. 完成の定義にハンドオフパッケージを含める ✅

最終スプリントの受け入れ基準に「ハンドオフドキュメントが最新」を明示的に追加してください。完全で正確なハンドオフパッケージを受け取ったクライアントは、一貫して高い満足度スコアとハンドオフ後のサポートリクエストの減少を示しています。オプションの付加価値ではなく、納品基準にしてください。

3. 手動で追加した内容にフラグを立てずにエージェント生成のドキュメントを編集しない ❌

生成されたドキュメントに手動のコンテキストを追加する場合（クライアント固有のビジネスルール、ミーティングで口頭で決定された事項）は、そのセクションにコメントを付けてください: <!-- Manual addition -->。これにより、次の /sk:docs update がコードだけから推測できないコンテキストを上書きするのを防ぎます。

4. クリーンなコードの代替としてドキュメントを使用しない ❌

大規模なゴッドオブジェクトに複数ページの説明がついていても、依然として大規模なゴッドオブジェクトです。ドキュメントはコードが何をするかを説明します。理解しにくいコードを修正するわけではありません。アーキテクチャドキュメントがあるモジュールがなぜその動作をするかを説明するために段落を重ねる必要がある場合は、/sk:plan "refactor" がより良い投資かどうかを検討してください。

トラブルシューティング

問題: API リファレンスは生成されるがレスポンスの形式が正しくない

解決策: エージェントはコントローラーのリターン文からレスポンスの形式を推測します。コントローラーが汎用オブジェクトを返すか共有のトランスフォーマー関数を使用している場合、エージェントは完全な形式を推測できない場合があります。プロンプトにより多くのコンテキストを提供してください: /sk:docs "generate API reference — include request/response examples using data from test files"。

問題: アーキテクチャドキュメントが実際のアーキテクチャではなく計画されたアーキテクチャを説明する

解決策: これはコードベースが意図したレイヤー構造から逸脱している場合に起こります。例えば、リポジトリが HTTP コールを行ったり、コントローラーが SQL クエリを実行したりする場合です。エージェントは存在するものをドキュメント化しますが、逸脱にフラグを立てます。出力にレイヤー違反の警告が表示される場合は、ドキュメントを再生成する前にリファクタリングで構造的な問題に対処してください。

問題: ハンドオフパッケージに「手動入力が必要」というギャップがある

解決策: コードから導出できない情報があります: ビジネスコンテキスト、クライアント固有の制約、口頭での決定、オンコールエスカレーションパス。エージェントは人間の入力が必要なものを正確にマークします。パッケージをクライアントに送付する前に、各プレースホルダーセクションを入力してください。

問題: /sk:docs update が手動でカスタマイズしたセクションを上書きする

解決策: 手動で書かれたセクションを HTML コメントでマークしてエージェントが更新時に保持できるようにしてください。自動生成されるセクションと手動でメンテナンスされるセクションを示すメモをファイルの先頭に追加してください。

次のステップ

• コードレビュー — 完全な品質記録のためにハンドオフドキュメントと合わせて納品チェックリストを生成する
• セキュリティ監査・スキャン — コンプライアンス重視のクライアント向けにハンドオフパッケージにセキュリティ監査レポートを含める
• レガシーコードのリファクタリング — アーキテクチャドキュメントをより有用にするために生成前にコードの明確さを改善する

重要なポイント: 締め切りのプレッシャー下で最後の瞬間に書かれたドキュメントはギャップだらけです。Sun Agent Kit はコードベース自体から継続的に生成するため、クライアントが要求する前に正確で完全な状態でハンドオフが準備できています。