「ドキュメントドリブン」でFlutter開発を加速する

「ドキュメントドリブン」 でFlutter開発を加速する 2026年7⽉17⽇ 第10回 FlutterGakkai 奥澤 俊樹 / 株式会社メドレー

⾃⼰紹介 奥澤 俊樹 ● 株式会社メドレー ○ ⼈材プラットフォーム事業部 ■ CTO室 ● モバイルアプリケーションエンジニア ● 最近の趣味はうどん 著作 ● 奥澤 俊樹, (2021), “Jetpack ComposeによるAndroid MVVMアーキテクチャ⼊⾨”, Next Publishing ● 奥澤 俊樹 他, (2023), “Software Design 2023年6⽉号「クリーンアーキテクチャとは何か？ モバイルアプリ 開発における実践」”, 技術評論社 ● 奥澤 俊樹 他, (2024), “［⼊⾨］ドメイン駆動設計 ――基礎と実践‧クリーンアーキテクチャ”, 技術評論社 ©2026 MEDLEY, INC. 3

「ドキュメントドリブン」でFlutter開発を加速する メドレーでは、「ドキュメントドリブン」の⽂化を⼤切にしています。 私たちは、仕事を始める際にドキュメントを先に書き出し、それを駆動⼒として活⽤して⾃らやチームを効率的 に動かします。ドキュメント化されていないことにより多くのメンバーが同じことを1から考えたり、読めばわか ることを⼝頭伝承したりするような時間の浪費を予防します。ドキュメントもシンプルで無駄のないものを志向 することで、将来のチームの⽣産性にも⼤きく貢献します。 https://www.medley.jp/recruit/culture/ 本⽇は、Flutterを⽤いたアプリ開発に「ドキュメントドリブン」を取り⼊れ、開発を加速している話をします。 ©2026 MEDLEY, INC. 4

• https://www.medley.jp/recruit/culture/

何故、今ドキュメントか ドキュメントはこれまでも常に⼤切であった。しかし、AIが普通に活⽤されるようになった今、ドキュメントは これまでよりもさらに⼤切になっている。 「ドキュメントドリブン」の⽂化はAIの活⽤と相性が良い。AIとドキュメントを適切に活⽤することで、チーム の開発⽣産性の向上につながる。 だから、今こそドキュメントに注⽬している。 ©2026 MEDLEY, INC. 5

活⽤するドキュメント 今⽇は以下のドキュメントについて話します。 ● ● ● ● ● Architecture Decision Records（ADR） Coding Rules（コーディング規約） Specification（仕様書） Design Doc Document Comment これらのドキュメントをGitのリポジトリにコミットし、プロダクトマネージャーやQAなど、エンジニア以外の職 種も活⽤しています。 ©2026 MEDLEY, INC. 6

Architecture Decision Records（ADR） 「特定のアーキテクチャ決定を記述した短いテキストファイル」（Mark Richards, Neal Ford (2022), p.289）。以 下の記事で初めて紹介された。2026年現在、広く利⽤されている。 Documenting Architecture Decisions https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions アーキテクチャ決定に関する背景、決定、影響を記述し、意思決定を記録する。意思決定事項がドキュメント化 されることでオンボーディングのコストを削減できると共に、トレードオフ判断を記録することで将来のアーキ テクチャ変更判断を助ける。 弊チームでは、オフラインファーストの設計⽅針、レイヤ間の依存ルール、設計パターン（MVVM、 Repository）、等のFlutterアプリのアーキテクチャ設計判断、バックエンドとのインタフェース設計、セキュリ ティリスクの受容判断について意思決定記録を残している。 ©2026 MEDLEY, INC. 7

• https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions

Architecture Decision Records（ADR） # 7. オフラインファーストの設計 Date: 2025-10-29 ## Status Accepted ## Context ネットワークが不安定‧利⽤できない状況においても最低限のユーザー体験を提供するため、オフラインファー ストなアーキテクチャを構築したい。[データレイヤの設計](0006-design-of-data-layer.md)において、 Repositoryパターン、及びResult型を使⽤したエラーハンドリングの仕組みが確⽴されている。本ADRでは、こ の既存のアーキテクチャを元に、オフライン対応のためのアーキテクチャを定義する。 ~~以下略~~ ©2026 MEDLEY, INC. 8

