コーディングエージェントの作り方

 (ghuntley.com)
62 ポイント 投稿者 GN⁺ 2025-08-25 | 4件のコメント | WhatsAppで共有
  • 2025年現在、コーディングエージェントを自分で作ることは、個人開発者が取り組める最高のプロジェクトの一つ
  • エージェントは300行のコードとLLMトークンループだけで動作し、これを作ってみることで、消費者ではなくAIの生産者へ転換する機会を得られる
  • 基本構成要素は、ファイル読み取り、ファイル一覧、Bash実行、ファイル編集、コード検索のようなツールで、これにより実際の自動化機能を実装する
  • モデル選定では、Claude Sonnet、Kimi K2のようなエージェント向きのモデルが適しており、必要に応じて GPT のようなオラクル型モデルをツールとして接続し、高度な検証を行う
  • 実際に Amp、Cursor、Claude Code、GitHub Copilot などの商用製品も類似した構造である

ワークショップ概要

  • Geoffrey Huntley が実施した無料ワークショップで、コーディングエージェントを自作する方法と原理を、実践中心で案内
  • Roo code、Cline、Amp、Cursor、Windsurf、OpenCode といった既存の商用 AI 支援ツールと構造や原理を比較しながら、実際に実装してみる機会を提供
  • 制作経験を通じて、単なる AI ユーザーから、自ら AI を活用して自動化ツールを作る開発者へ成長できる
  • 中核となる構造は、およそ 300 行のコードで LLM トークンをループ的に活用し、エージェント機能を作ること
  • 各ツール別のプリミティブ（読み取り、ファイル一覧、実行、編集、コード検索）機能を追加し、実際の動作例とコードは GitHub リポジトリ で公開

エージェントとは何か

  • 最近「エージェント」という用語は広く使われているが、実質的な意味や内部動作の原理は明確でない
  • エージェント制作の参入障壁が下がるにつれ、AI の消費者を超えて、業務自動化を主導できる生産者へ成長できる
  • 2025年時点では、基本的なデータベース概念（Primary key）のように、エージェント制作の原理が必須知識として定着しつつある
  • Canva などの企業はすでに採用面接の過程でAI の使用を推奨しており、AI 自動化の能力は採用の重要要素になっている
  • いま後れを取る理由は AI そのものではなく、自己研鑽を通じて新しいツールを身につけないことにある

コーディングエージェントの中核原理

  • コーディングエージェントは300行のコードとLLMトークンループだけで構成され、反復的なトークン入力によって機能を実行する
  • **同時作業（concurrent work）**の概念が重要
    • 例: Zoom 会議中でもエージェントが並列で作業を進められるため、業務効率が大きく向上する
  • すべての LLM がエージェント的というわけではない
    • 「高安全」(例: Anthropic、OpenAI)
    • 「低安全」(例: Grok)
    • 「オラクル」(要約・高次思考に有利)
    • 「エージェント的」(行動バイアス、素早い反復・ツール呼び出し)
  • 開発者はモデルごとの特性を理解し、目的に応じて活用するモデルを選ぶ
  • むやみにコンテキストウィンドウを割り当てることは性能低下の要因であり、「少ないほど結果が良い」ことを意識すべき
    • 過度な MCP ツール登録は性能低下につながる
  • ルール: 「Less is more」→ 必要な分だけツールとデータを文脈に配置してこそ最適な性能を確保できる

コーディングエージェント構築プロセスの流れ

  • 1. ツール登録と関数呼び出し

    • たとえば 天気照会ツールを LLM に登録し、適切な状況で LLM が関数呼び出し形式で対応できるようにする
    • MCP(Model Context Protocol) は「関数に関する情報バナー」に似ており、関数の説明だけ登録しても自動呼び出しが可能

  • 2. プリミティブツールごとの中核機能

    • ファイル読み取り(ReadFile): パスを渡すとファイル内容をコンテキストとして読み込む
    • ファイル一覧(ListFiles): ディレクトリ内のファイル・フォルダ一覧を提供
    • コマンド実行(Bash): LLM がシステムシェルのコマンドを実行し、結果を返す
    • ファイル編集(Edit): 指定ファイルの作成・修正を自動化
    • コード検索(CodeSearch): パターン、キーワード、関数名を基準にコードベース全体を高速検索する（ripgrep 活用）

  • 3. 例と結果の流れ

    • 各ツールを LLM に統合し、自然言語プロンプトだけで連続した業務（例: FizzBuzz コード生成→実行確認、ディレクトリ探索→内容分析など）を自動化
    • ツール関数はユーザー入力やシナリオに応じて順次呼び出され、結果の返却をループ内で繰り返す
    • エージェントの主要な動作シーケンス: ユーザー入力→ツール呼び出し要否の判断→ツール実行→結果をコンテキストに割り当て→反復

