執筆・運用ルール

このサイトは資料が増えるほど価値が出ますが、無秩序に増えると逆に探せなくなり死蔵します。肥大化を防ぐための最小限のルールを定めます。迷ったらこのページに戻ってください。

大原則

1ページ＝1つの問いに答える。 「これは何の話か」を1文で言えないページは分割するか統合する。
元資料の丸写しをしない。 PDFをそのまま貼るのではなく、「作り変えに必要な事実」に要約する。原本は _archive/（Git管理外）に置き、必要なら出典として参照する。
事実と推定を必ず区別する。 資料に書いてある事実か、DBやコードからの推定かを :::note / 「〜と推定」で明示する。
重複は1箇所に集約してリンクする。 同じ説明を2ページに書かない。正本を決め、他からはリンクする。
増やす前に、まず既存ページに追記できないか考える。 新規ページは「既存のどこにも入らない」ときだけ作る。

情報構造（IAの固定枠）

トップの構造は次の9群に固定します（正本は astro.config.mjs の sidebar 定義）。新しいトップ階層を増やさないでください。新ページは必ずどれかの配下に入れます。

枠	役割	入れてよいもの
はじめに	入口・横断	全体像（index）、用語集（glossary）
リリース計画	いつ・何を作るか	フェーズ管理、ロードマップ、確認事項（redesign/scope-phasing, redesign/roadmap, redesign/open-questions）
全体設計	新CRMの土台	設計全体像、データモデル、役割・権限、ベースデータ、フォーム一元化、共通タスク、連携、用語統一（redesign/overview, data-model/entities-phase1, redesign/roles-phase1, redesign/base-data, redesign/forms, redesign/tasks, redesign/integrations, redesign/terminology）
機能仕様	機能ごとの詳細	1機能＝1ページ。要件＋設計＋実装状況（features/events, features/item-master, features/wholesale, features/wholesale-settlement, features/crm-core, features/quote-pricing, features/kpi-forecast, features/chat-collab, features/ai-agent）
ValueOS（クライアントERP）	クライアント既存基盤の事実	概要・アーキテクチャ、データモデル、業務フロー、差分・突合（valueos/overview, valueos/data-model, valueos/workflow, redesign/valueos-gap）
移行・将来	移行手順と将来像	データ移行計画、将来構想（redesign/migration-plan, redesign/future-vision）
定例会・意思決定ログ	決定の経緯	定例会議事録（redesign/meeting-log）
参考：旧CRM（BT社・不採用）	旧提案の記録（不採用）	下記の5サブ枠のみ
このサイトの育て方	運用ルール	このページ（contributing）

「参考：旧CRM（BT社・不採用）」だけは内部にさらに5つのサブ枠を持ちます。旧提案の記録という性質上、新設計側とは分けて格納するための例外構造です。

サブ枠	入れてよいもの
前提・背景	会社・組織、業務フロー（現状）、評価・インセンティブ、予実管理（background/company, background/business-flow, background/evaluation, background/budget-actuals）
CRM要件	提案の出発点、要件定義サマリ、機能と実装状況（requirements/proposal, requirements/definition, requirements/status）
機能別仕様	旧CRMのKPI・試算・チャット・データ移行・バックオフィス自動化（features/kpi-dashboard, features/estimation, features/chat, features/data-migration, features/backoffice-automation）
データモデル	スキーマ概要、テーブル定義（data-model/overview, data-model/tables）
ベンダー・契約	見積・費用まとめ、インフラ構成（vendor/estimates, vendor/infra）

ファイル・命名規約

置き場所：src/content/docs/<枠ディレクトリ>/<kebab-case>.md
ファイル名は英語の kebab-case（例：business-flow.md）。日本語ファイル名は禁止。
表示名・本文は日本語。title は名詞句で簡潔に。
サイドバー登録は astro.config.mjs の sidebar で明示的に行う（自動生成は使わない＝並び順と労力を管理者が制御するため）。
1ページの目安はスクロール5〜7画面以内。超えたら分割を検討。

フロントマター規約

---
title: ページ名（名詞句）
description: 1文でページの内容（検索・SNS用、80字程度）
---

description は必須。「このページは何に答えるか」を1文で書く。
フロントマターに sidebar キーは使わない。並び順・所属枠は astro.config.mjs の sidebar 配列だけで管理する（ページ側の個別指定を禁止し、管理者が一元制御するため）。
仕様の確定度が低い項目は本文で :::caution を使って明示する。

機密情報の扱い（厳守）

このプロジェクトの元資料には 本番認証情報 と 実顧客の個人情報 が含まれます。次を厳守してください。

.env の実値、DBパスワード、APP_KEY、実在の顧客氏名・住所・電話・メールを 本文に書かない／コミットしない。
構成を示す必要があるときは <DB_PASSWORD> のようなプレースホルダに置換する。
DBの実データ（INSERT）は載せない。載せるのは**構造（カラム・コメント）**のみ。
原本・生抽出テキストは _archive/ に置く。_archive/ は .gitignore 済み。この除外を外さない。

ステータスの書き方（実装状況）

「できている／できていない」を書くときは、根拠と確度を添えます。

バッジ	意味	根拠の例
実装済	DBテーブル・カラムが存在し稼働が確認できる	スキーマに該当テーブルあり
部分／設計のみ	一部のみ、または設計・見積はあるが未確認	集計元データはあるが画面・設定が不明
未実装	要件・見積はあるがDB等に痕跡がない	該当テーブルなし＋別途見積で提示
未確認	資料からは判断不能	—

確度が「推定」なら必ずそう書く。断定は実コード確認後に格上げする。

レビューの軽い基準

ページを追加・更新したら、自分で次を確認してください。

このページの問いを1文で言えるか
どこかと内容が重複していないか（重複なら集約してリンク）
事実／推定の区別がついているか
機密（実値・実PII）が混入していないか
サイドバーに正しい枠で登録したか

ローカルでの起動

# Node 22 系が必要（fnm use 22 など）
npm install
npm run dev      # http://localhost:4321
npm run build    # 本番ビルド（リンク切れ等の検査を兼ねる）