Prompting AI coding tools

Models are only as good as the constraints you load. "Add caching" invites a distributed locking framework you did not ask for. A goal, an example module, hard constraints, and explicit non-goals usually save a round.

Point the agent at the files that matter. Dumping the whole monorepo into context wastes the window and dilutes attention.

What to load

• Goal — "Add idempotent Stripe refund webhook keyed on event.id" beats "fix billing."
• Examples — one good existing module to match style.
• Constraints — "no new dependencies," "must pass pnpm test," "follow expand/contract for the column."
• Non-goals — so the model does not invent a locking framework.
• Project instruction files — AGENTS.md, CLAUDE.md, Cursor rules: commands to run, house style, forbidden patterns. Keep them short and true. Stale instructions poison every session.

Snippet of a useful project instruction file
- Run checks with: pnpm test && pnpm lint
- Prefer existing `Result` helpers in src/lib/result.ts
- Never commit .env; use secrets via vault
- Migrations must be expand/contract; no destructive drops in one PR

For chat Q&A while learning a codebase: "Cite file paths and line ranges; if unsure, say so." Demand evidence over vibes.

Ask for a plan when the blast radius is more than about 3 files. If the agent wanders, stop, reset context, paste the plan you approved, and continue. Long confused threads rarely recover.

Walking through a stronger prompt

Weak: "Add caching."

Stronger:

Goal: cache product GET by id in Redis for 5 minutes with jitter.
Constraints: cache-aside; delete on update (do not SET on write);
key product:v3:{id}; use existing redis.ts client;
add unit tests with a fake redis; run pnpm test.
Match style of src/catalog/getCategory.ts.
Non-goals: CDN caching, stampede locking
  (call out if you think we need it).

Agent proposes a new BaseRepository. You reject: "We already have src/db/repo.ts patterns; extend those. No new base classes." Second attempt matches house style. Your job was architectural taste — five seconds that saved years of a wrong abstraction. See maintainable code.

Common mistakes

• "Fix billing." No goal, no key, no test.
• Stale AGENTS.md. Every session drinks the poison.
• Whole-monorepo context. The window fills; attention dies.
• Letting a new base class land because the first draft compiled.

Check yourself

1. What four things belong in a prompt for a multi-file change? Goal, an example to match, constraints including the check command, and non-goals.

2. The agent invents BaseRepository. What do you do? Reject it. Point at the existing src/db/repo.ts pattern. Taste is the job.

Key takeaways

• Load goal, example, constraints, and non-goals.
• Keep instruction files short and true.
• Point at the files that matter.
• Your five-second "no" on a wrong abstraction is the high-leverage move.

Further learning

Next, review the output in reviewing AI code.