Your coding agent wrote a migration by hand, again, though your team always uses the generator. It ran the wrong test command. It put the new file in the old folder. None of that is the agent being careless: it simply wasn't told. Every session starts fresh, and the agent only knows what's in its context window, its working memory.
Context engineering is deciding what goes into that window, when. Too little and the agent guesses. Too much and the important rules get lost.
The layers, from always-on to on-demand
Context files: always loaded
A plain Markdown file at the root of your repository that the agent reads at the start of every session.
- AGENTS.md is an open format, "a README for agents", now stewarded by the Agentic AI Foundation under the Linux Foundation. It has no required fields: just Markdown. Its site lists many agents that read it, including Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Jules, VS Code and Windsurf. In a monorepo, nested files apply to their folders, and the closest one to the edited file wins.
- CLAUDE.md is Claude Code's version. It loads
./CLAUDE.md(or./.claude/CLAUDE.md) for the project,~/.claude/CLAUDE.mdfor your personal preferences everywhere, and./CLAUDE.local.mdfor personal notes on one project that you keep out of git. Its docs say Claude Code can also read a repository's AGENTS.md instead.
Skills: loaded when relevant
Instructions for one task, such as "how we write a migration", that the agent loads only when the task comes up. See agent skills.
Memory: written by the agent
Claude Code also keeps an auto memory: notes it writes for itself from your corrections, loaded each session. Check it now and then; a wrong note is repeated just as faithfully as a right one.
What to put where
Context file (every session)
- How to build, test and lint, with the exact commands.
- Folder layout and naming rules.
- The few rules that apply to every change.
Skill (when needed)
- Step-by-step procedures: a release, a migration, a new endpoint.
- Long reference material and templates.
- Scripts the agent should run rather than rewrite.
Claude Code's docs suggest keeping each CLAUDE.md under about 200 lines, because longer files cost more context and are followed less consistently, and note that the more specific and concise your instructions, the more consistently Claude follows them.
A starting file
# Project notes for agents
## Commands
- Install: `npm ci`
- Test: `npm test` (run before every commit)
- Lint and types: `npm run lint && npm run typecheck`
## Conventions
- New database changes: `npm run db:migrate`, never hand-written SQL files.
- Components live in `src/components/<area>/`; one component per file.
- Copy is in sentence case.
## Don't
- Don't edit generated files in `src/__generated__/`.In Claude Code, /init writes a first CLAUDE.md for you by reading the codebase; refine it with what the agent couldn't discover itself.
In short
- The agent knows only what's in its context window; you decide what goes in.
- Context files for every-session rules; skills for procedures; memory for learned habits.
- Short, specific instructions are followed more reliably than long ones.
What to try next
Share this lesson- Turn your longest procedure into a skill: agent skills.
- Give your agent live access to your tools with MCP: Claude Code or Cursor.