Context engineering and what a coding agent loads

A bare Claude Code session starts with 16,389 tokens in its context before you type anything. Add the 549-line Prickles 2.x rule pack for TypeScript and the same session starts at 30,379. Tokens are the chunks of text a model reads and is billed by, and Claude Code sends every one of them again with each request.

Context engineering is deciding what goes into that window and when. For a coding agent, that means choosing what loads in every session and what waits until the work needs it. Some rules go to a linter instead. It also means knowing when to clear the window out.

Research so far points to one layout. Keep a one-line statement of every rule always loaded, move the detail into files that load on demand and hand anything a tool can check to the tool. Claude Code’s behaviour below was checked against Anthropic’s documentation on 12 October 2026, when the latest release was 2.1.296.

What’s in a coding agent’s context window

A model’s context window holds everything it sees on a turn, from instructions and tool definitions to your messages and every file and tool result so far. Anthropic’s Explore the context window (2026) lists what Claude Code loads before your first prompt. That covers the system prompt, CLAUDE.md, auto memory, skill descriptions and MCP tool names.

Manage costs effectively (2026) says token costs scale with context size. The same page notes that Claude Code sends the full conversation with every request. Prickles measured the starting cost on 11 October 2026 with Claude Code 2.1.295 and Opus 5.5. Each setup ran twice in a fresh Git repository, with MCP servers, plugins and user settings left out, and both runs gave identical counts:

claude -p "Reply with the single word OK." --output-format json --max-turns 1 \
  --strict-mcp-config --no-chrome --setting-sources project

Prickles 2.x puts nine files in .claude/rules, none of them scoped with paths:, so all nine load at launch. It adds 13,990 tokens to every session, 85% more than a bare one. The dollar figures are Claude Code’s own estimate at API prices.

Anthropic’s context-window page notes that after launch, file reads usually take up most of the window. That makes the code itself part of the context. The article on AI token cost covers that side.

Context engineering vs prompt engineering

Anthropic’s Applied AI team draws the line in Effective context engineering for AI agents (2025). Prompt engineering is writing and organising the instructions. Context engineering also covers everything else that reaches the model, for as long as the agent works.

That post sets the aim as finding the “smallest possible set of high-signal tokens” that makes the outcome you want most likely. Its reason is context rot, where a model recalls information less accurately as the window fills. Chroma’s Context Rot report (Kelly Hong, Anton Troynikov and Jeff Huber, 2025) tested 18 models and found that performance shifted as input grew, even on simple tasks. None of its tasks was coding, so its numbers won’t transfer directly to your codebase.

AI3 Working Context asks you to treat the window as a budget. For a coding agent, the curation starts before the session does, in the files you commit.

What to load every session

AI2 Persistent Brief keeps the agent’s brief in the repository. Files such as CLAUDE.md and AGENTS.md hold it and load at the start of every session.

Anthropic’s How Claude remembers your project (2026) sets out what goes where:

• Facts Claude needs in every session go in the file, such as build commands, conventions, the project’s layout and rules that always apply. Aim for under 200 lines a file.
• A multi-step procedure, or anything that matters for only one part of the codebase, goes in a skill or a path-scoped rule.

Thibaud Gloaguen and colleagues at ETH Zurich tested what such files do in Evaluating AGENTS.md (2026). Context files didn’t generally raise task success. They did raise inference cost, by over 20% on average. Agents did follow what the files said. They ran uv 1.6 times per task when a file mentioned it, against fewer than 0.01 times when it didn’t.

Gloaguen’s team concludes that context files help with coding practices that aren’t standard. Anthropic’s Best practices for Claude Code (2026) offers a test for each line. If removing it wouldn’t cause Claude to make mistakes, cut it.

Pointers or the rule itself

A tempting way to shorten the always-loaded file is to swap rules for pointers, such as “read docs/testing.md before writing tests”. The evidence says agents seldom go looking for rules on their own.

Wenhao Yang, Runzhi He and Minghui Zhou tested this in A First Look at Coding Agents’ Compliance with AI Contribution Rules (2026). They ran four agent and model pairs on 106 issues from repositories with rules about AI contributions. Left alone, the agents opened the policy file in 12 of 347 runs. The researchers then tried two ways of reaching the agent. One was a sentence in AGENTS.md saying a contribution policy existed. The other quoted the rule itself in AGENTS.md. For the rule asking agents to disclose AI help, compliance was:

