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

スタメンでCTOしております、 @tnir ( X: @takuya_stmn , note: @takuya_stmn ) です。 2023年9月、スタメン技術ブログで次の記事を公開しました。 ドメイン駆動設計は何を解決する手法なのか 記事では、TUNAG の技術的負債解消に向けてドメイン駆動設計（DDD）の導入を検討している、と書きました。その後の対外的な印象として、「スタメンは DDD を積極導入している」と読まれる場面がありました。 本記事の目的は二つです。 当時の検討表明と、いまの実装実態のあいだにある差分を正確に共有すること その後に行った小規模な試験導入（PoC）から得た、Rails 文脈での技術的・組織的な学びを共有すること 結論を先に述べます。私たちの設計の軸は ActiveRecord で、DDD はバックエンドのごく小さな範囲で試しました。その結果、ActiveRecord を軸にする方針を選んでいます。ただしこれは DDD全般の評価ではなく、私たちの文脈での記録です。小さく試し、合うものを残し、合わないものを手放すプロセス自体は、今でも有効なエンジニアリング判断だと考えています。 2023年の記事が書いていたこと 当時の記事の冒頭は、次のとおりです。 株式会社スタメンでは、企業エンゲージメント構築サービス TUNAG（ツナグ）の技術的負債解消と今後の持続的成長のため、ドメイン駆動設計(DDD)の導入を検討しています。 記事は実装報告ではなく、コアドメインを軸に「DDD が何を解決する手法なのか」を整理する解説でした。実装詳細は扱わない、とも明記しています。締めは、将来に向けた表明です。 つまり本文の事実は「導入を検討している」までであり、「すでに積極導入している」ではありません。ただし、解説の熱量や「邁進していきます」という結びが重なると、読後印象としては積極導入企業のように残りやすい面もありました。このギャップを、いま実装と検証結果に基づいて補正します。 当時の課題提起がなければ、机上の議論で終わっていた可能性もあります。検討を公開し、その後に実コードで検証まで進めたからこそ、本記事で共有するトレードオフが見えました。 何を、どこまで試したか 私たちのプロダクトは、大きくバックエンド（API）とフロントエンドに分かれます。 領域 DDD との関係 フロントエンド 導入なし バックエンド全体 教科書的な全面適用はなし。LoC ベースで全体の 1% を大きく下回る範囲で、部分的・実践的な試験のみ 試験の主例 社内教育・テスト（ナレッジテスト）領域の新規 API 見送り後の比較例 タスク依頼・ToDo 領域の新規 API 本記事では前者を 業務DXサービスA API 、後者を 業務DXサービスB API と呼びます。どちらも TUNAG 本体から独立した形で実装されたグリーンフィールドサービスのバックエンドです。 業務DXサービスA API は、MVC でくくると Model がおおよそ 2,000 LoC 前後、View + Controller がおおよそ数百 LoC 規模でした。期間は 2023年12月からの約3ヶ月です。ここでの DDD は、Evans 流の戦術パターンを全面適用したものではなく、不変条件が重要な箇所に限定した実用主義的な導入（DDD-lite としても呼ばれることがある）でした。設問・選択肢・合格判定・受験セッションなど、「壊れると困るルール」が比較的はっきりしている領域だったため、試験対象として適していました。 実コードでは、たとえば次が確認できます。 ドメイン層を ActiveRecord から分離した pure Ruby のオブジェクトがある 選択肢数・重複・合格ラインなどの不変条件を、生成時や操作時に検証する実装がある 一部の更新経路では、リポジトリ経由で集約を再構成してから永続化する 一方で、次の限界もありました。 単純更新・複製・一部セッション更新は ActiveRecord 直叩きのまま残り、層を迂回した 一部のドメインオブジェクトは、振る舞いに乏しいデータホルダーに近い ドメインイベントや、依存逆転を徹底した古典的構成までは採っていない つまり「DDD を名乗るに足る部分実装はあった」が、「プロダクト全体の標準アーキテクチャになった」わけではありません。 時系列は次のとおりです。 時期 内容 2023年9月 技術ブログで導入検討を表明 2023年12月〜約3ヶ月 業務DXサービスA API で部分的・実践的な DDD を試験導入 2024年3〜4月 PoC 振り返り。本格採用を見送り、業務DXサービスB API では採用しない方針を合意 2024年5月〜約3ヶ月 業務DXサービスB API を、DDD 非採用前提で初期開発 現在 フロント未導入。バックエンドでも局所試験の知見にとどまり、標準は ActiveRecord を軸にした設計 業務DXサービスB API は「DDD 導入の第2弾」ではありません。振り返りの結果、採らないと決めたあとの開発です。境界の分離や外部モデルの漏洩防止など、マイクロサービスとして当然の設計はありますが、それを DDD の戦術導入とは数えません。 なぜ本格採用を見送ったか — 技術的・組織的な理由 ここが本記事の本題です。「やらなければよかった」ではなく、「何が効き、何が合わなかったか」を残します。 1. 本来の課題と手法がずれた 2023年の検討の出発点は、TUNAG の技術的負債解消でした。ところが検証が進むにつれ、 手法の導入そのものが目的化しやすい 局面がありました。 負債解消で本当に解きたかったのは、たとえば次のようなことだと考えています。 変更影響の見通しを良くすること ドメイン知識をコード上で追跡しやすくすること チームが安全に改修できる速度を保つこと 一方で、層分け・用語・パターンの整備が進むと、「DDD らしく書けているか」が評価軸になりやすい。すると、負債解消や変更容易性への寄与より、導入の完成度が議論の中心になります。業務DXサービスA API での試験は、この目的化を本体から切り離して観測するためにも有用でした。振り返りの結論は明確で、 その時点のスタメンの文脈では、DDD の本格導入は TUNAG の技術的負債解消に適していない 、でした。 2. Rails / ActiveRecord との摩擦コストが高かった 業務DXサービスA API は Rails API です。ActiveRecord は永続化だけでなく、クエリ・バリデーション・ライフサイクル・関連の中心でもあります。ここに戦術的 DDD（集約の再構成、リポジトリ、pure ドメインモデル）を部分導入すると、少なくとも次のコストが発生しました。 二重モデル化 : DB 行としての AR と、ドメイン上のオブジェクトを往復させる変換が必要になる 経路の分岐 : 不変条件が強い操作だけドメイン経由、単純 CRUD は AR 直叩き、という二系統が同居する 認知負荷 : 「この変更はどの層に書くべきか」の判断自体が、機能追加のたびに発生する 複雑な採点や、正式版の訂正ルールのように、壊れ方が高い箇所では、pure なドメインオブジェクトに寄せる利点はありました。逆に、大半の更新が CRUD に近い画面・API では、変換と層分けのコストが、得られる安全性を上回りやすかった、というのが率直な感触です。 Rails way（責務を散らさない Model、明確な UseCase、必要なら concern）を主軸にした方が、少人数チームでの変更速度と学習コストのバランスが良かった、というのが本格採用見送りの技術的な中核です。 3. 効く範囲が、プロダクト全体のボトルネックと一致しなかった DDD が相対的に効きやすいのは、ルールが複雑で、不変条件の破壊がそのまま障害になる領域です。業務DXサービスA API でも、設問制約や採点のようにその種の箇所には部分適用の合理性がありました。 しかし TUNAG 本体を含むプロダクト全体の負債の主因が、「集約境界が無いこと」だけだったわけではありません。認証委譲、サービス分割、スキーマ契約、運用、データ整合、画面を含む変更伝播など、別種の複雑性の方が大きい局面も多い。戦術 DDD を局所に厚くしても、プロダクト全体の変更容易性が線形に改善するとは限らない、というのが PoC 後の整理です。 4. 小さく試せたから、大きく間違わずに済んだ 見送り自体を失敗とは捉えていません。新規の小さい API で約3ヶ月試し、振り返り、次の新規 API では使わないと決めた。この切れ方の方が、本体へ先に全面適用するより健全でした。 組織として得られた整理は、次です。 DDD は銀の弾丸ではない 導入を目的化すると、負債解消から離れる Rails 中心のプロダクトでは、戦術 DDD の全面適用より、ActiveRecord を軸に複雑箇所だけ設計を厚くする方が現実的なことが多い 手法の採否は、流行や完成度ではなく、事業成長と開発生産性（保守性・変更容易性を含む）で見る いまの設計方針 PoC 後の標準は、ActiveRecord を軸に置いています。UseCase（アプリケーションサービス）でユースケースの流れとトランザクション境界を担保しつつ、永続化モデル側は ActiveRecord 本来の表現力を活かす。そのうえで、モデルを無秩序に太らせないために、関心事ごとに concern へ閉じる、という形です。 これは「Fat Model に戻した」という意味ではありません。ドメイン層と AR を二重に持つコストを下げつつ、ユースケースのオーケストレーションは UseCase に残し、モデルに散らばりがちな関心事だけを concern で分割する、という選択です。Concern の濫用が神オブジェクトの隠蔽になりうることは認識したうえで、DDD-lite の二重モデルより、この分割の方がチームの認知負荷と変更速度に合う、と判断しています。 対外的な事実関係は、次で足ります。 2023年の記事は導入検討の表明であり、全面採用の報告ではない フロントエンドでは DDD を導入していない バックエンドでも、LoC ベースで全体の 1% を大きく下回る範囲での部分的・実践的な試験にとどまる 主例は業務DXサービスA API（2023年12月〜約3ヶ月） 2024年3〜4月の振り返りで本格採用を見送り、業務DXサービスB API（2024年5月〜約3ヶ月）では非採用前提で開発した 現在のスタメンを「DDD積極導入企業」と呼ぶのは実態に合わない 小さく検証し、合わなければ採用しない、という判断は今後も取りうる 手法の是非を好みで決めず、小さく試し、事業成長と変更容易性を含む生産性、および本来の課題（技術的負債解消）への寄与で採否を決める。業務DXサービスA API での試験と、業務DXサービスB API での見送りは、その一例です。 おわりに この記事は、過去のチャレンジ計画ブログ記事を消すためのものではありません。当時の検討や、その後の試験を否定するものでもありません。むしろ、2023年の記事が課題を言語化し、仮説を外に出したからこそ、机上の空論で終わらせず実コードでトレードオフを検証できました。話題の手法をスローガンで終わらせず、小さなプロダクトに落として確かめ、本格採用を見送った記録です。 エンジニアリングにおいて重要なのは、流行を追うことでも、一度選んだ手法に固執することでもありません。自社のプロダクト特性、フレームワークの前提、チームの認知負荷に照らして、効く設計を残し、効かない設計を手放せることです。今回の PoC は、その判断をコードと振り返りで一度通した事例だと考えています。 設計の話をするときも、採用の話をするときも、「スタメンは DDD を積極導入している」ではなく、「小さく試し、Rails / ActiveRecord を軸に UseCase と concern で整理する設計を主軸として選び直した」と読んでいただけると、実態に近いです。 今現在、主に採用しているシンプルな Rails Way に準じたアーキテクチャに関しては別の記事でコメントできればと思います。

はじめに 日々の開発において、AI にコードを書いてもらうことは日常になってきました。要件を伝えれば既存のコードベースを調査し、その作法に合わせて機能を足してくれます。 生成されたコードがいつも正しいわけではありませんが、それでも「コードを書く」という作業そのものは、以前ほど開発のボトルネックではなくなりつつあると感じています。 その一方で、AI と一緒に開発していると、「何を実装してもらうか」を決める時間の比重が増えてきました。この記事では、その実感を出発点に、次の 3 つを順に考えてみました。 AI 駆動開発で、設計はどこに書いておくとよいのか 既存の設計成果物で、実装されたコ