コーディングエージェントの構築

このチュートリアルでは、ソフトウェア開発タスクを支援するコーディングエージェントの構築方法を学びます。基本的なエージェントから始め、コードの読み取り、変更、テストの実行、ドキュメントの検索まで行える、実用的なアシスタントへと段階的に機能を拡張していきます。

最終的には、エージェントへの指示（instruction）の構造化、ツールの設定、そして複雑なワークフローのための複数エージェントの連携方法を習得できます。

作成するもの

以下の機能を備えたコーディングエージェントを構築します：

プロジェクト内のファイルの読み取りと修正
テストやリンターなどのコマンド実行
構造化された開発ワークフローの遂行
必要に応じたドキュメントの検索
複数ステップにわたるタスクの進捗管理

学習内容

YAMLによる cagent エージェントの設定方法
エージェントへのツールアクセス（ファイルシステム、シェルなど）の許可方法
効果的なエージェント指示（instruction）の書き方
特定タスクのための複数エージェントの構成方法
自分のプロジェクトに合わせてエージェントをカスタマイズする方法

前提条件

開始前に以下を準備してください：

cagent のインストール：インストールガイドを参照
APIキーの設定：環境変数に ANTHROPIC_API_KEY または OPENAI_API_KEY を設定してください。キーは Anthropic または OpenAI から取得できます。
作業用プロジェクト：エージェントの支援を試したい任意のコードベース。

最初のエージェントを作成する

cagentのエージェントはYAML設定ファイルで定義します。最小限の設定には、使用するモデルとその目的を定義する指示（instruction）が必要です。


agents:
  root:
    model: openai/gpt-5
    description: 基本的なコーディングアシスタント
    instruction: |
      あなたは有能なコーディングアシスタントです。
      コードの記述や理解を助けてください。

エージェントを実行します：


$ cagent run agents.yml

「Pythonでファイルを読み込む方法は？」といった質問を投げてみてください。この状態では質問に答えることはできますが、まだあなたのプロジェクトファイルを見たり、コマンドを実行したりすることはできません。

ツールの追加

コーディングエージェントが実際の開発作業で役立つためには、プロジェクトファイルへのアクセスとコマンド実行の権限が必要です。これらは toolsets を追加することで有効になります。

agents.yml を更新して、ファイルシステムとシェルへのアクセスを追加します：


agents:
  root:
    model: openai/gpt-5
    description: ファイルシステムアクセスを持つコーディングアシスタント
    instruction: |
      あなたは有能なコーディングアシスタントです。
      ソフトウェア開発を支援するために、ファイルの読み書きが可能です。
      タスクを完了する前に、必ずコードが動作するか確認してください。
    toolsets:
      - type: filesystem
      - type: shell

更新したエージェントを実行し、「README.md を読んで内容を要約して」と頼んでみてください。エージェントは以下のことが可能になります：

カレントディレクトリ内のファイルの読み書き
シェルコマンドの実行
プロジェクト構造の探索

Note

デフォルトでは、ファイルシステムへのアクセスはカレントディレクトリに制限されています。他のディレクトリへのアクセスが必要な場合、エージェントは許可を求めます。

エージェントへの指示（instruction）の構造化

汎用的な指示からは汎用的な結果しか得られません。実用的なエージェントにするには、特定のワークフローに従わせ、プロジェクトの規約を理解させる必要があります。

指示を構造化して更新します。以下の例は Go 言語開発用ですが、他の言語にも応用可能です。


agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Go言語のエキスパート開発者
    instruction: |
      あなたの目標は、コードの調査、修正、および検証を通じて開発タスクを支援することです。
 
      <TASK>
          # ワークフロー:
          # 1. 分析 (Analyze): 要件を理解し、関連するコードを特定する。
          # 2. 調査 (Examine): ファイルを検索し、構造と依存関係を分析する。
          # 3. 修正 (Modify): ベストプラクティスに従って変更を加える。
          # 4. 検証 (Validate): リンターやテストを実行する。問題があれば「修正」に戻る。
      </TASK>
 
      制約事項:
      - 変更を加える前に、十分に調査を行うこと
      - タスク完了と見なす前に、必ず変更を検証すること
      - コードはチャットで見せるのではなく、ファイルに書き出すこと
 
      ## 開発ワークフロー
      - `go build ./...` - アプリケーションのビルド
      - `go test ./...` - テストの実行
      - `golangci-lint run` - コード品質のチェック
 
    add_date: true
    add_environment_info: true
    toolsets:
      - type: filesystem
      - type: shell
      - type: todo

