こんにちは。ファインディ株式会社でプリンシパルエンジニアをしている戸田です。 ファインディでは、施策の立案からIssueの生成、タスク分解、AIエージェントによる並列実装やQAまで、開発フローの各所にAIエージェントを組み込んでいます。 この記事では、開発フロー全体のアーキテクチャを図で示し、構成要素ごとに役割を解説します。PM、開発、QAのそれぞれでエージェントが何を担い、人間がどこで判断しているのか、開発の状態をGitHubのどこに置いているのかが分かる内容となっています。 複数のAIエージェントを開発フローに組み込もうとしている方や、AIエージェントとの役割分担を考えているエンジニアの方の参考になると思います。それでは見ていきましょう！ 開発フローのアーキテクチャ 施策を作るエージェント 施策提案スキル 要件定義スキル 要件をIssueに分解するエージェント Issueの依存関係から実装の順番を決める計画エージェント 並列で動く実装エージェント スタックプルリクエスト QAのエージェント まとめ 開発フローのアーキテクチャ エージェントやスキルは、PM向け、開発向け、QA向けの3つのPluginにまとめています。 開発フローは次の順に進みます。 PM向けPlugin PMのエージェントがNotionやGitHubなどからコンテキストを集めて施策を作り、要件定義のIssueとしてGitHubに作成する 開発向けPlugin 開発のエージェントが要件定義のIssueをタスクに分解し、親Issue、Sub-issue、依存関係をGitHubに作成する 計画エージェントがGitHubからIssueと依存関係を読み、実装の順番を決める 実装エージェントが依存の順にIssueを実装し、スタックプルリクエストとして積む レビュー 人間やAIがプルリクエストを順にレビューしてマージする QA向けPlugin QAのエージェントが要件定義のIssueからQA観点とテストケースを作り、Playwrightで実行する ここからは、構成要素ごとに解説します。 施策を作るエージェント フローの起点は、施策を作る段階です。PM向けの社内Pluginに、施策を提案するスキルと、施策の要件を定義するスキルを用意しています。施策提案スキルで案を選び、要件定義スキルでGitHubのIssueにする、という順に使います。 施策提案スキル 施策提案スキルは、PMからテーマや領域を受け取り、取り組むべき課題を探すところから始めます。 最初に、専用のエージェントが情報を並列に収集します。社内ドキュメントからはKPIや戦略、コードベースからは既存の機能やデータスキーマ、GitHubからは既存のIssueとプルリクエスト、Notionからは仕様書や議事録などを集めます。あわせて、Google AnalyticsとSearch Consoleのアクセス解析のデータと、Web上の市場や競合の情報も取得します。 収集した結果をもとに、別のエージェントが複数の観点から施策のアイデアを出し、さらに別のエージェントがインパクトと実現可能性などで評価して優先順位を付けます。 PMは、順位付けされた提案の一覧から採用する案を選びます。採用した案は次に紹介する要件定義スキルに引き継ぎます。 要件定義スキル 要件定義スキルは、提案された施策の要件を定義します。 情報収集の段階では、仮説エージェントと収集エージェントを並列に動かします。仮説エージェントが仮説を立てると、収集エージェントはその仮説に沿って必要なデータを集めます。仮説エージェントは追加で集まったデータを受け取り、仮説を裏付けたり修正したりします。 続いて、施策の規模を判定します。ユースケースやユーザー種別が複数にまたがる場合は、MVPと優先度付きの拡張項目に分けます。そのうえで、収集したデータが仮説を裏付けているかと、技術的に実現できるかを整理して、統合ドラフトにまとめます。PMはこのドラフトをレビューし、修正や補足があれば伝えます。 PMがドラフトを最終承認すると、要件定義の親IssueをGitHubに作成します。 要件をIssueに分解するエージェント 要件定義のIssueを受け取るのが、Issue生成スキルです。要件定義IssueのURLを入力に、実装タスクのIssueを作るところまでを対話的に進めます。 最初に、要件定義Issueの本文とコメントを読んで要件を理解し、対象のコードベースを探索して既存の構造と実装パターンを把握します。 tech.findy.co.jp 設計の段階では、方針の異なる設計案を並列に作り、開発者が比較して設計方針を決めます。決めた方針をもとに、タスクに分解します。 tech.findy.co.jp Issueの作成は、専用のサブエージェントに切り出しています。サブエージェントは、要件定義Issueを親Issueとして再利用し、子IssueをSub-issueとして作成したうえで、Issue間の依存関係を設定します。依存関係を本文の #番号 ではなくGitHubのIssue依存関係機能（ blocked_by ）で登録しているのは、後段の計画エージェントが機械的に読めるようにするためです。 blocked_by は、あるIssueが別のIssueの完了を待つ関係を、Issue同士に設定する機能です。Sub-issueで「何を作るか」を親子に整理し、 blocked_by で「どの順に作るか」を表します。 Issueの依存関係から実装の順番を決める計画エージェント 並列実装を指揮するのが計画エージェントです。計画エージェントの役割は実行計画の作成と実装エージェントの起動に限られていて、コードの編集、worktreeの操作、GitHubへの書き込みはしません。 計画エージェントは親Issueを起点に、GitHubからopenなSub-issueと、それぞれの blocked_by を読み込みます。closedのIssueは対象から外し、closedのIssueへの依存は解決済みとして扱います。 開発者は、計画エージェントが提示した実行計画を確認します。確認が取れると、計画エージェントは、依存でつながったIssueのグループごとに実装エージェントを並列で起動します。 tech.findy.co.jp 並列で動く実装エージェント 実装エージェントは、依存でつながったIssueのグループごとに起動され、担当のIssueを実装してプルリクエストを作るまでを、完全に非対話で受け持ちます。 計画の承認が必要な場合は、先に計画だけを返す実装エージェントを起動します。開発者が計画を承認したあとで、改めて実装エージェントを起動します。 実装エージェントは、担当のIssueを依存の順に下から実装します。Issueごとにgit worktreeを作り、2番目以降のIssueは前のIssueのブランチをbaseにします。この時点のブランチはpushせず、手元に置いたままです。 tech.findy.co.jp グループの中に互いに依存しないIssueがある場合は、それらを並列に実装したあと、組み立てエージェントがリベースして依存の順に並べ直します。リベースを実行する権限は、このエージェントだけに持たせています。 並べ終わったブランチからプルリクエストを作成し、スタックプルリクエストとして登録します。 スタックプルリクエスト 実装エージェントは、プルリクエストをスタックプルリクエストとして登録し、そこで終了します。 tech.findy.co.jp プルリクエストの本文には、対応するIssue（ Closes #番号 ）、親Issue、依存しているプルリクエスト、セルフレビューなどの品質保証の結果を入れます。 開発者は、スタックを下から順にレビューしてマージします。下位のプルリクエストがマージされると、GitHubが上位のブランチを自動でリベースし、baseを付け替えます。図の例では、#201をマージすると#202のbaseがmainに付け替わります。どこまでマージされたかという状態はGitHubが持っているため、エージェントはマージを待ちません。 マージされたプルリクエストは、 Closes によって対応するIssueを自動でcloseします。closeされたIssueは、次に計画エージェントを起動したときの計画の対象から外れます。 QAのエージェント QAには、QA向けの社内Pluginを使っています。開発リポジトリとは別のQA用リポジトリで動かし、分析対象の開発リポジトリを設定で登録しておきます。 QA観点を作るスキルは、要件定義のIssueを仕様ソースとして読みます。NotionやFigmaのページも仕様ソースとして渡せます。まず仕様を抽出するエージェントが、キーワードと対象ファイルを決めて探索の範囲を絞ります。続いて、画面と操作フローを調べるエージェントと、変更による回帰リスクを判定するエージェントを並列に動かし、その間に要件がコードとテストで満たされているかを突き合わせます。 集めた検証項目は、テスト戦略のスキルで「テストコードで自動化するもの」と「QAテストで確認するもの」に分けます。QA観点にはQAテスト側の項目だけを展開し、テストコードが足りていない箇所は別のファイルとして出力します。 テストケースを作るスキルは、QA観点をもとに、前提条件、手順、期待値、ロールごとの結果欄を持つテストケースを作ります。各ケースには、ブラウザ操作で自動実行するAutoか、人間が目視で確認するManualかを付けます。判断に迷うケースはManualに寄せています。 作成した観点とテストケースは、QA基準のカテゴリごとにレビュー用のエージェントを並列に起動して、網羅性と品質を確認します。QA担当は、指摘のうちどれを反映するかを選びます。 Autoのケースは、Playwright MCPを使ってロールごとに順に実行します。結果は、失敗したケースのスクリーンショットを含むレポートとして出力し、元のテストケースには書き戻しません。Manualのケースは目視確認の一覧としてまとめ、QA担当が目視で確認します。 まとめ AIエージェントを開発フローに組み込むうえで大事なのは、AIに任せる範囲と人間が判断する部分を切り分けることだと考えています。 情報の収集、設計案の作成、実装、テストの実行といった作業はAIに委任し、施策の採択、設計方針の決定、実行計画の確認、マージ、QAの確認といった最終的な判断は人間が行います。 AIに委任して人間が最終判断するという線引きを決めておくことが、AIエージェントと一緒に開発を進めるうえでの前提になります。 開発フローのどこにAIエージェントを置くかは、チームによって答えが変わると思います。この記事の図が、自分たちのフローを見直すときのたたき台になればうれしいです。 ファインディでは一緒に会社を盛り上げてくれるメンバーを募集中です。興味を持っていただいた方はこちらのページからご応募お願いします。 herp.careers

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

