Tips on ROBOCO

エージェンティックコーディング推奨事項の解説

Tue, 17 Jun 2025 13:38:18 +0900

チョン・ドヒョン - ROBOCO首席コンサルタント

この記事は、Armin Ronacherのブログ記事「Agentic Coding Recommendations」（エージェンティックコーディング推奨事項）をもとに執筆しました。

序文

数日前、開発者コミュニティGeek Newsでアルミン・ロナハー（Armin Ronacher）のブログ記事「Agentic Coding Recommendations」（エージェンティックコーディング推奨事項）に触れ、少なからぬ衝撃を受けました。記事の著者であるArminはもともとFlaskウェブフレームワークの創始者として有名ですが、彼のバイブコーディングに関する洞察が、Robocoの目指す方向とも重なっていたからです。今回の記事では、Claude Code、Cursor、Windsurfといったツールに触れ始めたばかりのバイブコーディング入門者に向けて、Arminの記事に込められた核心をわかりやすく解きほぐしてお伝えします。

TL;DR

エージェンティックコーディングとは、AIエージェントに目標を任せ、開発者が結果と方向性を検討する進め方です。
単純な言語、高速なツール、明確なログ、保守的な依存関係管理が、エージェントのミスを減らします。
AIがコードを多く書く環境であるほど、開発者は単純性、安定性、適切なリファクタリングのタイミングをより意識する必要があります。

エージェンティックコーディングとは何か

Arminの言うエージェンティックコーディング（Agentic Coding）とは、コーディング作業の多くの部分をAIエージェントに委任する開発手法です。ここでのエージェントとは、開発者の指示を受けて自ら作業を遂行する自律プログラムを意味します。ここでは人のようにコーディング業務を手伝ってくれるAIプログラムを指し、ファイル編集、コマンド実行、ウェブ検索など、開発に関わる作業を代理人（agent）のように処理します。

一般的なAIコーディングアシスタント（例：GitHub Copilotの自動補完、ChatGPTを用いたコード生成）よりさらに一歩進んで、エージェントに一つの作業目標を割り当てると、そのエージェントが自ら必要な一連の作業を遂行するというものです。

エージェンティックコーディングは、アンドレイ・カルパシー（Andrej Karpathy）によってバイブコーディングという用語が提案されるまで、AI主導の開発を指す最有力の用語であり、現在もバイブコーディングという用語と並んで多く使われています。この記事では原著者の意志を尊重し、バイブコーディングという用語の代わりにエージェンティックコーディングで用語を統一します。

わかりやすく言えば、人間の開発者が「プロジェクトXのバグを直して」と自然言語で指示すると、エージェントがそのコードベースを把握し、コードを修正し、テストを実行して結果まで出してくれるという流れです。この過程で開発者は細かなステップごとに介入せず、結果が出るまで待つのが特徴です。

このアプローチでは、これまで私たちが使ってきたIDE（統合開発環境）の役割も大きく縮小します。Arminの場合はエージェントがコーディングの大部分を処理するため、彼は最後の仕上げ程度をテキストエディタ（Vimのようなツール）で行っています。それほどまでにエージェントが主導的にコーディング過程を担うのが、エージェンティックコーディングの姿です。

では、なぜエージェンティックコーディングが必要なのでしょうか。まず、うまく活用すれば開発生産性を飛躍的に高められるからです。人間の開発者が多くの時間を費やす反復作業（例：コードのリファクタリング、複数ファイルにまたがる修正、長い文書やコードベースの把握）をエージェントが代わりに行ってくれれば、開発者はより創造的で重要な問題に集中できます。実際にArminは「エージェントを開発プロセスに統合すれば、相当な生産性向上が得られる」と強調しています。またこうした方法は、急速に発展中のAI技術の最新の可能性を開発に取り込む道でもあります。

