AIコーディングツールに「取扱説明書」を書いたら、開発が変わった
はじめに
AIコーディングツールを導入すると、「これで開発速度が倍になる」と期待する人は多い。実際に使ってみると、たしかにコード生成は速い。しかし、しばらく運用してみると気づくことがある。
生成が速くても、意図とズレた出力を修正する時間が増えたら、トータルでは速くなっていない。
これは道具の問題ではなく、「道具の使い方を伝えていない」ことが原因だった。人間の新人にも業務マニュアルや引き継ぎ資料を渡すように、AIにも「このプロジェクトではこうしてほしい」というルールを書いて渡す必要がある。
この記事では、AIコーディングツールの「取扱説明書」を整備して開発ワークフローを改善してきた、実際の運用記録を紹介する。
AIへの「取扱説明書」を書く
ルールファイルという考え方
多くのAIコーディングツールは、プロジェクトのルートに置いた設定ファイル（Claude Code なら CLAUDE.md、Cursor なら .cursor/rules/ 配下のファイルなど）を読み込んで、その内容に従って動作する。
これは人間に渡す「業務マニュアル」と同じ役割を果たす。たとえば、以下のような情報を書いておく。
- プロジェクトの概要: どんなサービスで、どんな技術スタックか
- コーディング規約: 命名規則、ファイル構成のルール、使ってはいけないパターン
- やってはいけないこと（Anti-Pattern）:
any型の安易な使用、同じ情報の複数箇所への記述 など
実際に運用しているルールファイルの一部を紹介する。
## Anti-Patterns
| Don't | Why | Do Instead |
|-------|-----|------------|
| Use `any` type casually | Breaks type safety | Define explicit types |
| Write same content in multiple places | Update misses, contradictions | Define SSOT, use references |
| Create files over 1000 lines | Hard to maintain | Split into components/functions |このように「やるな」「なぜダメか」「代わりにどうするか」の3点セットで書くと、AIは高い精度でルールを守ってくれる。
計画の「伝え方」を整える
ルールファイルに加えて重要なのが、計画をAIに渡すときの書き方だ。
「認証機能を作って」という漠然とした指示では、AIは何をどこまで実装すべきか判断できない。代わりに、ゴール・現在地・戦略を明確にした形式で伝える。
1. userテーブルにemail, password_hashカラムを追加
2. bcryptでパスワードハッシュ化する関数を実装
3. POST /api/auth/login エンドポイントを作成
4. JWTトークン生成機能を追加ステップを分けて書くと、AIは各ステップを順に実行し、途中で確認を挟める。「全部おまかせ」より「刻んで依頼」の方が、最終的な品質は高くなる。
AIの「記憶の限界」を知る
コンテキストウィンドウとは
AIにはコンテキストウィンドウ（一度に処理できる情報量の上限）がある。これは人間でいえば「作業机の広さ」のようなものだ。机が広ければたくさんの資料を広げられるが、狭ければ一度に参照できる資料は限られる。
AIのコンテキストウィンドウも同じで、会話が長くなるほど古い情報が押し出されていく。つまり、1つのセッションで何でもやろうとすると、最初に伝えたルールや文脈をAIが忘れてしまう。
「1セッション = 1タスク」の原則
この制約に対する実践的な対策が、1セッション = 1タスクの原則だ。
1. Plan: 計画を立てる（設計書やタスクリストを参照）
2. Implement: 実装する（計画に沿って1つずつ）
3. Review: レビューする
4. Commit: コミットしたらセッションを区切る → 次のタスクへタスクが完了したらセッションをリセットし、次のタスクではクリーンな状態から始める。「もったいない」と思うかもしれないが、コンテキストが汚れた状態で続行するより、きれいな状態で始め直す方がはるかに効率がいい。
外部メモリを活用する
セッションを区切っても困らないようにするコツは、AIの外に情報を持たせることだ。
設計書、タスクリスト、仕様書をファイルとして管理しておけば、新しいセッションでも「このファイルを読んで、次のタスクを実装して」と伝えるだけで、AIは文脈を復元できる。AIの頭の中（コンテキストウィンドウ）ではなく、ファイルシステムを「外部メモリ」として使うわけだ。
これは、人間が付箋やメモ帳を使って「忘れてもいいようにする」のと同じ発想だ。
AIを「チーム」として動かす
Supervisor Pattern（監督パターン）
AIコーディングツールの中には、サブエージェント（子プロセス）を起動できるものがある。この機能を使うと、AIを1人の万能選手ではなく、役割分担したチームとして動かせる。
基本的な考え方は以下の通り。
- メインエージェント（Supervisor）: 計画を立て、タスクを振り分け、成果物をレビューする「司令塔」
- サブエージェント（Worker）: 指示されたタスクを実行する「実作業担当」
ユーザー: 「新機能の設計とリポジトリ整理をして」
メインエージェント:
├─ [並列] サブA: ファイル構造の整理案作成
├─ [並列] サブB: 競合他社の機能リサーチ
└─ [直列] サブC: サブBの結果を元に設計書作成
→ メイン: 全成果物をレビューし、統合して報告なぜチーム化するのか
メリットは大きく2つある。
1. コンテキストの保護
テスト実行やコードレビューは大量の出力を生む。これをメインのコンテキストで処理すると、「作業机」がログで埋まってしまう。サブエージェントに委譲すれば、メインのコンテキストはきれいなまま保てる。
2. 並列処理による高速化
独立したタスク（調査とコード整理など）は同時に走らせることができる。人間のチーム開発で「AさんはAPIを、Bさんはフロントを」と分担するのと同じだ。
丸投げしない
ただし、サブエージェントの出力をそのまま採用してはいけない。必ずメインエージェント（または人間）がレビューする。
確認すべき観点は以下の通り。
- 要件を完全に満たしているか
- セキュリティリスクはないか（入力検証、権限など）
- 既存のルールや設計と矛盾していないか
AIの出力にはバグが含まれることがある。「AIが書いたから大丈夫」ではなく、「AIが書いたからこそ確認する」という姿勢が重要だ。
失敗を「二度目」にしない仕組み
Lessons Learned セクション
AIとの協働で特に効果を感じたのが、失敗の記録と再発防止の仕組みだ。
ルールファイルに「Lessons Learned」セクションを設け、AIが犯したミスとその修正方法を記録していく。
### 2026-02-09: [Deploy] Edge Function デプロイ時に --no-verify-jwt を忘れない
- **Mistake**: フラグなしでデプロイ → 全リクエストが401で拒否
- **Correct**: `--no-verify-jwt` フラグを付けてデプロイ
- **Reason**: Webhook Triggerは別の認証方式を使うため、JWT検証が不要このフォーマットで記録しておくと、次回以降AIは同じ状況に遭遇したとき、過去の失敗を参照して正しい方法を選択できる。人間のチームでいう「ポストモーテム（振り返り）」をAIとの間でも実践しているわけだ。
AI出力の検証チェックリスト
失敗を防ぐもう一つのアプローチが、チェックリストによる検証だ。
□ 入力検証は適切か？
□ エラーハンドリングはあるか？
□ APIキーがハードコードされていないか？
□ SQLインジェクション対策はされているか？
□ 認証・認可は適切か？AIが生成したコードをコミットする前に、このチェックリストを通す。最初は面倒に感じるかもしれないが、本番環境でバグを踏むコストに比べれば安い投資だ。
公式ドキュメントを信頼する
AIの学習データには期限がある。ライブラリやフレームワークのAPIは日々更新されるため、AIの「知識」と現在の仕様が食い違うことは珍しくない。
対策はシンプルで、AIの出力より公式ドキュメントを優先すること。AIに対しても「自分の知識が古い可能性を前提に、公式ドキュメントを確認してから回答するように」とルールファイルに書いておくと効果的だ。
まとめ
AIコーディングツールを実務で使い込んで見えてきたポイントは、3つに集約される。
- ルールを書く: AIに「このプロジェクトではこうしてほしい」を明文化して渡す。ルールがなければAIは一般的な判断しかできない
- 制約を理解する: コンテキストウィンドウの限界を知り、1セッション=1タスクで刻む。外部ファイルを「AIの外部メモリ」として活用する
- 検証を怠らない: AIの出力は下書き。レビュー・チェックリスト・公式ドキュメントの確認を経て、初めて信頼できるコードになる
ルールファイルは一度書いて終わりではない。運用しながら「こういうミスが起きた」「この書き方のほうが伝わる」と更新を重ねていくものだ。
ルールは「育てるもの」。 育てた分だけ、AIは頼れるチームメイトになっていく。