自己紹介 こんにちは riataso です。 iOSエンジニアとして、TUNAG のアプリ対応を担当しています。 iOSDC への参加は今回で2回目です。最近は知り合いが次々と iOS から別のポジションへ移っていくことが多く、少し寂しさを感じていました。そんな中で、会場に iOS エンジニアがこれだけ集まっている景色を見ると、やっぱりいいなと思います。 はじめに 9月11日〜13日に有明で開催された iOSDC Japan 2026（ 公式タイムテーブル ）に、現地参加してきました。 今年はAI活用に関するトークが目立ちました。その中で多くの人が悩んでいるのは、 どこまで任せて、どこに人が線を引くか だと感じました。 このレポートでは、特に印象に残った2つのセッションを軸に、iOSエンジニアとしての向き合い方を整理します。 セッション① AI時代におけるiOS設計の守り方と人間の役割（遠藤拓弥さん） 9月12日に Track B で行われた、株式会社TVerの遠藤拓弥さんのスポンサーセッション（20分）です。AIで開発が速くなった結果、設計をどう守るのか、人は何を決めるのか、という話でした。（ fortee / スライド ） 概要 AIの活用で、TVerのマージ済みPR数は 1,619件から5,435件（約3.4倍） になったそうです。一方で、AIが速く書くほど設計は崩れやすくなります。問題はAIそのものではなく、AIにとって崩しやすい設計になっていることだとして、設計を作り替え、人が決めたことを仕組みに落とし込んできた、という内容でした。 人が整えている土台 アーキテクチャガイドラインの整備 機能単位でのパッケージ分割（AIが扱いやすく、壊れにくい境界を作る。Packageモジュールは約1年で22から204に） 依存方向をlintで制限し、CIで確認する 仕様書とテストの拡充 CLAUDE.mdやFigmaへの記録 AIには任せきれない判断 バグと仕様の見分け : 既存コードにある誤り（誤ったエラーコードの説明コメントなど）を正しいものとして読み、そのまま複製・拡散してしまう。 SwiftUIかUIKitかの選択 : UIKitを使っている34箇所には、SDKやOS標準がUIKit前提、SwiftUIに機能がない、特定のOSバージョンでSwiftUIが動かない、といったそれぞれの理由があり、その判断はAIには難しい。 感想 一番参考になったのは、「判断は人がする」で終わらせず、決めた内容をモジュール境界やlint、ルールファイルといった仕組みに落とし込んでいる点でした。レビューのたびに人が止めるのではなく、逆流する依存はlintとCIで検出するというように、人の判断を後から機械的に守れる形にしています。 AIが誤ったエラーコードの説明コメントをそのまま複製し、8ファイルを直す羽目になったという失敗例も印象的でした。AIの出力を確認せずに使わない、理由を説明できないコードは入れない、という当たり前のことを、個人の注意力ではなく仕組みで担保する必要があると感じます。 また、決めることの大変さはAIが速くなっても変わらない、というまとめにも納得しました。実装が速くなるほど、構造や仕様といった後から変えにくいものを先に固める価値は上がると思います。SwiftUIとUIKitの使い分けのような、SDKやOSの制約を踏まえた判断を人が持つ、という整理も、iOSエンジニアとして腹落ちしました。 セッション② スマホアプリ開発におけるハーネスエンジニアリングの取り組み（原隆幸さん） 9月12日に Track B で行われた、食べログを運営するカカクコムの原隆幸さんのスポンサーセッション（20分）です。食べログのアプリ開発チームが、AIを使った開発をどう整えているかが紹介されました。（ fortee ） 概要 食べログのアプリ開発チームは、「アプリ開発を誰でもできるようにする」というミッションのもと、スキルアップ、開発環境、変更容易性、コンテキスト、AI駆動プロセス、テストなど7つの領域に整理して改善を進めているそうです。 その中心にあるのが、ハーネスエンジニアリングです。AIに「何を伝えるか」を整える コンテキスト と、AIの出力を「どう検証し、どう矯正するか」を設計する ハーネス（ガードレール） を両輪として、あわせて「ハーネスエンジニアリング」と捉えている、という内容でした。 ポイント コンテキストは量より質 : 情報を詰め込むのではなく、単一の信頼できる情報源を保つ。 検証の自動化 : MaestroでUIテストを自動実行して、手動QAの負担を減らす。（発表後に公開された 公式ブログ では、テスト項目そのものをAIに作らせる取り組みも紹介されています） 継続的な改善 : CLAUDE.mdを育て続け、フィードバックループを作る。 感想 ハーネスエンジニアリングという考え方自体は以前から意識していましたが、実際にどんな単位で取り組んでいるのかを聞けたのが今回の収穫でした。AI活用をプロンプトの工夫に閉じず、スキルアップやテストも含めた開発環境全体の話として扱っている点が印象的でした。 中でも、AIに渡す情報（コンテキスト）と、出力を検証する仕組み（テスト・自動化）を両輪にしているところが参考になりました。足すのは簡単でも、減らして手入れするのは難しいので、CLAUDE.mdのような指示ファイルも、コードと同じように継続して育てる対象として扱う必要があると感じました。 2つのセッションから考える：「任せる範囲」と「人が引くガードレール」 2つのセッションは、同じことを別の角度から語っていると感じました。 層 人が担うこと 該当セッション 設計 アーキテクチャ、仕様、モジュール境界の決定 ① 情報 AIに渡すコンテキストの品質管理 ② 検証 テストの整備、最終的な動作確認 ①② 守る場所は、①が「構造（モジュールとlint）」、②が「情報（コンテキスト）と検証（テスト・自動化）」と、会社ごとに違っていました。それでも、AIに任せる前提で人が仕組みを整える、という方向は同じだと感じました。 実装そのものはAIに任せる流れが進む一方で、「 何を作るか、何が正しいか、どこで止めるか 」を決めるのは人に残る、というのが2つのセッションから受け取ったことです。 自分たちの現状 自分たちの TUNAG の iOS アプリでは、VIPER と Swift Package Manager によるマルチモジュール構成をとっています。AI向けには、CLAUDE.md にプロジェクトの概要や構成、ブランチ戦略をまとめ、コードスタイル・セキュリティ・テストのルール、PR作成やVIPERの機能追加といった定型作業のスキルやコマンドを用意しています。SwiftLint はビルド時に自動で動きます。レビュー用のガイドラインファイルも置いていますが、中身はコメントを日本語で書くといった最低限のものです。 今回の2社と比べると、次の違いがありました。 構造の守り方 : TVerさんは依存方向をlintで制限し、CIで確認しています。自分たちはVIPERの規約とスキルで案内する形が中心で、機械的に止める仕組みは多くありません。 仕様の持ち方 : TVerさんはMarkdownの仕様書を大きく増やし、機械可読な形にしていました。自分たちは、仕様をAIに渡す形としてまだ整理しきれていません。 検証 : UIの動作確認は人の目に頼る部分が大きく、食べログさんのような自動化は今後の検討課題です。 レビューでは、AIによるレビューと人によるレビューの両方が入る運用です。ただ、AIのレビューだけでは抜け漏れが出ることがあり、人が見て初めて気づく点も残っています。AIが生成したコードは見た目が整っているぶん、確認する側が「たぶん大丈夫」と流してしまう怖さもあります。何をAIに見てもらい、何を人が見るのかは、まだ整理しきれていません。 現地参加ならではの体験 今年も多くのエンジニアが会場に集まっていました。名刺交換アプリがあったおかげで、初めて話す方とも気軽に声をかけ合うことができ、前回よりも多くのエンジニアの方々とお話しできました。 ブースでは、pixivさんの企画アプリが印象に残っています。去年は、SwiftUIのModifierを題材にしたクイズ形式のアプリ「SwiftUIと秘密の修飾子」で、問題を解きながらクリアしていくものでした。今年は「ぴくしーる」という、自分のアイコンからデジタルシールを作り、シール帳のように集めて交換できるアプリでした。端末同士を近づけるNameDropを使って交換する仕組みで、それをきっかけに他の参加者の方と自然に交流できました。 2回目の参加ということもあり、去年よりも iOS について深く理解した状態で臨めました。その分、セッションやブースで得られる学びが増え、考えさせられることも多かったです。 今後見直していきたいこと すぐに何かを変えるというより、 自分たちの開発の進め方を一度立ち止まって点検したい と感じました。特に見直していきたい観点は次のとおりです。 レビューで見る観点 : AIレビューで抜け漏れが出ることがある以上、AIが生成したコードのどこを人が重点的に見るのかを、チームで揃えていきたいです。「既存コードのバグを仕様として実装する」という指摘を踏まえ、仕様の意図に関わる部分は人が確認する、といった整理から始めたいと思います。 AIに任せる範囲の線引き : 実装はAIに任せつつ、「仕様の判断」や「最終的な動作確認」は人が持つ、という整理は、2つのセッションに共通していました。自分たちの現場で、どこまでをAIに任せ、どこからを人が判断しているのかが明文化されているかを見直したいです。 AIに渡すコンテキストの整理 : 食べログさんの事例にあった「量より質」「単一の信頼できる情報源」を踏まえ、CLAUDE.mdなどの指示情報が増えすぎていないか、古い情報や重複がないかを調整していきたいです。 設計の守り方 : TVerさんの事例にあった、アーキテクチャガイドラインや機能単位のパッケージ分割は、AIが速く書くほど効いてくると感じました。ただし、チームの規模やテスト方針に見合わない過剰な整備は逆効果になりかねません。 自分たちの規模に合った粒度 を探りたいです。 おわりに AIで実装が速くなっても、「何を作るか、何が正しいか、どこで止めるか」を決める仕事は人に残ります。今回得た視点をチームで共有しながら、少しずつ自分たちに合った形に調整していきたいです。 スタメンではエンジニアを絶賛募集中です🙌 気になる方はこちらからアクセスをお願いします！ herp.careers