プロジェクトのドキュメント作成・管理の唯一の信頼できる情報源

Document Architecture Bible

1. はじめに

このドキュメントは、本プロジェクトにおけるドキュメント作成および管理に関する**唯一の信頼できる情報源（Single Source of Truth）**です。すべてのドキュメントは、ここに記された原則と規則に基づいて作成・維持される必要があります。

目的:

プロジェクトの知識を体系的に集約し、情報のサイロ化を防ぐ。
新規参画者が迅速にプロジェクトを理解できるような道筋を提供する。
AIアシスタントを含むすべての開発者が、一貫した方法でドキュメントをメンテナンスできるようにする。

1.1. AIアシスタントへの最重要指示

【警告】すべてのコード変更タスク（機能実装、バグ修正、リファクタリング等）を開始する前に、必ず以下のドキュメントを読み込み、その内容を完全に遵守してください。

00_philosophies_of_blueperiod: プロジェクトの根本思想、Deep MCP の定義、設計哲学。すべての判断の最上位基準。
06_development_guidelines.md: コーディング規約、命名規則、コンポーネント設計、状態管理などの基本方針。
09_design_system.md: デザイン哲学、カラースキーム（セマンティックトークン）、レスポンス戦略、UIパターン。

これらを無視して実装されたコードは、プロジェクトの一貫性を損なうため、受け入れられません。タスクに着手する思考プロセスの第一歩として、必ずこれらのガイドラインの確認を組み込んでください。

1.1.1. パッケージマネージャーに関する重要な注意事項

本プロジェクトはBunを使用します。npmではありません。

パッケージインストール: 必ず bun install を使用してください。npm install は使用しないでください。
スクリプト実行: bun run <script> を使用してください。
依存関係の追加: bun add <package> を使用してください。
Bun移行: 2026年3月にnpmからBunに移行済みです。詳細は 02_technology_stack.md を参照してください。

2. ディレクトリ構造

ドキュメントは、その性質に応じて以下のディレクトリに分類・格納されます。

2.1. ドキュメントサイト（Fumadocs）

fumadocs/ — Next.js + Fumadocs によるドキュメントサイト
- fumadocs/content/docs/: 全ドキュメントのSSOT（Fumadocs MDX形式）
  - system/: プロジェクトの根幹をなす永続的で普遍的な情報。旧 doc/system/ から移行済み。
    - system/components/: コンポーネント仕様書
    - system/agent_skills/: AIエージェントスキル定義
    - system/troubleshooting/: トラブルシューティング・ガイド・参考
  - getting-started/: 初めての方へ（ユーザー向け）
  - writing/: 執筆機能ガイド（ユーザー向け）
  - publishing/: 公開機能ガイド（ユーザー向け）
  - data-and-sync/: データと同期ガイド（ユーザー向け）
  - mcp/: MCP連携ガイド（ユーザー向け）
