Zenn
🦭

Claude CodeでAI駆動の開発ドキュメントを作る

に公開
ドキュメント
Claude Code
tech

話題のClaude Codeでシステム開発のサンプルドキュメントを作ってみたところ、既に実用レベルまで来ている気がしたので流れを公開したいと思います。（ドキュメントからコード生成する部分は現在検証中です。）

開発ドキュメントの重要性

システム開発においてドキュメントが重要なことは言うまでもないと思いますが、人の入れ替わりやスケジュール優先による後回し等で十分に用意できずに進めてしまうプロジェクトも多いのではないでしょうか。またプロジェクトが大きくなってくるとある部分の仕様を誰に聞けば良いか分からなかったり、本人もSlackを見返して当時のことを思い出しながら説明する、ドキュメントがあっても必要な情報に辿り着くまでに時間がかかるといったこともあると思います。

Claude Codeで変わったこと

生成AIが出てきてから、早くAIがプロジェクトについて全部答えてくれるようにならないかな、と思ってたまに情報収集していましたが気軽に取り組める方法を自分は見つけられませんでした。
しかし、Claude Codeによって遂にAI駆動の開発ドキュメントが作れる時代になってきていると感じます。

Claude Codeは以下の点で開発ドキュメント作成に違いをもたらしてくれました。

  1. CLIで手軽に動く
  2. ある程度大きめのタスクを丸投げしても完了させてくれる
  3. コーディング能力も高く賢い
  4. 月額固定で使い放題

これによりgit管理した開発ドキュメントをAIに作成・編集させて、分からないこともAIがドキュメントを辿って教えてくれる、という求めていた状態に近づいています。

諦めること、捨てること

AI駆動の開発ドキュメントでは、AIが全ての情報にアクセスできるように一元管理することが必要で、Git & Markdown管理に行き着くのではないかと思います。
しかしプロジェクトによっては、例えば受託開発であれば納品物をエクセルで指定されていたり、自社開発でもNotion, Confluenceなどのクラウドサービスで管理していたり色々な状況があるかと思います。また、ドキュメントの種類によってはGit & Markdownでの管理が辛い、難しい、受け入れられない、という状況もあります。

私もいくつかの点で悩みました。

共同編集作業ができなくなる

Google Drive等でドキュメント管理するメリットは職種関係なく多人数が同時にファイルを閲覧、編集可能で権限まで付けられることだと思います。
ここに関しては、同じファイルを複数人が同時に編集しない、ドキュメントの作成・整理をAIに任せて素早くアップするように頑張ることにし、Google Drive的なメリットは諦めました。

ER図, 業務フロー図などのdrawio形式のファイルが扱いづらい

私はER図や業務フロー図はdrawioで作成することが多いです。
業務フロー図はmermaid記法ならgithub等でも描画してくれますが、mermaidは表現力が低いのでdrawioを使ってきました。
drawioはxmlファイルなのでAIでも読めますが、視覚的に理解してくれるわけではないですし、xmlには不要な情報も多く、Claude Codeでもdrawioの読み書きの精度は高くないと感じています。

ここに関しては、プレインテキストにしないとAIが理解しづらくなるので表現力を捨ててmermaidを使うことにしました。まだ少し違和感はありますが多少は慣れの問題で解消しそうです。（業務フロー図というドメイン特化のmermaid記法が出てくると解決しそう）
ちなみにGithubではmermaid記法を描画してくれるので見やすいです。

ER図に関しても、テーブルの関係性や配置を重視しているのでテーブル定義から自動的に配置してしまうツールはあまり好きではありませんでした。ここに関してはER図は人間が読むためのもの、と割り切って自分で用意し、AIにはテーブル定義書から理解してもらうようにしました。

こういった点で導入しづらい、と感じる人は多いと思いますが、とりあえずやってみると意外と諦めがつくかもしれません。

全てをAIに任せるのではなく

  • 視覚表現は人間のためのドキュメントとして用意
  • markdownはAIと人間両方のためのドキュメントとして用意
    と分けて考えるのが良いと思いました。

具体的な流れ

基本はClaude Codeにドキュメント作成も編集も任せて終わりです。

  1. 人間が要件を理解し整理する
  2. 必要な成果物のフォーマットを考える
  3. Claude Codeと壁打ちしながらドキュメントを徐々に作らせる
    といったありきたりな流れでやっています。

少しずつ任せるタスク量を増やす

Claude Codeは平気で10分とか作業を続けてくれますが、なるべく手戻りをなくすために、一気に作らせずに認識合わせをしながらいくつか叩き台を作らせてから徐々に依頼する量を増やしています。

定期的にコンテキストを入れる

Claude CodeにはCLAUDE.mdという自動的にコンテキストに含めてくれるファイルがあり、Claude CodeにとってのREADME.mdのようなものです。なるべく簡潔にすることを公式でも推奨されていて、確実に従ってくれるわけではないので、定期的に重要なことを思い出すように会話したり、都度CLAUDE.mdを更新して最適化することが必要です。

自分でファイルを編集するケース

ほとんどの場合はドキュメント作成に介入しなくても問題なさそうでしたが、Cloud Codeがタスクを完了するまで単純なものでも数十秒〜数分かかることもあり速さ重視で自分で編集することもあります。
具体的には、文言の微修正やリンクの一括編集・置換、マルチカーソルで複数行一括修正などです。
AIはテキストを頑張って編集してくれますが、人間がIDEの機能で多少効率よく出来る機会はまだありそうです。

サンプルリポジトリ

個人的なプロジェクトで図書館の貸出予約システムを作っており、下記のリポジトリは7割位はAIが作成した開発ドキュメントです。（全部はレビューできてないので、不自然なところもあるかもしれません）

https://github.com/gomafu-tech/ai-driven-docs-sample

また外部公開したい場合のためにdocsify, Cloudflare PagesでBasic認証を入れたサンプルサイトも作っています。

https://ai-driven-docs-sample.pages.devにアクセスし
{ユーザー名: develop, パスワード: password}で閲覧可能にしています。

開発ドキュメントを読ませてAIに開発させる

開発ドキュメントとソースコードはリポジトリを分けています。
それぞれの変更タイミング、頻度、pushする気楽さが異なりますし、
Claude Codeはローカルの別ディレクトリ(リポジトリ)の情報も問題なく参照できるため一緒にする必要はないと感じたためです。

開発ドキュメントを参照したコーディングに関しては、現在進行形なので知見があまりないので、また試せたら公開していきたいと思います。

まとめ

Claude Codeによって開発ドキュメントの作成、編集をAIに任せつつ、情報を一元管理することでプロジェクトに関して質問することも出来るようになりました。
AIの進化が速くて追いつくのが大変ですが、どんどん便利になっていくのが楽しみです。

Discussion