Spec-Driven Development vs Context Engineering
Spec-driven development defines intent. Context engineering supplies the broader understanding required to execute that intent correctly.
Updated September 9, 2026: Clarified the comparison, linked supporting references, and reviewed current Archcore behavior.
A spec is one input to the agent. The comparison below separates the work of defining a contract from the work of supplying that contract with the relevant project background. GitHub Spec Kit illustrates specification-led workflows; Anthropic describes the broader context-management problem.
Spec-driven development vs context engineering: what differs?
| Spec-driven development | Context engineering | |
|---|---|---|
| Question | What should be built? | What does the agent need to know while building? |
| Artifact | A specification, upstream of the code | Architecture, decisions, rules, plans, and specs |
| Timing | Before implementation | During every turn of every session |
| Success | The result matches the contract | The result fits the system |
| Fails as | Code that satisfies the spec and fits nothing | Code that fits the system and does the wrong thing |
Note the two failure modes at the bottom. They are opposite, and each practice is the fix for the other’s failure.
What a spec cannot tell the agent
A specification for a session API can define behavior precisely while leaving these implementation constraints unstated:
- where in this repository that kind of code lives
- which library the team already chose, and which it rejected last quarter
- what conventions the surrounding module follows
- which prior decision the obvious implementation would violate
- what is already half-built on another branch
A spec can include these constraints or link to them. Shared background is usually easier to maintain once, with references from the contracts that depend on it. It belongs in project context, which is the broader set.
What context cannot tell the agent
The reverse gap is just as real, and it is the one teams hit after their context practice matures.
Architecture, decisions, and rules describe how the system is. They may leave the intended behavior of a new feature unspecified. An agent that knows your conventions perfectly will still build the wrong thing if nobody stated what “right” meant. Context helps the agent account for the system; the spec supplies criteria for checking the requested behavior. Tests and review still establish whether the implementation meets them.
The collapse in both directions
Collapsing context into specs. The team writes excellent specifications and treats them as the whole context. Every spec has to restate the architecture and the conventions to be useful, so specs grow, duplicate each other, and drift apart. The first sign is copy-pasted background sections.
Collapsing specs into context. The team documents architecture, decisions, and rules well, and never states what a change is supposed to achieve. The agent produces code that fits the system beautifully and solves an adjacent problem. The first sign is review comments about scope rather than style.
The relation that keeps them straight
A spec is one type of document inside project context, with a specific job: the normative contract for a boundary other things depend on.
That framing gives you a usable test for what to write.
| If the knowledge is | Write |
|---|---|
| What a boundary must guarantee to others | A spec |
| A choice that was made, and why | A decision |
| A standard that binds code in a directory | A rule |
| The shape of the system and why | Architecture |
| Work in progress and its next step | A plan |
Only the first row is a specification. The other four are context, and they are what most repositories are missing more of.
Where the two meet: after the merge
The practices converge at exactly the point where spec practices usually fail.
A spec written as a handoff artifact stops being read the day the feature ships. Six weeks later the code and the spec disagree and nobody knows which is wrong.
Keeping a spec as project context gives the team mechanisms to detect and address drift:
- It lives next to the code it constrains, so both can change on the same branch.
- It can be retrieved during a task or delivered before an edit on hosts with pre-write context injection.
- It is what a review measures the diff against.
- It has a status, so a superseded spec is visibly superseded.
A spec remains useful after release when the team keeps reading and maintaining it. Storage and retrieval make that workflow possible; they do not keep the document current on their own.
Practical sequencing
For most teams on an existing codebase:
- Write the decisions you keep re-explaining. Immediate payoff, no ceremony.
- Scope the rules your agent breaks most often to the directories they govern.
- Spec the boundary that breaks other people’s code, not the whole system.
- Add a spec each time you change a boundary, so coverage follows the work.
The distribution this produces is the correct one: the parts of the system that change most are the parts that are specified.
Reading further
- Spec-driven development for AI coding agents: what a spec is and is not, EARS clause form, and the computed planning routes
- Context engineering for AI coding agents: the five properties and why selective delivery matters most
- Project context: what belongs in each document type
Archcore keeps both in the same place, and yes, it is our tool: specs, architecture, decisions, rules, and plans as typed Markdown in a .archcore/ directory, linked to each other and served to any MCP-aware agent.
FAQ
Is spec-driven development a kind of context engineering?
A spec is one artifact within project context, so in that sense yes. But the practices differ in what they optimize. Spec-driven development is about defining intent precisely before implementation. Context engineering is about what the agent knows while implementing, of which the spec is one piece among architecture, decisions, rules, and plans.
Can I do spec-driven development without context engineering?
Yes. A self-contained spec may supply enough information for a small task. In an existing system, check whether it also provides or links the architecture, conventions, and decisions the implementation must respect.
Can I do context engineering without specs?
Yes, and for many teams that is the right starting point. Architecture, decisions, and scoped rules deliver value immediately. Specs earn their cost at boundaries other code depends on, which is a subset of the system rather than all of it.
Which should I start with?
Context, unless you are about to change a boundary other teams depend on. Writing down the decision you keep re-explaining pays off on the next session. Specifying a boundary nobody depends on is cost with no reader.
What happens to a spec after the feature ships?
Keep a useful spec with the code, update it when the contract changes, and use it in review. On hosts with pre-write context injection, Archcore can also deliver it before an edit. A spec stays current only if the team maintains it.