みんなAI Agentで開発どうしてる？僕はこうしてる！！

AI Agentを使った開発で一定の流れがあるなと感じたので備忘録がてらまとめます。

前提

新規構築の話で、1人での開発が前提になります。

ある程度年数が経過したサービスやチーム開発でも方向性は同じですが、やり方が全く違います。
そちらでは変更が小さいこと、他の人と競合しないこと、ユーザーへの影響がないことが重視されます。そこをうまく高速にやる方法はまだ見えていないです。

1. プロジェクトの立ち上げ

まずAGENTS.mdを書きます。

AGENTS.md

# AGENTS

NOTE: DO NOT ASK USER

## Core Concept

[何を、どんな思いで作るのか書く]

# Tech Stack

- [使いたい言語やフレームワークを書く]

長さによってはMotivationだったり、細かいセクションを入れたりもしますが、基本的に何を作りたいのかを書きます。

この状態でPlease continue developing the core conceptというプロンプトで25〜150回ほど繰り返し実行をします。
規模感にもよりますが小規模プロジェクトなら25回ぐらい、中規模なら100回ぐらいを目安に考えてます。気分次第では無制限に回して、翌日に確認して育っていたら止めることもあります。

このループの回し方は数が少なければシェルスクリプトのループなどで十分です。
数が多いときは考えることがいくつかあり、詳しくは下記を参照してください。

https://zenn.dev/kinzal/articles/6e789454354cfc

2. 実際に動かして機能を追加する

立ち上げが完了したら実際に動かしてみましょう。
動かしてみると色々足りないところ、もっとこうしたいみたいなことが言語化されるのでひたすら追加、確認を繰り返します。

言語化の度合い次第ではAGENTS.mdを書き換えてさらに回数を重ねたり、TODO.mdに大量にやりたいことを書いて回数を重ねるなどもあります。

このあたりは小さな追加であれば直接、具体的に何をしたいかを書けるならTODO.md、抽象的にしか言語化できないならAGENTS.mdみたいな使い分けのような気がします。

注意点としてUI/UXはこのタイミングでは一切触らないです。
エラーが出て動かないなどあれば直しますが、そうでもなければまず触りません。
UI/UXは事前準備が全てであり、準備していない段階で詰めても無駄になることが多いので機能を一通り作ってから詰めることが多いです。

3. 概念を整理し、機能を削除する

一通り機能を追加できたらAIさんと会話しながらコアコンセプトに関係する概念を整理します。

私がよくやるやり方としては

1. プロジェクト構造を見る
2. ファイル名やディレクトリ名のワードについて質問する
3. 会話しながら何でその命名なの？別のじゃダメなの？それ造語？一般概念？みたいにひたすら質問する
4. 脳内に概念モデルができる

という形でひたすら会話することが多いです（というか、この会話をしてるときが一番楽しい）。
レポートを作ってもらうこともありますが、だいたいプロジェクト構造見ればわかるのでそっちから行くことが多いです。

概念モデルができたらAGENTS.mdにそれを記載します。
最近書いたのだと下記のような感じでレイヤーや概念をざっと書きます。

AGENTS.md

iter is a CLI tool. The engine lives in Core; the surface syntax lives in a separate Language.

    CLI ──── Core ──── Language

Core is built from three concepts:

- **Runner** — the unit of exploration. A Runner binds a **Workspace** (where and how the agent runs) with an **Agent** (which AI agent runs, and how it is invoked), and iterates over them. Exploration breadth is controlled at this layer: what a Workspace lets the agent see, and what an Agent carries between turns.

- **Signal / Queue** — the boundary through which external information enters a Runner. A **Signal** is the unit that crosses the boundary; a **Queue** is the channel that carries it. Each turn of a Runner consumes one Signal.

- **Trigger** — a source of Signals. A Trigger watches something outside the Runner — a schedule, a file change, a webhook — and turns it into Signals on a Queue.

A Runner alone holds exploration inside its own radius. When that radius is too narrow, Triggers bring in what the Runner cannot reach from within, widening the circle through Signals on its Queue.

これができたら概念に合わせる形に修正、不要なものを全て削除していきます。

ここではまず、この機能を削除して、概念とズレているのでここをこう直してのように直接言及することが多いです。
ある程度落とせたら概念とズレているので直してのような形で「完全に一致してます」と回答が来るまで繰り返すことが多いです。

このあたり、AI Agentは現在のワークスペースが正しいというバイアスが強く、削除すべき機能が残ったり、名前が変わるだけで概念として整理されないことが多いので初めは細かく言及し、ある程度整ったら雑に方向性だけ示すみたいなやり方をしています。

4. 品質を上げる

