harmonize-docs

ドキュメントの整合性を整える

ドキュメントを、実装、意図、残作業を一貫して説明するものにします。長期にわたって有効な事実と変わりうるステータスには、それぞれ正規の記載元を1つだけ設け、ほかの読者向けの導線からはそこへリンクします。理解、根拠、運用、意思決定に必要な詳細は維持しつつ、古くなった内容や重複する内容は削ることを優先します。

対象範囲

対象範囲の指定がない場合は、リポジトリ内の有効なドキュメントをすべて対象にします。変更、パス、トピック、計画、サブシステム、比較が明示されている場合は、その起点と、ドキュメント上で必要となる影響範囲（正規の記載元、影響を受ける計画やステータス記録、ナビゲーション、相互参照）に範囲を限定します。範囲を限定した実行では、リポジトリ全体を調べないでください。

changes については、指定された既存の変更セットを使用します。指定がない場合は、現在のステージ済み、未ステージ、および未追跡の変更を使用します。意味のある変更セットが存在しない場合は、無関係な履歴を代わりに使わず、対象範囲を特定してください。

ドキュメント固有のナビゲーションと設定も対象に含めます。ソースコードは根拠として参照しますが、編集対象には含めません。アーカイブ、生成物、ベンダー提供ファイル、依存関係は対象外です。変更されない履歴は維持しつつ、有効なステータスの説明や履歴への導線は必要に応じて修正します。範囲外で信頼できる矛盾を見つけた場合は、範囲を広げず、後続対応のために記録します。

主張を切り分ける

次の状態を、それぞれ独立して把握できるようにします。

• 実装の実態： コード、設定、テスト、コマンド、リリースで検証された動作と運用上の境界。
• 目標設計： 最新の確認済み方針に基づく、選択済み、提案中、または未解決の将来の動作。
• 提供状況： リポジトリで既存の計画方式に従って示される、完了中、進行中、ブロック中、延期、次に取り組む作業。

採用された設計は、実装済みの動作ではありません。ソースコードに実装があるだけでは、検証、公開、サポート、認可、本番運用の準備ができていることの証明にはなりません。これらの違いは、文書の明確な位置づけ、時制、または簡潔なステータスマップで示し、各文に留保を繰り返し書くのは避けます。

ドキュメントを整合させる

対象範囲内の各ドキュメントを読み、重要な主張を適切な根拠に照らして検証します。意思決定と有用な根拠を掘り起こし、未解決の矛盾は意図を捏造せずに明らかにします。独立した領域は委任してもかまいませんが、対象範囲の網羅性と統合後の成果物には、コーディネーターが責任を持ちます。

各ドキュメントの目的、対象読者、範囲、ライフサイクルを定めます。簡潔で適切に機能しているドキュメントは維持します。記載内容の担当範囲や読者向けの導線に応じて、書き換え、統合、分割、移動、削除を行います。永続的に担う役割が明確に異なる場合に限り、ドキュメントを新規作成します。ツールが認識する指示の検出方法や優先順位を変更する場合は、それらを維持します。

ARCHITECTURE.md の作成、書き換え、分割、統合、移動を行う場合は、アーキテクチャドキュメントガイドを読んでください。目標とするアーキテクチャであることを明確に示し、提供順序や残作業は計画側で管理して、アーキテクチャをもう1つのロードマップにしないでください。

整合性のある結果をそのまま適用します。更新内容は適切な箇所に統合し、置き換えられた記述や記録の逐語的な履歴は整理して、影響を受けるリンク、コマンド、用語、ナビゲーションを修正します。元の表現や配置が合わなくなっても、有用な意図は維持します。別途依頼された場合に限り、ステージ、コミット、プッシュを行います。

完了

最終ドキュメントをまとめて読みます。影響を受けるリンク、パス、例、コマンドを確認し、古い用語や矛盾する記述を検索します。変動する件数が長期的に役立たない場合は、安定した事実や情報源への参照に置き換えます。

完了した作業が最新状況を示すドキュメントと進捗記録に反映され、未完了の設計が未実装であると明確に示されるよう、前後両方向のつながりを確認します。概要から直接入った場合も、詳細な計画と同じ信頼できる最新状況にたどり着けるようにします。対象範囲内のすべてのドキュメントと矛盾を確認し、利用可能な関連チェックを実行して、書き換えによる失敗を修正します。

重要な修正、担当や構成の変更、検証結果、未解決の制約を報告します。対象ドキュメントの内容が一致し、読者が実在するもの、予定されているもの、未完了のものを把握できる状態になったら完了です。