- AI era specification management
- spec documentation vs code
- prompt-driven development
- Claude Code specification
- schema-driven development
- Cursor specification
- Copilot specification
Should You Write Specs? 3 Patterns for Specification Management in AI Code Generation Era¶
With the emergence of Copilot, Claude Code, Cursor, and similar tools, the meaning of "writing code" is evolving. How much specification should we write? Can we treat code as the "sole specification"? Can prompts (AI instructions) serve as specifications?
In practice, these questions often get conflated. This article organizes three coexisting approaches in the AI era, presenting a framework for "how to use each where" rather than "which is correct."
Key Points¶
Three approaches to specification management in the AI era (spec documents, code-centric, prompt-driven) Hybrid operation guidelines based on risk, phase, and layer Preventing specification drift using Interface / Contract layers
Table of Contents¶
- Conclusion: Hybrid Operations and Interface Layer Design
- Overview of Three Approaches
- Essential Difference: What to Fix Where
- Strengths and Breaking Points
- Selection Guidelines
- Checkpoints
- Summary
Conclusion: Hybrid Operations and Interface Layer Design¶
Let's start with the conclusion. Going all-in on one approach carries high risk. Realistically, the following hybrid operation is reasonable:
- High-risk, long-term maintenance areas → Heavier specification documents (A-oriented)
- Internal modules, development speed priority areas → Code-as-specification baseline (B-oriented)
- Exploration, spikes → Full prompt-driven usage, elevating to A/B only what you decide to keep (C-oriented)
Additionally, designing the Interface / Contract layer (OpenAPI, Protobuf, GraphQL, type definitions, etc.) as a "common layer where specs, code, and AI converge" makes it easier to control specification drift and accountability.
Key Point of Hybrid Operations
By designing the Interface layer as a "common language for specs, code, and AI," you can maintain verifiable contracts regardless of which approach you adopt.
Overview of Three Approaches¶
Approach A: Specification Document Regression¶
Position: Because AI becomes the implementer, we need to properly document specifications or risk issues.
The underlying assumptions are:
- Human developers could "read between the lines" with team tacit knowledge and historical context
- AI resets each session, unable to infer unstated assumptions
- Consequently, without explicit specifications, AI independently interprets "best practice-style" each time
This position is strong in regulated industries (finance, healthcare, public sector), large enterprise core systems, mission-critical systems, and multi-vendor, offshore, long-term maintenance scenarios.
What (business requirements) is documented thoroughly, sometimes including How (design policy). The worldview is "working code alone doesn't fulfill accountability."
Approach B: Code-as-Specification (Living Documentation)¶
Position: Dual maintenance of specs and code is wasteful. Code and tests are the specification.
This thinking predates AI and aligns well with:
- BDD Gherkin scenarios (test = specification)
- Schema-driven design with OpenAPI / GraphQL / Protobuf
- "Type = contract" orientation in strongly-typed languages like TypeScript / Rust / Go
In the AI era, this accelerates further. Write code, then have AI auto-generate README / ADR / API documentation, centralizing the source of truth in code.
This position is strong in startups, small teams, early product phases, and environments leveraging strongly-typed languages or schema tools.
Approach C: Prompt-as-Specification (Prompt-Driven Development)¶
Position: AI prompts (instruction text) may function as specifications themselves.
With agent-based tools like Claude Code / Cursor / Devin, the flow is:
- Instruct tasks in natural language
- AI performs investigation, design, implementation, and testing end-to-end
- Reviewing prompts and conversation logs somewhat reveals "why it was implemented this way"
Prompts partially substitute the traditional specification role (What/constraint definition).
Important Note
This "prompt-as-specification" conceptual framing is more a hypothesis for capturing the phenomenon than an established industry term. Toolchains are still developing; currently, it's realistic to limit this to PoC or spike contexts.
Essential Difference: What to Fix Where¶
The three approaches aren't just about "whether to write specs." Essentially, it's about which layer's information to "fix" in which medium.
We divide into three layers:
| Layer | Content |
|---|---|
| What | What to achieve (business requirements, user stories, SLA, constraints) |
| Interface / Contract | "Verifiable contracts" like API / events / DB schema / types |
| How | Internal design, architecture patterns, implementation details |
Organizing how each approach handles each layer:
| Layer | A: Spec Document Regression | B: Code-as-Spec | C: Prompt-as-Spec |
|---|---|---|---|
| What | Document thoroughly | User stories + test cases | Prompts and conversation logs |
| Interface | Specs + schema management | Schema (OpenAPI etc.) primary | Auto-generated schema/types |
| How | Design docs or sampling review | Embedded in code and tests | Embedded in AI-generated code |
Key point: Every approach eventually has an "Interface / Contract layer" in some form. This layer functions as the intermediate language connecting human specs, code, and AI.
Strengths and Breaking Points of Each Approach¶
Approach A: Specification Document Regression¶
- Domains with heavy audit and accountability (regulated industries, public sector, finance)
- Large projects involving multiple companies/teams
- Systems with long-term maintenance and handoff assumptions
- Speed degradation: Specification consensus and updates take time
- Dual maintenance cost: Specs and implementation diverge, neither is trusted
- Nobody reads it problem: Developers look at code and tests; specs become audit-only PDFs
AI-era change: AI can draft specifications, lowering "writing from scratch" costs. However, "who reviews and takes responsibility for specs" becomes heavier.
Approach B: Code-as-Specification (Living Documentation)¶
- Startups, small teams, early product phases
- Strongly-typed languages like TypeScript / Rust / Go / Kotlin
- Combination with schema tools like OpenAPI / GraphQL / Protobuf / Prisma
- Business-side explanation gap: "Specs are in code" doesn't resonate
- External integration / contractual basis gap: "Read GitHub" doesn't work for contracts
- Intent loss in long-term maintenance: Hard to recover "why this spec exists" background from code
AI-era change: Auto-generating README / ADR / API docs from code strengthens B further.
Approach C: Prompt-as-Specification (Prompt-Driven Development)¶
- PoC / experiments / spike tasks
- Exploratory phases where requirements aren't finalized
- 1-2 person development close to individual work
- Prompt history fragmentation: Unclear which conversation is the "final spec"
- Traceability absence: Can't trace "who generated what with which prompt" later
- Unclear accountability: Ambiguous where responsibility lies among prompt author, AI, reviewer
Current limitation: Toolchains for version-controlling prompts and outputs together, trackable at team level, are still developing.
Selection Guidelines: Risk × Phase × Layer¶
Going all-in on one approach is risky. Decide "where to emphasize A/B/C" based on risk, phase, and layer axes.
Axis Definitions¶
| Axis | Categories |
|---|---|
| Risk | High (legal, major customers, high financial impact) / Mid (medium customers, medium impact) / Low (internal tools, PoC) |
| Phase | PoC/spike / Beta/growth / Production stable operations / Long-term maintenance |
| Layer | What / Interface / How |
Guideline Matrix¶
| Condition | Recommended Approach |
|---|---|
| High × Production/Long-term × What/Interface | A+B: Spec documents required + schema integration |
| Mid × Growth × Interface/How | B-centric: Code-as-spec, schema-driven, minimal ADR |
| Low × PoC × All layers | C-centric: Prompt-driven for speed priority, elevate to A/B only if keeping |
What matters is verbalizing "which cell gets which approach" as a team once.
Example policies:
- "Finance production API What/Interface uses A/B"
- "Admin UI internals go B-only"
- "Prototypes use C, elevate to A/B side only what we decide to keep"
Having this level of policy makes explaining "why write thick specs here / not there" easier.
Checkpoints: Where Is Your Team?¶
Quick checkpoint for considering which way to lean (A/B/C).
Question 1: What's the scariest risk?
- Audit / lawsuit / contract breach → A-oriented
- Speed degradation / market opportunity loss → B/C-oriented
- Team productivity / burnout → B-oriented
Question 2: Where's the biggest bottleneck now?
- PR reviews clogged → Revisit Interface layer
- Lost on "what to build" → Clarify spec origin with A or C
- "What's the spec?" unclear → Consider B-oriented reverse generation approach
Question 3: What's your product phase?
- Not yet customer-facing → C-heavy is fine
- Revenue generating, customers attached → Increase A/B ratio
- 5+ year maintenance assumption for core system → A/Interface layer investment nearly mandatory
Summary¶
The three approaches aren't mutually exclusive.
- All-A makes the field too heavy to move
- All-B clogs external explanations, long-term maintenance, cross-org coordination
- All-C makes reproducibility and accountability ambiguous, risky for production
The realistic strategy is hybrid operations based on risk, phase, and layer.
Additionally, designing the Interface / Contract layer as a "common layer where specs (A), code (B), and AI (C) converge" facilitates controlling specification drift and accountability.
Rather than seeking one "correct approach," it's sufficient if this organization serves as a framework for deciding "where to assign A/B/C" based on your product, organization, and risks.
Next Steps
- Verbalize as a team "which cell gets which approach" policy once
- Design Interface / Contract layer (OpenAPI, type definitions, schemas) to prevent spec drift
- Periodically review specification management approach, adjusting for risk and phase