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. リクエストされたファイル、ディレクトリ、または差分の範囲を早期に棚卸しします。ドキュメンテーション全体の作業にはガバナンスと製品ドキュメントを含めます。リポジトリのサイズだけではスコープレビューが拡大されることはありません。
3. 多言語範囲（複数言語の README/ドキュメント）を検出し、必要なパリティレベルを定義します。
4. references/agent-and-contributing.md でエージェント指示と CONTRIBUTING.md ワークフロールール（棚卸し、正規/エイリアス マッピング、デュアルモードのバランス、成果物基準、優先順位/競合処理）を読み込みます。
5. references/principles.md で統治ルールセット（Matt Palmer & OpenAI）を読み込みます。
6. OpenClaw のドキュメント作業の場合、ビルド/レビュープレイブックの前に references/openclaw.md を読み込みます。
7. ビルドタスクの場合は references/build.md に従います。
8. レビュータスクの場合は references/review.md に従い、繰り返しプロンプトを待たずに問題を積極的に検出します。
9. 複雑またはリスクの高いタスク（ビルドまたはレビュー）の場合、必要に応じてより長く、より深く、より徹底的な調査を実行しても問題ありません。
10. 利用可能な場合は、サブエージェントを使用して制限付きの並行発見/レビュー作業を行い、出力を1つの首尾一貫した最終成果物に統合します。
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）：サブエージェントの出力を1つの優先順位付けされた修正計画と統一された優先順位モデルに統合します。

入力

• ドキュメントタイプ（チュートリアル、ハウツー、リファレンス、説明）と対象読者。
• ファイルスコープまたは差分スコープ。
• ドキュメンテーションフレームワーク/ツールの制約（Fern、Mintlify、Sphinxなど）。
• ビルド/レビューモードとブラウンフィールド/エバーグリーンの意図。
• 対象となるエージェントと人間の互換性の意図。
• 範囲内のドキュメンテーションフレームワークの対象面（例：Fern、Sphinx、Mintlify、Markdown/MDX/MDC/RST/RSCファイル）。
• 必要な調査の深さ/時間予算（クイックパス vs 徹底的なレビュー）。
• 実行モード（利用可能な場合、single-agent または sub-agent-assisted）。
• 是正モード（デフォルトでは apply-fixes、リクエスト時は report-only）。
• 多言語範囲：ソースオブトゥルース言語、対象ロケール、パリティ期待値。
• リポジトリ固有のオーバーレイ制約（存在する場合）。

出力

• 明確な次のアクションを含む更新されたドラフトまたはレビュー結果。
• 検証ノート（チェックされた内容、残っているもの）。
• 長期的な品質のためのナビゲーション/メンテナンスの推奨事項。
• AGENTS/CONTRIBUTING に触れた場合のガバナンスドキュメントアライメントの概要。
• エージェント指示対象面のマップ（プライマリファイル、エイリアスファイル、Codex/Claude/Cursor 処理計画）。
• ドキュメンテーションの対象範囲マップ（/docs でレビューしたもの、README 階層、フレームワーク固有のソースツリー）。
• 適用された修正（または明示的なレポートのみの結果）を含む自動検出された問題リスト。
• サブエージェントを使用した場合の委任ノート（委任された範囲と結果の統合方法）。
• 多言語パリティノート（同期済み、理由付きの部分的、または意図的に異なる）。
• 使用された場合のリポジトリ固有のオーバーレイノート。