PM Server — User Guide

1. 基本コンセプト — pm-server は 3 つの層から成る

PM Server を効率よく使うために、最初に「誰が pm-server を呼ぶか」を整理する。

1.1 用語 mini 辞書

task

作業単位 (todo / in_progress / review / done / blocked) — PMSERV-NNN ID

issue

task の子として起票される欠陥/改善 — defect は親を auto-revert

ADR

Architecture Decision Record — 設計判断の永続記録 (ADR-NNN)

KR

Knowledge Record — research / spec / tradeoff / risk_analysis の構造化記録 (KR-NNN)

memory

SQLite + FTS5 に保存される observation / insight / lesson

workflow

テンプレートベースの状態マシン (WF-NNN) — discovery / development / super-research

outbox

Phase 2 で追加。Desktop ⇄ Code 間の append-only 共有 bridge

Lens

RO 配布モード (PM_LENS=1) — Desktop/Cowork 等の viewer host 用

2. クイックスタート — 5 分で動かす

2.1 インストール

$ pip install pm-server
$ pm-server install           # Claude Code に MCP サーバーを登録
✓ claude-code: registered pm-server

$ pm-server install-hooks     # 自動 context 注入の hook を有効化 (任意)
✓ installed

2.2 プロジェクトの初期化

Claude Code セッションを開いて、初期化を依頼するだけ。

> PM 初期化して

# Claude が pm_init を実行
# project 名・version・phases を自動推定 (discovery.py)
# <repo>/.pm/ ディレクトリが作成される
✓ Initialized .pm/ for "my-app"

2.3 CLAUDE.md ルールの注入

auto-action rules (CLAUDE.md / AGENTS.md) を注入すると、セッション開始時に Claude が自動で pm_status / pm_next / pm_recall を呼ぶようになる。

$ pm-server update-rules             # auto detect → 該当 host の rule file を更新
$ pm-server update-rules --target=all # 強制的に全 host (CLAUDE.md + AGENTS.md)
$ pm-server update-rules --dry-run    # 差分を表示するだけ

2.4 動作確認

> 現在の進捗は？
# → pm_status → "Tasks: 0 total — todo:0 in_progress:0 done:0 blocked:0"

> "ログイン機能を実装する" タスクを追加して
# → pm_add_task → PMSERV-001 が採番される

> 次にやるべきことは？
# → pm_next → PMSERV-001 が推薦される

3. CLI コマンド完全リファレンス

CLI コマンドは セットアップ・診断・自動化スクリプト用。日常運用では LLM 越し MCP の方が早い。

3.1 サーバー管理

3.2 プロジェクト操作

3.3 ルール / hook 管理

3.4 補助

4. 1日のセッションフロー

CLAUDE.md auto-action rules が full deployment されていれば、下記は Claude が自律的に進める。 人間が叩くのは「タスクを依頼する」「Yes/No を返す」だけ。

5. 進捗チェック Tips — 4 つのツールの使い分け

5.1 「Claude を信頼して状況把握だけお願いする」 pattern

> 朝の状況確認お願い

# Claude が auto で実行: pm_status + pm_next + pm_recall + pm_blockers
# それぞれの結果を要約して提示
# ブロッカーや期限超過があれば警告

5.2 specific フィルタの例

> phase-8 の todo タスクだけ priority 順で出して
# → pm_tasks(phase="phase-8", status="todo", sort="priority")

> "installer" tag がついてるタスク全部
# → pm_tasks(tags=["installer"])

6. メモリ活用 — pm-server の心臓部

SQLite + FTS5 のメモリ層は「compaction で失われる文脈を永続化する」中核機能。タイミングと粒度がコツ。

6.1 type の使い分け

6.2 保存の典型 pattern

> 今の発見を覚えておいて: "X は Y のときだけ動く"
# → pm_remember(content="X は Y のときだけ動く", type="insight", tags=["..."])

> このタスク (PMSERV-042) に紐付けて記憶: "Z を試したが失敗"
# → pm_remember(content="...", task_id="PMSERV-042", type="observation")

6.3 想起 (recall) の使い分け

