documentation-impact

ドキュメントへの影響

ドキュメントは、利用者が実際に使う動作に合わせてください。どのドキュメントを更新する必要があるか判断する前に、実際の変更とその呼び出し元を確認してください。根拠を示したうえで「変更不要」と結論づけることも、完全な成果です。

モードと範囲を選択する

タスクでドキュメントの更新が許可されている場合は author を使用してください。監査、独立したレビュー、状況確認、その他の読み取り専用タスクでは review を使用してください。呼び出し元の指定するモードに従ってください。更新権限が明確でない場合は、review モードで調査して報告してください。

• author モードでは、許可された変更の範囲内で影響を受けるドキュメントを更新してください。無関係な編集には手を加えないでください。
• review モードでは、評価対象の成果物を編集せずに調査してください。結果はその作成者に返してください。ドキュメントを修正したうえで、自分の修正を自分で認定しないでください。

委任、モデルの選択、作業の継続、人間による確認は、呼び出し元のワークフローが担います。ここで別のコーディネーターを起動したり、公開ワークフローを開始したりしないでください。

受け入れ済みの依頼、課題、または既存の作業概要を使用してください。新たな仕様書、チケット、ドキュメントツリー、作業台帳を要求しないでください。

実際に調査した内容に基づいて、確認の範囲を明確にしてください。

• コミット済みの作業では、固定したベースとヘッドを特定して記録してください。ベースからヘッドまでの差分と、その各リビジョンにおける関連する実装およびドキュメントを確認してください。
• ローカルの作業では、ステージ済みおよび未ステージの変更と、関連する未追跡ファイルも確認してください。これらの入力について、コンテンツのフィンガープリントまたは保持したスナップショットを記録してください。HEAD が変更されていないように見えることや、ファイル名の一覧だけでは、変更されたファイルの内容を特定できません。
• Git の管理外では、対象範囲に含まれる実装とドキュメントの明示的なコンテンツスナップショットを記録してください。関連する入力を入手できない場合は、網羅したと主張せず、その不足を明記してください。

確認したパスと、フィンガープリントの方式または保持したスナップショットの場所を記録し、別のエージェントが比較を再現できるようにしてください。結果を返す前に入力を再確認してください。並行編集によって内容が変わっていた場合は、該当する確認をやり直すか、結果が現在の成果物を反映していないことを報告してください。

変更内容を読者に結び付ける

リポジトリの指示を読み、保守されているドキュメントやサンプルの場所を特定してください。変更された動作を、プロジェクトを利用、実行、アップグレード、開発する人々までたどってください。アプリケーションコードが変更されていなくても、スキルや設定における公開ワークフローの変更を含めてください。

変更によって影響を受ける場合は、次の種類のドキュメントを検討してください。

変更された動作	ドキュメントの候補
インストール、オンボーディング、基本的な使い方	README、クイックスタート、チュートリアル
コマンド、API、フラグ、デフォルト値、設定、環境変数	CLI および API リファレンス、設定ガイド、実行可能なサンプル
互換性、ストレージ、アップグレードの動作	移行およびアップグレード手順、非推奨の通知
リリース時に利用者が認識する動作	リポジトリで管理している場合は、リリースノートまたは変更履歴
モジュールの境界、データフロー、運用上の動作	アーキテクチャの説明、図、運用手順書、開発者向けガイド

すでに変更されたファイル以外も検索し、古い名前、古い値、矛盾するサンプルを確認してください。該当する記述は、文脈を含めて読んでください。更新日時が新しいこと、パスが一致すること、生成された文章であること、描画された図であることだけでは、事実が正確だとは判断できません。

影響を受ける読者のタスクごとに、該当する保守対象のドキュメントを特定するか、ドキュメントの変更が不要な理由を説明してください。既存のドキュメントがすでに正確な場合もあります。内部のリファクタリングによって、文書化された契約がまったく変わらないこともあります。確認作業を成果があったように見せるためだけに、内容のないドキュメントを作成しないでください。

更新または確認

author モードでは、変更された動作に必要な最小限の修正を行います。リポジトリのドキュメント構成と生成コマンドに従います。生成済みの出力を手作業で編集するのではなく、生成元のドキュメントを更新します。

