Prompt Engineering Was Step One
Writing a clever user message still matters. But once you run coding agents every day, the bottleneck shifts: what sits in the context window before the model even sees your request.
That discipline is context engineering -- deciding which facts are always loaded, which load only when relevant, which live as on-demand procedures, and which rules must be enforced outside the model.
If your agent keeps repeating the same mistakes, the fix is rarely "try a longer prompt." It is almost always a better context layout.
---
The Layer Model
Think in layers. Each layer has a different context cost.
| Layer | When it loads | Put here |
|---|---|---|
| Always-on (`AGENTS.md`, root `CLAUDE.md`, Always Apply rules) | Every session | Build/test commands, architecture map, hard conventions |
| Path-scoped rules / nested AGENTS.md | When matching files are in play | Module-specific conventions |
| Skills | Description always; body on invoke | Multi-step playbooks and reference packs |
| @-mentions / agent search | Per request | Task-specific files and docs |
| Subagents | Isolated window; summary returns | Heavy research that would pollute main context |
| Hooks / linters / permissions | Outside the model | Non-negotiable safety and formatting |
The golden rule: always-on context is expensive. Every line competes with your code for attention.
---
What Belongs in AGENTS.md (or Root Rules)
Keep the root file short. A practical ceiling many teams use is about 200 lines. Include:
Reference canonical files instead of pasting them:
## Components
Follow the patterns in `components/Button.tsx` for new UI primitives.
Do not invent a second button API.Avoid:
Cursor documents project rules under `.cursor/rules`, plus plain `AGENTS.md` as a simpler alternative. Nested `AGENTS.md` files apply when working under that directory. Claude Code uses `CLAUDE.md` and `.claude/rules` with the same short-file philosophy.
---
Path-Scoped Rules Beat Giant Always-On Files
If a rule only matters for migrations, API handlers, or mobile code, scope it.
That way a docs-only session does not pay for database migration policy.
Write intelligent-apply descriptions as triggers, not titles:
---
Skills for Procedures, Not Facts
If you keep pasting the same checklist into chat -- release steps, incident triage, PR review rubric -- that is a skill, not an always-on rule.
Skills cost almost nothing until invoked. Facts the agent needs on every task stay in `AGENTS.md`. Procedures move out.
---
Hooks for Guarantees
Models follow instructions most of the time. They do not provide guarantees.
Use hooks (or CI + linters) when the outcome must happen:
If you can express the rule as a deterministic check, prefer the harness over prose.
---
Session Hygiene
Long chats compress. Instructions you said only in the first message may survive as a vague summary or vanish.
Habits that help:
1. Put durable instructions in files/rules, not chat lore
2. Start a new chat when switching to unrelated work
3. Bring forward only the needed prior context with explicit @ references
4. Keep a lightweight progress note in the repo for multi-hour agent work so the next session can resume cleanly
Also maintain `.cursorignore` (or equivalent) for generated artifacts, large dumps, and secrets so agents do not waste tokens reading noise.
---
A Minimal Starter Layout
AGENTS.md # shared always-on facts
.cursor/rules/ # Cursor-scoped rules (optional)
CLAUDE.md # Claude-specific extras, keep lean
.claude/skills/ # procedures
.claude/settings.json # permissions + hooks
docs/architecture.md # deep detail, linked not pastedStart empty. Add a rule only after the agent makes the same mistake twice. Treat the instruction set like production code: review PRs that change it.
---
Who This Guide Is For
Perfect for: teams running Cursor, Claude Code, or both on the same repos; anyone whose agent "forgets" conventions mid-task.
Not the focus: one-off ChatGPT questions with no repo context.
---
Bottom Line
Context engineering is product work for your AI workflow. Keep always-on files short, scope the rest, move procedures into skills, and enforce must-never-fail rules with hooks and CI. That combination beats another clever prompt every time.