二つの開発者が同じAIツールを使う。一人は30秒で動作するコードを得る。もう一人は壊れたものを得て、1時間かけて修正する。
違いはツールではない。プロンプトだ。
なぜほとんどのAI生成コードは悪いのか
AIコーディングツールは、非常に大きなコンテキストウィンドウを持つパターンマッチャーです。明確なパターンを与えると、それを素晴しく完成させます。曖昧さを与えると、彼らは仮定を創り出します——通常は間違ったものです.
一般的な間違い:
- あまりに曖昧："私のアプリに認証を追加する"——AIはあなたのスタック、データベーススキーマ、またはあなたの慣習を知りません
- あまりに大きい: "SaaSダッシュボードを作って" — AIは要しない設計を発明し、それを1時間かけて解読する
- コンテキストなし: "このバグを修正"コードの周囲がない — AIはシステムを推測する
- 決定を求める: AIを使って製品や設計の選択をする代わりに、既に決めたものを実装する
修正は別のAIツールではなく、プロンプトを書く別の方法です.
フレームワーク：コンテキスト → 制約 → タスク
すべての効果的なコーディングプロンプトには三つの部分があります.
[CONTEXT] Given this [file/system/function],
[CONSTRAINT] following these [conventions/rules],
[TASK] do [specific, scoped thing].
悪いプロンプト：
"削除ボタンを追加する"
良いプロンプト：
"
src/components/ProjectCard.tsxに削除ボタンを追加し、deleteProjectサーバーアクションをsrc/actions/projects.tsから呼び出します。クリック時に、既存のAlertDialog(shadcn/ui) を使用して確認ダイアログを表示します。削除後、revalidatePath('/dashboard')を呼び出します。既存のエラーハンドリングパターンに従い、エラーをキャッチして sonner を使用してトーストを表示し、投げ出さない。
同じリクエストです。2番目の方は書き込むのに40秒余計かかります。出力は完成品用ではなく、1時間かけてクリーンアップする必要がある開始点です.
コーディングプロンプトの6つの種類
1. 実装プロンプト
新しい機能を作るために。最も一般的で、最も間違えやすいです.
テンプレート:
Add [feature] to [file/component].
It should [behavior description].
Use [specific library/pattern] — not [what to avoid].
Follow the existing pattern in [example file or function].
The return/export should look like: [description].
例：
Add pagination to `getUserProjects` in `src/lib/queries.ts`.
It should accept `{ page: number, limit: number }` and return
`{ data, total, hasMore }`.
Use Drizzle's `.offset()` and `.limit()` — not cursor-based pagination.
Follow the same select pattern as `getUserById`: select specific
columns, never `select *`.
Type the return with a `PaginatedResult<T>` generic.
2. バグ修正のプロンプト
デバッグのために。期待される挙動と実際の挙動について十分な文脈を提供していない間違いです.
テンプレート：
[function/component] in [file] is broken.
Expected: [what should happen]
Actual: [what is happening]
Error: [exact error message if any]
Relevant context: [the failing code + what it calls]
例：
The `createProject` Server Action in `src/actions/projects.ts`
returns { error: "Unauthorized" } even when the user is logged in.
Expected: creates the project and returns { data: project }.
Actual: always hits the requireAuth() error branch.
Error: no error message, just the unauthorized return.
requireAuth() is in `src/lib/auth.ts` — pasting it below.
The user is definitely authenticated (visible in Clerk dashboard).
3. プロンプトを再構築
既存のコードを改善しつつ、壊さないように。重要な制約条件：変更してはならないものを指定.
テンプレート：
Refactor [function/file] to [improvement goal].
Keep: [API, behavior, types that must stay identical]
Change: [what should change]
Don't: [specific things to avoid]
例：
Refactor `UserTable.tsx` to extract the row actions into a
separate `UserTableActions` component.
Keep: the exact same props API on UserTable, same visual output,
same TypeScript types.
Change: move the action buttons and their handlers to
`UserTableActions.tsx`.
Don't: change how the parent passes data, don't add new dependencies.
4. テストの書き出しのヒント
テストの生成のために。ライブラリ、カバーすべき内容、モック化すべき内容について明確に指定する.
テンプレート:
Write [unit/integration] tests for [function/component] in [file].
Testing library: [Vitest/Playwright/etc.]
Cover: [list of specific scenarios]
Mock: [external dependencies to mock and why]
Don't test: [implementation details to avoid]
例:
Write Vitest unit tests for the `createProject` Server Action
in `src/actions/projects.ts`.
Cover:
- success case (user authorized, valid input)
- validation failure (name exceeds 50 chars)
- unauthorized user (requireAuth throws)
- database error (insert fails)
Mock: `src/lib/db.ts` (mock insert to return a fake project),
`src/lib/auth.ts` (mock requireAuth).
Don't test the actual database or actual auth — only the action's logic.
5. 説明プロンプト
不慣しいコードを理解するために。間違い：一般的な説明を求める.
悪い:
"このコードを説明して"
良い:
"このDrizzleクエリが何をするかを説明してください。具体的には：
.$onConflictDoUpdateは何をするのか、そしてなぜtarget: [users.clerkId]が必要ですか？データベースに与える全体的な影響を一言でまとめてください。"このコードを説明してください"と聞くと、既に知っていることをカバーする壁のテキストが返ってきます.
焦点を当てた質問には焦点を当てた答えが得られます.
6. マイグレーションとアップグレードのプロンプト
新しいAPIバージョンへのコード更新のために.
テンプレート：
Migrate [file] from [old API] to [new API].
Breaking changes to handle: [list specific breaking changes]
Don't change: [function signatures your app uses]
Reference: [paste the relevant migration docs]
例：
Migrate `src/lib/auth.ts` from Clerk v4 to Clerk v5.
Breaking changes: `auth()` is now async, `clerkMiddleware` replaces
`withClerkMiddleware`, user object shape changed.
Don't change the signatures my app uses: requireAuth() and getAuthUser().
Here are the relevant Clerk v5 migration notes:
[paste the breaking changes section from the docs]
コンテキストが倍率です
出力品質の最大の要因はコンテキストです。AIツールはあなたが与えるものしか使えません
いつも含めるべきもの
- 正確なファイルパス
- 特定の関数やコンポーネント名 — 全てのファイルではなく
- フォロワーに従うべきパターンの一つ例
- 使用中のライブラリ — スタックを知っているとは限らない
- 「完了」の見た目（戻り値、ビジュアル出力、挙動）
含めないべきもの
- コードベース全体（「ここに私のプロジェクト全体があります」）
- 関連のないファイル（「
/libにあるすべてのもの」） - 複数のシステムを同時にカバーする要件
最適な文脈は、曖昧さを避けるために必要な最小限の情報です
ヒント（Claude Code）： Claude Codeを使用すると、プロンプトにコードを貼り付ける必要はありません。ファイルパスを参照するだけで十分です——"in
src/actions/projects.ts"と記述するだけで、Claude Codeが自動的に読み取ります。特定の箇所を強調したい場合に限り、貼り付けを行ってください。
CLAUDE.md: 永続的なコンテキストを無料で提供
良いプロンプトを書く際の問題は、毎回あなたの規約を繰り返すことです："cuid2を使用してIDを生成し、サーバーアクションを使用してAPIルートは使用しない、{ data }または{ error }を返す..."
Claude Codeを使用すると、ルートディレクトリのCLAUDE.mdファイルに一度だけ書けます：
# CLAUDE.md
## Stack
- Next.js 15 App Router, TypeScript strict mode
- Drizzle ORM + Neon (PostgreSQL)
- Clerk auth, Zod validation, shadcn/ui
- Biome for linting and formatting
## Conventions
- cuid2 for all IDs, never auto-increment integers
- Soft-delete users (deletedAt), never hard delete
- Server Actions for mutations, not API routes
- Import env from `@/lib/env`, never `process.env` directly
- `requireAuth()` at the top of every protected action
- Return `{ data }` or `{ error: string }`, never throw from actions
- Error messages lowercase, no periods
## File structure
- Server Actions: `src/actions/[feature].ts`
- DB queries: `src/lib/queries.ts`
- Shared types: `src/types/[domain].ts`
Claude Codeは起動時にこれを読み込み、これらのルールをすべてのプロンプトに自動的に適用します。「cuid2を使用する」라고 말할 필요はもうない——それがただやってしまうのです.
タスク分解：本物のシニア開発者のスキル
素晴らしい結果を得る開発者とイライラする開発者を区別する唯一のスキル：タスクを適切なサイズに分解すること.
しないこと：
「サインアップ、ログイン、ソーシャル認証、Google OAuth、パスワードリセット、メール検証、セッション管理、アカウント設定ページを含むユーザー認証を構築してください。」
やること：
- 「Next.js 15 App RouterでClerkを設定」→完了
- 「
requireAuth()ヘルパーをsrc/lib/auth.tsに作成」→完了 - 「Clerkミドルウェアを
/dashboardルートを保護するために追加」→完了 - 「
(dashboard)/settings/page.tsx」でアカウント設定ページを作成する → 完了
各ステップは30秒のプロンプトで、明確で検証可能な出力が得られます。組み合わせた結果は大きなリクエストと同じですが、ゼロの幻覚的アーキテクチャがあり、すべての行を理解しています
ルール：人間が完全に仕様を特定するのに5分以上かかるプロンプトは、2つのプロンプトです
AIに尋ねるべきでないこと
アーキテクチャの決定：
「マイクロサービスを使うべきか、モノリスを使うべきか？」
AIは一般的なパターンに基づいて、道理にかなった答えを与えるだろう。あなたのチームの規模、トラフィック、事業運営期間を知らない。まずは自分で決定してから、AIにあなたの決定を実装してほしいと尋ねること。
ビジネスロジック：
「ユーザーがサブスクリプションをキャンセルした場合に何が起こるべきか？」
これは収益に影響する製品の決定です。自分で定義して、それを実装してください.
セキュリティ監査：
「このコードは安全か？」
AIは要求された場合に安全なコードを書くことができます。既存のコードのすべての脆弱性を自発的に捉えることはありません。監査のために専用のツールを使用してください。
読まないもの:
AIの出力をコピーする前に読まないならやめろ。あなたは理解していないコードを送信している。それが壊れたら——そして壊れる——どこを探せばいいかわからない.
以前 / 後: 実際の例
機能実装
以前（30秒で書けるが、45分かかる修正）:
"プロジェクトリストに検索機能を追加"
以後（90秒で書き込み、最初から動作）：
「
src/app/(dashboard)/projects/page.tsxに検索機能を追加してください。URLの検索パラメータ(?q=)を使用して、検索状態がリフレッシュしても維持されるようにしてください。getUserProjectsからの結果をフィルタリングし、nameがクエリを含む場合（大文字小文字を無視）にフィルタリングしてください。デボンサス入力を使用し、useDebounceからsrc/hooks/useDebounce.tsを使用して300msのデボンサスを設定してください。新しい依存関係を追加しないでください。」
バグ修正
以前:
「私のフォームが提出されない」
後:
「
CreateProjectFormのsrc/components/CreateProjectForm.tsxで提出されたときに Server Action が呼ばれない。React Hook Form のhandleSubmitが接続されているが、アクション (createProjectから) は」src/actions/projects.tsはトリガーされない——アクションの上部で console.log で確認した。ブラウザエラーはなし。両方のファイルを以下に貼り付ける。"
再構築
前：
「このファイルをクリーンアップする」
後：
「
src/lib/db.tsファイルには三つのインラインヘルパー関数 (withRetry、paginate、softDeleteが現在6+の場所で使用されているものを抽出してsrc/lib/db-helpers.tsに置き換え、すべてのインポートを更新してください。関数のシグネチャや動作は変更しないでください—場所だけを変更する。「
」 メタスキル
プロンプティングが上手くなる最良の方法は、悪い結果を受け取ったときにどうしてそうなったのかを尋ねることです。
- 出力が曖昧すぎる→あなたのタスクが具体的でなかった
- AIは建築を発明した→タスクがあまりにも大きかったので、それを分割した
- AIは間違ったパターンを使用した→コンテキストが不足していたので、関連するファイルを追加した
- AIは製品の決定を行った→実装ではなく決定を求めた
- コードがあなたのスタックと一致しない→あなたの規約が
CLAUDE.md
すべての悪い出力はプロンプトに対するフィードバックです。出力だけでなくプロンプトを修正してください。
AIツールから10倍の成果を得ている開発者は、別のレベルや別のモデルを使用していない。60秒余分に時間を使ってより良いプロンプトを書いているだけだ。それが全ての優位性であり、毎日複合的に増えている.
CLAUDE.mdテンプレートとClaude Codeワークフローを含む完全ガイド：
https://stacknotice.com/blog/ai-coding-prompts-senior-2026