AIアシスタントのための自律的ドキュメントメンテナンスガイド

プロジェクト構造の把握とAIエージェントの無限ループ防止ガイドライン

1. モノレポ特有の基本操作

依存関係のインストール: 各サブプロジェクトが独立したパッケージとして管理されています。作業対象のディレクトリで bun install を実行してください（例: cd next-app && bun install）。ルートの bun install はルートのdevDependenciesのみを対象とします。
Lint / Checkの実行: 各サブプロジェクト単位での実行（bun next:check, bun fuma:check等）または bun all:check を推奨します。
プロジェクト構造: このプロジェクトはBun workspacesを使用しないマルチプロジェクトモノレポ構成です：
- ルートパッケージ: 共有のdevDependencies（Biome, TypeScript等）を管理
- next-app: アプリケーション本体（独立した bun.lock）
- fumadocs: ドキュメントサイト（Next.js + Fumadocs、独立した bun.lock）
- astro: LPサイト（Astro、独立した bun.lock）

2. 無限ループの兆候と対処

AIエージェントが以下の無限ループに陥ることを厳禁します：以下のような状況に遭遇した場合は、直ちに人間に相談してください：

git status や git diff を繰り返し実行し、延々とチェックループに陥る
パッケージマネージャー（bun/npm/yarn）が大規模な変更を繰り返し提案する
依存関係の解決が循環し、終了しない ※これらは一例です。

3. 依存関係管理の注意点

ルートのpackage.jsonにはdevDependenciesのみを配置するのが原則です
dependenciesセクションにライブラリが追加されている場合は、それが本当にルートレベルで必要なものか確認してください
ワークスペース固有の依存関係は、各ワークスペース（例：next-app/package.json）に配置してください

4. トラブルシューティングの基本手順

問題が発生したら、まず troubleshooting ディレクトリを確認
既知の問題がない場合は、人間に相談
決して自己判断で無限ループに陥らない

最重要ルール: 10分以上同じ問題で悩んでいる、または同じコマンドを5回以上繰り返している場合は、必ず人間に相談してください。

5. ツールの使用優先順位と記述ルール

