AI Coding の環境を整える（後）：AI Agent と MCP サーバ

悲しいお知らせ

AI Coding の環境を整える（前）で一生懸命 Ollama について語ったのですが、Ollama で、かつ一般的な GPU（VRAM 16GB 以内）で動かせるモデル（例：gpt-oss:20b）を使って AI Coding を行うのは、かなり無理があるということが分かりました。
恐らくは Context Length の問題が一番大きな原因かとは思います。
なので私は Github Copilot をメインに使うようにしました。最も安いモデル（GPT-5-mini）でもそれなりに精度高く動かすことが出来ます。

オススメ AI Agent

今や世に出ている AI Agent は本当に星の数ほどあります。私は以下の条件で良い AI Agent を探しました。

• 無料で使える（OSS である）
• Ollama を使うことが出来る
• Terminal で使うことが出来る（TUI を持つ）
• Instruction（AGENTS.md 等）を設定することが出来る

私が辿り着いたのは OpenCode です。ホームページの見た目はレトロですが、かなりオススメです。

OpenCode の良いところ：

• OSS で開発もかなり活発
• ドキュメントが充実している
• 動作が軽快で分かりやすい
  • completion（補完）がかなり強力
• 機能が豊富で、そのほとんどの機能をカスタマイズ可能
  • 特に Agent 機能がオススメ
• 様々な Provider（LLM）を使うことが出来る
  • もちろん Ollama も使える
• ローカルの MCP サーバをきちんと動作させることができる
  • MCP サーバについては後述
• 設定に環境変数を使うことが出来る
  • 地味だが、かなり魅力的なポイント

「動作が軽快」と書きましたが、やはりそれなりの modern で高速な Terminal だとより良いと思います。私のオススメ Terminal は wezterm です。

OpenCode のインストールと設定

私の OpenCode の設定はここで公開しています。基本的に設定は ~/.config/opencode/opencode.json を作るだけなのですが、私が公開している opencode.json を使うならば、インストール方法は以下になります。

• npm（nodejs）、uv をインストールする
  • asdf-vm を使ったインストールがオススメ
• Gemini CLI を MCP サーバとして使うためのインストール・設定
  • npm --global install @google/gemini-cli@latest
  • Gemini CLI を動かして（gemini）認証を通しておく
• npm --global install opencode-ai@latest

また、個人的に作った基本的な Instruction（Rule）も公開しています。私の AGENTS.md は、各言語でどのような実装をして欲しいかと、MCP サーバの使い方を設定しているだけです。これを ~/.config/opencode/AGENTS.md に置くだけで、それなりに使えるはずです。

基本的な OpenCode の使い方

• Python を使った Project ならば、あらかじめ pyproject.toml, README.md, Makefile 等を作っておく
• Project の root directory で OpenCode を立ち上げる
  • opencode
• その Project で初めて OpenCode を使う場合、その Project 特有の AGENTS.md を作る
  • /init
• Tab で（primary）Agent を切り替える
  • Build: 実際にファイルを作ったり編集したり出来る
  • Plan: ファイルを読むだけでファイルの編集・作成は行わない
• @ で操作対象のファイルを指定する
  • 補完が効きます
• / で OpenCode もしくは MCP サーバのコマンドを指定して実行する
  • 補完が効きます
  • MCP サーバのコマンドも指定できるのが、かなり強力です

補完が効くので、覚えておく事はほとんどありません。

OpenCode の Agent について

AI Agent を使う際に最も困ることは「最適な Prompt を覚えておかなければならない」とことだと思っています。これを解決するのが Agent 機能です。

• Prompt を Markdown で書いておくことによって、同様の処理を高精度で行うことが出来る
• 「もっとこうしたい」と思ったら、Markdown を書き換えれば良い
  • 一般的な Instruction と同じなので、チャッピーや Gemini に聞けば簡単に改善出来る

OpenCode では上記を複数のやり方で実現できます。

• Command
  • Prompt を OpenCode のコマンドとして実行する
  • 特定の Agent の下で使う
  • / で指定する
• primary Agent
  • 基本的な役割（振る舞い方）を指定する
  • OpenCode の Built-in Agent である Build や Plan を置き換えるもの
  • Prompt と共に、使用する LLM モデルや、実行する Linux コマンドの許可/拒否などを設定できる
  • Tab で切り替える
