/docs 運用ルール¶

このファイルは、/docs 配下の配置・更新・検証の基本ルールです。受け入れ側が判断しやすく、かつ現在の実装・運用と整合する状態を保つことを目的にします。

基本原則¶

要件の根拠は必ず docs/specifications/ の原本に置く。
原則として日本語で記述する。
根拠のない数値や見積を本文へ書かない。
Admin UI という表現は使わない。運用画面は Vendure Dashboard、React 製の管理画面配備面は React Dashboard と表記する。
同じ趣旨の文書を増やさず、既存文書への統合を優先する。

変更内容と更新先¶

変更の種類	更新先
要件・受入条件の変更	`docs/specifications/` の原本確認のうえ、`docs/01-requirements/` と関連ポータル
設計判断・データモデル・API 方針の変更	`docs/02-design/`、必要に応じて `docs/technical-specifications/`
実装手順・運用手順・インフラ構成の変更	`docs/03-implementation/`、`docs/development-guide.md`、`docs/infrastructure-and-environment.md`
進捗、課題、検収準備、合意事項の変更	`docs/04-project-management/`
マニュアル、引き継ぎ、保守手順の変更	`docs/05-delivery/`
追加提案・拡張候補の変更	`docs/06-optional-features/`
Frontend の UI 方針・実装パターンの変更	`docs/07-frontend/`、`docs/02-design/`、`docs/03-implementation/frontend/`
データ移行・インポート手順の変更	`docs/migration/`、必要に応じて `docs/03-implementation/`
顧客共有用・対外説明用の資料	`docs/client-documents/`
技術検証・比較・調査メモ	`docs/technical-analysis/`

現在のディレクトリ運用¶

パス	役割
`docs/index.md`	ドキュメントポータル。目的別・役割別の入口
`docs/project-overview.md` / `docs/development-guide.md` / `docs/development-standards.md` / `docs/infrastructure-and-environment.md`	ルート直下の横断ガイド
`docs/specifications/`	要件判断の原本。PDF / Excel / DOCX などの一次情報
`docs/01-requirements/`	整理済み要件、補足要件、トレーサビリティ
`docs/02-design/`	設計判断、アーキテクチャ、設計方針
`docs/03-implementation/`	実装詳細、運用手順、実装ガイド
`docs/04-project-management/`	スケジュール、課題、週報、進捗、会議録
`docs/04-project-management/progress/`	進捗台帳。配下の `AGENTS.md` を正本とする特別領域
`docs/05-delivery/`	マニュアル、保守、引き継ぎ、納品資料
`docs/06-optional-features/`	追加開発候補、将来拡張
`docs/07-frontend/`	Frontend の UI / プレビュー環境ルール
`docs/client-documents/`	顧客向け・対外共有前提の資料
`docs/plans/`	共有対象の計画書・検討計画。作業メモの置き場にはしない
`docs/migration/`	移行・インポート・データ移送に関する資料
`docs/technical-analysis/`	技術検証、比較、調査メモ
`docs/technical-specifications/`	実装に近い確定技術仕様の補助領域
`docs/archive/`	廃止・旧版資料の保管
`docs/images/`	図版、スクリーンショット、ダイアグラム

命名と導線の安定化ルール¶

repo 管理対象の docs/ 配下のファイル名・ディレクトリ名は、原則 ASCII の lowercase kebab-case を使う。
AGENTS.md / README.md / index.md のような固定慣例名は例外として維持する。
docs/specifications/ の一次情報、docs/client-documents/ の受領資料、外部ツールや upstream が名称を規定するファイルも例外とする。
docs/ 直下はポータル/索引/横断ガイドと補助領域のみに使い、詳細テーマのために新しいトップレベルディレクトリを増やす前に既存 taxonomy へ収める。
docs/index.md は全体ポータル、docs/05-delivery/index.md は検収・運用・引き継ぎの共有導線として役割を分け、優先読者（検収担当 / システム管理者・運用担当 / 引き継ぎ開発者・保守担当）はまず docs/05-delivery/ 側へ案内する。
番号付き主要セクション（01-requirements/〜07-frontend/）は index.md を必須とする。
補助領域（images/, migration/, plans/, technical-analysis/, technical-specifications/ など）は、所有する親文書やポータルから辿れることを優先し、直接 browsable hub として扱う場合だけ index.md を追加する。
docs/ 直下の新規トップレベルディレクトリを追加・改名する場合は、少なくとも docs/index.md と .mkdocs/dev.yml を同時更新し、仕様書サイトにも載せるべき内容なら .mkdocs/spec.yml も同期する。

更新時の必須作業¶

先に docs/AGENTS.md と対象ディレクトリ配下の AGENTS.md を確認する。
docs/specifications/ またはユーザー指定の情報源から根拠を確認する。
対象文書だけでなく、必要な index.md、ポータル文書、関連ハブを更新する。
ナビゲーションに影響する場合は、以下の設定も同期する。
.mkdocs/dev.yml
.mkdocs/spec.yml
apps/docs-site/cloudflare.yml

MkDocs / Cloudflare Pages の現行構成¶

開発用ドキュメントサイト
設定ファイル: .mkdocs/dev.yml
出力先: apps/docs-site/dist/site
主なコマンド: just docs-serve, just docs-build
仕様書サイト / PDF
設定ファイル: .mkdocs/spec.yml
出力先: apps/docs-site/dist/specification-site, apps/docs-site/dist/specification-book.pdf
主なコマンド: just docs-spec（公式納品物 PDF の確認を含む）
Cloudflare Pages 配備物
設定ファイル: apps/docs-site/cloudflare.yml
出力先: apps/docs-site/dist
主なコマンド: just docs-deploy staging, just docs-deploy production, just docs-deploy manual
位置づけ: 顧客共有用の絞った導線。検収・管理運用中心

検証ルール¶

Markdown の整形・記法確認: pnpm exec markdownlint-cli2 "docs/**/*.md" "README.md"
開発用サイトの確認: just docs-build
仕様書側にも影響する変更の確認: just docs-spec
Pages 配備手順や apps/docs-site/ の更新を含む場合: pnpm run docs:deploy:manual

アーカイブ方針¶

現行でなくなった文書は削除せず、必要に応じて docs/archive/ へ移す。
アーカイブ冒頭には、少なくとも以下を明記する。
置換先
廃止理由
当時の適用範囲や参照文脈
現行の正本として参照してほしくない文書は、アーカイブ先と置換先が一目で分かる状態にする。

補足¶

docs/04-project-management/progress/ の台帳運用は、配下の AGENTS.md を正本とする。
docs/specifications/ の原本は改変しない。必要な整理や補足は別文書へ反映する。
新規文書を追加した場合は、少なくとも対応する index.md から辿れる状態にする。

/docs 運用ルール¶

基本原則¶

最新性の扱い¶

変更内容と更新先¶

現在のディレクトリ運用¶

命名と導線の安定化ルール¶

更新時の必須作業¶

MkDocs / Cloudflare Pages の現行構成¶

検証ルール¶

アーカイブ方針¶

補足¶