How 5 Engineers Built a 20‑Person‑Weeks Product in 7 Days with Spec‑Driven Development

Case Study: 5 People, 7 Days

Day 0 – No code written : The team spent a full day defining the MVP boundary, breaking down modules, writing a spec.md for each module, and committing all specs to a repository wiki. This zero‑code day created the anchor for the whole project.

Day 1‑2 – Architecture Development

Each member acted as a “Spec engineer”. Using the Qoder framework, the team wrote a plan.md that captured architecture decisions, module breakdown, and interface contracts. The AI generated code and pull requests (PRs); humans reviewed and merged them, allowing a single person to handle multiple PRs per day.

Day 3‑4 – Incremental Spec Updates

When new requirements or bugs appeared, the team immediately added an incremental spec, delegated a Quest, and the AI produced a PR. The human reviewer merged the PR, enabling one person to process several PRs daily.

Day 5‑6 – Polishing and Dogfooding

The early version of QoderWork was used to test itself. New issues were captured as additional specs, and Quests fixed them, forming a self‑reinforcing feedback loop.

Day 7 – Release

The product was officially launched after seven days of coordinated work.

Why Spec‑Driven Development (SDD) Works

SDD is version control for your thinking. – Microsoft

SDD treats the specification as the single source of truth . Code becomes a by‑product of a well‑crafted spec. In the AI era, the quality of the spec directly determines code quality because the model does not ask clarification questions—it merely infers from the provided context.

Four‑File System of Spec Kit

Specify (Human): spec.md – problem statement, success metrics, constraints. Key action: define problem, boundaries, success criteria.

Plan (Human + AI): plan.md – architecture, module breakdown, interface contracts. Key action: choose architecture, split modules, define contracts.

Implement (AI): generated code + tests. Key action: execute tasks from the plan and generate PRs.

Validate (Human + AI): automated test reports. Key action: run tests, review PRs, merge.

Good vs Bad Specs

Good Spec : clear problem statement, measurable success metrics (e.g., P95 < 200 ms), explicit non‑goals, technology‑agnostic constraints.

Bad Spec : vague terms like “fast”, missing boundaries, mixed‑in implementation details, UI‑only concerns in a backend spec.

Concrete Spec Example (User‑Permission Management)

# Feature: 用户权限管理模块
## Problem Statement
当前系统缺乏细粒度的权限控制。所有用户要么是管理员（全部权限），要么是普通用户（只读权限）。产品团队需要支持至少 5 种角色，以满足不同部门的差异化需求。
## Success Metrics
- 支持自定义角色，每个角色可配置不少于 20 种独立权限
- 权限校验 API 响应时间 P95 < 50ms
- 权限变更实时生效，无需用户重新登录
- 向后兼容：现有管理员/普通用户的权限行为不变
## User Stories
1. 作为系统管理员，我可以创建自定义角色并分配权限组合
2. 作为部门主管，我可以将部门成员批量分配到指定角色
3. 作为普通用户，我的权限变更后无需重新登录即可生效
## Acceptance Criteria
- [ ] RBAC 模型支持角色继承（最多 3 层）
- [ ] 单用户可拥有多个角色，权限取并集
- [ ] 提供权限变更审计日志，保留 90 天
- [ ] 权限校验支持通配符匹配（如 `resource:*:read`）
## Non‑Goals
- 本期不实现跨组织的权限委托
- 不支持基于时间段的临时权限
- 不涉及 UI 层的权限管理界面（由前端团队单独出 Spec）
## Constraints
- 必须兼容现有 OAuth2.0 认证流程
- 权限数据存储使用现有 PostgreSQL 实例，不引入新的存储组件
- 权限模型设计需参考 AWS IAM Policy 语法规范

Plan Example

# Plan: 用户权限管理模块
## Architecture Decision
采用 RBAC (Role‑Based Access Control) 模型，使用 Casbin 作为权限引擎。
## Module Breakdown
1. `permission-model` – 权限模型定义与 Casbin 适配层
2. `permission-api` – RESTful API 层
3. `permission-cache` – Redis 缓存层（解决 P95 < 50ms 要求）
4. `permission-audit` – 审计日志模块
## Interface Contracts
POST /api/v1/roles
GET /api/v1/users/{userId}/permissions
PUT /api/v1/roles/{roleId}/permissions
## Risk Assessment
- 风险：角色继承层级过深可能导致权限计算性能下降
- 缓解：限制最大继承深度为 3 层，权限结果做预计算缓存

Tasks Example

# Tasks
## Task 1: 数据库 Schema 设计
- 创建 roles、permissions、role_permissions、user_roles 四张表
- 支持角色继承的 parent_role_id 字段
- 验证：migration 脚本可在空库上成功执行
## Task 2: Casbin 适配层
- 实现 RBAC 模型的 Casbin 配置
- 支持通配符匹配
- 验证：单元测试覆盖率 > 90%
## Task 3: 权限校验 API
- 实现 GET /api/v1/users/{userId}/permissions
- 集成 Redis 缓存
- 验证：压测 P95 < 50ms

