AIを使って開発しているが、品質や手戻りに悩んでいる人向け。
この記事の要点
  • AI開発でいちばん終わらないのは「最後の20%」——品質・手戻り・仕上げ
  • 解決の発想は、AIを万能な「個人」ではなく役割を分けた「チーム」として扱うこと
  • フェーズと人間の承認ポイントを設計に組み込み、再現性を担保する

AIを「個人」として使う

  • 1回の指示で全部やらせる
  • 抜け漏れ・暴走に気づきにくい
  • 品質が指示者の運任せ

AIを「チーム」として使う

  • 設計・実装・レビューで役割分担
  • フェーズ境界で人間が承認
  • 手順化され再現できる

ChatGPT や Claude を使った開発は、もはや「コードを書かせる」段階を超えている。 ただ、現場で本格的に使い始めると、誰もが似たような壁にぶつかる。

この記事では、私が個人的に作っている dev-agent-team というリポジトリを題材に、「AIをチームとして扱うとはどういうことか」「なぜそういう構造にしたのか」を整理する。 コードの解説はほとんどしない。重視するのは設計思想と運用方法、そして再現性だ。

筆者は普段 SaaS 開発をしており、フロントエンドからインフラまで一通り担当している。 Claude Code を業務と個人開発の両方で日常的に使っている立場から書いている。

1. 問題：AI開発の「最後の20%」が終わらない

AI を使って開発している人なら、たぶん全員が経験している現象がある。

これは AI が悪いわけではない。プロンプトを丸投げされた AI が、「目の前の差分」だけを見て最適化した結果だ。

つまり、AI開発の難しさは コード生成 ではなく、 その前後の判断（要件整理・既存調査・影響範囲・テスト観点・レビュー） にある。 ここを毎回プロンプトで指示し直していると、結局チーム内で品質がバラつく。担当者ごとに、AIの使い方ごとに、出力がブレる。

「動くコードを書く」より、「動くコードを 正しい手順で 書く」ほうが、実務では難しい。

2. 発想：AIを「個人」ではなく「チーム」として扱う

ここで発想を変えた。

AIを 1人の万能エンジニア として使うのをやめて、 役割の違うエージェントが協働するチーム として扱う。

人間の開発チームは、たいてい以下のような分業になっている。

これを Claude Code の Agent / Command / Skill にマッピングすればいい、というのが出発点だった。

ポイントは2つある。

  1. 役割を分けることで、各エージェントの責務が小さくなる → プロンプトが短くなり、出力が安定する。
  2. フェーズ単位で人間が介入できる → 全工程を AI に丸投げせず、要件確定・実装案採用・リリース可否の判断点を人間に残せる。

これは「AI に開発を任せる」ではなく、「AI に 手順を踏ませる」設計だ。

3. 設計：dev-agent-team の構造

リポジトリは Claude Code 向けの開発支援キットになっている。中身はざっくりこういう構成。

dev-agent-team/
├── agents/      # 各フェーズを担当するエージェント定義
├── commands/    # スラッシュコマンド（入口）
├── skills/      # エージェントが使う汎用スキル
├── workflows/   # 上記をつなげた標準開発フロー
├── templates/   # 成果物のテンプレート
├── examples/    # サンプルIssueと処理例
└── docs/        # 導入ガイド・運用ドキュメント

中心にあるのは 8 Phase のワークフロー。Issue から PR まで、以下の順で進む。

なぜ「Phase」で区切ったか

各 Phase の終わりに、必ず以下を出すようにしてある。

これは「AI が暴走しないようにするためのブレーキ」ではなく、 AI の判断を人間がレビューしやすくする粒度 を作るためだ。 Phase 1 の要件整理が間違っていれば、Phase 5 まで進んでから手戻りすると痛い。だから Phase 1 で必ず人間に見せて止まる。

ルールの優先順位を明示する

複数の指示が衝突したとき、どれを優先するかを明示してある。

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

これが地味に重要で、汎用キットが対象リポジトリのローカルルールを上書きしないこと を保証している。 「AI が勝手に流儀を持ち込んで現場のルールを壊す」のを防ぐ、ただ一つの安全装置だ。

/adopt-project という入口

利用側は、ホーム配下に1回だけクローンしておく。

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

これで ~/.claude/commands/adopt-project.md がシンボリックリンクで配置され、 どのプロジェクトディレクトリからでも /adopt-project が呼べる。 対象リポジトリ側には .dev-agent-team/ が生成され、Project Rules の雛形が置かれる。 git pull するだけで全プロジェクトに更新が反映される。