最後に、エージェンティックコーディングは単に「コードをより速く書くこと」にとどまりません。究極的には、より高い品質のコードを書き、保守性と安定性を高めることを目標としています。Arminは、数か月前まではひどかったAIのコード出力が今ではかなり改善されたとしたうえで、今後も発展を重ねていくだろうと述べています。したがって、この記事の後半で見ていくClaude Codeのようなツールをうまく活用すれば、初心者の開発者も次第に「AIエージェントと協業する開発者」へと成長していけるでしょう。

Arminが提案するエージェンティックコーディングの核心原則

Armin Ronacherは自身の記事の中で、エージェンティックコーディングを効果的に活用するための助言を数多く示しています。プログラミングの基礎程度を知る読者にも理解できるよう、彼の主な推奨事項を一つずつ解きほぐして説明します。

単純で安定した言語の選択：エージェントが扱う言語を選べるのであれば、可能な限り単純な言語を選ぶようArminは勧めています。彼は新しいバックエンドプロジェクトの場合にGo言語を強く推奨しましたが、その理由は明確です。Goは文法が単純で予測可能なため、エージェント（LLM）がミスをする余地が少なく、テストの実行も自動で一度にうまく動作するからです。たとえばGoではgo testコマンドで必要なテストを一度にまとめて回せます。エージェントがテスト対象の選定で混乱することがありません。またGoのエコシステムは変化が遅く後方互換性が良いため、AIが古い例示コードを生成する危険が小さいのです。一方、Pythonのようにマジック（magic）の多い動的言語では、エージェントが隠れた挙動を誤解したり、実行環境の問題で試行錯誤しやすいといいます。したがって、言語自体が単純で環境の変化が少ないほど、エージェントはより安定してコードを扱えます。
エージェントに優しい開発ツールの設定：言語と同じくらい、開発ツール（tool）をどう整えるかも重要です。Arminの助言は「ツールは何でも構わないが、必ず速く明確に動作しなければならない」というものです。エージェントは皆さんの環境でbashコマンド、ビルドツール、テストランナーなどを実行することになりますが、反応が遅かったり出力が不必要に冗長なツールは避けるべきです。たとえばArminは自身のプロジェクトでMakefileを活用し、よく使うコマンドを整理しています。make devで開発サーバーを立ち上げ、make tail-logでログを見るという具合です。重要なのは、エージェントがこうしたツールを使う際にエラーが出たら即座に知らせ（logging）、重複実行を防ぐといった保護の仕組みも必要だという点です。実例として、Arminはプロセス管理ツールを修正し、すでにサーバーが実行中であれば二度目を立ち上げられないようにし、その代わり「すでに実行中」というエラーを明確に出力するようにしました。おかげでエージェントはmake devを実行したときにサーバーがすでに動いているかを判断し、すぐにログを確認する次のステップへ進むことができました。

そしてログ（logging）そのものをエージェンティックコーディングの核心的なツールとして活用するよう、Arminは繰り返し強調しています。たとえば会員登録時に認証メールを実際に送る代わりに、開発モードではメールの内容をコンソールログに出力しておけば、エージェントがそのログを読んで認証リンクを自動的に見つけてクリックできます。Arminは自身のCLAUDE.md設定ファイルに「デバッグモードではメールがログに出力される」という情報を入れておき、Claudeエージェントはそれを参照して、実際に会員登録から認証までを自ら完了させました。このように、明確なログと親切なツールの出力はエージェントの目と耳になってくれます。私たちが開発するときにコンソールやログを見ながら問題を把握するのと同じく、エージェントもログを通じて状況を理解し、次の行動を決めるからです。

