docs: CLAUDE.md 監査による Agent Teams 記述の更新とプラグイン宣言の同期

[fumtas1k]

目的

claude-md-improver skill による CLAUDE.md 監査の結果を反映する。**スコア 87/100（Grade B）**で、最大の弱点は Currency（10/15）だった。

対象ファイルは ./CLAUDE.md 1 件のみ（.claude.local.md / ~/.claude/CLAUDE.md は未使用）。@import 先 4 ファイルは全て実在確認済み。

修正した 3 点

1. Agent Teams セクション（Currency）

公式ドキュメントと突き合わせ、以下の乖離を修正した。

項目	修正内容
teammateMode の既定値	v2.1.179 で "auto" → "in-process" に変更された旨を追記
"tmux" の前提	split-pane モードで tmux / iTerm2 (it2) が必須。VS Code 統合ターミナル / Windows Terminal / Ghostty では非対応と明記
廃止された API	TeamCreate / TeamDelete は廃止済み（事前セットアップ不要）、Agent tool の team_name は受理されるが無視される
「使わない場面」の欠落	公式は「逐次タスク・同一ファイル編集・依存の多い作業では単一セッションか subagent が効果的」「2 人が同じファイルを編集すると上書きになる」と明記しているが、旧記述は「活用する場面」3 つのみだった
トークンコスト	「単一セッションより著しく多く消費」「初手 3〜5 teammate」「実装並列より research / review から」を追記

なぜ重要か: 旧記述の「長大な実装を複数エージェントで分担する場合」は公式の file conflict 警告と衝突し、また .agents/rules/common.md 6.9 節の委譲判断（往復コストを踏まえて委譲しない条件）とも方向性が矛盾していた。

2. プラグイン宣言のドリフト（Currency）

claude-md-management を install したが enabledPlugins に宣言されていなかった。claude plugin install はユーザーレベル設定に書き込むため、宣言漏れだと session-install.sh が読めず web セッションでは install されない。

• .claude/settings.json の enabledPlugins に追加
• CLAUDE.md の推奨プラグイン表に行追加
• 「リポジトリで共有するプラグインは必ず宣言する / 個人的に試すだけのものは宣言しない」と境界を明記

3. 前提モデル節を新設（Actionability）

settings.json は model: "opus[1m]" を指定しているが CLAUDE.md にその前提が書かれておらず、規約の背景が追えなかった。opus が現行世代の最新 Opus を指すエイリアスであること、規約が執筆時点の現行世代（Claude Opus 5）の既定挙動（応答・生成ドキュメントが長い / subagent 委譲に積極的）を前提にしていること、エイリアスの解決先が世代更新されたら本節を見直すことを出典付きで明示した（世代番号の固定は避けた → レビュー指摘対応）。

監査で判明したが修正していないもの

• Commands 18/20: 初回 clone 時の npm ci が worktree 文脈（common.md 6.2.1）にしか書かれていない。実害が小さいため未対応
• Non-obvious patterns 15/15: Tailwind v4 の variant 非対応、docs/ auto scan 除外、loopback deny、workflow_dispatch 403 等が事故 PR 番号付きで根拠を残しており、この項目は模範的。変更不要

取り下げた注記: session-install.sh の unbound variable

当初「npm run test の stderr に .claude/scripts/session-install.sh: line 65: plugin: unbound variable が出る」という別 issue 候補を記載していたが、再現しないため取り下げた。

• bash .claude/scripts/session-install.sh を 3 回直接実行 → 一度も再現せず
• レビュー側でも develop で再現せず
• set -u は 15 行目にあるが、while IFS= read -r plugin は入力が空でも plugin を束縛するため set -u には引っかからない（レビューの指摘どおり）
• 初回観測時の出力は変数名部分が文字化けしており（plugin?:）、hook の stderr がテスト出力に混線した見かけ上の症状と判断

