superior-docs

優れたドキュメント

チャット履歴に頼らず、将来の保守担当者がプロジェクトの現状、重要な決定、安全な運用手順を把握できるドキュメントを作成します。ドキュメントは、根拠を維持しながら示すものであり、創作した事実を記す第2の情報源ではありません。

モードを選択する

• ブートストラップ： まだ存在しない場合に、役立つ docs/ の仕組みを整えます。
• 記録： 検証済みの実装、修正、リファクタリング、設定変更、機能の成果を実装タイムラインに記録します。
• 同期： 検証済みのプロジェクト変更後に、影響を受けるドキュメントを更新します。
• 再構築： リポジトリの根拠から、アーキテクチャの変遷、リリース、保守履歴を明らかにします。
• 引き継ぎ： 大きな作業の終了時に、現在の実装、境界、リスク、次の作業を記録します。

依頼内容からモードが明らかな場合、ユーザーに選択を求めないでください。

実装作業は原則として記録する

コード、設定、スキーマ、API の動作、セキュリティ制御、ビルドの動作、またはユーザーから見える機能に対して、検証済みの重要な変更を加えた後は、ユーザーがドキュメントの作成や更新を明示的に求めない限り、実装記録を作成または更新してください。

別の実装スキルが重要な作業を完了したときは、必ず references/automatic-change-recording.md を読みます。ここには、標準の進め方、最小限のブートストラップ、記録項目、オプトアウトの動作、対象外事項が定義されています。

別途ドキュメント作成を依頼されるのを待たず、通常の許可を求めないでください。「ドキュメントは不要」「これを記録しないで」などの明示的なオプトアウトや、それに相当するプロジェクトの指示は、優先されるものとして扱います。ユーザーが明言しない限り、あるタスクに対するオプトアウトは恒久的な希望ではありません。

根拠を確認する

関連するコードパス、設定、テスト、スクリプト、デプロイ用ファイル、既存のドキュメント、リポジトリの指示を確認します。履歴の経緯やリリースが対象となる場合は、Git の履歴を使用します。

変更を特定する前に、リポジトリの状態とタスクの実際の差分を確認します。作業ツリーに未コミットの変更がある場合は、無関係なユーザーの編集を保持し、既存の変更を今回のタスクの成果として記述しないでください。

記述を次のように分類します。

• 現在の事実： 現在のリポジトリまたは実行時の根拠によって証明されているもの。
• 合意済みの決定： 信頼できる決定記録に記されているか、ユーザーが明示的に確認したもの。
• 過去の事実： コミット、タグ、リリース、移行、または日付のある資料によって裏付けられているもの。
• 計画中の作業： 明示的に提案されているものの、まだ実装されていないもの。
• 不明： 未解決であり、その旨が明記されているもの。

裏付けがないまま、コミットメッセージ、古くなったドキュメント、使われていないファイル、もっともらしいアーキテクチャを現在の事実として扱わないでください。

必要最小限で役立つドキュメント構成を作る

docs/ のブートストラップや再構成を行うときは、references/documentation-map.md を読みます。ユーザーが継続性を支えるドキュメント一式を求めた場合は、必ずインデックスと3つの中核ドキュメントを作成します。専用セクションは、対応する根拠と保守上の価値がリポジトリにある場合に限り追加します。

自動変更記録は、より小規模なブートストラップです。ドキュメントの仕組みが存在しない場合は、docs/README.md、docs/implementation-timeline/README.md、安定した機能領域のサブフォルダーとそのインデックス、最初の検証済み変更記録だけを作成します。記録の既定動作を満たすためだけに、3つの中核ドキュメントを捏造して作成しないでください。

空のディレクトリ、プレースホルダーのガイド、想像上のサブシステムごとのファイルを作成しないでください。見栄えはよくても信頼できないツリーより、正確さを維持できる、相互にリンクされた小規模な構成の方が優れています。

検索しやすいドキュメントを書く

• 各ドキュメントでは、長期的に有効なテーマを1つ扱い、安定したパスを付けます。
• 各ドキュメントの冒頭に、目的、対象範囲、最後に検証したリビジョンまたは日付を記載します。
• 信頼できるコード、設定、コマンド、決定事項、関連ドキュメントにリンクします。
• すぐに古くなる網羅的なファイル一覧ではなく、担当範囲と境界を記録します。
• 正確なコマンドは、リポジトリ内の情報または安全な実行によって検証した後にのみ記載します。
• 現状と履歴、今後の作業を分けます。
• マッピング、決定事項、インターフェース、コマンドには簡潔な表を優先し、根拠や制約には文章を使います。
• 変更されやすい契約の信頼できる情報源を明記し、生成されたスキーマ、コマンド出力、設定一覧を手作業で重複させないようにします。
• 担当範囲と更新のきっかけを明確にします。ドキュメントが古くなる可能性のある事象と、メンテナーがどこで確認できるかが分かるようにします。

ドキュメントのインデックス、プロジェクトのコンテキスト、アーキテクチャ、または決定事項の記録を作成する際は、references/core-files.md を読んでください。

履歴を慎重に再構成する

コミット、リリース、移行、または以前のドキュメントを使ってタイムラインや引き継ぎ資料を作成する際は、references/history-and-handoff.md を読んでください。

変更は、その結果とアーキテクチャ上の影響を要約します。すべてのコミットを列挙したり、コミットの順序を因果関係として扱ったり、関連コードが一時的にブランチに含まれていたという理由だけで機能がリリースされたと主張したりしないでください。安定した識別子がある場合は、事実をコミットまたはタグにリンクします。

すべてを書き換えずに同期する

変更後は、記述が不完全または誤りになったドキュメントのみを更新します。有用な履歴を維持し、リポジトリで追記型の記録を採用している場合は、決定事項を追記します。現状が変わった場合は、現状の説明を置き換え、両方の説明が有効であるかのように残さないでください。

ドキュメントの記述が動作中のコードや設定と矛盾する場合は、次の手順に従います。

1. そのコードパスが有効であることを確認します。
2. 承認済みの保留中の移行または例外がないか確認します。
3. 権限がある場合は、古くなったドキュメントを更新します。
4. 未解決の矛盾について、どちらかの説明を優先して選ぶのではなく報告します。

記録と同期は関連していますが、別の作業です。重要な実装は、原則として簡潔なタイムライン記録に残します。現状のアーキテクチャ、決定事項、ガイド、ビルド関連ドキュメントは、その記述や手順が実際に変わった場合にのみ更新します。

検証する

• 変更したドキュメントをすべて再度開き、相対リンクをたどって確認します。
• コマンド、パス、名前、バージョン、担当範囲を最新の情報源と照合します。
• ルートインデックスから、保守対象のすべてのドキュメントに到達でき、プレースホルダーを参照していないことを確認します。
• 差分を確認し、シークレット、認証情報、非公開のインフラ詳細、個人データ、コピーされたログがないことを確かめます。
• ドキュメントの記述が、現在のタスクの証拠で裏付けられる作業のみを扱い、無関係な作業ツリーの未コミット変更を取り込んでいないことを確認します。
• 確認した証拠、変更したドキュメント、履歴上の制限、未解決の不明点を報告します。