ハクソク

世界を動かす技術を、日本語で。

エージェント工学パターン

概要

  • Claude CodeOpenAI Codexなどのコーディングエージェントを活用する際の最適な利用パターンを解説
  • 効率的なプロンプト設計やフィードバック方法のポイントを紹介
  • コーディングエージェントから高品質な出力を得るための工夫
  • エージェントの限界や注意点にも言及
  • 実践的なテクニックのまとめ

コーディングエージェント活用パターン

  • ゴールの明確化

    • 目的や期待する出力例の簡潔な提示
    • コードの用途や制約条件の明記
  • 具体的なプロンプト設計

    • 必要な入力・出力フォーマットの指定
    • 言語やフレームワーク、バージョンの明示
    • 関数名や変数名など、命名規則の共有
  • 段階的な指示出し

    • 複雑な処理は小さなタスクに分割
    • ステップごとに確認・修正を繰り返す方法
  • 例示とサンプルの活用

    • 期待するコード例やテストケースの提示
    • 入力値と期待される出力例の併記
  • フィードバックの具体化

    • 間違いや改善点は明確に指摘
    • どの部分を修正すべきか具体的に伝達
  • 反復的なやりとり

    • 一度の出力で満足しない姿勢
    • 少しずつ要件を追加・調整しながら精度向上
  • エージェントの限界理解

    • 長大なコードや特殊なAPI利用時の注意
    • セキュリティや最適化の最終確認は人間によるレビュー必須

より良い結果を得るための実践テクニック

  • 自然言語とコードの併用指示

    • 英語・日本語問わず、コメントや説明文の活用
    • コード例とその説明を交互に提示
  • エラーやバグ発生時の対応

    • エラーメッセージや実行環境情報の共有
    • 修正後の再テスト指示
  • ドキュメント生成やリファクタリング依頼

    • コードの説明やコメント追加の依頼
    • 可読性や保守性向上のためのリファクタリング指示
  • 複数案の提案要求

    • 別アプローチや異なるアルゴリズムの提案依頼
    • 比較検討の材料として活用
  • 最終レビューと検証

    • 出力コードの動作確認
    • セキュリティやパフォーマンスの二次チェック

コーディングエージェント利用時の注意点

  • 著作権やライセンスの確認

    • 出力コードの利用規約やライセンス遵守
  • 個人情報や機密情報の入力回避

    • セキュリティリスクの低減
  • バージョンアップやAPI変更への追従

    • 最新環境への対応状況確認
  • 過信せず、最終判断は人間が行う姿勢

    • エージェントは補助ツールという認識

Hackerたちの意見

