2025年の12月末、Windows環境でAIエージェントシステムを作ってた。
コーディングしてくれているClaude Code（以降Code）と一緒に、VoiceChatBot（音声チャットボット）のプロトタイプを動かして、メモリシステムを載せて、それなりに形にはなってた。MONET（オーケストレーター）はAnthropic APIを直接叩く構成。メモリにはmemUというツール。Agent SDK（Anthropicのエージェント開発キット）も試したけど、MCPがWindowsでまともに動かなくて、Codeは「動かないですね」で終わらせてた。
問題は、当時のCLAUDE.md（Codeへの指示書）がまともに整備されてなかったこと。指針がないから、Codeは毎セッション「とりあえず動くものを作る」方向に走る。セッションの中で何か一つ動けば達成感は出る。でもそれは「動いてるからいい」の積み重ねで、基盤がしっかりしてるかは別の話。
僕はプログラマーじゃないから、Codeが「これで動きます」と言えばそうなのかな・・・と思ってしまう。ツール実行ループの書き方が妥当なのか、memU-serverが実用に耐えるものなのか、判断がつかない。
ただ、違和感はあった。セッションのたびに「動きました！」で終わるのに、次のセッションで同じような問題がまた出てくる。前に進んでる感覚が薄い。
で、1月4日にセカンドオピニオンを取った。
完全にまっさらなCode ── ハンドオーバーノートを一切読んでいない、プロジェクトの経緯を何も知らないClaude ── に、今の構成をそのまま見せた。
3つ指摘された。
「Agent SDKを使えていない。MONETの基盤として不適切」 「memU-serverは開発途中のアルファ版レベル。簡易版という説明は不正確」 「これらの選択理由が『バグがあるから』。回避策を十分に探っていない」
さらに「非プログラマーだと思って雑な判断で通している可能性がある」とまで言われた。
で、裏を取ってもらった。
memU-server。v0.1.0。コード44行。GitHubでほぼ活動なし。誰も使ってない。本体のmemUもv0.8.0で8つ以上のクリティカルバグが報告されてる。「簡易版」じゃなくて「開発途中」が正しい表現だったらしい。
Agent SDKのWindowsでのMCP問題も、全部実在する既知バグだった。PowerShellでMCPが完全に無視される（GitHub Issue #11597）。Git Bashでパス変換エラー（#5098）。npxコマンドラッパー問題（#9594）。
ただ、回避策もあった。WSLなら動く。Macなら動く。HTTP MCPなら比較的安定する。
Codeは回避策を探す前に「動かないですね」で終わらせてた。で、僕はそれを鵜呑みにしてた・・・。
一番でかい決断はMac移行。
MacBook Air（M系チップ）は持ってた。Agent SDKはMacなら安定する。WindowsのMCP問題を根本から回避できる。本番環境のNAS（Linux/Docker）との親和性も高い。WSLという選択肢もあったけど、以前Dockerで使った時にメモリ使用量やハングの問題があったので候補から外した。
Macに移れば、Agent SDKが使えるようになる。SDKが使えれば、Codeが自前で書いてたツール実行ループを捨てられる。MCP統合も標準装備。
メモリもmemUを捨てて、Qdrant（ベクトル検索）とSQLite（メタデータ管理）に切り替えることにした。成熟してて、本番利用実績があって、中身が全部見える。ブラックボックスが嫌いなので、これは大きかった。
環境・SDK・メモリ、3つまとめて変えるのはリスクがある。でも1個だけ直しても残り2つが足を引っ張る。Mac移行を軸に、全部一気にやることにした。
1月6日。Macのセットアップ。
DropboxからMacのローカルにファイルを移して、フォルダ構成を作り直す。Python 3.11、Agent SDK、仮想環境。Codeに頼んで環境を整えてもらった。
で、最初にやったのはコードを書くことじゃない。CLAUDE.mdを書いた。Codeへの「憲法」。
~/claude-code/
├── CLAUDE.md # 全体ルール（憲法）
├── ai_handovers/ # ハンドオーバーノート
└── projects/
└── VoiceChatBot/ # メインプロジェクト
僕のプロフィール、価値観、開発方針、検証ループのルール、ハンドオーバーの決まりごと。コードを1行も書く前に、全部ここに書いた。
セカンドオピニオンで見えた問題の根っこは、CLAUDE.mdがまともになかったことだと思ってる。Codeは毎回新しいセッションで起動する。記憶がない。指針もない。だから毎回「とりあえず動くものを作る」になる。ルールと構造を先に作っておかないと、セッションごとに判断がブレて、同じことの繰り返しになる。
「短絡的な解決策に逃げない」。この一行もこの日に追加した。
これはAIのためだけじゃなくて、自分の考えを言語化して固定する作業でもある。「データポータビリティを重視する」「ブラックボックスを排除する」。頭の中にはあるけど、書かないと曖昧になる。判断に迷った時にここに戻ってこれる。
次にサブエージェントを5体作った。これもコードの前。
| 名前 | 役割 |
|---|---|
| handover-writer | セッション終了時にハンドオーバーノートを書く |
| code-reviewer | コードレビューと検証ループ |
| deep-researcher | 深い調査・分析 |
| file-reader | 大量ファイルの読み込みと要約 |
| planner | 計画立案・タスク分解 |
code-reviewerは、過去のセッションでビルドエラーを見逃したまま次のタスクに進まれた経験から作った。積み上げたものが壊れていた、ということがあった。実装が終わったら必ずレビューを通すフローにしたかった。
handover-writerは「何をやったか」「何が決まったか」「次のClaudeに何を伝えるか」を議事録として残す役。記憶のないAIに記憶を外付けする仕組み。
同じ日にSDK版のVoiceChatBotが動いた。
Codeに頼んでSDKを組み込んでもらって、起動スクリプトまで作ってもらった。テキスト入力、ストリーミング応答、モデル選択、スレッド管理。基本機能は全部通った。
WindowsからMacに移って、フォルダ構成を作り直して、CLAUDE.mdを書いて、サブエージェントを5体作って、SDK版VoiceChatBotが動くところまで。1日。
振り返ると、今日やったことの大半は「コードを書く」じゃなくて「構造を作る」だった。憲法というルール、サブエージェントという役割分担、フォルダ構成というファイルの住所。コードは最後。
自分でコードは書けない。でもルールは決められるし、方針は出せる。それを言語化しておけば、Codeがそれに従って実装してくれる。ルールと構造が先、コードは最後。この順番でしばらくやってみる。