01 · Definition
Context is part of the software system.
AI coding agents can produce a plausible patch from a short request, but plausibility is a weak quality signal. A useful change depends on facts that may live in AGENTS.md, tests, deployment notes, ownership boundaries, data contracts, recent incidents, and the history of why a rule exists.
CDD treats those facts as working infrastructure. A task begins with the context needed to make a decision, continues through a change that has explicit scope and stop conditions, and ends with evidence that another person can inspect. The output is code plus a smaller amount of uncertainty.
02 · Why it matters
Generation got faster; judgment stayed scarce.
A prompt can request a feature, but it cannot silently supply the repository's actual conventions, the production boundary, or the evidence required to trust the result. When that context is missing, agents fill gaps with assumptions. The patch may compile while duplicating a route, weakening an authorization check, breaking a migration rollback, or claiming a source that was never verified.
That accumulated gap is context debt. It slows every future change because each worker has to rediscover the same facts, and it makes reviews noisier because the reviewer has to reconstruct the author's assumptions before evaluating the diff.
CDD reduces that tax by making context explicit at the point of work and by recording durable discoveries in the repository or its operating notes. The aim is not more documentation for its own sake; it is less repeated guessing.
03 · The workflow
Five moves from request to evidence.
- Frame the task. Name the outcome, the exact surface that owns it, the non-goals, the approval boundary, and what observable result counts as done.
- Load the context. Read the nearest instructions, relevant code and tests, current dirty state, data contracts, and recent decisions. Separate observed facts from assumptions.
- Make a bounded change. Keep the write set narrow, reuse existing patterns, and preserve unrelated work. A good task packet says when to stop instead of inviting an agent to keep exploring.
- Verify the behavior. Run the smallest useful test first, then the broader check needed for the risk. Inspect the generated artifact or real output when a build, page, model, or release surface is involved.
- Compound the learning. Update the durable instruction, test, source note, or runbook when the work exposed a reusable rule. Future work should start with more signal than this task did.
These moves can be performed by one engineer, several agents, or a scheduled workflow. The ownership and evidence contract remains human-readable even when execution is parallel.
04 · Comparison
CDD is an operating model, not a prompt style.
| Approach | What it optimizes | Where it fails |
|---|---|---|
| Prompt-driven | Fast response to an isolated request | Assumptions stay implicit, so the answer may fit the prompt and miss the system. |
| Document-driven | Written plans and specifications | Documents can become stale unless the code, tests, and operational evidence close the loop. |
| Contract-driven | Explicit inputs, outputs, and acceptance criteria | Contracts still need repository context and runtime checks to describe reality. |
| Context-driven | Decisions that remain grounded in current code, ownership, and evidence | It requires disciplined context retrieval and maintenance, which is work the team must own. |
05 · Practice
A small repository checklist.
Before the change
- Nearest instructions and safety boundaries are known.
- Current branch and dirty files are recorded.
- Owning module, tests, and generated surfaces are identified.
- Acceptance evidence and stop conditions are written down.
After the change
- Focused tests and the relevant broader check pass.
- Generated output, routes, metadata, or real responses were inspected.
- Unverified claims and baseline failures are named.
- Reusable context was added where it will actually be found.
For a concrete starting point, use the Agent-Ready Repo Kit to audit the repository surface, then use the SWE skills to run recurring review and maintenance work.
06 · FAQ
Common questions.
Does CDD mean writing long prompts?
No. It means making the context and acceptance boundary available in the places where work is planned and verified. A short, well-scoped task with the right files and checks beats a long prompt that asks an agent to guess.
Is CDD only for AI-generated code?
No. The same workflow improves human changes, migrations, incident follow-up, and handoffs. AI makes the need more visible because it can act quickly on incomplete context.
What should a team do first?
Pick one recurring change and record its real inputs, owner, validation command, and stop line. Then make the next run leave behind a test, note, or artifact that makes the following run cheaper.
Further reading: The Context Engineer, Context Debt, When Agile Becomes Harmful, and Context-Driven Automations.