はじめに
開発を続けていると、コードとドキュメントの内容がいつの間にかズレてしまうことがあります。
開発当初はきちんとドキュメントを作っていても、
- 機能追加
- 仕様変更
- リファクタリング
- API変更
などを繰り返していくうちに、コードだけが更新されてドキュメントが置いていかれる。
そしてしばらく経つと、
「このドキュメント、今も正しいんだっけ？」
という状態になります。
ドキュメントは作ること自体よりも、継続的にメンテナンスすることの方が難しいのかもしれません。
そこで今回は、Claude Codeを使って、
コードの変更とドキュメントの更新を、普段の開発フローの中で一緒に管理できないか
を試してみました。
今回は第一歩として、Flutterプロジェクトのモデルに関する技術ドキュメントを対象にしています。
この記事の要約
Claude Codeを使って、コード変更にドキュメントが追従する運用を試してみました。
ポイントは以下の3つです。
- ドキュメントのフォーマットをあらかじめ定義する
- 開発途中ではなく、PR作成前をコードとドキュメントの同期ポイントにする
- CLAUDE.mdに更新タイミングと確認内容をルール化する
結果として、「ドキュメントを更新して」と明示しなくても、Claude Codeが必要な更新を拾える運用にできました。
今回やりたいこと
目指したのは、単純にClaude Codeへ、
このモデルのドキュメントを作って
と依頼することではありません。
今回考えたのは、次のような運用です。
ドキュメントのフォーマットを決める
↓
Claude Codeが再利用できる形でルール化
↓
既存コードからドキュメントを作成
↓
普段どおり開発・改修
↓
PR作成前に確認
↓
必要なドキュメントを更新
↓
コードとドキュメントを同じPRでレビュー
ポイントは、ドキュメント作成を一度自動化して終わりにしないことです。
コードが変更されたあともドキュメントが追従できるところまでを、今回のゴールとしました。
Step 1：ドキュメントのフォーマットを決める
AIにいきなり「ドキュメントを作って」と依頼しても、毎回同じ品質・構成になるとは限りません。
そこで最初に、
モデルのドキュメントには何を書くのか？
を決めました。
今回は以下の情報を含めることにしています。
| 項目 | 記載する内容 |
|---|---|
| 概要 | 何を表すモデルなのか、対応するAPI |
| フィールド一覧 | フィールド名・型・内容など |
| Extension | モデルに定義されているExtension |
| 注意点 | 実装上把握しておきたい内容 |
| モデル間の関係 | 同一ドメイン内などの関連モデル |
| 主な利用箇所 | Repository / Provider / 代表的なUIコンポーネント |
単純なフィールド一覧だけではなく、
そのモデルがアプリケーションの中でどのように使われているのかまで追える
ことを意識したフォーマットにしました。
Step 2：毎回同じ指示を書かなくていいようにする
フォーマットを決めても、モデルのドキュメントを作るたびに長いプロンプトを書くのでは運用しづらくなります。
そこで、以下の内容を再利用できる指示として定義しました。
`〇〇`ドメインのモデル一覧のドキュメント作成を依頼したい。
出力先は `docs/models/〇〇.md`。
項目は
①概要（何を表すモデルか、対応API）
②フィールド一覧（表形式）
③Extension
④注意点。
複数モデルが含まれる場合はモデル単位で章立てし、
モデル間の関係や主な利用箇所
（Repository/Provider/代表的なUIコンポーネント）
も記載する。
こうしておけば、実際にドキュメントを作る際の指示はかなりシンプルになります。
今回の検証では、
categoryドメインのモデルドキュメント作って
とだけ指示しました。
結果
Claude Codeが対象となるコードを調査し、指定したフォーマットに沿って、
docs/models/category.md
を生成してくれました。
生成されたドキュメントと実際のコードを確認しましたが、今回の対象範囲では内容に問題はありませんでした。
実際のモデルおよび生成されたドキュメントにはプロジェクト固有の情報が含まれるため、本記事では掲載していません。
ここまでは「ドキュメント生成」の話
ここまでなら、
Claude Codeで既存コードからドキュメントを生成できた
という話です。
そこで次に、
モデルが変更されたら、関連するドキュメントもClaude Codeに更新してもらう
という運用を考えました。
Step 3：ドキュメントを更新するタイミングを考える
最初に思いつくのは、かなり単純です。
モデル変更
↓
ドキュメント更新
常にコードとドキュメントを同期させておけば、更新漏れは発生しません。
ただし、実際の開発では一つ問題があります。
開発中のコードは何度も変わる
一つのPRを作るまでにも、
モデル変更
↓
動作確認
↓
追加修正
↓
やっぱり変更
↓
再度動作確認
↓
レビュー前に微調整
と、同じコードを何度も変更することがあります。
そのたびにClaude Codeが、
モデル変更を確認
↓
ドキュメントを読み込む
↓
ドキュメントを更新
と動くと、まだ確定していない変更に対して何度も処理することになります。
当然、その分トークンも消費します。
「常に同期」ではなく「PR前に同期」
そこで今回は、更新タイミングを次のようにしました。
| タイミング | ドキュメント更新 |
|---|---|
| 開発途中のモデル変更 | ✕ |
| 動作確認中 | ✕ |
| 細かな修正 | ✕ |
| PR作成前の最終確認 | ○ |
| PR作成準備 | ○ |
| PR作成 | ○ |
つまり、
コードとドキュメントを常に同期するのではなく、PR作成前を同期ポイントにする
という考え方です。
開発途中ではドキュメントを更新しない。
PRとしてレビューに出すタイミングで、確定したコードとドキュメントを一致させる。
このくらいが実運用ではちょうど良さそうだと考えました。
Step 4：CLAUDE.mdに運用ルールを書く
更新タイミングが決まったので、CLAUDE.mdにドキュメント運用ルールを追加しました。
最初に設定した内容は以下です。
## ドキュメント運用
モデルの仕様ドキュメントは `docs/models/` 配下にドメイン単位
（`lib/model/<domain>/` 配下のモデルをまとめて1ファイル）
で管理する。
`lib/model/` 配下の変更を含むPRを作成する際は、
対応する `docs/models/<domain>.md` が存在する場合は
改修内容に合わせて併せて更新し、
コード変更と同じPRでレビューできるようにする。
開発途中の細かい改修のたびに更新する必要はなく、
PR作成時点で確定した仕様に合わせて更新すればよい。
想定していた動きはこうです。
通常の開発
↓
PR作成前
↓
lib/model/ の変更を確認
↓
対応する docs/models/ を確認
↓
必要ならドキュメント更新
↓
コード + ドキュメントをレビュー
これでうまくいくと思っていました。
しかし、更新されなかった
モデルを変更した状態でClaude Codeに、
変更内容確認してPR作成の準備お願いします！
と指示してみました。
人間としては、
PRを作る前の最終確認をお願い
という意味です。
ところが、
ドキュメントは更新されませんでした。
なぜ？
CLAUDE.mdには、
lib/model/ 配下の変更を含むPRを作成する際は〜
と書いていました。
そのためClaude Codeからすると、
「PR作成の準備」
↓
まだPRを「作成する際」ではない
↓
ドキュメント更新のタイミングではない
と解釈された可能性があります。
ここで一つ分かったことがあります。
CLAUDE.mdに方針を書くだけでは、こちらが意図したタイミングで必ず実行されるとは限らない。
人間同士なら文脈から読み取れるようなルールでも、AIに実行してもらうのであれば、もう少し具体的に定義した方が良さそうです。
Step 5：「いつ」「何をするか」までルール化する
そこでCLAUDE.mdを見直しました。
単純に、
PR作成時にドキュメントを更新する
とするのではなく、実行するタイミングを具体化しました。
・PR作成前の最終確認
・PR作成準備
・PR作成
さらに、そのタイミングで行うことも明確にしました。
① lib/model/ に変更があるか確認
↓
② 対応するドキュメントが存在するか確認
↓
③ コードとドキュメントの差分を確認
↓
④ 仕様に影響する変更があれば更新
修正後のCLAUDE.md
実際に追加したルールは以下のような内容です。
## ドキュメント運用
モデルの仕様ドキュメントは `docs/models/` 配下にドメイン単位
（`lib/model/<domain>/` 配下のモデルをまとめて1ファイル）
で管理する。
`lib/model/` 配下の変更を含む場合、
PR作成前の最終確認・PR作成準備・PR作成を依頼されたタイミングで、
対応する `docs/models/<domain>.md` が存在するか確認する。
ドキュメントが存在する場合は、
確定したコード変更と現在のドキュメントとの差分を確認し、
仕様に影響する変更があればドキュメントも更新する。
開発途中の細かい修正のたびに更新する必要はない。
PR作成前の最終確認時点で、
コードとドキュメントの内容が一致している状態にする。
ドキュメント更新が必要な場合は、
PR作成前にコード変更と併せて実施し、
同じPR内でレビューできる状態にする。
Step 6：再チャレンジ
ルールを変更した状態で、Claude Codeにこう指示しました。
必要な作業の漏れがないか確認して
今回は、
ドキュメントを更新して
とは伝えていません。
結果
対象となるモデルドキュメントが更新されました。
「必要な作業の漏れがないか確認して」
↓
CLAUDE.mdを確認
↓
lib/model/ に変更あり
↓
対応する docs/models/ が存在
↓
コードとの差分を確認
↓
ドキュメント更新が必要
↓
更新
今回やりたかった動きにかなり近づきました。
Before / After
今回変えたかったのは、ドキュメントの書き方というより開発者の運用です。
「ドキュメントを更新することを人間が覚えておく」部分を減らせたのが、今回一番大きな変化です。
「AIに書かせる」より「AIが動けるルールを作る」
今回試してみて、一番重要だと感じたのはここでした。
Claude Codeを使えば、コードからMarkdownのドキュメントを作ること自体はそれほど難しくありません。
ただ、それだけではドキュメント運用の問題は解決しません。
人間が決めること
AIがドキュメント運用を考えるのではなく、人間が運用を設計して、その中の作業をAIに任せる。
今回の検証では、この形が一番しっくりきました。
Model以外にも展開できそう
今回はFlutterのModelを対象にしましたが、今回作った運用自体は他のドキュメントにも展開できそうです。
重要なのは、対象ごとに何をドキュメントとして残すのかを最初に決めておくことだと考えています。
フォーマットを決める
↓
再利用できる指示として定義
↓
初期ドキュメントを作成
↓
更新タイミングをルール化
↓
PR前にコードとドキュメントを同期
対象が変わっても、この流れ自体は変わりません。
必要なところから少しずつドキュメント化の対象を広げていこうと思います。
今後やりたいこと
今回は開発者向けの技術ドキュメントを対象にしました。
次は、コードや技術ドキュメントの変更をもとに、お客様と共有する「システムの挙動仕様」も継続的に更新できないか試してみようと思います。
こちらは別の記事で取り上げる予定です。
まとめ
今回、Claude Codeを使ってFlutterのモデルドキュメントを作成し、その後の改修でもドキュメントを継続的に更新できる運用を試してみました。
今回の流れをまとめると、
やってみて感じたのは、
ドキュメント生成そのものより、更新する仕組みを作ることの方が重要
ということです。
特に今回は、
開発途中では無理に同期せず、PR作成前をコードとドキュメントの同期ポイントにする
という方法にしました。
これなら開発途中の細かな変更に毎回追従させる必要がなく、トークン消費を抑えながら、レビュー時点ではコードとドキュメントを一致させられます。
またCLAUDE.mdについても、
PR時にはドキュメントを更新する
という方針だけを書くより、
いつ確認するのか
×
何を確認するのか
×
どんな条件なら更新するのか
まで具体化した方が、期待する動作につながりました。
今後は今回作った運用をベースに、対象となるドキュメントを少しずつ広げながら試していこうと思います。
🔥 成長と挑戦を楽しむ仲間を募集中！
スピードリンクジャパンでは、一緒に技術を楽しめる仲間を探しています！
会社の雰囲気や働く環境などをまとめていますので、ご興味のある方はぜひサイトに遊びに来てください！