diff --git a/knowledge/published/spec-driven-development-for-ai-coding-agents.md b/knowledge/published/spec-driven-development-for-ai-coding-agents.md index a12bee4..a0badd0 100644 --- a/knowledge/published/spec-driven-development-for-ai-coding-agents.md +++ b/knowledge/published/spec-driven-development-for-ai-coding-agents.md @@ -29,20 +29,24 @@ sources: url: 'https://www.swebench.com/original.html' - title: 'Bun: Rewriting Bun in Rust' url: 'https://bun.com/blog/bun-in-rust' - - title: 'Test-Driven Development for Code Generation' + - title: Test-Driven Development for Code Generation url: 'https://arxiv.org/abs/2402.13521' - title: 'TDAD: Test-Driven Agentic Development' url: 'https://arxiv.org/abs/2603.17973' + - title: OpenSpec concepts + url: 'https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md' + - title: OpenSpec getting started + url: 'https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md' aiAssisted: true generatedBy: Co sourceDigest: 'sha256:2c1346b177c414e224f697e476192dafbf8f542611ed553868b3ace88f86859c' -updated: '2026-07-20T22:35:00.000Z' +updated: '2026-07-23T20:08:00.000Z' reviewStatus: approved reviewedBy: Cameron -reviewedAt: '2026-07-20T23:00:00.000Z' +reviewedAt: '2026-07-23T20:15:55.347Z' publishedAt: '2026-07-20T23:00:00.000Z' -reviewedContentDigest: 'sha256:99811596b3efc7d34c012b5dde16d107925ea9e4b0807d9f8f4eac1d003fa949' -reviewReceiptDigest: 'sha256:7ef7b1051046099b58fe1e94d30ec9bda18ad7aba3ca6fbd249f10ffa7a00502' +reviewedContentDigest: 'sha256:5e5f0fe8e87bffd27ab7b3bfe165838c256e0539a7e6304c6c0b75a8ee206850' +reviewReceiptDigest: 'sha256:ae65d737b6dc7edd02b2538aef780de4b1ac2b8144e12606be89a4c39a1078a5' --- Spec-driven development for AI coding agents is a software-development method in which durable specifications, constraints, and verification evidence guide delegated implementation. It treats generated code as a replaceable artifact and preserves product intent in documents and tests that can be inspected across agent sessions. @@ -85,6 +89,23 @@ The specification surface is the set of documents that define what a system clai - implementation changes code; - convergence repairs disagreement among those artifacts. +#### OpenSpec: current truth and proposed deltas + +[OpenSpec](https://openspec.dev/) is a concrete, brownfield-first implementation of this separation. It keeps the system's agreed current behavior under `openspec/specs/`, organized by domain, while each proposed modification receives a self-contained folder under `openspec/changes/`. + +A change can contain four related artifacts: + +- `proposal.md` records intent and scope; +- delta specs record requirements being added, modified, or removed; +- `design.md` records technical decisions; +- `tasks.md` records the implementation checklist. + +When the change is archived, its deltas merge into the current specs and the complete change folder moves into an archive. The repository therefore retains both the current behavioral contract and the history of how that contract changed. + +OpenSpec's important move is temporal: **current truth and proposed change are different objects**. A reviewer can inspect the requirement delta before reading the implementation, and multiple changes can remain separate until each is ready to alter the shared specification. Its artifact dependency graph is configurable and deliberately fluid; dependencies describe which artifacts can be produced from existing context rather than imposing an irreversible waterfall. + +This pattern strengthens the specification surface, but it does not supply the other three layers by itself. OpenSpec can validate artifact structure and exposes an optional verification command, but Git-backed Markdown alone does not establish that repository assumptions are current, select the right regression evidence, or prove that an external effect occurred. Repository grounding, verification maps, and execution receipts remain separate obligations. + The specification needs enough precision to constrain work without freezing every implementation detail. A cathedral of Markdown is still a cathedral, even when the clergy are agents. ### Repository grounding @@ -205,6 +226,7 @@ This lesson combines peer-reviewed work, active software documentation, recent p ## Sources - GitHub. [Spec Kit](https://github.com/github/spec-kit) and [Spec-Driven Development methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md). +- Fission-AI. [OpenSpec](https://openspec.dev/), [core concepts](https://github.com/Fission-AI/OpenSpec/blob/main/docs/concepts.md), and [getting started](https://github.com/Fission-AI/OpenSpec/blob/main/docs/getting-started.md). - Taghavi and Bhavani (2026). [“Spec Kit Agents: Context-Grounded Agentic Workflows”](https://arxiv.org/abs/2604.05278). - Piskala (2026). [“Spec-Driven Development: From Code to Contract in the Age of AI Coding Assistants”](https://arxiv.org/abs/2602.00180). - Mathews and Nagappan (2024). [“Test-Driven Development for Code Generation”](https://arxiv.org/abs/2402.13521).