Context engineering for coding agents: what belongs in the prompt, files, and team memory

A coding agent receives a prompt to change checkout retries.

The prompt includes the feature request, a pasted architecture document, two incident summaries, a full style guide, recent Slack messages, and the transcript from yesterday's debugging session.

The important constraint is one line inside the second incident: a third payment attempt can duplicate a charge with one provider.

The agent has more context than ever. It still misses the fact that matters.

Context engineering is not the practice of putting everything into the window. It is the practice of selecting the smallest useful set of information, giving each kind of context a reliable home, and retrieving it when the task needs it.

The short answer

Context	Best home	Load when
Immediate goal and acceptance criteria	Prompt	Every task
Stable commands and boundaries	CLAUDE.md, AGENTS.md, scoped rules	At startup or matching paths
Unfinished task state	Handoff file	When continuing the task
Changing operational facts	Live tool or MCP source	When the fact drives a decision
Accepted team choices	Shared decision record or ADR	Before changing affected behavior
Large reference material	Searchable docs or skills	On demand
Personal recurring learnings	Local agent memory	When useful to that person or environment

A prompt should orient the agent, not become the team's entire knowledge system.

Put the task in the prompt

The prompt should answer:

• What outcome do we want?
• What is in scope?
• What constraints are known now?
• What does done mean?
• What should the agent inspect before acting?

Update checkout retry handling for Provider A.

Scope: services/checkout and its tests.
Done when: duplicate-charge fixture passes, existing Provider B behavior is unchanged,
and the plan names any conflict with accepted payment decisions.
Before editing: read the payment rules and current Provider A decision.

Do not paste every potentially relevant document. Point the agent to the sources and require retrieval where it matters.

Put stable project context in files

Version-controlled instruction files are for information the team would otherwise repeat in many sessions:

• build and test commands
• repository layout
• coding and review conventions
• hard project boundaries
• short pointers to decisions and deeper docs

## Payments
- Run focused tests with `pnpm test payments`.
- Never retry a non-idempotent capture automatically.
- Read matching accepted records in `docs/adr/` before changing provider flows.

Claude Code reads project CLAUDE.md and supports path-scoped files in .claude/rules/. Cursor supports .cursor/rules and AGENTS.md. Both recommend focused instructions rather than large copied manuals.

The test is stability. If an item changes every day, it does not belong in a startup file.

Sources: Claude Code memory and Cursor Rules

Put unfinished work in a handoff

Conversation history contains exploration. A handoff contains the current state.

# Checkout retry handoff

Done:
- reproduced duplicate capture
- added Provider A fixture

Next:
- change retry classifier
- rerun `pnpm test payments`

Constraint:
- keep Provider B at three retries
- current Provider A decision: PAY-18

Open risk:
- manual recovery path has no integration test

A handoff should be temporary. Close or remove it when the task finishes so the next agent does not follow stale next steps.

Anthropic's guidance for long-running agents recommends durable progress artifacts and clean state for the same reason: a fresh context window needs the result of prior work, not every token used to reach it.

Source: Effective harnesses for long-running agents

Retrieve changing facts from live systems

Deployment state, incident status, ticket ownership, current service health, and customer configuration change too quickly for copied memory.

Use the source through a tool or MCP connection. Ask it when the fact becomes action-driving.

A static note can say staging runs v2 long after a rollback. A live deployment source can answer what is running now, with its own timestamp and scope.

Keep retrieval instructions in the project file. Keep the fact in the system that owns it.

Put accepted choices in team memory

A team decision is different from a rule and different from a fact.

"Run tests before merging" is a rule. "Staging is on v2" is a current fact. "Keep dual writes until Customer A exits the old API" is a decision.

A decision record should include:

• accepted choice
• rationale and constraints
• rejected options
• owner and date
• affected scope
• status
• replacement link

This prevents search from presenting a proposal and the accepted answer as equal context. Repository ADRs work for codebase-local architecture. Cross-repository product and engineering choices need a shared system every agent can query.

Load large context just in time

Anthropic describes context as a finite resource. Tool definitions, retrieved documents, conversation history, instructions, and outputs all compete inside the window.

Use progressive retrieval:

1. Load short instructions and the task.
2. Search an index or source for likely relevant material.
3. Read the matching records.
4. Follow links to current replacements.
5. Pull large references only when the plan needs them.

This is more reliable than loading a complete wiki before the agent knows which subsystem matters.

Source: Effective context engineering for AI agents

Use subagents to protect the main context

A focused subagent can inspect a large log, repository area, or research corpus and return the relevant result. This keeps raw material out of the main task's context.

Use this when:

• the search space is large
• the task can be bounded clearly
• the main agent needs findings, not every source token

Do not use subagents as a substitute for ownership. The final plan still needs one agent or person to reconcile findings against the current decisions.

Compact with intent

Long sessions eventually compact. Claude Code can summarize automatically or through /compact with a focus.

/compact preserve the current checkout plan, failed approaches, Provider A
constraint, tests run, and the next exact step

Project-root instructions and several startup context mechanisms reload after compaction. Conversation-only details may survive only as summary. If a constraint must persist across sessions and people, promote it to the correct durable home instead of trusting the summary.

Source: Claude Code context window

A context budget for a real task

For a payment retry change:

Startup

• root project instructions
• payment path rule
• tool names, not full tool results

Prompt

• exact outcome
• files or service in scope
• acceptance criteria
• instruction to check current payment decisions

Retrieved on demand

• current Provider A decision
• matching incident detail
• relevant code and tests
• live provider configuration

Written during the task

• plan and ownership in the task system
• handoff if unfinished
• new decision proposal if the current decision must change

Not loaded unless needed

• unrelated incidents
• full repository wiki
• old transcript
• every payment ADR

Common mistakes

Treating the prompt as long-term memory

The next session may not receive it. Move repeated instructions and accepted choices into durable sources.

Treating files as live facts

Static copies drift. Query the source that owns changing state.

Loading every rule in every session

Use scope and relevance. Too many instructions can conflict and reduce adherence.

Using search without lifecycle fields

Similarity finds related text, not the current authority. Decisions need status and replacement links.

Saving outputs but not ownership

A note with no owner cannot tell the next agent who may confirm or change it.

Related guides

For why agents forget and the memory layers that fix it, start with the AI coding agent memory guide. For the wider market, see the best tools for AI coding agent context. For storage boundaries, compare CLAUDE.md and agent memory. For live protocol options, see the best MCP servers for engineering teams.

For durable team choices, compare the best decision log tools for product and engineering.

Where Lockstep fits

Lockstep is the shared home for accepted product and engineering decisions inside the context stack.

Prompts can name the task. Files can guide the agent. Handoffs can carry unfinished state. MCP can retrieve live facts. Lockstep supplies the current choice, rationale, rejected options, owner, scope, and status when an agent is about to change affected work.

Good context engineering does not make one mechanism remember everything. It gives the agent the right context from the right source at the right time.