{"slug": "coding-agent-context-engineering-make-agents-read-before-they-edit", "title": "Coding Agent Context Engineering: Make Agents Read Before They Edit", "summary": "A developer argues that coding agents fail not because they can't write code, but because they write too soon without sufficient context. The proposed solution is a context engineering workflow that forces agents to collect evidence—such as repo maps, retrieved decisions, and impact analysis—before editing. This approach aims to build trust by requiring agents to prove understanding of the codebase before making changes.", "body_md": "A coding agent does not usually fail because it cannot write code. It fails because it writes too soon.\n\nIt opens a few files, guesses the architecture, edits the wrong seam, runs a narrow test, and returns a confident summary. The pull request may even look clean. Then you find the real damage later: a broken tenant boundary, a missed migration, a hidden side effect, or a test that passed because it never touched the risky path.\n\nThe fix is not a longer prompt. It is a context engineering workflow that forces the agent to collect evidence before it edits.\n\nFor AI app builders, solo developers, and small product teams, this matters more than it sounds. AI coding tools are getting faster, agent frameworks are improving, and repo-scale assistants are moving from demos into daily work. Speed is no longer the scarce resource. Trust is.\n\nThis guide shows how to design a practical pre-edit context layer for coding agents: repo maps, local indexes, retrieved decisions, impact analysis, test discovery, and verification receipts.\n\nThe goal is simple: make the agent prove it understands the codebase before it changes the codebase.\n\nMost teams treat context as a chat problem:\n\n`README.md`\n\n.That helps, but it is not enough for production work.\n\nA coding agent needs a repeatable way to answer these questions before editing:\n\nWithout this, agents burn tokens rediscovering the same repo shape over and over. Worse, they rely on partial evidence. A few text matches become an architecture model. A passing unit test becomes a release signal. A prompt instruction becomes a substitute for real code inspection.\n\nContext engineering turns that loose behavior into a workflow.\n\nCurrent AI developer tooling is pointing in the same direction: agents need structured evidence, not just larger windows.\n\nRecent signals include local code intelligence tools that expose symbols and references, memory tools that reduce repeated exploration, monitors that track context windows and cost, and review agents that require exact file-line evidence. The pattern is clear: teams are no longer satisfied with “the agent seemed smart.” They want evidence before edits, proof after edits, and readable receipts during review.\n\nContext engineering is the design of what an AI system sees, when it sees it, and how it proves that the context is relevant.\n\nFor coding agents, it has five layers.\n\n| Layer | Purpose | Example evidence |\n|---|---|---|\n| Task context | Defines the work | issue, user story, acceptance criteria, non-goals |\n| Repo context | Shows code structure | files, symbols, routes, schemas, dependencies |\n| Memory context | Recalls prior decisions | ADRs, past fixes, migration notes, gotchas |\n| Risk context | Highlights danger zones | auth, billing, tenant isolation, deletion, PII |\n| Verification context | Proves the outcome | tests, lint, typecheck, traces, logs |\n\nA good agent workflow does not dump all of this into the prompt. That creates noise. Instead, it retrieves the smallest useful slice at each stage.\n\nThink of it as a pipeline:\n\n``` php\ntask brief\n  -> repo search\n  -> symbol/reference lookup\n  -> impact analysis\n  -> memory retrieval\n  -> plan\n  -> edit\n  -> verification\n  -> review receipt\n```\n\nThe key is order. Evidence comes before the plan. The plan comes before the edit. Verification comes before the summary.\n\nThe most dangerous coding-agent failure is not an obvious crash. It is confident partial context.\n\nYou see it when the agent says:\n\nThe output looks professional. The summary is crisp. But the agent never built a complete enough map of the change.\n\nThis is especially risky in AI app codebases because small edits often cross boundaries:\n\nThe agent needs to see these connections before it starts typing.\n\nUse a pre-edit routine for any agent task that touches production code, data, auth, billing, integrations, or AI behavior.\n\n```\n1. Restate the task and non-goals.\n2. Identify likely files and symbols.\n3. Find references and callers.\n4. Identify tests and missing tests.\n5. Retrieve relevant memory or decisions.\n6. Name risks and assumptions.\n7. Propose an edit plan with validation commands.\n8. Wait for approval or continue only if risk is low.\n```\n\nYou can give this routine to an agent as a policy, but it works better when backed by tools.\n\nFor example, a repo-aware agent can run:\n\n```\nrepo_status\nsearch_code(\"usage metering webhook\")\nget_definition(\"recordUsage\")\nget_references(\"recordUsage\")\nimpact_analysis(\"recordUsage\")\nfind_tests_for_change(\"usage metering webhook\")\nplan_change(\"add idempotency to usage webhook\")\n```\n\nThe exact tool names do not matter. The behavior does.\n\nThe agent should not move from “search” to “edit” until it can explain primary files, related files, expected side effects, validation commands, confidence level, and known gaps.\n\nImagine you are changing an AI support agent so it can escalate billing questions to a human.\n\nA weak prompt says:\n\n```\nAdd human escalation for billing questions in the support agent.\n```\n\nA better context packet says:\n\n```\ntask: Add human escalation for billing questions in the support agent.\nintent: Billing conversations should create an escalation ticket instead of giving account-specific billing advice.\nnon_goals:\n  - Do not change pricing logic.\n  - Do not expose invoice details in model prompts.\n  - Do not auto-refund or modify subscriptions.\nrisk_zones:\n  - billing data\n  - tenant isolation\n  - tool permissions\n  - PII in logs\nrequired_evidence:\n  - support agent route or workflow entrypoint\n  - billing intent classifier or prompt\n  - escalation tool schema\n  - existing ticket creation tests\nvalidation:\n  - unit tests for billing intent classification\n  - integration test for escalation ticket creation\n  - log redaction check\n```\n\nThis is still short, but it gives the agent a map. It also defines what “done” means.\n\nAgents waste time when every task starts with blind exploration. A repo map reduces that cost.\n\nA useful repo map can start as one markdown file:\n\n```\n# Repo Map\n\n## Product areas\n- `apps/web`: user-facing dashboard\n- `apps/api`: API routes and background jobs\n- `packages/ai`: prompts, model routing, tool schemas\n- `packages/db`: schema, migrations, query helpers\n- `packages/evals`: golden tasks and regression evals\n\n## Risk zones\n- Auth: `apps/api/src/auth`, `packages/db/src/tenant.ts`\n- Billing: `apps/api/src/billing`, `packages/stripe`\n- AI tools: `packages/ai/src/tools`\n- Retrieval filters: `packages/ai/src/retrieval`\n\n## Validation commands\n- `pnpm test`\n- `pnpm typecheck`\n- `pnpm lint`\n- `pnpm evals:agent`\n```\n\nThis map gives agents a starting point. It also helps human reviewers see whether the agent touched the right surface area.\n\nAgent memory is useful, but it can become dangerous if it outranks the current code.\n\nGood memory items look like this:\n\n```\n{\n  \"scope\": \"billing-webhooks\",\n  \"fact\": \"Webhook handlers must use idempotency keys from Stripe event IDs before writing usage records.\",\n  \"source\": \"incident-usage-duplicates.md\",\n  \"last_verified\": \"2026-07-04\",\n  \"confidence\": \"high\"\n}\n```\n\nBad memory items look like this:\n\n```\n{\n  \"fact\": \"Billing is handled in the old webhook file.\"\n}\n```\n\nThe first memory has scope, source, and a verification date. The second may be stale and misleading.\n\nUse memory for architectural decisions, prior incidents, gotchas, migration warnings, evaluation failures, and “do not repeat this” notes.\n\nDo not use memory as a replacement for code search. The agent should retrieve memory, then verify it against the current repo.\n\nA safe instruction is:\n\n```\nUse memory to guide exploration, not to conclude. If memory conflicts with code, trust current code and report the conflict.\n```\n\nMany agents edit first and look for tests later. Reverse that.\n\nBefore editing, the agent should answer which tests cover current behavior, which test should fail before the fix, which test proves the new behavior, and which validation is too expensive to run locally. A small test discovery note can prevent a lot of review pain:\n\n```\n## Test discovery\n\nLikely existing tests:\n- `packages/ai/src/tools/__tests__/ticket-tool.test.ts`\n- `apps/api/src/support/__tests__/support-agent-route.test.ts`\n\nMissing test:\n- No regression test confirms billing questions create escalation tickets without exposing invoice data.\n\nPlan:\n- Add a failing test for billing intent -> escalation.\n- Add a redaction assertion for logs.\n- Run support-agent route tests and agent tool tests.\n```\n\nThis stops the agent from treating tests as cleanup and starts treating them as navigation.\n\nNot every change needs the same ceremony. A typo fix should not require a full architecture review. A billing-agent tool change should.\n\n| Tier | Example | Agent behavior |\n|---|---|---|\n| Low | docs, comments, isolated UI copy | inspect, edit, run narrow check |\n| Medium | UI logic, internal API, non-critical job | pre-edit plan, tests, summary receipt |\n| High | auth, billing, tenant data, AI tools, deletion | approval gate, impact analysis, rollback note |\n| Critical | production data migration, permission model, external writes | human review before execution |\n\nFor AI systems, mark these as high risk by default: prompt changes that affect customer-visible answers, tool permission changes, retrieval filter changes, memory writes, model routing changes, fallback logic, usage metering, PII handling, and tenant isolation.\n\nA final agent message should not be “done.” It should be a receipt.\n\n```\n## Change summary\n- Added billing escalation path for support agent.\n\n## Evidence used\n- Read support route, intent classifier, escalation tool, and audit log code.\n- Checked references for `createEscalationTicket`.\n\n## Validation run\n- `pnpm test support-agent-route` ✅\n- `pnpm test agent-tools` ✅\n\n## Risks remaining\n- Did not run full eval suite because it takes 40 minutes.\n```\n\nThis format separates claims from evidence and tells the reviewer where to look.\n\nYou can implement a context gate without building a full platform.\n\nCreate `.agent/context-gate.md`\n\n:\n\n```\n# Context Gate\n\nBefore editing production code, complete this checklist:\n\n- [ ] Restate task and non-goals.\n- [ ] List primary files with reason.\n- [ ] List references/callers checked.\n- [ ] List tests found before editing.\n- [ ] List risk tier.\n- [ ] List validation commands.\n- [ ] List unknowns.\n\nDo not edit high-risk files until the plan includes risk, rollback, and validation.\n```\n\nThen add a short agent instruction:\n\n```\nFor code tasks, read `.agent/context-gate.md` first. Complete the checklist before editing. If the change is high risk, pause after the plan.\n```\n\nMore context is not always better. Large irrelevant context can make the agent slower and less accurate. Use retrieval and handles instead.\n\nMemory should have source, scope, and verification. Stale memory is just a confident rumor.\n\nTests guide the plan. Find them before editing.\n\nA CSS tweak and a tenant-filter change should not have the same workflow.\n\nA summary tells you what the agent claims. A receipt tells you what the agent checked.\n\nIf you are a solo builder or small AI product team, start here:\n\nHigh-risk file patterns can be simple:\n\n```\nhigh_risk:\n  - \"**/auth/**\"\n  - \"**/billing/**\"\n  - \"**/migrations/**\"\n  - \"**/tools/**\"\n  - \"**/retrieval/**\"\n  - \"**/tenant*.ts\"\n  - \"**/prompts/**\"\n```\n\nThen tell the agent:\n\n```\nIf a touched file matches a high-risk pattern, stop after the plan and explain risk, rollback, and validation.\n```\n\nThat one rule can prevent a lot of expensive agent confidence.\n\nCoding agent context engineering is the practice of designing what evidence an AI coding agent receives before, during, and after a code change. It includes task briefs, repo maps, code indexes, memory, risk rules, tests, and verification receipts.\n\nNo. A larger context window can help, but it does not guarantee relevance. Agents still need retrieval, symbol lookup, reference checks, test discovery, and risk rules so they use the right context instead of more context.\n\nYes, but memory should guide exploration rather than replace code evidence. Good memory includes source, scope, freshness, and confidence. The agent should verify memory against the current repo before relying on it.\n\nBefore editing, an agent should restate the task, list non-goals, identify primary files, check references, find tests, retrieve relevant decisions, assign risk, and propose validation commands.\n\nRequire a verification receipt. The receipt should list evidence used, files touched, tests run, risks remaining, and reviewer focus areas. This gives human reviewers a trail instead of only a diff.\n\nRequire approval for high-risk changes such as auth, billing, tenant isolation, data deletion, migrations, AI tool permissions, retrieval filters, memory writes, prompt changes that affect users, and external actions.", "url": "https://wpnews.pro/news/coding-agent-context-engineering-make-agents-read-before-they-edit", "canonical_source": "https://dev.to/jackm-singularity/coding-agent-context-engineering-make-agents-read-before-they-edit-19ik", "published_at": "2026-07-04 14:51:07+00:00", "updated_at": "2026-07-04 15:18:37.446745+00:00", "lang": "en", "topics": ["artificial-intelligence", "developer-tools", "ai-agents", "large-language-models", "ai-products"], "entities": [], "alternates": {"html": "https://wpnews.pro/news/coding-agent-context-engineering-make-agents-read-before-they-edit", "markdown": "https://wpnews.pro/news/coding-agent-context-engineering-make-agents-read-before-they-edit.md", "text": "https://wpnews.pro/news/coding-agent-context-engineering-make-agents-read-before-they-edit.txt", "jsonld": "https://wpnews.pro/news/coding-agent-context-engineering-make-agents-read-before-they-edit.jsonld"}}