The common failure mode for modern coding agents isn't a lack of data; it's data drowning. A recent deep dive from Lockstep highlights a critical scenario where an agent, bombarded with architecture docs, incident summaries, style guides, and Slack transcripts, still misses the single line constraint that actually matters. The prompt becomes a dumping ground, and the agent’s attention fractures. Context engineering isn't about maximizing input; it's about strategic placement.

The Prompt Is for the Task, Not the Library

Your prompt should answer four things: the desired outcome, the scope, known constraints, and the definition of done. It should not be a repository of every potentially relevant document. Instead of pasting a full style guide, point the agent to the source and require retrieval. If you are updating checkout retries, the prompt needs the specific constraint about duplicate charges, not the entire history of the payment system. Orient the agent; don't bury it.

Files Are for Stable, Version-Controlled Truth

Stable project context belongs in version-controlled files like CLAUDE.md, AGENTS.md, or .cursor/rules. These are for build commands, repository layout, and hard boundaries that the team would otherwise repeat in every session. The key test is stability: if the information changes daily, it does not belong in a startup file. Claude Code and Cursor both support path-scoped rules, allowing you to keep instructions focused and relevant to specific code areas rather than loading a massive manual into every context window.

Live Facts Must Come From Live Systems

Deployment states, ticket ownership, and service health are volatile. Storing them in static files or memory leads to drift. A note saying 'staging runs v2' might be true today and false tomorrow after a rollback. Use tools or MCP connections to retrieve these facts only when they drive a decision. Keep the retrieval instructions in the project file, but keep the actual fact in the system that owns it. This ensures the agent acts on current reality, not cached assumptions.

Team Memory Is for Decisions, Not Rules

There is a distinction between a rule ('run tests'), a fact ('staging is on v2'), and a decision ('keep dual writes until Customer A exits'). Accepted team choices belong in a shared decision record or ADR. This prevents search algorithms from presenting a rejected proposal with the same weight as the accepted answer. A proper decision record includes the rationale, rejected options, owner, date, and status. This creates a durable, queryable home for architectural choices that agents can consult before altering behavior.

Key Takeaways

  • Prompt: Immediate goal, acceptance criteria, and current task constraints. Load every time.
  • Files: Stable commands, boundaries, and conventions (CLAUDE.md, AGENTS.md). Load at startup.
  • Handoff Files: Unfinished task state. Load when continuing work; delete when done.
  • Live Systems: Changing operational facts (deployments, tickets). Retrieve via tools/MCP on demand.
  • Team Memory: Accepted decisions and ADRs. Consult before changing affected behavior.

The Bottom Line

Stop treating the context window as infinite storage. Good context engineering gives the agent the right data from the right source at the right time, protecting the main context from noise and drift.