速度と効率の最適化：エージェンティックコーディングのボトルネックは、主にAIモデルの推論コストと非効率なツールの使用から生じます。したがって応答速度を上げ、不要なトークンの浪費を減らすことが重要です。上で述べたとおりツールの迅速な実行が基本であり、さらにエージェントが新たに書いて実行するコード（「emergent tool」）もできる限り軽く作るべきです。たとえば、エージェントがある作業のために一時的なPythonスクリプトを書いて回すとしましょう。このときそのスクリプトの実行に5秒かかり、実行のたびに初期化で1分ずつ消費するとすれば、全体の流れは大きく遅くなります。Arminは実際の業務プロジェクト（Sentry）で、エージェントがコードをリロードするのに時間がかかりすぎたため、一時的に「ファイルの変更を検知して自動的にモジュールをimportし、結果をログに書く」デーモンを作り、エージェントに活用させたといいます。複雑な再起動なしに素早くコードを注入して実行結果だけを確認させたわけです。このような創造的な方法で、できる限りリアルタイムに近いフィードバックを返すよう環境をチューニングすれば、エージェントの作業効率は上がります。またログもあまり冗長だとトークンを食い速度を落とすので、重要な情報だけを含むよう適切な水準に調節するのがよいと助言しています。
安定性と最小驚きの原則：Arminは「安定したエコシステム」の価値を繰り返し言及します。AIがコードベースを扱うとき、外部の変化が少ない環境でははるかにミスが減ります。たとえばLLMエージェントはGoやFlaskのような長く検証された技術スタックを好みます。逆に、依存関係が激しく変わるJavaScriptエコシステムのように、毎日新しいバージョンとライブラリが押し寄せる環境では、AIが数日前のコードを参照して誤ったコードを生成する危険が高くなります。またエージェントは、コードを書きながら決定した理由をコメントとして残すなど、自分なりの痕跡（breadcrumb）を残す傾向がありますが、私たちが何気なく依存ライブラリを最新バージョンに上げてしまうと、そうしたコメントやコードパターンはたちまち古いものになり、AIの思考の流れに混乱を与えかねません。人間も同じですが、AIは「どうせテストが通ればいいのでは」という気持ちで手軽にアップグレードを試みることがあるので、特に注意が必要です。Arminの助言を一言で言えば「以前よりもさらに保守的にアップグレードせよ」ということです。そして新しいライブラリをあまり使わず、可能なら直接コードで実装するほうがよいとも述べています。どうせエージェントが素早くコードを作ってくれるのだから、複雑な依存関係を持ち込む代わりに必要な機能は自分で書き、一貫性と予測可能性を保てという意味です。実際にArminは「なぜ自分でコードを書くべきか」という題の記事を以前書いており、エージェンティックコーディングをやってみてその考えがより確固たるものになったといいます。
コードは可能な限り単純に：「複雑なコードはエージェント環境で性能が出ない。最も愚かに見えるが動く解決策を選べ」——Arminが強調した一文です。エージェントがコードを扱うときは明瞭さが最優先です。したがって開発者は普段よりもさらに直截的で単純なコードスタイルを追求すべきです。たとえば複雑なクラス継承よりも、長く具体的な名前の関数を複数作るほうが理解しやすくなります。あまりに抽象的なパターンやマジック（マジックナンバー、リフレクションなど）を乱発すると、AIは文脈を見失いやすくなります。Arminは「普通のSQLクエリを直接書け」とまで助言します。ORMなどを通じて間接的にデータベースを扱うより、いっそエージェントにSQLを書かせたほうが、AIがログのSQL出力と自分のコードをすぐに対応づけてデバッグしやすくなります。また権限チェックのような重要なロジックは、可能な限り当該コードの近くに置くべきです。もし権限検査が設定ファイルやデコレータに隠れていると、エージェントが新しい機能を追加する際にその部分を見落とし、セキュリティホールを作るおそれがあります。結局、「単純明瞭で一貫したコード」がエージェントにも人間にも良いコードだ、ということです。
並列化（Parallelization）を念頭に置く：エージェント一つでは非常に速いわけではありませんが、複数を同時に走らせれば作業を並列処理して効率を高められます。たとえば数百個のファイルのlintエラーを一度に直さなければならない場合、一つのエージェントが順番に処理する代わりに、複数のエージェントにそれぞれ一部のファイルを任せるという具合です。そのためには、共有資源（ファイルシステム、DBなど）の衝突を最小化できるようプロジェクトを構成する必要があります。簡単なことではありませんが、ArminはDockerを用いた隔離実行ツールや、CI（継続的インテグレーション）環境でバックグラウンドエージェントを走らせるなど、初期の試みが出てきていると紹介しています。現在は自身のワークフローに完全には適用できていないものの、まもなく急速に発展する分野だと見通しており、遠からず実用化される可能性があります。
適時にリファクタリングする：エージェンティックコーディング環境では、リファクタリング（refactoring）のタイミングが重要です。エージェントは一定の水準までは、そこそこの複雑さのコードでも問題なく処理します。しかしプロジェクトの規模と複雑度が限界点を超えると、エージェントの文脈維持能力にも限界が来ます。Arminはたとえば「序盤はフロントエンドにTailwind CSSのクラスをあちこちに書き散らしながらエージェントと素早く開発を進められるが、ファイル50個にスタイルが散らばった時点で、もうコンポーネントライブラリへ構造を再編するときだ」と述べています。それほどコードベースが膨大になると、エージェントも一貫した修正が難しくなり、大きな修正時にバグが続出しかねません。したがって、早すぎるリファクタリングで初期の速度を殺す必要はありませんが、遅らせすぎると、エージェントにも収拾がつかなくなる時点が来るということです。人であれAIであれ、適切な時点でコード構造を整理してやることは保守に不可欠です。エージェンティックコーディングをしていると、エージェントが新しい関数やファイルをすらすら追加してくれるため、あるタイミングでは開発者が乗り出して重複コードをまとめ、モジュール化するといった大掃除をしてやってこそ、その後の作業が楽になります。

