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