仕事ではバックエンドの API を開発していて、今は Claude Code を Agents として使っています。結論から書くと、Agents は私が書くソフトウェアの品質を上げましたが、効率のほうは言われているほど大きくは上がっていません。ボトルネックは Agents ではなく人、つまり私のレビューです。
開発の流れ
設計を詰めて機能概要にまとめる
追加したい機能について、まず Claude Code と議論します。grill-me skill を使って、こちらの考えを厳しく問い詰めてもらいます。Agents と私の考えが一致したところで、機能概要のドキュメントを書いてもらいます。
API と database の spec を書く
機能概要ができたら、API と database の spec を設計します。私はバックエンドの担当なので、実装に入る前にこれらを固めます。
spec をもとに issue を作る
spec ができたら、機能の大きさに応じて複数の issue に分割します。
unit of work 単位で実装する
issue を 1 つ選んで実装に入ります。1 つの issue に unit of work が複数あることもあります。実装は implement skill に任せますが、必ず unit of work 単位で進めてもらいます。各 unit of work は TDD の流れです。失敗する test case を先に書き、実際に失敗することを確認してから実装し、test が通るまで回します。
test が通ったら review skill を呼び、次の 3 点を見てもらいます。
- 実装が spec の要求を満たしているか
- test coverage。挙げておいた test patterns を網羅しているか
- code review
TDD、実装、テスト、レビューを unit of work ごとに回し、すべて終わったら最後に全体のレビューをします。
MR を作る
コードが書けたら create-mr skill を呼びます（MR は merge request です。私のプロジェクトでは GitLab を使っています）。用意してある merge request のテンプレートと issue の変更内容をもとに生成してもらいます。
人力でレビューする
MR ができたら、自分でレビューします。この人力レビューが一番時間がかかります。 実装は spec の要求をおおむね満たしていますが、細かいところは調整が必要です。よく出てくるのは次のような問題です。
- コード規約の遵守が甘い
- 頼んでいないことまでやる。A を頼んだのに B も一緒にやってしまう。B は要らないと伝えると、B を消した上で「B をやらない理由は……」という長いコメントを追加してくる。書かれるコメントは総じて冗長で、読み手を混乱させる
- code base の既存コードの質が悪いと、その悪いコードを学習してしまう。直すにはかなりの労力がいる
- テストケースが簡単すぎることがある。カバレッジが十分でなく、重要なテストが抜けていることもある。手で確認して、何が足りないかを指摘する必要がある
commit を整理して push する
人力レビューと Agents の修正を何度か往復して満足のいく状態になったら、最後に全 commit のレビューを Agents にもう一度させます。ここで問題が出れば直し、大きな問題がなければ完了です。
完了したら commit を整理し直します。途中には fix の commit がたくさん残っているので、最初から正しい commit だったように並べ替え、途中の修正の過程が見えない形にします。それを remote に push して、merge request の説明を更新します。ここで他のレビュアーに見てもらえる状態になります。
各段階で工夫したこと
issue 作成を自動化する
最初は issue の内容を Agents にローカルのファイルとして書かせて、それを自分で GitLab にコピーしていました。効率が悪く、しかも issue を作る時点で GitLab 上の既存の issue が見えません。
今は glab コマンドで GitLab 上に直接 issue を作らせています。作成が速くなっただけでなく、作る前に既存の issue を検索してくれるので、重複を避けたり関連する issue をリンクしたりできるようになりました。
issue の質を上げる
- issue template：bug、improvement、feature の 3 種類を用意しています。テンプレートに沿わせるだけで、欲しい内容がおおむね揃います
- create-issue skill：たとえば「実装方針は方向だけ書き、細部までは書かない」と決めています。issue に実装方針を細かく書きすぎると、Agents が後で実装するときにその細部に縛られます。しばらく経ってから coding するときには、書いておいた細部がすでに古くなっていることもあります
- 技術的になりすぎない：ソースコードの変数名やファイル名、具体的なコードを並べないようにしています。必要なこともありますが、issue を見る人の中にはコードに詳しくない人もいて、それでは内容が伝わりません。なるべく技術的でない言葉で書かせると、何が起きているのかが他の人にも伝わります
- out of scope：関連はするけれどこの issue の範囲には含めないものを明記します。Agents の実装を範囲内に留めやすくなります
worktree で並行開発する
並行して開発を進めるために worktree を作っています。同時に進めるタスクが互いに干渉しません。
ただし git の worktree コマンドで worktree を作るだけでは、本当の意味で並行にはなりません。開発しているのはバックエンドの API なので、worktree を作った後に server port と database port を変えてもらいます。こうすると worktree ごとに別の server と database が立ち上がります。
同じ port を使うと衝突して、後から起動する server が立ち上がりません。同じ DB に繋ぐと、テストのときに衝突します。
implement guide と test guide を置く
実装とテストで一番困っていたのが、既存の設計の良くないコードを Agents が学習してしまうことです。新しいアーキテクチャと新しいコードがすでにあっても、そちらを参照してくれるとは限りません。
そこで implement guide と test guide を用意しました。どういう構造にするか、どういう命名規約か、どういうテスト規約かを明記して、新しい規約に従ってもらうようにしています。
レビューの指摘を skill に還元する
レビューのとき、私はいつも同じことを言っています。この命名は読んでも分からない、コメントが冗長すぎる、コードが複雑すぎる、細かいところが意図と違う。Agents は同じ間違いを繰り返します。
同じ間違いを繰り返させないために、レビューの指摘と私が入れた修正から Agents 自身に学ばせることにしました。何をする、何をしない、こちらよりあちらを選ぶ、といった私の訂正をルールとして取り出し、私の具体的な場面だけでなく一般の場面にも当てはまる形に一般化してもらいます。まとめてもらったルールを私が確認して、既存の guide や skill を update します。
実装 → 私が訂正 → skill を update。 このループを回すと、Agents が学んだことが guide と skill に固定され、少しずつ望む形に近づいていきます。
感じたこと
品質は上がった
上がったのは主に設計の段階です。
- 議論していると、自分が考えていなかった点を指摘してくれる
- 自分が設計した API や database のテーブルについて、既存の設計と矛盾する点や問題のある点を指摘してくれる
- どう設計するのが良いか自分でも決めきれないとき、best practice や OSS コミュニティを参照した上で提案してもらえる
もらう提案は筋の良いものが多く、この議論の積み重ねから API Design guide と Database Design guide をまとめました。
設計の質が上がると、実装も欲しいものに近づきます。API spec と database の設計を書き切っておけば、実装はおおむね忠実です。
テストも Agents の恩恵が大きいところです。テストケースを速く書けるので、品質を担保しやすくなりました。Agents なしで手で書くと時間がかかり、出来も良いとは限りません。私が主に review するのは、用意されたデータが適切か、テストケースが網羅できているかです。テストの構造やテストケースの組み立て方を変えたいと思いついたときも、Agents がいると素早く形にできます。Agents がなければ、思いつかなかったか、思いついてもテストが書きにくくて見送っていたはずです。
効率のボトルネックは人
効率も上がってはいますが、よく言われる 5 倍や 10 倍のような上がり方はしていません。今のボトルネックは人、つまり私です。
- レビューに時間がかかります。設計を見て、コードは全行見て、実装もテストも見ます。テストケースは以前は細かく見ていました。今は Agents の書き方が良くなったので全行は見ませんが、各ケースがどうデータを用意して何を検証しているかは見ます
- 今の code base は古いプロジェクトで、以前の設計に問題があります。既存のアーキテクチャの上でどう少しずつ refactoring するかを Agents に指示する必要があります。コードが良くないことは Agents の効率にも響き、私のレビューの時間も伸びます
これから
human in the loop を減らす
プロセス全体で Agents に細かく指示するのを減らしたいです。最初から最後まで私の介入なしで回るループを作る。今すぐには簡単ではないと分かっていますが、この方向に進まないと効率は上がらないと思っています。人がレビューする速度は遅いからです。
古いコードの refactoring を早める
プロジェクトの古いコードを refactoring する速度を上げたいです。古いコードをできるだけ良いアーキテクチャ、良い設計に寄せる。これは human in the loop を減らすための土台にもなります。新旧 2 つのアーキテクチャが同居していると、Agents は既存コードを読んで混乱し、間違った実装をする確率が上がります。
他のモデルを試す
今はほとんど Claude Code だけで開発していて、他のモデルにはあまり触れていません。Codex や Kimi など、上位に挙がるモデルは一度試しておきたいです。他のモデルとそのツールを触ると、Claude Code だけでは気づけないことが見えるかもしれません。違いに触れるほど認識が広がり、Agents を使う力も上がるはずです。それに、Claude Code が落ちたときに他のモデルへ切り替えられます。