- fumadocs/content/docs/*/meta.json: 各セクションのサイドバー定義（タイトル、アイコン、ページ順序）
- Vercelプロジェクト: docs.blueperiod.blue（LP: blue.blueperiod.blue とは完全独立）
- 相互リンク: LPヘッダーにDocsリンク、DocsヘッダーにLPリンク

WikiLinksの二段構え方式:

リポジトリ内（Foam）: [[page-name]] をそのまま維持。グラフビュー・バックリンク・補完が動作
ビルド時（Fumadocs）: remark-wiki-link がWikiLinksをページリンクに変換して出力

2.2. 開発ログ（未移行）

/doc/log/
- 目的: 日々の開発活動に関する**時系列の記録（ログ）**を格納します。
- 構造: 年・月単位のサブディレクトリで階層化し、肥大化を防ぎます。
  - 例: /doc/log/reports/2025/12/
- 内容:
  - issues/: 解決すべき課題、機能要望、バグ報告（すべての出発点）。
  - plans/: 課題に対する具体的な解決策、設計、実装計画。
  - reports/: 実装完了後の記録、変更内容の要約。
  - decisions/: 重要な意思決定の記録。
  - その他: reviews, audits, proposals, prompts など。
/doc/archive/
- 目的: 古くなった、あるいは現在では有効でないが、記録として残す価値のあるドキュメントを格納します。

2.3. ルート

/ (ルート)
- README.md: プロジェクトの入り口。

4. 命名規則

System Documents (`fumadocs/content/docs/system/`)

フォーマット: XX_topic_name.mdx
説明:
- XX: 2桁の数字。ドキュメントのカテゴリと順序を示します。（例: 01_, 02_）
- topic_name: ドキュメントの内容を端的に示す名前。（例: architecture, state_management）
例:
- 01_architecture.mdx
- 02_technology_stack.mdx
- 03_state_management.mdx

frontmatter（必須）: 各ファイルの先頭に title と description を定義

---
title: アーキテクチャ設計
description: BluePeriodの全体アーキテクチャ設計
---

meta.json: 各ディレクトリにサイドバー定義を配置（タイトル、アイコン、ページ順序）

Log Documents (`/doc/log/`)

パス規約: /doc/log/{type}/{YYYY}/{MM}/YYYY-MM-DD_HHmm_{type}_{description}.md
説明:
- {type}: ドキュメントの種類。（例: plans, reports, reviews, audits, references, proposals, prompts, issue）
- {YYYY}/{MM}: 作成時の年と月によるディレクトリ階層。
- YYYY-MM-DD_HHmm: ISO 8601形式の日付と時刻（24時間制）。
- {type}: 種類の区切りはアンダースコア _ で区切る。
- {description}: タイトル内はハイフン - で単語区切り。

区切り文字のルール:

YYYY-MM-DD_HHmm_type_title-keyword.md
│        │    │    │    │
│        │    │    │    └─ タイトル内は `-` で単語区切り
│        │    │    └──── 種類は `_` で区切り（report_, plan_, review_）
│        │    └───────── 時刻は4桁のHHmm形式
│        └───────────── 日付は ISO 8601 形式（ハイフン区切り）
└────────────────────── 全体の大区分は `_` で区切り

5. Frontmatter（必須）

/doc/log/ 以下のドキュメントには、先頭に以下の形式でFrontmatterを記載します。

---
title: プロンプトシステムの調査
date: 2025-12-31_1530
tags: [sync, prompt, investigation]
status: open
---

各フィールドの説明：

フィールド	必須	説明
`title`	Yes	ドキュメントのタイトル。簡潔かつ分かりやすい表現。
`date`	Yes	作成日時。ISO 8601形式 + 4桁時刻（`YYYY-MM-DD_HHmm`）。ファイル名の日時と一致させること。
`tags`	Yes	関連するタグの配列。検索・分類に使用。（例: `[sync, ui, bug-fix, feature]`）
`status`	Yes	ドキュメントの状態。（`open`

注: 以前存在した related フィールドは、二重管理防止とエディタのナビゲーション機能活用のために廃止されました。ドキュメント間のリンクは、本文末尾の「## 関連」セクションに記述します。

タグの命名規則：

小文字で記述
複合語はハイフン - で区切る（例: bug-fix, performance-improvement）
一般的なタグ例：
- 機能領域: sync, auth, publish, chat, reader
- 作業種別: bug-fix, feature, refactor, investigation, audit
- 技術要素: ui, db, api, llm, typescript

status の値と意味：

値	説明	使用場面
`open`	未解決 / 進行中	新規作成されたIssue、進行中のPlan
`close`	解決済み / 完了	完了したIssue、実装済みのPlan

※ 以前の `todo` / `done` は使用せず、今後は `open` / `close` に統一してください。

5.1. ドキュメント間リンク（WikiLinks）

本プロジェクトでは、VSCodeのネイティブ機能を最大限に活用するため、以下のリンク規約を採用します。

記法: ファイル名 (拡張子なしのWikiLinks形式)
- 重要: **バッククォート () で囲まないでください。** 囲むと ファイル名` のような「ただのコード表記」になり、Foam のグラフ機能やナビゲーション、リンク解決が正常に動作しません。
配置場所: 原則としてドキュメントの最末尾に「## 関連」または「## Related」セクションを作成し、そこに箇条書きで記述します。
メリット:
- ファイルをディレクトリ間で移動させても、VSCodeが名称ベースで解決するためリンクが壊れません。
- フロントマターにパスを記述する手間（二重管理）が省けます。
- Ctrl+クリックで即座に関連ドキュメントへ遷移できます。

なお開発体験の向上のために、VSCodeの拡張機能「Foam」を使用することを推奨します。

5.2. ファイル参照に関する規約 (Path Reference Policy)

ドキュメント内やAIとの対話において、IDE固有の長大な絶対パスや内部URI（cci:7://... 等）を記述することは厳禁です。可読性を保つため、以下の基準でパスを記述してください。

ドキュメント間のリンク:
- 必ずファイル名 (WikiLinks) 形式を使用してください。
- 禁止事項: バッククォートで囲むこと（例: [[01_architecture]] は不可）。プレーンテキストとして記述してください。
- 例: 01_architecture
プロジェクト内のソースコード等の参照:
- プロジェクトルート（/blueperiod/）からの相対パス、または単一ファイル名を使用してください。
- 良い例: next-app/src/app/page.tsx, package.json
- 悪い例: C:\Users\...\CharactersPageClient.tsx, cci:7://file:///...
外部URL:
- 通常のMarkdownリンク形式を使用してください。
- 例: [shadcn/ui](https://ui.shadcn.com/)

6. ドキュメント駆動開発（DDD）ワークフロー

本プロジェクトでは、GitHub Issues等の外部ツールを使わず、リポジトリ内のドキュメントによって開発サイクルを完全に管理します。「Issue → Plan → Report」の3点セットを揃えることを、本プロジェクトの「開発完了」の定義とします。

Issue (課題の定義 - 必須):
- フォルダ: /doc/log/issues/
- 役割: 「何が問題か」「何がしたいか」を定義する。
- ルール: 全ての開発タスクの起点。Issueが存在しない実装は許可されない。
Plan (設計と計画 - 推奨):
- フォルダ: /doc/log/plans/
- 役割: 技術的なアプローチ、変更ファイル、データ構造などを設計する。
- ルール: Issueへのリンクを含める。
- 特例: 軽微な変更（1ファイル程度の修正）の場合、Issue内に「Implementation Plan」を記述することで、個別のPlanファイルの作成を省略できる。
Report (完了報告 - 必須):
- フォルダ: /doc/log/reports/
- 役割: 最終的な実装内容、テスト結果、残課題を記録する。
- ルール: 関連する Issue および Plan へのリンクを含め、それらの status を close に更新する。

6.1. トレーサビリティの確保

各ドキュメントの末尾には「## 関連」セクションを設け、Issue, Plan, Report を相互にWikiLinks (ファイル名) で繋いでください。これにより、後から「なぜこのコードになったのか」という経緯を逆引きできるようになります。

レガシー・コンテキストの扱い

100万文字を超えるような過去の膨大なメモや、日付が不明なレガシーデータは、以下のルールで管理します。

Cold Storage: 整形せず /doc/log/issues/legacy/ 配下にダンプ。
Just-in-Time Retrieval: AIアシスタントがタスク開始時に適宜検索 (grep) して情報を掘り起こす。整理は行わない。
Promotion: 重要な項目のみ、今日の日付の正式な Issue として「昇格」させて管理する。

実践的な更新プロセスとシナリオ別ガイドは、document_maintenance を参照してください。

Document Architecture Bible

On this page