.agents/rules/common.md 6.4 節は「先送りは必ず issue 化」を求めるが、これはスコープ判断による先送りではなく再現しない観測なので、issue 化せず本文から削除する扱いとした。

検証

チェック	結果
settings.json JSON 妥当性	✅ valid
npm run format:check	✅ pass（初回 fail → npm run format でテーブル整形修正）
npm run test	✅ 148 files / 2716 passed, 1 skipped
node_modules/.bin/astro check	✅ 0 errors / 0 warnings / 0 hints
npm run test:e2e	⏭️ 未実行

E2E 未実行の理由: diff は CLAUDE.md と .claude/settings.json のみで、src/ tests/ に変更がなく E2E が検証する実行時挙動に影響しない。CI を最終ゲートとする。

関連

PR #758（.agents/rules/common.md への出力量の規律・委譲判断の追加）と同じ監査の流れだが、対象ファイルが異なるため独立した PRにしている。本 PR の「前提モデル」節は #758 で追加する規約を参照するので、#758 → 本 PR の順でマージするのが自然（逆順でも壊れない）。

🤖 Generated with Claude Code

---

レビュー対応（2026-07-28）

指摘	対応	commit
nit: 「前提モデル」節の Opus 5 ハードコードが Currency ドリフトを再導入する	✅ 修正。opus がエイリアスである旨を明記し、世代番号は「執筆時点の現行世代」として位置づけ、解決先が移ったら見直す旨を追記	02e767f
deferral 整備: unbound variable は再現しないので issue 化するか注記を落とす	✅ 対応。3 回直接実行して再現せず、注記を本文から取り下げた（上記「取り下げた注記」参照）	本文のみ
任意: teammateMode: "tmux" 設定値そのものの再考	⏭️ 対応不要と判断（レビューの見解と一致）。docs-only の本 PR で caveat を明文化済みのため、設定値の変更は別途

nit 修正の差分

-`.claude/settings.json` で `model: "opus[1m]"`（Claude Opus 5 / 1M context）を指定している。`.agents/rules/common.md` の…
+`.claude/settings.json` で `model: "opus[1m]"` を指定している。`opus` は **現行世代の最新 Opus を指すエイリアス**
+（`[1m]` は 1M context 版）であり、世代が更新されれば解決先も移動する。
+
+`.agents/rules/common.md` の … 執筆時点の現行世代である Claude Opus 5 の既定挙動（…）を前提にしている → [Prompting Claude Opus 5](…)
+
+**エイリアスの解決先が次世代に移ったら、本節と上記規約の前提を見直すこと**（世代番号を固定した記述は Currency ドリフトの発生源になる）。

指摘のとおり、監査 PR 自身が Currency ドリフトの発生源になるのは本末転倒でした。エイリアスの性質を明示したうえで、behavioral リファレンスとしての Opus 5 リンクは残しています。

再検証（02e767f 時点）

チェック	結果
npm run format:check	✅ pass
npm run test	✅ 148 files / 2716 passed, 1 skipped
node_modules/.bin/astro check	✅ 0 errors / 0 warnings / 0 hints

[github-actions]

🖼️ Visual Regression Test 結果

• Status: ✅ 全 74 件 pass
• Workflow run: 30277119900
• Artifact (diff 画像 / playwright-report): 上記 workflow run の Artifacts セクションから download

diff が 意図的な visual 変更の場合: Update Visual Regression Baseline workflow を本 PR ブランチで workflow_dispatch trigger して baseline を更新。
diff が 意図しない regression の場合: 該当変更を fix。
本 check は required ではないため fail のままでも merge は可能（reviewer 判断）。

[fumtas1k]

レビュー（セキュリティ / デザイン / ロジック / アーキテクチャ / テスト）

docs のみの PR ですが、Currency 監査という性質上「記述内容が公式と一致しているか」が最重要なので、引用元 2 リンクを実際に取得して事実確認しました。総評: マージ可。指摘は 1 件の nit と 1 件の deferral 整備のみで、いずれもブロッカーではありません。