概念を整理しコアコンセプトを凝縮させたら次は品質を上げて使える状態に引き上げます。

4.1. Agent設定でファイルの読み書きを制御する

例えばAGENTS.mdは書き込み禁止する、.claude以下は読み込みすら禁止するなど設定を変更します。

また、この後に紹介する品質を上げるためのツールの設定群はAI Agentによる変更を禁止します。
これはツールで縛っても設定で緩和するなどして回避する行動が発生するので、ここは必ず縛ります。

4.2. リンターを入れる

リンターで雑に品質を上げるというのもありますが、どちらかというとカスタムルールを作るのが目的です。
コードを見て気に食わないコードがあればとりあえずルールを追加します。

• Service/Utility/Helperみたいな名前は禁止する
• privateメソッドを禁止する
• コメントでの警告抑制を禁止する

など、気に入らないコードは一度ルール化し、経過観察しながら調整していきます。

4.3. レイヤーの依存制御を入れる

だいたいこの時点でレイヤー間の関係性が狂っているので、まず整理を行い、依存関係を制御するツールを入れます。

元々はレイヤー制御がなくても、適切にレイヤーを切れば問題ないというスタンスでした。
が、気がついたら相互参照になって修正が完了できなかったり、レイヤーが明示されないことによってあっちこっちに同じようなコードが生まれたりするので、レイヤーの依存制御は早めに入れるようになりました。

4.4. ユニットテストでカバレッジ100％にする

とりあえずユニットテストのカバレッジを100％にします。
これはカバレッジというよりテスタブルな設計にするのが目的です。

ユニットテストのカバレッジを100％にしてください。
これはカバレッジを100％にするのが目的ではなく、このタスクを通じてテスタブルな設計にすることが目的です。この目的を踏まえてカバレッジを100％にしてください。

というようなプロンプトで行うことが多いです。

これは趣味ですがモックを使わないようにリンターで設定することもあります。
その際にはIOが走るところはFakeやTestcontainersを使うように指示を出すこともあります。

4.4.1 Fakeを作成する

DBアクセスなどはオンメモリのFakeを作ります。
外部APIなどで気軽に呼べないものがあればオンメモリのFakeを作ります。

DDDだとわかりやすくRepositoryのオンメモリのものを作る形ですね。
外部APIなどでFakeを作る場合はOpenAPI Schemaなどを基にオンメモリで読み書きできるものを作ります。

可能なら本物とFakeの入出力を比較するDifference Testを入れるのが望ましいですが、この辺は可能かどうかで変わります。

Fakeができたらテストでは基本的にこれを使う形になります。

注意点としてFakeをどう検証可能に作るかが重要になります。
そこを無視してFakeを作ってくれとAI Agentに指示を出すとそれっぽく動くゴミが生まれ、後で問題が顕在化します。早い段階で潰しておくのが安牌です。

4.4.2 Mutation Testを追加する

テストの分量次第ではMutation Testを入れます。
カバレッジ100％ならそれでいいのではと思われるかもしれませんがAIを舐めてはいけません。

あいつらassert(true)のテストとか普通に書いてくるんだ・・・。
そこまでいかないにしてもカバレッジ100％のために酷いテストを本当に書いてくるので、少しでもマシにするためにMutation Testは悪くないです。

ただし、2026/05時点のモデルでもMutation Testは難しいです。
MSI 95％など高い基準を達成させようとするといつまで経っても修正が終わらないなど普通に起こりえます。
また、高い基準を達成するために過剰なホワイトボックステストになることも多く、未だに良い塩梅の設定は見つけきれていないです。

4.5. Fuzzingを入れる

ツールやライブラリ系の場合はFuzzingを入れることが多いです。
用途的にはPBTでも耐えきれるはずなのですが、私がライブラリやツールを作ることが多いので検証したい境界が外にありFuzzingを選ぶケースが多いです。

FuzzingもFakeと同じでそれっぽいものが作られやすいです。
作るときはコードを読みながら生成器の生成可能な範囲の広さをひたすら詰めたり、生成器のアルゴリズムを詰めるのが本当に重要になります。

多分、想像の10倍ぐらい苦労するのですが、それでもやる価値は大きいと思います。

4.6. Design Systemを入れる

UIがあるもの限定ですが、UIを詰める場合は必ずDesign Systemを作り、トークン、コンポーネントの作り込みを行います。
またこのときに合わせてコンポーネントカタログやVRTまで入れて、不意のUI崩れを防ぐようにしておきます。

このあたりWebならCSSフレームワーク＋Storybookなどで簡単にできるのですが、デスクトップアプリケーションはどうするべきか未だに答えが見えないです。
特にデスクトップアプリケーションだと設定値と実際の描画された値がズレることもあり、かつAI Agentの画像認識ではpx差異を読み取れないのでいつまで経っても修正できないなど起こり得ます。