6.4 cleanup (定期メンテ)

> 30 日以上前の memory を dry-run で出して
# → pm_memory_cleanup(days=30, dry_run=True)
# 危険なので default dry_run=True、actual=True で実削除

7. Issue 管理 — defect vs enhancement

レビュー中に「課題」を発見した時、欠陥 (defect) か 将来改善 (enhancement) かで挙動が変わる。

7.1 典型的な flow

> PMSERV-042 を完了。
# → pm_update_task(..., status="done")

> レビュー中に edge case の漏れを発見。issue 起票。
# → pm_add_issue(parent_id="PMSERV-042", title="...", severity="defect")
# → warnings: [{ "code": "parent_reverted", "message": "PMSERV-042 done → review" }]

# ⚠ Claude は必ず warnings を user に明示すること (CLAUDE.md ルール)

> 欠陥を修正、issue 完了。
# → pm_update_task(child_id, status="done")
# → all_issues_resolved=true なら「親 PMSERV-042 を done に戻しますか？」と提案

8. Dashboard

HTML / テキスト両形式のダッシュボード。pm_dashboard はカレント project、portfolio dashboard は全 project 横断。

> dashboard を HTML で出力
# → pm_dashboard(format="html") → file path を返す

> portfolio dashboard を出して
# → 全 registered project を集約した HTML を生成

8.1 ファイルの場所

9. Multi-Host 対応 — Claude Code / Desktop / Codex の役割分担

9.1 install / update のターゲット切り替え

$ pm-server install --target=auto      # 環境を自動検出
$ pm-server install --target=all       # 全 host (Code + Codex)
$ pm-server install --target=codex     # Codex CLI のみ

$ pm-server update-rules --target=all --all  # 全 host × 全 project の rule 注入

10. Desktop Outbox (Phase 2) — Desktop ⇄ Code の bridge

Claude Desktop は本来 RO だが、Phase 2 (ADR-019) で「専用 outbox DB に append-only で書ける」拡張が入った。 main の .pm/memory.db は不可触のまま、Desktop ユーザーが「あとで Code 側で memory に取り込みたいアイデア」を その場で保存できる。

10.1 Desktop 側 — 思いついた瞬間に保存

> (Desktop で) このアイデアを覚えておいて: "X を Y で実装したい"
# → pm_outbox_remember(content="...", type="memory", source_project="/path/to/my-app")
# → ~/.pm/desktop/desktop.db に append (status=pending)

> (Desktop で) 今日のメモ: "Z に着手"
# → pm_outbox_log(entry="Z に着手", category="progress")

10.2 Code 側 — レビューして promote

> (Code で) Desktop 未処理を見せて
# → pm_outbox_pending() → status=pending の一覧 (paginated, limit=50)

> id=3, 5, 7 を my-app project に merge
# → pm_outbox_merge(ids=[3, 5, 7], target_project="/path/to/my-app")
# type=memory/lesson → MemoryStore.save()
# type=log → daily/YYYY-MM-DD.yaml に追記

> id=4 は要らない、reject
# → pm_outbox_reject(id=4, reason="duplicate of memory:120")

10.3 manifest 自動伝播 (v0.8.0)

v0.8.0 の .mcpb manifest は PM_DESKTOP_WRITE=1 を自動 propagate する (PMSERV-100)。 Desktop ユーザーは bundle を drag & drop するだけで outbox bridge が成立する。

11. Hooks & CLAUDE.md — pm-server を「自律」させる 2 つの経路

pm-server が「ユーザーが叩かないのに動く」のは 2 つの違う仕組みのおかげ。

11.1 CLAUDE.md auto-action rules (LLM レイヤ)

pm-server update-rules が CLAUDE.md / AGENTS.md に注入する「自動行動ルール」セクション。 Claude が prompt 解釈時にこれを参照し、適切なタイミングで pm_* ツールを発火する。

例: 「セッション開始時に pm_status / pm_next / pm_recall を実行する」「タスクに着手する前に in_progress に変更する」等。

11.2 Claude Code hooks (ランタイムレイヤ)