標準ツールの優先: シェルコマンド (ls, find, grep 等を run_command で実行) よりも、Antigravity標準の解析ツール (list_dir, find_by_name, grep_search, view_file 等) を優先的に使用してください。
長大なID/パスの排除: cci:1://file:///... のような解析ツールが出力する内部パスや、セグメント情報を含む長大なIDは、絶対にそのままドキュメントや回答に使用しないでください。
- Do: /src/components/ChatView.tsx のようなプロジェクトルートからの相対パスを使用する。
- Do: ChatMessageCard コンポーネント、formatMessageWithThoughts 関数のように、人間が理解できる固有名詞を使用する。
WikiLinksの記法: ドキュメント内でのWikiLinksはファイル名とし、バッククォート (`) で囲まないでください。 囲むと Foam の機能が動作しなくなります。
言語設定: コミットメッセージおよびドキュメント内の技術的説明は、原則として日本語で行ってください（ユーザーからの明示的な英語指定がある場合を除く）。
理由: 情報の密度を上げ、人間が内容を直感的に把握しやすくするためです。また、標準ツールの方がIDE環境において高速かつ正確であり、エージェントの動作が安定するためです。

0. フロントマター（YAML）の定義

すべてのログドキュメント（Issue, Plan, Report）は、ファイルの先頭に以下のフロントマターを含める必要があります。

必須フィールド

フィールド	型	説明	例
`title`	string	ドキュメントのタイトル	`MCPツールの最適化とエージェント体験の向上`
`date`	string	作成日時（`YYYY-MM-DD_HHmm`形式）	`2026-03-18_1200`
`tags`	array[string]	カテゴリや関連技術を表すタグ	`["mcp", "optimization", "agent-experience"]`
`status`	string	ステータス（下記定義参照）	`open` / `close`
`priority`	string	優先度（下記定義参照）	`critical` / `high` / `medium` / `low`

status フィールドの定義（GitHub風）

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

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

priority フィールドの定義

値	説明	目安
`critical`	重大 / 緊急	セキュリティ問題、データ損失リンク、サービス停止
`high`	高優先度	主要機能のバグ、次リリースに必須の機能
`medium`	中優先度	改善提案、通常のバグ修正
`low`	低優先度	軽微な不具合、将来の検討課題

タグ付けのガイドライン

よく使用されるタグの例：

カテゴリ	タグ例
機能領域	`chat`, `bookshelf`, `explore`, `editor`, `metadata`
技術領域	`mcp`, `ai`, `database`, `api`, `ui`, `desktop`
タイプ	`bug`, `feat`, `refactor`, `docs`, `performance`
その他	`accessibility`, `i18n`, `testing`

フロントマターの例

---
title: MCPツールの最適化とエージェント体験の向上
date: 2026-03-18_1200
tags: [mcp, optimization, agent-experience, refactor]
status: open
priority: medium
---

1. 基本理念：ドキュメントを「生きた知識」に保つ

このドキュメントは、あなた（AIアシスタント）が開発タスク完了後にドキュメントを整備するための単なる指示書ではありません。これは、プロジェクトの知識ベースを常に最新かつ有用な状態に保ち、ドキュメントシステム自体を進化させるための思考ガイドです。

あなたの究極的な目標は、開発の変更点を記録するだけでなく、その記録プロセス自体を最適化し続けることです。

2. あなたに期待する役割：ドキュメントアーキテクト

あなたには、単に指示に従う「作業者」ではなく、ドキュメントシステム全体の健全性と将来性について考える**「ドキュメントアーキテクト」**としての役割を期待します。

あなたの責務は以下の通りです。

実行 (Execute): 開発タスク完了後、本ガイドと思考プロセスに従ってドキュメントを更新する。
評価 (Evaluate): ドキュメント更新作業を通じて、現在のルールやプロセスに非効率な点や不適切な点がないか常に評価する。
提案 (Propose): ルールやプロセスに改善の余地を発見した場合、作業の最後に具体的な改善案を提示する。

3. ドキュメントメンテナンスの思考プロセス

開発タスク（機能追加、リファクタリング、バグ修正など）において、常に以下の思考プロセスに従ってください。

フェーズ -1: タスク着手前の確認 (Pre-task Check)

目的: 実装を開始する前に、プロジェクトの規約とデザインの方針を正しく理解し、手戻りを防止します。

聖典の確認: document_architecture の「1.1. AIアシスタントへの最重要指示」を再読する。
ドキュメント索引の確認: document_index で全ドキュメントの担当スコープを把握し、タスクの影響を受けるドキュメントを特定する。
ガイドラインの遵守: 06_development_guidelines の「4. AIアシスタントのための実装前チェックリスト」を一つずつ確認する。
思想の再確認: 開発のすべての判断基準となる 00_philosophies_of_blueperiod を読み、プロジェクトの方向性と乖離していないか確認する。
デザインとの整合性: UIの変更を含む場合、必ず 09_design_system を読み込み、哲学と具体的なスタイリングルール（セマンティックトークン等）を確認する。

フェーズ 0: コミットメッセージの生成 (Commit Message Generation)

目的: タスク完了時に、変更内容を適切に要約したコミットメッセージを生成し、ユーザーに提示します。

プロセス:

タスクの分析:
- WHAT: 何を変更したか（変更されたファイル、コンポーネント、機能）
- WHY: なぜ変更したか（問題点、改善の動機）
- HOW: どのように変更したか（実装方法、技術的アプローチ）
コミットタイプの選択:
- 08_git_commit_conventions.md を参照し、適切なtypeを選択
- 主な選択肢: feat, fix, docs, style, refactor, perf, test, build, ci, chore
スコープの特定:
- 変更が影響する主要な領域を特定（例: explore, bookshelf, chat, api, db）
コミットメッセージの構成:
```
<type>(<scope>): <subject>

<body>
```
- Subject: 50文字以内、命令形、小文字開始、ピリオドなし
- Body: 変更の背景、問題点、解決方法を説明（必要に応じて）
ユーザーへの提示:
- 生成したコミットメッセージを明確に提示
- 重要: 提示するコミットメッセージは必ずMarkdownのコードブロック（```）で囲んでください
- ユーザーが確認・修正できるようにする
- 承認後、次のフェーズ（ドキュメント整備）に進む

出力フォーマット例:

---
【提案コミットメッセージ】

feat(explore): unify header design with bookshelf

The Explore and Bookshelf pages had inconsistent header designs,
leading to a disjointed user experience. This commit standardizes
the header layout across both pages:

- Adopt 3-column layout (icon+title, search, actions)
- Use consistent spacing and typography
- Implement responsive design for mobile and desktop
- Add Store icon for Explore page

This improves visual consistency and user navigation.
---

このコミットメッセージでよろしいでしょうか？
修正が必要な場合はお知らせください。

承認いただけましたら、ドキュメント整備作業に進みます。

重要な注意点:

コミットメッセージは、変更の「意図」と「影響」を明確に伝えることが重要です
技術的な詳細よりも、「なぜこの変更が必要だったか」を重視してください
複数の無関係な変更がある場合は、複数のコミットに分けることを提案してください

フェーズ1: タスクの自己分析 (Self-Analysis)

まず、完了したタスクの本質を深く理解し、ドキュメントの整合性を確認します。

チェック項目:
- 起点となる Issue ドキュメントは存在するか？（なければ過去に遡ってでも作成する）
- 実装の方針を示す Plan ドキュメントは作成したか？（小規模ならIssueに含まれているか？）
分析:
- WHAT: 何を変更したのか？ (例: ChatView.tsxのUIを修正)
- WHY: なぜその変更が必要だったのか？ (例: 特定の条件下でメッセージがオーバーフローするバグを解消するため)
- HOW: どのように解決したのか？ (例: CSSのflex-wrapプロパティを適用)

フェーズ2: 影響範囲の特定とSystemドキュメントの検討 (Impact Analysis)

次に、その変更がプロジェクトのどの側面に影響を与えるかを分析し、更新すべきドキュメントを特定します。

2.1. Systemドキュメント（永続仕様書）の影響判定プロセス

記録用ドキュメント（Issue/Plan/Report）に取り組む前に、「実装した内容が、プロジェクトの永続的な仕様（地図）に影響していないか」を以下のカテゴリで判定してください。

第一歩: document_index を開き、変更内容が影響するスコープを持つドキュメントを洗い出す。document_index は全ドキュメントの担当スコープを一覧化しているため、更新対象の特定に最も効率的である。

更新が必要な場合は、document_index で特定したファイルを fumadocs/content/docs/system/ から直接開いて更新する。

カテゴリ	更新が必要な「変化」の閾値	関連する仕様の探索キーワード
データ構造	カラムの追加/変更、テーブル新設、DBのバージョンアップ、外部キー制約の変更	`database`, `schema`, `persistence`
アーキテクチャ	コンポーネント間の依存関係の変化、新しいサービスレイヤーの導入、データフローの変更	`architecture`, `hybrid`, `backend`
外部通信 / API	APIエンドポイントの追加/削除、リクエスト・レスポンスのスキーマ変更	`api`, `specification`, `endpoint`
開発ガイド	新しい命名規則、推奨ライブラリの変更、共通コンポーネントの使い方の変更	`development_guidelines`, `conventions`
デザイン / UI	新しい共通UIパターン、カラースキームの追加、レスポンシブ戦略の変更	`design_system`, `style_guide`, `component_bible`
AI統合	AIモデルの変更、判定プロンプトの更新、エージェント設計の変更	`ai`, `agent`, `provider`, `18_agent_tool_integration_guide`

「記録（Log）は一過性のイベントですが、地図（System）は永続的な真実です。」地図の更新を忘れた報告書は、価値が半減すると心得てください。

2.2. ドキュメント戦略の自律的選択 (Documentation Strategy Selection)

AIエージェントは、管理のオーバーヘッドを削減しつつトレーサビリティを維持するため、タスクの規模に応じて以下のドキュメント戦略を自律的に選択してください。

フルセット（Issue + Plan + Report）:
- 対象: 大規模な機能追加、複数のコンポーネントに跨るリファクタリング、設計判断を伴う変更。
- メリット: 設計意図と実装結果を分離して記録でき、レビューや後の追跡が容易。
簡易セット（Issue [Plan内包] + Report）:
- 対象: 単一コンポーネントのバグ修正、1〜2ファイル程度の軽微なロジック変更、既存パターンの横展開。
- 運用: Plan.md を作成せず、Issue.md 内に ## 実施計画 (Implementation Plan) セクションを設けて設計方針を記述する。
- 判断基準: 「別のエンジニア（またはAI）が実装前に方針をレビューするのに、個別のPlanファイルが必要なほど複雑か？」を自問する。
最小セット（Issueのみ）:
- 対象: 文言の修正、コメントの追加、明確なタイポ修正。
- 運用: Issue.md の本文に変更内容を簡潔に並記し、完了後に status: close にする。

不変の原則: どのような規模であっても、「起点としてのIssue」 と 「実装ワークフローを含むReport（またはIssueへの追記）」 は必須です。記録のない変更はプロジェクトの「未知の負債」となります。

3.1. 実装ワークフローの可視化 (Workflow Transparency)

レポート（Report）を作成する際は、結果だけでなく、**「どのようにその結果に到達したか」**というワークフローを明示してください。

記述すべき項目:

実行コマンド: 実際に使用した主要なコマンド（bun install, tauri dev, cargo check 等）。
実行ディレクトリ: どの階層で実行したか。
手順の概観: どのような順番で作業を進めたか（初期化 -> プラグイン追加 -> 動作確認等）。

期待される効果：これにより「どのようなコマンドを、どのディレクトリで、どのような順序で実行したか」が常に記録されるようになり、トレーサビリティ（追跡可能性）が大きく向上します。

フェーズ3: ドキュメントの実行 (Execution)

実践的なチェックリスト:

プロジェクトの入り口は影響を受けるか？
- 新しい技術の導入、開発手順の変更など、新規参画者が最初に知るべき情報に変化はあるか？
- → Yes ならば、ルートの README.md を更新し、関連ドキュメントへのリンクを追加・修正します。
3点セットは揃っているか？
- → /doc/log/ の issues/open/, plans/open/, reports/ すべてに適切なドキュメントを作成・リンクします。
プロジェクトの根幹に関わる永続的な変更か？
- → fumadocs/content/docs/system/ のシステム仕様書（MDX）を更新、または新規作成します。
解決されたIssueはあるか？
- → 対応する Issue を issues/open/ から issues/close/ へ移動し、frontmatterの status を close に更新します。
- → 関連する Plan も plans/open/ から plans/close/ へ移動します。
既存のルールでは分類できない新しい種類の変更か？
- → 最も近いと思われるルールを適用しつつ、フェーズ4で新しいルールの必要性を提案します。

実装手順（優先順位順）:

Systemドキュメントの更新 (Map First):
- フェーズ2.1で特定した fumadocs/content/docs/system/ 配下のファイルを真っ先に修正・ステージングする。
- 地図が最新になってから、その上での「出来事」を報告する順序を守る。
README / プロジェクト入口の更新:
- 必要があればルートの README.md を更新する。
Logドキュメントの作成 (Event Second):
- /doc/log/ 配下の Issue (status更新), Plan (status更新), Report (新規作成) を行う。
相互リンクの記述:
- 全てのドキュメントの末尾に ## 関連 セクションを作成し、相互にリンクを張る。

ドキュメント体系の設計思想は、常に以下の最上位ドキュメントを参照してください。これが唯一の信頼できる情報源です。

ドキュメントの聖典(Bible): document_architecture

フェーズ4: 完了前セルフ・オーディット (Pre-completion Audit)

すべてのドキュメント作業を終え、ユーザーに報告する直前に、以下の「サボり防止チェック」を自律的に実行してください。

変更点の再走査: git diff --cached (または編集履歴) を見直し、Systemの仕様変更（DB/API/UIパターン）が含まれていないか再確認したか？
地図と報告の順序: Systemの更新がReportの作成よりも先に行われ、Report内で「仕様書が更新されたこと」に触れているか？
検索可能性: WikiLinks (ファイル名) は正しく機能しているか？（バッククォートで囲まれていないか？）
不要なコードの抹消: 実装中に一時的に導入したデバッグ用コードや、今回のように「取りやめた機能」の残骸がドキュメントやコードに残っていないか？
プロセスへの問い:
- 「今回の作業で、既存のルールでは対応しづらい点はなかったか？」
- 「ドキュメントを探す、あるいは作成する上で、ディレクトリ構造は直感的だったか？」
ルールへの問い:
- 「document_architecture の内容は、現在のプロジェクトの実態に即しているか？」
- 「より効率的なドキュメント管理方法はないか？」
本ガイドへの問い:
- 「この document_maintenance の記述は、より明確に、より高い自律性を促すように改善できないか？」

改善点を発見した場合、すべての作業の最後に、以下のフォーマットで人間がレビューできるよう提案してください。

---
【ドキュメントシステム改善提案】

- **対象ドキュメント/プロセス:** (例: `document_architecture.md`自体, `reports`の命名規則)
- **現状の問題点:** (例: バグ修正報告書のフォーマットが統一されておらず、後から見返しにくい)
- **具体的な改善案:** (例: `reports`ディレクトリに`bug-fix-report-template.md`を追加し、バグ修正時はそのテンプレートの使用をルール化することを [[document_architecture]] に追記することを提案します。)
---

4. シナリオ別実践ガイド

以下のチェックリストは、document_architectureで定義された構造に従ってドキュメントを更新するための実践的なガイドです。

シナリオA: ライブラリの追加

例: dnd-kit を導入し、ドラッグ＆ドロップ機能を追加した。

更新チェックリスト:

06_development_guidelines を再確認し、規約を遵守する
02_technology_stack の該当カテゴリにライブラリ情報を追加
- ライブラリ名、役割、選定理由を記載
/doc/log/reports/ に作業レポートを作成
- ファイル名: YYYY-MM-DD_HHmm_report_introduce-<library-name>.md
- 導入の背景、使用方法、影響範囲を記載
README.md の技術スタック一覧を更新（必要に応じて）
関連する system ドキュメントを更新（該当する場合）

シナリオB: バグ修正

例: チャット画面でメッセージがオーバーフローするバグを修正した。

更新チェックリスト:

06_development_guidelines を再確認し、規約を遵守する
/doc/log/reports/ にバグ修正レポートを作成
- ファイル名: YYYY-MM-DD_HHmm_report_fix-<bug-description>.md
- バグの内容、原因、修正方法、影響範囲を記載
該当する system ドキュメントを更新（設計に関わる場合）
既知の問題リストから該当項目を削除（存在する場合）

シナリオC: データベーススキーマの変更

例: 新しいテーブルを追加、または既存テーブルのカラムを変更した。

更新チェックリスト:

06_development_guidelines を再確認し、規約を遵守する
マイグレーションファイルを作成
- bunx supabase migration new <description>
マイグレーションを適用
- ローカル: bunx supabase db reset
- リモート: bunx supabase db push
TypeScript型定義を自動生成
- bunx supabase gen types typescript --linked > next-app/src/lib/types/supabase.ts
04_database_schema_supabase.md を更新
- 新しいテーブル/カラムの説明を追加
- 外部キー関係を明記
05_migration_guide.md の「重要なマイグレーション履歴」セクションを更新
- マイグレーションの目的、主な変更、影響範囲を記載
/doc/log/reports/ に詳細レポートを作成
- ファイル名: YYYY-MM-DD_HHmm_report_<migration-description>.md
TypeScriptのビルドエラーがないことを確認

シナリオD: メジャーフレームワークのバージョンアップ

例: Next.js 14 から Next.js 15 にアップグレードした。

更新チェックリスト:

06_development_guidelines を再確認し、規約を遵守する
02_technology_stack.md のバージョン番号を更新
- 破壊的変更や重要な変更点を注記として追加
/doc/log/reports/ に詳細な移行レポートを作成
- ファイル名: YYYY-MM-DD_HHmm_report_<framework>-<version>-upgrade.md
- アップグレードの理由、破壊的変更、対応内容、影響範囲を記載
影響を受けるコードファイルをリストアップ
必要に応じて system ドキュメントに移行ガイドを追加
- 例: 06_nextjs15_migration_notes.md
README.md の「必要な環境」セクションを確認・更新
package.json のバージョンが正しく更新されていることを確認
すべてのテストが通ることを確認
ビルドが成功することを確認

追加の注意点:

破壊的変更が多い場合は、段階的な移行計画を /doc/log/plans/open/ に YYYY-MM-DD_HHmm_plan_... 形式で作成することを検討
チーム全体に影響がある場合は、移行ガイドを詳細に記述

シナリオE: 新機能の追加

例: ユーザープロフィール編集機能を追加した。

更新チェックリスト:

06_development_guidelines を再確認し、規約を遵守する
/doc/log/plans/open/ に実装計画を作成（大規模な場合）
- ファイル名: YYYY-MM-DD_HHmm_plan_<feature-name>.md
機能実装後、/doc/log/reports/ に実装レポートを作成
- ファイル名: YYYY-MM-DD_HHmm_report_implement-<feature-name>.md
関連する system ドキュメントを更新
- 例: アーキテクチャに影響する場合は 01_architecture.md
- 例: 状態管理に影響する場合は 03_state_management.md
データベース変更がある場合は、シナリオCのチェックリストも参照
新しいライブラリを使用する場合は、シナリオAのチェックリストも参照
README.md の機能一覧を更新（必要に応じて）

シナリオF: UI/UXの改善

例: ExploreページとBookshelfページのデザインを統一し、タグフィルタリングUIを改善した。

更新チェックリスト:

06_development_guidelines を再確認し、規約を遵守する
/doc/log/reports/ にUI/UX改善レポートを作成
- ファイル名: YYYY-MM-DD_HHmm_report_<improvement-description>.md
- 改善の背景、問題点、実装内容、影響範囲を記載
- Before/Afterの比較（スクリーンショットやコードスニペット）を含める
07_component_bible.md を更新（該当する場合）
- 新しいコンポーネントの追加、または既存コンポーネントの責務の変更を記載
- デザインパターンや再利用可能なUIパターンを文書化
デザインシステムに影響する場合は、デザイントークンやパターンを文書化
- カラー、タイポグラフィ、スペーシング、シャドウなどの変更を明記
- 統一されたデザインパターンがある場合は、実装例とともに記載
レスポンシブデザインの変更がある場合は、ブレークポイントと動作を明記
- モバイル、タブレット、デスクトップでの表示の違いを説明
アクセシビリティへの影響を確認し、必要に応じて記載
- キーボードナビゲーション、スクリーンリーダー対応、色のコントラストなど
パフォーマンスへの影響を評価（大規模なUI変更の場合）
- レンダリングパフォーマンス、バンドルサイズの変化など

追加の注意点:

UI/UXの改善は、ユーザー体験の一貫性を保つことが重要です
既存のデザインパターンとの整合性を確認し、新しいパターンを導入する場合は明確に文書化してください
複数のページやコンポーネントに影響する場合は、すべての影響範囲を明記してください

シナリオG: 複合タスク（機能追加 + バグ修正）

例: MetadataEditModalにカバー画像アップロード機能を追加する過程で、IndexedDBのBlob永続化バグを発見・修正した。

更新チェックリスト:

/doc/log/reports/ に包括的な作業レポートを作成
- ファイル名: YYYY-MM-DD_HHmm_report_<primary-feature-name>.md
- 初期Issue、発見されたバグ、両方の解決策を含む統合的な内容
コミットメッセージは主要な機能をtypeとし、bodyで関連バグ修正にも言及
- 例: feat(metadata): add cover image upload to metadata edit modal
- Body内で「Additionally, fixed IndexedDB persistence issue」と記載
関連する system ドキュメントを更新
- 新機能に関連するコンポーネントドキュメント
- 型定義やアーキテクチャの変更があれば該当ドキュメント
複数の独立した変更がある場合は、コミットを分割することも検討

判断基準:

バグ修正が機能実装の前提条件または副産物である場合 → 単一のレポートとコミット
バグ修正が機能実装と完全に独立している場合 → 別々のレポートとコミット

5. Plan ドキュメントのフォーマット（散文ベース・設計重視）

Plan ドキュメントは、実装の「設計意図」と「判断理由」を記録するドキュメントです。タスクの進捗管理は AI アシスタントの TaskCreate ツール（セッション内）で行い、Plan には記載しません。

5.1. 根本思想: Plan = 設計意図と判断理由

Plan は「設計意図と判断理由」を伝えるドキュメントであり、細かい作業のチェックリストではありません。実際の進捗管理は各作業環境のタスク管理機能で行います。

	Plan (ドキュメント)	進捗管理 (各環境のタスク機能)
役割	「何を作るか」「なぜそうするか」	「今何をしているか」「残り何」
内容	設計方針・判断理由・アーキテクチャ	具体的な作業チェックリスト
記述スタイル	散文ベース + Phase単位の大まかなTODO	細粒度のタスク管理
更新頻度	低（方針変更時のみ）	高（作業ごと）

5.2. Plan の記述ルール

各Phaseの本文は散文のみ。チェックリストを混ぜず、「何をするか」「なぜそうするか」を自然な文章で記述する。
技術的な詳細は触るファイル名を列挙する程度にとどめ、設計の文脈を優先する。
「完了の目安」を各Phaseの末尾に1-2行で書く。これがそのPhaseの達成基準になる。
進捗管理は末尾の独立セクションで行う。Phase本文ではなく、Planの末尾に ## 進捗 セクションを作り、Phase単位などで1行ずつのチェックリストを置く。細かいタスク分解はしない。
completion_percentage と last_updated はフロントマターに含めない。

5.3. Plan ドキュメントの基本構造

---
title: <計画のタイトル>
date: YYYY-MM-DD_HHmm
tags: [<タグ1>, <タグ2>, ...]
status: open | close
priority: critical | high | medium | low
related:
  - [[<関連Issueファイル名>]]
---

# <計画のタイトル>

## 1. 概要

計画の目的と対象を簡潔に記述します。

## 2. 設計方針

実装にあたっての設計方針、アーキテクチャの決定事項を記述します。
「なぜこの方針を選んだのか」という判断理由を含めてください。

## 3. 実装フェーズ

### Phase 1: <フェーズ名>

<何を実現するか、なぜ必要かを散文でのみ記述。チェックリストは混ぜない>

触るファイル: <対象ファイルのパスを列挙>

完了の目安: <1-2行で達成基準を記述>

### Phase 2: ...

## 4. 実装順序と依存関係

<Phase間の依存関係をシンプルに図示>

## 5. 進捗

- [ ] Phase 1: <フェーズ名>
- [ ] Phase 2: <フェーズ名>
- [ ] Phase 3: <フェーズ名>

## 6. 関連ドキュメント

- [[<関連ドキュメント>]]

5.4. 記述スタイルの比較

避けるべき書き方（Phase本文にチェックリストを混ぜる）:

### Phase 1: データ層のリファクタリング
#### 1.1. 型定義の更新
- [ ] lib/types.ts: ProjectRecord に localizations 追加
- [ ] localizations の型ヘルパー作成
- [ ] PublishRequestData 型の更新
#### 1.2. IndexedDB スキーマ更新
- [ ] lib/db.ts: スキーマバージョンアップ
- [ ] マイグレーションロジック実装

推奨する書き方（Phase本文は散文のみ + 進捗は末尾セクション）:

### Phase 1: データ層のリファクタリング

ProjectRecord に `localizations: Record<string, {...}>` を追加し、
ManuscriptやPlotと同じ `{ [lang]: data }` マップパターンに統一する。
これにより、作品メタデータの国際化がPublishとは独立して管理できるようになる。

触るファイル: `lib/types.ts`, `lib/db.ts`, `lib/metadataUtils.ts`

完了の目安: getDisplayMetadata が localizations ベースで動作し、
フォールバックチェーン（表示言語 → 原語 → en）が正しく機能すること

---（中略）---

## N. 進捗

- [ ] Phase 1: データ層のリファクタリング
- [ ] Phase 2: UI再構築
- [ ] Phase 3: 仕上げ

5.5. Phase 構成のガイドライン

規模に応じた Phase 構成の目安：

規模	Phase 数	1 Phase の目安	例
小	1-2	1-3日	バグ修正、軽微な機能追加
中	3-5	3-7日	新機能追加、リファクタリング
大	6+	1-2週間	アーキテクチャ変更、複数機能統合

6. システムドキュメント一覧

全システムドキュメントの担当スコープは document_index を参照のこと。document_index は新規ドキュメント作成・更新時に随時更新すること。

Fumadocs プロジェクトの主要設定ファイル

Docsサイトの動作に関わる設定ファイル。Systemドキュメント（MDX）ではないが、影響分析で参照すべきファイル。

ファイル	役割
`source.config.ts`	MDX設定、WikiLinks解決（pageResolver）、Mermaid
`lib/source.ts`	ページツリー生成、baseUrl 設定
`lib/layout.shared.tsx`	ナビゲーション設定（nav, links, githubUrl）
`lib/shared.ts`	共通定数（appName, docsRoute, gitConfig）
`app/layout.tsx`	ルートメタデータ（SEO/OGP/title/icons）
`app/api/search/route.ts`	Orama検索設定（日本語トークナイザー）
`biome.jsonc`（ルート）	Biome設定。lint・formatの全設定を一元管理
`tsconfig.json`	TypeScript設定。.next, .source をexclude

7. ステータス管理（open/close ディレクトリ運用）

タスク完了時、AIアシスタントは以下のディレクトリ移動を自律的に行います：

対応する Issue を issues/open/ → issues/close/ へ移動（git mv）
関連する Plan が存在する場合、plans/open/ → plans/close/ へ移動（git mv）
Report を reports/YYYY/MM/ に作成
各ドキュメントの status フィールドを close に更新
WikiLinks が正しく機能していることを確認

運用ルール:

新規Issue作成時は issues/open/YYYY/MM/ に作成
新規Plan作成時は plans/open/YYYY/MM/ に作成
年明けには新しい年のディレクトリを open/ と close/ の両方に作成
Reports はopen/closeの区別なし（完了記録のため）

Document Maintenance Bible

On this page