Coding Rules（コーディング規約） ADRは抽象度の⾼い決定事項を記載しているが、Coding Rulesとしてより具体性の⾼い制約を設けている。いわ ば実装レベルのガイドラインである。 Dartの書き⽅はlintで制約する。それ以外をCoding Rulesとしてドキュメント化し、制約している。 ● ● アクセシビリティに関するCoding Rules ○ WCAG Aに準拠するレベルを⽬指したコーディング規約 ○ 例えば、画像に対するDescriptionの書き⽅、読み上げ順の制御、コントラスト⽐ ○ 規約を設けた結果、リリース時のアクセシビリティテストの指摘事項ほぼなし セキュリティに関するCoding Rules ○ FlutterのSecure Codingに関するプラクティスを集めたコーディング規約 ○ 例えば、機微データの保存時の `flutter_secure_storage` の利⽤、WebViewのJavaScriptデフォル ト無効化、難読化 ○ 規約を設けた結果、リリース時の脆弱性診断の指摘事項なし ©2026 MEDLEY, INC. 9

Coding Rules（コーディング規約） ### 4. 読み上げ⽤の属性が適切である #### 重篤度 `MAJOR` #### チェック頻度 毎回 #### チェック⽅法 `semanticLabel` において適切な説明がなされていること。以下の例では、前者は画像に対して適切な説明がな されていない。後者のように、何の画像なのか？を適切に説明すべきである。 - ❌ `semanticLabel: '画像'` - ✅ `semanticLabel: '商品Aの外観写真'` ©2026 MEDLEY, INC. 10

Specification（仕様書） チームの合意形成の核⼼となるドキュメント。「何を作るのか」をチームで合意する。弊チームではSpec駆動開 発を取り⼊れているため、仕様書の作成‧保守は開発プロセスにおける⾄上命題である。 ● ● プロダクトマネージャー‧エンジニア‧QAなど、Pull Request上で職種を跨いで仕様のレビューを⾏い、 合意形成する 仕様書を起点としてエンジニアは設計を、QAはテスト設計‧テストケース作成を⾏う 仕様書の作成段階で、仕様間の⽭盾‧考慮不⾜‧認識齟齬などを減らすことで、品質向上‧⼿戻りの防⽌に繋げ る。職種横断で仕様書の作成をAIフレンドリーにしていくのを試⾏錯誤中。grill-meは有⽤。 ©2026 MEDLEY, INC. 11

Specification（仕様書） # A画⾯ 詳細仕様書 ## 詳細仕様 [Figma](ここにFigmaのリンクが⼊る) <img width="300" src="./img/screenshot.png" /> ここに概要を書く。 ### 画⾯要素B 画⾯要素Bに関する仕様を書く。 ## イベントトラッキング イベントトラッキングに関する仕様を書く。 ©2026 MEDLEY, INC. 12

Design Doc 仕様書や修正仕様を元に、設計⽅針（どう作るのか）を記載し、⼤局的な設計のレビュー‧合意形成を⾏う （Ishikawa Munetoshi (2024), p.69）。 コードレビューでは局所的な変更しかレビューできず、往々にして設計の破綻が露呈するタイミングが遅くな る。その場合、⼤きな⼿戻りが発⽣してしまい、開発者⽣産性を低下させる。また、設計に関する明⽰的なレ ビュー⼯程が存在せず、設計品質の向上が難しい。 仕様書の作成後、実装着⼿前にDesign Docを作成‧レビュー‧合意形成を⾏うことで、⼤局的な設計の承認プロ セスをシフトレフトする。これによって、⼿戻りの防⽌‧設計品質の向上を図り、開発者⽣産性を向上させる。 ただし、重厚なDesign Docはレビューコストがかかり、却って開発者⽣産性を低下させ得る。⾃明なことは省略 する、論点を絞る、などを⼼がけてDesign Docを書くと良い。そもそも設計が⾃明な場合はDesign Docを書く必 要はない（軽微なbug fixなど）。Design Docは保守せず、書き捨てで良い。 ここでもgrill-meは有⽤。 ©2026 MEDLEY, INC. 13

Design Doc # A機能 Design Doc ## 設計の⽅針 ### 全体構成 既存のアーキテクチャパターン（ViewModel + UiState + Navigator）に従い、以下を新規作成する。 ~~省略~~ ### レイヤ構成 各レイヤの責務は以下の通り。 ~~省略~~ ©2026 MEDLEY, INC. 14

