documentation-guidelines

ドキュメント作成ガイドライン

コードだけでは説明できない、長期にわたって有効な意味を記録します。ビジネス上の意図、責任者、不変条件、権限、契約、運用上の決定などが該当します。実装の詳細や実行可能な証拠は、ソースコードとテストに委ねます。

委任

デフォルトではメインの会話で作業します。委任によって利用量が増える可能性があるため、サブエージェントを使う前に、予定するエージェント数と作業範囲について明示的な承認を得てください。承認された範囲内ではその承認を再利用し、承認済みの数や範囲を超える前に、改めて確認してください。

責任者と証拠を確認する

関連するドキュメントのインデックスと責任者がある場合は確認し、影響を受ける事実をソースコード、テスト、スキーマ、設定、実行時の証拠と照合します。変更される契約を理解するために必要なリンクをたどり、それ以上読んでも結果に影響しなくなった時点で止めます。ドキュメントが不足している、または古くなっている場合はソースコードを調べる理由になりますが、作業を妨げる前提条件ではありません。

対象範囲について、該当する関係者、トリガー、ルール、状態遷移、入出力、副作用、失敗時の経路、責任者、互換性要件を特定します。無関係な項目は省き、重要な未解決事項は推測せずに記録します。

長期的に有効な意味が変わる場合はドキュメントを変更する

変更	ドキュメント上の対応
内部リファクタリング、書式変更、またはドキュメントに記載された動作を復元する修正	必要に応じて、影響を受けるパスまたは証拠への参照のみを更新します
ユーザーの動作、ビジネスルール、またはワークフロー	既存の担当ドキュメントを更新します
API、スキーマ、権限、イベント、または互換性	契約と、影響を受ける利用者向けの対応関係を更新します
セットアップ、移行、デプロイ、バックアップ、または復旧	担当するランブックを更新します
エンティティの名称変更、移動、または削除	発見経路と古い参照を修正します
ドキュメントの重複または矛盾	有効な事実を1つの担当ドキュメントに残し、リンクを修正したうえで、対象範囲内の古いコピーを削除します

作業の経過を記録するだけのドキュメント変更は避けてください。一時的な計画、コマンドログ、CI の出力は、長期的に有効な運用要件を示すものでない限り、タスク、PR、または既存の証拠を記録する場所に留めます。

発見しやすく、保守しやすい内容にする

• 長期的に有効な事実には、それぞれ明確な担当ドキュメントを設けます。利用者はそこへリンクし、自分たちに関する対応関係や制約だけを記載します。
• リポジトリのレイアウトに従います。実際の発見上またはツール上の必要性から、その保守が正当化される場合に限り、ルーター、レジストリ、メタデータを追加します。
• 具体的なルール、検索しやすい見出し、例、少数のソースコード／テストへの参照を使います。壊れやすい行番号よりも、シンボル名やパスを優先します。
• 事実、推奨事項、不明点を分けます。汎用的なチュートリアル、推測に基づく要件、実装のコピー、古くなるステータスメタデータは削除します。
• 監査、移行、運用上の目的に役立つ場合は、履歴記録を保持します。追跡対象だった内容が置き換えられた場合は、十分であれば Git の履歴を利用します。

ドキュメントの種類については templates.md、複数の責任者にまたがる構成については architecture.md、統合については audit-cleanup.md を参照してください。

検証して報告する

既存のエントリーポイントから更新した担当ドキュメントまでの発見経路をたどります。リンク、識別子、コマンド、証拠への参照、および影響を受ける利用者向けの契約を確認します。矛盾するコピーや古い名称がないか検索します。対象を絞ったドキュメント検証ツールや生成検証ツールに加え、該当する必須チェックを実行します。アプリケーションのテストが必要なのは、変更が実行時の動作またはその契約に影響する場合に限られます。

変更した長期的に有効な事実、重要な削除や統合、検証内容、残る課題を報告します。