Context Engineering: Give an Agent the Right Project State

Context engineering means selecting and organizing the information an AI agent needs for the task it is doing now. In project work, that includes the current goal, relevant files, decisions, verified results and unfinished steps. A larger context window can hold more text, but it cannot decide which version of a plan is current or whether a reported success actually happened.

Start with a small task packet that another person could use to resume the work. This guide shows an illustrative import-dashboard project and a handoff test. The packet is an authored template, not a measured claim about any model's performance.

Separate project knowledge from current task state

Anthropic's context engineering discussion examines how agents manage useful information within a finite context. Its guidance on tools for agents also emphasizes clear, relevant information returned by tools. For a project, the practical question is which facts the next action depends on.

Stable project knowledge might explain how authentication works, where tests live and how deployment is performed. Current task state explains the specific change being attempted, which candidate was checked and what remains unresolved. Keep both available, but do not make them competing accounts of progress.

An older plan can still explain why a decision was made. Label it as historical when the implementation moves on. Otherwise the agent may spend effort reconciling two documents that appear equally authoritative.

Write a task packet with observable completion

The following sample assumes a fictional CSV import dashboard. Replace its identifiers and paths with actual project references. Avoid including private customer rows when synthetic fixtures can express the same requirement.

Goal: Let an operator preview invalid CSV rows before import.
Completion: Valid rows persist; invalid rows show field errors;
reloading shows the same saved import receipt.

Candidate: branch import-preview, revision DEMO-A.
Entry points: upload form, validation service, import receipt.
Preserve: original row numbers and existing owner permissions.

Verified: fixture missing-account.csv is rejected before save.
Evidence: receipt TEST-21, candidate DEMO-A, local environment.
Unknown: corrected import persistence after reload.
Next action: run corrected fixture and read back its receipt.
Stop condition: do not deploy until that check passes.

The completion statement is useful because it includes visible behavior and saved state. “Improve CSV import” leaves too much room for an agent to stop after changing the screen. The preserved behavior also prevents a narrow fix from discarding information that operators already rely on.

Give each verification receipt enough identity to determine its relevance. A passing test from a different candidate is background evidence, not proof that the current candidate works. If the exact revision is unknown, write that uncertainty in the packet rather than guessing.

Select context by the next decision

For the reload check, the agent needs the corrected fixture, import handler, storage boundary and previous receipt format. It probably does not need every design conversation from the start of the project. Link to deeper material and open it when the task reaches that dependency.

This approach also applies to tool output. A search result containing the relevant function and its surrounding logic may be more useful than an entire repository dump. Return paths and identifiers so the agent can inspect the source again when necessary.

Classify the packet's statements as verified, inferred or unknown when the distinction affects the action. “The write returned success” is an observation. “The dashboard will preserve that write after reload” is an inference until checked. That distinction directs the next test without requiring a lengthy discussion of uncertainty.

Keep instructions separate from external source content. An imported document or issue comment may describe a problem, but it should not silently change the project's authorization or deployment rules. The packet should identify the source and summarize the relevant evidence in its own structure.

Make freshness a property of evidence

A timestamp helps readers understand when a record was written. It does not establish whether the facts still match the application. Tie facts to the object that can change: a repository revision, configuration version, document identifier or provider response.

For the fictional dashboard, use these refresh rules:

Refresh what the change affects. Repeating every check after a wording adjustment adds noise; retaining old persistence evidence after changing storage leaves a real gap. The dependency between a change and its evidence is more useful than a blanket “last updated” label.

When summarizing, preserve the unresolved part of a partial result. “Validation passed; persistence not yet checked” is a resumable state. “Import finished” may lead the next agent to skip the remaining work.

Run a handoff test

Give the packet to a fresh agent session or a colleague who has not followed the discussion. Ask them to explain the current goal, locate the relevant candidate and perform the next authorized check. This is a practical test of the packet, not a benchmark of model intelligence.

Inspect what they did rather than whether they can repeat the packet's wording. Did they use the intended fixture? Did they verify the current candidate? Did they preserve the original row numbers? Did they stop before deployment if the required result was missing?

If they cannot locate the candidate, add the repository identity and revision. If they rerun completed work, distinguish current evidence from unfinished steps. If they deploy prematurely, make the stopping condition and authorization boundary explicit. Fix the specific missing information before expanding the document.

Also test a changed user request. Suppose the operator asks to preserve only valid rows while reporting invalid ones. That changes the original all-or-nothing behavior. Update the objective, acceptance example and affected tests together. A task packet should preserve accepted steering rather than leaving the new request only in chat history.

Build a task-state board with Atoms

Atoms can help build and iterate on a web application from a written brief. A task-state board can make goals, candidates, receipts and next actions visible to the project team. It does not automatically receive repository changes or agent memory; start with manual or synthetic records and specify any later integration separately.

Build a project handoff board with synthetic import tasks.
Each task has goal, completion criteria, candidate revision,
preserved behavior, accepted decisions, evidence receipts,
unknowns, next action and stopping condition. Show verified,
inferred and unknown states distinctly. A receipt records
candidate, environment, check, result and evidence reference.
Keep historical decisions readable without making them the
current status. Begin with manual editing and demo fixtures.

Start with the AI app builder workflow. For a board that also tracks release readiness, the QA dashboard guide connects scenarios to candidate-specific evidence.

Before inviting a team, check whether a saved task survives reload and whether its history identifies the author of a change. Define who can edit completion criteria and who can record evidence. These are application behaviors to verify, not conclusions drawn from the appearance of the board.

Conclusion

Good context engineering gives an agent enough reliable state to make the next decision. Maintain one current task packet, connect claims to their evidence and preserve meaningful unknowns during handoff. Use Atoms to prototype a shared task board, then test whether someone can resume the work correctly from that board alone.

FAQs

Q1: Is context engineering the same as prompt engineering?

They overlap, but project context includes more than the wording of one request. It includes which files are available, what tools return, how current state is recorded and which evidence is retained during handoff. A carefully phrased prompt can still fail if it points to an obsolete plan or omits an unfinished check. Start by making the task state accurate and accessible, then improve the instructions that use it. For a small project, a concise packet with clear references may be enough; a larger memory system is not automatically necessary.

Q2: What should I keep when summarizing an agent task?

Keep the goal, accepted constraints, current candidate, meaningful decisions, verified results, unresolved questions and next authorized action. Include references that let the next session inspect the underlying evidence. Remove repeated discussion that no longer changes the decision, but preserve corrections that changed the objective. A summary should distinguish a completed local check from a production result and a proposed action from an authorized one. Test the summary by asking someone unfamiliar with the conversation to resume the task. Their behavior reveals missing context more clearly than a polished summary does.

Q3: How often should project context be updated?

Update current task state when the objective changes, a decision is accepted, a check produces new evidence or the next action changes. Refresh stable project knowledge when its underlying behavior changes. You do not need to write a new document for every command or chat message. For evidence that can become stale, record the candidate or configuration it describes and revisit it when that dependency changes. This keeps updates useful and limits competing progress records. The aim is a reliable current state, not a large volume of timestamped notes.