docs 整理ルール

このディレクトリは、プロジェクトの設計・開発・運用に関するドキュメントを置く場所です。迷ったときは、まず ドキュメントトップ から目的別の入口を確認し、各カテゴリの README で正本と補助資料の扱いを確認してください。

この階層に置くもの

• 複数カテゴリにまたがるドキュメントの入口、索引、整理方針
• カテゴリをまたいで参照される正本ドキュメントへの案内
• 置き場所を判断するためのカテゴリ説明

個別の設計、手順、調査メモは、目的に合うカテゴリ配下へ置きます。カテゴリが曖昧な場合は、利用者が最初に探す文脈を優先します。

正本ドキュメント

正本は、同じテーマについて最終的に参照すべき文書です。新しい資料を追加する前に、既存の正本を更新できないか確認してください。

領域	正本・入口
設計書の置き場所、ID、一覧	機能設計ドキュメント
アーキテクチャ方針	アーキテクチャ
CI 運用	CI
テスト・品質確認	テスト
ローカル実行コマンド	開発コマンド一覧
品質ツール設定	品質設定ドキュメント
デプロイ	デプロイ
環境構築・同期	環境
運用メモ	運用
障害対応・調査	トラブルシューティング

補助資料・履歴資料の扱い

補助資料は、正本の判断を助ける調査メモ、移行記録、作業ログ、過去の検討経緯です。補助資料を追加する場合は、冒頭に「どの正本を補足する資料か」を書き、正本側にも必要に応じてリンクを追加します。

履歴資料は、現在の手順や仕様を上書きしません。現在の判断に使う内容が残っている場合は、履歴資料ではなく正本へ移してください。

docs/_* で始まるディレクトリは、原則として作業計画や完了済み移行手順などの履歴保存用です。現役の本番作業では、まず docs/deploy/、docs/environment/、docs/operations/ の正本を参照し、履歴資料を使う場合は冒頭の注意書きと関連する正本リンクを確認してください。

過去の調査メモは、現在も使う計測手順や運用手順と同じカテゴリに残す場合があります。その場合も、調査メモ側の冒頭に「参考」「履歴」「現役手順ではない」などの位置づけを書きます。

命名と表示名

設計書や一覧のファイル名には、管理用 ID や検索しやすい語を含めることがあります。ただし、ドキュメント上の表示名はファイル名や ID よりも論理名を優先します。たとえば SC-001_日別記事結果ショートコード.md は、本文や一覧では「日別記事結果ショートコード」として扱います。