AIネイティブドキュメンテーション

Description

コードを書くエンジニアだけでなく、AIが理解できる形式のドキュメンテーションをチームとして作成することで、チーム全体の生産性向上が見込めます。 例として、データベースのテーブル定義書を PowerPoint や Excel ではなく Markdown で書き、ドキュメンテーションとして Git で管理することが挙げられます。

Problem

製品開発では、要件定義書、設計書、アーキテクチャ概要図、インフラコンフィグレーション仕様書、テストケースドキュメントなど、さまざまなドキュメントが必要です。 一般的には、PowerPointやExcelのようなフォーマットが好まれますが、AIはそれらのドキュメントを読むことができません。 また、バイナリファイルをGitリポジトリで管理することはベストプラクティスではありません。

Story

あなたのチームにGitHub Copilot for Businessが導入されました。 エンジニアたちは、作業時間が短縮されることを喜んでいます。チームはAIの助けを借りることで人数が倍増したかのように感じられています。 一方で、AIはコードをうまく書いてくれますが、問題はAIがエンジニアが指示したことしかできないことです。 また、AIはエンジニアが持っている文脈を理解していないため、エンジニアはAIに多くの文脈を伝えるために、大量の自然言語を入力する必要があります。 そのため、PMから渡された文章をコピー＆ペーストしたり、上司が作成したPowerPointスライドや複雑なフォーマットのExcelをAIが読めるMarkdownやCSV形式に変換する作業が増えました。

「最初からCSVやMarkdownで書かれていればいいのに！」

Context

多くのプロジェクトでは、PowerPointやExcelなどのドキュメンテーションで管理されています。エンジニア以外の人は、GitHub以外の場所でコミュニケーションをとっており、最終的な決定はリポジトリに保存されていません。ドキュメントはAIに読みやすい形でまとめられていますが、一元管理されていません。

Solution

チームは、MarkdownやCSVなどのテキストベースのドキュメントを作成するよう努めます。 最終的にエンジニアとAIに渡すべき文脈を含むドキュメントは、Gitリポジトリに保存するようにします。 リポジトリは Git Submodule などを使って外部からワークスペースに呼び出しやすくします。 必要に応じてファイルのテキストをコメント欄にコピーし、プロンプトとして AI に渡します。

Known Instance

  • テーブル定義ファイルをCSVやMarkdown形式で用意し、マイグレーションファイルの作成やインタフェースの作成に関連付けます。

  • 自然言語でまとめられたインフラストラクチャの定義をTerraformをはじめとするInfrastructure as Codeの設定ファイルに変換します。

  • テストケースドキュメントからテストファイルに変換します。APIテストなど一定のパターンがあるものについては、より効果的に機能します。これによりテスト駆動開発が容易になります。

Resulting Context

  • エンジニアは、より少ない労力で、より多くのコードを作成できるようになり、工数削減につながります。

  • プロジェクトオーナーやプロダクトマネージャーも、エンジニアからより早く成果物を得ることができます。

  • コードを普段書かないメンバーも、GitHubを使ってコラボレーションを行うことで、エンジニアが必要とする文脈やAIに提供すべき文脈を判断することに慣れ、AIを活用した適切な開発ができるようになります。

  • ドキュメントに変更履歴が残るため、誰がどのタイミングで何の変更を加えたのか、意思決定がいつ行われたのかに関して、コード以外も全体的にトラッキングが可能になります。

  • ドキュメントと実装の乖離がなくなります。

Note

  • 現在 GitHub Copilot が読む対象にするファイルは限定的です。Python を書いている場合は開いているタブの中でも Python のコードが読まれ、プロンプトに渡されます。そのため、AIフレンドリーなドキュメントのなかから必要な文章をコピーして、.py のファイルのコメント欄にコピー・ペーストしましょう。

  • このパターンはすべてのドキュメントにおいて有効なわけではありません。格納すべきドキュメントの判断を誤ることによって、リポジトリに大量の不必要なドキュメントが発生し、検索性能が低下することになります。実装に近い文章を優先的にマークダウンで書くことを心がけましょう。

  • AI に渡せるトークン数には限りがあります。なるべく前後の文章に多くの依存関係を持たないように、それぞれの文章のセクションを簡潔にまとめることを心がけましょう。