拡張可能性とオープンソース

  • 現在、ほとんどのコーディングエージェントは ripgrep などの既存オープンソースツールを基盤として動作している
  • GitHub には SST Open Code、mini-swe-agent など、わずか 100 行で実装されたシンプルかつ強力なエージェントプロジェクトが存在し、性能や構造の参考にできる
  • 開発者には既存製品を比較するより、直接作って原理を理解し活用することが推奨される
  • 実業務・自動化へ適用する際には、自前のエージェントの作成と組織内への展開が競争力につながる

結論と示唆

  • コーディングエージェントは複雑な技術ではなく、シンプルなループ構造とツールの組み合わせで構成される
  • コーディングエージェント制作の核心は構造理解と迅速な実行力であり、自作経験を通じて AI 技術の変化に積極的に対応できる
  • 重要なのは AI そのものより、継続的な自己研鑽とツール制作能力の確保といった自己投資が現時点で最も重要な個人の成長戦略だということ
  • 「AI があなたの仕事を奪うのではなく、あなたの同僚がエージェントで武装して自動化し、より速く働くことが脅威である」

関連記事

4件のコメント

 
GN⁺ 2025-08-25
Hacker Newsの意見

  • 私たちのPrinceton SWE-benchチームは、約100行のコードでSWE-benchで良い成績を出すエージェントを作りました。興味があれば一度見てみるとよいです mini-swe-agent

    • 本当にかなりシンプルな構造なのに驚きました。こういう情報を共有してくれてありがとう。
      コード全体は実際にはこのプロンプト群で動いています エージェント基本プロンプトのソースコード

      Your task: {{task}}. Please reply
with a single shell command in
triple backticks.