• subagent
  • primary Agent の下で、補助的な役割として設定する
  • 例えば同じ subagent でも、Build の下で動かすか Plan の下で動かすかによって、実際にファイルを変更するのか、ファイルを変更せずに dry-run するだけなのかを切り替えることが出来る
  • primary Agent とは別コンテキストで動作する
    • 個人的にこれは非常に鬱陶しい
  • @ で指定する
  • 例えば、Project や特定のファイルに関係ない指示や質問をする場合の @general など

Command はまさに「Prompt を繰り返し行いたい」という目的に完全一致するものですし、subagent と共に柔軟性が高くて良いですが、私のオススメは primary Agent です。

• 一旦設定してしまえば、かなり自動化できる
• / や @ は OpenCode コマンドやファイルの指定と被るので、紛らわしい
• 操作ミスがなくなる
  • 長い時間かけて考えたのに「あっ、Plan だった」ってことが無くなる

最初に思いつく AI Agent の使い道は「関数に docstring をつける」「Unit Test を書かせる」だと思います。私のそれぞれの設定は python_commend.md と python_test.md として公開しています。実際に使ってみて、かなり強力に動いています。

Tips

AI Agent に何もかもやらせようとすると不正確だったり処理が遅かったりするので、以下を Makefile に設定しておくと、かなり良い感じになります。
（もちろん ruff, mypy, black, isort の設定は pyproject.toml で行っておくことが前提として）

.PHONY: lint
lint:
	uvx mypy src/ tests/ --explicit-package-bases
	uvx ruff check src/ tests/

.PHONY: fix-lint
fix-lint:
	uvx ruff check --fix src/ tests/

.PHONY: format
format:
	uvx black src/ tests/
	uvx isort src/ tests/

MCP サーバについて

今や AI Agent にとって MCP (Model Context Protocol) サーバは必要不可欠のものとなっています。簡単に言うと以下の役割を提供するものです。

• LLM 単体では実現できない（実現し難い）機能を提供する
• 確実な処理や Context の圧縮を実現する
• ドメイン知識を持たない LLM にドメイン知識を埋め込むことも出来る

RAG や LLM 自体の Fine-Tuning と目的が被るところもありますが、私なりの整理は以下です。

• RAG（Retrieval-Augmented Generation）
  • ドメイン知識を格納した DB を AI Agent（LLM）の前段に立たせることによって、ユーザーのクエリ（質問）に似たドメイン知識を Prompt の中に埋め込み、LLM に few-shot Learning をさせることによって、LLM の回答にドメイン知識を埋め込むもの
  • 一般的に、ドメイン知識を頻繁に更新・追加する際に有効
  • 精度は DB の検索精度などに依存し、Context は逆に膨れ上がる
• LLM 自体の Fine-Tuning
  • LLM にドメイン知識を埋め込んだり（Task-Specific Fine-Tuning）、LLM の出力を望ましいように整える（Instruction Tuning）
  • 一般的に、ドメイン知識のデータが揃っており、ほとんど更新・追加されない場合に有効
  • 精度に関しては人手で評価したり、LLM-as-a-Judge で評価することが必要
• MCP サーバによる機能提供
  • 使う MCP サーバによって、ドメイン知識の追加に留まらない、様々な機能を提供することが可能
  • LLM を frontend に立たせた backend service の提供、とも言うことが出来る
  • RAG と Fine-Tuning の良いとこ取り…というのは過言か

オススメ MCP サーバ

opencode.json を見れば分かりますが、私が使っている MCP サーバは以下です。

• context7
  • Python の 3rd party library の仕様を参照するため
• serena
  • LSP として
  • OpenCode 自体に LSP と接続する機能はあるが、ファイルの読み書きなどにも使えるので、serena を使った方が良さげ
• gemini-mcp-tool
  • Web 検索として Gemini を使う際に、Gemini CLI への Bridge となるもの
• spec-workflow-mcp
  • SDD（Spec-Driven Development：仕様駆動開発）を行うためのツールとして
  • serena にも SDD を行うための機能は（一部）あるが、後述の理由によりspec-workflow-mcp を推す

Tips

設定の際に、MCP サーバの名前を適当に変更してしまうと上手く動かなくなることがあるようです。なので、以下の名前できちんと設定した方が無難です。

• context7: context7
• serena: serena
• gemini-mcp-tool: gemini-cli
  • リクエストが Timeout するなどしたら、gemini CLI で何か質問をして再度認証を通過させると動く事が多いです
• spec-workflow-mcp: spec-workflow

