ささっとCoding Agentをはじめる

Intro

coding agentは、プロジェクト内のファイルを自由に読み書きしたり、コマンドを実行したりできる。プログラミング用途で必須のツールになりつつあるが、それ以外にもドキュメント作成、設定ファイルの編集、データ処理など、あらゆるテキスト作業に活用できる。

この記事では、無料ですぐに始められるcoding agentと、有料の高性能なものを、最小限の準備で始める方法を紹介する。

TL; DR

• 無料ですぐ始めるならOpencodeかGemini CLI
• プロジェクトには指示ファイル（CLAUDE.md / GEMINI.md / AGENTS.md）と初期設計ファイル（docs/design/init.md）を用意する
• coding agentは確率的に振る舞う。ルール違反が頻発するなら構造的なハーネスを検討する
• Claude Codeは有料だが高機能。Z-AI経由なら安価に利用できる

• 無料ですぐ始める
  • Opencode
  • Gemini CLI
• 最小限の事前準備
  • 指示ファイル
  • プロジェクト概要: docs/design/init.md
  • .gitignore
• 進め方
  • 軽い作業
  • 大きな作業
  • 外部ファイルへのアクセス
• 注意点
  • ツールによるハーネス
  • 設定によるハーネス
• Claude Code
  • Z-AI経由で安く使う

無料ですぐ始める

Opencode

Opencodeは複数のLLMプロバイダを統一的なTUIで使えるcoding agentクライアントだ。無料で一定量まで利用できるLLMと事前に連携されており、インストール直後からすぐに使い始められる。

# opencode install
# https://opencode.ai/ja
curl -fsSL https://opencode.ai/install | bash

無料枠のモデルに加えて、他のLLMプロバイダのAPIキーも設定できる。/connectコマンドから各プロバイダの設定画面に進める。

Gemini CLI

GoogleのGemini CLIも無料で始められる。Googleアカウントでログインするだけで利用可能だ。

npm経由でインストールするため、事前にnvmとnpmを用意しておく。
新規WSL環境構築 #nvm

# インストール
npm install -g @google/gemini-cli

# 起動
gemini

# Googleアカウントでログイン
/auth login

無料で使えるが、応答に癖がある。指示に忠実に従うタイプではなく、独自の判断で内容を膨らませたり、存在しない事実をでっち上げたりすることがある。出力は必ず確認すること。

最小限の事前準備

coding agentを効果的に使うために、プロジェクトにいくつかファイルを用意しておく。

指示ファイル

coding agentはプロジェクト内の指示ファイルを最優先で読み込む。Claude CodeならCLAUDE.md、Gemini CLIならGEMINI.md、GitHub CopilotならAGENTS.mdだ。

プロジェクトで守ってほしいルールや、使用言語、禁止事項を短く記載しておくとよい。

CLAUDE.md

## 基本方針
- 日本語で返信、ドキュメント作成をすること
- 一時的なファイルは必ず `./tmp/` に作成すること

## プロジェクト構成

- src/: ソースコード
- docs/: ドキュメント
- tmp/: 一時的なファイル

## 開発ルール
- テストコードは必ず書くこと
- `as`キャスト禁止。型ガード関数を使用すること

メモ

複数のcoding agentを使う場合、各エージェントの指示ファイルに同じ内容を書くのは面倒だ。シンボリックリンクを張るか、各エージェントがサポートする@ファイルパス記法で共通ファイルを参照させるなどの工夫がある。

プロジェクト概要: docs/design/init.md

docs/design/init.mdにプロジェクトの目標と概要を記載しておく。

coding agentはファイルを自由に読み書きできる。当然それらのファイルはコンテキストをクリアしても残る。最初の段階で目標を明確にしておけば、セッションが途切れてもagentが自律的に文脈を取り戻しやすくなる。

docs/design/init.md

## 概要

coding agentが過去の会話履歴を検索・取得するためのCLIツール。

### ユースケース

- 以前の会話で使った手順・コマンドを再利用する
- 特定のエラーや実装について過去のやり取りを参照する
- agentが自分自身のセッション履歴を文脈として取得する

