dev-agent-teamシリーズの4本目。 設計思想、 実運用で出た失敗と対処、 学びの一般化に続いて、 今回は「Claude Code本体が出した新機能を、自作ワークフローと併用する話」。
この記事の要点
  • 本体の新機能が出ても自作ワークフローは陳腐化しない——レイヤーが違う
  • 型（何を・なぜ）とエンジン（どう動かすか）は競合せず積み重なる
  • 大原則：人間の承認ゲートはエンジンの自律ループに越えさせない

dev-agent-team = 型

  • 何を・なぜやるか
  • Stop Condition / 人間の判断点
  • 各Phaseのチェックリスト

/goal・Workflows = エンジン

  • どう動かすか
  • ループ・並列ファンアウト
  • 実行の駆動力

Claude Code本体に /goal（自律ループ）と Dynamic Workflows（並列オーケストレーション） が入った。これを見て、もっともな疑問が湧く—— 「Anthropicがこういう便利機能を出すなら、自作の dev-agent-team はもう要らないのでは?」

今回の改善（PR #16）は、 この問いに正面から答えるためのものだ。結論から言うと 冗長ではない。レイヤーが違う。だから競合せず、積み重なる。

1. 「何を・なぜ」と「どう動かすか」は別レイヤー

整理するとこうなる。

  • dev-agent-team = 「何を・なぜ」 — 意思決定の型。 Stop Condition（どこで止まるか）、Human Decision Point（どこで人間が判断するか）、 各Phaseのチェックリスト。
  • /goal や Dynamic Workflows = 「どう動かすか」 — 実行エンジン。 ループを回す、並列でファンアウトする、といった駆動力。

この2つは競合しない。型は「正しい順番で、正しい場所で人間を挟んで進める」ことを保証し、 エンジンは「それを速く・並列に実行する」。 型をより強力なエンジンで実行するために取り込む——というのが今回の方針だ。

逆に言えば、エンジンだけあっても「どこで止まるべきか」「何を人間に確認すべきか」は決まらない。 便利な実行基盤が出たからこそ、それをどう型にはめて使うかの指針が要る。

2. 大原則：人間ゲートはエンジンに越えさせない

今回いちばん大事に据えたのがこれだ。 /goal の自律ループは強力だが、放てば承認も確認もスキップして突っ走る。 だから併用には明確な制約をかけた。

  • /goal は「機械的サブループ」限定。 テストが通るまで直す、lintが消えるまで直す——のように 機械が成否を判定できる閉じたループにだけ使う。
  • Human Decision Point・承認系の Stop Condition は越えさせない。 「これで進めてよいか」の人間判断は、エンジンの自律ループの外に置く。

この線引きを運用で効かせるため、ワークフロー定義の Stop Condition に 〔機械検証可〕／〔人間判断〕のタグを付ける規約を導入した。 前者はエンジンに任せてよく、後者は必ず人間で止まる。 タグがあることで「ここは自動化していい / だめ」が一目で分かる。

3. Dynamic Workflows で Phase 2（Discovery）を並列化

併用の具体例として、Phase 2のDiscovery（既存コード調査）を並列化する Dynamic Workflow /dev-agent-discovery を実装した。

多数のファイルやサブシステムにまたがる調査は、1つずつ読むと時間がかかる。 そこで pipeline() で候補ファイルを並列に読解し、 investigation-report（関連ファイル / 類似実装 / 規約 / 暫定変更リスト / 未解決の確認事項） という構造に集約する。

ここで効いているのが先の大原則だ。このワークフローの 内部には人間ゲートを置かない。 並列調査はあくまで機械的なファンアウトで完結させ、 完了後に人間がPhase 3へ進む前にレビューする立て付けにした。 Dynamic Workflowsの併用は「単一フェーズ内のファンアウト」に限定し、 フェーズをまたぐ判断はエンジンに持たせない。

インストール周りも対称に整えた。install.sh / uninstall.sh に WORKFLOWS 配列を追加し、dynamic-workflows/*.js を ~/.claude/workflows/ へsymlink配置・削除する （コマンド処理と同じ形、env override対応）。

4. あえて「やらなかった」こと

ここでも線引きを明確にした。やれるけれど今回はスコープから外したものがある。

  • 8 Phase全体の無人ワークフロー化 — 全部を /goal で自律化することはしない。 人間判断のPhaseが残る以上、全自動は原則に反する。
  • agents / skills のネイティブ形式（frontmatter / SKILL.md）への変換 — 将来課題としてドキュメントに明記し、今回は見送り。

「便利機能が出たから全部それに乗せ替える」のではなく、 型の本質（人間が判断すべき場所）を守れる範囲でだけエンジンを取り込む。 この判断自体を docs/native-tooling-integration.md に レイヤー対比表・併用ルール・判断早見表として残した。

5. まとめ

本体機能の進化は、自作ワークフローを陳腐化させるとは限らない。 むしろ「型」と「エンジン」のレイヤーを分けて考えると、新機能は型を強化する燃料になる。

  • dev-agent-team =「何を・なぜ」、ネイティブ機能 =「どう動かすか」。競合せず積み重なる
  • /goal は機械的サブループ限定。人間ゲートはエンジンに越えさせない
  • Dynamic Workflowsは単一フェーズ内のファンアウトに限定して取り込む
  • 便利だからと全部乗せ替えず、型の本質を守れる範囲だけ統合する

「新機能が出た＝自作の仕組みは不要」と短絡せず、 自分の型のどのレイヤーに効くのかを見極めて取り込む。 この見極めができると、本体の進化を毎回そのまま味方にできる。

なお、この /dev-agent-discovery は構文検証だけで実走していなかった。 次の記事では、実際に動かしてみて出たバグの話を書く。

リポジトリはこちら: fecot/dev-agent-team