technical-documentation

技術ドキュメント

目的

人間とエージェントの双方にとって、明確で実行しやすく、保守しやすい技術ドキュメントを作成・レビューします。これには、コントリビューター向けガバナンスファイルとエージェント指示ファイルも含まれます。

使用する場面

• 既存の製品やコードベース（ブラウンフィールド）のドキュメントを作成または全面的に見直す場合。
• 長期にわたって正確さと再利用性を保つことを目的とした、エバーグリーンドキュメントを作成する場合。
• 構成、明確さ、運用上の正確さについて、ドキュメントの差分をレビューする場合。
• ガバナンスファイルと製品ドキュメントの両方を対象に含める必要がある、リポジトリ全体のドキュメント監査を実施する場合（docs/、README*、.md/.mdx/.mdc、Fern/Sphinx/Mintlify形式のソース）。
• エージェントとコントリビューターのワークフローを現在のリポジトリの慣行に合わせるため、AGENTS.md や CONTRIBUTING.md を更新またはレビューする場合。
• コントリビューションの手順、issue テンプレート、PR のフロー、レビューのゲートを含む、リポジトリのオンボーディングやドキュメントを改善する場合。
• 別名の指示ファイル（例：CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）があるリポジトリのガバナンスドキュメント戦略を設計する場合。AGENTS.md がある場合は標準として扱い、別名ファイルは互換性を保つためのものとして維持します。
• チームが不足ファイル、壊れたコマンド、ポリシーの競合を明らかにするために、繰り返しプロンプトする必要があったエージェントファイルの乖離を診断する場合。
• リポジトリ固有のドキュメント用オーバーレイ（OpenClaw のページ種別、ドキュメント IA、保持、検証ルールなどが存在する場合）を適用する場合。

ワークフロー

1. タスクを build または review に分類し、コンテキストを brownfield または evergreen に分類します。
2. 早い段階でドキュメントの対象範囲全体を洗い出します（ガバナンスと製品ドキュメント）。AGENTS/CONTRIBUTING/別名ファイルに加え、ドキュメントディレクトリ、フレームワークのソース、ルートおよびモジュールの README を確認します。
3. 多言語対応の範囲（複数の言語で書かれた README/ドキュメント）を検出し、必要な同等性のレベルを定義します。
4. エージェント指示と CONTRIBUTING.md のワークフロールール（対象の洗い出し、標準ファイルと別名ファイルの対応付け、両モードのバランス、成果物の基準、優先順位と競合への対処）について、references/agent-and-contributing.md を読みます。
5. 適用されるルールセット（Matt Palmer と OpenAI）について、references/principles.md を読みます。
6. OpenClaw のドキュメント作業では、build/review のプレイブックを実行する前に references/openclaw.md を読みます。
7. build タスクでは、references/build.md に従います。
8. review タスクでは、references/review.md に従い、繰り返しプロンプトされるのを待たずに、問題を先回りして検出します。
9. 複雑なタスクやリスクの高いタスク（build または review）では、確信を得るために必要に応じて、時間をかけた詳細かつ網羅的な調査を行ってもかまいません。
10. 利用できる場合は、対象を限定した並行調査やレビューにサブエージェントを使い、その結果を統合して一貫性のある成果物にまとめます。
11. プラットフォームやツールの選択が推奨事項に影響する場合は、references/tooling.md を使います。
12. ガバナンスとドキュメント内容の両方について、先回りして問題を洗い出します。明示的に報告のみを求められていない限り、確度の高い不具合は同じ作業で修正します。
13. ブラウンフィールドモードでは、現在のドキュメント IA、ツール、リリース状況との互換性を優先します。
14. エバーグリーンモードでは、時代に左右されない表現、更新戦略、長期的に維持できる構成を優先します。
15. 成果物に加え、検証に関する注記、同等性の状況、未解決の不足点を提示します。

サブエージェントのオーケストレーションに関するガイダンス

リポジトリが大規模な場合や、依頼された変更範囲が広い場合は、サブエージェントを優先してください。リポジトリ全体、複数のフレームワーク、または競合が多い作業では、デフォルトで使用してください。

• inventory-agent -> agents/inventory-agent.md（fast / Claude haiku）：ファイル／設定の検出、カバレッジマップ、パスの欠落チェック。
• governance-agent -> agents/governance-agent.md（thinking / Claude sonnet）：AGENTS／CONTRIBUTING／エイリアスの優先順位、競合、ポリシーの乖離。
• docs-framework-agent -> agents/docs-framework-agent.md（thinking / Claude sonnet）：フレームワーク設定、相対パスの基準、ファイルパスと URL パスのマッピングチェック。
• synthesis-agent -> agents/synthesis-agent.md（long / Claude opus）：サブエージェントの出力を統合し、優先順位を付けた修正計画と統一された優先順位モデルを作成します。

入力

• ドキュメントの種類（チュートリアル、ハウツー、リファレンス、解説）と対象読者。
• 対象ファイルまたは差分の範囲。
• ドキュメントのフレームワーク／ツールに関する制約（Fern、Mintlify、Sphinx など）。
• ビルド／レビューのモード、およびブラウンフィールド／エバーグリーンの意図。
• 対象エージェントと人間の互換性に関する意図。
• 対象とするドキュメントのフレームワーク領域（例：Fern、Sphinx、Mintlify、Markdown／MDX／MDC／RST／RSC ファイル）。
• 希望する調査の深さ／時間の上限（簡易確認か徹底レビューか）。
• 実行モード（利用可能な場合は single-agent または sub-agent-assisted）。
• 修正モード（デフォルトは apply-fixes、指定があれば report-only）。
• 多言語対応の範囲：正本となる言語、対象ロケール、パリティの要件。
• リポジトリ固有のオーバーレイ制約があれば、その内容。

出力

• 明確な次のアクションを含む、更新済みのドラフトまたはレビュー結果。
• 検証メモ（確認した内容と、未確認の内容）。
• 長期的な品質向上のためのナビゲーション／メンテナンスに関する提案。
• AGENTS／CONTRIBUTING に変更を加えた場合のガバナンス文書との整合性の概要。
• エージェントの指示サーフェスのマップ（プライマリファイル、エイリアスファイル、Codex／Claude／Cursor の対応計画）。
• ドキュメントサーフェスのカバレッジマップ（/docs、README の階層、フレームワーク固有のソースツリーで確認した内容）。
• 自動検出した問題の一覧と適用した修正（または明示的なレポートのみの結果）。
• サブエージェントを使用した場合の委任メモ（委任した範囲と、結果を統合した方法）。
• 多言語パリティの注記（同期済み、理由付きの部分対応、または意図的な差異）。
• リポジトリ固有のオーバーレイを使用した場合の注記。