To finish, the first line of the
output of the shell command must be
'COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT'.

    • エージェントのサンプルプロンプトのうち、「1. コードベースで関連ファイルを見つけて読む 2. 問題再現スクリプトを作る 3. 問題を修正する 4. スクリプトで修正を確認する 5. エッジケースをテストする」の部分が役に立ちます。
      私もデバッグループでこのようなプロンプトを似た形で使っています。
      「コードベースを分析して原因候補をリストアップし、可能性の高い順にランク付けし、スクリプトやデバッグログで仮説を検証する」というやり方が、自分の問題解決ルーチンに大いに役立っています。

    • 問題が1つのファイルの中で自己完結しているときは、LLMを使って修正するのはとても簡単です。
      しかし一般的なコードベースでは、ファイルや文脈があちこちに散らばっているので、開発者の構造化された設計意図や整理の仕方に沿って把握するのは簡単ではありません。

    • 素晴らしい試みに拍手を送りたいです。ただ、残念なのはツールがあまり多くないことです。
      コードの大半はエージェントフレームワークに当たり、SWE専用に特化したコードは思ったほど多くありません。
      私も遊びでSWEエージェントを作ってみたので、autocodeも参考にするとよいです。

    • 感謝の気持ちを込めて参考資料に追加しました。

  • Thorsten Ballが書いた非常によく似た「エージェントの作り方ガイド」が AmpCode How To Guide にもあります。
    全体的にAmpもかなり興味深いです。
    もう秘密めいたサービスではありませんが、エージェントコーディング関連のツールが次々に公開されるのはうれしいことです。
    今後はさまざまなソフトウェアにこうしたエージェントモデルが標準で組み込まれるようになると思います。

    • こちらの方がずっと見やすくてありがたいです。

    • 著者本人がAmpで働いていることにも言及されています。

    • GhuntleyもAmpで働いています。

  • 1枚の絵は普通1000語の価値があると言いますが、この資料では図の価値が99.6%引きになった感じです。
    これは何なのか気になります。

    • カンファレンスのワークショップ用スライド資料です。
      テキストは実際の発表での言い回しを書き起こしたものです。

  • 誰かツール利用の仕組みについて確認してくれないかと思っています。
    ClaudeやChatGPTなどはAPIで「ツール」を提供していて、ツール呼び出し要求が入ると、応答側が実際にツールを実行して結果を返す形だと理解しています。
    でも実際のモデルは厳密には文字ベースなので、APIでどうやってモデル応答を複数の構造に変えているのか気になります。
    きっとファインチューニングの過程で、特定のツール呼び出しを特殊なブロック形式で入れた例を通じてモデルが理解し、Claude/ChatGPTのサーバー側でそれを解釈する、という流れがあったのだろうと推測しています。
    これに関連する文書や、内部で使う特殊トークンに関する情報があるのか、またユーザー入力がこの「意味を担う」トークンを悪用できないようにどう防いでいるのか気になります。

    • Anthropicが公開している実装文書があります。
      Anthropic Tool Use Documentation
      ここから、モデルは実際には「テキスト」ではなくトークン単位で動いていることがよく分かります。
      コンパイラがソースコードを解析して、キーワード、括弧、構造などの「トークン」列を作るのと似ています。
      出力には実際の単語と一緒にメタデータが含まれることもあります。

    • 概念的にはその理解で合っています。
      LLMとの唯一の本当のインターフェースは「トークン」だけで、制御チャネルとデータチャネルは分離されていません。
      モデルAPI層では、ツール呼び出し用の指示と利用可能なツール一覧をプロンプトに挿入し、それぞれの説明も一緒に与えます。
      ツール呼び出しが必要なとき、モデルは応答内に特殊ブロック（特殊トークンを含み、ツール名とパラメータを明示）を挿入し、API層がそれを抽出してJSON形式に変換します。
      ツール実行結果も特殊トークンでエンコードされて挿入されます。
      ユーザー入力からこうしたトークンを独自に注入できないよう、API層が防いでいます。
      最新のSoTAモデルはツール呼び出しについてかなりファインチューニングされており、汎用的なツール呼び出しと特定ツール向けケース（例: Claude SonnetモデルがClaude Codeツールに特化している場合）の両方が含まれます。
      これらすべてがうまく動いているのは驚くほどで、ツール呼び出しではファインチューニングが本当に重要な役割を果たしています。
      ファインチューニングなしでも動作はしますが、成功率は大きく下がります。

    • 「ツール呼び出しが必要な例を特殊なブロックで返す形にファインチューニングした」という推測は正しいと思います。
      答えがよく分からないときや、そう指示されたときに、ツール呼び出しフォーマットで応答するよう学習されています。
      フォーマットに従うツール呼び出し例（フォーマット自体）と、一部ツールに特化した学習の両方が行われています。
      例えばgpt-ossは、たとえ特に言及がなくても検索ツールを使おうとする傾向があります。
      Anthropicの文書には、なじみのあるツール（例: text_editor、bash）の一覧も別にあり、これらのツールについては使い方の深い意味まで別途学習されている可能性が高いです。
      実際には構造はかなり壊れやすく、「特殊トークンやトークン列」という低レベルの信号を通じて実現されています。

  • 「トークンをループに投げ込み続ければエージェントが生まれる」という言葉は、「トークン」を「お金」に置き換えてみると現実的な風刺に感じられます。
    結局、お金を燃やし続ければエージェントが生まれるということです。

    • トークンがすべてお金だと言い切るのは難しいと思います。
      ローカルモデルもどんどん良くなっています。
      今のところ最高の結果を出すにはトークン（=お金）が必要ですが、将来は変わる可能性が高いです。

  • こんなふうに画像ばかりだと読むのがとてもつらいです。
    スクロールシミュレーターを見ているような気分です。

  • bashツール以外に、なぜわざわざ別のツールが必要なのか気になります。
    ファイル一覧の取得や、リポジトリの検索と探索、ファイル内容の編集といったことはbashだけでも全部できるのではないでしょうか。
    それとも上の mini-swe-agent の例で示されているケースなのでしょうか。

    • 技術的に見れば、bashひとつだけでもかなり多様な作業が可能で、実際それで成功した経験もあります。
      興味深いのは、ツールを制限するほどエージェントがより創造的にアプローチすることです。
      ただし、学習済みのさまざまなツールを提供すると、モデルが各ツールの使い方をすでによく理解しているため、トークン使用量も効率的で、全体として成功率も高くなります。
      bashだけを使う場合、bashismや引数処理、空白処理のような部分でよく迷う問題もあります。

    • 別個のツールを使う方が、bashひとつに詰め込むよりずっと単純です。
      もしすべてをbashで処理するなら、必ず安全に実行できるコマンド（例: ファイル一覧取得）はそのまま実行し、それ以外の危険なコマンドはユーザー承認を求める仕組みを別途実装しなければなりません。
      ファイル一覧取得を別ツールとして提供すれば、プロジェクトディレクトリ外のファイル露出も防げます。

    • 実質的にはbashツールとEditツールだけでもコーディングエージェントは十分動かせます（Editは必須ではありませんが、ないと非効率が大きくなります）。
      ただしコード検索のような部分では難しさがあるかもしれません。
      例えばripgrepをbashで使うようプロンプトを調整する形でカバーできそうです。

    • なぜIDEが必要なのですか。シェルで全部できるのに、なぜあえて使うのでしょうか。
      UI（インターフェース）とは、その瞬間に必要な情報とアクションを提供するためのものです。

    • なぜbashツール以外も入っているのか、という質問に対しては、最初は最小限のツールだけ与えて始めて、後からbashを追加してもよいから、ということだと思います。

  • 「エージェントの作り方」を長々と説明するより、エージェントが実際に作ったプロジェクトを見せてほしいです。

    • 実際にエージェントを作って、HNに「Show HN」として共有してくれたらとてもうれしいです。

  • Oracle、Agent、high safety、low safety という軸が何を意味するのか説明できる人はいますか。

  • edgeとchromeのオンデバイスモデル（phi4-mini、gemini nano）で実際に試してみましたが、モデルサイズのわりにかなりよく動いて驚きました。
    how to build an agent on device 実験事例
 
crawler 2025-08-25

普通、1枚の図には1000語分の価値があるっていうけど、この資料では図の価値が99.6%オフになった感じ。これが何なのか気になる

めちゃくちゃ笑ったｗｗｗ 何のことかと思ったけど、リンクに入ったらすっと理解できた
 
savvykang 2025-08-25

ブログのほかの投稿のサムネイルもひどいですね。まったくクリックしたくならない見た目です。
 
nemorize 2025-08-25

ｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