AIに「丸投げ」しないための、仕様の書き方

AIと一緒に開発していると、はっきり感じることがあります。うまくいくかどうかは、最初に「何を作りたいか」をどれだけ言葉にできるかで決まる、ということです。この記事では、自分が実際に使っている仕様の書き方を、テンプレートと具体例で紹介します。

ふわっとした依頼は、ふわっとした結果になる

「いい感じにして」と頼むと、たいてい、いい感じの“それっぽいもの”が返ってきます。悪くはないけれど、自分が本当に欲しかったものとは少しずれている。そんなことがよくありました。

原因はシンプルで、こちらの頭の中にある「欲しいもの」が、言葉になっていないからです。AIは超能力者ではないので、言葉にしていない前提は当然くみ取れません。

自分が使っている仕様テンプレート

スムーズに進むときは、だいたい次の型に沿って先に書き出しています。新機能ひとつにつき、5〜10行で十分です。

## 目的
この機能は何のためにあるのか（一文で）

## 入力 / 出力
- 受け取るもの：
- 返すもの：

## やること
- 箇条書きで、満たすべき条件

## やらないこと
- 今回は対象外にすること

## 具体例
- たとえばこういう入力なら、こういう結果になる

特に効くのが「やらないこと」と「具体例」の2つです。やらないことを決めると話が広がりすぎず、具体例を1つ添えると、認識のズレが一気に減ります。

具体例：検索機能を頼むとき

たとえば記事の検索機能なら、こう書きます。

## 目的
ブログ記事をキーワードで絞り込めるようにする

## 入力 / 出力
- 受け取る：検索キーワード（文字列）
- 返す：タイトルか本文にキーワードを含む記事の一覧

## やること
- 大文字小文字は区別しない
- 該当0件のときは「見つかりません」と出す

## やらないこと
- あいまい検索・タグ検索（今回はしない）

## 具体例
「supabase」で検索 → タイトルに Supabase を含む記事がヒットする

ここまで書いておくと、出てくるコードのブレがほとんどなくなります。「あいまい検索は今回いらない」と先に言ってあるので、余計な作り込みもされません。

仕様を書くのは、自分の整理でもある

面白いのは、仕様を言葉にしていくと、自分自身の考えも整理されていくことです。「あれ、ここはどうしたいんだっけ？」と、作る前に気づける。手戻りの多くは、実装ミスではなく「決めていなかったこと」から生まれます。それを着手前にあぶり出せるのが、この一手間の最大の効果です。

AIに伝えるための仕様は、結局のところ、自分が何を作りたいのかをはっきりさせる作業でもある。そう考えると、この一手間が惜しくなくなりました。Claude Code を使った具体的な進め方は「Claude Code を使うと、個人開発はどう変わるか」にも書いています。