作成またはレビューするドキュメントには、technical-writing スキルを使用します。次に、unslop スキルを使用します。例は、実在するシンボル、パス、フラグ、デフォルト値、サポート対象のバージョンに即したものにします。例に使うパスは、読者の環境で解決できるものでなければなりません。マシン固有のパスには明示的なプレースホルダーを使い、実際の値を確認または指定する方法を示します。先行する手順で作成される場合、一時パスは有効です。作成者の説明のない作業用パスは、使用できる例ではありません。アップグレードにユーザー操作が必要な場合は、その操作と、変更前から変更後への動作を明記します。

実装をたどって、ドキュメントに記載された効果を確認します。設定を受け付けたり報告したりするだけでは、対応する処理が実行される証拠にはなりません。意図した動作と確認された動作が食い違う場合は、欠陥をサポート対象の動作として記述するのではなく、その不一致を実装上の指摘として報告します。

review モードでは、影響を受ける読者のタスクを実装から独自に導き出します。「変更なし」という主張も含め、作成者による網羅性の判断をソースと照合します。作成者の報告は、結論ではなく調査対象となる証拠として扱います。

図によって影響を受ける関係を文章より明確に説明できる場合は、リポジトリ既存の図形式を使用します。変更された各アクター、エッジ、方向、境界を実装と照合します。利用できる場合は、任意のビジュアルツールを使って指摘をわかりやすく示してもかまいません。それ以外の場合は、Markdown または既存の図ソースを使用します。この確認を完了するために、ビジュアル関連の依存関係をインストールしたり、ブランディングに関する情報を求めたり、注釈へのフィードバックを待ったりしてはいけません。

author モードでレビューが必要か判断する

author パスでは、次のいずれか 1 つの結果を返します。

• independent review required：ドキュメントが変更された場合、公開ワークフローまたはドキュメント化された契約が変更された場合、あるいはドキュメントの不足が未解決のまま残る場合。
• independent review not required：内部的な変更でドキュメントへの影響がないことを証拠で示せる場合に限ります。

公開ワークフローまたはドキュメントの変更がある場合、independent review not required は無効です。確認した成果物とともに、author の結果を裏付ける証拠を記録します。完了またはリリースのワークフローが独立したレビューを開始できるのは、author の結果が independent review required の場合に限られます。

独立したレビューが必要な場合は、別のエージェントが成果物を編集せずにレビューします。独立レビューの判定は pass、needs changes、または unverified です。修正後、レビュー担当者は結果の成果物を確認してから pass を返します。確認対象の変更、ドキュメント、関連する周辺コンテキストが一致している場合に限り、判定を再利用できます。リベース後に安定した patch-id が一致しても、ドキュメントのコンテキストが変わっていないことの証明にはなりません。そのコンテキストを再確認するか、レビューを再実施してください。

検証して結果を返す

関連するリポジトリのドキュメントチェックを実行し、タスクの権限内で安全な場合は、変更した例を実際の実装に対して動作確認してください。完了の根拠として使用するコマンドには、verify-commands スキルを使用してください。レビュー時は、レビュー対象のファイルを変更せずにチェックを実行し、チェックによって出力が書き込まれる場合は使い捨てのコピーを使用してください。

構文やレンダリングだけでなく、事実としての意味も確認してください。誤ったデフォルト設定で実行される例や、存在しない承認手順を追加した図も誤りです。安全に実行できないチェックや利用できないチェックは、未確認事項として報告してください。例を検証するためだけに、デプロイ、ドキュメントの公開、外部データの変更を行わないでください。

簡潔な結果を会話または既存の作業記録に記載してください。

• モード、対象範囲、確認したリビジョンまたはスナップショット（関連するローカル変更を含む）。
• 影響を受ける読者のタスクとドキュメントのパス。更新した場合はその内容、変更しなかった場合はその根拠。
• 実際に実行したチェック、その結果、残っている指摘や検証上の不足。
• 執筆モードでは、執筆結果とその根拠。レビュー時は、pass、needs changes、または unverified を返してください。明らかな欠落や誤った記述が確認された場合は needs changes を、判断に必要な根拠が不足している場合は unverified を使用してください。

執筆結果は、独立したレビュー判定ではありません。