Quoting the rule beat the reminder for all four pairs, by between 6 and 40 points. For Claude Code, the reminder changed nothing. The study tested contribution policies rather than coding standards. It didn’t test a pointer with a file path either. The two kinds of rule do share one thing. An agent doesn’t know they apply until something tells it.

So keep each rule’s statement in the always-loaded file, and point from there to the explanation, examples and exceptions behind it. Write each pointer as a plain path tied to a moment, such as “before you write a test, read docs/testing.md”.

Path-scoped rules and skills load context on demand

Claude Code can hold text back until the work needs it in two ways. One is a path-scoped rule, a file in .claude/rules with a paths: list in the frontmatter, the settings block between --- lines at its top. Anthropic’s memory docs say it loads when Claude reads, writes or edits a matching file. Since version 2.1.293, as the changelog records, a single-file cat, head or grep in the Bash tool counts as a read too.

No model decision is involved, so it’s the most predictable of Claude Code’s ways to load text on demand. This is the top of the Testing file in the Prickles 3.0.0 pack for TypeScript:

---
paths:
  - "**/*.test.ts"
  - "**/*.test.tsx"
  - "**/*.spec.ts"
  - "**/*.spec.tsx"
  - "**/__tests__/**"
  - "**/*.feature"
---

In the Prickles measurement, a paths: list for test files on the 2.x testing rules took 1,962 tokens off the start of a session. The limit is timing. A path-scoped rule isn’t there until the agent opens a matching file, so it can’t shape a plan or the choice of where a new file goes.

Skills are the second way, each one a folder holding a SKILL.md file. Anthropic’s Extend Claude with skills (2026) says Claude keeps every skill’s description in context and loads the body only once someone invokes the skill. Those descriptions share a budget of 1% of the context window, and each is cut at 1,536 characters.

Here the model decides. Anthropic’s Extend Claude Code (2026) warns that vague or overlapping descriptions can make Claude load the wrong skill or miss one. Jude Gao measured how often that happens in AGENTS.md outperforms skills in our agent evals (Vercel, 2026), using Next.js 16 APIs that weren’t in models’ training data:

• Left to its default behaviour, the agent never invoked the skill in 56% of cases, and scored 53%, the same as with no docs at all.
• Told explicitly to use the skill, it scored 79%.
• An 8 KB compressed docs index in AGENTS.md, pointing at files the agent could read, scored 100%.

Vercel’s post doesn’t name the agent or the model, or say how many cases it ran. On that evidence, scope rules that belong to a kind of file with a file pattern. Save skills for procedures tied to a known moment, such as starting a task or preparing a release.

What to leave to the linter

A linter rule, a type check or a hook sits outside the context window. It takes no space there until it reports a broken rule. That report arrives at the point where the rule applies. TA1 Linter as Law makes every such gate an error.

Two studies and Anthropic’s own docs put deterministic feedback above any choice about where text sits:

• In Yang, He and Zhou’s study, one round of feedback naming the broken rule lifted verification to between 90% and 100% for every agent and model pair.
• Yujun Zhou and colleagues compared rules given as prompt text with the same rules compiled into checks, in Getting Better at Working With You (2026). Prompt text reached 55.0% compliance and compiled checks 70.1%, against 31.6% with no rules.
• Anthropic’s best practices call CLAUDE.md instructions advisory and hooks deterministic. Its Extend Claude Code page adds that a PostToolUse hook that runs your linter feeds the results back as text Claude reads.

HumanLayer’s Writing a good CLAUDE.md (2025) gives the same advice. It says to leave code style to deterministic tools, because they’re cheaper and faster than a model. Once a linter enforces a complexity limit or a parameter count, the instruction file needs at most a line naming it. The error message says the rest. The file keeps the judgement calls no tool makes, such as naming and where a responsibility belongs.

Compacting and clearing the Claude Code context window

Claude Code compacts automatically as a session nears its limit. It replaces the conversation with a structured summary and reloads some context from disk. Anthropic’s context-window page lists what comes back:

That’s another reason to keep each rule’s statement in the always-loaded file, because it’s the layer compaction restores. Where compaction starts depends on the model. Anthropic’s Model configuration page (2026) puts it at about 967K tokens for models with a native 1M-token window. Sonnet 4.6 and Opus 4.6 without extended context compact at 200K.

