Context engineering

An agent's context window is a budget, not storage: reliability falls as the window fills (context rot). Give the agent the smallest set of high-signal tokens for the step it is on, and load everything else only when needed. Each line in an always-loaded file must change behavior, and a rule that must always hold belongs in a hook, linter or test, not text. Add a context file only for a failure you have seen.

Evidence that more context can hurt

Read these together. Vercel's result is not "skills are bad". It says knowledge the agent needs on nearly every task belongs in always-on context as a compact index, and skills fit explicit, user-triggered workflows. ETH's result says the always-on file must stay short and specific. The two agree: put little in always-on context, and make all of it count.

What goes where

Use the cheapest layer that still loads when the agent needs the content. Full decision table and examples are in placement-guide.

Size budgets

Other tools have their own caps and defaults. Check the vendor docs for the tool in use before assuming these numbers carry over. Use /context in Claude Code for a live breakdown, and /doctor prompt-audit to find outdated or conflicting instruction files.

Signs of instruction bloat

• The agent ignores a rule that is clearly written. Often a longer file buried it.
• The same rule appears in two files, or in the file and in a linter config.
• Rules that explain things the agent can see: directory trees, tech stack lists, a README summary.
• Rules written for an older model ("think step by step", "be careful") or for a tool the team dropped.
• Two files that disagree (one says tabs, the other spaces).
• Style rules a formatter already enforces.
• Rules for one package that load for the whole repository.
• Emphasis inflation: many lines marked IMPORTANT, NEVER or CRITICAL. When everything shouts, nothing stands out.
• A rule that exists because of an old incident nobody remembers.
• A skill routing table ("When X, use /skill") or an agent roster copied into the instruction file. Every skill and agent description already carries its trigger and reaches the model on its own, so the copy only adds size and goes stale. Entries for skills that are not installed point nowhere. Replace the table with one generic line ("Before acting, check the available skills and invoke any whose description matches the task") plus rules for the few skills that need a custom trigger, each checked against the installed set.
• The same project rules in both AGENTS.md and CLAUDE.md, or in a tool file and a global file. Keep one copy and import or point to it.

Fix by deleting first, then moving, then rewriting. For each line ask: what mistake would the agent make without this? If the answer is "none", delete it. For wording of the lines that stay (one word per concept, positive phrasing, a project glossary), see writing-levers.

Skill listing overflow

Agents load every skill name and description into context each turn, within a fixed budget. With many installed skills the budget runs out.

Sources: skills docs, descriptions are cut short, override skill visibility, settings reference. Other tools cap their listings differently, so check their docs.

Instruction drift

Always-on instruction files load once at session start. As the conversation grows with file reads and tool output, they make up a smaller share of what the agent sees, and rules from early in the session are followed less (see context rot above). Symptoms: the agent follows the file for the first prompts, then stops using a convention, a persona, or a prohibition.

One source of truth for instructions

Several tools means several files, and copies drift apart. Write project rules once in AGENTS.md. Claude Code reads AGENTS.md by itself only when no CLAUDE.md exists (v2.1.277 or later). If a CLAUDE.md is needed, make its first line @AGENTS.md and add only Claude-specific lines below. Never paste the same rules into both. The import avoids a second copy, but the imported text still loads at launch, so it does not lower cost (memory docs). For user-level files there is no shared standard: Codex reads ~/.codex/AGENTS.md, and Claude Code documents ~/.claude/CLAUDE.md. Keep each short. See placement-guide.

Signs of context rot in a session

• The agent repeats a question you already answered or redoes finished work.
• It forgets a constraint stated early in the session.
• Quality drops after many large file reads or long tool outputs.
• It cites files or functions that do not exist.

Respond by compacting with a focus, writing state to a file, or starting a clean session, in that order of effort. Do not keep pushing in a degraded window.

Compaction hygiene

Compaction replaces history with a summary. Plan for what it keeps and drops. Details and a notes template are in long-task-notes.

1. Put the most important instructions at the top of any file that gets re-injected. Truncation keeps the start.
2. Compact on your own schedule, between phases, with a focus: /compact focus on the auth bug and the failing test list. The automatic pass guesses what matters.
3. Clear between unrelated tasks (/clear). Old conversation crowds out the files you need next and costs tokens on every message.
4. Keep rules that must survive in always-on files. Path-scoped rules and nested files load into message history, so a compaction summary can drop them until the agent touches a matching file again.
5. Re-invoke a skill after compaction if the task depends on its full text.
6. Do not rely on chat history for decisions. Write them to a file.

Other agents compact differently. Check the tool's docs for what survives.

Offload big reads to subagents

A subagent works in its own window. It may read tens of thousands of tokens and return a summary of about 1,000 to 2,000 tokens. Use one when the answer is small but the search is large: tracing a code path, auditing a directory, reading a long log, comparing many files.

• Ask for a condensed answer with file paths and line numbers, so the main agent can verify.
• Give the subagent a narrow question and the files to start from.
• Do not use one for work that needs the main conversation's context or for a three-file lookup you can do directly.

Long tasks

For work that spans many sessions or compactions, keep a progress file and a task list in the repository, update them at each step, and begin every session by reading them. See long-task-notes for the file layouts, the one-feature-per-session pattern, and handoff notes.

Reference Files