MCP サーバの使い方

使い方は、OpenCode にコマンドが登録されるものとされないもので大きく２つに分かれます。

• OpenCode にコマンドが登録されないもの
  • context7, serena
  • 基本的には AI Agent が勝手に判断して使ってくれる、はず
  • 明示的に使わせたい場合は、Prompt の最後に use context7 などを付け加える
    • 例）scikit-learn の train_test_split の使い方について教えて use context7
• OpenCode にコマンドが登録されるもの
  • gemini-mcp-tool, spec-workflow-mcp
  • / でコマンド一覧から補完されるので、使いたいものを選ぶ
    • 例）/gemini-cli:ask-gemini scikit-learn の train_test_split の使い方について教えて

SDD と spec-workflow-mcp の推しポイント

SDD については既に様々な解説記事があるので詳細は省略しますが、私は以下のように考えています。（spec-workflow-mcp にしかない機能も含まれているかも）

• 面倒くさい仕様書作成を全部 AI Agent がやってくれる
  • クライアントに見せることも出来る？
• 作成した機能についても仕様書を作ってくれるので、何をどのような目的で実装したのかが分かりやすい
  • アサイン変更の際にも役立つ
• 機能を実現するために、タスクへの分割・落とし込みをして、その記録を残してくれるので、進捗状況を把握しやすい
  • 要するに、Tech Lead が不要になり、個人でより大規模な開発も可能になる
    • 非常に素晴らしいポイントだと思う
    • Tech Lead を育てるための教育という役割も果たせると思う
• タスクの仕様を作るということは、すなわち AI Agent がコードを作成する際の Prompt を作るということなので、AI Agent の実装精度が向上する
  • AI がほぼ自動でプログラムを作る、という世界の実現に近い

この SDD を行うツールとして私は spec-workflow-mcp を推しているのですが、その理由は以下。

• 仕様書を作る方法が非常に明確
  • 詳細は後述
• Dashboard が付属しており、人間が納得するまで仕様書をブラッシュアップすることが出来る
  • 仕様書を作るための基本的なプロセス
    • AI Agent が仕様書を作り、人間に承認を求める
    • 人間が Dashboard で仕様書を確認し、全体的な指摘や個別の文章・単語の指摘（変更依頼）を付けて、AI Agent に修正依頼を出す
    • AI Agent が修正依頼に基づき改善して、修正したものに対して再び人間に承認を求める
    • （これを人間が納得するまで繰り返す）
    • 人間が納得したら、Dashboard で承認する
    • AI Agent が承認を受け取ったら、次のプロセスに進む
  • これは spec-workflow-mcp の最大のウリだと思う
• Dashboard にはカンバン機能があり、進捗が可視化できる
  • 本来ならば GitHub/GitLab issue を使うべきなんだろうけど、AI Agent がバンバン実装していくので、とりあえずはこれでも良いかと
  • 気が向いたら GitHub MCP Server や GitLab MCP Server を使った記事を書くかも

spec-workflow-mcp の使い方

spec-workflow-mcp が作る仕様書は以下の６種類です。

• Project 全体に関する仕様書（Steering Documents）
  • Product Steering Document
    • ファイルの場所：.spec_workflow/steering/product.md
    • プロジェクトの概要や目的を示す仕様書
    • README.md に相当
  • Tech Steering Document
    • ファイルの場所：.spec_workflow/steering/tech.md
    • どのような（3rd patry）Library を使うかなどを示す仕様書
    • requirements.txt に相当
  • Structure Steering Document
    • ファイルの場所：.spec_workflow/steering/structure.md
    • repository の中の directory 構成やコーディング規約を示す仕様書
    • pyproject.toml に相当
• 各機能に関する仕様書
  • Requirements Document
    • ファイルの場所：.spec_workflow/spec/<機能名>/requirements.md
    • 機能の具体的な目的や期待される入出力などを示す仕様書
  • Design Document
    • ファイルの場所：.spec_workflow/spec/<機能名>/design.md
    • 機能がどのようなモジュール（ファイル）に分割されて実装されるかを示す仕様書（Programming Design）
  • Tasks Document
    • ファイルの場所：.spec-workflow/spec/<機能名>/tasks.md
    • 機能の実装をタスクに落とし込んだ、各タスク（＝モジュール＝ファイル）に関する詳細な内容とそれを実現する Prompt を示す仕様書
    • 各タスクは Markdown の ToDo リスト形式になっており、これでカンバン機能を実現している

