---
title: 「ドキュメントドリブン」でFlutter開発を加速する
tags: 
author: [okuzawats](https://www.docswell.com/user/okuzawats)
site: [Docswell](https://www.docswell.com/)
thumbnail: https://bcdn.docswell.com/page/8JDKMX5KEG.jpg?width=480
description: 第10回 FlutterGakkai（2026年7月17日開催）のスポンサーセッション発表資料です。
published: July 17, 26
canonical: https://www.docswell.com/s/okuzawats/KDM98G-document-driven
---
# Page. 1

![Page Image](https://bcdn.docswell.com/page/8JDKMX5KEG.jpg)



# Page. 2

![Page Image](https://bcdn.docswell.com/page/VEPKRPG378.jpg)

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


# Page. 3

![Page Image](https://bcdn.docswell.com/page/27VVR26N7Q.jpg)

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


# Page. 4

![Page Image](https://bcdn.docswell.com/page/5JGLMRN57L.jpg)

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


# Page. 5

![Page Image](https://bcdn.docswell.com/page/47QYRVQLEP.jpg)

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


# Page. 6

![Page Image](https://bcdn.docswell.com/page/KE4W8MN5J1.jpg)

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


# Page. 7

![Page Image](https://bcdn.docswell.com/page/L71Y2852JG.jpg)

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


# Page. 8

![Page Image](https://bcdn.docswell.com/page/G7WGRZ52E2.jpg)

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


# Page. 9

![Page Image](https://bcdn.docswell.com/page/4JZLR1N4E3.jpg)

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


# Page. 10

![Page Image](https://bcdn.docswell.com/page/YE6WRL8GEV.jpg)

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


# Page. 11

![Page Image](https://bcdn.docswell.com/page/GE5M819XE4.jpg)

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


# Page. 12

![Page Image](https://bcdn.docswell.com/page/9729K12QJR.jpg)

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


# Page. 13

![Page Image](https://bcdn.docswell.com/page/DJY4NZYY7M.jpg)

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


# Page. 14

![Page Image](https://bcdn.docswell.com/page/V7NYX3PRE8.jpg)

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


# Page. 15

![Page Image](https://bcdn.docswell.com/page/YJ9P893Z73.jpg)

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


# Page. 16

![Page Image](https://bcdn.docswell.com/page/GJ8D89LYJD.jpg)

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


# Page. 17

![Page Image](https://bcdn.docswell.com/page/LJLMRWL9ER.jpg)

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


# Page. 18

![Page Image](https://bcdn.docswell.com/page/47MYR9MV7W.jpg)

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


# Page. 19

![Page Image](https://bcdn.docswell.com/page/P7R9RGVWE9.jpg)

⼈間は品質‧価値に責任を果たす
●
●
●
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


# Page. 20

![Page Image](https://bcdn.docswell.com/page/PJXQRXZV7X.jpg)

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


# Page. 21

![Page Image](https://bcdn.docswell.com/page/3JK9RW85JD.jpg)

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


# Page. 22

![Page Image](https://bcdn.docswell.com/page/LE3W8121E5.jpg)

参考資料（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）


# Page. 23

![Page Image](https://bcdn.docswell.com/page/8EDKMXZK7G.jpg)

参考資料（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