あまりにも辛すぎて自作のComputer Useを作り、そこにPixelSnapライクな計測アプリを作るぐらいにはデスクトップアプリケーションは難しいです。

4.7. Integration/E2Eテストを入れる

ここまでの対応を行うと必要な部品が揃うのでIntegration/E2Eテストを作りやすいです。

私の場合は実際に本物のDBやAPIを準備するのが面倒なので、オンメモリ実装を使った最外層のテストをよく行います。
オンメモリ実装を使えばIntegration、代替する必要がなければE2Eみたいな位置付けですね。

言語や作ったものによってはexamplesを作って、実際に使う例で代替することもあります。

5. 気合いで品質を上げる

4までの対応である程度は品質を確保できますが、実際のところ全然足りないです。

お遊びのおもちゃならここまでで終えます。
そうではなく、OSSとして公開したり、他者に使ってもらう場合はさらに詰めます。

5.1. コードを全部読んで気合いで修正する

AIが1日で作って、2週間かけてリファクタリングするとかよくあります。
特にクラスや関数の名前をひたすら詰めて、その名前に合った振る舞い以外をさせないようにひたすらリファクタリングします。
また、4のツールでの品質を上げるためにそもそも設計が悪く、効果的ではないということもあり、より良くするために調査してリファクタリングもします。

ルールやスキルを書けばいいのではと思われるかもしれませんが、私にとってここは言語化できない領域であり、機械的に検知もできないので困っている領域ですね。

これをやると理解も上がるし、所有感も出るし、予後もいいのであまりに馬鹿にできないです。ただ時間と集中力を持っていかれるので大変ですけどね。

5.2. 品質を上げる手法の探索を繰り返す

品質が悪い感触はあるが言語化できないときは回数を増やして探索をします。

• Please improve the quality of the system design
• Please strengthen the guidelines to improve system quality
• The current design is incorrect. Please refactor it into a more sophisticated form.

こういったプロンプトでおおよそ50回ほど回すと、それなりに面白い取り組みが出るのでそれを取り込みます。
どういったプロンプトにするかは変化の幅次第で、より良くといったニュアンスであれば狭く、現在の否定であれば大きく変わります。

この手法は面白いもので、何度探索を行っても必ず修正されるコードがあったりします。
そういうのを見つけ、AIとディスカッションして修正することで、知見を得られるので学習という面でも役に立ちます。

5.3. リポジトリ外部に監査エージェントを作る

これはあまりやりたくない手法ですが、開発しているリポジトリとは別に監査用のリポジトリを作ります。

この監査リポジトリでは開発リポジトリで公開した成果物に対して、この成果物の仕様は何かというのを探索してもらいます。
このとき根拠は重要視しており、シナリオテストだったり形式手法でのモデリングを行ってもらい、それを基準に仕様を記述してもらい、矛盾等を洗い出してもらいます。

開発リポジトリと同様にAGENTS.mdに何を目指すのかを記載して、数百回の実行を行います。
数百と言いましたが開発リポジトリは常に進むので、常時動かしてもいいぐらいです。

と言うのは簡単ですが結構これも暴れ馬で、例えば1ファイルに数千行の仕様ファイルだったり、1ディレクトリに数百のテストファイルが作られたりなど酷い状況によくなります。本当によくなります。
これに関しては都度停止して方向性を修正するぐらいしか解決策はないです。

このあたりはまだ詰めきれてないので、どういった手法で構築すると良いのかが見えていないです。
ただ直感的には根拠に基づいた形式仕様記述だとは思っており、そういう方面の研究をしたいとは常々思っています。

6. ドッグフーディング

品質を上げ切って動作するようになったらドッグフーディングです。
実際に触ってみるとここまでやってもまだ問題が起きるか・・・とビックリすると思います。

このときすぐに修正をするのではなく

1. 問題の原因を調査する
2. 各種品質系でなぜ捕捉できなかったのかを調査する
3. 品質系でのチェックを追加可能であれば追加する
4. 問題を修正する

という手順を実行するのが望ましいです。
余力があればポストモーテムを開催しても良いかもしれません。
稀にそんな良い方法が！みたいな提案が出ることもあるので、余力があればやった方がいいです。

7. 新しい機能を追加する

ドッグフーディングで欲しい機能が言語化できたら機能追加をしましょう。
もし、何か足りない、何か新しい機能が欲しいけど何も思いつかないなどがあれば、探索をしましょう。

• Please continue developing the core concept
• Please add a new feature
• Please improve the usability

おおよそ50回ほど実行するとそれなりに面白い機能が生まれることが多いです。
機能自体は微妙でも良い発想があることも多く、それを基にAI Agentとディスカッションして機能を追加することもあります。