✅ 事実確認（公式ドキュメントと突き合わせ）

Agent teams / Prompting Claude Opus 5 を fetch し、本 PR の主張は以下すべて公式と一致することを確認しました。

• teammateMode 既定値が v2.1.179 で "auto" → "in-process" に変更（公式明記）
• TeamCreate / TeamDelete 廃止・team_name は受理されるが無視される（公式明記）
• split-pane は tmux / iTerm2 必須、VS Code 統合ターミナル / Windows Terminal / Ghostty で非対応（公式の Limitations に同記述）
• トークン線形増・初手 3〜5 teammate・research/review から（公式 Best practices に同記述）
• Opus 5 の「応答と生成ドキュメントが長い / subagent 委譲に積極的」（Opus 5 ページに同記述）

リンク切れ・記述乖離は無し。監査 PR としての精度は高いです。

✅ アーキテクチャ改善として妥当

旧記述の「長大な実装を複数エージェントで分担」を削除し**「使わない場面（逐次・同一ファイル編集・依存過多）」を新設した点は、公式の file-conflict 警告および .agents/rules/common.md 6.9 節の委譲判断との矛盾を解消**しており、監査の狙いどおりです。

🔒 セキュリティ

懸念なし。enabledPlugins に追加した claude-md-management@claude-plugins-official は既存 context7 と同じ公式マーケットプレイス由来で、session-install.sh 側の name-format regex（^[A-Za-z0-9][A-Za-z0-9_.-]*@...$）がインジェクション防止として機能したまま。宣言漏れ→web 未 install の因果も実コード（55〜65 行が enabledPlugins を読む）と一致しています。

🎨 フロントエンド / E2E

UI 差分なし。「src/ tests/ 無変更のため E2E 未実行・CI を最終ゲート」は .agents/rules/common.md 3 章の運用と整合しており妥当な省略です。

🟡 nit（ロジック / Currency）— 「前提モデル」節の "Opus 5" ハードコード

model: "opus[1m]"（Claude Opus 5 / 1M context）

opus は現行世代の最新 Opus を指すエイリアスで、次世代が出れば opus[1m] の解決先も移動します。ここに世代番号 "Opus 5" を固定すると、まさに本 PR が潰そうとしている Currency ドリフトを再導入することになります（実際このレビューを行っているセッションは Opus 4.8 で動作しており、opus が現時点で必ず Opus 5 を指すとは限りません）。

• 提案: 本文は opus エイリアス（現行世代の最新 Opus / 1M context） のように世代非依存の表現にし、Opus 5 リンクは「現行世代の挙動リファレンス」として残す。あるいは「エイリアス解決先が世代更新されたら本節も見直す」旨を一言添える。

規約の背景を明示する意図自体は良く、リンク先の behavioral 記述も正確なので、表現の微調整のみで解消できます。

🟡 deferral 整備 — plugin?: unbound variable 注記

PR 本文の別 issue 候補について、npm run test（develop）で再現しませんでした。while IFS= read -r plugin ループは入力が空でも plugin を束縛するため set -u には引っかからず、tests/meta/session-install.test.ts 実行時の stderr にも当該行は出ていません。

• 実際に断続再現する不具合なら、.agents/rules/common.md 6.4 節に従い**「必要なら起票」ではなく今 issue 化**するのが規約どおりです。
• 再現しないなら、stale な注記として本文から落とすのが無難です。

いずれも本 PR スコープ外なので、deferral の扱いを締める趣旨の指摘です。

💭 任意（ブロッカーではない）

.claude/settings.json は teammateMode: "tmux" を固定したままですが、既定が in-process に移り、かつ本リポジトリは web セッション主体です。設定値そのものの再考余地はありますが、docs-only の本 PR が caveat を正しく明文化しているので対応不要と考えます。

---

Generated by Claude Code

[fumtas1k]

レビューありがとうございます。公式ドキュメント 2 本を実際に fetch して事実確認いただいた点、特に助かりました。

