/docs ルールガイド（ディレクトリ別）¶

このファイルは、/docs 配下の各ディレクトリに「どんなドキュメントを」「どう記述するか」を定義する運用ルールです。新規作成や更新の前に必ず確認してください。

重要原則（AGENTS.md 準拠）

要件は /docs/specifications/ 内の元仕様（PDF/Excel/DOCX）を唯一の根拠（Single Source of Truth）とする。
要件定義と技術選定・実装計画は完全に分離する。
根拠のない数値を記載しない。見積・計画の単位は人日（1 人日 = 8 時間）で統一。
新規ファイル作成前に、既存ドキュメントの重複有無を確認し、乱立を防止する。
MkDocs のナビ更新・ビルドルール（下部参照）を遵守する。

実装同期ルール（最新性の担保）¶

原則：/docs は現在の実装・運用に整合する最新情報を提示する。
乖離が発生した場合は「更新」または「アーカイブ」のいずれかで解消する。
更新が可能な場合は、該当ドキュメントを最新実装に合わせて改訂する。
機能廃止・設計置換などで不適合となった資料は /docs/archive/ に移動し、置換先を明示する。
要件定義書（requirements-specification.md）は例外的に「顧客の元仕様を忠実に反映」する役割のため、実装が先行して乖離が出た場合は、要件書を直接修正せず、以下で管理する：
乖離の事実を 04-project-management/ で課題・変更要求として記録（承認後に元仕様・要件書を更新）。
実装上の暫定差分は 02-design/ に「実装差分メモ」として記載し、要件側には反映しない。

影響のあった変更に対する更新先（マッピング）

API/スキーマ/データモデルの変更 → 02-design/ と technical-specification.md
ビルド/運用/監視/リリース手順の変更 → 03-implementation/
UI/UX や画面遷移の変更 → 02-design/（画面設計）
顧客向けの対外説明が必要な変更 → mediator-documents/ に反映の可否を検討
仕様（要件）の変更 → 元仕様（/docs/specifications/）の更新を前提に requirements-specification.md を改訂

PR/レビュー時チェックリスト（推奨）

公開仕様/API/データ構造に変更はあったか → 02-design/ 更新
手順・運用に影響はあったか → 03-implementation/ 更新
顧客に伝達が必要か → mediator-documents/ 検討
要件の変更か単なる実装差分か → 後者は 02-design/ の差分メモ、前者は変更要求を起票

アーカイブ手順（簡易）

当該ファイルを /docs/archive/ へ移動し、冒頭に以下を明記：
置換先（最新版の場所）
最終適用対象（対応コミット/タグや運用期間の記述）
廃止理由/背景

ルート直下（/docs の直下）¶

index.md
ドキュメントサイトのトップ。プロジェクト概要、目次、更新履歴（簡易）を記載。
技術選定や実装詳細は記載しない（概要リンクのみ）。
requirements-specification.md
技術中立の要件定義書（顧客のビジネス要件・機能要件・非機能要件・データ仕様・法的要件）。
記載禁止：具体的プラットフォーム名、技術スタック、実装方針・開発計画、開発体制。
出典は必ず /docs/specifications/ の原本に限定し、章末に出典を明記。
プラットフォーム選定統合資料.md
プラットフォーム比較・選定の唯一の統合資料（Single Source of Truth）。
新情報・分析はすべて本ファイルに追記。新規の比較ファイルは作成禁止。
作成禁止ファイル名例：platform_comparison_*.md、プラットフォーム比較*.md、プラットフォーム代替案*.md、プラットフォーム実現可能性*.md。
例外：特定プラットフォーム個別の詳細技術検証は /docs/technical-analysis/ 配下で可。
platform-selection.md
既存の場合は「統合資料へのリダイレクト・差分メモ」のみに限定し、内容の二重化を避ける。
新規作成禁止。内容は順次 プラットフォーム選定統合資料.md に統合する。
technical-specification.md
技術仕様の集約（アーキテクチャ、API 方針、データモデル、運用要件など）。
要件の再記載は禁止。要件との関係は参照リンクで示す。
implementation-plan.md
実装計画（フェーズ案、WBS 概要、テスト計画、移行方針、リリース手順）。
工数は人日表記で根拠を付す。未確定事項は「検討中」と明記。

01-requirements/¶

目的：要件定義作業の成果物を体系化（ユースケース、業務フロー、画面要求、用語集等）。
出典：要件の根拠は必ず /docs/specifications/ の原本とし、各ファイル末尾に出典を明記。
requirements-specification.md（ルート直下）が唯一の要件集約先。重複する全文コピーは禁止（必要箇所はリンク参照）。
記載禁止：プラットフォーム名、アーキテクチャ記述、実装計画、見積詳細。
推奨構成例：
use-cases.md（ユースケース一覧：アクター、前提、基本/代替フロー）
business-flows.md（BPMN/フローチャート画像は /docs/images/ に格納して参照）
screen-requirements.md（画面要件：目的、入出力、バリデーション、権限）
glossary.md（用語集：原典と業務上の定義）

02-design/¶

