AI主導でFastAPIのWebサービスを作るときに 人間が構造化すべき境界線

AIを使えば実装は速くなりました。しかし、開発が止まる瞬間は今も変わらず「判断できなくなったとき」です。本発表では、FastAPIによる実プロダクト開発（NecoKeeper）の経験をもとに、AI主導開発において人間が構造化すべき境界（データモデル、認証、業務ルール、E2Eの正解定義）について整理しました。静的解析・自動テストで守れるものと、人間が担うべき判断の違いを考えます。

PyCon mini Shizuoka 2026での登壇用スライド
https://shizuoka.pycon.jp/2026/
https://pycon-shizu.connpass.com/event/372943/

作ったプロダクト：https://devpost.com/software/necokeeper

Transcript

1. AI主導でFastAPIのWebサービスを作るときに 人間が構造化すべき境界線 オカザキ（PyCon mini Shizuoka 2026） 1
2. ⾃⼰紹介 名前: オカザキ （@dario_okazaki) • Web系エンジニア → PM（SE） • 過去個⼈開発したもの：Webサービス、アプリ、ノベルゲーム等 • 「⾃分はコードを書かない」縛りでハッカソンKiroween参加 • 保護猫管理WEBアプリ「NekoKeeper」を開発 Pycon mini shizuokaでは過去 2020年に「Pythonでデスクトップアプリを簡単に作る⽅法」で登壇 2
3. 今⽇話すこと / 話さないこと 【話すこと】 • AI主導開発で、人間が先に決めるべきこと • 個人開発でAIを使って良かった点・つまずいた点 【話さないこと】 • 各技術の詳細な使い方 • プロンプトの細かい書き方 3
4. はじめに 個⼈開発で「途中まで作って⽌まる」を何度も経験 • 手を動かす • 少し動く • 触らなくなる 4
5. よく⾔われる理由 個⼈開発で「途中まで作って⽌まる」を何度も経験 • 手を動かす • 実現方法が分からない • エラーが直せない • 時間がない • モチベーションが続かない 5
6. どれも要因だが、決定打ではない 6
7. 本当の原因（仮説） • 開発が⽌まる瞬間は「判断できなくなったとき」 • 何が正しいか分からない • これでいいのか決められない 7
8. 本当の原因（仮説） • 開発が⽌まる瞬間は「判断できなくなったとき」 • 何が正しいか分からない • これでいいのか決められない 8
9. AIが導⼊して解消した問題と残る問題 9
10. 問題は気合ではなく、判断可能性の設計 10
11. NecoKeeperの紹介 • 保護猫団体向けのAI活⽤Webアプリ • 紙運⽤（世話記録‧医療メモ）をデジタル化 • 保護から譲渡までを⼀元管理 参照: https://devpost.com/software/necokeeper 11
12. NecoKeeperで解決したかった現場課題とPOC状況 実際の保護猫カフェでPOC運⽤中。 ボランティアが紙で⼊⼒していた記録を管理者がエクセルで⼊⼒、⾃治体へ世話記録を毎年提出する。 現場は⽇々の記録。簡単に⼊⼒したいのと短い期間を⾒返せればばいい。 管理者、⾃治体は⻑い期間の記録を閲覧、検索、保管したい 記憶の期間がペルソナによって違う。 12
13. NecoKeeperの規模感 画⾯は31画⾯ DB はSQLiteで15テーブル コード⾏数 • Backend Python: 10K • フロンエンド：html 7K, JavaScript: 10K 主要技術 FastAPI / SQLAlchemy / Alembic / Pydantic Jinja2 / Vanilla JavaScript / SQLite Ruff / mypy / pytest / MCP / WeasyPrint 13
14. NecoKeeperの代表機能（5つ） • 保護猫マスタ管理 • 世話記録⼊⼒/可視化（公開フォーム + 管理画⾯） • 医療記録/処置管理 • ⾥親応募/譲渡管理 • 帳票出⼒ + Automation API連携 14
15. Kiro / Kiroween について Kiro: Agentic AI開発を⽀援するIDE/CLI • SPEC とVibe Codingの使い分け Kiroween: Kiro活⽤を条件とする公式ハッカソン • 期間は2025/10/31〜2025/12/5 • NecoKeeperは提出作品（Devpost公開） 参照 • https://kiro.dev/ • https://kiroween.devpost.com/ 15
16. 16 ⼀か⽉間である程度動くものを開発する必要があった
17. 開発の前提とKiro 「⾃分はコードを書かず、設計意図と制約を渡す」縛り 17
18. 壊れたポイント 「壊れる」＝前提のズレ • 画⾯ごとに挙動が違う • 同じデータの意味が場所ごとにズレる • 機能追加時に思わぬ副作⽤が出る 18
19. 機械で直せる問題 検知ルールが明確な問題は、AI + ⾃動化で回せる • フォーマット/静的解析: Ruff • 型不整合: mypy • 回帰不具合: pytest • ⼊⼒整合: Pydantic 19
20. 難しい問題（先に決めるべきもの） • データモデル/テーブル構造の初期設計 • ビジネスロジックと実装の整合 • 「何を正とするか」の定義 「何を正とするか」今回は⼈間によるE2E（ブラウザ操作）で確認を実施 20
21. それぞれの担保⽅法 • データモデル/テーブル構造の初期設計 → スプレッドシートなどで事前に設計 • ビジネスロジックと実装の整合 → SPEC＋テストコードで確認 • 「何を正とするか」の定義 → ⼈間によるE2E（ブラウザ操作）で確認を実施 21
22. E2Eを⼈間がする理由 ⼈間が検知しやすい（伝えにくいもの）を確認 • 導線の⾃然さ • 画⾯崩れ • 違和感 • 微妙なUX破綻 22
23. 3つのズレ 壊れるのはコード単体より、前提のズレ • 認証実装のズレ • ログイン判定の⽅法が揃っていない • データ定義のズレ • 何を正として保存するかが曖昧 • 実装場所のズレ • どこでルールを担保するかが分散 23
24. 「認証実装のズレ」について 【Before】 • 画⾯単位で実装、 • 判定場所が分散 • 不整合発⽣ 【After】 • 認証仕様を先に⽂書化 • ミドルウェア‧共通処理に集約 • 未認証時の遷移、レスポンスコードをまとめる 学び：認証は「実装で合わせる」のではなく「仕様を先に固定する」 24
25. 「データ定義のズレ」について （例１ 猫の区分） • 初期案（AI提案）: ⼦猫 / 成猫 / ⽼猫 • 現場ヒアリング: 外⾒で年齢判定は難しく運⽤上も粗い • 判断: ⽉齢中⼼の⼊⼒へ変更（必要時は推定フラグ） 学び: わかりやすさより、現場で意味があるか 25
26. 「データ定義のズレ」について （例2 餌の⼊⼒） • 初期案: メーカー/商品をマスター管理して記録 • 検討: ⽇々⼊⼒の負荷が⾼い、⽬的（在庫管理等）が曖昧 • 判断: 初期リリースでは⾒送り、将来拡張へ 学び: 機能追加より運⽤コンセプトを優先 26
27. 「実装場所のズレ」について • 状況: 既存記録編集で「排便なし」に変更時、便の状態が残って保存エラー • 問題: 画⾯⼊⼒順に依存し、結果が変わる • 判断: ルールはサーバー側で統⼀し、⽭盾値を⾃動クリア 学び: 業務ルールはバックエンドで⼀貫して担保する 27
28. FastAPIで固定すべき構造 28
29. 考える基準 • 前提ドキュメント（Spec相当）：⽬的、制約、受け⼊れ条件 • 判断ログ：論点、採⽤理由、⾒直し条件 • ズレ防⽌ルール：認証、データ、実装場所 「将来なぜそうしたか説明できないと困る判断」だけ残す 29
30. AIへの運⽤ルール • ⼈間：⾃動チェックの定義/ どこを⼈間が確認するか（例：E2Eの実施） • AI：実装前のドキュメント参照、実装後の⾃動チェック反復 判断軸を運⽤で保ち続ける 30
31. ⼤事なこと 最終責任は⼈間がする。 そのための判断の⼟台を持ち続ける。 31
32. まとめ • AIで実装は速くなる。でも、判断は残る • ズレを防ぐ判断は⼈間が引き取る • 最終的な成果物の責任は⼈間が持つ AIはときに「間違えるのは⼈間」と⾔う。 だからこそ、判断軸を先に設計して運⽤する。 32
33. おわり • これは正解の提⽰ではなく、2025年12⽉時点での個⼈の試⾏錯誤の記録 • AI駆動開発は変化が速い • 現時点で有効だとわたしがおもった進め⽅の⼀例として共有 33
34. 宣伝 Kiroweenに出たことで、海外ハッカソンに出ることが怖くなくなった。 AWS 10000 AIdeas Competition に応募したらセミファイナルに選出されました。 3⽉中旬：AWS Buildersで記事公開予定。 読んでよかったらいいねをしてください。 34