📚

AI開発時代にドキュメントをどう運用すればよいのか

に公開
AI
documentation
development
idea

はじめに

AI を用いた開発が主流になり，ドキュメントに必要な要素が変化している．「仕様書を書いてから実装」ではなく「実装しながら意思決定のログとしてドキュメント」を育てるスタイルが求められている．

「作成したドキュメントを示して他の人に実装してもらう」から「自分と AI で実装する」に変化しているため，ドキュメントをあらかじめ作成する義務は薄れてきている．例えば新機能実装の際も，大まかな UX を定めておき作りながら最適化を図ったほうが良い場合もある．このような場合はあらかじめドキュメントを整備しておいても修正することコストが発生して不利になる．しかし，そのまま放置しておくと「ドキュメントは頭の中にあります」状態になってしまい，未来の自分が困る．

そのため，今回 AI 時代におけるドキュメントの在り方について下記の視点で整理したい．

  1. ドキュメントを考慮した「一人 + AI」開発フローのイメージ
  2. 工数にあらかじめドキュメントも含める
  3. AI 時代のドキュメント視点

ドキュメントをどのような構成にすればよいのかはケースバイケースであり筆者も思考錯誤中であるため本記事では扱わない．

1. フローの前提を変える：ドキュメントは「設計・実装のログ」

旧来の流れ

ドキュメントを書く → 実装する →（たまに）ドキュメント更新

一人＋ AI 前提

実装・会話の中で決めたことをその場で薄くドキュメントに残す → 実装する → 実装した内容をドキュメントに反映・整理

つまり「ドキュメント → 実装」から「実装 ↔ ドキュメント（双方向に更新）」に変えるイメージ．

実務フローとしては例えば：

  1. ざっくり UX／方針 だけ決めておく（UX のファイルに簡単に記述）
  2. AI と対話しながら実装を進める
  3. 「方針を決めた・変えた」タイミングに 2〜3 行でいいのでドキュメントに追記
  4. 機能が一区切りついたら README と関係するドキュメントファイルをメンテ

ドキュメントを「設計情報の最終形」ではなくそのときの自分と AI の思考ログを整形したものと見なす．本格的にドキュメントを書くのは，実装が終わったタイミングでコードを元に記述すればコードとドキュメントの乖離がない．4 のタイミングではテンプレートを用意しておくと AI の作業が安定する．

2. ドキュメント整備を工数にどう組み込むか

AI が実装を手伝ってくれるようになると「コードを書く時間」は確かに減るが，以下の時間を確保することがより重要になる．

  • 仕様をちゃんと考える時間
  • AI に説明するための文書を書く時間
  • 決めたことを整理して残す時間

そのため，上記を明示的に工数に入れておかないとなんかしんどくなる．工数の見積もりは難しい作業の一つだが，エンジニアの身体と精神の健康を守るために極めて重要な要素である．

ドキュメントを独立させて考えるからよくわからなくなるのであって，チケットや TODO を切るときに最初からこう設計しておくイメージ．

  • 例：機能hogefugaを実装する

    • コード
    • テスト
    • feature/hoge.md に関連ルールを追記
    • screens/SCR-XXX-hoge.md を作成 or 更新
    • screens/SCR-XXX-fuga.md を作成 or 更新

「実装」と「ドキュメント」を分けずに一体化して扱う．「コード」「テスト」「ドキュメント」の 3 つセットで完了させるイメージ．

ある程度やらないと見えてこないが，割合や時間で「ドキュメント整備にかける工数の目安」を決めておくと全体の完了目安が立てやすい．

3. AI 時代の新しい視点

今っぽい話．

3-1. ドキュメントは「AI のための API 仕様」でもある

AI を開発パートナーとして見ると，ドキュメントは AI に対するインターフェース定義でもある．

  • ai-prompts.md → AI に対するグローバル設定ファイル
  • screens/ → 「この画面を変更して」と頼むときの参照先
  • ux/ → 想定した UX を損なっていないかを確認するときの参照先

などとなるので，

  • 構造化されている
  • 一貫した表現ルールがある
  • 一箇所を変えれば AI の挙動（生成物）も一貫して変わる

ようにしておくと，AI の出力を「設計でコントロール」できるようになる．

3-2. AI 負債の最小化

昔から技術負債はあったがが，AI 導入後はもうひとつ，

AI が誤った前提で学習し続ける / 誤った仕様を正しいと信じ続ける

という「AI 負債」が出現する．

  • 古い / 矛盾するドキュメントをコンテキストに投げてしまう
  • 削除した機能のドキュメントを読んで出力がおかしくなる
  • 人間と AI で参照している文書が違う

こういう状態は，時間が経つほど「なんか毎回ズレる」という結果になる．

なので，

  • 「単一情報源」の徹底
  • 内容の重複がないドキュメント構成
  • 不要ドキュメントはちゃんと削除する
  • AI に渡すファイルをしぼる（何でもかんでも貼らない）

あたりは，AI 時代ならではの「新しい保守コスト」として明示的に扱ったほうが良さそう．開発ルールに参照するファイルやディレクトリを決めておいたり，参照先がない場合や矛盾する場合は作業を停止して指示を求めるように AI に促すのも手．

3-3. AI にドキュメント整備を手伝わせる

当然ドキュメント生成も AI である．

  • コード変更から「今回変わった仕様」を AI にサマリしてもらう
  • バラバラのメモをテンプレートに従って整形してもらう

上記のように AI が行う作業を決めておくことで，人間のドキュメント作成に関する負担を大幅に減らせる．例えば以下を定める部分は人間が介入する必要があるだろう．AI と相談しながら決めればよい．

  • 何を書くか
  • どのような構成にするか
  • どのタイミングで更新するか
  • テンプレートの設計

まとめ

これからは「ドキュメントを書いてから実装」ではなく「実装・AI との対話の中で決めたことを即座にドキュメントへ還元する」スタイルが求められる．

ドキュメントは独立させて考える要素ではなく，実装と一体化して扱うべきである．繰り返すが，ドキュメント整備も工数に含めて考えてほしい．エンジニアの健康のためにも．

今後 AI の出力が高まれば「意図が表現されているかどうか」「コードとテストとドキュメントが揃っていて，その間に矛盾がないこと」程度をレビューすれば済むようになるかもしれない．

以上だ( `･ω･)b

GitHubで編集を提案

Discussion