AIエージェント開発のプロンプト・設定ファイルチートシート

最後の章は、引くための章です。読み物ではなく、作業中に開く前提でまとめています。

指示の型

本書で扱った「効く指示」を、そのまま使える形にしました。

検証まで一続きにする

[やること]を実装して。
期待する挙動は次のとおり: [具体例を列挙]
実装後にテストを実行して、通るまで直して。
症状を抑えるのではなく、原因を直して。

ポイント — 「実装して」で止めない。確認と修正まで1つの指示に含めると、自走する範囲が広がります。→ 14章

作らせる前に計画させる

[やりたいこと]をしたい。
まず既存の実装を調べて、どう進めるか計画を出して。
実装はまだしないで。

計画を確認してから実行に移します。手順が読める作業はワークフローに寄せ、読めない部分だけをエージェントの裁量に残すのが基本です。→ 12章

タスクを検証可能な単位に切る

弱い切り方	強い切り方
認証機能を実装して	正しい認証情報で200が返るテストを通して
パフォーマンスを改善して	一覧取得のクエリ発行数を2回に減らして
バグを直して	この再現テストが失敗している。通るようにして

終わったかどうかを機械が判定できるかが唯一の基準です。→ 12章

調べさせる（コンテキストを汚さない）

サブエージェントを使って[調べたいこと]を調査して。
結果の要約だけを返して。

大量のファイルを読む作業は、別のコンテキストに逃がします。→ 9章

レビューさせる

サブエージェントで [対象] の差分をレビューして。
正しさと要件に関わる欠落だけを挙げて。
スタイルの好みは挙げないで。

「気になる点を全部挙げて」は過剰設計への入り口です。挙げる範囲を絞ります。→ 14章

修正ループを回す

[レビュー結果]を踏まえて修正して。
修正後にもう一度検証して、指摘がなくなるまで繰り返して。
同じ箇所を行き来し始めたら止めて報告して。

止める条件を先に決めておきます。→ 15章

やってはいけない指示

避ける	理由
「いい感じに」「適切に」	終了条件が存在しないので、エージェントが勝手に決める
「このコードベースを改善して」	広範なスキャンを誘発し、コンテキストとコストを食う
一度に大きすぎる仕事	タスクが長くなるほど成功率は崖のように落ちる
失敗したときに指示を足す	射程外のタスクは説明では救えない。切り直す

設定ファイル早見表

どのファイルが誰に届くかを間違えると、事故になります。→ 10章

置き場所	誰に効くか	何を書くか	Git
組織の管理設定	組織全員	禁止ルール、絶対に守らせる方針	配布
ユーザー設定（ホーム配下）	自分・全プロジェクト	個人の好み、言語設定	対象外
プロジェクト共有設定	チーム全員	権限、フック、テレメトリ	コミットする
プロジェクト個人設定	自分・このプロジェクト	個人の例外、試行中の設定	コミットしない

注意点

プロジェクト個人設定はプロジェクト共有設定より強い
「今後は聞かない」の許可はプロジェクト個人設定に溜まる。チームに要るものは共有設定へ引っ越す
個人設定ファイルを手で作った場合は自動でGit除外されない
共有設定は起動したフォルダからしか読まれない。リポジトリのルートで起動する

指示ファイルに書くもの・書かないもの

→ 11章

書く	書かない
ビルド・テスト・lintのコマンド	コードを読めば分かること（ディレクトリ構成、依存一覧）
触ってほしくないファイル	一般論（「読みやすいコードを」）
ディレクトリの役割、ドメイン用語	頻繁に変わる事実（バージョン番号）
PRの出し方、コミットの粒度	長いアーキテクチャ解説

サイズの目安 — 公式が示す目安は200行未満（Cursorのルールは500行以内）。長いと遵守率が下がります。

具体性の目安

効きにくい	効きやすい
コードを適切にフォーマットする	インデントはスペース2つを使う
変更をテストする	コミット前に `npm test` を実行する
ファイルを整理して保つ	APIハンドラは `src/api/handlers/` に置く

