Claude CodeでArduino開発フローを構築する
朝比奈幸太郎リリース：音のアプリ使い放題プラットフォーム『空音開発』
こんにちは、朝比奈幸太郎です。
Claude codeでほとんどのことは自動化できるようになりました。
そこで、最近はネットの開発ばかりしていたので、やはりハードの方も考えていかないといけないということで、Arduinoを久しぶりに開いてみると、随分とバージョンが更新されており、急ぎ、Claudeと連携する方法をメモしておきたいと思います。
本稿で扱うのは、Claude Code を用いて M5Stack の開発フローをどこまで自動化できるかというところ。
わかってます。
サンプルコードとかそういうのはいらないんですよね。
どのディレクトリにプロジェクトフォルダを作るのか？自分で作るのか？任せるのか？
パスの伝え方や、最初のプロンプト・・・なんかで十分ですよね。
本稿で扱うのは、Claude Code を用いて M5Stack の開発を始める際の、最初の数分間の設計です。
サンプルコードや実装の詳細ではなく、プロジェクトフォルダをどこに作るか、それを人間が用意するのかエージェントに任せるのか、Claude Code にパスをどう伝えるのか、最初のプロンプトに何を書くべきか、という入口の手順に絞って整理します。
論点は三つ。
第一に、プロジェクトディレクトリの置き場所と作成主体の選択。
第二に、Claude Code に作業対象を認識させるための起動方法とパスの伝え方。
第三に、最初のプロンプトに含めるべき前提情報の範囲。
これらが決まれば、以降の工程はほぼ自動で進む領域に入ります。
プロジェクトフォルダはどこに作るか
ローカルユーザーディレクトリ配下に作るのが基本となります。
macOS なら ~/m5-projects/ のような専用の親ディレクトリを切り、その下に案件ごとのフォルダを並べる構成が扱いやすい範囲です。
Web 開発の ~/dev/ や ~/code/ と階層を分けておくと、Claude Code を複数セッション開いて並行作業する際に混線しません。
避けるべき置き場所は、iCloud Drive や OneDrive のような同期フォルダ配下です。
arduino-cli のビルド成果物が同期対象になるとビルドが遅くなり、ファイルロックの衝突も起きやすくなります。
Desktop や Documents も同様の理由で外しておく方が安全です。
ディレクトリ名は、プロジェクト名と .ino ファイル名を一致させる必要があるという arduino-cli の制約があるため、最初から確定させておきます。
たとえば時計プロジェクトなら ~/m5-projects/m5-clock/ というフォルダを用意し、後で m5-clock.ino を置く、という対応関係です。
自分で作るか、Claude Code に任せるか
結論として、空のフォルダだけは人間が mkdir で作り、その中身はすべて Claude Code に生成させる、という分業が最も摩擦が少ない範囲です。
人間が空フォルダを作る理由は、Claude Code を起動する際に「どのディレクトリで作業するか」を最初に確定させる必要があるためです。
エージェントにフォルダ作成から任せることも技術的には可能ですが、その場合は作業対象のディレクトリが定まる前に対話が始まるため、生成物がホームディレクトリ直下や予期しない場所に置かれる事故が起こり得ます。
フォルダの中身、すなわち sketch.yaml、secrets.h、.gitignore、CLAUDE.md、スケッチ本体は、すべて Claude Code に生成させて構いません。
人間が手で書く意味があるのは、生成された secrets.h に実際の Wi-Fi 認証情報を書き込む作業だけです。
認証情報の実値を会話に含めると履歴に残るため、ここだけはエディタで直接編集します。
既存プロジェクトを改変する場合は別で、対象ファイルが置かれたフォルダで Claude Code を起動する形になります。
新規ゼロからのプロジェクトと、既存資産を引き継ぐプロジェクトで、入口の所作が変わる点を意識しておく必要があります。
Claude Code へのパスの伝え方
Claude Code に作業対象を認識させる方法は二通りあります。
第一に、ターミナルで対象ディレクトリへ cd してから claude コマンドで起動する方法です。
エージェントは起動時のワーキングディレクトリをそのまま作業対象として扱うため、追加でパスを伝える必要がありません。
最も単純で、事故が少ない範囲です。
第二に、任意のディレクトリで起動した後に、対話の中で対象パスを伝える方法です。
この場合、最初のメッセージで絶対パスを明示します。
たとえば「これから /Users/kotaro/m5-projects/m5-clock で作業する」と書けば、エージェントはそのディレクトリを基準として動きます。
チルダ展開（~/ 表記）はシェルが解釈するもので、Claude Code との対話文中では絶対パスに展開された形を渡すほうが確実です。
複数の M5Stack 案件を並行する場合は、ターミナルのタブごとに別ディレクトリで claude を起動する運用が扱いやすい範囲です。
一つのセッションで複数プロジェクトを跨ぐと、エージェントの参照対象が混在する可能性があります。
最初のプロンプトに含めるべき情報
最初のプロンプトには、エージェントが推測ではなく事実に基づいて初期構成を組めるよう、次の四点を明示します。
ひとつ、対象機種と FQBN。M5Stack Core2 であれば m5stack:esp32:m5stack_core2 を直接書きます。機種同定はハードウェア固有の情報であり、人間が一次情報として持っている方が速い領域です。
ふたつ、接続中のシリアルポート名。
事前に arduino-cli board list を一度実行し、得られたポート名（/dev/cu.usbserial-XXXX など）をそのまま貼り付けます。
みっつ、採用するライブラリ方針。
Core2 単体なら M5Unified を使う、複数機種を混在させる予定があるか、といった指針を一行で示します。
よっつ、作りたい機能の要件。
例えば時計を作るなら「Wi-Fi で NTP から時刻を取得して JST で LCD に表示する時計」というレベルで十分です。
実装の細部は初期案を見てから調整する形が無駄が少ない範囲です。
加えて、生成してほしいファイル群（sketch.yaml、secrets.h、.gitignore、CLAUDE.md、スケッチ本体）と、最後に arduino-cli compile でビルド確認まで走らせてほしい、という指示を添えます。
secrets.h は .gitignore で除外する旨も最初のプロンプトに含めると、初回コミット時の認証情報混入を防げます。
これらを満たす最初のプロンプトは、おおむね 5 行から 10 行程度の自然文に収まる分量となります。
粒度としては「機種、ポート、ライブラリ方針、要件、生成してほしい物、ビルド確認まで走らせる」が一通り書かれていれば十分で、これ以上書き込むとエージェントの初期判断を不必要に縛ることになります。
初回起動後にエージェントが行うこと
最初のプロンプトを送ると、Claude Code は次の流れで自律的に動き出します。
プロジェクトファイル群を順に生成し、必要なら arduino-cli core list や arduino-cli lib list を実行して環境を確認し、ビルドコマンドを実行する、という反復です。
コンパイルエラーが出ればログを読んで該当箇所を修正し、再ビルドに入ります。
人間がここで介入する必要はほとんどありません。
エージェントが一時停止して確認を求めてくる場面、たとえば未インストールのライブラリを入れてよいか、.gitignore の内容に追加してよいか、といった問いに「はい」「進めて」と返す程度で、初期構成は完成します。
エージェントの動きがいったん止まるのは、ビルドが通り、書き込みフェーズに入る直前です。
ここから先は、人間が secrets.h に実値を書き、M5Stack を USB 接続し、書き込み指示を返す、という人間側の作業に切り替わります。
CLAUDE.md は事前に書くか、生成させるか
CLAUDE.md を人間が先に書いてからエージェントに渡すべきか、エージェントに生成させるべきか、という論点があります。
新規プロジェクトでは後者で十分な範囲です。
最初のプロンプトに含めた前提情報（機種、FQBN、ポート、ライブラリ方針）をそのまま CLAUDE.md の骨子としてエージェントに書かせれば、以降のセッションで同じプロジェクトに戻ってきたときの参照ドキュメントとして機能します。
人間が手で書き足すべき内容は、プロジェクトを進めていく中で蓄積される運用上の知見、たとえば書き込み時に必要となる物理操作の癖、特定のライブラリ組み合わせで起きるエラーと対処、といった、エージェントが事前には知らない情報です。
CLAUDE.md は初期に完成させるドキュメントではなく、開発の進行とともに育てていくログに近い性格を持つ、と整理しておくのが現実的です。
二回目以降のプロジェクト
時計が動いた後、同じ M5Stack Core2 で別のスケッチを作る場合は、新しい空フォルダを切ってその中で claude を起動し、最初のプロンプトを送る、という同じ手順を繰り返します。
繰り返しを軽くするために、~/m5-projects/_template/ のようなテンプレートディレクトリを一つ用意しておき、そこから sketch.yaml、.gitignore、CLAUDE.md の雛形をコピーする運用も選択肢になります。
テンプレートを使うと、最初のプロンプトは「_template/ からコピーして、機能要件はこう」というレベルまで短縮できます。
ただしテンプレートが古くなるとそれ自体が負債になるため、案件が三つ四つと増えてからテンプレート化を検討する、という順序が無駄が少ない範囲です。
まとめ
M5Stack 開発を Claude Code で始める際に、人間が担うのは三つだけです。
プロジェクトを置く空フォルダを ~/m5-projects/案件名/ の形で作ること。
そのフォルダで Claude Code を起動すること。
最初のプロンプトに、機種・FQBN・ポート・ライブラリ方針・機能要件を書き、必要なファイル群の生成とビルド確認まで指示すること。
ここまでが整えば、sketch.yaml、secrets.h、.gitignore、CLAUDE.md、スケッチ本体の生成、ライブラリ導入、コンパイルエラーの修正までは、人間の介入をほとんど必要としない範囲で進みます。
人間に戻ってくるのは、secrets.h への実値の書き込み、M5Stack の USB 接続、書き込み許可の返答、そして実機上での目視確認だけです。
入口の設計、すなわちどこにフォルダを置き、どのパスで起動し、最初に何を伝えるかという数分間の判断が、その後の開発フローの摩擦の大半を決めます。
なんというか、けしからん時代であります。
出典・参照情報
- Arduino 公式 arduino-cli ドキュメント：https://arduino.github.io/arduino-cli/
- Arduino sketch project file（sketch.yaml）仕様：https://arduino.github.io/arduino-cli/latest/sketch-project-file/
- M5Stack 公式 Arduino IDE 環境構築ドキュメント：https://docs.m5stack.com/en/arduino/arduino_ide
- M5Unified GitHub リポジトリ：https://github.com/m5stack/M5Unified
- Anthropic Claude Code ドキュメント：https://docs.claude.com/