コンテンツにスキップ

docs/ 配下の運用ルール（受け入れ側視点 / Agent向け）

この docs/ ディレクトリ配下でドキュメントを追加・更新する際のルールです。本リポジトリの docs/ は「開発者向けの設計書」ではなく、受け入れ（検収）側が判断できることを重視した文書を優先します。

受け入れ側視点（最優先）

  • 受け入れ担当者が「何をどう確認し、どうなればOKか」を判断できるように書く。
  • 観察可能な結果（画面/出力/ファイル/ログ/操作の成功/失敗）を優先する。
  • 内部実装（クラス名、関数名、アーキテクチャ詳細）は必要最小限の補足に留める。
  • 受け入れの論点と、実装・技術・開発都合の論点を混在させない。
  • 実装方針・作業手順・開発者向け詳細は、必要な場合のみ別文書へ分離する。

共通ルール

  • 原則、日本語で記述する（引用・固有名詞は除く）。
  • 根拠のない数値（推測の工数/期間/件数など）を本文に書かない。
  • “Admin UI” という表現は使用しない（管理画面は Vendure Dashboard と呼称する）。

命名とディレクトリ安定化

  • repo 管理対象として追加する docs/ 配下のファイル名・ディレクトリ名は、原則 ASCII の lowercase kebab-case を使用する。
  • 例外は、AGENTS.md / README.md / index.md のような固定慣例名、 docs/specifications/ の原本、docs/client-documents/ の受領資料、外部サービスや upstream が名称を規定するファイルに限定する。
  • docs/ 直下はポータル/索引/横断ガイドと補助領域だけを置き、詳細文書のために新しいトップレベルディレクトリを安易に増やさない。
  • 番号付き主要セクション（01-requirements/〜07-frontend/）は index.md を必須とする。補助領域（images/, migration/, plans/, technical-analysis/, technical-specifications/ など）は、直接 browsable hub として扱うときだけ index.md を追加する。

ドキュメント作成・更新

  • 新規ファイルを作る前に、同趣旨の既存ドキュメントがないか検索して重複を避ける。
  • docs/ 直下はポータル/索引/横断資料を中心にし、詳細は適切なサブディレクトリへ置く。
  • 変更後は必要に応じて索引（例: 各 index.md）や MkDocs ナビゲーションの参照が切れていないか確認する。
  • キャッシュ方針の更新: Storefront / Vendure / Cloudflareのキャッシュ挙動を変更した場合は、docs/specifications/ の正本と docs/03-implementation/infrastructure/cache-strategy.md を同時に更新し、local / mock と production / staging / preview の差分、および public/private の境界を明記する。
  • マイルストーン変更や計画修正を行う場合は、対象ドキュメントの本文（前提/目的/完了条件/依存関係）まで精査し、関連ドキュメント（索引・スケジュール・運用手順・受け入れ観点など）の整合性が取れるように更新する。

アーカイブ方針（過去記録）

受け入れ側のトレーサビリティ確保のため、meetings/ 等の過去記録は アーカイブ（当時の事実）として扱います。

  • 実装変更・仕様変更があっても、過去記録を「現在の正」に合わせて書き換えない（改ざん防止）。
  • 誤りが判明した場合は、当該記録を直接書き換えるのではなく、追記（追補）で訂正内容・日付・理由を残す。
  • 現在の仕様/判断を示す必要がある場合は、別の「現行ドキュメント（原本）」に反映し、過去記録からはリンクで参照する。

要件の情報源（重要）

  • /docs/specifications/ 内の元仕様書（PDF/Excel/DOCX）およびユーザーが指定した情報源のみを「要件」の根拠として扱う。
  • 仕様書に無い事項は「未確認」として扱い、推測で要件化しない。

進捗・検収（04-project-management/progress）

  • 進捗/検収の原本は、対象ディレクトリ配下の AGENTS.md（より深い階層のルール）に従う。
  • dogfooding 記録は docs/04-project-management/progress/dogfooding/ に集約し、発見した問題は原則として GitHub Issue を起票して相互リンクする。
  • Excel/画像などのバイナリ資料を追加する場合も、docs/ 配下に格納し、リンクを index.md から辿れるようにする。