私は AI を使ってコードを書いていると思っていた。
実際は、ただタイピングが速くなっただけだった。
これがその違いであり——そしてすべてを変えた 7 つのエージェントシステムです。
これを保存しておけば、数ヶ月の時間を節約できます。
誰も語らない問題
生産的に感じられるが、実際はそうではないループ:
→ Claude に機能の構築を依頼 → コードを生成 → 何かが壊れる → エラーを貼り付けて戻す → パッチを当てる → また別の何かが壊れる → 再度依頼
1 日目: これは魔法のように感じられる。
30 日目: コードを書いていた頃よりも、AI の監督に多くの時間を費やしている。
同じロジックが 3 つの異なる場所に現れる。
Claude は 2 週間前に設定した規則を忘れている。
新しい機能が古い機能を壊す。
テストが欠けているか、浅い。
目が覚めて気づく: AI が失敗しているのではない。
あなたのワークフローが失敗しているのだ。
本当の問題は構造的なものです。
「この機能を構築して」と Claude Code に入力するとき、あなたは 1 つの AI セッションに次のことを求めています:
→ プロダクトアナリスト → アーキテクト → バックエンドエンジニア → フロントエンドエンジニア → テストエンジニア → コードレビュアー
すべてを同時に。
同じ乱雑な会話の中で。
計画における誤った仮定が、誤ったデータベースモデルになる。
誤ったデータベースモデルが、誤った API になる。
誤った API が、誤った UI になる。
気づいたときには、ミスはあらゆる場所に広がっている。
これがバイブコーディングと呼ばれるものです。
そして、これには明確な限界があります。
転換: バイブコーディングからソフトウェアファクトリーへ
実際にすべてを変えるもの:
実際のエンジニアリングチームは、1 つの大きな会話で仕事をしません。
それぞれ異なる人が異なる仕事を担当します:
→ ユーザーの問題を明確にする人 → アーキテクチャを考える人 → API を構築する人 → UI を構築する人 → エッジケースを考える人 → レビューする人
これらすべてを 1 つの AI セッションに詰め込むと、ミスが静かに積み重なります。
解決策は、作業を専門化されたエージェントに分割することです。
各エージェントは以下を得ます: → 1 つの集中したジョブ → それ自身のクリーンなコンテキストウィンドウ → 実際に必要なツールのみ → 触れてはいけないものに関する厳格なルール
結果: ソフトウェアファクトリーの完成です。
1 人の開発者 + 7 人の集中エージェント = 連携したチーム。
以下が、それを機能させる 7 つのエージェントです。
7 つのエージェント
エージェント 1: コードベースリサーチャー
開発者が AI に対して犯す最大の過ちは？
最初のアクションとしてコードを要求することです。
AI はプロンプトを受け入れ、ギャップを埋めるために推測し、生成を開始します。
その時点で、悪い設計が忍び込みます。
コードベースリサーチャーはこれを修正します。
その唯一の仕事: コードベースを調査し、1 行のコードも書かれる前に、物事がどのように機能するかを説明すること。
その役割: → 関連ファイルとその役割をマッピングする → 従うべき既存のパターンを文書化する → すでに構築された類似機能を見つける → リスクをフラグする（タイムゾーン、マルチテナント、リトライロジック） → どのテストを更新する必要があるかをリストアップする
できないこと: → ファイルを編集する（読み取り専用アクセスのみ） → 状態を変更するコマンドを実行する → 仮定をする — 代わりに質問する
ツール: Read、Grep、Glob のみ。
ルール: 構築する前に探索する、毎回必ず。
リサーチャーが最初に実行されます。常に。
エージェント 2: ストーリーライター
ほとんどの機能が失敗するのは、コードが間違っていたからではありません。
問題が明確に定義されていなかったからです。
ストーリーライターは、技術的な決定が行われる前に、大まかな機能アイデアを実際のユーザーストーリーに変換します。
入力として受け取るもの: → あなたの大まかな機能の説明 → リサーチャーの調査結果
生成するもの:
1 つのユーザーストーリー:「[役割] として、[行動] をしたい、その理由は [結果] のためである。」
受け入れ基準:テストが直接検証できる文。正常系パス。失敗系パス。ビジネスルール。
エッジケース:境界値、リトライ、マルチテナントに関する懸念事項。
対象外:明示的に構築しないもの。
未解決の質問:本当にわからないこと — 決して推測しない。
できないこと: → ビジネスルールを発明する → コードや技術設計を書く → 何かが明確でない場合に先に進む
ツール: Read のみ。
ルール: 他の何かが起こる前に、このストーリーを読んで承認する。
これが、以降のすべてを救う人間によるチェックポイントです。
エージェント 3: スペックライター
ストーリーが承認されると、スペックライターがそれを技術的な概要書に変換します。
これは、すべてのビルドエージェントが従う設計図です。
入力として受け取るもの: → 承認済みのユーザーストーリー → リサーチャーの調査結果 → プロジェクトの CLAUDE.md ルール
生成するもの:
→ データモデルの変更（フィールド、型、マイグレーション） → バックグラウンドフロー / プロセスフロー → API の変更（エンドポイント、リクエスト/レスポンスの形状） → フロントエンドの変更（コンポーネント、ページ、フック） → 必要なテスト（成功、失敗、エッジケース） → リスクと未解決の質問 → 変更されるすべてのファイル
できないこと: → ファイルを編集する → 新しいインフラを発明する — 代わりに明示的に指摘する → テナント分離やタイムゾーンの懸念をスキップする → 未回答の質問を残す
ツール: Read、Grep、Glob のみ。
ルール: この概要書は 2 番目の人間によるチェックポイントです。
1 つのファイルも触れられる前に、あなたが読んで承認します。
「メモリに ID を保存」と書いてあったら — それはあなたへの警告信号です。
今すぐキャッチしてください。10 個のファイルが変更された後ではありません。
エージェント 4: バックエンドビルダー
いよいよ構築が始まります。
バックエンドビルダーは、機能のバックエンド部分を実装します — そしてバックエンド部分のみです。
入力として受け取るもの: → 承認済みの技術概要書 → リサーチャーの調査結果 → プロジェクトの CLAUDE.md
構築するもの: → API ルート → サービスとビジネスロジック → データベースアクセスとマイグレーション → バックグラウンドジョブ → 作成するすべてのものに対する単体テスト
できないこと: → React コンポーネント、ページ、クライアントサイドフックに触れる（それはエージェント 5 の仕事） → 指示なしに新しい依存関係を発明する → 合意されたスコープ外のファイルを変更する → typecheck、lint、テストスイートを実行せずに停止する
完了後、サマリーを返します: → 追加または編集されたすべてのファイル → 再利用された既存のヘルパーやパターン → 役立ったであろう CLAUDE.md ルール
ツール: Read、Edit、Write、Bash — バックエンドフォルダのみにスコープ設定。
分離こそがポイントです。
バックエンドビルダーが誤ってフロントエンドを壊すことは決してありません。
エージェント 5: フロントエンドビルダー
フロントエンドビルダーは UI 部分を実装します — そして UI 部分のみです。
最初にバックエンドビルダーのサマリーを読みます。
これが重要です。
バックエンドが生成した API をそのまま利用します。
新しいエンドポイントを発明することはありません。
API の形状が UI にとって間違っている場合、パッチとしてではなく、不一致をフィードバックとして表面化します。
入力として受け取るもの: → 承認済みの技術概要書 → リサーチャーの調査結果 → バックエンドビルダーのサマリー（API コントラクト）
構築するもの: → React コンポーネントとページ → クライアントサイドフックと状態 → ローディング状態とエラー状態 → 作成するすべてのものに対するコンポーネントテストと単体テスト
できないこと: → サービス、API ルート、ワーカー、マイグレーションに触れる（それはエージェント 4 の仕事） → エンドポイントやレスポンスの形状を発明する → 指示なしに依存関係を追加する → typecheck、lint、テストスイートを実行せずに停止する
ツール: Read、Edit、Write、Bash — フロントエンドフォルダのみにスコープ設定。
2 人のビルダー。
2 つのクリーンなコンテキストウィンドウ。
一方が他方の作業を壊す可能性はゼロ。
エージェント 6: テスト検証者
両方のビルダーがそれぞれのコードに対して単体テストを書きました。
それだけでは十分ではありません。
テスト検証者はただ 1 つのことだけを行います: 機能が実際にユーザーストーリーで述べられたことを実行することを証明すること。
受け入れテストを書きます。
単体テストではありません。
受け入れテストです。
これらは機能を外部からテストします — 実際のユーザーがそれを体験する方法で。
入力として受け取るもの: → 承認済みのユーザーストーリー（すべての受け入れ基準を含む） → 承認済みの技術概要書 → 両方のビルダーのサマリー
生成するもの: → すべての受け入れ基準をカバーする 1 つの受け入れテストファイル → レポート: どの基準が合格したか、どの基準が失敗したか、どの基準をクリーンにカバーできないか
できないこと: → バックエンドコードまたはフロントエンドコードを変更する → テスト不可能な基準に対する回避策を発明する → 実際にはカバーされていない基準をカバー済みとマークする
テストが失敗した場合: 機能はストーリーを満たしていません。
どの基準が失敗したかを正確に報告します。
コードにパッチを当てることはしません。
それは適切なビルダーに戻されます。
ツール: Read、Edit、Write（テストファイルのみ）、Bash。
ルール: 受け入れテストに合格するまでは、機能は完成したとは言えません。
エージェント 7: 実装検証者
これが、他の誰もが見逃したすべてをキャッチするエージェントです。
検証者は、現在の実装を承認済みのストーリーと概要書と比較し、ギャップを報告します。
決して何かを修正しません。
ただ真実を伝えるだけです。
毎回実行するチェック:
→ ストーリーからの受け入れ基準がまだ実装されていないもの → テストカバレッジのない失敗系パス → セキュリティ問題: 認証チェックの欠落、テナント分離のギャップ、ログ内のシークレット、クライアントに公開された生のエラー → 合意されたスコープ外で変更されたファイル → CLAUDE.md または既存のコードと矛盾するパターン → 既存のヘルパーを再利用すべき重複ロジック → 概要書から静かにスキップされたタイムゾーンまたはマルチテナントの懸念事項
出力は常に重大度別にグループ化されます:
Critical — マージ前に修正必須 Important — マージ前に修正すべき Minor — 意見ベース、レビュアーの判断
各発見事項にはファイルパスと行番号が含まれます。
問題が何もなければ、そのように明確に述べます。
念入りに見せるために問題を発明することはありません。
ツール: Read、Grep、Glob のみ。
このエージェントこそが、ファクトリーが信頼できる理由です。
自己採点の答案用紙には価値がありません。
ディスク上にあるものだけを見る検証者 — それがどのように書かれたかではない — は正直です。
チェーンがどのように実行されるか
完全なフロー — 1 つのプロンプトですべてが始まります:
Claude Code を開いて、次のように入力します:
「7 日以上未払いの請求書に対する請求リマインダーを構築してください。」
あなたが他に何も入力しなくても、以下のことが起こります:
ステップ 1 → リサーチャーが請求書、支払い、メールのコードをマッピングします。関連ファイル、既存パターン、リスクを返します。
ステップ 2 → ストーリーライターがユーザーストーリーと受け入れ基準を生成します。
⏸ 一時停止: あなたがストーリーを読んで承認します。
ステップ 3 → スペックライターが承認されたストーリーを技術概要書に変換します。
⏸ 一時停止: あなたが概要書を読んで承認します。（「メモリに ID を保存」という間違いをここでキャッチします。）
ステップ 4 → バックエンドビルダーがサービス、API ルート、BullMQ ジョブ、単体テストを実装します。返すもの: 変更されたファイル、再利用されたパターン、すべてのテストがグリーン。
ステップ 5 → フロントエンドビルダーがバックエンドビルダーの API サマリーを読み、管理 UI タイルとリマインダーボタンを構築し、コンポーネントテストを書きます。すべてのテストがグリーン。
ステップ 6 → テスト検証者が 6 つすべての受け入れ基準に対する受け入れテストを書きます。レポート: 7 合格、1 不合格 — 手動トリガーがテナント所有権をチェックしていない。
ステップ 7 → 検証者がそれを見つけます。ファイルパスと行番号付きで Critical として報告します。
→ バックエンドビルダーにループバック。 修正が適用されます。8 つすべての受け入れテストに合格。検証者が再実行。クリーン。
⏸ 一時停止: あなたがレビューして PR を開きます。
3 つの人間によるチェックポイント。
他のすべては自動で実行されます。
基盤: エージェントが機能する前に、これが必要です
CLAUDE.md — すべてのセッションを生き残るメモリ:
Claude Code を開くたびに、ゼロメモリから始まります。
CLAUDE.md がこれを修正します。
これはリポジトリルートにある Markdown ファイルで、セッションごとに自動的に読み込まれます。
永続的なプロジェクト情報がここにあります:
→ スタック（Next.js App Router、Node.js、Prisma、BullMQ、Resend） → コマンド（npm run dev、npm test、npx prisma migrate dev） → アーキテクチャルール（「ビジネスロジックはサービスにあります。API ルートは薄く保ちます。」） → やってはいけないこと（「cron を追加しないでください — BullMQ を使用してください。生のペイロードをログに記録しないでください。」） → より詳細なドキュメントへのポインタ（docs/billing.md、docs/architecture.md）
100 〜 300 行に保ってください。
AI があなたを驚かせるようなミスを犯すたびに、自問してください: CLAUDE.md のルールでこれを防げたか？
ルールを追加してください。
数週間もすれば、CLAUDE.md は AI が間違えたすべての仮定の記録となり、セッションは著しく改善されます。
コンテキストドリフト — 静かな殺し屋:
ほとんどの Claude Code セッションは劇的に失敗するわけではありません。
ドリフトします。
誤った仮定がコンテキストに入ります。
モデルはその上に構築し続けます。
あなたは Claude にサブスクリプション管理の構築を依頼します。
それは設計します: User → Subscription。
あなたは思い出します: サブスクリプションはユーザーではなく会社に属している。
単に「いいえ、サブスクリプションは会社に属します」と言うと — Claude はパッチを当てます。
今、あなたは user.subscriptionId と company.subscriptionId の両方をあちこちに持つことになります。
ルール:
→ 小さなタイポ? インラインで修正せよ。 → 誤ったアーキテクチャ上の仮定? 会話を破棄し、正しい仮定を最初のプロンプトに組み込んで新しく始めよ。
正しいメンタルモデルを持つクリーンなセッションは、パッチを当てられたセッションに常に勝ります。
結果: 実際に変わること
ファクトリー以前:
→ バイブコーディングループ: プロンプト → 生成 → エラー → パッチ → 繰り返し → セッションコンテキストがノイズで満たされる → 誤った仮定が壊れた機能に積み重なる → 1 人のエンジニアは一度に 1 つのことしかできない → すべての機能は適切な人が利用可能になるのを待つ
ファクトリー以後:
→ 構造化チェーン: 調査 → ストーリー → 概要書 → 構築 → 検証 → 妥当性確認 → 各エージェントは必要なものだけを含むクリーンなコンテキストウィンドウを得る → 誤った仮定は 10 ファイル後ではなく、概要書承認時にキャッチされる → 1 人のエンジニアが完全な垂直スライスを出荷する: バックエンド、フロントエンド、テスト、妥当性確認 → チームの最高の知識はエージェントに生きる — 人の中に閉じ込められない
本当の変化:
決済のスペシャリストが決済統合エージェントを構築します。
今やチームの全エンジニアが、請求に触れる機能を出荷できます。
待つことなく。
引き継ぎなしで。
フロントエンドリードのコンポーネントパターンは、フロントエンドビルダーエージェントに生きています。
DevOps エンジニアの CI チェックはフックに生きています。
QA リードのエッジケースはテスト検証者ルールに生きています。
専門知識、エージェントとして共有。
可用性に閉じ込められない。
今週末にあなた自身のものを構築する方法
8 ステップのセットアップチェックリスト:
1. Claude Code をインストール → code.claude.com
2. フォルダ構造を作成: → .claude/agents/ → .claude/skills/feature-factory/ → .claude/skills/build-with-tests/ → .claude/hooks/
3. CLAUDE.md を書く（100 〜 300 行: スタック、コマンド、アーキテクチャルール、禁止リスト）
4. Claude Code の /agents コマンドを使用して 7 つのエージェントを作成。各エージェントの役割を説明。Claude がファイルを書く。あなたがレビューしてコミット。
5. feature-factory オーケストレータースキルを作成。これを書くよう Claude に依頼 — 7 つのエージェントファイルを読み、チェーンを配線する。
6. build-with-tests スキルを作成。チームの構築方法を記述: 既存パターンに一致させる、コードと一緒にテストを書く、最後に typecheck を実行する。
7. pre-commit フックを追加。.env、.key、.pem、secrets.json ファイルを含むコミットをブロック。所要時間 5 分。大惨事を防ぐ。
8. 1 つの実際の機能を完全なチェーンで実行。小さなものを選ぶ。どこでつまずくかを見る。ルールを追加。ファクトリーが自動調整される。
合計時間: 2 〜 3 時間。
その後、いくつかの機能を実行します。
3 〜 4 回後には、ファクトリーはあなたのコードベースを理解します。
監督に費やす時間は減ります。
次に何を構築するかを決定する時間が増えます。
7 つのエージェント — クイックリファレンス
→ リサーチャー — 何かを構築する前にコードをマッピング（Read のみ） → ストーリーライター — アイデアを受け入れ基準付きのユーザーストーリーに変換（Read のみ） → スペックライター — ストーリーを技術概要書に変換（Read のみ） → バックエンドビルダー — API、サービス、ジョブ、単体テストを構築（バックエンドフォルダのみ） → フロントエンドビルダー — コンポーネント、ページ、フック、UI テストを構築（フロントエンドフォルダのみ） → テスト検証者 — ユーザーストーリーに対する受け入れテストを書く（テストファイルのみ） → 検証者 — 実装をストーリーと概要書と比較、ギャップを報告（Read のみ）
3 つの人間によるチェックポイント: → ストーリーを承認 → 概要書を承認 → PR を承認
他のすべては自動で実行されます。
Claude Code を使用しているほとんどの開発者は、まだバイブコーディングをしています。
プロンプト → 生成 → パッチ → 願望。
それは間違っていません。
ただの限界です。
ファクトリーはあなたをプロセスから排除するものではありません。
それはあなたを必要としない部分からあなたを排除します。
あなたの判断が重要となるループにあなたは留まります:
これは正しい問題か？ これは正しい設計か？ これは安全に出荷できるか？
エージェントはその間のすべてを処理します。
それが、AI をより速いキーボードとして使うことと—
AI を連携したチームとして使うことの違いです。
これが役に立ったなら:
→ リポストしてネットワークと共有 → @sairahul1 をフォローして、このような解説をもっと見る → ブックマーク — 7 つのエージェントを参照したくなるでしょう
私は AI、プロダクト構築、そしてあなたが寝ている間に機能するシステムについて書いています。