StrongDMのダークファクトリーの原則は、すぐに実行可能だと思うよ(ごめんね、サイモン!): https://factory.strongdm.ai/principles
それに賛成!時には問題に対してトークン燃料を投げる価値があるし、進めながら検証していくのもアリだよね。
何も謝ることはないと思うよ。彼は数週間前にそれについて書いてたしね。 https://simonwillison.net/2026/Feb/7/software-factory/
最近、エージェント的なコーディング/エンジニアリングをたくさん試してみたんだけど、簡単にテストできるソフトウェアがこのエージェントループにぴったりだと気づいた。実験の一つでは「Linuxバイナリをより良い圧縮でダウンロードしやすくする」というシンプルな目標を持ってたんだ。[1] 圧縮はこれに最適。簡単に検証できる(バイナリ -> 圧縮 -> 解凍 -> バイナリ)から、各イテレーションで何かしらの進展がないと、その試みは捨てられるべきだよ。私が学んだことは以下の通り:- マイクロマネジメントはしないこと。AIはアイデアを出すのが得意だから、あまり干渉しなくていい - テストハーネスが全て。検証する方法がないと、ループが迷走する - イテレーションを実験させる。AIにアイデアを探求させたり、実験で壊させたりするのが大事。イテレーションが長くなるかもしれないけど、その実験は次のイテレーションにとって価値がある - セッションの合間にいくつかの.mdファイルをメモ代わりに残しておくと、各イテレーションが前の実験や試みから学べるよ。[1] https://github.com/mohsen1/fesh
本当に良いテストが必要だよ。変な方法でバグるからね(経験豊富なプログラマーはコーディング中に脳内でループを回してると思う)。いいニュースは、エージェントは新しいテストを追加したりバグを見つけたりするのが得意だってこと。そういうのをやろう。ユニットテストやプレイライトもやってみて。ウェブドライビングで全てをテストするのはエージェント以前は狂気の沙汰だったけど、今は十分可能だよ。
テストハーネスのポイントは、私にとっても本当に印象に残っている。ブラウザの自動化作業にエージェントループを使っていて、そのドメインには自然なバリデーションシグナルがある。つまり、ブラウザセッションが実際のユーザーのように振る舞うか、そうでないか。そういう二元的なフィードバックがループをきれいに閉じる。私たちの場合、"正しく振る舞う"には2つのレイヤーがあって、機能的(正しくナビゲートできたか?)と行動的(検出システムにとって人間に見えるか?)。エージェントは最初のレイヤーには問題ないけど、2つ目には直感がない。行動的バリデーションをループに組み込むことが、実際に役立つものにした。セッション間の.mdのスクラッチパッドは過小評価されている。私たちはそれを短い決定ログに形式化した。何が起こったかの要約ではなく、明白でない選択とその理由だけ。次のセッションにおいて「私たちはXを試した」と「私たちはXを試したが、Yのせいで失敗したのでZを使う」というのは大きな違いだ。
「テストハーネスが全てだよ。作業を検証する方法がなければ、ループは迷走する」これがAIコーディングエージェントを使う上で最も重要なポイントだね。彼らは本当に魔法のような機械で、多くの開発や一般的なコンピューティング、データ収集のタスクを簡単にこなせるけど、決定論的で実行可能なチェックやテストがなければ、ループの一回目から次の回にかけて何も保証できないよ。
私は主にAIをワークフローで簡単なボイラープレートや問題解決、ドキュメントのために使ってる。エージェント的な作業にも時々手を出してるけど、あまり印象的な結果は出てない(まあ、機能する出力があるだけでもすごいけど、文句を言いたくなるようなコードではない)。同じことを言う人が多いけど、尊敬する人たちの中にはもうほとんどコードを書かないって言ってる人もいる。これをうまく整理するのはちょっと難しい時もあるね。とにかく、この本が進化する中で、いくつかのパターンを試すのが楽しみ。どうやって他の人がこれらのツールを使っているのかを理解するのは、私にとって大きなギャップだよ。
最後に試したのはいつ?エージェントに大きなタスクをやらせるのは、去年の終わりまでずっと当たり外れがあったと思う。ここ数ヶ月で彼らがかなり良くなったのを感じてる(私だけじゃないけど)。コーディングアシスタントが得意なことの私の経験は、スマートオートコンプリートから、ターゲットを絞った変更/追加、そしてフルエンジニアリングへと変わったよ。
私もあなたと同じような状況だったけど、DHHがエージェントの使い方を変えたって投稿を見てから変わった。彼がLex Fridmanとのトークで話していたアプローチは私のと似ていて、ハイプの中で一つの常識の核のように感じた。だから、彼がアプローチを変えたと言ったとき、もう一度見直してみた。今は毎日エージェント(Claude code)を使ってるし、毎日コードも書いてるよ。(この立場を強化するために、OpenCodeのDax Raadも同じことを言ってる)。モデルがプロダクションのコードベースを持つことができるとは思えないし、エンジニアは責任を持つために十分なスキルを維持する必要があると思ってる。エージェントは多くのことに役立つけど、通常は先行事例がたくさんあるパターン化されたコードに限る。CCはポーラーズコードを書くのが一貫して苦手だと思う。正直、エージェントを使うのは全然楽しくないし、誰もがこれがどうなるかを本当に知っているとは思えない。でも、自分でツールを使うことで、ハイプの中で現実感が強くなった気がする。
私の経験では、単一のエージェントからの最初のイテレーションの出力は、私が責任を持ちたくないものだよ。「もうコードを書かない」というのとつながるのは、出力を改善するためのイテレーティブなプロセスだね:1) エージェント間でレビューのループを持つ(別の「レビュアー」エージェントを生成する)ことと、明確なテスト/評価基準が、結果をかなり改善してくれた。2) 手動でレビューして改善の指示を出すことが、私が責任を持てるコードを得るためには必要だよ。
> これをうまく調整するのはちょっと難しい時もあるよね。私の経験では、これはタスクによって大きく変わるし、良いフィットと悪いフィットの間には大きな溝がある。人によっては、その溝の片側だけで作業して、もう片側に戸惑うこともあると思う。
あんまり言われないことだけど、手でコードを書く方が、AIを使うよりも早いことが多い(少なくとも私には)。AIのためにプランを作って、実行を待って、確認して、再度プロンプトを出す…なんてやってると、頭の中にプランがあって(メモも少しあれば)、自分でやる方が早いことがある。ゼロから何かを作ったり、高度なリファクタリングをするのはAIを使った方がほぼいつも早いけど、私の日常的なタスクの大半はバグ修正や機能追加で、10%がコーディング、90%がどうやってやるかを知っていることなんだ。
> 時々エージェント的な作業に手を出してみるけど、出力にはあまり感心してない(まあ、機能する出力があるだけでもすごいけど、文句を言う責任を持ちたくないコードだしね)。 > 同じことを言ってる人がたくさんいるけど、尊敬する人たちの中には、ほとんどコードを書かなくなったって言ってる人もいる。これをうまく整理するのはちょっと難しい感じがする。整理はうまくいくよ。ブログやコメントを読んで「これ、絶対AIが生成したな」って思ったことある?それがわかるなら、自分のブログやサイト用に、自分がレビューしたブログを受け入れる?俺は無理だな。「うわ、気持ち悪い」って思って書き直す。良いAI体験を持ってる開発者は、AI生成コードを読んでも同じ「うわ、気持ち悪い」って感じはしない。悪いAI体験を持ってる開発者は、AIコードをレビューするたびに「うわ、気持ち悪い」って感じて、そのコードを受け入れないことにする。まあ、これは俺の理論だけどね。
昨日、まさにこれについての投稿を書いたんだ。ソフトウェア開発、つまり手動でコードを作る行為は衰退している。新しい分野が生まれつつある。これは本当のエンジニアリングに近い。橋の建設を監督するエンジニアのように、仕事はレンガを積むことじゃない。構造が崩れないようにすることだ。コードの限界コストが崩壊している。この一つの事実がすべてを変える。
> これは本当のエンジニアリングに近い。 ソフトウェアエンジニアリングを機械、化学、電気工学と同じ文脈で「本物」とは言えないと思う。コードのコストが崩壊しているのは、ウェブ開発が広く厳密ではなく、堅牢なソフトウェアが優先事項ではなかったからで、みんなそれを知っている。AIがまだ十分ではないと文句を言っている人たちは、今の職業にいる多くの人たちも同じだということを理解していない。
私たちは技術的負債の上に全てのウェブを構築していて、LLMもそれに基づいて訓練されている。何が悪くなる可能性があるのか?
正式な工学の分野は、建設と設計の区別ではなく、通過した規制のゲートや社会の利益のために背負っている倫理的負担によって定義される。
> かなり重い言葉だね。みんながその投稿をフラグ付けした理由がわかるよね?痛いほど非人間的だよ。私はLLMを活用することには賛成だけど、サイモンの投稿を読むことを強く勧めるよ。彼は明らかにAIを多用してるけど、彼のブログ投稿はそんなに無機質じゃないし、それが彼が新しいHNブログの人気者になった理由だと思う。 [0]: 私は個人的にサイモンが自分の声で書いていると思うけど、誰が知ってる?
これ、すごく変な見解だね。君の言葉は、過去の暗号通貨のハイプサイクルを思い出させる。人々がWeb3.0やNFTのFOMOヒステリーを推してた時期だ。エンジニアリングは、問題を解決するための科学と数学の実践的な応用だよ。君が説明してるのは、もしかしたら建設管理のことを言ってるんじゃない?ここに価値があることは否定しないけど、君の主張は現実から離れてるように思える。非自明なアクチュアリーのモデルをバイブコーディングして、それがレビューの長いリストを通過して、大手企業が実際にそれを採用するのは大変だよ。
同意する。これは「ループの中」にいる状態から「ループの上」にいる状態への移行だね。
これを読むのは気持ちよくないね。ここでの主張は深いけど、関数レベルでのコードベースの理解はもう必要ないって言ってるのは、そんなに深いことじゃないよ。前にも「エージェント的なものが未来だ」とか言って、もうコードを知らなくてもいいっていう同じようなブログを読んだことがあるけど、それも深いとは思わなかったし、みんなが繰り返すのはもっとバカみたい。もしかしたら、書かなくて済む時間を全部、読まないことに使ってるのかもね。
それはお前が書いたもんじゃないし、そう信じるべきじゃないよ。
今日は学部のデータ構造の学生たちに、1970年代後半からのCPUとGPUアーキテクチャの進化について講義をした。主なテーマは以下の通り: - 20世紀の最後の20年間、ムーアの法則が維持され、次の年のチップにはより多くのトランジスタが詰め込まれ、どんどん速いクロックスピードで動くことができた。ソフトウェアはハードウェアの性能向上に乗っかっていたから、速いコードを書くことがいつも価値があるわけじゃなかった。 - 電力消費はトランジスタの密度には依存せず、クロック周波数の3乗に依存するので、2000年代初頭にはインテルが壁にぶつかり、通常の熱放散方法ではクロックを約4GHz以上に押し上げられなかった。マルチコアプロセッサが、年々性能を向上させる唯一の方法だった。 - ここまでの間、CPUは巧妙なスケジューリングトリックを使って逐次コードを並列化することで性能向上を図っていたが、マルチコアになるとソフトウェア開発者は同時プログラミングが学術やHPCクラスターだけのものではないと認識せざるを得なくなった。CSのカリキュラムは、ほとんどが2000年代初頭に取り残されているように感じる。ビッグOを教えて、マージソートやクイックソートがバブルソートよりも優れていることを示すけど、アムダールの法則のようなトピックは上級選択科目に埋もれていて、実際には現代のワークロードにおけるリアルなコードの性能にもっと直接的に関係しているのに。とにかく、これらのことを理由に、2年生と3年生にビトニックソートを教えることにした。ここで言いたいのは、サイモンの「コードは安い」という主張が、アクセスしやすい大規模並列計算ハードウェアのある世界で、パフォーマンスの高いソフトウェアを書くために重要なことが完全に変わったことを実感するようなパラダイムシフトに感じるということ。分岐やデータ依存を最小限に抑えることで、ほとんどの開発者が慣れ親しんでいるコードとは全く異なるコードが生まれる。例えば、5回の線形パスを1つのマージパスで実行するよりも、異なるメモリに触れる5回のパスの方が実際には速いかもしれない。マージパスはキャッシュにデータを入れたり出したりするのを待たなきゃいけないから。これがソフトウェア開発プロセスに何を意味するのかは分からないけど、新しいパラダイムを最初に見つけてそれを活用できる人には、すごいリターン(10〜100倍、適切に並列化されたコードと同じように)があるだろう。
最近、クラウドコードで赤/緑TDDにハマっていて、これが正しい方向だと思う。プロジェクトが複雑さと範囲を増していく中で、他の部分に微妙に影響を与えるものを作っているのではないかと心配になった。限られたコンテキストウィンドウのせいで、あるサイズを超えると、クラウドは自分がやっている作業がシステムの他の部分とどう相互作用しているかを理解しなくなることが明らかだった。テストはそれに対する保護を助ける。赤/緑TDDは特に、現在の作業が実際に達成しようとしていることにかなり集中していることを保証する。変更の結果として行動の具体的な変化を観察できるし、テストスイートが時間とともに成長するという追加の利点もある。包括的な統合テストスイートを作るのも今まで以上に簡単になった。私にとって最も価値のあるテストは、実際のバックエンドを使ってUI要素だけでユーザー向けのワークフロー全体をテストするものだ。
赤/緑は特にクラウドと相性が良い。今でもオーパス4.6で、クラウドは「//X/Y/Zまで実装保留: return { true }」のようなコメントを出して、インラインスキップコメントに基づいて実装を完全にスキップすることがある。以前はテストでもこれを積極的にやっていたけど、全体的に赤/緑のプロンプトが大いに役立つ。エージェントに「失敗したテストを今は成功と考えろ」と言っているようなもので、そうすればたくさんの失敗が出てくる。私も統合テストが好きだ。手動コーディングだと統合テストが悪い感じになることがあった。場合によってはコード出力がほぼ倍になるから、特にサーバーをモックする必要があるときは。今はそれが安くなっていて、とても助かる。
私はオープンソースの仕様に基づいたプロジェクト管理ツールに貢献してる。仕様を反復しながら、AIを使ってその仕様自体を洗練させるのに、だいたい1日かけてる。時々、ClaudeやGeminiにフィードバックを送り合ったりしてる。仕様が価値なんだ。AIのPMツールを使って、それをn個のタスクやサブタスク、依存関係に分解する。その後、プロジェクトを達成するためにClaudeをチームモードで起動する。夜間は放置しておけるし、朝起きるとn個のPRがマージされてる。
記事のパターンはスタート地点かもしれないけど、カバーすべきことがもっとたくさんあるよね:エージェントの役割(オーケストレーター、QAなど)、エージェントのコミュニケーション、思考パターン、反復パターン、機能フォルダ、時間を意識した変更履歴の追跡、プロンプトの強制、リアルタイムの指示など。これには本当に公共のWikiが必要かもね(C2 [1]スタイル) [1]: https://wiki.c2.com/
またやるつもりだよね?シンプルで理にかなったこと(「まずテストを書く」、「小さなコンポーザブルモジュール」など)を、 fancyな複雑な名前(「行動制約実装ライフサイクルパターン」、「境界スコープ処理構造パターン」など)にして、コンサルタントや専門家がそれを売りにする業界を作るんだ。みんなが秘密のソースと正しい呪文を持ってるって言ってる。あのクソみたいなやつは_話す_んだ。単に_話しかける_だけでいい。やりたいことを頼むだけで済む。
> あのクソみたいなやつは_話す_んだ。単に_話しかける_だけでいい。やりたいことを頼むだけで済む。でも、バターを渡せるの?
誰か「アジャイルAI」に対して主張した人はいるの?
このエージェント的なエンジニアリングのスレッドには、繰り返し出てくるテーマがあるんだ。それは、教訓がほぼ常に普遍的に語られるけど、実際にはチームのサイズ、コードベースの成熟度、テストカバレッジ、リスク許容度に深く依存しているってこと。よく整備されたバックエンドサービスの「勝利」として提示されるものが、UI重視の古いコードを扱っている人たちを間違った道に導くこともある。これのアートは、正しいパターンを見つけることよりも、パターンが適用される時を正直に宣言することかもしれないね。
いい指摘だね。これを本じゃなくてウェブサイトにしてる理由は、情報が常に変わるからなんだ。更新したいし、各パターンがどこでいつ有効かっていうメモを追加するつもりだよ。そういう制約が明確になったらね。
同意だね。しかも、いくつかは普遍的だよね。今、エージェントのワークフローは独立した真実のソースからのチェックインでめっちゃ恩恵を受けてる。サイモンのツールの多くは、これを統合できるようにハーネスを作ってるんだ。例えば、デモを作って、コードがそのデモを生成するか確認する「showboat」とか。ドキュメンテーションの真実のソースを作る「rodney」もあって、視覚的にナビゲーションで期待通りに動くか確認するんだ。赤緑テストは概念的には同じで、これらのテストがあれば、エージェントはもっと成功裏にループできるようになると思う。だから、チームやデプロイメントの特異性を超える「普遍的なもの」、あるいは少なくとも「今のところの普遍的なもの」があると思うよ。