こうしていろいろ機能を追加したら3に戻って概念整理を行い、品質の見直しを行って、改めて機能追加をするというようなループに入ります。

8. その他

その他で最近やっていることとして、まずOTelサポートはよくやります。
これはアプリケーションが期待どおりに動作しないときに調査をしやすくするためで、OTel+Logをローカルネットワーク内にあるサーバーに突っ込んでいることが多いです。
特に問題に遭遇したが再現しないときなどに重宝します。

次にAI Agentのセッションログからレポート生成→日次レポート→週次レポート→月次レポートの生成をやっています。
このとき合わせてセッションログのバックアップもしているので、何でこうなっているんだっけ？ということを確認しやすいです。
個人的には作成したSkillsの検証や、Ruleの生成、ADRの生成などいろいろ発展させられそうと思いつつ、まだそこまでうまく活用はできていないです。

また、セッションログのバックアップ先としてClickHouseを入れました。
活用はこれからですが、1セッションの変更範囲から設計の良くないところを抽出したり、どう言うところで認識ズレが起きるのかの言語化などをできないかなと思っています。

このあたり、AI Agentの外側にAIをよりよく動かすための気づきの元を作り始めたみたいなところがあります。

なぜ1つのプロンプトで繰り返し実行をするのか

ここまで読んで、探索するという名目でなぜ繰り返し実行を多用するのか気になる方も多いと思います。

この答えとしては「何をすべきかわからないからAI Agentに走ってもらう」というところになります。
何をどうするか決まっていればそれは指示ができます。
しかし知らなかったり、答えを言語化できないときにはとりあえず走ってもらい、その結果が肯定/否定どちらでも言語化を一歩進めることができます。

このあたりは不確実性に対して探索を行い、気づきを得て、調査をするという、エンジニアの中でよく言われている手法を実践しているだけですね。

また、厳密なゴールを定義できないとき、AI Agentは1回の実行ではタスクを完遂できません。
どうしても欠けた対応になるため、それを繰り返し実行でフォローして完遂させます。

AI Agentによってできるようになったこと

言ってしまえば、ここまでやっていることはある意味これまでのエンジニアリングと大差ないです。

ただ、圧倒的にやりやすくなったこととして

• Fake実装
• Fuzzing
• E2E

といった、あると便利だけど作成・保守コストが高すぎてやりにくかったものが、やりやすくなりました。
特にパターンが膨大なケースで自作するにはモチベーションが湧かないみたいなものでも、とりあえずAI Agentに投げて作り始めることができるのはいいですね。

今抱えている課題

シナリオテストや仕様のドキュメントなどを作っていると、それ自体の正しさをどう定義するのかという課題が生まれます。
特に多層での保証をしているとどうしても層間の矛盾が生まれがちです。

また、AI Agent自身がそれらを変更可能だと、気がついたら壊れていたり、想定していない形に変わっていたりする瞬間があります。

こうなることはもうある程度許容しないといけないのだろうなとは思いますが、バグとして認識する前にズレていることに気づける状態にしたいです。

このあたり形式仕様記述なども調べていますが、どうしても部分的な保証になってしまい、欲しい解決策とは少しズレるところがあります。

次に、これは少し特殊ですが、AI Agentで開発しているとこういうものが必要になる→作ろうでどんどん作りたいものから遠ざかることが多いです。
Fuzzをやるための生成器だったり、その言語にないテスト系ライブラリだったり、AI Agentを探索させるためのフレームワークだったり、独自のComputer Useだったりですね。

こういうのは本題ではないので関心が強いわけではないのに、どうかすると本題より品質が求められるので気がついたらそちらばかり作っているとかあるあるです。

自律進化、自己適応するアプリケーションを作る仕組みがそろそろ欲しいです。

おわりに

2025/11から何だかんだで数十のアプリケーション、ツール、ライブラリを作って、同じようなことを繰り返しているなと思ったので改めてまとめてみました。

こうして俯瞰してみるとAgent機能は全くと言っていいほど使っていませんね。
実際使っている機能はというと

• AGENTS.md
• ファイルの読み書き設定
• Plan
• /loop、/goalなどの一部のコマンド（記事では言及してないけど、他のAgentを使ったレビューとかでよく使っています）
• 自作ツール、ローカル環境向けSkills

ぐらいですね。
多分いろいろ便利な機能は多いのでしょうが、メイン2つ、サブで4つぐらいAI Agentを使ったり、いろんなプロジェクトを作ったりしていると、作り込むのが手間で結局こんな形になってしまってます。

皆さんはAI Agentでどう開発していますか？僕はこんな感じでした。