Session length matters too. Damon McMillan ran 1,650 Claude Code sessions for Instruction Adherence in Coding Agent Configuration Files (2026), with one trivial annotation as the rule. File size, the rule’s position, splitting the file and a contradiction in a neighbouring file made no detectable difference. The largest effect came within the session. Each extra function the agent wrote carried 5.6% lower odds of following the rule, within the session lengths tested.

Long sessions cost more as well. Pengfei Gao and Chao Peng’s More with Less (2025) names token counts that grow quadratically with each turn as one cause of coding agents’ costs. Claude Code gives you these controls:

• /clear starts afresh between unrelated tasks, and Anthropic’s costs page says it costs nothing.
• /compact with a focus, such as /compact focus on the auth bug fix, keeps what you choose before a long new task. Compacting a large context is itself a large request.
• /autocompact with a token count, such as /autocompact 500k, sets how full the window gets before automatic compaction.
• A subagent does large reads in its own context window and returns only a summary.

What caching changes

Prompt caching lets the API skip reprocessing the start of a request when it hasn’t changed. Anthropic’s How Claude Code uses prompt caching (2026) puts CLAUDE.md, auto memory and rules with no paths: in one cached layer. That layer is rebuilt when a session starts and after /clear or /compact.

Anthropic’s Prompt caching docs (2026) price cached reads at a tenth of the base input rate, and at 5% on Opus 5.5 and Sonnet 5.5. In the Prickles measurement, the 2.x pack raised a session’s first call from $0.0494 to $0.1614, and each later cached call from $0.0034 to $0.0062.

Caching changes what the tokens cost. Cached tokens still take up room in the window and still compete for the model’s attention. The cache also expires. The costs page gives it an hour on a subscription and five minutes by default on an API key. After a longer break, the next message reprocesses the full context.

Prickles 3.0.0 packs as a worked example

Prickles release 3.0.0, published on 13 October 2026, restructures every agent’s rule pack along these lines. The aim is code written correctly, and nothing is removed. In the default layout, called Recommended:

• An entry of about 11 KB loads in every session. It holds each of the 50 tenets’ ID, name and rule line under nine pillar headings. Eighteen rule lines were reworded for 3.0.0 so that each opens with what to do.
• Each heading names the file that holds the rest of its pillar and says when to read it, as a plain path with no @.
• Foundations, Architecture, Style, Types & Schema, Testing and Patterns load by file pattern wherever the agent supports one. Testing loads on test files only.
• Process, AI Collaboration and Tooling are Agent Skills. An agent with no file patterns gets every pillar as a skill.
• Tests rebuild every tenet’s rule byte for byte from the entry and the pillar files, and check that each entry stays under 12,000 bytes and 150 lines.
• The Strict layout loads the whole canon in every session, as 2.0 did.

For Claude Code, the entry is .claude/rules/prickles-canon.md, a rule with no paths:, so compaction restores it. The code pillars are .claude/rules files with paths:. The other three are skills in .claude/skills. The pack needs Claude Code 2.1.293 or later.

Here is how the entry opens, without its preamble or the other pillars:

# Prickles canon v3.0.0: the 50 tenets

IMPORTANT: reading a pillar's file is a precondition. Read it with your file-read tool before your first edit of the kind its heading names, and again after your context is compacted.

## Testing (TS1–TS8). Before you write or change a test, read `.claude/rules/prickles-testing.md`.

- **TS1 Living Documentation.** If a behaviour matters, write a test that proves it. The test is the spec. Prose docs are a paraphrase.

Each choice follows the evidence above. Rule lines stay in every session because agents seldom fetch rules they don’t know apply. Code detail loads by file pattern because no model decides when. Procedures are skills because they matter at known moments, such as the start or end of a task. The entry emphasises one line only, as Anthropic’s best practices advise.

How to engineer a coding agent’s context

1. Run /context at the start of a session and note what loads before you type.
2. Keep the always-loaded file under 200 lines, with a one-line statement of every rule, each written as something to do.
3. Move detail that belongs to one kind of file into a rule scoped by file pattern, with paths: in Claude Code.
4. Turn procedures into skills whose descriptions say when to use them.
5. Give anything a tool can check to the linter, the type checker or a hook, and cut it to one line in the file.
6. Name files for later as plain paths, because @ imports load at launch.
7. Run /clear between unrelated tasks and /compact with a focus before a long new one.

Other agents have their own names for path-scoped rules and their own skill folders. CLAUDE.md vs AGENTS.md sets out which agent reads what.