Context Engineering for Coding Agents: Where the Why Lives

Search “context engineering for coding agents” and the first page agrees with itself. The context window is the constraint. Keep it small, because long contexts rot. Put your standing instructions in a CLAUDE.md or an AGENTS.md. Compact the session, start fresh often, push side quests into subagents, and give the agent a way to verify its own work. Anthropic’s own guide (September 2025) says it in one line: find the smallest set of high-signal tokens that gets the job done.

All of it is right, and all of it is written for one developer tuning one session. An engineering lead rolling agents out across a team has a different question. The context that matters most to us is not in the repository: it is the product call Priya made in a Slack thread in March, the convention the Checkout team adopted after an incident, the reason the last three pull requests on this module were sent back. Where does an agent get that, who keeps it true, and what does it cost when the agent guesses instead?

This post answers those three questions. The worked example is a YAGNI Team, where every Agent reads the Team’s decisions before it guesses.

What is context engineering for coding agents?

Context engineering is deciding what a coding agent reads before it acts. The name replaced “prompt engineering” once it was clear that the prompt is the smallest part of what an agent sees: the system instructions, the files it opens, the tool results, and whatever it carried over from earlier in the session all compete for one window, and attention degrades as it fills.

It helps to split the subject in two, because the two halves have different owners.

Session hygiene is the developer’s half: how big to let a session get, when to summarize and restart, which tools to expose. This half is well covered. Birgitta Böckeler’s piece on martinfowler.com (February 2026) is the best taxonomy of the mechanisms, and Pete Hodgson’s post (October 2025) is the best concrete workflow for a long task.

Team knowledge is the organization’s half: what the agent needs to know about this product and this team that no file in the repository states. The ranking pages gesture at it and stop. It is the half that decides whether an agent’s second ticket is better than its first.

What do the instruction files actually get you?

Every coding agent now reads a standing instruction file, and as of October 2026 the formats have mostly converged:

• Claude Code reads CLAUDE.md at the user, project, and local levels, imports other files from it, and loads path-scoped rules from a .claude/rules/ directory.
• AGENTS.md is the cross-tool convention, a plain Markdown file at the repository root that Codex, Cursor, and others read, now stewarded under the Linux Foundation.
• Cursor’s rules are small files with a description and a glob, applied always, by file match, by the agent’s judgment, or by hand, and the docs advise keeping each under 500 lines.
• Kiro’s steering files split the same idea into product, tech, and structure documents.

These are table stakes, and the evidence says they are worth less than the pages claim. A February 2026 study from ETH Zurich, Evaluating AGENTS.md, measured agents on real repository tasks with and without their context files. The files did not generally improve task success rates, they raised token cost, and the cases where they helped were the ones where the file encoded a practice the agent would not have inferred from the code.

That last clause is the whole lesson. A context file that restates what the code already shows (the stack, the directory layout, “run the tests before you commit”) is a tax the agent pays on every turn. A context file that states what the code does not show pays for itself. So the question is not “do we have an AGENTS.md” but “what does our code not show, and where does that live today”.

What does the code not show?

Four kinds of knowledge, each kept somewhere an agent reading the repository cannot see.

Kind of context	Where it lives today	What the agent does without it	Who keeps it true today
Product-intent decisions: what this feature should do and why	A Slack thread, a Confluence or Notion page, a comment on a Jira or Linear ticket, someone’s memory	Picks the plausible default and builds the wrong thing well	Nobody, or the person who was in the thread
Conventions that differ from the default	Review comments on past pull requests, a style guide that is two refactors old	Follows the ecosystem default and gets sent back	The reviewer who keeps writing the same comment
The state of the work: what the ticket is, what it blocks, what the last attempt found	The tracker, the pull request thread, the standup	Re-derives the task from the title and misses the constraint in comment four	The engineer assigned to the ticket
Corrections: what a person changed or rejected last time	A closed pull request, a sent-back plan, a verbal note	Makes the same mistake on the next ticket	Nobody; it is remembered or it is not

Notice the right-hand column. The instruction file drifts because the knowledge in it is a copy, and the sources it was copied from keep moving. A rules file is accurate on the day it is written. By the next quarter three of its conventions have changed, nobody owns it, and the agent follows the stale one with full confidence.

The fix is not a better file. It is to read the sources the knowledge actually lives in, and to give the knowledge that has no source a home with an owner.

Where should team context come from?

From the tools the team already keeps, read as grounding, not pasted into a prompt. That is how a YAGNI Team is set up, and the reading is what makes the later stages cheap.

A Team mirrors one of your engineering teams. Its configuration is one page: the Responsibilities, a single editable sentence stating what the Team is on the hook for, which every job on the Team reads first; the backlog it works from, a Linear team or project or a Jira project, epic, or saved filter, read live from the tracker; and the connected tools it reads as grounding. For engineering teams today those are GitHub, Jira, Linear, Slack, Confluence, Notion, Google Workspace, databases, and any MCP server the team already runs.

On top of the tools sit two things the tools do not hold.

The decision ledger is the Team’s record of product-intent judgment calls, captured as engineering work happens. “Orders paid by bank transfer stay pending for seven days.” “Voided invoices stay in the export for reconciliation.” Each entry is scoped to a repository or to the whole workspace, and every Agent reads the relevant decisions before it guesses. A fresh repository can seed the ledger from its own history, with a person’s say-so, so the first tickets are not starting from nothing.

The Playbook is the Team’s set of learned rules for how the work gets done: review norms, conventions, repo- and path-scoped rules. It is not configured. It is learned as a byproduct of people reviewing the Team’s work: a sent-back plan or a review comment becomes a candidate rule, and a person adopts or dismisses it. A rule reads as the Team’s (“the Checkout Team learned that finance-facing exports wait for the tax decision”), never as one person’s note.

