Back to articles
Guide

Context Engineering for Coding Agents: AGENTS.md, Rules, Skills, and Hooks

Prompt engineering is not enough once agents edit real repos. Context engineering decides what loads every turn, what loads on demand, and what is enforced by the harness. Here is a practical layer model for Cursor and Claude Code.

11 min read

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.

LayerWhen it loadsPut here
Always-on (`AGENTS.md`, root `CLAUDE.md`, Always Apply rules)Every sessionBuild/test commands, architecture map, hard conventions
Path-scoped rules / nested AGENTS.mdWhen matching files are in playModule-specific conventions
SkillsDescription always; body on invokeMulti-step playbooks and reference packs
@-mentions / agent searchPer requestTask-specific files and docs
SubagentsIsolated window; summary returnsHeavy research that would pollute main context
Hooks / linters / permissionsOutside the modelNon-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:

  • How to install, build, typecheck, lint, and run a single test
  • Where major systems live (one short map, not a novel)
  • Conventions that differ from language defaults
  • Gotchas that have already burned the team twice
  • 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:

  • Entire style guides (use the linter)
  • Every possible CLI flag for npm/git
  • Edge cases that almost never apply
  • Duplicating README content that the agent can open when needed
  • 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.

  • Cursor: rules with globs / "Apply to Specific Files"
  • Claude Code: path-scoped rules under `.claude/rules`
  • That way a docs-only session does not pay for database migration policy.

    Write intelligent-apply descriptions as triggers, not titles:

  • Good: "Use when changing the payment capture or refund flow"
  • Bad: "Payments overview"
  • ---

    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:

  • Auto-format after edits
  • Block writes to `.env` or secrets paths
  • Require tests before the agent marks work done
  • Run secret scanning before commit
  • 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 pasted

    Start 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.

    Found this helpful?Share this article with your network to help others discover useful AI insights.

    Share your thoughts on X or Facebook