spec-workflow-mcp を使った仕様書の作り方

Prompt のサンプルはプロンプティングガイドにあります。覚えるのは面倒くさいので、Command を作っても良いかも。

• Steering Documents の作り方
  • 実行するタイミング
    • Project の開発を始める時
    • 開発の途中から spec-workflow-mcp を使い始める時
    • 開発が進んで今までの Steering Documents が古くなってきた時
  • OpenCode を立ち上げ、Agent を Plan にする
  • /spec-workflow:inject-steering-guide
    • Steering Documents の作り方を OpenCode に登録させる
      • OpenCode には todowrite や todoread といった Tool があるので、非常に OpenCode と相性が良い
  • Agent を Build にする
  • ステアリングドキュメントを日本語で作成して
    • 複数の仕様書を一気に作ったりもすることもある
    • ここで「日本語で」と付け加えれば、日本語で出力してくれる
    • /spec-workflow:create-steering-doc というコマンドもあるが、使わない方が無難
  • spec-workflow-mcp --dashboard で Dashbord を立ち上げる
    • OpenCode が立ち上げてくれることもある
  • Dashboard で確認し、コメントを付けて「修正を依頼」するか、「即時承認」する
  • OpenCode に「修正を依頼した」や「承認した」と伝える
  • ３つの仕様書に関して、作る・修正する・承認するを繰り返す
• 各機能に関する仕様書の作り方
  • OpenCode を立ち上げ、Agent を Plan にする
  • /spec-workflow:inject-spec-workflow-guide
  • Agent を Build にする
  • <機能の内容>の仕様を作成して
    • 機能の内容をなるべく詳しく書いてもいいけど、ふんわりとしたもので大丈夫
      • Dashboard で詳細を指摘して修正依頼するなど、後から修正する方法はある
    • /spec-workflow:create-spec というコマンドはあるが、使わない方が無難
  • 全部承認すると、いきなり実装し始める
• 各タスクの（途中からの）実装方法
  • OpenCode は Session を保存するので、前の Session を再利用すれば続きから始められるが、Context が長くなりすぎたので新しい Session で始めたくなったり、別の人がやっていたものを引き継ぐ場合
  • OpenCode を立ち上げ、Agent を Plan にする
  • /spec-workflow:spec-status <機能名>
  • Agent を Build にする
  • <機能名>のタスク<番号>を実装して
    • /spec-workflow:implement-task というコマンドはあるが、使わない方が無難

まとめ

現在進行系の Project に AI Agent を使って AI Coding を始めたい場合は、以下のプロセスになると思う。

1. pyproject.toml, README.md, Makefile, requirements.txt（requirements.in）等は既にあるものとする
2. comment Agent や test Agent を使って、コメントを書いたり UnitTest を作ったりする
   • 特に AI Coding をする場合は、既存の codebase を壊さないために UnitTest は超重要
3. spec-workflow-mcp を使って Steering Documents を作る
4. 追加したい機能の仕様を spec-workflow-mcp を使って作る
5. AI Agent にブンブン実装させながら、適宜 comment Agent にコメントを追加させたりしていく
   • UnitTest は普通に（自動的に）作るようになっているはず

新しく始める Project に AI Agent を使っていく場合。

1. コーディング規約（と見做すことが出来る）pyproject.toml を他の Project からパクってくる
   • Project 毎にコーディング規約を変える必要は無いだろう
   • Python のバージョンを上げる時などは、多少の変更が必要
2. 環境の設定方法・Format や Type check, Linting check のツールの利用方法を示している（ものと見做すことが出来る）Makefile を他の Project からパクってくる
   • Project 毎に（以下省略
3. README.md を（ほんのちょっと）頑張って書く
   • Project の目的
   • Project が提供する機能
4. spec-workflow-mcp で Steering Documents を作る
5. spec-workflow-mcp で各機能の仕様を作る
   • この際に <機能名> という名前で @README.md にある <機能名> の目的を実現する機能の仕様を作って 等とすれば、OpenCode 上で頑張って作文する必要が無いし、README と仕様の一貫性が保てる
6. ブンブン実装していく

ブンブン実装していきましょう。

TODO

• spec-workflow-mcp を使って実装する場合の、requirements.in の上手な管理方法
• GitHub/GitLab MCP Server を spec-workflow-mcp と連携させながら使う方法
• sandbox を提供する MCP Server を使った開発