.gitignore

.gitignoreは後から用意してもよいが、早めに用意しておくに越したことはない。特に環境変数ファイルや一時ディレクトリ、ビルド成果物は最初から除外しておく。

.gitignore

.env
tmp/
output/

# JavaScript / TypeScript
dist/
node_modules/

# Rust
target/

進め方

coding agentを起動したら、まずプロジェクトの現状を把握してもらう。

「docs/design/init.mdを見て。さらに、プロジェクトの現状を把握して。」

この時点で指摘された問題に気になる点があれば反論する。プロジェクトを実行するための方法について、LLMの理解が不足していれば補足説明をする。

その後、作業の規模に応じて進め方を変える。

軽い作業

バグ修正や小さな機能追加など、範囲が明確な場合は直接指示を与えて進める。

「src/auth.tsのlogin関数で、トークンの有効期限チェックが抜けている。
期限切れの場合はrefreshTokenを呼ぶように修正して。」

大きな作業

新規開発や大規模なリファクタリングなどの場合は、要件定義から設計までagentに任せる。

「これから要件定義、設計、実装を行うので、その想定でプロジェクトの開発計画を立てて、
docs/dev/にファイルを作成せよ。検討や要件定義などで質問があれば適宜行え」

外部ファイルへのアクセス

プロジェクト外部のファイルにアクセスしたい場合、慎重に判断する。読み取りだけならある程度気軽に許可してよいが、書き込みや削除については念入りに確認すること。

注意点

指示ファイルや口頭での指示で、ある程度LLMの行動をコントロールすることはできる。しかし基本的に彼らは確率的に行動する。一度ルールを破った場合、その後も繰り返される見込みが高い。頻度が高いならなおのことだ。

そもそも簡単に想定と異なる行動があったということは、ルールや方針が世間の常識と乖離しているということであり、ルール自体の見直し、構造の修正、ツールや設定による決定論的なハーネスの導入を検討したほうがいい。(ルール違反が繰り返されてストレスがたまるだけだ)

ツールによるハーネス

タスク管理を特定のCLIツールに任せる、pre-commitフックで自動チェックを仕掛けるなど、ツールレベルで行動を制約できる。

設定によるハーネス

coding agentやgitの設定で、特定の行動を禁止できる。たとえばClaude Codeならsettings.jsonで特定のコマンドの実行を禁止したり、許可する操作を明示的に指定したりできる。

gitでも--forceプッシュを禁止する設定などがある。これらの「決定論的な制約」は、指示ファイルの「確率的な制約」より確実に効く。

Claude Code

Claude CodeはAnthropicのcoding agentだ。有料だが、非常に高性能で高機能。OpenAIのCodexと人気を二分している。

月額のProプランとAPI従量課金の二通りがある。

Z-AI経由で安く使う

Z-AIは中国のLLMサービスで、Claude Codeを大幅に安く使えるルートがある。Z-AIのAPIキーを環境変数に設定し、専用のラッパー関数を用意すれば、通常のClaude Codeと同じUI・機能で利用できる。

~/.bash_aliases

alias zaic='_zaiClaudeCode'
function _zaiClaudeCode(){
    ANTHROPIC_AUTH_TOKEN="$ZAI_API_KEY_CLAUDE" \
        ANTHROPIC_BASE_URL="https://api.z.ai/api/anthropic" \
        API_TIMEOUT_MS="3000000" \
        CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
        ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-4.5-air" \
        ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5" \
        ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5" claude $@
}

ZAI_API_KEY_CLAUDE環境変数にZ-AIのAPIキーを設定しておけば、zaicコマンドで起動する。モデルにはZ-AI側のglm-5が割り当てられるが、UIや機能はClaude Codeそのものだ。

Z-AI経由の場合、モデルはClaudeではなくZ-AI独自のモデル（glm-5など）になる。API互換インターフェースを通して動作するため操作感は同じだが、出力品質や推論能力は実際のClaudeとは異なる点に留意すること。