これらの原則は、Arminが「今後技術が変わっても有効な本質的な概念」と強調した部分です。実際のツールや技法は速く進化していくでしょうが、単純性、安定性、観測可能性（ログなど）、賢い並列化といった原則は、今後もエージェンティックコーディングの成否を分ける要素だという意味です。私たちRobocoチームもこうした洞察に深く共感しており、AIとともにあるコーディング文化が健全に定着するためには、上記のようなソフトウェア工学の基本原則がいっそう重要になると信じています。

Claude Code活用の実践例

ここからは、Anthropic社のClaude Codeというツールを通じて、上で述べたエージェンティックコーディングが実際にどのように行われるのかを見ていきます。Claude CodeはArminが主に使用するコマンドライン基盤のAIコーディングエージェントで、プロジェクトディレクトリでターミナルコマンド（claude）から実行します。このエージェントはコードベースを理解してファイルを編集し、テストやビルドのコマンドを直接実行できます。またGitと統合されており、gitの履歴検索やコミット、PR作成まで手伝ってくれる強力なツールです。以下にClaude Codeを活用したいくつかの状況別の例を紹介します。

コードリファクタリングの例

たとえば、processData()という関数の性能問題を改善したいとしましょう。普段であれば開発者がその関数を開いてロジックを修正し、関連する部分の動作を検証する必要があります。Claude Codeを使えば、こうしたリファクタリング作業をかなりの部分まで自動化できます。開発者は自然言語で簡単に指示します。

processData()関数をリファクタリングして、すべてのデータを一度にロードする代わりにストリーミングを使うように変更して。

プロンプトを入力すると、Claude Codeエージェントが自らprocessData関数のあるファイルを開いてコードの修正を始めます。たとえば、一度にすべてのデータをメモリに載せていた部分をストリーミング方式に変更し、必要であれば関連する関数のシグネチャも修正するでしょう。Claude Codeは修正後、自動的にプロジェクトのテストを実行し、リファクタリングが既存の機能を壊していないかを確認します。もしテストで失敗が発生すれば、エージェントが原因を分析してコードをさらに修正することもあります。すべてのテストが通れば、Claude Codeは開発者に「リファクタリング完了、メモリ使用が大きく減りました。既存のテストもすべて通りました」といった要約結果を見せてくれるでしょう。開発者はこの変更内容（diff）を確認し、満足できればそのままコミットすることもできます。

