武井でございます。 ちゃんとした DSP（デジタル信号処理の機材）を買おうとすると、数万円から10万円近くします。DSP とは、スピーカーの音を補正したり、エフェクトをかけたりする機材です。イコライザーやコンプレッサーなどが入っていて、ライブハウスやスタジオでは定番の装備です。昔のラジカセにも簡易的なのついていましたよね、高音域とか低音域とか調整するグライコって呼ばれていたやつ。ドンドンって重低音響かせることの出来るアレです。DSPはそれのもっとすごいやつです。 それが、 ラズパイと数千円のオーディオインターフェース、無料のアプリだけ で作れてしまう。アンプまで込みで 約2万円 です。 しかも音の調整は、自分では1つも数値を考えていない。AI に「こもってるからすっきりさせて」と日本語でお願いして、出てきた テキストをインポートしただけ 。 気に入らなければ「もうちょい低音控えめで」と言えば、作り直してくれる。 控えめにいって最高です。 まずは実物を見てください。     DSP まわりをアップにすると、こんな感じです。 ※ 上がタッチディスプレイに映した Easy Effects、手前左が Raspberry Pi 5、真ん中の黒い箱がアンプ（FX-AUDIO FX202A/FX36A PRO）、右の銀色の箱が UCA222 です。 なぜ作ったのか スピーカーの音を補正したいとき、定番なのが DSP です。イコライザーで帯域ごとに音量を整えたり、エフェクトをかけたりできます。 ただ、これがマジで高い。 そのうえ、買ったあとも問題があります。 イコライザーをどういじればいいのか、正直よくわからない 。何 Hz を何 dB 削ればいいのか、聞いてもピンとこないわけです。専用ソフトの画面でバンドを1本ずつ動かして、耳で確かめて……を延々と繰り返すことになります。 そこで考えました。 DSP は、 Raspberry Pi 5 + Easy Effects にやらせればいい。Easy Effects は無料のオープンソースなのに、イコライザー、コンプレッサー、ノイズ除去まで入っている Easy Effects のイコライザーは、 設定をテキストファイルでインポートできる 。ということは、そのテキストを AI に書かせればいい つまり、 機材は格安、音作りは AI に日本語でおまかせ 。これが今回の凄みです。 というわけで作ったのが、この環境です。 全体像 音の流れはこうなっています。 Android タブレット のイヤホン端子から、3.5mm → RCA の変換ケーブルで UCA222 に入れる UCA222 がアナログ音声をデジタルに変換（ADC）して、USB でラズパイへ送る Raspberry Pi 5 の Easy Effects がエフェクトをかける 処理済みの音を USB で UCA222 に戻し、UCA222 がアナログに戻す（DAC） UCA222 から RCA で ミキサー → アンプ → スピーカー ポイントは、 UCA222 1台で入口（ADC）と出口（DAC）の両方をまかなっている ところです。USB ケーブルも1本で済みます。地味にえらい。 使った機材 ※ Raspberry Pi 5 の 2GB モデルが 2024年8月に発売されたときの、スイッチサイエンスでの税込価格です。メモリ価格の高騰で、その後は値上がりしています。Easy Effects のメモリ使用量は約 350MB だったので、2GB でも足りる見込みです。 ソフトウェア 注意 ：Easy Effects は 8.x で画面が作り直されています（GTK 版 → Qt 版）。7.x 以前の解説記事とはボタンの位置や設定ファイルの保存先が違うので、バージョンを確認してから読んでください。 Easy Effects：Linux の音にエフェクトをかけるアプリ Easy Effects は、Linux のサウンドサーバー PipeWire の上で動くエフェクトアプリです。イコライザー、コンプレッサー、ノイズ除去など、ひととおりのエフェクトがそろっています。 画面は2つに分かれています。 Output（出力側） ：PC で再生している音（YouTube や音楽アプリなど）にエフェクトをかける Input（入力側） ：マイクから入ってきた音にエフェクトをかける 今回はタブレットの音を UCA222 から「入力」としてラズパイに入れるので、 Input のほうを使います。 Listen to Mic：トグル1つで入力をスピーカーへ ここが今回いちばんのキモです。 Easy Effects の Input は、本来マイクの音を加工して、録音アプリや通話アプリに渡すための機能です。つまり そのままでは、加工した音はスピーカーから出てきません 。 ふつうは PipeWire の loopback 設定を書いたり、配線ツールでつないだりするところです。でも Easy Effects には 「Listen to Mic」 というトグルがあって、これを ON にするだけで、加工後の音が出力デバイスに直接流れます。 UCA222 入力 → Equalizer → Crystalizer → Exciter（今はバイパス） → Easy Effects Source（仮想マイク） → UCA222 出力 設定ファイルも配線ツールも不要。トグル1つです。 画面右下のマイクのボタンがそれです（後述）。 構築手順 1. OS を用意する Raspberry Pi Imager で Raspberry Pi OS（64-bit、デスクトップあり） を microSD に書き込んで、初期設定まで済ませます。今の Raspberry Pi OS は最初から PipeWire で音を扱っているので、サウンドまわりの追加設定はいりません。 2. Easy Effects をインストールする Flatpak 版を使います。残っていた7行の履歴は、ほぼこれでした。 # Flatpak 本体をインストール sudo apt install flatpak # Flathub（Flatpak のアプリ配布元）を登録 sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo # Easy Effects をインストール sudo flatpak install flathub com.github.wwmm.easyeffects # 再起動（アプリメニューに Easy Effects が出てくるようになる） sudo reboot 3. 機材をつなぐ 全体像の図のとおりに配線します。 UCA222 をラズパイの USB ポートにつなぐ タブレットのイヤホン端子 → 3.5mm-RCA 変換ケーブル → UCA222 の INPUT UCA222 の OUTPUT → RCA ケーブル → ミキサー ミキサー → アンプ → スピーカー UCA222 が認識されているかは、次のコマンドで確認できます。 USB Audio CODEC と出れば OK です。 aplay -l # 再生デバイス（出力）の一覧 arecord -l # 録音デバイス（入力）の一覧 card 2: CODEC [USB Audio CODEC], device 0: USB Audio [USB Audio] 注意 ：ミキサーとアンプのボリュームは、絞った状態から始めてください。いきなり爆音が出ると、ジャンクのスピーカーが本当のジャンクになります。 Easy Effects の画面はこんな感じ 画面はこんな感じです。 メイン画面 Input ：入力側のエフェクトを設定する画面に切り替えます。今回はこちらを使います Add effect ：エフェクトを追加します エフェクトの並び ：上から順に音が通ります。電源アイコンで ON/OFF、ゴミ箱で削除、右端のつまみで並べ替えです。グレーになっている Exciter はバイパス（無効）中 マイクのボタン ：これが Listen to Mic です。ON にすると、加工した音が出力デバイス（UCA222）から出てきます 入力デバイスと出力デバイスには、どちらも PCM2902 Audio Codec （UCA222 の中のチップ名）を選んでおきます。「UCA222」とは表示されないので、ちょっと迷います。 エフェクトの追加 Add effect を押すと、エフェクトの一覧が出てきます。 Search ：「equalizer」と打てば一発で見つかります + ：押すとエフェクトが追加されます まずは Equalizer を追加しておきましょう。器ができたら、中身を AI に作ってもらいます。 AI にイコライザーを作ってもらう テキストで読み込めるから、AI と相性がいい この記事でいちばん伝えたいのがここです。 イコライザーの設定を GUI でしか入力できないなら、AI に数値を考えてもらっても、結局は自分で1つずつ打ち込むことになります。でも Easy Effects は、 設定をテキストファイルでインポートできます 。AI はテキストを書くのが大得意なので、 AI の出力を、そのまま音作りに流し込める わけです。 APO 形式で出してもらうのがコツ イコライザーの設定は、 Equalizer APO 形式 （AutoEq 形式とも呼ばれます）で出してもらいます。 1行が1つのフィルターになっている、人間にも読めるテキスト PC 用の Equalizer APO や AutoEq などで広く使われているので、AI もこの形式をよく知っている Easy Effects の Equalizer にそのままインポートできる ちなみに筆者は、この記事を書く直前まで「JSON で読み込ませたんだっけ？」と思い込んでいました。掘り返してみたら、使っていたのはこの APO 形式のテキストでした。記憶とはあてにならないものです。JSON は、Easy Effects のプリセット全体を保存したときにできるファイルのほうです（後述）。 このイコライザーを作ったプロンプト AI に伝えるのは、次の4つです。 どんな機材か 何が不満か どうしたいか 出力の形式と条件 ※ 当時のプロンプトは残っていなかったので、以下は同じ結果が出るように再現したものです。 Raspberry Pi 上の Easy Effects でスピーカーの音を調整したいです。 イコライザーの設定を、Equalizer APO 形式のテキストで作ってください。 # 環境 - スピーカーはジャンク品の小型ブックシェルフ。素性はよくわからない - 音源はタブレットの音楽アプリ。ポップスや歌モノが中心 # 困っていること・したいこと - 全体的にこもって聞こえるので、すっきりさせたい - ボーカルを前に出したい - 低音はほんの少しだけ足したいが、ブーミーにはしたくない - 高音に少し空気感がほしい # 条件 - フィルターはピーキング（PK）を6本以内 - ゲインは ±3dB 程度の控えめな調整にする - 音割れしないように Preamp でマイナス補正を入れる - 各フィルターの意図も説明してほしい AI が出してきたもの Preamp: -4 dB Filter: ON PK Fc 100 Hz Gain 2 dB Q 1.0 Filter: ON PK Fc 250 Hz Gain -3 dB Q 1.0 Filter: ON PK Fc 500 Hz Gain -2 dB Q 1.0 Filter: ON PK Fc 1000 Hz Gain 1 dB Q 1.0 Filter: ON PK Fc 3000 Hz Gain 2 dB Q 1.0 Filter: ON PK Fc 8000 Hz Gain 3 dB Q 1.0 たった7行です。これをラズパイ上で preset.txt として保存しました。 mkdir ~/eq vi ~/eq/preset.txt # AI の出力を貼り付けて保存 出力ファイルの読み方 7行とはいえ、何が書いてあるのかわからないまま使うのも気持ち悪いので、読み方を押さえておきます。 1行の意味 Filter: ON PK Fc 100 Hz Gain 2 dB Q 1.0 を分解するとこうなります。 Preamp: -4 dB は、イコライザーに入る 前に 全体の音量を 4dB 下げる設定です。イコライザーで持ち上げた帯域が 0dB を超えて音が割れる（クリップする）のを防ぐためのものです。 この設定は何をしているか ひとことで言うと「 中低域のこもりを取って、ボーカルと高域を前に出す 」です。安いスピーカーにありがちな、もこもこした鳴り方への対策としては定番の形だそうです（AI 談）。 気に入らなければ、「もう少し低音を減らして」「8kHz が刺さるので弱めて」と 言葉で追加注文して作り直してもらうだけ 。ここがこの方法のいちばん楽なところです。 Easy Effects に読み込ませる 画面左上の Presets を押すと、この画面が出てきます。 New preset name ：プリセットの名前を入れる欄 + ：今の設定を、1 に入れた名前のプリセット（JSON ファイル）として保存します インポート ：ファイルからプリセットを読み込みます。筆者の記憶では、ここから preset.txt を読み込みました 読み込めると、Equalizer の6本のバンドに周波数・ゲイン・Q が入り、各バンドのモードが APO (DR) になります。 設定が決まったら、1 に名前を入れて 2 の + で保存しておくと安心です。別のラズパイに持っていくときにも使えます。 まとめ どうでしたでしょうか？まともに買うと高いDSPが、ちょっとした工夫でこんなに安く、しかもAIで音質を制御なんてステキですね。浮いたお金でさらによいスピーカー買いたくなってきました。 ご覧いただきありがとうございます！ 参考 Easy Effects（GitHub）： https://github.com/wwmm/easyeffects Easy Effects（Flathub）： https://flathub.org/apps/com.github.wwmm.easyeffects ご覧いただきありがとうございます！ この投稿はお役に立ちましたか？ 役に立った 役に立たなかった 0人がこの投稿は役に立ったと言っています。 The post ラズパイとAIで作ったオレの格安高音質オーディオ環境、控えめにいって最高すぎる〜Raspberry Pi + Easy Effects で自作DSP、音の調整はAIにおまかせ〜 first appeared on SIOS Tech Lab .