目的：技術設計（要件に対するソリューション設計）。
記載範囲：アーキテクチャ、モジュール設計、API 設計、データモデル、非機能設計、監視運用設計。
参考の集約先は technical-specification.md。本ディレクトリは詳細版・分割版として運用し、重複を避ける。
図表は /docs/images/ を参照（ファイル命名規則に従う）。

03-implementation/¶

目的：実装計画と手順の具体化（ただし要件の再掲は禁止）。
記載範囲：WBS 詳細、マイルストーン、テスト観点、移行手順書、ロールバック手順、リリース計画。
見積は人日で記載（根拠・前提条件を明記）。時間単位の表記は禁止。
集約先は implementation-plan.md。詳細は本ディレクトリに分割し、相互リンクで一貫性を担保。

04-project-management/¶

目的：プロジェクト運営情報（対外共有前提の情報は慎重に扱う）。
記載範囲：計画・体制・リスク・課題・決定事項・会議メモ・品質指標・コミュニケーション計画。
顧客向けの表現が必要な資料は /docs/mediator-documents/（仲介者向け）へ振り分ける判断基準を明記。
未確定事項は「検討中」とし、確定と混在させない。

05-delivery/¶

目的：納品・引き渡し関連のドキュメント。
記載範囲：受け入れ基準、引き渡し手順、運用開始チェックリスト、トレーニング資料索引。
生成物（HTML/PDF）は格納しない。ビルド成果物は deliverables/ 配下（運用ルールは下記）。

mediator-documents/¶

対象：仲介者（代理店・コンサルタント）向け資料。
記載方針：
バランスの取れた情報（メリット/デメリット）。
技術的実現性と制約の明確化。
スケジュール・体制・リスクの客観的提示。
顧客説明に使える平易な表現と根拠提示。
禁止：競合他社の過度な批判、未確定仕様の断定、内部課題の詳細暴露。

archive/¶

目的：廃止・旧版ドキュメントの保管。
方針：廃止理由・置換先・最終有効日を先頭に記載。現行への参照は禁止（警告を明記）。
ファイル命名：<元パス>__<YYYY-MM-DD>__archived.md など、追跡可能に。

images/¶

用途：ドキュメント内で参照する図版・スクリーンショット・ダイアグラムの格納。
命名規則：<カテゴリ>-<短い説明>-<YYYYMMDD>.<拡張子>（例：req-usecase-overview-20250917.png）。
品質：適切な解像度に最適化（過大サイズ禁止）、代替テキスト（alt）を必ず記述。
参照方法：相対パスで Markdown から参照。キャプションに出典を明記。

slides/¶

用途：プレゼンテーション資料（PPTX/Key/Google Slides エクスポート）。
運用：主要版は PDF を併置し、版数・日付・配布対象を先頭に明記。
機微情報：対外配布可否をファイル冒頭に明示。

specifications/（未作成の場合の取り扱い）¶

役割：要件の唯一の情報源（原本：PDF/Excel/DOCX）。
追加時の初期構成例：
基本仕様書.pdf、業務について.pdf、要件概要追加項目追記済み.pdf
BtoB発注システム要件 (最新).xlsx、キャンペーン.xlsx
README.md（収録物の目録と改訂履歴）
注意：このディレクトリ内の原本は改変禁止。要件書側に要約・参照を行う。

technical-analysis/（必要時に作成）¶

用途：特定プラットフォーム名を含む個別の詳細技術検証。
命名例：shopify-plus-storefront-api-evaluation.md のように対象が明確なもの。
禁止：プラットフォーム比較・選定の横展開（比較は統合資料に一本化）。

MkDocs 運用ルール（共通）¶

構成ファイル：mkdocs.book.yml（仕様書用）、mkdocs.site.yml（開発用）。
出力先：
仕様書サイト/冊子：deliverables/specification-site/、deliverables/specification-book.pdf
開発用サイト：docs-site/site/
ビルド手順：
仕様書生成：pnpm docs:spec
開発用生成：pnpm docs:build
開発サーバー：pnpm docs:serve
更新手順：
/docs/ に新規セクションや index.md を追加
必要に応じて mkdocs.site.yml / mkdocs.book.yml のナビを更新
pnpm docs:build / pnpm docs:spec を実行して警告を確認
未参照ファイル・リンク切れ警告は解消してからレビュー依頼

記述スタイル（共通）¶

言語：日本語を基本。技術略語は初出で定義。
数値：根拠のない数値は記載しない。見積は人日で統一（1 人日 = 8 時間）。
参照：原典（/docs/specifications/）の明示、相対パスリンクの使用。
重複禁止：同内容の乱立を避け、集約先（本ルールで指定）へ統合。
版管理：冒頭に「作成日・改訂日・作成者・レビュー者・承認者」を記載。
対外/内部：対外公開前提の資料はトーンを調整し、機微情報は削除または別管理。

追加メモ¶

既存の platform-selection.md は移行期間のブリッジとして扱い、内容は順次 プラットフォーム選定統合資料.md に統合してください。
/docs/specifications/ が未整備の場合、原本追加後に requirements-specification.md の出典を追記してください。