文書要約の例

エージェントはコーディングだけでなく、文書の理解や要約の作業にも役立ちます。プロジェクトに新しい開発者が加わったと仮定してみましょう。この開発者がARCHITECTURE.mdという設計文書を素早く把握しなければならないとき、Claude Codeに要約を頼むことができます。

docs/ARCHITECTURE.mdの内容を3行で要約して

Claude Codeは該当のマークダウン文書を読み、核心的な内容を抜き出して要約してくれます。たとえば次のような結果を出力してくれるでしょう。

- このプロジェクトはクライアント・サーバーアーキテクチャで構成されており、サーバーはREST APIを提供する。
- ユーザー認証と権限管理のためのモジュールが含まれており、役割に応じて機能へのアクセスが制限される。
- 拡張性のためにメッセージキューとキャッシュを導入し、今後増加するトラフィックにも対応できるよう設計されている。

要約されたポイントを通じて、新しく来た開発者は短時間でシステムの構造を理解できます。このようにClaude Codeは、プロジェクトのコードだけでなく関連文書まで文脈を把握して、質問に答えたり要約したりするのに活用できます。膨大なコードベースの中で特定の機能がどこに実装されているかを尋ねたり、設定ファイルの役割を尋ねたりと、コードQ&Aアシスタントとして使うこともできます。

AIでアーキテクチャ図を描く

Sat, 14 Jun 2025 12:35:06 +0900

チョン・ドヒョン - ROBOCO首席コンサルタント

バイブコーディングをするとき、人はしばしばコードさえあれば十分だと考えがちです。しかし現実は違います。文書化のないコードは、地図を持たずに出かける旅のようなものです。目的地がどこなのか、道のりがどうなっているのかが分からなければ、誰も一緒に来てはくれません。バイブコーディングにおいて文書化が特に重要なのは、コードが単に動作するためのものではなく、アイデアと設計の意図を他の人に正確に共有するためのものだからです。文書化は協働を滑らかにし、プロジェクトの方向性を明確にし、ひいては持続可能な開発環境を築く土台になります。

私は文書化の作業をコードと一緒に管理する方式を強くおすすめします。特にMarkdownとmermaidを使えば、シンプルで明確な図をすばやく作成できます。複雑な構造や流れを長い言葉の代わりに図ひとつで表せるので、意思疎通がはるかに効果的になります。

もちろん、mermaidだけでは足りないこともあります。より精緻で複雑な図が必要なときは、draw.ioを使うことができます。draw.ioはXMLベースの.drawioというファイル形式を使うため、AIにこの形式で図を生成するよう指示すれば比較的簡単に作業できます。ただし、AWSアイコンのような特定のアイコンのIDは公開されていないので、AIがそのまま活用するのは容易ではありません。

そこで私は、draw.ioクライアントからAWSアーキテクチャアイコンのIDを直接抽出し、別途文書化しました。これによってAIにアイコンIDを教え、望むアイコンを正確に活用できるようにしたわけです。この文書は、次のGitHubリポジトリで実際に作業した例を通して確認できます。

TL;DR

バイブコーディングにおいて文書化は選択肢ではなく、設計意図と協働の文脈を共有するための中核的な作業です。
単純な構造ならMarkdownとmermaidで十分ですが、より精緻なアーキテクチャ図はdraw.ioファイルをAIと一緒に生成できます。
AWSアイコンのようにAIが知りにくい細かなIDは、別文書として与えれば望みどおりの図をより正確に作れます。

ECS - Fargate Fast Scaleout

