dev-agent-teamシリーズの14本目。 前回（自作ツールに、廃止論を全力で書かせた）で キットの価値の重心が移ったという結論を出した。 ならば一度、いまこれが何なのかを通しで再掲しておくべきだろう——という記事。 シリーズを追っていない人はここから読んでもらって構わない。
この記事の要点
  • 構成はほとんど変わっていない——Agent 7本 / Skill 8本 / Command 6本 / Phase 0〜8のワークフロー
  • 変わったのは役割。「熟練者の手順を明文化した手順書」から始まり、いまは別のものになっている
  • 転換①手順書 → 線引き：AIがどこまで先に動いてよいかを決める役へ
  • 転換②型 → 型＋エンジン制御：/goalや並列実行に手綱をつける役へ
  • 転換③賢さの明文化 → 現場の台帳：踏んだ罠と下した判断を貯める役へ

dev-agent-team は、 Claude Code向けの開発支援キットだ。個人の実験リポジトリとして2026年5月1日に作り始めて、 いま4か月目に入っている。

出発点にあった問題意識は、いま読み返しても変わっていない。

優秀なエンジニアでも、タスクが積まれ余裕がなくなると「とりあえず動くものを書く」モードに入る。 問題は「個人の能力」ではなく「プロセスの欠如」だ。 型がなければ、忙しい状況では人は省略する。

だから「熟練者が無意識に踏んでいる手順」を明文化して、Claude Codeに実行させる。 それが当初の狙いだった。そして、そこがいちばん大きく変わった部分でもある。 先に現物を出してから、何がどう変わったのかを書く。

1. いまの構成——全体像

ファイル構成はこうなっている。数字は2026年8月24日時点の実数だ。 

dev-agent-team/
├── agents/      7本   各フェーズを担当するエージェント定義
├── skills/      8本   エージェントが使う汎用スキル
├── commands/    6本   スラッシュコマンド
├── workflows/   1本   Phase 0〜8 の標準開発フロー（人間が読む型）
├── dynamic-workflows/ ネイティブ実行スクリプト（JS）
├── templates/   6本   成果物のテンプレート
├── docs/        3本   導入ガイド / ネイティブ併用 / トラブルシュート
├── CONCEPT.md         「型を作るとはどういうことか」
└── CHANGELOG.md       v0.1.0（05/04）→ v0.2.0（07/13）→ 現在
workflows（人間が読むプロセスの型）と dynamic-workflows（ランタイムが実行するJS）は別物。混同しないよう名前を分けている

1-1. Agent 7本——8フェーズの担当割り

中核はここだ。開発プロセスを分解して、各局面に担当エージェントを置いている。

1ProductInterpreter — イシューを受け取り、まず要件を整理する
↓
2CodebaseExplorer — 既存コードを読んで文脈を把握する
↓
3ArchitectureReviewer — 変更の影響範囲を分析する
↓
4ImplementationDriver — 実装案を複数出す。最小案も必ず含める
↓
5TestStrategist — テスト観点を明示する
↓
6ReviewGatekeeper — PRを説明可能な状態にする
↓
7ReleaseCaptain — リリースリスクを確認する

これを繋いだのが workflows/feature-development.md の Phase 0〜8——Project Context Loading / Intake / Discovery / Impact Analysis / Implementation Planning / Safe Implementation / Test Design / Review Gate / Release Check。

Phase 0が最初から独立しているのが地味に効いている。 ここで対象リポジトリのルールを読み込む。キットの共通ルールより対象リポジトリのルールが上だからだ。

1-2. Rule Priority——迷ったときの優先順位

1ユーザー（人間）の明示指示
2対象リポジトリの Project Rules（CLAUDE.md / README / docs/ 等）
3dev-agent-team の共通 Workflow / Commands / Agents / Skills
4一般的なベストプラクティス

キットの共通ルールが対象リポジトリのルールを上書きしてはいけない。 汎用キットが現場を殴り返すと、現場では使われなくなる。

1-3. Command 6本と Skill 8本

Commandは入口だ。/adopt-project（導入）、/run-feature-workflow（通しで回す）、 /issue-to-plan、/codebase-explore、/safe-implement、/pr-review。 全部を通さず、必要な局面だけ単発で呼べるようにしてある。

Skillは横断で使う道具立てで、requirement-analysis / codebase-reading / impact-analysis / test-design / safe-refactoring / browser-verification / migration-spec-capture / legacy-modernization の8本。 後半3本は実プロジェクトで痛い目を見て足したもので、ここが後述の「台帳」の性格を帯びている。

1-4. 導入

git clone https://github.com/fecot/dev-agent-team.git ~/.claude/dev-agent-team
cd ~/.claude/dev-agent-team && ./install.sh

# あとは対象プロジェクトで
/adopt-project
ホーム配下に1回クローンし、入口コマンドをシンボリックリンクで配置する。更新は git pull だけで反映される（macOS / Linux。Windowsネイティブは対象外）

2. 変わったこと——3つの転換

ここからが本題だ。上に書いた構成は、初期からほとんど変わっていない。 エージェント7本もフェーズ構成も、5月の時点でだいたい今の形だった。 変わったのは、このキットが何のためにあるのかのほうだ。

転換① 手順書 → 線引き

当初（2026年5月）

  • 熟練者の手順を明文化する
  • AIに正しい順番を踏ませる
  • 価値の源泉＝手順の網羅性

