Chapter 2 · 6 lessons
Context Engineering
AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions — what belongs in always-on memory, what belongs in a skill, and how to spend the token budget.
Cursor · Claude Code · OpenAI Codex · GitHub Copilot
Show all 6 lessonsHide list
Lesson 1 of 6
Context Is a Budget, Not a Bucket
Everything the agent sees competes for the same window: system prompt, repo memory files, skill descriptions, MCP tool schemas, open files, conversation history, and tool outputs. More context is not better context — irrelevant tokens dilute attention and push useful history out.
always loaded ▓▓▓▓ system + harness
▓▓▓ repo memory (AGENTS.md, rules)
▓▓ skill names + descriptions
▓▓▓▓ MCP tool schemas (every connected server!)
on demand ░░░░ files read, search results
░░░ activated skill bodies
growing ████████ conversation + tool outputs- Always-on content should be short, stable, and true for almost every task
- Task-specific procedures belong in skills (loaded on activation)
- Large references belong in files the agent reads only when needed
- Long sessions degrade — start fresh threads for new tasks and summarize handoffs
Refresher
Token budgeting and prompt stacks are covered in depth in the AI & FDE track's LLM Foundations chapter.
Lesson 2 of 6
Repo Memory Files Across Tools
| File | Read by | Scoping |
|---|---|---|
| AGENTS.md | Codex, Cursor, Copilot, many others | Nested files; nearest to the working directory wins or is appended later |
| CLAUDE.md | Claude Code (Copilot also accepts a root CLAUDE.md) | Root plus nested directories |
| .cursor/rules/*.mdc | Cursor | alwaysApply, globs, or description-based selection |
| .github/copilot-instructions.md | Copilot | Repository-wide |
| .github/instructions/*.instructions.md | Copilot | applyTo glob per file |
Codex builds an instruction chain: a global file in ~/.codex, then AGENTS.md (or AGENTS.override.md) from the project root down to the current directory, concatenated so closer files take precedence. It stops once the combined size hits project_doc_max_bytes (32 KiB by default). Other tools have similar layering — know yours.
One source, many tools
Keep canonical guidance in AGENTS.md and make tool-specific files thin (for example CLAUDE.md that says '@AGENTS.md' or a short always-apply rule). Duplicated guidance drifts.
Lesson 3 of 6
What to Put in Always-On Memory
| Include | Exclude |
|---|---|
| How to build, test, lint (exact commands) | Things the model already knows (what React is) |
| Non-obvious conventions (naming, error handling, folder ownership) | Long tutorials and API docs — link or make a skill |
| Hard constraints (never edit generated files, no new deps without asking) | Time-sensitive notes that go stale |
| Where things live (monorepo map) | Personal preferences that only apply to you |
- Write like concise internal docs: imperative, specific, with one example
- Prefer 'Run pnpm test:unit before finishing' over 'Make sure tests pass'
- Scope file-specific rules with globs instead of loading them everywhere
- Review memory files in PRs like code — they change agent behavior for everyone
Lesson 4 of 6
Memory vs Skill vs One-Off Prompt
| Mechanism | Who decides it runs | Loaded | Use for |
|---|---|---|---|
| Repo memory / always rule | Harness, every session | Always | Universal conventions and commands |
| Scoped rule / instructions file | Harness, when files match | When globs match | Language- or folder-specific standards |
| Skill | Model (from description) or you (by name) | On activation | Multi-step procedures and domain know-how |
| Slash command / prompt file | You, explicitly | When invoked | Repeatable prompts you trigger by hand |
| Hook | Harness, on event | Never in context | Checks that must always run |
| One-off prompt | You | This turn | Task-specific details |
Decision rule
Ask two questions: who decides the mechanism runs, and what guarantee do you need? If it must happen every time, it is a hook. If it is how to do something, it is a skill. If it is always true, it is memory.
Lesson 5 of 6
Session Hygiene and Handoffs
- New task, new thread — stale context causes the agent to 'remember' abandoned approaches
- Before switching threads, ask for a short handoff: decisions made, files touched, open questions
- Point at files and symbols (@file, paths) instead of pasting large blobs
- When compaction happens, re-state the goal and constraints in your next message
- Store durable decisions in the repo (ADR, plan file, memory file), not only in chat
Symptom
If the agent keeps reintroducing a bug you already fixed, your context is lying to it — old diffs or instructions are still in the window. Start fresh with a precise summary.
Lesson 6 of 6
Worked Example: The Invented Test Command
A monorepo uses pnpm and Vitest. New agent sessions keep running the wrong commands and creating files in the wrong places.
agent: Running npm test...
npm ERR! missing script: test
agent: Let me install jest and add a test script.
(adds jest, jest.config.js, utils/formatDate.test.js)
you: we don't use jest. or utils/.AGENTS.md (12 lines):
## Commands
- Test: pnpm --filter web test:unit
## Layout
- Shared helpers: packages/lib/src (never create utils/)
## Never
- Add dependencies without asking
agent: Running pnpm --filter web test:unit ... 48 passed.
Added packages/lib/src/format-date.ts with a Vitest test.- Twelve lines fixed a problem that no amount of per-prompt nagging did
- Only non-inferable facts went in: commands, layout, forbidden actions
- CLAUDE.md contains just @AGENTS.md so every tool reads the same source
Takeaway
Repo memory is the cheapest performance upgrade you will ever ship.