このようにして生成された図は、VS Codeのdrawio関連の拡張機能を使えば手軽にプレビューしたり修正したりできます。また、draw.ioクライアントをインストールすると一緒に提供されるCLIツールで、簡単にSVGやPNG形式の画像に変換して文書へ挿入することもできます。

一方で、最近のmermaidの最新バージョンでは、AWSアイコンをはじめとするさまざまなアーキテクチャアイコンが標準でサポートされ始めました。公式ドキュメントを参照すればすぐに活用できます。ただし、GitHubではまだこの最新機能がサポートされていないため、先ほど説明した方法が当面は最も有用なアプローチになるでしょう。

良い文書は単なる説明書にとどまらず、協働の質を高め、長期的にプロジェクトの価値を持続させます。バイブコーディングにおいて文書化は選択ではなく必須です。

バイブコーディングでは韓国語より英語のほうがうまく動作するのか？

Fri, 04 Apr 2025 08:12:04 +0900

チョン・ドヒョン - ROBOCO首席コンサルタント

バイブコーディング（Vibe Coding）、つまりGPTのような大規模言語モデル（LLM）を使って開発する方式について、よく聞かれる質問が一つあります。「このモデルと韓国語で対話するときと英語で対話するときとで、作業の品質に違いはあるのか？」という点です。結論から言えば、私の経験からも、LLMの動作原理から見ても、言語そのものによって作業の質が変わることはありません。

TL;DR

韓国語と英語のどちらがより良い結果を出すかよりも重要なのは、トークン効率です。
韓国語は同じ内容を伝えるのにより多くのトークンを使うことがあり、コスト、速度、そして渡せるコンテキストの量に影響を与えかねません。
大規模プロジェクトやルールファイルのように繰り返し入力されるドキュメントは、英語で簡潔に管理する戦略を検討する価値があります。

まず原理を簡単に見ておきましょう。LLMは入力されたテキストをトークン（token）という単位に分割し、それらのトークンをもとに次の内容を予測しながら作業を実行します。英語は一般に単語または単語の一部が一つのトークンに分割されますが、韓国語は音節や形態素の単位でより細かく分割されます。

たとえば「Hello」は通常1つのトークンが使われますが、「안녕하세요」はLLMサービスの内部動作によって差はあるものの、「안」「녕」「하세요」のように複数のトークンに分割される可能性が高いのです。

とはいえ、これが作業の品質に影響を与えるとは考えにくいでしょう。結局のところLLMは、入力された内容を理解し文脈を把握する過程で、言語の違いをかなりうまく乗り越えるからです。

しかし、注目すべき点は別にあります。それがトークン使用量です。英語は比較的簡潔にトークンが消費される一方、韓国語は同じ内容を伝えるのにもより多くのトークンを必要とします。これは単なるコストの問題にとどまらず、プロンプトの処理速度や、渡せるコンテキスト全体の大きさにも影響します。

特にバイブコーディング環境で使う.cursorrules（Cursor）、.windsurfrules（Windsurf）、CLAUDE.md（Claude Code）のようなルールファイルは、モデルとやり取りするたびに繰り返し入力されるため、これらのルールを最適化することが非常に重要になります。言語を選ぶという問題は、ここで実質的な意味を持ちます。ルールやドキュメントをより簡潔な言語で整理すれば、不要なトークン消費を減らし、より多くのコンテキストを渡せるようになります。

ほとんどの開発作業では、実のところ韓国語で進めたからといって大きな問題が生じることはありません。しかし大規模プロジェクトや複雑なコンテキストを扱わなければならない場合であれば、英語の使用を一度検討してみるのも良いアプローチになりえます。トークン使用を最小化しながら、より速く効率的なバイブコーディング環境を構築できるからです。

結局、韓国語と英語のどちらがより「うまく」動作するのかという問いの本質は、作業の品質ではなく効率性の問題として捉えるべきです。コストと速度、効率的なコンテキスト管理が必要な状況であれば、英語でプロンプトとルールを書く戦略が賢明な選択となるでしょう。