nit（Opus 5 ハードコード）→ 修正しました（02e767f）

完全に正しい指摘です。 監査 PR 自身が Currency ドリフトの発生源になっており、本末転倒でした。opus がエイリアスであることを明記し、世代番号は「執筆時点の現行世代」という位置づけに変更、さらに解決先が移ったら見直す旨を追記しました。

`.claude/settings.json` で `model: "opus[1m]"` を指定している。`opus` は 現行世代の最新 Opus を指すエイリアス
（`[1m]` は 1M context 版）であり、世代が更新されれば解決先も移動する。
…
エイリアスの解決先が次世代に移ったら、本節と上記規約の前提を見直すこと（世代番号を固定した記述は
Currency ドリフトの発生源になる）。

behavioral リファレンスとしての Opus 5 リンクは、現行世代の挙動を説明する出典として残しています。

deferral 整備（unbound variable）→ 注記を取り下げました

再現性を検証した結果、取り下げが妥当と判断しました。

• bash .claude/scripts/session-install.sh を 3 回直接実行 → 一度も再現せず
• set -u は 15 行目に存在するが、ご指摘のとおり while IFS= read -r plugin は入力が空でも plugin を束縛するため set -u には引っかからない
• 初回観測時の出力は変数名部分が文字化けしており（plugin?:）、hook の stderr がテスト出力に混線した見かけ上の症状と判断

6.4 節の「先送りは必ず issue 化」に照らすと迷うところですが、これはスコープ判断による先送りではなく再現しない観測なので、issue を作らず本文から削除する扱いにしました。実際に再発したら改めて起票します。

任意（teammateMode: "tmux" の再考）→ 対応不要に同意

docs-only の本 PR で caveat を明文化できているので、設定値そのものの変更は別途とします。本リポジトリが web セッション主体である点を踏まえると "in-process" への変更は検討余地がありますが、ローカルの tmux 環境（3.7b 確認済み）で split-pane を使う運用が残っているなら現状維持が無難と考えています。

---

再検証（02e767f 時点）

チェック	結果
npm run format:check	✅ pass
npm run test	✅ 148 files / 2716 passed, 1 skipped
node_modules/.bin/astro check	✅ 0 errors / 0 warnings / 0 hints

Generated by Claude Code

[fumtas1k]

再レビュー（02e767f）— 指摘はすべて解消、マージ可

前回の 2 点をどちらも的確に対応いただけました。差分（CLAUDE.md / .claude/settings.json のみ）を再確認しました。

✅ nit（Currency ドリフト再導入）— 解消

「前提モデル」節が

• opus を現行世代の最新 Opus を指すエイリアス（[1m] は 1M context 版、世代更新で解決先が移動）と明記
• "Claude Opus 5" を執筆時点の現行世代として位置づけ（世代番号の固定ではなくなった）
• エイリアスの解決先が次世代に移ったら本節と規約前提を見直す旨を追記

という形になり、監査 PR 自身がドリフト源になる懸念は解消。behavioral リファレンスとして Opus 5 リンクを残した判断も適切です。

✅ deferral 整備 — 撤回の判断に同意

unbound variable 注記の撤回に異論ありません。while IFS= read -r plugin が空入力でも plugin を束縛する以上 set -u には該当せず、直接実行 3 回・develop 双方で再現しないなら「再現しない観測」であって §6.4 の対象（スコープ判断による先送り）ではない、という切り分けは正確です。文字化け（plugin?:）が stderr 混線由来という推定も筋が通っています。

✅ teammateMode 据え置き — 合意どおり

docs-only の本 PR で caveat を明文化済みのため、設定値変更は別途で問題なし。

---

多角観点（セキュリティ / デザイン / ロジック / アーキテクチャ / テスト）で残課題なし。#758 → 本 PR の順というマージ順序の整理も妥当です。当方は同一アカウントのため formal approve は付けられませんが、内容としては LGTM / マージ可です。

---

Generated by Claude Code