AIコーディングについて考えるとき、つい意識が向きやすいのは、どのモデルを使うか、どんなプロンプトを書くか、といった点です。もちろん、これらは重要です。
ただ実際に使ってみると、それらと同じくらい重要なのが、AIに何を読ませるかです。
プロジェクト共通の方針を書いたドキュメント、特定の作業を進めるためのskill、レビュー観点を整理した手順書。こうした前提情報の置き方によって、AIの出力の安定性や扱いやすさはかなり変わります。
一方で、それらは増やせば増やすほどよい、というものでもありません。文書やskillsが増えていくと、「これは何のためのものなのか」「どの場面で使うのか」「何を出力させたいのか」が曖昧になりやすいからです。
自分はこのあたりを整理したいと思っていたときに、書籍『UNIXという考え方』に出てくる 「フィルター」 という発想を思い出しました。
ただ、ここで言いたいのは、UNIXやコマンドを知っている人だけに通じる話ではないということです。
むしろ大事なのは、何かを受け取り、次に使いやすい形へ整えるものとして考える、という見方です。
この記事では、AIコーディングまわりのskillsやドキュメントを「知識の置き場」ではなく、入力を次の形へ変換するフィルターとして考えると、設計や整理がしやすくなる、という見方を紹介します。
最初に、この記事で使う「フィルター」という言葉の意味をはっきりさせておきます。
ここでいうフィルターは、特別に難しいものではありません。
何かを受け取り、少し整理して、次に扱いやすい形にして返すもの、くらいに考えてください。
たとえば、日常でも似たことはよくあります。
誰かから長い相談を受けて、それをそのまま別の人に渡すのではなく、「要するにこういう話です」と整理して伝えることがあります。あるいは、会議の内容をそのまま全部残すのではなく、要点だけを抜き出して議事メモにすることもあります。
これらは、元の情報を丸ごとそのまま次に渡しているわけではありません。次に使いやすい形に変えているわけです。
この記事で言いたい「フィルター」も、それに近いイメージです。
AIに読ませるskillやドキュメントも、単に情報を置いておくためのものとしてではなく、何かを次の工程で使いやすい形に整えるものとして考えると、役割を整理しやすくなります。
AIコーディングというと、どうしてもプロンプトそのものに注目しがちです。
でも実際には、AIが参照できる前提情報によって、出力はかなり変わります。
たとえば、同じ依頼をしても、AIが次のような情報を参照できるかどうかで返ってくる内容は変わります。
こうしたものが整っていれば、AIはチームの前提に沿って答えやすくなります。
逆に、これらが整理されていないと、AIは毎回その場で推測しながら答えることになります。すると、出力の方向性がぶれたり、チームとして揃えたい判断が反映されにくくなったりします。
ここで難しいのは、AIに渡す文書を単なる情報の保管場所としてだけ見ると、設計しづらいことです。
情報量を増やせばよい、詳しく書けばよい、という発想だけでは、実運用では扱いづらくなることがあります。文書が大きくなりすぎたり、役割が重なったりして、「結局これは何のための文書なのか」が見えにくくなるからです。
ここで参考になるのが、UNIXにある「フィルター」という考え方です。
ただし、この記事はUNIXの知識そのものを説明したいわけではありません。
ポイントはひとつで、ひとつの道具に全部やらせるのではなく、それぞれに役割を持たせ、必要に応じてつないで使う、という考え方です。
たとえば、
という流れがあるとします。
これを全部まとめて一気にやらせるのではなく、途中の役割ごとに分けて考えると、全体が見えやすくなります。
AIコーディングで使うskillsやドキュメントも、これと同じように見ることができます。
つまり、skillsやドキュメントを、知識を詰め込む箱としてではなく、入力を次の工程で使える形に変換する部品として考える、ということです。
この見方に立つと、文書の役割がかなりはっきりします。
この見方をすると、AI向けの文書は単に「AIに知っておいてほしいこと」を並べるためのものではなくなります。
そうではなく、何かを受け取り、次に扱いやすい形へ変換するためのものとして位置づけられます。
たとえば、Issueをもとに実装を進めるためのskillを考えてみます。
このskillの役割は、Issueの文章を読むことそのものではありません。Issueを、実装や調査に着手できる形へ変換することです。
たとえば、次のように整理できます。
こう捉えると、そのskillが何のために存在しているのかが明確になります。
「Issueを読ませるためのskill」ではなく、Issueを実装可能な計画に変換するフィルターだと言えるからです。
同じ見方は、ほかの文書やskillsにも適用できます。
たとえばレビュー用のドキュメントなら、役割は単なるチェック項目の列挙ではありません。コード差分を受け取り、レビュー観点に沿って論点を整理し、修正の優先順位をつけた形に変換することです。
あるいは、要求仕様からテスト観点を作る文書であれば、仕様の文章をそのまま読むためではなく、テストケース設計に進める粒度へ落とし直すことが役割になります。
この見方のよいところは、文書の価値を「情報量」ではなく、変換の明確さで考えやすくなることです。
たくさんのことが書いてある文書よりも、何を受け取り、どう変換し、何を返すのかが明確な文書のほうが、AIにとっても人にとっても扱いやすくなります。
ここまでの話を、もう少し日常的な感覚で言い換えてみます。
たとえば、誰かが書いた長いメモを読んで、そのまま会議に持っていくのではなく、「今日決めるべきことは3つです」と整理して共有することがあります。
あるいは、問い合わせ内容をそのまま開発メンバーに転送するのではなく、「事象」「再現条件」「優先度」にまとめて渡すこともあります。
これはどちらも、元の情報をそのまま扱うのではなく、次の人が動きやすい形に整えている状態です。
AIに読ませる文書やskillも、同じように考えられます。
こうして見ると、「フィルター」という言葉が少し具体的になるはずです。
この見方をすると、skillsやドキュメントをどう分けるかも考えやすくなります。
まず分けやすいのが、毎回使うものと、特定の場面でだけ使うものです。
毎回使うものは、いわば常設のフィルターです。たとえば、プロジェクト共通の設計原則、コーディング規約、出力フォーマット、命名ルールなどがこれにあたります。
一方で、「Issueを実装計画に変換する」「レビュー結果を修正タスクに落とす」「要求仕様からテスト観点を抽出する」といったものは、特定の工程に対応したフィルターとして切り出せます。こうしたものは、独立したskillや個別ドキュメントとして分けたほうが扱いやすい場面が多いはずです。
また、フィルターとして考えると、ひとつの文書に多くを背負わせすぎないほうがよい、という感覚も自然に出てきます。
たとえば、次のような内容をひとつの巨大な文書にまとめることはできます。
ただ、これらを全部まとめると、文書の責務が曖昧になりやすくなります。
読む側からしても、「今ほしいのはどの部分なのか」が見つけにくくなりますし、AIにとっても、どのルールをどの場面で優先すべきかがわかりにくくなります。
フィルターとして見るなら、「何を受け取り、何を返すのか」という責務は、なるべく小さく、はっきりしていたほうがよいはずです。
この意味では、AI向けの文書にも、「1つのことをうまくやる」という発想は相性がよいように思います。
この見方を実際に使うなら、文書やskillを作るときに、まず次の4点を見ると整理しやすくなります。
Issueなのか、コード差分なのか、要求仕様なのか、レビューコメントなのか。入力が曖昧なままだと、文書の役割も曖昧になります。
要約なのか、実装計画なのか、修正タスクなのか、確認ポイントなのか。出力が定まると、文書の責務が見えやすくなります。
毎回読むべきものと、特定の工程だけで使うものは分けたほうが管理しやすくなります。
その出力は、次にレビューへ渡すのか、実装へ渡すのか、テスト設計へ渡すのか。つなぎ先が見えると、必要な出力の粒度も決めやすくなります。
この4点を意識するだけでも、AI向けの文書はかなり設計しやすくなります。
ここまで書いてきたのは、厳密な設計論というより、ものの見方に近いものです。
必ずこう設計すべきだと言いたいわけではありません。プロジェクトの規模やチームの運用によって、最適な分け方は変わるはずです。
ただ少なくとも、skillsやドキュメントを「知識の置き場」としてだけ見るより、「入力を次の形へ変換するフィルター」として見るほうが、次のような利点があります。
AIコーディングでは、モデルが何でもやってくれるように見える瞬間があります。
それでも実際には、何を読み、どう整理し、次に何を出すかという流れを整えることが、出力の安定性や再利用性に大きく効いてきます。
だからこそ、skillsやドキュメントの設計を、フィルターの列として捉えてみる価値があります。
AI向けの文書を増やす前に、まず「その文書は何を受け取り、何を返すのか」を定義してみる。そこから始めるだけでも、設計の見通しはかなりよくなるはずです。
AIコーディングの作法は、まだ全体として固まりきっていません。
だからこそ、自分たちなりの設計原則を作っていく余地があるのだと思います。