Spec-driven development is no magic bullet, but it’s useful nonetheless. The trap is expecting any technology to solve all problems — or dismissing it when it doesn’t. Treat every new tool as part of your toolkit and understand its strengths and limitations.
Here are 10 things I’ve learned about working with specs for AI-assisted development.
1. What’s a spec, really?
A spec is different from a prompt or interactive coding session. It’s a structured document that captures what you want the system to do — like providing a recipe rather than asking someone to “cook dinner.” The shift is from micromanagement to delegation.
2. Specs come in different flavors
- Feature specs — functional and technical requirements (prompt.md, spec.md)
- Agent identity specs — personality, boundaries, and behavior definitions
- Task/workflow specs — process coordination and sequencing
- Usage/knowledge specs — domain expertise and patterns
3. Format matters, but not decisively
Markdown dominates because it’s readable and GitHub-friendly. But there are many emerging formats: Cursor rules, Speclang, BMAD patterns, OpenAI model specs, Agents.md, Claude Skills, EARS format. The key reality: specs are sensitive to the models being used.
4. Context window constraints are real
Oversized specs overwhelm agents. Solutions: intelligent context selection, specialized agents with focused scope, AST parsing with LSP integration. Good specs need information architecture, not just consolidation.
5. App regeneration remains limited
Regenerating a full app from specs is possible but demands a planning framework (like Backlog.md). Results vary by language and model training data. It’s an iterative approach, not a “generate once” solution.
6. Tool ecosystem is expanding rapidly
Over 450 tools in the AI Native Dev Landscape, including Kiro, Speckit, Claude Flow. My advice: pick one tool and develop expertise rather than constantly switching.
7. Registries and sharing are emerging
The evolution parallels DevOps — from custom scripts to shared registries. Git submodules work today. Package repositories and public registries are coming, enabling reuse patterns similar to npm or PyPI.
8. Code review remains essential
Human review is crucial. Tests function as intent specifications themselves. Keep implementation and testing agents separate — different perspectives catch different problems.
9. Legacy applications present challenges
The strangler pattern enables gradual modernization. Language-specific model training varies significantly. AST-based tools increasingly bridge existing code and new specs, but specs won’t magically modernize legacy systems.
10. Currently useful despite immaturity
Specs provide a robust alternative to “vibe coding” — iterative prompting without structure. But output varies across models and tools, spec evaluation metrics don’t yet exist, and knowledge capture best practices are still underdeveloped.
Getting started
Begin with a single feature. Include tests from day one. Version your specs in Git. Iterate based on agent responses. Share learnings with your team — specs enable alignment across both humans and AI agents.