rails_ai_agents SDD实战:手把手用规格驱动开发构建你的第一个Rails功能
rails_ai_agents SDD实战:手把手用规格驱动开发构建你的第一个Rails功能
rails_ai_agents 是一个面向 Ruby on Rails 的 AI 开发工具集,内置 11 个 SDD(Spec Driven Development,规格驱动开发)斜杠命令。它能帮你先写规格、再定方案、后写代码,让 Claude Code 按照规范的流程构建你的第一个 Rails 功能,从需求描述一路推进到可验证的实现。
什么是 SDD 规格驱动开发?
传统的 AI 辅助开发往往是"直接告诉 AI 做什么,然后看代码",容易出现理解偏差和返工。SDD 的思路正好相反:
先想清楚,再动手,最后验证(think first, build second, verify at the end)
整个流程像一条流水线,每个环节都会生成一份 Markdown 文档(规格、计划、任务清单……),你只需审阅和确认,AI 负责推进。核心命令包括:
/sdd:specify:从一句自然语言生成完整功能规格/sdd:clarify:用最多 5 个针对性问题消除规格中的歧义/sdd:plan:生成技术实现计划、数据模型和路由契约/sdd:tasks:把计划拆解成按依赖排序的可执行任务/sdd:implement:按任务清单逐条实现,自动跑测试/sdd:validate:实现完成后验证代码是否兑现了规格承诺
所有产物统一存放在 specs/<分支名>/ 目录下,详见 README.md 中的 SDD Kit 章节。
快速上手:三步装好 SDD 工具链
- 安装并配置 Claude Code CLI
- 克隆仓库,把配置复制到你的 Rails 项目:
git clone https://gitcode.com/gh_mirrors/ra/rails_ai_agents
cp -r rails_ai_agents/.claude/ /path/to/your-rails-app/.claude/
cp -r rails_ai_agents/.specify/ /path/to/your-rails-app/.specify/
- 验证工具链就绪:
ls .specify/ # 应有 memory/ scripts/ templates/
ls .claude/commands/sdd/ # 应有 specify.md plan.md tasks.md implement.md ...
其中 .specify/ 存放模板、脚本和项目"宪法"(constitution),是 SDD 命令的运转基础;命令定义在 .claude/commands/sdd/ 目录下,每个命令都是一个 Markdown 文件。
实战:构建"文章收藏"功能
我们以官方教程 docs/your-first-sdd-feature.md 中的真实案例为例:让用户收藏文章,稍后再读。
第 1 步:Specify —— 描述你要构建什么
在 Claude Code 中执行:
/sdd:specify Users can bookmark articles and view their bookmarked articles list
AI 会创建一个编号特性分支(如 004-bookmark-articles),并写入 specs/004-bookmark-articles/spec.md,包含用户故事、功能需求(FR-001…)和 Given/When/Then 验收场景。
💡 你的角色:审阅规格。觉得哪里不对就直接说,比如"收藏应该是私有的,不是公开的"。
第 2 步:Clarify —— 补齐规格缺口(可选)
/sdd:clarify
AI 会从功能范围、数据模型、安全等 9 个维度扫描规格,一次问一个针对性问题,每个问题都附带推荐答案。回复 A 或 yes 接受推荐即可,最多 5 个问题。
现在花 5 分钟回答 5 个问题,能省下后续 5 轮代码评审的返工。
第 3 步:Plan —— 设计技术方案(可选)
/sdd:plan I am building with Ruby 3.3, Rails 8.1, PostgreSQL, Hotwire
生成 plan.md(含架构决策)、data-model.md(实体与迁移计划)和 contracts/routes.md(路由契约)。数据模型是下游一切的基础,schema 改动越晚修复成本越高,建议重点审阅。
第 4 步:Tasks —— 拆解成有序任务
/sdd:tasks
生成按用户故事优先级(P1 → P2 → P3)分阶段排序的 tasks.md,任务遵循 TDD 流程,例如:
Phase 1: Setup
- [ ] [T001] [P1] Create bookmarks migration with user_id, article_id, timestamps
Phase 3: User Story P1 - Bookmark an Article
- [ ] [T005] [P1] [US-1] Create BookmarksController with create/destroy actions
- [ ] [T007] [P1] [US-1] Write request specs for bookmark create/destroy
第 5 步:Implement —— 开始构建
/sdd:implement
AI 按顺序执行任务:每个任务交给一个携带最小上下文的子智能体完成,每完成一个任务跑 rubocop 和相关 rspec 测试,每完成一个阶段跑全量测试;失败会自动带上下文重试,并把教训记录到 .specify/memory/lessons-learned.md,让项目越做越聪明。
第 6 步:Validate —— 验证规格对齐
/sdd:validate
通过结构扫描、测试映射、AI 语义分析等 4 层混合方式,输出一份 validation-report.md,逐条核对需求是否被代码覆盖,例如"FR-001 已覆盖,证据是 BookmarksController#create"。合并前处理掉未覆盖项即可。
小改动怎么办?用 sdd-change 轻量模式
不是每个改动都需要完整流程。修 bug、小调整用三步走即可(命令定义在 .claude/commands/sdd-change/):
/sdd-change:specify Fix: clicking bookmark on draft articles returns 500 error
/sdd-change:tasks
/sdd-change:implement
没有 clarify、plan、validate 环节,一个简单改动 15 分钟就能走完。选择建议:
| 场景 | 使用 |
|---|---|
| 修 bug、1-3 个文件的小重构 | /sdd-change:specify |
| 新特性、跨模块的多故事 epic | /sdd:specify |
| 6 个文件以上的大重构 | /sdd:specify |
常见问题速答
- 每一步都必须走吗? 不必。最小可行路径是
specify → tasks → implement,其余步骤为复杂特性增加严谨度。 - 可以手改生成的文件吗? 可以。它们都是纯 Markdown,AI 下一步会读取你修改后的版本——这些文档属于你,不属于 AI。
- 不同意 AI 的规格怎么办? 直接说"更新规格:收藏要支持标签",或自己改文件后继续。
- 实现失败或测试不过? AI 会带上下文重试并记录到 lessons-learned.md;解不了会请你介入,你也可以手动修复后重跑
/sdd:implement从断点继续。
结语
SDD 的价值不在"更长的流程",而在于把"想清楚"变成了一组可审阅、可修改、可追溯的文档。配合 rails_ai_agents 中 19 个领域专家 agent(如 README.md 提到的 model-agent、query-agent)和 14 条按路径自动加载的规则,你的 Rails 项目从第一行规格开始就被约束在最佳实践之内。现在,打开终端,写下你的第一条 /sdd:specify 吧。
