こんにちは、AWSグループの藤岡です。
システム立ち上げ時には、議論・検討した結果を仕様書や設計書として記録します。しかし、システムの運用が進むにつれて、以下のような課題に直面したことはないでしょうか（私はあります）
- 更新漏れで、古い仕様が残る
- どれが正式版かわからない
- 誰が責任者かわからない
- 更新されたか判断できない
Gitで一定はカバーできますが、上記の状態になるとさらに更新されずにコードとの乖離が大きくなるといった悪循環に陥り、ドキュメントが機能しなくなります。
ただ最近は、コーディングエージェントを使った実装やドキュメンテーションが日進月歩です。ドキュメントはAIエージェントにとっての指針になり、これまで以上に重要な役割を担っています。そのため、「書いて終わり」ではなく、「常に最新で正確な状態を保つ」ことがますます重要になっています。
そこで本記事では、AI主体の開発スタイルに合わせた「継続的に更新されるDocs運用」の整備にトライしてみましたので、ご紹介します。
本記事では、Docs運用全体やツールをご説明します。次回のブログ②で、セットアップと動作確認までお伝えします！
従来/これからのドキュメンテーションプロセス
従来のDocs運用は、主に以下のプロセスで行われてます。いずれも人が行います。
書く → 読む → 更新する → 読む → 更新する → ・・・
一方、AIの使用を前提とすると、プロセスは以下のように変わります。
人が指示 → AIが生成 → 人が指示 → AIが読む&修正 → 人が指示 → ・・・
人は要件をもとにした指示を行いますが、ドキュメントを読んで既存の状況を確認することや、指示をもとに生成・修正を行うのはAIが主体です。
コーディングエージェント中心に行うドキュメンテーションでは、ドキュメントを人間だけが触る前提とせずに、
- AIがどうやって読むか
- AIがどうやって更新するか
を前提にドキュメント構造を設計することが重要です。
有効なアプローチの一例として、AWSのしょぼちむさんが書かれているブログがあります。こちらでは、KiroのHooksを活用することで、ドキュメントを適切なサイズに分割管理することを自動化・仕組み化しています。
今回の解決アプローチ
今回、以下の役割分離を決めて、ドキュメンテーションを行いました。
| サービス | 役割 |
|---|---|
| Git | コミット前のHooksの実行 |
| Kiro | ドキュメントの生成・修正、エージェントHooksの実行 |
| バリデーター | Hooksから実行されるスクリプト。ドキュメントの状態を判定。 |
| MkDocs | Markdownを指定のフォーマットで表示して、閲覧・検索 |
解決アプローチの全体像は以下のようになります。
ファイル単位でいうと、Hooks配置構成は以下のようになります。
.git/hooks/ └─ pre-commit # Gitコミットhook（validate_docs.pyを実行） | .kiro/ ├─validate-semantic-consistency.kiro.hook # 意味的整合性を検証するhook └─validate-tone-consistency.kiro.hook # 文体一貫性を検証するhook | tools/ └─validate_docs.py # 静的メタデータ検証
この構成は、ドキュメントを2つのフックで自動的に検証するアプローチです。
Gitは、コミット前に指定のスクリプト実行し、ドキュメント全体のメタデータや必須項目の更新漏れがないかなどを判定します。一方でKiroは、生成後にドキュメントの更新が指示を満たしていることやドキュメント全体のトーン・一貫性などを判定します。
つまり、Git hooksはドキュメントの状態を機械的にチェックし、Kiro hooksはドキュメントの品質を文脈的にチェックをします。
このように役割を分担することで、個別のバリデーションを分割して管理しやすく、バリデーション自体も継続的に見直し・修正しやすくなります。
Kiro hooksの作成方法・注意点
Kiroのhookファイルは決まった型があるため、Kiro IDEで作成するのがオススメです。
サイドバーのKiroアイコンを選択して、
右上の＋ボタンを押すと、以下のようにhook作成画面が表示されます。
フォームに作りたいhookを自然言語で入力するだけで、hookファイルが生成されます！（入力は日本語でOKです）
Kiroのhooksで1つ注意点があります。hooksによるアクションで、エージェントによるアクション("askAgent action", shellコマンドの実行でない場合)を指定する場合には、Kiro IDEのチャットコンソールからKiroに指示する必要があります。Kiro CLIは対応してません。
With this action, you can define a prompt that is sent to the agent each time the hook is triggered. The agent will respond and act on this prompt just like it does with a prompt provided in the chat panel.
MkDocsを採用した理由
ドキュメントを継続的に更新するには、自動的な仕組みづくりに加えて、ドキュメントを更新するインセンティブを大きくして、メンバーにドキュメントを更新するメリットを実感してもらうメンタル的な仕組みづくりが重要と個人的には考えています。
その仕組みづくりの1つとして、ドキュメントを閲覧・検索しやすくするMKDocsのような表示ツールを利用しています。
MKDocsは、最低限の設定だけで簡単に導入できます。docsフォルダ内にMarkdownファイルを配置すると、Webサイト形式で構造的にドキュメントを表示することができます。
⚠️ "構造的に"というのが重要なポイントです。個人的な所感ですが、コーディングエージェントを使った開発でのドキュメントの構造的な配置・管理は、エージェントのアウトプットの精度を大きく左右していると感じます。
（以下サイトのように、RAGの文脈などで長文文書の階層化は有効と言われるので、同じく有効と推測できます。）
まとめ
コーディングエージェントの利用が広がる開発現場で、継続的にドキュメンテーションするためのDocs運用が求められています。
そのため重要なのは、「ドキュメントを書くこと」ではなく「ドキュメントが壊れない仕組みを作ること」です。
GitやKiroのhooksによる自動的な品質チェックや、MKDocsによる構造的なドキュメント管理は、コーディングエージェントだけでなくエンジニアを助けてくれます。
本記事を通して、プロジェクトのドキュメンテーション運用をブラッシュアップするキッカケになっていただければ幸いです。 ご興味ございましたら、ぜひ次回でセットアップや動作確認もご覧ください！
