AIはまた間違ったファイルを変更してしまいました。
ドキュメントファイルを更新するように頼みました。するとドキュメントファイルは更新され、さらにまったく別のディレクトリにあるコンポーネントが、黙って変更されていました。ブラウザで見たときに何かが違って見えたので、ようやく気づけました。追跡できるまでに、私はすでにその変更を受け入れてしまっていました。
これはプロンプトの問題ではありません。私は明確で具体的なプロンプトを書いていました。AIは指示に従いました——ただ、そのうえで私が頼んでいないことも実行したのです。そしてそれをした理由は、どのファイルを触ってよくて、触ってはいけないのかについての十分なコンテキストがAIに無かったからです。
この出来事が、私に永続的なコンテキストシステムを作らせました。単一のプロンプトを書く前に、AIにプロジェクト全体の完全で正確な状況を伝えるための3つのファイルです。
3つのファイル
1. .cursorrules — すべてのセッションのグローバルルール
このファイルはプロジェクトルートに置かれており、Cursorのすべてのセッションで自動的に読み込まれます。これは、私が何を頼もうと、AIが必ず従わなければならない制約を記載したものです。
こちらが私の実際の内容です（抜粋）：
## Tech Stack — ロック。変更またはアップグレード禁止。
- Next.js 16.1.6（App Routerのみ — Pages Routerでは決してない）
- React 19.2.3（React Compilerを有効化）
- TypeScript strict mode — any型は絶対に使わない
- Tailwind CSS v4のみ — tailwind.config.js は無し
## TypeScript Rules — 重要
- strict modeはON — すべての変数、パラメータ、戻り値の型は明示的に指定する必要があります
- any型は無し — 代わりにunknown、適切なインターフェース、または型の絞り込み（type narrowing）を使う
- catch (error) ブロックでは、errorをunknownとして型チェックできる必要があります
## React Rules — 重要
- React Compilerが有効 — useMemo または useCallback を決して使わない
## ファイル構造ルール
- バックエンドルートは4つ存在します：generate、checkout、verify、portal
— 明示的な承認なしで追加しない
- 明示的に依頼されない限り、新しいファイルやコンポーネントは作成しない
## 絶対に変更してはいけないもの
- コアのリクエスト実行ロジック（handleSendRequest）
- generate/route.ts にあるJWT検証ロジック
- localStorageキー：apibuilder_pro_token、apiBuilderSavedRequests
重要な洞察は、これらは「好み」ではないということです。すでに私が下した判断を、AIが勝手に行わないようにするための制約です。このファイルがなければ、すべてのセッションが最初から作り直しになります。AIは、学習データから得た知識として useMemo を追加することを決めるかもしれません。Tailwind v3のやり方に従って tailwind.config.js を作ってしまうかもしれません。あるいは、私が既存のものを修正するように頼んだだけなのに、新しいAPIルートを追加してしまうかもしれません。
.cursorrulesファイルは、「やらないで」という会話を、私が何かを言う前にAIが従うルールに変換します。
2. CONTEXT.md — セッションごとのアーキテクチャコンテキスト
これは、私が毎回Cursorセッションの最初に貼り付けるファイルです。AIに、プロジェクトの現在の状態——何が作られているか、アーキテクチャがどう見えるか、そして部品同士がどのようにつながっているか——のスナップショットを渡します。
構成：
## このプロジェクトが何か
[1段落：何をするのか、誰のためか、どうやってお金を稼ぐのか]
## テックスタック
[具体的なバージョン、具体的なパターン、具体的な制約]
## ファイル構造
app/
├── api/generate/route.ts ← AI生成エンドポイント
├── api/checkout/route.ts ← Stripe Checkout
├── builder/page.tsx ← メインのアプリUI
├── page.tsx ← ランディングページ
└── layout.tsx
## 現在の状態
[何ができているか、主要コンポーネントがそれぞれ何をしているか、
存在する状態変数、データフローがどうなっているか]
## 重要な制約
[やってはいけないこと、変更してはいけないこと、立ち入り禁止の範囲]
これにより、最もコストの高い種類のAIミス——誤った前提——を防げます。このファイルがなければ、AIはあなたのアーキテクチャを推測します。App Routerを使っているのに、Pages Routerを使っていると思い込むかもしれません。すべてがlocalStorageに入っているのに、データベースがあると仮定するかもしれません。実際は/builderにあるのに、page.tsxがランディングページだと思い込むかもしれません。
これらの誤った前提はすべて、コンパイルは通っていて見た目も正しそうに見えるコードを生みますが、どこか微妙なところで壊れてしまいます。
3. マスタードキュメント — 完全なプロジェクト履歴
これは最も長いファイルで、参照される頻度も最も低いものです。プロジェクトの完全な履歴、つまりあらゆる主要な判断、毎週の進捗、そしてなぜそうしたのかを含むすべてのアーキテクチャ上の選択が入っています。私はこれをCursorに貼り付けません——長すぎるからです。戦略的な助言が必要なとき、または大きな機能を計画しているときに、Claude.aiに貼り付けます。
このファイルの目的は、セッションをまたいだ継続性です。AIには、会話間の記憶がありません。マスタードキュメントが記憶です。私が新しいClaude.aiのセッションを開始して「ここまでの続きはこうです」と伝えるときに貼り付けるのが、このドキュメントです。
なぜ、より良いプロンプトよりもうまく機能するのか
AIコーディングの標準的な助言は「より良いプロンプトを書け」です。より具体的に。より多くの詳細を追加する。エッジケースを含める。そういう助言は正しいのですが、不十分です。
プロンプトだけに頼る問題は、毎回あなたがプロンプトを書くたびに、すべての制約、すべてのアーキテクチャ上の判断、そして「ここは触るな」というルールをいちいち覚えておく必要があることです。人は忘れます。AIはあなたが望まなかったことをしてしまいます。変更点を突き止めるのに20分を費やすことになるでしょう。
コンテキストファイルは、そうした制約をあなたの記憶から切り離し、環境へ移します。AIは、あなたのプロンプトを読む前にこれらを読みます。あなたが忘れてしまう前に、ルールが適用されます。
この仕組みを作ってからというもの、AIが私に頼まれていないファイルを変更することはありませんでした。最初の1週間に悩まされたTypeScript strict modeのエラーが消えたのは、「any型は無し」という方針が頭の中ではなくルールファイルに書かれているからです。AIは、私が何かを作るように頼む前にアーキテクチャを理解しているため、設計の一貫性が保たれます。
ブレイクスルーは、より良いプロンプトを書けるようになることではありませんでした。AIが働けるための、より良い環境を設計することを学んだのです。
この仕組みは、APIBuilderHQを作っている最中に開発されました。これはAIコーディングツールを使って5つの週末で出荷した、ブラウザベースのAPIクライアントです。上記の.cursorrulesとCONTEXT.mdの抜粋は、実際のプロジェクトからのものです。