Claude Code ぶん回して仕様駆動開発を実践してみた 〜 設計書3.6万行と6つの落とし穴 〜 この記事のポイント 問題提起 背景 前提 システムの全体像 開発体制と Claude Code の使い方 設計時のぶん回し 設計書を Fix してから実装する 依頼は「まず既存の仕組みを調べて」から始める 選択肢は「影響範囲」の列を立てて比べる 決まったことは設計書の冒頭とメモリに残す アーキテクチャ選定で分かったこと 画面設計：Excel と MD3 の方針だけで作る 実装時のぶん回し 実装計画も、人間がレビューしてから走らせる テストは先に書かせ、失敗を見てから実装させる OpenAPI と design.md で「正」を分ける インフラ：検証環境と本番環境の差異に苦戦 新本番環境想定の負荷試験をやり切る アプリ動作確認：エミュレータを Claude Code に操作させる 実装計画に「セルフフィードバック」を組み込む Crashlytics の調査 問題点と解決策 問題点 1：尤もらしい誤りと「存在しない懸念」が紛れ込む 解決策 1：「推測」と「確定」を分けて書かせ、出典を残させる 問題点 2：AI は足し算が得意で、引き算が苦手 解決策 2：方針とスコープで「引き算」を仕組みにする 問題点 3：ドキュメントが膨大になり、人間のレビューが追いつかない 解決策 3：人間が読むもの（design.md）と AI が読むもの（plan.md）を分ける 問題点 4：設計書と実装がズレていく 解決策 4：実装結果を設計書に書き戻すまでを「完了」にする 問題点 5：リポジトリやセッションをまたぐと前提が抜け落ちる 解決策 5：共有メモリと HANDOFF.md でコンテキストを受け渡す 問題点 6：Git 操作で作業ツリーやブランチ運用を壊しかける 解決策 6：Git のルールを CLAUDE.md に明文化し、コミットは人間が握る まとめ 問題提起について 誰が読んでも共通のドメイン知識を持てる product-docs 最後に 　こんにちは、開発本部 開発２部 RetailHUB NetSuperグループに所属するホーク🦅アイ👁️( @every_hawk_eyes )です。本記事で紹介するプロジェクトでは、エンジニアリーダーとしてフロントエンド・バックエンド・インフラ・アプリ開発のすべてに関わりながら、プロダクトマネジメントも少し担っていました。 この記事のポイント 2026 年 6〜8 月の 3 か月間、3〜7 名のチームで、ネットスーパーの Server API、AWS基盤、ピッキングアプリを、Claude Code を中心に新規開発 設計書を Claude Code に書かせ、人間がレビューで Fix してから実装する、仕様駆動開発（SDD）に近い進め方をとった。1 つの機能だけで設計書・計画書は約 3.6 万行に達し、ボトルネックは人間のレビューへ デザイナー不在の中、注釈付き既存画面スクショと Material Design 3 の方針だけでアプリ開発 AI の尤もらしい誤り、足し算の設計、膨らむドキュメント、設計書と実装のズレ、コンテキストの断絶、Git 事故という 6 つの落とし穴を、解決策と併せて紹介 問題提起 AI に任せてもそれなりのものが作れる時代でも、平準化されないエンジニアの価値とは、 AI と質疑を重ねて設計を詰め切る力と、チーム内議論での発言力・決断力ではないか AI の尤もらしい誤りを疑うためのドメイン知識とシステム全体の理解を得るには、 誰が読んでも共通のドメイン知識を持てるドキュメント整備が肝要なのではないか 背景 　弊社では Claude を非エンジニアも含めた全社に展開しており、我々のチームでも今年 3 月に Cursor から Claude Code へ移行しました。 　2026 年 6〜8 月には、新しい小売チェーン向けにネットスーパーを立ち上げる新規開発がありました。Server API、AWS インフラ、店舗の作業者が使う Android のピッキングアプリまでを、最小 3 名、いちばん多い時期でも 7 名（1 か月間のみ）で作る必要があり、アプリのデザイナーもいません。そこで、設計から実装・テスト・障害調査まで、Claude Code を「ぶん回す」前提で進めました。 　本記事では、うまくいったやり方に加えて、 現場で実際に起きた問題点と、それに対する解決策について を紹介します。 前提 システムの全体像 システムの全体像。既存の小売は、別のクラウドサービスの VM で動くネットスーパー本体（PHP）と DB を使う。新規小売は、AWS に移したネットスーパー本体（PHP / ECS Fargate）と RDS を使う。両方の本体から Go の Server API を呼び出し、Server API は両方の DB を読み書きする。ネットスーパーから独立したピッキングシステムは、Server API から注文データを受け取って Aurora DSQL に保存し、Server API へは EventBridge のカスタムバスと API Destination で非同期に連携する 　ネットスーパー本体は、別のクラウドサービスの VM で長年動いてきた PHP のシステムです。本体は極力改修しない方針で、新しい処理は Go の Server API に寄せています。今回は、主に次の 2 つの対応が必要でした。 インフラを AWS に 1 本化するための、ネットスーパー本体の AWS へのマイグレーション。今回の新規小売が、移行先の AWS で本番を立ち上げる最初の小売になった（9 月 1 日にローンチ） ネットスーパーとは独立したプロダクトとして開発しているピッキングシステムに、注文単位でピッキングする新モードを追加する開発 　呼び出しの向きは「ネットスーパー本体 → Server API → ピッキングサーバー」を基本とし、逆向きは EventBridge 経由の非同期に限っています。1 つの機能が 4〜5 リポジトリにまたがる構成です。 開発体制と Claude Code の使い方 項目 内容 人数 最小 3 名〜最大 7 名（7 名体制は 1 か月間のみ）。インフラは専任を置かず全員が兼務 設計書 product-docs（Markdown の設計書を GitHub で管理するリポジトリ。名前は本記事での仮のもの） デザイナー 不在（Figma などのデザインツールも不使用） Claude Code VSCode 拡張版やターミナル経由。プラグインは superpowers を中心に使用 　Claude Code は次のように設定して使いました。 メインのセッションは、その時点の最新の上位モデルに、Effort を Extra high にして実行していた。サブエージェントのモデルは特に指定せず、Claude Code の既定に任せました 2026 年 8 月 14 日に Auto モードが default 化されてからは、常に Auto モードでプロンプトを実行してました。それに合わせて、以前の記事 で紹介した Hooks による macOS の通知は、Claude Code から質問が来たとき（AskUserQuestion）だけ鳴るように変えました それまでは「Edit automatically」で使いながら、 .claude/settings.json の許可ルールを都度追加して整えてきたので、Auto モードに切り替えることに不安はありませんでした 　ツールの構成や挙動は、2026 年 6〜8 月時点のものです。 設計時のぶん回し 設計書を Fix してから実装する 　今回いちばん効果があったのは、 いきなりコードを書かせない ことでした。複数リポジトリにまたがる機能をそのまま実装させると、仕様の解釈違いや影響範囲の見落としが後から大量に出てきます。そこで、superpowers のワークフローに乗せて、次の流れで進めました。 ① 要件と関連資料を渡し、「まず既存の仕組みを調べて」と頼む ② brainstorming：コード調査 → 質問 → 選択肢の比較 → 人間が方針を選ぶ ③ 設計書（DD）を書かせ、チームがレビューして Fix する ④ writing-plans：実装計画（PD）を実装リポジトリごとに作らせ、人間がレビューする ⑤ TDD とタスクごとのセルフレビューで実装させる ⑥ 実装で判明した差分を DD / PD に書き戻させる 　これはいわゆる仕様駆動開発（SDD）です。Birgitta Böckeler 氏の整理でいえば、実装後も設計書に書き戻して保守に使い続ける「spec-anchored」に近い運用です。superpowers の基本のワークフローとの違いは、設計書を専用のリポジトリに置いてチームでレビューすることと、実装計画を実装リポジトリごとに分けることです。 参考: Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl （Birgitta Böckeler 氏、2025 年 10 月 15 日。SDD を spec-first / spec-anchored / spec-as-source の 3 段階に整理しています） 参考: obra/superpowers （GitHub。README の「The Basic Workflow」に各スキルの役割が書かれています） 　 AI に任せるのは「調べる・書く」まで、「決める」のは人間 と線を引き、設計書も実装計画も、人間が OK を出すまで次の工程に進ませないことがポイントです。 依頼は「まず既存の仕組みを調べて」から始める 　「こう作ってほしい」と実装方法から指示するより、 先に既存の仕組みを調べさせる ほうが、既存の作りに沿った無理のない案が出てきます。 選択肢は「影響範囲」の列を立てて比べる 　方針を決める前に、2〜3 個の選択肢を「処理の流れ・メリット・デメリット」付きで並べさせ、人間が選びます。判断が割れる論点は、ここでチームでも議論します。比較の表には 変更対象の影響範囲 の列も必ず立てさせています。「1 行追加するだけ」の改修案が、実は 10 以上の小売が共有し、毎日使われる画面への変更だったことがあるためです。 決まったことは設計書の冒頭とメモリに残す 　議論で決まったことがチャットに埋もれていると、AI は次のセッションでそれを参照できません。設計書の冒頭に「決定事項サマリー」を置き、レビューで受けた指摘は「なぜ」と「次からどうするか」を付けて Claude Code のメモリに残すようにしました。こうしておくと、一度受けた指摘を毎回言い直す必要がなくなります。 アーキテクチャ選定で分かったこと 　EventBridge を使った 2 つの仕組み（バッチの起動と、ピッキングサーバーからの非同期連携）は、どちらも選択肢を並べて比べ、 採用しなかった案とその理由 を設計書に残しました。その中で分かったことは次の 3 つです。 前提から見直す。NAT Gateway の新設コストを避けるためにバッチのタスクをパブリックサブネットに置いていたが、見直すと NAT Gateway はすでにあり、そもそもの前提が成り立っていなかった 非同期にするなら、受け手の作法まで決める。EventBridge の API Destination は応答待ちが最大 5 秒で、リトライするのは 5xx と一部の 4xx だけなので、受け手は 5 秒以内に返し、再送しても直らないエラーはリトライされない 4xx で返す。同じイベントが何度届いても結果が変わらないようにもしておく 非同期がいつも正解ではない。ECS のタスク起動に 1 分ほどかかるため、データ連携の開始時に台帳を作る処理は同期にした 参考: Amazon EventBridge のターゲットとしての API 送信先 （AWS ドキュメント。5 秒のタイムアウトと、リトライするエラーコードの一覧が載っています） 画面設計：Excel と MD3 の方針だけで作る 　デザイナーもデザインツールも使わず、インプットは既存アプリのスクショに要望の吹き出しを描き足した Excel と、Material Design 3（MD3）に沿うという方針だけでした。Claude Code は画像を読めるので、スクショを渡して画面ごとの設計書に MD3 のコンポーネント、色・文字のトークン、アクセシビリティまで書かせ、アプリ開発エンジニアがレビューしてから実装しました。これでデザイナー不在でも「エンジニアのなんとなくの見た目」にはなりませんでしたが、 現場の作業者が使う業務アプリ だから成立した面も大きいです。 実装時のぶん回し 実装計画も、人間がレビューしてから走らせる 　設計書が Fix したら、superpowers の writing-plans で実装計画 plan.md を作ります。作業を 1 ステップ 2〜5 分の単位に分け、ファイル・コード・テストの方法まで書く方針なので、1 本で 2,000 行を超えることも珍しくありません。plan.md も 人間がレビューしてから実装に入ります 。plan.md を書き終えるなり実装を始めさせると、ファイルの数・タスクの順序・コミットの粒度といった、こちらの方針が反映されるべき判断を後から直すコストが大きいためです。 テストは先に書かせ、失敗を見てから実装させる 　AI は「テストが通るように実装を寄せる」だけでなく「実装に合わせてテストを直す」こともやりがちなので、 先に失敗を見る 手順を挟むことが大事でした。 OpenAPI と design.md で「正」を分ける 　API の型は OpenAPI、業務的な意味は design.md を正とすることで、サーバー担当とアプリ担当が I/F だけ先に合意し、それぞれ Claude Code で並行して実装を進められました。 インフラ：検証環境と本番環境の差異に苦戦 　移行先の AWS の本番環境は、Claude Code に 今春既に構築済の検証環境 の Terraform を棚卸しさせ、「検証環境 のこのリソース → 本番ではこの名前・この設定で作る」という対応表を設計書にまとめさせたうえで、約 2 週間で構築しました。この期間は単に AWS リソース作成だけで終わらず、セキュリティ対策や、本番環境特有の WEB アプリケーション側の設定ファイルの設定差異を調整する作業も行いました。 新本番環境想定の負荷試験をやり切る 　ローンチ前の負荷試験を1人でやり切る必要があったためここでも Claude Code をぶん回してやり切りました。 目標値は推定ではなく、既存の小売の実アクセスや過去の注文実績データから出しました 環境はコスト節約のため AWS リソース適用を 3 モードで切り替えられるように工夫しました ワーカーの枯渇を見逃さないように外部依存のモックには本番相当の遅延を入れるようにしました ボトルネックは Web ではなく DB という結果が得られ、インデックスの欠落を見つけることができました アプリ動作確認：エミュレータを Claude Code に操作させる 　画面をまたぐ動作確認は、Claude Code に Android エミュレータを adb で操作させ、スクリーンショットを見て判定させました。弊社のテックブログには、iOS シミュレータと Maestro MCP で試した記事 もありますが、今回は MCP を使わず素の adb です。カメラを使う画面も、エミュレータの仮想カメラに QR コードの画像を貼れば、実機なしで確認できます。一方で、ラベルプリンターやハンディ端末のスキャナーはエミュレータでは確かめられないので、widget テストと人間による実機確認で補いました。 参考: カメラのサポート （Android Studio のドキュメント。エミュレータの仮想シーンに QR コードなどの画像を取り込む手順が載っています） 実装計画に「セルフフィードバック」を組み込む 　実装計画の最後には、ブランチ全体の差分をレビューさせるタスクを毎回入れ、 設計書に書かれていない実装上の判断 （失敗時の扱い、エッジケース、競合、再試行など）を重点的に見させています。人間のレビュー指摘が、設計書で合意済みの部分よりもこうした隙間に集中していたためです。このレビューで、「何も選ばずに適用すると全件分の重いリクエストが飛ぶ」という設計書自体の欠陥が見つかったこともあります。 Crashlytics の調査 　Firebase MCP 経由で Crashlytics の FATAL を調べさせると、 別々に見えていた 3 件（計 69 events）が、1 つの共通実装に起因している ことを突き止めてくれました。 問題点と解決策 　ここからが本題です。3 か月ぶん回してみて実際に困ったことと、取り入れた解決策を組にして紹介します。 問題点 1：尤もらしい誤りと「存在しない懸念」が紛れ込む 　AI が書いた設計書は体裁が整っていて、それらしく読めてしまいます。しかし実際のレビューでは、指摘に対して次のような回答が返ってくる場面がありました。 AI が出したけど誤っていた内容で、削除するのを失念していました。 AI が「こういう問題が起こりうる」と言い始めて、調査したらそんなものはなかった、というやり取りがあって、そのやり取りをわざわざ設計書に入れてしまっていました。 　インフラでも、EFS のバーストクレジットが尽きるまでの日数や、試験環境の維持費（月 $3〜20 → 実測で月 $1.3）の見積もりが、尤もらしい根拠付きで大きく外れていました。AI は「知らないこと」を知らないとは言わず、それらしく埋めてしまいます。そして 書いた本人も AI の出力をすべて把握しきれていない まま PR が出てしまう、というのが一番怖いところでした。 解決策 1：「推測」と「確定」を分けて書かせ、出典を残させる 「 事実と推測を区別する 」をメモリにフィードバックとして残す 設計書には「未確定事項」の節を設け、確定していないことはそこに書かせる 決定事項には、いつ・どの議論で決まったかを添えさせる AI との試行錯誤の経緯は設計書に書かせない。残すのは 決まった結論と、その理由 だけ 業務の事実確認が必要な設計書は、業務を知るメンバーを必ず Reviewer に入れる 　加えて、PR を出す前に「 この設計書の内容を、自分の言葉で説明できるか 」を作成者自身が確かめることが大事だと感じています。 問題点 2：AI は足し算が得意で、引き算が苦手 　AI に設計させると、「この問題も起こりうるので対策を」「ここも新規 API を作って」と、機能と考慮事項がどんどん足されていきます。たとえばパッキング完了の書き戻しの設計書は、当初「受け取った側がピッキング結果を取りに行く API を新設する」案でした。これにレビューで「本当に新規で実装する必要がある？ EventBridge にリクエストボディで渡せばいいのでは？」と指摘が入り、API を新設せずに済みました。AI は、工数や運用コストの観点で「そもそも作らなくていいのでは」と 引き算 をするのが苦手で、このレビューはまさにそれを人間が担った例です。 解決策 2：方針とスコープで「引き算」を仕組みにする 「無改修で済む案があるなら、既存コードを直す案より優先する」をメモリに残し、AI の提案の前提にする 判断が割れる論点は、設計書より先に選択肢比較を作らせ、影響範囲の列を見て人間が決める 設計書の冒頭には「スコープに含むもの」だけでなく「 スコープ外 」を必ず書かせ、外した論点は「残課題」の節に担当者付きで残す 　「やらないこと」を書く場所をあらかじめ用意しておくと、AI が出してきた懸念を「今回はやらない、でも忘れない」と判断しやすくなります。 問題点 3：ドキュメントが膨大になり、人間のレビューが追いつかない 　AI は疲れないので、設計書も計画書もいくらでも書けます。設計書の PR は 3 か月で 68 本とリポジトリ別で最も多く、注文別ピッキング関連だけで設計書・計画書は 約 3.6 万行 、最も大きい設計書 PR は 1 本で 追加 12,670 行 に達しました。 　人間がこれをすべて精読するのは現実的ではなく、「書いてあるけど誰もちゃんと読んでいない」箇所から、問題点 1 の誤りがそのまま素通りしてしまいます。SDD のツールを試した Böckeler 氏も「正直、これだけの Markdown ファイルより、コードをレビューしたい」と書いています。SDD はレビューのボトルネックを消すのではなく、コードから設計書という上流へ移すのだと思います。 解決策 3：人間が読むもの（design.md）と AI が読むもの（plan.md）を分ける ドキュメント 主な読み手 内容 人間のレビュー design.md（設計書） 人間 何を・なぜ作るか（業務的な意味、方針、影響範囲、未確定事項、非ゴール） しっかり読んで議論する plan.md（実装計画） AI どうやって作るか（ファイル単位のタスク、テスト、コマンド） ファイルの数・タスクの順序・コミットの粒度を中心に見て、OK を出してから実装させる 　人間のレビュー力は有限なので、精読の優先度を design.md に置き、設計書は画面・サブ機能の単位に分けて 1 本の PR を小さく保つようにしました。実際、レビューの往復が多かった設計書 PR の上位 4 本は、 いずれも追加 400 行未満 でした。 　PR が大量にある中、具体的なレビュー方針は次のように分けて実施しました。 設計書（DD） ：議論すべき論点や、Fix が必要な未決事項を残した状態があっても PR を出し、チームで決めきりました 実装（編集量が大量ではないもの） ：今まで通りの担当 Reviewer が全て目視でレビューをしました 実装（編集量が多いもの） ：AI にレビューさせました。ただし任せきりにはせず、結果をまず Reviewer へ報告させ、その内容を吟味し AI と会話して、コメント投稿させていました 問題点 4：設計書と実装がズレていく 　実装して初めてわかる仕様の穴は、必ず出てきます。実装中に Claude Code が「計画にない判断」をして解決すると、それが設計書に戻ってきません。設計書が古くなると、次の設計で AI がその古い前提を読み込んでしまい、設計駆動の良さが逆に仇になります。 解決策 4：実装結果を設計書に書き戻すまでを「完了」にする 実装が終わったら「計画からの逸脱」「実装で判明した仕様の穴」「残課題」を設計書に追記するところまでを、タスクの完了条件にする 設計書の冒頭にステータス欄（「実装済（日付）」「未リリース」など）を置き、実装のたびに更新させる 　なぜ計画から外れたかを一番よく知っているのは、実装したセッションの Claude Code なので、その場で書き戻させるのが最も安上がりです。 問題点 5：リポジトリやセッションをまたぐと前提が抜け落ちる 　1 つの機能が複数のリポジトリにまたがるため、A リポジトリで決めたことを B リポジトリの Claude Code セッションは知りません。長い作業では、途中でコンテキストが要約されて細部も落ちます。開発人数が増減する中で、人間同士の引き継ぎに加えて「AI への引き継ぎ」も必要になりました。 解決策 5：共有メモリと HANDOFF.md でコンテキストを受け渡す 置き場所 スコープ 内容 CLAUDE.md 全リポジトリ共通 / リポジトリ 前提・ルール（Git の禁止事項、ドキュメントの置き場所など） メモリ リポジトリ レビューで受けた指摘や過去の経緯（「なぜ」と「次からどうするか」付き） 共有メモリ リポジトリ横断 他リポジトリに影響する変更（API 仕様、DB スキーマ、インフラ、設計判断など） HANDOFF.md 作業単位 セッションをまたぐ作業の引き継ぎ（いまの状態、次にやること、引き継ぎプロンプト） 　共有メモリには、作業完了時に Skill で「影響先」「内容」「対応が必要なこと」を書き出させ、関連リポジトリで作業を始めるときに読ませています。「設計書のここがまだ実装に追従していない」といった申し送りも書かせているので、問題点 4 のズレを追跡する台帳にもなります。セッションの残りが少なくなったら、その時点の状態を HANDOFF.md に書き出させてから新しいセッションに切り替えると、細部が落ちる前に区切れます。 問題点 6：Git 操作で作業ツリーやブランチ運用を壊しかける 　AI は良かれと思って Git を操作します。設計書リポジトリの master への直接コミット、並行して動いていた別セッションの作業とぶつかるブランチの切り替え、別ブランチの中身を読むつもりの git checkout <ref> -- . で未コミットの 27 件のローカル変更を消す、ということが実際に起きました。未ステージの変更は Git では復元できず、残る手段は VS Code のローカル履歴だけです。 解決策 6：Git のルールを CLAUDE.md に明文化し、コミットは人間が握る ## 作業ツリーを壊さない（全リポジトリ共通・最優先） - 調査・参照のためにユーザの作業ツリーへ書き込むコマンドを実行しない。 他コミットの内容は ` git show <ref>:<path> ` / ` git worktree add ` などで読む。 - 明示的な GO なしに実行禁止: ` git checkout -- . ` / ` git restore ` / ` git reset --hard ` / ` git clean ` / ` git switch ` / ` git stash ` - 作業ツリーには常に未コミット変更がある前提で動く。触れる前に ` git status ` を見る。 　あわせて、 git add -A は使わない、設計書リポジトリのコミット・push・PR は人間が行う、並行作業は git worktree add でディレクトリを分ける、といったルールもメモリに残しています。「AI を信用しない」のではなく、 AI が壊せない構造にしておく のがポイントです。 まとめ 　3 か月間、少人数のチームで、Server API・インフラ・Android のピッキングアプリまでを、Claude Code をぶん回して開発しました。デザイナー不在でアプリを作り切れたのも、AWS へのマイグレーションと並走しながら本番構築から負荷試験までを回せたのも、AI 駆動ならではだと思います。 　一方で、ぶん回してみてわかったのは、 AI 駆動開発のボトルネックは AI ではなく、人間のレビューと意思決定 だということです。AI は調べて書くのは圧倒的に速いですが、尤もらしい誤りを混ぜ、足し算で膨らみ、決めたことを忘れ、ときには Git を壊します。だからこそ、 設計書を先に書き、人間がレビュー・議論して Fix してから実装する 人間が読むもの（design.md）と AI が読むもの（plan.md）を分ける 決めたこと・やらないこと・ズレたことを、AI が読める Markdown に残し続ける AI が壊せない構造（ルールと worktree）を先に作っておく という「 人間が決めて、AI がぶん回す 」ための仕組みづくりが、結果的に一番の生産性向上につながりました。 問題提起について 　AI に任せきっても、それほど悪くないものができあがってしまうくらい、モデルの精度は高くなっています。その中で、エンジニアの存在意義や能力の差が平準化されるのでは、という危惧もあります。ただ、今回の開発プロジェクトを振り返ると、私は 決してそうではない と実感しています。理由は 2 つあります。 AI と設計を詰め切る力は、一朝一夕では身につかない ：superpowers の brainstorming で AI と質疑を繰り返し、設計を Fix させる力は簡単には身につかないと思います。その議論をチームで行うときの発言力や決定力にも、差が大きく出てくるはずです AI を疑うには、ドメインとシステムの理解が要る ：ハルシネーションによる誤りや、尤もらしい実装が出てきたときに、まず疑ってセルフフィードバックできることが重要です。そのためには、プロジェクトのユビキタス言語やドメイン知識、システム全体の仕様をしっかり理解しておかなければなりません 誰が読んでも共通のドメイン知識を持てる product-docs 　設計書を置いている product-docs は、AI、エンジニア、問い合わせ担当、セールス担当の 4 種の読み手に役立つことを目指したリポジトリです。Markdown を中心に、Claude Code を通して誰が読んでも共通のドメイン知識を持てるよう、都度書きためています。書き足しているのはエンジニアなので設計書が多いですが、既存システムの仕様やアーキテクチャをまとめたドキュメントもあります。 　このリポジトリをチームでフル活用したおかげで、ドメイン駆動での開発が円滑に進み、スポットで参加したエンジニア 3 名にもパフォーマンスを発揮してアウトカムを出してもらえたのではないかと感じています。 最後に エブリーでは、ともに働く仲間を募集しています。 テックブログを読んで少しでもエブリーに興味を持っていただけた方は、ぜひ一度カジュアル面談にお越しください！ corp.every.tv

こんにちは。株式会社タップルでiOSアプリエンジニアをしている五味と、同じく株式会社タップルでiOS ...