AIに任せられるFlutterコードベースを作る 〜仕様をコードで表し、ハーネスで守る〜

FlutterKaigi 2026 での発表資料です。

2025年、AI に実装を任せられるようになり、アプリエンジニア以外のメンバーも Flutter アプリの実装に参加するようになりました。一方で、アプリエンジニアの頭の中にあったアーキテクチャのルールが共有できておらず、レビューでの指摘と往復が増えました。

この発表では、申請・経費精算のモバイルアプリを題材に、AI に任せられるコードベースをどう作ってきたかをお話しします。

- 仕様をコードで表す: 明細の種類や金額を sealed class などの型で表し、ルールに反するコードをコンパイラや lint で止める
- ハーネスで守る: 決定的に表せるものは型・lint・CI に置き、表せない知識だけを Skill と Subagent で AI に渡す
- 結果で評価する: eval（AI の振る舞いの単体テスト）で、AI がルールを読めているかを確かめる
- 育てる: レビューの指摘から Skill の更新を AI が提案するループを回す

任せられる範囲は、AI の能力ではなく、アーキテクチャとハーネスで決まる、という考え方をまとめています。

Transcript

1. AIに任せられるFlutterコードベースを作る 〜仕様をコードで表し、ハーネスで守る〜 FlutterKaigi 2026 yohei
2. final me = Engineer('yohei'); yohei myohei LayerX バクラク事業部 (2023-09 -) バクラク 申請・経費精算 プロダクトエンジニア Android → Go → Flutter（約5年） 最近は Go が多め（書いているのは AI） © LayerX Inc.
3. 今日の題材 今日の題材: 申請・経費精算のモバイルアプリ Flutter で作っている。2024年9月にリリース 申請: SaaS を使ってよいかの承認や、受け取った請求 書の支払いの依頼など 経費精算: 立て替えたお金を、会社に請求する AI が入力を補助し、簡単に申請できる © LayerX Inc. 3
4. 前半: 背景 1. 仕様をコードで表現する 2. なぜ仕組みで守るのか アジェンダ 後半: AI と作るハーネス 3. AI ハーネスを作る 4. 仕組みを評価する 5. 仕組みをメンテする 締め 6. 結果と課題 7. まとめ
5. 1. 仕様をコードで表現する 業務のルールを、型とコードの構造で表す
6. 1. 全体像 今日お話しする3つの仕様 ① ② ③ 金額を分ける明細と、分けない明細 日本円と、外貨 金額で、経路が変わる 明細の種類 金額 承認経路 これらの仕様が、複雑に絡み合って動く © LayerX Inc. 6
7. 1. ① 明細の種類 1つの申請に、按分する明細としない明細が並ぶ 開く 30,000円を 営業部 50% マーケティング部 50% 申請（明細が2つ） © LayerX Inc. 会食を、営業部とマーケティング部で 50% ずつ 7
8. 1. ① 明細の種類 明細には種類がある 種類ごとの持つ値の違いを型で表せる 種類が増えても、switch で漏れなく分岐できる （どれにも当てはまらない場合）で受けると、新 しい種類も気づかないうちに入る → lint で禁止 _ 概念です。実際のクラス名は英語 © LayerX Inc. 8
9. 1. ② 金額 外貨にも対応した金額を、型で分ける 日本円は金額だけ。外貨は通貨・金額・レートを持つ（USD 200.00 × 150.00 ＝ 30,000円） 明細の種類ごとに、使える金額の型が決まっている どちらも円換算できる → 承認経路は円で判定する © LayerX Inc. 9
10. 1. ③ 承認経路 承認経路は金額で変わり、動く仕組みは申請の種類ごとに違う 例: 5万円以上になると、部長の承認が1段増える。入力に合わせて、その場で変わる 申請の種類 経路（金額） 経路（明細合計） 外貨 取引先 経費精算 • • 支払申請 • • • 申請種類X • • 申請種類Y • …（全17個） … … … … 金額と承認者は例。実際の経路と閾値は会社ごとに設定する © LayerX Inc. 10
11. 1. まとめ 仕様ごとに、守る層を変える 金額 明細の種類 承認経路の連鎖 取り違えるとコンパイルエラー 種類が増えたら、コンパイラが教える 型でも lint でも表せない（3章で説明） 型 switch + lint AI に渡す知識 → 3章で「どうやって AI に渡しているか」 © LayerX Inc. 11
12. 2. なぜ仕組みで守るのか
13. 2. なぜ仕組みで守るのか 2025年: アプリエンジニア以外も実装に参加した これまで 実装するのは、アプリエンジニアだけ アーキテクチャのルールは、アプリエンジ ニアが頭に持ち、実装時やレビューで守る © LayerX Inc. 2025年 Claude や ChatGPT（Codex）などの登場 で、Web のエンジニアなども実装に参加 アプリエンジニア以外の PR が 月 26〜71 件 ルールが共有できておらず、指摘と往復が 起きた 13
14. 2. なぜ仕組みで守るのか アプリエンジニア以外の PR は、往復が多かった レビューコメント数（1 PR あたり平均） 4.1 アプリエンジニア それ以外 7.7 約1.9倍 レビュー後の追加コミット（1 PR あたり平均） アプリエンジニア それ以外 2.0 3.4 約1.7倍 集計: 2025-01〜2026-09 のマージ済み PR（bot を除く）。アプリエンジニア 573 件 / それ以外 451 件 © LayerX Inc. 14
15. AI 向けに作り変える 人向けに作ってきたもの、人の頭にしかなかったもの を、AI が使える形に © LayerX Inc. 15
16. 3. AI ハーネスを作る
17. 3. AI ハーネス ハーネスとは AI が外れずに、長く走り続けられるように 用意する枠 この発表では、3つで構成する 型 書けない lint・CI 書いたら落ちる Skill・Subagent 知識を渡す プロポーザルにあった Specification は、具体的すぎたので今日は抜きました。ごめんなさい © LayerX Inc. 17
18. 3. AI ハーネス 決定的に表せるものは、決定的な層に置く 決定的 非決定的 型 lint・CI 書けない 書いたら落ちる 毎回同じ結果 機械が止める © LayerX Inc. Skill・Subagent 知識を渡す 毎回同じとは限らない AI が読んで判断する 18
19. 3. AI ハーネス ここからは、lint と Skill・Subagent の作り方 型の設計は1章で。ここからは、自分たちで作るもの © LayerX Inc. 19
20. 3. lint の作り方 Good / Bad を渡すより、lint を作らせる Good / Bad を AI に伝える 伝われば守る。抜け落ちれば外れる 毎回同じとは限らない lint にする 書いたら、必ず落ちる ルールが決まれば、AI がすぐ作れる lint を作る手順も Skill にしている（ create-lint-rule ） ① 判定ゲート: lint にすべきか。標準 lint で足りないか / 1ファイルで判定できるか / 誤検知を抑えられるか ② 違反の実測: 今のコードに、違反が何件あるか ③ scaffold: ルールとテストの雛形を作る ④ TDD: 違反する例・しない例のテストから実装する © LayerX Inc. 20
21. 3. lint の作り方 今ある lint の例 lint no_default_on_sealed_switch avoid_riverpod_annotation avoid_use_datetime_now no_throw_on_enum_unknown no_cross_feature_import ルール sealed の switch で _ を使わず、すべてのパターンを網羅する @riverpod を使わない DateTime.now() ではなく clock.now() サーバーの enum に知らない値が来ても throw しない Feature をまたいで import しない ※ 歴史があるので、懇親会で話しましょう © LayerX Inc. 21
22. 3. Skill の作り方 ドキュメントの読み手が、人から AI に変わった 昔: 人が読むアーキテクチャ文書 人が思い出さないと、読まれない 分からなければ、書いた人に聞ける 今: AI が読む Skill AI が、必要なときに自動で読む 書いてあることしか知らない 例: 申請フォームの状態管理の文書は、今は Skill への索引だけが残っている © LayerX Inc. 22
23. 3. Skill の作り方 「いつ読むか」まで書く いつ読むか を書く → AI が自分で読みに行く 中身は全体像（1章の Observer の表） 禁止は、できるだけ lint で落とす © LayerX Inc. 23
24. 3. Subagent の作り方 役割ごとに Subagent を作り、Skill を持たせる プラン 実装 テスト レビュー Subagent Subagent Subagent Subagent plan-reviewer dart-flutter-specialist test-writer implementation-supervisor 持たせる知識 持たせる知識 flutter-test-mocking REVIEW.md request-form-specialist 持たせる知識 request-form-state-expert などの Skill © LayerX Inc. 持たせる知識 アーキテクチャ・ ドメインの知識 （どうレビューするか） 24
25. 3. まとめ 決定的に表せるものは、決定的な層に置く 決定的 非決定的 型 lint・CI Skill・Subagent 金額の種類 明細の種類 switch の網羅 @riverpod を使わない など 承認経路の連鎖の知識 役割ごとの Subagent 非決定的な部分は、狙いどおりに動くかを確かめる → 4章 © LayerX Inc. 25
26. 4. 仕組みを評価する
27. 4. 正解の決め方 過程は縛らず、結果で評価する eval = AI の振る舞いの 単体テスト。お題を出して、結果を機械で判定する 過程を縛らなければ、モデルの進化の恩恵を、そのまま受けられる 「どう作ったか」ではなく「何ができたか」を見る © LayerX Inc. 27
28. 4. 正解の決め方 例: 禁止された書き方を頼まれても、断れるか © LayerX Inc. 28
29. 4. ぶれを見る 1回ではなく、3回回す AI は非決定的。1回の合格だけでは、たまたま通っただけかもしれない ケース を使う で書き直してと頼まれても断る ファイルを読むと、そのファイル用のルールを AI が読める 実際の作業でも、そのファイル用のルールを AI が読める 全体のルールを守る clock.now() @riverpod © LayerX Inc. 合格 3/3 3/3 3/3 1/3 3/3 ケースの作り方 1ケース ＝ 1ルール 判定は機械で（ファイルの中身・呼んだ道 具・最終レスポンス） 「やらない」が正解のケースを必ず入れる お題は、ルールの文言を引かず普段の頼み 方で 29
30. 4. ケースの作り方 コアな部分から、ケースを作る どこから どう 進め方 外れたときの影響が大きいルール 何度も指摘してきたルール ルールの文とファイルを渡して case.json を作らせる ルールを外すと落ちる → 戻すと通る コアな部分 AI に書かせる TDD で 期待する結果を eval にしておけば、Skill の改善も AI に任せられるようになる ただ、トークンは安くない。だから、コアな部分から © LayerX Inc. 30
31. 5. 仕組みをメンテする
32. WIP 5. AI が更新する AI が読むものは、AI が更新する レビューで指摘が出る Skill を読んで実装する 同じ指摘を出にくくする Skill を 育てる 集めて、Skill の更新を提案 GitHub のレビューを集める Skill eval で確かめて、取り込む モバイルのエンジニアが確認 © LayerX Inc. 32
33. 5. メンテナンスの実態 体験に直結する判断は、まだ人が決める 人が決めていること AI の提案を、Skill や REVIEW.md に書いていいか 例: ローディングで画面全体を止めるか、その場だけ出すか。体験に直結するので、AI にはまだ決 められない これから 人が見送った 理由 も残し、次の提案で AI に読ませる 体感として、同じ指摘は減り、クオリティも上がってきている © LayerX Inc. 33
34. 6. 結果と課題
35. 6. 結果 過去の指摘は、今どの層で止まるか レビューでしていた指摘 フラグを持たせるのではなく、sealed class にして アノテーションを使わず、Provider は手で書いて 業務ルールは、決まった部品に分けて書いて © LayerX Inc. 今止まる層 型 lint Skill 35
36. 6. 課題 まだまだ、これから 詰まる所は「ルールを決めること」に移った 独自クラスの説明ができていない。暗黙知が残っている 体験の判断（ローディングの出し方など）の基準を、まだ言葉にできていない eval を増やし、PR マージ前に自動で回す。モデルを変えたときも回す ルールが決まったら、lint も AI が自動で作る ハーネスを、モバイル以外のメンバーも含めたチームで育てる © LayerX Inc. 36
37. 7. まとめ
38. 7. まとめ 任せられる範囲は、アーキテクチャとハーネスで決まる まず: 仕様をコードで表し、AI が動けるアーキテクチャ を作る そのうえで守る: 決定的に表せるものは決定的な層へ（型 → lint・CI → Skill） 自由にさせる: 過程は縛らず、結果で評価する。知識は AI に更新させ続ける © LayerX Inc. 38
39. 明日からの一歩 © LayerX Inc. ※ 実際に動かすには --allowedTools などの指定が要ります 39
40. ありがとうございました