いま

  • Human Decision Point（人間が判断を下すべき地点）を定義する
  • AIが先に動いてよい範囲を決める
  • 価値の源泉＝線引きの正しさ

理由は単純で、手順の明文化はモデルが強くなるほど価値が目減りするからだ。 「コードを読んでから仮説を立てろ」「影響範囲を洗ってから実装しろ」—— こういう指示は、いまのモデルなら言われなくてもやる。 公式ガイドも「従来モデル向けの細かい指示はかえって品質を落としうる」と明言している。

一方で、どこで人間に確認を取るべきかはモデルの側から出てこない。 破壊的・不可逆な操作か、スコープが変わるのか、本人にしか出せない入力か—— この線引きだけは外から与えるしかない。だからキットの重心はそちらへ寄った。

転換② 型 → 型 ＋ エンジン制御

6月以降、Claude Code本体に /goal（自律ループ）、Dynamic Workflows（並列実行）、 Scheduled Tasks、Agent Teams が入った。 当然「じゃあこのキット要らないのでは」という話になる—— 前回の記事はまさにその検証だった。

結論は置き換えではなく積層。エンジンは「どう動かすか」を提供するが、 あなたのプロセスを知らない。だからキットの側に、併用ルールを定義する章が増えた。 

docs/native-tooling-integration.md

§2  /goal の併用ルール         → 機械的サブループ限定
§3  Dynamic Workflows          → 単一フェーズ内の fan-out 限定
§5  エンジンに委譲しないもの   → 人間判断のコア
§6  Agent Teams                → リードAIの承認は人間の承認ではない
§7  Scheduled Tasks            → 自己再発火の禁止
ネイティブ機能そのものではなく、「どこまで使わせるか」だけを定義している

つまりキットは、エンジンの競合ではなくエンジンに手綱をつける側に回った。 /goal は「終了条件を満たすまで回す機構」であって、 終了条件の中身は持っていない。そこを埋めるのが型の役目だ。

転換③ 賢さの明文化 → 現場の台帳

そして、いま最も投資している層がこれだ。CONCEPT.mdには型は二層あると書いてある。

汎用の賢さの明文化

  • 誰でも踏む手順
  • モデル世代が上がるたび吸収されていく
  • 方針：原則と「なぜ」だけ残して痩せさせ続ける

現場の台帳

  • Known Risks（踏んだ罠）
  • Decision Log（下した判断と理由）
  • 移行の計測項目、無主物リスト
  • 方針：投資を寄せる。使うほど・失敗するほど太る

この層は、どれだけモデルが賢くなっても外から与えるしかない。 あなたの現場で何が落ちたかを、モデルは知らないからだ。

Decision Logは今月足したばかりの新顔で、 判断 / 理由 / 再利用条件の3点セットで記録する。 理由を必須にしたのが要点だ。判断だけ残すと、 前提が変わったときに見直す手がかりがなく、ただの縛りになる。

3. 事故が型になる——いちばん分かりやすい例

「現場の台帳」がどういうものか、実例を1つ挙げるのが早い。

以前、ルーチンが自分自身を毎時再アームし続けて、 2日間・185回にわたってトークンを空費した事故を起こしている。 原因は監視対象が人間待ち（PRのマージ）だったことだ。 人間が動くまで状態が変わらないので、終了条件が原理的に存在しない。

この教訓が、いまキットの docs §7 に 「自己再発火の禁止」として入っている。そして重要なのは、 これはネイティブの汎用ガードレールでは拾えないということだ。 「終了条件が原理的に存在しないループを検出して止める」機構は、ランタイムに存在しない。

人間ゲートは「越えさせない」だけでは足りず、「待たせてもいけない」。 ゲートを飛び越える事故と、ゲートの手前で止まらなくなる事故は、同じ場所で起きる。 この一文は、実際に殴られるまで書けなかった。

4. で、いまこれは何なのか

一言でまとめるとこうなる。

AIに何をさせるかを書いた手順書ではなく、
AIにどこで止まってもらうかの線引きと、その現場でしか得られない失敗と判断の台帳。

当初の「熟練者の手順を明文化する」という狙いは、半分は達成され、半分は本体に吸収された。 吸収された分を惜しまずに削り、吸収されない側に寄せ続ける—— いまのメンテナンス方針はそれだけだ。

この方針を維持するために、今月取り込み基準も明文化した。 ネイティブ機能の変更は「人間ゲートの位置または強度が変わるもの」だけ取り込む。 「新機能が出たら検討する」だと追随コストが無限に増えるが、この基準なら 本体がどれだけ機能を出しても仕事量は増えない。

5. まとめ

  • 構成は初期からほぼ不変——Agent 7 / Skill 8 / Command 6 / Phase 0〜8
  • 変わったのは役割。手順書 → 線引き → 台帳と重心が移った
  • キットはエンジンの競合ではなく、エンジンに手綱をつける側
  • 汎用の賢さは痩せさせ、現場の蓄積を太らせる。前者は吸収され、後者は吸収されない
  • 事故から書いたルールがいちばん強い。殴られるまで書けない文がある

個人の実験リポジトリなので万人向けではないが、 「AIに任せる範囲をどう線引きするか」で悩んでいる人には、 CONCEPT.md と docs/native-tooling-integration.md の2本だけでも 読む価値があるかもしれない。

github.com/fecot/dev-agent-team ——本記事で触れた Decision Log と取り込み基準は、いずれも main にマージ済み。