本リポジトリのドキュメントは 読み手 と 抽象度 の 2 軸で構成される。 本書はその全体像と、各ドキュメントの役割・依存関係・更新ルールを示す。
利用者・運用者向けの主要文書はルートの
README.md からも辿れる。
- 日本語が正 — すべての公式ドキュメントは日本語で書かれ、これが 仕様・設計の正典。実装やコメントとの間に齟齬があれば、文書側を正と みなして実装を直す(または文書を意図的に更新する)。
- 上流が下流を拘束する — 要件 → 仕様 → 設計 → 実行計画 は厳密な 階層関係にあり、下流が上流に矛盾してはならない。
- 読み手で分離する — 利用者・運用者は「使うために必要なもの」、 開発者・メンテナは「作る/直すために必要なもの」を読む。 両者に同じ文書を要求しない。
要件 → 仕様 → 設計 → 実行計画 の流れに沿って書く。下に行くほど具体になる。
┌─────────────────────────────────────────────────────────────┐
│ requirements.md ── 何を解くか (スコープ / 機能・非機能要件) │ 上流
└─────────────────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ spec/spec.md ── 外からどう見えるか (MCP ツール契約) │
└─────────────────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ design/design.md ── 内部でどう実現するか (アーキテクチャ) │
└─────────────────────────────────────────────────────────────┘
▼
┌─────────────────────────────────────────────────────────────┐
│ tasks/task.md ── どの順で作るか (WBS タスク一覧) │ 下流
└─────────────────────────────────────────────────────────────┘
重要な決定 は ADR (Architecture Decision Records) として
adr/ に時系列で保存する。設計を変えるときは、設計書本体に
加えて ADR を追加する。
サーバを使う・運用する人がまず読む。実装の中身は前提にしない。
| 文書 | 役割 | いつ読む |
|---|---|---|
| installation.md | 導入・初期設定 | はじめて入れるとき |
| operations.md | 常設運用・同期戦略・監視 | 常駐で動かすとき |
| distribution.md | 配布方針(どの形態で入れて、どこから繋ぐか) | 構成を選ぶとき |
| spec/spec.md | 外部仕様(ツール入出力・エラー・設定・性能) | クライアント実装/結合のとき |
| usage-for-llm.md | LLM 向け利用ガイダンス(capability discovery 文言の原本) | LLM 側のプロンプト/挙動を理解したいとき |
| agent-sequence.md | エージェント連携シーケンス | spec/spec.md / usage-for-llm.md を読むときの補助線 |
コードを書く・変える人が読む。本リポジトリで作業する前提を共有する。
| 文書 | 役割 | いつ読む |
|---|---|---|
| requirements.md | 要件(何を解くか) | スコープを判断するとき |
| design/design.md | 内部設計(アーキテクチャと決定事項) | 構造に触れる変更のとき |
| release.md | リリース手順(タグ push で GitHub Actions が自動公開) | 版を切るとき |
| tasks/task.md | 実行計画(WBS タスク一覧と状態) | 次に何をやるか決めるとき |
| 文書 | 内容 |
|---|---|
| adr/0001-mcp-framework-selection.md | MCP フレームワーク選定 — 公式 mcp Python SDK |
上流が変われば下流の整合性を必ず確認する。逆方向(下流から上流への こっそりとした書き換え)は禁止。
- 要件を変える → 仕様・設計・実行計画の影響箇所を更新する
- 仕様を変える → 設計・実装・テスト・実行計画を更新する
- 設計を変える → ADR を追加し、設計書本体と実装を更新する
- タスクを変える → 実行計画(
tasks/task.md)のみ。 仕様・設計を触らずにタスクだけ書き換える場合は、その変更が上流に 矛盾しないことを確認する
利用者・運用者向けの文書(installation.md / operations.md /
distribution.md)は、仕様・設計の変更が利用体験に影響する場合に
合わせて更新する。