2026-09-10 · claudecode · 設定 · 個人開発 · ai · devops
5人格のうち4つで回っていて、ふつうに動いているように見えた
Claude Code を、権限の違う5つのサブエージェントとして使っています。 設計者・実装者・レビュアー・コンフリクト解消担当・UIデザイナー。
そのうち1つが、読み込まれなくなりました。
どこにも出ませんでした。 作業は残った人格に振り分けられて進みます。 遅くなり、レビューが甘くなり、宣言した scope が守られなくなる。 どれも「モデルの調子が悪い」に見える症状です。
症状は「うまく動いていない」の形で、原因は「そこに居ない」でした。
.claude/agents/ のファイルは、黙って飛ばされる
frontmatter に次のどれかがあると、そのファイルはサブエージェントとして扱われません。
| 条件 | 何が起きるか |
|---|---|
name が無い |
ドキュメント扱い。エージェントの横に置いたメモと同じ |
開きの --- が1行目でない |
frontmatter 無しと読まれ、やはりドキュメント扱い |
name が - で始まる／: を含む |
ファイルごとスキップ |
name はあるが description が無い |
スキップ |
| YAML として壊れている | 何も読まれずスキップ |
どれもセッションには出ません。 理由はデバッグログにだけ出て、
それは --debug で見えるもので、うまくいっているように見えるときには付けていません。
私が踏んだのは2行目です。人格ファイルに内容を貼り付けたとき、
エディタが開きの --- の上に何かを入れました。
以降そのファイルは、4人のエージェントの隣に置かれた散文で、
Claude はその仕事を残りに振り分けていました。
: が使えないのは、プラグイン用の名前（my-plugin:reviewer）に予約されているためです。
先頭の - も同じ類の理由で使えません。
人格を複製するときが、いちばん面白い
人格を足すのに既存のファイルを複製するのは自然な手で、
name を変え忘れるのも自然な間違いです。
同じ名前のファイルが2つあるとき、どちらが読み込まれるかは文書化されていません。 ファイルシステムの読み出し順で決まります。
つまり同じリポジトリが、マシンによって別の人格を動かします。 そして両方のマシンが「動いています」。
これで痛い目を見た話は持っていません。運が良かっただけだと思っています。
claude plugin validate は途中まで連れて行ってくれる
claude plugin validate .claude/agents
claude plugin validate ~/.claude/agents
パースできない frontmatter を見つけます。 制限が2つあります。
- 指定したディレクトリしか見ません — ユーザ側は別に指定する
- 「パースはできるが
nameが無い」ファイルは出ません
上の表のほとんどがこちらです。回す価値はあり、それだけでは足りません。
自分のせいだったもの
実装者の人格に、これが入っていました。
tools: *
「こいつには全部使わせる」という意味です。
tools が受け付けるのは正確なツール名か、
サーバ単位の mcp__<server> / mcp__<server>__* です。
裸の * はそこに含まれておらず、解決できない項目があると
サブエージェントは起動を拒否されます。
「全部」の文書化された書き方は、欄ごと省くことでした。
自分の検査ツールがなぜこれを見られなかったかは別に書きました。
https://zenn.dev/quintetkit/articles/blind-spot-from-refusing-to-check
短く言うと、誤検出を避けるために書いた規則が
「tools の欄を見ない」という形になっていたからです。
これは人格が1つ欠けるより悪いです。coder はコードを書く人格なので。
他の4つは動くので、症状は**「今日は実装者の調子が悪い」**の形で出ます。
いまやっていること
検査は2つ、そして回すのは2回だけです。セットアップ直後と、人格を足したとき。
npx @quintetkit/ccheck # 5条件・名前の重複・tools: *
claude --debug # 1回だけ。何が飛ばされたか、理由つきで見る
そしてどちらより安い習慣が1つ。数えることです。
設定が5人格だと言っているなら、確かめたいのは5つ読み込まれたことで、 作業が進んでいることではありません。作業が進んでいるかは、最初から問いではなかった。
5条件と、書ける全項目を1枚にしたものはこちらです。
https://quintetkit.github.io/reference/claude-code-subagent-frontmatter.html
Claude Code に設計・実装・レビューを別々の人格として分担させ、GitHub Issue と
ブランチを軸に並列開発を回すための設定一式を MIT で公開しています。
コピーして ./setup.sh を叩けば動きます。技術スタックには依存しません。
https://github.com/quintetkit/quartet
このワークフローだけで実際にツールを 1 つ作りました。Issue の分割から PR、 レビュー、マージまで記録が全部残っています。うまくいかなかった箇所も消していません。
https://github.com/quintetkit/mdlinkcheck
UI 設計人格・レビュー基準・Issue 単位の並列実行スクリプト・実践ガイド 11 章を 足したものは製品ページにあります。
実践ガイド全 11 章は Zenn Book で読めます（¥1,500・2章まで無料）。
https://zenn.dev/quintetkit/books/claude-code-parallel-workflow
設定一式（5人格・スクリプト・ガイド全文）の配布はこちらです。