構造化された指示により、エージェントは以下の能力を得ます：

明確なワークフローの遵守
プロジェクト固有のコマンドの把握
ケアレスミスを防ぐための制約の理解
実行環境に関するコンテキスト（add_date など）の活用

todo ツールセットを追加すると、エージェントは複雑なタスクを細分化し、進捗を管理できるようになります。

複数のエージェントを組み合わせる

複雑なタスクでは、役割を分担した方が効率的です。メインのエージェントがコーディングに集中できるよう、ドキュメント調査などを担当する「サブエージェント」を追加できます。

ドキュメント検索を担当する「司書（librarian）」エージェントを追加してみましょう：


agents:
  root:
    model: anthropic/claude-sonnet-4-5
    description: Go言語のエキスパート開発者
    instruction: |
      (中略...)
      ドキュメントの調査や仕組みの検索が必要な場合は、librarian（司書）エージェントに依頼してください。
    toolsets:
      - type: filesystem
      - type: shell
      - type: todo
    sub_agents:
      - librarian
 
  librarian:
    model: anthropic/claude-haiku-4-5
    description: ドキュメント調査担当
    instruction: |
      あなたは「司書」です。あなたの仕事は、開発エージェントを助けるために
      関連するドキュメントやリソースを見つけることです。
      必要に応じてインターネットを検索し、Webページの内容を取得してください。
    toolsets:
      - type: mcp
        ref: docker:duckduckgo
      - type: fetch

「Goで context.Context を使うにはどうすればいい？その後、サーバーのコードに適用して」と頼んでみてください。メインエージェントは調査を司書に委任し、得られた情報を元にコードを修正します。

司書に小型で高速なモデル（Haiku 4.5）を使用することで、コストを抑えつつ、メインエージェントのコンテキストをコードに集中させることができます。

プロジェクトへの適応

コアとなる概念を理解したので、特定のプロジェクトに合わせてエージェントを適応させます：

開発コマンドの更新

Goのコマンドをプロジェクトのワークフローに置き換えます：


## 開発ワークフロー
- `npm test` - テストの実行
- `npm run lint` - コード品質のチェック
- `npm run build` - アプリケーションのビルド

プロジェクト固有の制約の追加

エージェントが同じ間違いを繰り返す場合は、明示的な制約を追加します：


制約事項:
  - タスク完了と見なす前に、必ずテストを実行すること
  - src/ ディレクトリ内の既存のコードスタイルに従うこと
  - generated/ ディレクトリ内のファイルは決して変更しないこと
  - 新しいファイルにはTypeScriptの厳密モード（strict mode）を使用すること

適切なモデルの選択

コーディングタスクには、推論に特化したモデルを使用します：

anthropic/claude-sonnet-4-5 - 強力な推論能力、複雑なコードに適している
openai/gpt-5 - 高速で、一般的なコーディング能力が高い

ドキュメント検索などの補助的なタスクには、小型のモデルが適しています：

anthropic/claude-haiku-4-5 - 高速でコスト効率が高い
openai/gpt-5-mini - 単純なタスクに適している

使用状況に基づいた反復

エージェントを改善する最善の方法は、それを使用することです。問題に気付いたときは：

問題を防止するための具体的な指示を追加する
動作をガイドするための制約を更新する
開発ワークフローに関連するコマンドを追加する
複雑な領域のために専門のサブエージェントを追加することを検討する

学習した内容

あなたは以下の方法を習得しました：

基本的なcagent設定の作成
エージェントの機能を有効にするためのツールの追加
一貫した動作のための構造化された指示の作成
専門的なタスクのための複数エージェントの構成
異なるプログラミング言語やワークフローへのエージェントの適応

次のステップ

大規模な出力の処理、エージェントチームの構造化、およびパフォーマンスの最適化に関するベストプラクティスを学ぶ
cagentをお使いのエディタと統合するか、エージェントをMCPクライアントのツールとして使用する
利用可能なすべてのオプションについて設定リファレンスを確認する
どのような機能が有効にできるかツールリファレンスを確認する
さまざまなユースケースの設定例を探索する
Dockerチームがcagentを開発するために使用している完全な golang_developer.yaml を参照する