技術文書作成（Technical Documentation Authoring）
技術文書を安定した、保守しやすく、ナビゲートしやすい知識の器に仕上げます。まず事実の属する場所と読者が必要とするものを決定し、次に内容を整理し、最後に表現を洗練させます。
基本原則（Core principles）
- 書き始める前に情報の種類を特定する; 発見プロセスをそのまま記事の構造にしてはいけません。
- 各永続的事実にはただ一つの正規の所有者（canonical owner）を置く; 所有者はソースコード、設定、スキーマ、ジェネレーター、ドキュメント、または決定記録（decision record）のいずれかです。
- ファイル名や既存の資料ではなく、読者の意図（reader intent）に基づいて文書の種類を選択します。
- 書き始める前に文書契約（Document Contract）を確立する: 読者、目標、主題、範囲、除外事項、権威ある情報源、詳細上限。
- 文書の種類によってスコープが拡大してはいけません; 上位文書は直接の子文書を要約し、詳細の所有者へのリンクを提供します。
- 調査、実装、コミットの順序ではなく、前提条件、依存関係、検証可能な結果に沿って内容を整理します。
- 現在の状態、設計の理由、履歴を異なる文書の責務として分離します。
- 境界を越える場合は権威ある詳細にリンクし、現在の範囲に収まり、かつ十分に安定した内容のみを保持します。
- まずメインエージェントが作成計画（authoring plan）を凍結してから、タスクを委譲するかどうかを決定します; サブエージェントは境界の明確な部分的な執筆のみを実行します。
作業契約（Working contract）
執筆、書き直し、分割、統合、または構造レビューを実行する前に、簡潔な文書契約（Document Contract）を作成します。内部で完結させても構いません; タスクの調整が必要な場合にのみ可視の成果物として記録します。
以下の項目を記録します:
- 読者の意図（Reader intent）：読者が学習、タスク完了、情報検索、理解、履歴追跡、またはルール遵守のいずれを目的としているか。
- 文書の種類（Document type）：意図に一致する主要な文書の種類; 一つの文書は一つの主要な意図のみを保持します。
- 主題（Subject）：文書が直接担当するトピックまたはシステム階層。
- 範囲（Scope）：含まれるオブジェクト、動作、深さ。
- 除外事項（Exclusions）：明確に他の文書または権威ある情報源に委ねる内容。
- 権威情報源（Authorities）：現在の事実を支えるソースコード、設定、生成ファイル、決定記録、または既存の文書。
- 詳細上限（Detail ceiling）：現在の主題と読者の目標において許容される最高の詳細レベル。
所有者、読者の意図、範囲、または権威情報源を確定できない場合は、まず不確実性を保持し、ギャップを報告します; 製品の決定や現在の動作を経験に基づいて補って書いてはいけません。
作成ワークフロー（Authoring workflow）
1. タスクと文書の位置を特定する
新規作成、更新、分割、統合、または構造レビューのいずれであるかを識別します。適用可能な AGENTS.md、CLAUDE.md、CONTEXT.md、文書インデックス、および隣接文書を読み、リポジトリに既存の階層、命名規則、リンク規則を確認します。
対象文書が存在しない場合、タスクをグリーンフィールド文書作成（greenfield documentation）として扱います: コードディレクトリ、公開API、設定スキーマ、テスト、サンプル、コマンド、生成ファイルから候補文書マップを構築します。まず、入口文書が一つ必要なのか、所有者と読者の意図で分割された文書群が必要なのかを判断し、コードフレームワーク全体を一つの大きな包括的な説明書に圧縮してはいけません。
完了条件: 既存文書がある場合は、対象パス、親文書、直接の子文書、適用可能なローカルルールを把握している; 既存文書がない場合は、コードフレームワークの主要な境界、候補文書集合、各文書の暫定的な所有者と権威情報源を把握している。
2. 情報を棚卸し、分類する
保存する予定の事実、説明、手順、サンプル、制限、履歴資料をリストアップします。情報の種類ごとに分類し、現在の状態、永続的な理由、操作手順、参照資料、ルール、インシデント、生成コンテンツを区別します。
詳細な分類表が必要な場合は、references/information-and-ownership.md を参照してください。
完了条件: 候補となる各コンテンツに情報の種類が割り当てられている; 異なる種類の資料が未定義の段落に混在していない。
3. 事実を正規所有者（canonical owner）にルーティングする
各永続的事実に対して既存の所有者を探します。ソースコード、設定、スキーマ、ジェネレーター、既存の決定記録を優先的に権威情報源として使用します; 文書はその責務範囲内の説明、プロセス、または安定した契約のみを所有します。
既に所有者が存在する内容については、必要な要約と所有者へのリンクのみを保持します。複数の所有者が競合している場合は、まず競合を報告し、解決すべき権威問題を記録します。
完了条件: 重要な事実にはそれぞれ唯一の所有者が存在する; 現在の文書は他の場所にある権威ある詳細を複製していない。
4. 読者の意図に基づいて文書の種類を選択する
読者の目標から、チュートリアル（Tutorial）、ハウツー（How-to）、リファレンス（Reference）、解説（Explanation）、アーキテクチャ決定記録（ADR）、ポリシー（Policy）、またはインシデントレポート（Postmortem）などの種類を選択します。一つのファイルに複数の種類の内容が含まれているからといって、複数の主要な種類を重ねてはいけません; 混合された意図がナビゲーションや保守性に影響を及ぼす場合は、文書を分割します。
種類の選択と構造パターンについては、references/document-types-and-composition.md を参照してください。
完了条件: 「誰が何のためにこの文書を読むのか」を一文で説明でき、主要な文書の種類を一つ指摘できる。
5. スコープと詳細上限（Detail ceiling）を固定する
主題、対象読者、目標、含める内容、除外する内容、権威情報源、詳細上限を書き出します。文書を自身の主題、属する階層、直接の子文書の責務に制限します; より低レベルのメカニズム、テスト、チェックリスト、実装の詳細は所有者に移動します。
文書の種類によってスコープを拡大してはいけません。親文書は構成、責務、高レベルの動作を記述します; 子文書は型定義、パラメータ、テストメカニズム、または具体的な操作を所有します。
完了条件: 各セクションが「それが現在の読者の目標とスコープにどのように貢献するか」に答えられる; 範囲外の資料は適切な移動先またはリンクが決まっている。
6. 実行可能な作成計画（authoring plan）を策定する
まず読者が知っておくべき前提概念を配置し、次にそれらに依存する操作、説明、または参照内容を配置します。文書の種類に対応する構造を使用し、調査、実装、議論、コミットの順序を教育の順序にしてはいけません。
大規模文書の場合は、セクションツリー、事実の所有者、セクション間の依存関係、対象ファイル、除外事項、各セクションの受け入れ条件を記録します。計画は、別のエージェントが全体構造を再設計することなく、局所的なタスクを完了できるものでなければなりません。
完了条件: 読者が後続の文章を参照しなければ、前提用語、前提条件、またはアクションを理解できないことがない; 各主要段落は明確な質問に答える; 各計画ユニットは一意の範囲と完了条件を持つ。
7. 実行モードを選択し、委譲する
デフォルトではシングルエージェントパスを採用します。以下の条件がすべて満たされた場合にのみ、サブエージェントを起動します:
- 計画が凍結されており、読者の意図、文書の種類、スコープ、所有者、主要構造に未解決の競合がない。
- 独立して読み取り、独立して書き込み、独立して受け入れ可能な作業単位が少なくとも二つ存在する。
- 各作業単位に一意の対象ファイルまたはセクションの所有者がおり、タスク間で同じ段落を同時に編集することがない。
- 依存関係が明示的に記録されている; 共有が必要な事実には権威ある情報源が存在し、サブエージェントが互いに推測する必要がない。
- 委譲と統合のコストが、メインエージェントが全文書コンテキストを保持し続けるコストよりも低い。
条件を満たす場合、references/orchestration-and-delegation.md を参照し、メインエージェントが委譲ブリーフィングを生成してサブエージェントを呼び出します。メインエージェントはグローバルな計画、事実の帰属、セクション間のリンク、統合の決定、最終的な受け入れ権限を保持します。サブエージェントは文書の種類を再設計せず、他の作業単位を変更せず、未確認の事実を結論として書きません。
条件を満たさない場合、メインエージェントは単独で執筆を続行します。単一ファイルの部分的な補足、少数の段落の修正、単一所有者のリファレンス更新、強く直列に依存するタスクはいずれもシングルエージェントパスに該当します。
完了条件: シングルエージェントまたは委譲実行のいずれかが明確に選択されている; 委譲する場合、すべてのタスクに境界、依存関係、出力形式、受け入れ条件がある。
8. 現在の契約と観察可能な動作を直接記述する
具体的な主体、アクション、API、オプション、結果を用いて内容を表現します。まず現在の状態と読者が観察可能な動作を記述し、次にデフォルト値、制限、例外、原理、トレードオフを補足します。「必須」「デフォルト」「推奨」「可能」を明確に区別します。
チュートリアルとハウツーは最小限のサンプルを説明の中心にできます; リファレンスは検索可能な定義と境界を中心にします; ADR とインシデントレポートはそれぞれに必要な理由やタイムラインを保持します。
完全な表現ルールとチェックリストが必要な場合は、references/writing-and-validation.md を参照してください。
完了条件: 本文は推論プロセス、実装の流水帳、または空虚なメタ言説ではなく、保守可能な事実、契約、または手順を述べている; 委譲タスクの出力はすべてメインエージェントに回収されている。
9. 統合し、統一する
サブエージェントを使用した場合、メインエージェントは各出力が作成計画に適合しているかを項目ごとにチェックします。重複する事実、用語のずれ、セクションの境界、相互リンク、スタイルの不統一を解決します; 未解決の問題は集中的に記録し、ローカルエージェントがグローバルな決定を独自に発明してはいけません。サブエージェントのプロセス説明をそのまま本文に組み込まず、保守可能な結果のみを統合します。
完了条件: 各委譲ユニットに結果または明確なブロック理由がある; 同じ事実に複数の所有者が存在しない; グローバルな目次、リンク、用語、読者のパスが一貫している。
10. リンクし、縮約し、検証する
重複する事実、手書きリスト、無関係な背景、詳細上限を超える詳細を削除します。目標を説明するリンクを用いて、所有者、子文書、ソースコード、決定記録に接続します。参考ファイルに記載された順序に従って、構造的検証と言語的検証を完了します。
完了条件: 所有者、種類、スコープ、依存順序、現在/履歴の境界、リンク、表現ルールがすべてチェックされている; 未処理の競合や不確実性が残っていない。
境界（Boundaries）
リポジトリ固有のファイル階層、スクリプトコマンド、文字数制限、コードブロックのコンパイルルール、バイリンガルプロセス、特定の用語を汎用ルールとして記述してはいけません。ローカルプロジェクトの規約を読み、それに従います; 本スキルはプロジェクト間で安定した文書決定フレームワークのみを提供します。
README、architecture.md、AGENTS.md を固定された汎用文書の種類として扱ってはいけません。まず読者の意図を判断し、次にプロジェクトにおけるこれらの媒体の具体的な規約に従います。
最終引き継ぎ（Final handoff）
完了後、簡潔に以下の内容を説明します: 文書の種類と読者の意図、正規所有者（canonical owner）の扱い、スコープの境界、関与したリンクや分割、およびまだ人間による決定が必要な事実の競合。未解決の問題を現在の状態として偽装してはいけません。