spec-to-repo

Spec to Repo

将自然语言描述的项目规格说明转换为完整、可运行的入门代码仓库。它不是模板填充工具，而是一个规格解释器，能为任意技术栈生成真实可用的代码。

适用场景

• 用户提供一段应用的文字描述，并希望得到代码
• 用户有 PRD、需求文档或功能清单，需要一个代码库
• 用户说"帮我做一个……的应用""搭建脚手架""初始化项目"
• 用户需要一个可运行的入门仓库，而不仅仅是文件树

如果用户明确想要带有 Stripe 和身份认证的 SaaS 应用，则不适用本技能，应改用 product-team/saas-scaffolder。

核心工作流

第一阶段：解析与理解

阅读规格说明，在内部提取以下字段：

字段	来源	是否必需
应用名称	明确给出，或从描述中推断	是
描述	规格说明的第一句话	是
功能	描述行为的要点或句子	是
技术栈	明确指定（如"使用 FastAPI"）或从上下文推断	是
身份认证	"登录""用户""账户""角色"	提及时需要
数据库	"存储""保存""持久化""记录""schema"	提及时需要
API 接口	"endpoint""API""REST""GraphQL"	提及时需要
部署目标	"Vercel""Docker""AWS""Railway"	提及时需要

技术栈推断规则（用户未指定时）：

信号	推断的技术栈
"web app""dashboard""SaaS"	Next.js + TypeScript
"API""backend""microservice"	FastAPI（Python）或 Express（Node）
"mobile app"	Flutter 或 React Native
"CLI tool"	Go 或 Python
"data pipeline"	Python
"high performance""systems"	Rust 或 Go

解析完成后，向用户展示结构化的理解结果：

## Spec Interpretation

**App:** [name]
**Stack:** [framework + language]
**Features:**
1. [feature]
2. [feature]

**Database:** [yes/no — engine]
**Auth:** [yes/no — method]
**Deploy:** [target]

Does this match your intent? Any corrections before I generate?

标出存在歧义之处。最多提出 3 个澄清问题。如果用户说"直接做就行"，则采用最佳默认值继续。

第二阶段：架构设计

在编写任何文件之前先设计项目：

1. 选择模板：从 references/stack-templates.md 中匹配一个技术栈模板
2. 定义文件树：列出将要创建的每个文件
3. 将功能映射到文件：每个功能至少对应一个文件或组件
4. 设计数据库 schema：如适用，定义表或集合及其字段和类型
5. 确定依赖：列出每个包及其版本约束
6. 规划 API 路由：如适用，列出每个接口的方法、路径、请求和响应结构

在生成之前，向用户展示文件树：

project-name/
├── README.md
├── .env.example
├── .gitignore
├── .github/workflows/ci.yml
├── package.json / requirements.txt / go.mod
├── src/
│   ├── ...
├── tests/
│   ├── ...
└── ...

第三阶段：生成

编写每个文件。规则如下：

• 真实代码，而非占位桩。 每个函数都要有真实实现。不得使用 // TODO: implement 或 pass 占位符。
• 语法有效。 每个文件都必须能在其语言中无错误地解析。
• 导入与依赖匹配。 每个导入都必须对应清单文件（package.json、requirements.txt、go.mod 等）中的某个包。
• 包含类型。 TypeScript 项目使用类型；Python 项目使用类型提示；Go 项目使用有类型的结构体。
• 环境变量。 生成 .env.example，列出每个必需变量，并用注释说明用途。
• README.md。 包含：项目描述、前置条件、设置步骤（克隆、安装、配置环境变量、运行），以及可用的脚本或命令。
• CI 配置。 生成 .github/workflows/ci.yml，包含：安装、代码检查（若依赖中有 linter）、测试、构建。
• .gitignore。 忽略适合该技术栈的内容（node_modules、pycache、.env、构建产物）。

文件生成顺序：

1. 清单文件（package.json / requirements.txt / go.mod）
2. 配置文件（.env.example、.gitignore、CI）
3. 数据库 schema / 迁移
4. 核心业务逻辑
5. API 路由 / 接口
6. UI 组件（如适用）
7. 测试
8. README.md

Phase 4 — 验证

生成完成后,按以下清单逐项检查:

• 每个导入的包都存在于清单文件中
• 导入引用的每个文件都存在于文件树中
• .env.example 列出了代码中使用的每个环境变量
• .gitignore 覆盖了构建产物和敏感信息
• README 中的安装说明确实可用
• 没有硬编码的密钥、API 密钥或密码
• 至少存在一个测试文件
• 构建/启动命令已记录且可以正常运行

针对生成的目录运行 scripts/validate_project.py,以发现常见问题。

示例

示例 1:任务管理 API

输入需求:

"帮我做一个任务管理 API。用户可以创建、列出、更新和删除任务。任务包含标题、描述、状态(todo/in-progress/done)和截止日期。使用 FastAPI 和 SQLite。通过 API 密钥添加基础认证。"

输出文件树:

