# Claude Web・Claude Code・MCP連携

PM on Railsは **MCP（Model Context Protocol）** に対応しています。Claude Web / Claude Code / Codexなどの外部AIツールから、プロジェクトのグラフを直接読み書きできます。アプリ内AIアシスタントと違い、**読み取りも書き込みも幅広いツールが揃っており**、管理作業と実装作業の中から要求・タスク・シナリオを操作できます。

## MCPとは

MCPは、AIツールに「PM on Railsの操作道具」を渡すための共通規格です。Claude WebやClaude Codeは、会話の内容だけで判断するのではなく、PM on Railsが公開しているツールを呼び出して、実データを読み取り、必要な変更を保存します。

- **同じグラフを操作する** — 画面、AIアシスタント、Claude Web、Claude Code、Codexのどこから触っても、要求・要件・ストーリー・シナリオ・タスクは同じデータです。
- **自然言語をツール実行に変える** — 「この要求の影響範囲を見て」「このタスクに着手して」のような依頼を、PM on Rails側の読み取り・更新操作に変換します。
- **読み取りと書き込みを分けて扱う** — 調査は読み取りツール、作成・更新は書き込みツールで実行します。書き込みはPATの権限とプロジェクトのルールに従います。
- **応答に次の作業情報が返る** — タスク着手時にはブランチ名やPR本文用の識別行、上流変更の警告など、開発でそのまま使う情報が返ります。

## 使い分け

| 使う場所 | 向いている人 | 主な使い方 |
| --- | --- | --- |
| Claude Web | PM / PdM / Biz | 要求整理、優先度確認、ストーリーや確認事項の作成、会議後の更新、影響範囲の確認 |
| Claude Code | エンジニア | タスク選定、背景・受入条件の確認、着手、ブランチ作成、実装中の仕様確認、PR紐付け |
| Codex | エンジニア / レビュー担当 | 既存コードを読みながらタスクを進める、テスト・修正・PR作成、仕様と実装の差分確認 |
| PM on Railsの画面 | チーム全体 | 一覧確認、ロードマップ、カンバン、レビュー、設定、権限管理 |

PMはClaude WebにMCP接続して、「昨日の議事録から未整理の要求を出して」「Mustのストーリーだけ確認して」「この変更で影響するタスクを教えて」のように、管理作業を会話で進められます。エンジニアはClaude Code / Codexから同じMCPに接続し、「次に着手できるタスクを選んで」「受入シナリオを読んでから実装して」「PR本文に必要な識別行を入れて」のように、開発作業へつなげます。

## セットアップ