Document Comment コードに対するドキュメンテーション。class、メソッド、プロパティなどの契約として記述する。 実装を読まずともメソッドの概要を把握するのに役⽴つ。適切に書かれた、かつ適切に保守されている Document Commentは、コードリーディングや調査のコストを下げ、開発者⽣産性を向上させる。Coding Agentに対しても同様（多分）。 ただし、⾃明なコードに対するDocument Commentは冗⻑になりがち（ `getName()` がNameを返すのは当た り前）。Document Commentを読むことで情報量が増えないなら、Document Commentの作成‧保守コストは もちろん、読む時間もムダになるので開発者⽣産性の低下につながる。Document Commentを書くべき場合を 完全にルール化することは難しいが、冗⻑にならない場合は常に書くのが好ましい。 ©2026 MEDLEY, INC. 15

Document Comment /// 成功または失敗を表現する型 /// /// Repositoryのメソッドの戻り値として使⽤し、エラーを型レベルで表現する。 /// これにより、エラーハンドリングの漏れを防ぎ、適切なエラー処理を強制する。 /// /// [T] 成功時の値の型 /// [E] 失敗時のエラーの型 /// /// ## 使⽤例 /// /// ```dart ~~省略~~ /// ``` @freezed sealed class Result<T, E> with _$Result<T, E> { ©2026 MEDLEY, INC. 16

ドキュメントの役割を整理する Architecture Decision Records（ADR） アーキテクチャレベルの制約を 設ける Coding Rules（コーディング規約） コードレベルの制約を設ける Specification（仕様書） 「何を作るのか」の合意形成を行 う Design Doc 「どう作るのか」の合意形成を行 う Document Comment コードのインタフェースの契約を 明示する ©2026 MEDLEY, INC. 17

ドキュメントの役割を整理する Review Review Review Review MCP Figma アノテーション Specification 実装 Design Doc Document Comment Test Cases ADR ©2026 MEDLEY, INC. Coding Rules 18

⼈間は品質‧価値に責任を果たす ● ● ● AIによるコーディングでアプリのリリースは30%増えている ⼀⽅で、ユーザー数の増加は⾒られない。誰も使わないアプリが⼤量⽣産されている AIによってアプリを量産できるようになった‧開発速度が上がったからこそ、⼈間がしっかりと品質‧価値 の向上に責任を果たすことが求められている Writing Code vs. Shipping Code: Productivity Effects Across Generations of AI Coding Tools (Mert Demirer, Leon Musolff, Liyuan Yang, (2026)) ©2026 MEDLEY, INC. 19

まとめ ● ドキュメントはずっと⼤切だったが、AIを活⽤するために⼀層⼤切になっている。 ● 「ドキュメントドリブン」⽂化はAIとの相性が良い。ドキュメントとAIを活⽤することで、職種を跨いで チームの⽣産性を向上できる。 ● ドキュメントの作成をAIに委譲しつつ、バリューストリームの各ステップで⼈間がドキュメントをレビュー する。⼈間は品質‧価値の向上に集中できる。 ● ただし、ドキュメンティングにAIを活⽤する場合、レビュー不可能な量のドキュメントが⽣成されることが ある。⼈間がレビューしきれないと品質‧価値に責任を持つことができない。そのため、「シンプルで無 駄のない」ドキュメントを志向することが好ましい。 ● AIによって誰でも⾼速に開発できるようになったからこそ、⼈間は品質‧価値に責任を持つことが必要であ る ©2026 MEDLEY, INC. 20

WE ARE HIRING Flutterエンジニア ⼤募集中 ©2026 MEDLEY, INC.

参考資料（1） ● ● ● ● ● ● Documenting Architecture Decisions, https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions （最終アクセス 日：2026/07/09） メドレーのカルチャー, https://www.medley.jp/recruit/culture/ （最終アクセス日：2026/07/09） Mark Richards, Neal Ford, 島田浩二 訳, (2022), 「ソフトウェアアーキテクチャの基礎」, オラ イリー・ジャパン 西見公宏, 吉田真吾, 大嶋勇樹, (2026), 「実践Claude Code入門」, 技術評論社 Munetoshi Ishikawa 他, (2024), 「エンジニアチームの生産性の高め方」, 技術評論社 Munetoshi Ishikawa, 「Design Doc の書き方」, https://speakerdeck.com/munetoshi/how-to-write-a-design-doc-ja-ver-dot （最終アクセス 日：2026/07/09）

• https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
• https://www.medley.jp/recruit/culture/
• https://speakerdeck.com/munetoshi/how-to-write-a-design-doc-ja-ver-dot

参考資料（2） ● Mert Demirer, Leon Musolff, Liyuan Yang, (2026), “Writing Code vs. Shipping Code: Productivity Effects Across Generations of AI Coding Tools”, National Bureau of Economic Research