追記するタイミング — 同じ間違いを2回した／レビューで指摘された／前回と同じ訂正を打った／新しいメンバーにも同じ説明が要る。再説明が起きたら書くという運用にします。

権限とサンドボックス

→ 5章

原則	内容
評価順	禁止 → 確認 → 許可。最初に一致したものが決まる
設計の向き	許可を広げるより、禁止を先に固める
緩めてよい条件	モデルの賢さではなく、環境が隔離されているか
二層構造	権限はエージェントの判断に効く。サンドボックスは判断が乗っ取られても効く
ネットワーク	遮断 → 信頼済みのみ → 許可リスト → 全開放。絞ってから足す

最初に禁止しておくもの

.env などの認証情報ファイルの読み取り
本番環境に触れるコマンド
履歴を書き換える破壊的なgit操作
リポジトリ外への書き込み

フックの使いどころ

→ 14章・8章

やりたいこと	使うタイミング
整形・lintを必ずかける	ファイル編集の後
巨大な出力を絞る	ツール実行の前（コマンドを書き換える）
検証が通るまで終わらせない	停止時
完了・確認待ちを通知する	通知イベント／停止時
操作の記録を残す	ツール実行の前後

判断基準 — 指示ファイルはお願い、フックは保証。破られると困ることはフックへ移します。

セッションの運用

→ 9章・17章

無関係な作業に移るときはセッションを切る（最も効くコスト対策）
圧縮が何度も走ったら、セッションを作り直す合図
同じ指摘を2回しても直らないなら、文脈が汚れている。切り直して指示を書き直す
調査など出力の多い作業はサブエージェントに逃がす
モデルは仕事に合わせる。最上位を既定にしない

並列で走らせるときの確認

→ 7章

worktreeで作業ディレクトリを分けたか
作業ディレクトリの外に書き込むものを洗い出したか（ポート・DB・生成ファイル・キャッシュ）
各worktreeの初期化（依存インストール、環境変数）は自動化したか
タスクは互いに独立しているか
レビューできる量を超えていないか
終わったworktreeを片付ける手順はあるか

新しいプロジェクトで始めるときのチェックリスト

上から順に効きます。

うまくいかないときの切り分け

症状	まず疑うところ	該当章
指示を守らない	指示ファイルが読み込まれているか／長すぎないか／矛盾していないか	11章
完了と言うが動かない	検証手段を渡しているか	14章
途中から的外れになる	コンテキストが長すぎないか。切り直す	9章
大きい作業が毎回失敗する	タスクが射程を超えていないか	12章
設定が効かない	スコープ。読み込まれているか、上位で上書きされていないか	10章
想定より高い	セッションを切っているか。モデルは適切か	17章
並列にしたら壊れた	作業ディレクトリの外の共有状態	7章
レビューが詰まる	機械のレビューを人間の前に置いているか	15章

おわりに

本書を通して繰り返してきた考え方を、最後にもう一度だけ挙げます。

エージェントの性能はモデルだけで決まらない。渡すもの、許すもの、検証させるもの——ハーネス側の設計が結果を変えます
書くより、機械で強制する。お願いで済ませていいのは、破られても致命的でないことだけです
資産をツールに縛りつけない。ナレッジ本体をツールの外に置いておけば、次に良いものが出たときすぐ試せます
体感を証拠にしない。測るのは難しいですが、難しいことと、測らなくていいことは違います

この分野は動き続けます。ここに書いた製品名やコマンド名は変わりますが、上の4つと、各章で扱った原則は、しばらく使えるはずです。

参考リンク

AGENTS.md — 指示ファイルの共通規約
How Claude remembers your project（Claude Code 公式） — 指示ファイルのサイズと具体性の指針
Configure permissions（Claude Code 公式） — 権限ルールの評価順と書き方
Hooks reference（Claude Code 公式） — フックのイベント一覧
Best practices for Claude Code（公式） — 検証手段の渡し方と失敗パターン

AIエージェント開発のプロンプト・設定ファイル チートシート

AIエージェント開発のプロンプト・設定ファイルチートシート