pm-server install-hooks が ~/.claude/settings.json に登録する PostToolUse hook。 ツール実行直後に pm-server がコールバックされ、context を memory に転写したり diagnostic を更新する。

11.3 二経路の使い分け

12. 上級 Tips & よくある落とし穴

12.1 「複数 project を扱う日」のお作法

resolve_project_path() は cwd から最も近い .pm/ を探す。 別 project に切り替える時は 必ず cd してから Claude に頼むか、明示的に project_path を指定する。

> /Users/me/repo-B の pm_status を出して
# → pm_status(project_path="/Users/me/repo-B")

12.2 pm_status.diagnostics を毎朝チェック

• utils_fingerprint.stale: 旧 binary が cache されてないか
• builtin_templates_dir.exists: workflow テンプレートが壊れてないか
• outbox_pending: Desktop からの未処理アイデアが溜まってないか

12.3 cross_project 検索を有効活用

「過去の project でこれと似たことやらなかったか」を pm_memory_search(cross_project=True) で全 project 横断検索。 再発明を防ぐ唯一の手段。

12.4 quote するなら ID で

memory の content 内で他の memory / ADR / KR を参照する時は memory:152 / ADR-019 / KR-005 の形式で書く。後で pm_memory_search("ADR-019") で逆引きできる。

12.5 YAML を直接編集しない

.pm/*.yaml は基本的に MCP ツール経由で書き換える。手動編集が必要な場合は commit 前にロード (pm_status 等) して schema 妥当性を確認すること。

12.6 commit 粒度

1 task = 1 commit (atomic) を厳守すると pm_velocity の精度が上がる。 PR 単位ではなく task 単位で commit を切る (CLAUDE.md rule)。

13. FAQ & トラブルシューティング

Q. claude mcp list に pm-server が出ない

A. pm-server install --dry-run で何が起きるか確認、必要なら pm-server install 再実行。 ~/.claude/mcp_servers.json も直接 grep してみる。

Q. Claude が auto で pm_status を呼んでくれない

A. CLAUDE.md の auto-action rules セクションが古いか欠落している可能性。 pm-server update-rules を実行。global CLAUDE.md (~/.claude/CLAUDE.md) と project CLAUDE.md の両方を確認する。

Q. pm_recall が前回 session を返さない

A. 前回 pm_session_summary が呼ばれていない可能性。 CLAUDE.md rule に「/clear 前に pm_session_summary」とあるが、 クラッシュ等で呼ばれない時は ~/.pm/memory.db に session が残っているか sqlite3 ... "select session_id from session_summaries" で直接確認できる。

Q. Desktop で pm_outbox_remember がない

A. PM_DESKTOP_WRITE=1 が立ってない。v0.8.0 .mcpb なら manifest で自動伝播されるが、 既存の旧 config を手動更新する必要がある場合は claude_desktop_config.json の env に PM_DESKTOP_WRITE を追加する。

Q. WAL sidecar (memory.db-shm) が大量に生成される

A. v0.7.0+ で Lens モードでは ?mode=ro&immutable=1 で接続するため発生しないはず (PMSERV-080)。発生する場合は pm-server の version を pm-server --version で確認。

Q. pm_add_issue(severity=defect) で親 task が done に戻った警告を見逃した

A. CLAUDE.md rule で warnings[] を明示するよう書かれているが、Claude が拾い損ねる場合がある。 疑わしい時は pm_tasks(parent_id="PMSERV-XXX") で親と子の整合性を確認。

Q. workflow を間違えて start してしまった

A. pm_workflow_abandon で放棄できる (履歴は残る)。state は preserve されるので、 後で pm_workflow_list(status="abandoned") で見返せる。

Q. cross-project 検索が遅い

A. ~/.pm/memory.db が大きくなりすぎている可能性。 pm_memory_stats でサイズ確認後、pm_memory_cleanup(days=180) で古い observation を整理。

13.1 もっと深く知りたい時

• 内部実装 → Architecture & Behavior
• workflow テンプレート作成 → Workflow Guide
• 全 MCP ツール一覧 (簡潔版) → Cheatsheet (ja)
• 設計判断の経緯 → design.md