細かい工夫だが、「導入コストが低くないと、自分以外は使ってくれない」という運用上の現実から来ている。

4. なぜうまくいったか

実際に運用してみて、効いたポイントは3つあった。

(1)「いきなり実装しない」がデフォルトになる

dev-agent-team の基本方針には、こう書いてある。

これらは新しい話ではない。シニアエンジニアが当たり前にやっていること を、AI に強制しているだけだ。 ただ、「当たり前」を毎回プロンプトで書くのは現実的じゃない。仕組みに埋め込むことで、毎回確実に踏まれるようになる。

(2) Artifact を Git 管理しない

要件整理・調査・計画・レビューといった中間成果物（Artifacts）は、原則 Git にコミットしない。 Git に残すのは .dev-agent-team/project-rules.md だけで、重要な判断は PR 本文に要約する。

これは「AI 由来のドキュメントが増えすぎてリポジトリが汚れる」問題への答えだ。 Artifacts は判断のための一時ファイルであって、コードと一緒にレビューする対象ではない。 残すべきは判断結果であって、思考プロセス全体ではない。

(3)「速さ」を捨てた

dev-agent-team は爆速開発ツールではない。READMEにも明記してある。

dev-agent-team は「爆速開発ツール」ではありません。開発判断（要件確定・実装案採用・リリース可否）の品質を、担当者によらず一定水準に揃えるための「型」です。

メールアドレス検索を追加するだけの小さな機能でも、全 Phase を通す。 無駄に見えるが、「型を踏んだ判断」と「型を踏まない判断」の差 は、長期で見ると手戻りコストに直結する。

5. 失敗と注意点

ここからは正直な話。うまくいかなかったことも多い。

Phase を増やしすぎると人間が読めなくなる

最初は 12 Phase くらいあった。が、各 Phase の Output を人間がレビューしきれず、結局スキップする運用になった。 人間がレビューできる粒度に Phase を切らないと、ただの儀式になる。 いまの 8 Phase でもまだ多いかもしれない、と思っている。

共通ルールを強くしすぎると、現場と衝突する

汎用キットなので、最初は「これはこうあるべき」という意見を強く持たせていた。 結果、対象リポジトリの流儀と衝突して、人間が毎回上書き指示を入れる羽目になった。 今は Rule Priority で「対象リポジトリの Project Rules を上書きしてはいけない」 と明記している。 汎用キットは「弱い意見」を持つくらいでちょうどいい。

Examples を実装デモと誤解される

examples/ にサンプル Issue と処理例を置いているが、これは プロセスのデモであって実装デモではない。 読み手が「動くコードがある」と誤解すると、評価軸がズレる。READMEに何度も書き直した。

個人の運用に閉じやすい

dev-agent-team は今のところ完全に個人実験の域を出ていない。 複数人で使うと「Phase の解釈が人によって違う」「Stop Condition Check の厳しさが違う」といった、 チームで AI を使うときの新しいズレ が出てくるはずだ。ここは未検証の領域。

6. GitHub リンク

リポジトリはこちら。

fecot/dev-agent-team

試すときは以下の順がおすすめ。

  1. workflows/feature-development.md — IssueからPRまでの全体像
  2. commands/run-feature-workflow.md — 8 Phase の入口コマンド
  3. examples/sample-workflow-output.md — Phase ごとの Output サンプル
  4. docs/adoption-guide.md — 既存リポジトリへの導入手順

ライセンスは MIT。フォークして自分のチーム用に改造して使ってもらって構わない。 汎用キットは「自分の現場に合わせて調整する」前提で作っている。

7. まとめ

AI を使った開発で詰まったとき、答えは「もっと賢いモデル」でも「もっと長いプロンプト」でもないことが多い。

dev-agent-team は、これを Claude Code 上で実現するための個人的な答えだ。 完成品ではないし、この先も書き換え続ける。 ただ、「AI に開発を任せたいが、品質を担保したい」という同じ悩みを持っている人にとっては、出発点として使える型になっていると思う。

AI をチームとして扱う発想は、まだ業界全体としても初期段階にある。試行錯誤の途中経過として参考になれば。

相談について

もし「AIを開発にどう組み込むか」「チームとしてどう設計するか」で悩んでいる場合は、軽く相談も可能です。

→ https://fecot.net/