Constitution Example (Project‑Level Immutable Principles)

# Project Constitution
## Immutable Principles
### 1. API Design
- 所有 API 遵循 RESTful 规范，版本化路径（/api/v1/...）
- 错误响应统一使用 RFC 7807 Problem Details 格式
- 所有 API 必须有 OpenAPI 3.0 文档
### 2. Security
- 所有用户输入必须经过校验和清洗
- 敏感数据（密码、Token）禁止出现在日志中
- 数据库查询必须使用参数化查询，禁止字符串拼接
### 3. Code Quality
- 单元测试覆盖率不低于 80%
- 所有公共方法必须有文档注释
- 禁止引入未经安全审计的第三方依赖
### 4. Infrastructure
- 所有服务必须支持优雅关闭（Graceful Shutdown）
- 配置项通过环境变量注入，禁止硬编码
- 日志格式统一使用结构化 JSON

Tool Ecosystem Overview

Spec Kit (GitHub)

Positioning: Agent‑agnostic framework

Agent Support: 8+ agents

Core Feature: Three‑file system + constitution

Typical Use‑case: General projects

OpenSpec (Fission‑AI)

Positioning: Lightweight iterative tool

Agent Support: 25+ tools

Core Feature: Fast iteration

Typical Use‑case: Small rapid iterations

Kiro (AWS)

Positioning: SDD‑native IDE

Agent Support: Built‑in agent

Core Feature: Full IDE integration

Typical Use‑case: AWS ecosystem projects

QoderWork (Alibaba)

Positioning: Qoder Quest execution engine

Agent Support: Qoder ecosystem

Core Feature: Spec + Quest parallel execution

Typical Use‑case: Alibaba ecosystem projects

Empirical Results

API change cycle reduced by 75 % when specs were complete (arXiv finance case).

Manual refinement of specs cut LLM‑generated code errors by 50 % .

Stripe delivered 1,300 AI‑generated PRs with no systemic failures, demonstrating that spec constraints make large‑scale AI coding controllable.

Veracode 2025 report: 45 % of AI‑generated code contained security vulnerabilities when no spec constraints were applied.

GitClear observed a 4× increase in code duplication over four years in AI‑generated code, highlighting the need for disciplined specs.

SDD vs. Vibe Coding

Core Assumption

Vibe Coding: AI understands intent automatically.

SDD: AI needs explicit specifications.

Startup Speed

Vibe Coding: Very fast.

SDD: Slower because spec writing precedes implementation.

Maintainability

Vibe Coding: Poor (no documentation).

SDD: Good (spec serves as documentation).

Collaboration

Vibe Coding: Low (only the author knows the “vibe”).

SDD: High (spec is a shared language).

Security

Vibe Coding: 45 % vulnerable code.

SDD: Better because specs can enforce security constraints.

Scale

Vibe Coding: Small projects.

SDD: Medium‑large projects (spec compresses large codebases).

Ceiling

Vibe Coding: Three‑month “wall”.

SDD: Depends on spec quality.

Five Common Pitfalls

Over‑Specification : Specs become longer than code, turning the AI into a “typewriter”. Mitigation – test spec validity across technology stacks.

Spec Rot : Specs lag behind code. Mitigation – update specs immediately after each change (the incremental spec workflow from Day 3‑4).

Spec Bureaucracy : Minor UI tweaks require the full spec‑plan‑task cycle. Mitigation – distinguish major changes (require spec) from trivial edits.

False Confidence : Detailed specs lead to lax code review. Mitigation – treat spec as requirements, not a substitute for security and code review.

Tool Overhead : Complex toolchains consume more time than spec writing. Mitigation – start with a single spec.md and an existing AI agent.

Future Spectrum of SDD

L1 – Spec‑First (Mainstream)

Specs are written before code; drift is inevitable without automation.

Typical practice: Spec Kit in most teams.

L2 – Spec‑Anchored (Advanced)

Specs and code are continuously synced; tests enforce consistency.

Typical practice: Kiro’s built‑in workflow.

L3 – Spec‑as‑Source (Visionary)

Humans edit only specs; AI fully generates and maintains code.

Currently no mature implementation.

Conclusion

The breakthrough was not the AI‑generated code on Days 1‑6 but the disciplined spec work on Day 0. By turning human thinking—requirements, boundaries, success criteria, constraints—into a concrete, version‑controlled document, the team could safely harness AI’s speed while keeping the project controllable. Starting tomorrow, write a spec.md before any new feature; three to five iterations are enough to make the spec effective, and you only need a Markdown file and an AI assistant to begin.