理系学生日記

おまえはいつまで学生気分なのか

コーディングエージェント用のオンボーディングドキュメントを、エンジニア用のドキュメントと同一にできるのだろうか

ai

コーディングエージェントによるコード生成の精度は結構いい感じになってきていて。GitHub CopilotとかClaude Codeとか、コーディングアシスタントだかエージェントだかがどんどん現場に入ってきています。 でも、これらのツールに「いい感じのコード」を書いてもらうには、プロジェクトの目的とかルールとか、ちゃんと伝えないといけない。いわゆる「オンボーディングドキュメント」ってやつです。

「Projects as a Code」、「Everything as a Code」

この話をする前に、まず最近の開発現場で起きてることを整理してみると、プロジェクトのルールや作法を言語化する動き、これ「Projects as a Code」って呼ばれてますよね。さらに進んで「Everything as a Code」なんて言葉も出てきてます。

Everything as Codeでは、ネットワークインフラも、コードも、Gitで管理できるプレーンドキュメントも、全て含みます。あらゆる情報をテキストファイルに記録することで、人間しか知らない情報を減らします。

[セッションレポート]Al Agent 時代のソフトウェア開発の型 ～Everything as Codeで智を伝える〜 #AWSSummit | DevelopersIO

要するに、これまで「なんとなく」でやってたことを全部言語化・テキスト化する。プロジェクトのことをちゃんと言語化しておけば、新しく入ってきた人もコーディングエージェントも、すぐにプロジェクトを理解できるようになる。 で、自然に出てくるのが「人間用のドキュメントをそのまま読ませればいいんじゃない？」って発想。あー確かに。そうですね、というやつ。

ドキュメントは読み手を想定して作るもの

でも、新人の頃に先輩に教わったんだわ。「ドキュメントは読み手のことを考えて書け」。 ドキュメントの目的は人に理解してもらうこと、一般に、書き手と読み手には情報格差があり、だからその情報格差を埋める必要がある。

大規模開発だと、新人とか若手とか、いろんな経験レベルの人が入ってくるので、広く戦力になってもらえるように、めちゃくちゃ丁寧にドキュメントを書く。わかりにくい言葉は噛み砕き、時には図とかも使って、一番経験が浅い人でも理解できるようにする。

生成AIの知識レベルは人間よりはるかに高い

一方で、生成AIはどうか。 ClaudeとかGPTとか、最近の大規模言語モデルって、人間よりもはるかに知識が豊富。あんまり知識レベルで伝えることがない。ゴチャゴチャいうよりも「SOLID原則に従え」、「CQRSで頼む」、「YAGNIでOK」で終わったりする。

さらには、実際に人間用のドキュメントをそのままコーディングエージェントに渡してみると、冗長すぎてコンテキストの上限を超えることもある。さらには、何とか総量を抑え込んだとしても、生成AIは大量の情報から重要な情報を絞り込むのは苦手なはずで、Needle in a haystack問題とか色々あった（最近はどうなんすかね、体感変わってない感じありますが）。 だから、できるだけ端的に、重要なことだけを伝えないといけない。

「同一ドキュメント論」

もちろん、「同じドキュメントでいいじゃん」って意見があるのはわかる。

生成AIと人間の間で知識のズレが少なくなる…かもしれないし、メンテナンスは楽。小規模チームだとメンバーの知識レベルをコントロールしやすいので、優秀な人が集まれば生成AIに近い端的な記述で済むこともあると思う。 でも、いろんな経験レベルのエンジニアが参加する環境では、人間向けの丁寧な説明と、生成AI向けの端的な指示は、明らかに別物になると思う。生成AI向けのプロンプト詠唱は、人間向けとは別物だろ。

結論：読み手に応じた最適化が必要ではないか

というわけで、僕の中では人間用と生成AI用のドキュメントを分けて作るべきという考えをしてる。 だって、読み手が違うんだもの。ドキュメントの目的は相手に伝えることなので、相手に合わせる必要があると思う。

生成AIに必要なのは、わかりやすい情報ではなく、的確で端的な指示。 だからこそ、人間用と生成AI用のドキュメントを分けることになる。

Be Clear and Concise: Use simple language and avoid ambiguity.

Cline rules - Cline

Keep your instructions short and self-contained. Each instruction should be a single, simple statement.

Customize AI responses in VS Code

両方を維持するコストは確かにかかる。でも、それぞれの読み手に最適化されたドキュメントを用意することで、人間もコーディングエージェントも、もっと効率よくプロジェクトで活躍できると思う。