Then the Agents, in story order, each reading what its job needs:

• Bailey, the Product Manager, reads the backlog and the Responsibilities and proposes the next ticket as a written spec: the problem, why now, done-when statements, what is out of scope, and the questions it could not settle from the tracker. That spec is context for everything after it.
• Reeve, the Staff Engineer, plans an accepted ticket. It reads Bailey’s spec, the ticket and its comments, the linked Slack thread or wiki page, the decision ledger for this repository, and the Playbook. What it cannot settle, it asks as one question on the case file.
• Wright, the Builder, builds the approved plan to a draft pull request in a sandbox, with the plan and the decisions it cites in reach.
• Proctor, the Reviewer, reviews the pull request against the approved plan and the Team’s learned conventions, and posts one review.
• Fletcher, QA (in beta), writes a test plan from the change and the done-when statements and walks it in a browser.
• Harper, the Chronicler, reports what shipped with the receipts attached, which is how the rest of the team learns a decision was made.

Nobody pastes anything. The context is read from where it lives, and the two pieces with no home elsewhere, the decisions and the learned rules, get one with an owner.

Who keeps the context true?

A named person, and the design of the record is what keeps that job small enough to do.

Take the ledger. Every entry carries a verification tier, asserted or confirmed, and Agents weigh a confirmed decision above an assumption. When an Agent has to proceed without a decision, it says so: the answer it gives itself carries a standing (confirmed, asserted, inferred, or no position), and a no-position answer records the assumption it proceeded on, so the assumption is visible on the case file instead of buried in the diff. People curate on the Decisions page: confirm, record one by hand, discard, supersede, reactivate. A change of judgment is a supersession, never an edit in place, so the record shows what the team believed in March and what replaced it in May.

The review queue is ordered by reliance, not by arrival: the decision Agents have cited most is the one a person is asked to confirm first. That is the difference between curating a ledger and maintaining a rules file. The ledger tells you which of its lines matter.

The Playbook works the same way from the other direction. A correction is the signal: a plan sent back with a reason, a review comment Proctor keeps seeing a person add, a declined proposal. Each becomes a candidate rule, active until a person adopts or dismisses it behind the Team page’s Playbook card. The rule is written once, by the correction, and reviewed once, by a person, instead of being remembered by the reviewer who is tired of writing the same comment.

All of it lands on the ticket’s case file: the decisions a plan cited, the question it asked, who answered, and what it cost. The practice managing AI coding agents describes (ownership, review, a record) is the same practice applied to the agent’s knowledge.

What does a ticket look like with the context in place?

A worked example, on a Team called Checkout that attaches acme/checkout and reads the Checkout project in Linear.

Bailey proposes CHK-318, “Expire unpaid orders after 24 hours”, with the evidence: the oldest urgent ticket, it blocks inventory reconciliation, two customer requests linked. Noor, the Team’s owner, reads it and clicks Start plan.

Reeve plans it. It reads the ticket and its comments, where a support lead linked the Slack thread that started it. It reads the Confluence page on order states. It reads the decision ledger for acme/checkout and finds a confirmed entry from a ticket in August: orders paid by bank transfer stay pending for seven days. So the plan excludes bank-transfer orders from the 24-hour expiry, and cites the decision. It finds a Playbook rule the Team learned in July, that anything touching order state ships behind a flag, and plans the flag. One question it cannot settle from any source: should an expired order send the customer an email? It asks that one question on the case file.

Noor answers no, not yet, the notifications work is its own ticket. The answer lands in the ledger as a confirmed decision scoped to acme/checkout. She approves the plan.

Wright builds it to a draft pull request. Proctor reviews against the plan, flags that the flag’s default was set to on, and posts one review. Wright corrects it. Fletcher (beta) walks the done-when statements in a browser and attaches the video. Noor merges.

Three weeks later Bailey proposes CHK-341, “Notify customers when an unpaid order expires”. Reeve reads the ledger, finds Noor’s decision from CHK-318 with its reason, and does not ask. The plan arrives with the right scope on the first pass, and the sent-back round a team without the ledger would have paid for does not happen. That round is what context engineering for a team is for.

The same shape runs in spec-driven development with AI: the spec is written before the code, and the decisions it rests on are recorded where the next spec can read them.

How does this change what you pay?

Less than the token arithmetic suggests and more than the ranking pages admit.

Context costs tokens, which is why the ETH study found the files raised cost. True, and it is the small number. The large number is a retry: a plan built on a wrong assumption costs a build, a review, a send-back, a person’s attention, and a second build. That round trip is the part grounding removes. An Agent that reads the relevant decision first does not take it.

On a YAGNI Team the runs are metered on one rate card, on vetted US-hosted open-weight models at 60% or more under comparable frontier API rates, with no seats. Usage shows what each Agent spent, broken out by the job that spent it. The same meter carries your developers: YAGNI Code, the terminal agent, reads the same decision ledger and connected tools from the command line, so a developer pairing with the Team on a hard ticket is working from the same context the Team is.

Start with the why the code does not show

Keep your AGENTS.md short, with only what the code cannot tell an agent. Then look at the right-hand column of the table above and ask who owns each row. If the answer is “the person who was in the thread”, that knowledge is one departure from being lost, and every agent on the team is guessing at it today.

YAGNI runs agent teams, managed like your engineering team. Each Team reads the tools your engineers already keep, records the decisions people make as the work happens, and learns its rules from the corrections your reviewers already write, so the second ticket is better than the first and a person can see why. See how Agent Teams work, or book 30 minutes to attach one of your repositories and read what the ledger seeds from its history before anything else happens. The guide to AI agents for software development covers the Team that reads this context: the six Agents, the checkpoints, and the cost.