task-api/
├── README.md
├── .env.example              # API_KEY, DATABASE_URL
├── .gitignore
├── .github/workflows/ci.yml
├── requirements.txt          # fastapi, uvicorn, sqlalchemy, pytest
├── main.py                   # FastAPI app, CORS, lifespan
├── models.py                 # SQLAlchemy Task model
├── schemas.py                # Pydantic request/response schemas
├── database.py               # SQLite engine + session
├── auth.py                   # API key middleware
├── routers/
│   └── tasks.py              # CRUD endpoints
└── tests/
    └── test_tasks.py         # Smoke tests for each endpoint

示例 2:食谱分享 Web 应用

输入需求:

"我想要一个食谱分享网站。用户注册后可以发布包含食材和步骤的食谱、浏览其他人的食谱,并收藏喜欢的食谱。使用 Next.js 和 Tailwind。数据存储在 PostgreSQL 中。"

输出文件树:

recipe-share/
├── README.md
├── .env.example              # DATABASE_URL, NEXTAUTH_SECRET, NEXTAUTH_URL
├── .gitignore
├── .github/workflows/ci.yml
├── package.json              # next, react, tailwindcss, prisma, next-auth
├── tailwind.config.ts
├── tsconfig.json
├── next.config.ts
├── prisma/
│   └── schema.prisma         # User, Recipe, Ingredient, Favorite models
├── src/
│   ├── app/
│   │   ├── layout.tsx
│   │   ├── page.tsx          # Homepage — recipe feed
│   │   ├── recipes/
│   │   │   ├── page.tsx      # Browse recipes
│   │   │   ├── [id]/page.tsx # Recipe detail
│   │   │   └── new/page.tsx  # Create recipe form
│   │   └── api/
│   │       ├── auth/[...nextauth]/route.ts
│   │       └── recipes/route.ts
│   ├── components/
│   │   ├── RecipeCard.tsx
│   │   ├── RecipeForm.tsx
│   │   └── Navbar.tsx
│   └── lib/
│       ├── prisma.ts
│       └── auth.ts
└── tests/
    └── recipes.test.ts

示例 3:命令行支出记录工具

输入需求:

"用于记录支出的 Python 命令行工具。命令包括:add、list、summary、export-csv。存储在本地 SQLite 文件中。不使用任何外部 API。"

输出文件树:

expense-tracker/
├── README.md
├── .gitignore
├── .github/workflows/ci.yml
├── pyproject.toml
├── src/
│   └── expense_tracker/
│       ├── __init__.py
│       ├── cli.py            # argparse commands
│       ├── database.py       # SQLite operations
│       ├── models.py         # Expense dataclass
│       └── formatters.py     # Table + CSV output
└── tests/
    └── test_cli.py

反模式

反模式	修正方法
占位代码 — // TODO: implement、pass、空函数体	每个函数都要有真实实现。如果比较复杂,就实现一个可运行的简化版本。
技术栈覆盖 — 用户说的是 Flask,却选择了 Next.js	始终遵循用户明确指定的技术偏好。只有在用户未指定时才进行推断。
缺少 .gitignore — 提交了 node_modules 或 .env	将与技术栈相匹配的 .gitignore 作为最先生成的文件之一。
虚假导入 — 导入了清单中不存在的包	完成前,将每个导入与 package.json / requirements.txt 逐一核对。
MVP 过度设计 — 在 v1 中加入 Redis 缓存、限流、WebSocket	只构建最小可用功能。用户可以之后再迭代。
忽略既定偏好 — 用户说 "PostgreSQL",你却生成了 MongoDB	仔细解析需求。明确的偏好不可更改。
缺少环境变量 — 代码读取 process.env.X,但 .env.example 中没有列出	代码中使用的每个环境变量都必须出现在 .env.example 中,并附带注释。
没有测试 — 交付的仓库中零测试文件	至少为每个 API 端点编写一个冒烟测试,或为每个核心函数编写一个测试。
臆造 API — 生成的代码调用了不存在的库方法	坚持使用文档完善、稳定的 API。不确定时,采用最简单的方案。

验证脚本

scripts/validate_project.py

检查生成的项目目录中的常见问题:

# Validate a generated project
python3 scripts/validate_project.py /path/to/generated-project

# JSON output
python3 scripts/validate_project.py /path/to/generated-project --format json

执行的检查项:

• README.md 存在且非空
• .gitignore 存在
• .env.example 存在(前提是代码中引用了环境变量)
• 存在包清单文件(package.json、requirements.txt、go.mod、Cargo.toml、pubspec.yaml)
• 没有提交 .env 文件(避免泄露敏感信息)
• 至少存在一个测试文件
• 生成的代码中没有 TODO/FIXME 占位符

渐进式增强

对于复杂需求,分阶段生成:

1. MVP — 仅包含核心功能,端到端可运行
2. 认证 — 如有需要,添加身份认证
3. 打磨 — 错误处理、校验、加载状态
4. 部署 — Docker、CI、部署配置

MVP 完成后询问用户:"核心功能已可运行。接下来要添加认证/打磨/部署,还是先迭代当前内容?"

交叉引用

• 相关：product-team/saas-scaffolder：SaaS 专用脚手架（Next.js + Stripe + Auth）
• 相关：engineering/spec-driven-workflow：规范优先的开发方法论
• 相关：engineering/database-designer：数据库 Schema 设计模式
• 相关：engineering-team/senior-fullstack：全栈实现模式