![PM on Railsのトークン管理。PATを発行してMCP接続に使う。導入前はエージェントに渡す認証が手元のメモだった。導入後はプロジェクトの権限の範囲で接続できる。](https://pmonrails.com/docs-img/mcp-tokens.png)

1. Claude Codeは、ターミナルで `npm install -g pm-on-rails` → `pm-on-rails login` → `pm-on-rails mcp install` の順に実行してつなぎます。`login` でブラウザの承認画面が開き、トークンはOSのキーチェーンに保存されます（トークンを手で発行する必要はありません）。
2. それ以外のツールは、「個人設定 → 連携」のトークン管理で **パーソナルアクセストークン（PAT）** を発行します（発行時のみ平文表示。scopeと有効期限を選択可）。外部ツール側に、MCPサーバーの接続先とPATを設定します。
3. PATは**ワークスペース単位**で固定です。別ワークスペースを操作するにはその数だけ発行します。

> PATは秘密情報です。紛失時は失効させて再発行してください（平文は再取得できません）。

## どう動くか

1. **外部AIツールがMCPサーバーへ接続** — PATでワークスペースと権限を確認します。
2. **AIが使えるツール一覧を読む** — 要求作成、トレーサビリティ検索、タスク更新など、PM on Rails側が許可した操作だけが見えます。
3. **ユーザーの依頼を解釈** — 「ログイン周りの抜け漏れを見て」のような依頼を、必要な読み取り・更新ツールへ分解します。
4. **PM on Railsが実データで実行** — AIの推測だけでなく、Neo4j上のプロジェクトグラフ、権限、状態遷移ルール、GitHub連携状態を見て実行します。
5. **結果と次アクションを返す** — 変更結果、根拠、関連ノード、ブランチ名、PR本文用の識別行、注意点が外部AIツールへ返ります。

| カテゴリ | 主なツール | 何ができるか |
| --- | --- | --- |
| 要求 | `create_demand` / `update_demand` / `list_demands` / `get_demand` / `archive_demand` | 要求カードの作成・更新（MoSCoW/スコアリング）・一覧・アーカイブ |
| 要件 | `create_requirement` / `update_requirement` / `list_requirements` | 非機能要件・制約の作成・更新・一覧（機能仕様はストーリー概要） |
| 判断・ADR | `create_decision` / `list_decisions` / `create_architecture_decision` / `update_architecture_decision` / `supersede_architecture_decision` / `list_architecture_decisions` | 採用判断と設計判断（ADR）の記録・状態変更・置き換え・一覧 |
| ストーリー | `create_story` / `update_story` / `list_stories` / `get_story` / `link_story_demand` / `unlink_story_demand` / `sync_story_to_github` | ストーリーの作成・更新・一覧・詳細の読み取り・親要求の付け替え・GitHub同期 |
| シナリオ | `create_scenario` / `update_scenario` / `update_scenario_status` / `supersede_scenario` / `read_scenario` | Gherkinシナリオの作成・更新・状態遷移・新版化 |
| タスク | `create_task` / `update_task` / `start_task` / `update_task_status` / `assign_task_to_me` / `complete_task` / `list_tasks` / `get_task` | タスクの作成・更新・着手・状態遷移・自分への割当・完了 |
| 表示言語 | `update_language` | コンソールと同じUser.languageをja / enに切り替える |
| バグ | `resolve_bug_destination` / `create_bug_task` / `resolve_bug` / `update_bug_affects` / `promote_bug_to_requirement` / `list_bugs_affecting` | バグの行き先 (破られたシナリオ) の解決・起票・解決・影響範囲・要件昇格 |
| 計画 | `create_epic` / `update_epic` / `create_cycle` / `update_cycle` / `list_cycles` | Epic・開発サイクルの作成・更新（`cycle` は開発サイクルの内部名） |
| 連携 | `link_pr` / `search_github_pull_requests` / `sync_story_to_github` | PR検索・紐付け・Issue同期 |
| 探索 | `get_traceability` / `search_similar_demands` / `search_similar_requirements` / `search_similar_decisions` / `get_project_stats` / `get_embedding_coverage` | トレーサビリティ追跡・類似検索・統計・類似検索データのカバー率 |
| 見積もり | `suggest_estimate` | LLM ＋ 個人補正の見積もり提案 |
| 文書 | `list_folders` / `create_folder` / `create_document` / `get_document` / `update_document_body` / `generate_document_draft` / `list_documents` / `request_document_review` / `approve_document` / `revert_document_version` / `delete_document` | 議事録・検討メモなど一般ナレッジの下書き生成・保存・更新・レビュー・承認・版復元・削除 |
| 設計書 | `list_design_folders` / `create_design_folder` / `list_design_documents` / `create_design_document` | 基本設計ドライブのフォルダ管理、要求・要件・ストーリーに紐づく既存設計書の検索、DESIGNS付き設計書の作成 |
| アーカイブ・削除 | `archive_*` / `restore_*` / `delete_*` | 要求・要件・ストーリー・シナリオの保管 / 復元 / 削除（子も連動） |
| コメント | `add_comment` / `update_comment` / `list_comments` | コメントの追加・更新・一覧 |
| 一括 | `execute_operations` | 複数操作を1トランザクションで原子的に実行 |
| 使い方 | `get_mcp_usage_guide` | セッション開始・着手・完了・トレーサビリティなど、運用トピックごとの使い方を返す |

> MCPは「チャットの裏にあるAPI」です。会話は自然文でも、実際の読み書きはPM on Railsのツールとして記録されます。
> 設計書は一般ナレッジとは分けて扱います。新しい設計書を作る前に、同じ要求・要件・ストーリーへ紐づく既存設計書を `list_design_documents` で探し、あれば `get_document` と `update_document_body` で統合します。

## シナリオ・タスク・テストの関係

`create_scenario` は、受入仕様の正本である `SDLCScenario` を作るだけではありません。同じ実行で、カンバンに出るscenario `KanbanTask` と、シナリオテスト結果を記録するためのつながりも用意します。

- **受入仕様の正本** — Given / When / ThenとGherkinは `SDLCScenario` に保存されます。
- **実装アンカー** — カンバン上のscenario `KanbanTask` は実装・PR・バグ・テスト結果を結びつける作業カードです。Gherkinやscenario_typeはコピーしません。
- **テスト結果** — `create_scenario` の時点では `TestResult` 行は作られません。実行後に、生成されたscenario taskの `task_id` へ `create_test_result` で合否を記録します。

`create_scenario` 後に同じ振る舞いを `create_task` でも起票すると二重管理になります。シナリオ本文を直す場合は、taskの `scenario_id` を使って `read_scenario` / `update_scenario` / `supersede_scenario` を呼びます。単発の内部作業・調査・移行は `create_task(task_type='task')` のまま扱います。

## 反映案を画面で確認する（MCP Apps）

`list_cascade_proposals`（AIが用意した要件・ストーリー・シナリオの更新案の一覧）は、**MCP Appsに対応したホスト（Claude Webなど）では画面として表示**されます。差分を見てから「適用」「保留」「却下」を選べ、いずれも押す前に確認が入ります。対応していないホストには同じ内容がテキストで返るので、会話で読み上げてもらう使い方も変わりません。適用は既存のツールと同じ権限・プロジェクト境界で実行されます。

## Claude WebでPMができること

- **会議後の整理** — 取り込んだ議事録をもとに、未整理の要求・確認事項・優先度の候補を出す。
- **要求の棚卸し** — Must / Shouldの要求だけを見たり、根拠が弱い要求や重複しそうな要求を探す。
- **ストーリー作成** — 要求からユーザーストーリーと受入シナリオの叩き台を作る。
- **未決事項アジェンダ作成** — 未回答・議論中の確認事項をまとめ、MarkdownのMTGアジェンダにしてナレッジへ保存する。
- **変更の影響確認** — 「この要求を変えたらどのストーリー・タスクに影響するか」を確認する。
- **確認事項の管理** — AIレビューで出たステークホルダーへの質問を確認事項へ残し、回答が来たら要求やストーリーへ反映する。

例を示します。

```text
在庫アラート周りの Must 要求を見て、ストーリー化されていないものを教えて。
不足している確認事項があれば、ステークホルダーに送る質問文として作って。
```

## Claude Code / Codexで開発者ができること

- **次のタスクを選ぶ** — 開発サイクル、担当、依存関係、状態から、着手できるタスクを探す。
- **背景を読む** — タスクからシナリオ、ストーリー、要求、元の発言まで辿り、完成条件を確認する。
- **着手を記録する** — `start_task(task_id)` でタスクを進行中にし、担当者と開発サイクル、実績時間の開始点を残す。
- **ブランチとPRを紐付ける** — 応答に含まれるブランチ名とPR本文用の識別行を使って、PRとタスクを自動連携する。
- **仕様変更を検知する** — 実装中に上流の要求・シナリオが変わっていたら、PRマージ前後に再確認が必要だと分かる。
- **実装後に更新する** — タスク完了、バグ起票、シナリオ更新、確認事項の追加を、コード作業の流れから直接行う。

例を示します。

```text
今のサイクルで自分が着手できるタスクを1つ選んで。
関連するストーリー、受入シナリオ、上流要求を読んで、ブランチ名とPR本文に入れる識別行も出して。
```

## 活用例

### 1. PMが会議後に要求を整理する

```text
今日取り込んだ議事録から、未整理の要求候補を出して。
既存の要求と重複しそうなもの、ステークホルダーに確認が必要なもの、Must 候補を分けて。
```

MCPは文書・要求・過去の判断を読み、必要なら要求カードやコメントの下書き候補を残します。ステークホルダーへの質問は確認事項として残せるので、会議メモから次のアクションまでつながります。

### 2. PMがスコープ変更の影響を確認する

```text
「在庫アラートをメールだけでなくSlackにも出す」に変更したい。
影響するストーリー、シナリオ、未完了タスク、確認が必要な仕様を出して。
```

要求から下流を辿り、実装中のタスクや受入シナリオの変更漏れを確認します。必要ならストーリーの更新案やステークホルダーへの確認事項も作れます。

### 3. エンジニアが実装に入る

```text
今のサイクルで着手できるタスクを選んで、自分に割り当てて進行中にして。
背景、受入シナリオ、注意すべき上流変更、ブランチ名、PR本文用の識別行も出して。
```

タスク一覧、タスク詳細、背景のトレーサビリティ、担当変更、状態変更を組み合わせて、タスク選定から着手記録まで進めます。必要なタスク作成や内容更新は `create_task` / `update_task` で先に済ませ、実際に着手するときだけ `start_task(task_id)` を呼びます。これにより未担当なら呼び出し元が担当者になり、未着手ならstarted_atが刻まれ、DoRが評価され、cycle未割当でactiveな開発サイクルが一意に決まる場合はそのcycleに入ります。activeな開発サイクルが無い場合は勝手に期間を決めず、開始日・終了日・運用単位 (1週間 / 2週間 / その他) を確認してから `create_cycle` で作成し、同じ `start_task` を再実行します。他人の進行中タスクを巻き取る場合は `assign_task_to_me` を明示的に使い、started_atは初回着手時刻のまま保持します。着手後の担当変更履歴があるタスクは、個人別の所要時間補正サンプルから除外されます。返ってきたブランチ名とPR本文用の識別行を使うと、PRマージ時にタスクと親ストーリーが自動更新されます。

### 4. 実装中に仕様差分を確認する

```text
このタスクに着手してから、上流の要求やシナリオが変わっていないか確認して。
変わっていたら、実装に影響する差分だけ教えて。
```

着手時刻と上流ノードの更新時刻を比べ、古い仕様のまま実装していないかを確認します。差分がある場合は、PRマージ前に再確認が必要なタスクとして扱えます。

### 5. レビュー担当がPRと仕様を照合する

```text
このPRに紐づくタスクの受入シナリオを読んで、実装差分で満たせているか確認して。
不足しているテストや、仕様と違う点があれば指摘して。
```

CodexやClaude Codeはコード差分を読みつつ、MCPでタスク・ストーリー・受入シナリオを取得できます。レビューは「コードだけ」ではなく「なぜこの仕様なのか」まで辿って確認できます。

### 6. PM on Railsの外へ持ち出す

```text
今回の開発サイクルの対象ストーリーをMarkdownで出して。
GitHub未連携のものはIssue化して、連携済みのものは最新内容をpushして。
```

MarkdownエクスポートとGitHub Issue同期を使えるので、PM on Railsの外でも同じ内容を使えます。普段はMCPで管理・開発し、必要に応じてMarkdownやGitHubへ持ち出せます。

## できることの全体像

MCPは、AIアシスタントより広い操作をカバーします。利用者は英語のツール名を覚える必要はありません。Claude Web / Claude Code / Codexに日本語で依頼すれば、必要な操作はエージェント側が選びます。

| やりたいこと | できる操作 |
| --- | --- |
| 要求を整理する | 要求カードの作成・更新、MoSCoWやスコアの調整、一覧確認、アーカイブ |
| 要件・制約を残す | 非機能要件、制約、前提条件の作成・更新、関連要求との紐付け |
| 判断を残す | 採用 / 却下 / 保留の判断、ADR、古い判断の置き換え、判断理由の一覧確認 |
| ストーリーを作る | ユーザーストーリーの作成・更新、親要求の付け替え、受入シナリオの追加 |
| シナリオを整える | Given / When / Thenの作成・更新、状態変更、新しい版への置き換え |
| タスクを進める | タスクの作成・更新、担当変更、着手、完了、カンバン状態の確認 |
| バグを扱う | バグ起票、解決記録、影響範囲の整理、再発防止の要件化 |
| 計画を組む | Epic、開発サイクル、スプリント対象、進捗状況の確認 |
| GitHubとつなぐ | ストーリーのIssue化、Issueへの反映、PRとタスクの紐付け |
| 探す・辿る | 要求からタスクまでの根拠確認、影響範囲の確認、似た要求や過去判断の検索 |
| 見積もる | タスクの所要時間見積もり、個人実績を踏まえた見積もり補正 |
| 文書を管理する | 文書の一覧、レビュー依頼、承認、版の復元、削除 |
| まとめて処理する | 複数の起票・更新を一括実行。途中で失敗した場合はまとめて取り消し |

> すべてのMCP操作を日本語で確認したい場合は [MCP機能リファレンス](https://pmonrails.com/docs/mcp-reference.md) を参照してください。開発者向けに、内部ツール名も併記しています。

## こう打つと、こうできる

グラフ構造（要求 → 要件 → ストーリー → シナリオ → タスク）を意識すると、自然言語で一連の操作を任せられます。

| Claude Web / Claude Codeにこう頼む | PM on Rails側で起きること |
| --- | --- |
| 「在庫管理の要求から、ストーリーと受入シナリオまで一式作って」 | 要求カード、ストーリー、受入シナリオを順番に作成 |
| 「この要求の実装に必要なタスクを分解して起票して」 | 関連する要求・ストーリー・シナリオを確認し、複数タスクを作成 |
| 「今やっているタスクに着手するブランチを教えて」 | タスクを進行中にし、ブランチ名とPR本文用の識別行を返す |
| 「このバグが影響するシナリオを洗い出して、再発防止の要件にして」 | 影響するシナリオを記録し、再発防止の要件候補を作成 |
| 「ログイン周りで過去に似た要求や判断がないか調べて」 | 似た要求カード、要件、過去の判断を検索 |
| 「この要件を変更したら何が壊れるか影響範囲を出して」 | 上流・下流のつながりを辿り、影響するストーリー・シナリオ・タスクを列挙 |
| 「このストーリーをMarkdownで出して」 | Markdownエクスポートで外へ持ち出す |
| 「このストーリーをGitHub Issueにして」 | GitHub Issueを作成し、以後の同期先として記録 |
| 「このストーリーは別の要求カードの配下に移して」 | 親要求を付け替える。配下のシナリオや要件リンクは保つ |
| 「未回答の確認事項から明日のMTGアジェンダをMarkdownで作って、ナレッジに保存して」 | 確認事項・関連ストーリー・既存文書を読み、Markdown下書きを作って文書として保存 |
| 「複数のタスクをまとめて一気に作って（途中で失敗したら全部戻して）」 | 複数操作を一括実行し、途中失敗時はまとめて取り消す |

## PRとタスクの自動紐付け

実装着手時、MCPの応答に含まれるブランチ名とPR本文用の識別行を使うのが基本です。

- 返ってきたブランチ名でブランチを切る（例: `feat/9e300a0b-add-login`）
- PR本文に返ってきた識別行（例: `PMR-Task: 9e30...`）を1行入れる

これでPRマージ時にタスクが自動で完了になり、親ストーリーも再計算されます。GitHub連携は、MCPで進めた開発の結果を外へ出すためのものです。詳細は [GitHub連携](https://pmonrails.com/docs/github.md)。

## 安全のしくみ

- すべての操作は、トークンに紐づく**ワークスペースとプロジェクトの権限**の範囲内に制限されます。
- 画面操作（UI）と同じ業務ルール・安全確認が、外部ツールからの操作にも同じように効きます。
- 出力には日本語のラベルも併記されるため、AIが内容を解釈しやすくなっています。

## 次のステップ

- 会話で使う簡易版 → [AIアシスタント](https://pmonrails.com/docs/ai-assistant.md)
- できることの網羅 → [MCP機能リファレンス](https://pmonrails.com/docs/mcp-reference.md)
- しくみ → [AIのしくみ](https://pmonrails.com/docs/graphrag.md)

---

https://pmonrails.com/docs/mcp