technical-documentation

技術ドキュメント

目的

人とエージェントのどちらにとっても明確で、曖昧さがなく、保守しやすい技術ドキュメントを作成、レビュー、監査します。製品ドキュメント、コントリビューター向けガバナンスファイル、エージェント向け指示ファイルが対象です。読者やエージェントが誤読しないよう、文章には Simplified Technical English を使用します。シャーディング、敵対的チェック、並行した修正により、数百ページに及ぶツリーにも対応できるよう監査を拡張します。

使用する場面

• 既存の製品やコードベース（ブラウンフィールド）のドキュメントを作成、または全面的に見直す場合。
• 長期にわたり正確さと再利用性を保つことを目的とした、長く使えるドキュメントを構築する場合。
• 構成、明瞭さ、運用上の正確性について、ドキュメントの差分をレビューする場合。
• ガバナンスファイルと製品ドキュメントの対象範囲（docs/、README*、.md/.mdx/.mdc、Fern/Sphinx/Mintlify/MkDocs のソース）にわたり、リポジトリ全体のドキュメント監査を実施する場合。
• 数百ページに及ぶ、またはページの文字数が 20k を超える、ナビゲーションが分かりにくい、ロケールが多い、読者体験が良くないといった、大規模または煩雑なドキュメントツリーを監査する場合。
• 手順、リファレンスページ、エラーメッセージ、ツールの説明、AGENTS.md、CONTRIBUTING.md など、密度が高い、または曖昧な英語を Simplified Technical English に書き直す場合。
• AGENTS.md や CONTRIBUTING.md を更新またはレビューし、エージェントとコントリビューターのワークフローを現在のリポジトリの慣行に合わせる場合。
• 別名の指示ファイル（CLAUDE.md、AGENT.md、.cursorrules、.cursor/rules/*、.agent/、.agents/、.pi/）があるリポジトリ向けに、ガバナンスドキュメントの戦略を設計する場合。
• チームが、欠けているファイル、壊れたコマンド、ポリシーの競合を見つけるために、反復的なプロンプト入力を必要としていた場合に、エージェントファイルの乖離を診断する場合。

証跡と成果物

• 通常の範囲を定めたレビューや監査の結果は、チャットまたは標準出力に記録します。デフォルトでは、レポートファイル、台帳、シャード用ディレクトリを作成しないでください。
• 永続的な証跡を作成するのは、依頼された成果物、または大規模監査、作業の再開、引き継ぎに関する具体的な要件がある場合に限ります。ファイルを書き込む前に、その利用者と目的を明示してください。
• 必要な証跡には、タスクごとに1か所の保存場所を再利用します。大規模または再開可能なワークフローで必要となる場合は、網羅範囲、重複排除、記録、復旧に関する要件を維持してください。
• 結果をインラインで示す場合もファイルに記録する場合も、網羅範囲と不足箇所を報告してください。永続化を減らしても、調査の範囲を狭めてはなりません。

ワークフロー

1. タスクを build、review、audit、rewrite のいずれかに分類し、コンテキストを brownfield または evergreen に分類します。
2. 依頼されたファイル、ディレクトリ、または差分の範囲を早い段階で確認します。ドキュメント全体を対象とする作業では、ガバナンス文書と製品ドキュメントも含めます。リポジトリの規模だけを理由に、対象を限定したレビューの範囲を広げてはいけません。
3. 多言語対応の範囲を特定し、必要なパリティレベルを定めます。
4. エージェント向けの指示と CONTRIBUTING.md のルールについて、references/agent-and-contributing.md を読みます。
5. 適用するルールセット（Matt Palmer、OpenAI、ASD-STE100）について、references/principles.md を読みます。
6. 文章の執筆または書き換えを行う前に、references/simplified-technical-english.md を読みます。ファイルごとに Strict モードまたは STE 寄りのモードを選びます。
7. 委任が有効で Agent ツールが利用可能な場合は sub-agent-assisted を使用し、それ以外の場合は single-agent を使用します。作業範囲を分割する必要がある場合、またはユーザーが Workflow を求めた場合は、references/workflows.md を読みます。workflow を使用するのは、ユーザーの明示的な同意があり、Workflow ツールを利用できる場合に限ります。
8. build タスクでは、references/build.md に従います。
9. review タスクでは、references/review.md に従い、問題を積極的に検出します。
10. 依頼された監査範囲を分割する必要がある場合は、references/large-docs-audit.md に従います。まず round-0 の機械的スキャンとリポジトリ固有のバリデーターを実行し、その後、文字数の上限に基づいて分割し、対象範囲内のすべてのページを全文監査します。各分割範囲でまとめて敵対的チェックを実施します。新たな指摘が 2 回連続でなくなるまでラウンドを続け、収束したと主張するのではなく、各ラウンドで追加された件数を報告します。メッセージに収めるために監査を途中で切り上げてはいけません。
11. rewrite タスクでは、まず scripts/ste-lint.py を実行し、STE のプロセスに従って書き換えた後、リンターを再実行します。重大な違反を増やしてはいけません。ユーザーがルール表を求めていない限り、書き換えたテキストのみを返します。
12. 大規模な修正では、編集を始める前に references/pr-program.md を使って台帳を PR にまとめ、そのフェーズ順に反映します。
13. プラットフォームやツールの選択が推奨事項に影響する場合は、references/tooling.md を使用します。
14. 依頼された範囲内で問題を積極的に洗い出します。報告のみを求められていない限り、確度の高い不具合は同じ作業で修正します。
15. brownfield モードでは、現行のドキュメント情報設計、ツール、リリース状況との互換性を優先します。evergreen モードでは、時代に左右されない表現と長期的に使える構成を優先します。
16. 成果物に加えて、検証メモ、対象範囲、パリティの状況、残っている課題を返します。

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

依頼された作業の範囲が広い場合は、委任を優先してください。リポジトリ全体、複数のフレームワーク、または競合が多い作業では、デフォルトで委任してください。

• inventory-agent -> agents/inventory-agent.md (haiku)：ファイル／設定の検出、カバレッジマップ、パスの不足チェック。
• ste-lint-agent -> agents/ste-lint-agent.md (haiku)：シャードごとの決定論的な STE リントのベースライン。
• governance-agent -> agents/governance-agent.md (sonnet)：AGENTS／CONTRIBUTING／エイリアスの優先順位、競合、ポリシーの乖離。
• docs-framework-agent -> agents/docs-framework-agent.md (sonnet)：フレームワーク設定、相対パスの基準、ファイルパスと URL パスの対応関係。
• verify-agent -> agents/verify-agent.md (sonnet)：指摘事項 1 件に対する反証的な検証。
• docs-ux-audit-agent -> agents/docs-ux-audit-agent.md (fable)：シャード 1 件を全文読み込んで行う読者体験の監査、台帳の出力。
• ste-rewrite-agent -> agents/ste-rewrite-agent.md (fable)：意味を保った Strict または STE 風の書き換え。
• remediation-agent -> agents/remediation-agent.md (fable)：検証済みの指摘事項をファイル 1 件に適用し、バリデーターを再実行。
• synthesis-agent -> agents/synthesis-agent.md (fable)：出力を統合して、優先順位付きの修正計画を作成。

Claude Workflows（references/workflows.md）では、監査テンプレートにより各シャードで docs-ux-audit-agent を実行し、続いて各シャードでバッチ化した verify-agent を実行してから、統合と完全性の批評を行います。指摘事項ごとに検証を振り分けることが、こうした実行でセッションを使い果たす主な原因です。そのため、検証はバッチ化し、範囲を限定してください。修正テンプレートでは、レビュアーを付けてファイルごとに remediation-agent を実行します。ユーザーの明示的な同意を得てから Workflow を開始してください。

入力

• ドキュメントの種類（チュートリアル、ハウツー、リファレンス、解説）と対象読者。
• ファイル、ディレクトリ、または差分の対象範囲。
• ドキュメントのフレームワーク／ツールに関する制約（Fern、Mintlify、Sphinx、MkDocs など）。
• タスクモード（build、review、audit、rewrite）と、既存プロジェクトの改修か継続的な更新かの意図。
• ファイルごとの STE モード（strict または flavored）、またはドキュメントの種類からスキルに推定させます。
• 対象エージェントと、人間との互換性に関する意図。
• 希望する調査の深さ（簡易確認、徹底調査）。監査では、指定された範囲内での徹底調査をデフォルトとします。
• 実行段階（workflow、sub-agent-assisted、single-agent）と Workflow の実行への同意。
• 修正モード（デフォルトは apply-fixes、または report-only）。
• エビデンスと成果物に基づき必要な場合に限り、永続的なエビデンスの用途とパスを指定します。大規模監査で台帳が必要な場合は、監査ルートに .audit/ledger.jsonl を使用してください。
• 多言語の対象範囲：原文の言語、対象ロケール、同等性に関する期待事項。

出力

• 更新したドラフト、書き換えたテキスト、または明確な次のアクションを含むレビュー指摘。
• 検証メモ（確認した内容と残っている作業）。STE リントの実行前／後の件数を含みます。
• 監査の対象範囲の報告：ディレクトリごとに、対象ページ数のうち読み込んだページ数を記載。
• ステータス別（未対応、検証済み、反証済み、修正済み、修正しないと決定）の件数を含む指摘事項。デフォルトではインラインで提示し、必要に応じて指定の台帳に記録。
• 大きすぎるページの分割計画と、ナビゲーション／IA の変更一覧。
• AGENTS／CONTRIBUTING を変更した場合のガバナンス文書との整合性の概要。
• エージェントの指示対象マップ（主要ファイル、エイリアスファイル、Codex／Claude／Cursor の対応計画）。
• 指定範囲内のドキュメント対象領域のカバレッジマップ（/docs、README の階層、フレームワークのソースツリー）。
• 委任に関するメモ：使用したエージェントまたは Workflow の実行 ID、委任した範囲、指摘事項の統合方法。
• 各ラウンドの指摘件数と、収束状況の報告。
• 大規模な修正作業の場合は、PR の計画。
• 多言語の同等性に関する注記（同期済み、理由を示した一部対応、または意図的な差異）。

フロー

stateDiagram-v2
    [*] --> ScopeInventoryAndRules
    ScopeInventoryAndRules --> SelectMode
    state SelectMode <<choice>>
    SelectMode --> Build: build
    SelectMode --> Review: review
    SelectMode --> RewriteWithLint: rewrite
    SelectMode --> AuditScope: audit
    AuditScope --> InlineAudit: scoped work needs no sharding
    AuditScope --> ShardedAudit: scope requires coverage ledger and shards
    Build --> ValidateAndReport
    Review --> ValidateAndReport
    RewriteWithLint --> ValidateAndReport
    InlineAudit --> ValidateAndReport
    ShardedAudit --> ValidateAndReport
    ValidateAndReport --> [*]
    note right of ShardedAudit
        Workflow tool use requires opt-in.
        Retain evidence only for a declared need.
    end note