OpenSpec explained: turn an AI coding request into reviewable artifacts
Measuring OpenSpec overhead: planning time versus avoided rework
Design a small evaluation without treating Markdown volume or task count as productivity.
What you will learn
- Define a comparable change
- Account for the assistant separately
- Report failures and uncertainty
Before you start
- Basic Git and Node knowledge
- A disposable sample repository
Display dependencies and missing evidence without automatically executing the next instruction.
Key takeaways
- Accepted changes are the useful denominator.
- Assistant costs are a separate dependency.
- Graph correctness is not a productivity benchmark.
Define a comparable change
Select several small changes with known acceptance tests and similar scope. Record time spent clarifying behavior, writing artifacts, reviewing implementation and correcting failures. The useful unit is an accepted change, not a generated document.
Do not compare a trivial prepared task with an unfamiliar cross-service feature and attribute the difference to OpenSpec. Record repository familiarity, assistant version and requirement ambiguity alongside elapsed time.
Account for the assistant separately
OpenSpec’s MIT license does not pay for an external coding assistant or its model usage. Track assistant calls and review time if your environment exposes them. Avoid entering current provider prices into a static article without a dated source.
Schema guidance can reduce repeated context, but a long or duplicated plan can also consume more context and attention. Measure actual usage and rejected proposals instead of assuming that every additional artifact saves tokens.
Report failures and uncertainty
Keep a record of missed scenarios, implementation rework and plans abandoned before coding. A workflow that catches a wrong requirement early may take longer to plan while producing less downstream rework. Both observations belong in the report.
No latency, token-cost or productivity benchmark was executed here. The worksheet is an experiment design; the six offline graph assertions establish ordering behavior only and cannot support a percentage improvement claim.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Choose comparable changes and acceptance tests.
- 2
Record planning, review and rework separately.
- 3
Publish rejected trials and measurement limits.
Copy-ready example
change,scope,planning_minutes,review_minutes,rework_minutes,accepted,assistant_usage
trial-export,small,,,,,Frequently asked questions
Can task count measure productivity?
No. Tasks differ in scope and may be checked without adequate evidence.
Are savings demonstrated in this series?
No comparative workflow benchmark was performed.
Sources
- OpenSpec / README.mdSource checked 2026-09-23
- OpenSpec / src/core/artifact-graph/graph.tsSource checked 2026-09-23