1. 项目概述从“蓝图驱动”到“事件驱动”的AI编程范式革新如果你和我一样每天都在和Claude、Cursor这类强大的编码模型打交道那你一定经历过这样的困境一方面你惊叹于模型能快速生成代码、重构函数、甚至提出你没想到的架构思路另一方面你又常常感到失控——模型跑偏了方向怎么办它写的代码真的可靠吗一个复杂的任务让它自由发挥最后出来的东西和你的预期南辕北辙时间全浪费在来回纠错上。传统的“说明书驱动开发”试图解决这个问题它要求你先写一份详尽到堪比产品需求文档的规格说明书然后让模型像执行脚本一样去编码。这就像在AI这匹千里马身上套上了沉重的马车你得到了确定性和可控性却彻底扼杀了它的探索能力和创造性。我们需要的不是把AI变回一个听话的“代码填充工具”而是为它这匹“野马”打造一套轻量而可靠的“缰绳与鞍具”。这就是huisezhiyin/sdd-riper项目特别是其核心sdd-riper-one-light所要解决的问题。这个项目不是一个功能库也不是一个插件它是一套“驾驭工程”的心法与工作流。它的核心主张非常明确承认并接受大模型已经成为一个能够主动推进事件的“行动者”然后为这种能动性构建一个人类可控的“控制平面”。简单说就是让AI去冲锋、去探索、甚至去试错而人类则牢牢掌握着方向、边界、节奏和最终的验收权。它通过“最小化规格书”、“检查点批准”、“证据验收”和“反向同步”这几个关键机制将原本非确定性的、黑盒的模型协作变得可观察、可恢复、可交接。无论你是一个独立开发者还是一个技术团队的负责人只要你希望将大模型编程从“玩具”升级为稳定、可靠的“生产级”协作伙伴这套方法论都值得你深入研究和实践。它不绑定任何特定模型或IDE是一种普适的协作哲学和操作框架。2. 核心理念解析从“挖渠引水”到“沿河耕作”的思维转变要理解SDD-RIPER尤其是其Light版本的精髓我们必须先完成一次根本性的思维范式转换。这不仅仅是工具使用的变化更是对软件开发中“人机角色”的重新定义。2.1 传统范式精确的运河工程师在AI能力爆发之前软件开发更像是一门精确的运河工程。人类工程师是总设计师和总指挥。我们先在图纸上规格书、设计文档规划好水流的每一条路径、每一个闸口、每一处灌溉区域然后指挥工人或早期的代码生成工具严格按照蓝图去挖掘河道。水功能的流向是完全被预设和控制的。这种模式的优点是确定性高流程清晰适合需求稳定、逻辑明确的项目。但其核心是“人定义路径工具执行路径”AI在这里顶多是个更高效的“挖掘机”。2.2 重型SDD撰写超级蓝图的建筑师当大模型出现后第一种自然的想法是让它来执行更复杂的蓝图。于是有了重型的“说明书驱动开发”。人类需要撰写一份极其详尽、无歧义的规格说明书试图覆盖所有边界情况、数据结构、API设计和错误处理。然后将这份“超级蓝图”交给模型期望它像编译一样输出完全符合预期的代码。这种方法的问题在于撰写成本极高写一份能让模型不出错的详细规格书所花费的时间和精力有时甚至超过直接编码。扼杀探索性模型强大的代码理解、模式识别和创造性解决问题的能力被框死了。它不敢也不能偏离蓝图半步即使它“感觉”有更好的路径。无法应对模糊性现实开发中大量需求在初期是模糊的、探索性的。要求先有完美蓝图等于堵死了快速原型和迭代验证的路。这就像你有一匹能日行千里的汗血宝马却非要让它按照你一步一步画好的脚印来走路。2.3 SDD-RIPER Light与水流共舞的农夫SDD-RIPER Light倡导的是另一种哲学“沿河耕作”。我们不再预先挖掘所有河道。相反我们释放水流让模型去探索和尝试观察它自然流淌的轨迹找到它自己形成的“河床”即问题的最佳解决路径。然后人类作为“农夫”在河床两侧设置堤坝定义边界、修建水闸控制检查点、验证水质证据验收并最终在河流滋养的土地上耕作获得可交付的成果。在这个范式下模型角色是主动的“事件行动者”。它负责分解任务、尝试方案、编写代码、运行测试、从失败中恢复并推动工作向前进展。它拥有局部判断和探索的自由。人类角色是“控制平面”的操作员。我们负责定义最终目标、设定安全边界、控制任务节奏、评估潜在风险并在关键节点检查点给予“批准”或“否决”。我们拥有最终的方向权和验收权。两者的关系更像是骑手与赛马。骑手不控制马匹每块肌肉如何运动他选择赛道、控制节奏、在弯道给予指示、判断冲刺时机。马匹提供核心的动力与奔跑的智慧。sdd-riper-one-light就是这套轻量而坚固的“鞍具”和“沟通指令”它确保了在高速奔跑中骑手依然掌控全局。核心提示这种转变最难的不是技术而是心态。你需要克服“必须完全掌控每一行代码”的惯性焦虑转而信任模型在设定好的护栏内的探索能力。这需要练习但一旦适应开发效率和解耦程度将大幅提升。3. sdd-riper-one-light 实战详解轻量缰绳的五大核心约束sdd-riper-one-light作为日常的AI智能体驾驭工具其强大之处在于“约束的极简与关键”。它只规定了少数几条硬性规则但每一条都直指人机协作的核心痛点。下面我们逐条拆解并附上具体的操作示例和背后的逻辑。3.1 约束一复述优先 —— 对齐认知的起跑线规则在开始任何计划或修改代码之前必须首先复述你对任务的理解。操作示例 假设我给模型的指令是“给用户模型添加一个‘最后活跃时间’字段并在用户每次调用API时更新它。”模型不应该直接回答“好的我来修改User模型和AuthMiddleware”。它应该首先输出类似这样的复述**我的理解** 1. **核心变更**在数据库的users表中添加一个last_active_atTIMESTAMP字段。 2. **触发逻辑**在用户成功通过身份验证后、执行任何业务逻辑前更新这个字段为当前时间。 3. **涉及范围**可能需要修改User模型/实体、数据库迁移脚本、以及认证中间件或拦截器。 4. **潜在影响**需要考虑并发更新、性能开销每次API调用都写库、以及该字段在查询中的索引问题。为什么这么做这是消除歧义、对齐认知的第一步。很多协作失败源于“我以为你懂了”。强制复述能立即暴露理解偏差。比如模型可能理解为“只在登录时更新”而你的本意是“每次请求都更新”。在复述阶段发现这个问题成本为零。这相当于在起跑前双方最后确认一遍地图和目的地。3.2 约束二循环锚点 —— 聚焦当前核心目标规则每一个协作循环都必须有一个明确的、单一的“当前核心目标”。操作示例 承接上面的任务模型在复述后应该明确声明**本次循环的核心目标**完成User模型/实体的变更与数据库迁移脚本的生成并确保其可被安全执行。在这个循环里它不应该去碰中间件的代码。完成这个目标后下一个循环的核心目标可以是“修改认证中间件集成活跃时间更新逻辑”。为什么这么做大模型在处理复杂任务时容易“发散”或者试图一步到位这增加了出错和回滚的复杂度。将大任务分解为连续的、原子性的“核心目标”循环使得每个步骤都可控、可验证、可回滚。人类在每个循环结束时进行检查和批准确保了进程始终在正确的轨道上。3.3 约束三无规格不编码 —— 建立最小真相源规则在实施任何代码更改之前必须创建或更新一个“最小规格书”。操作示例 这个“规格书”不是长篇大论而是一个集中的、结构化的信息记录。它可以是一个项目根目录下的SPEC.md文件或者一个专门的决策记录目录。对于“添加最后活跃时间”任务模型在第一个循环应该生成或更新如下规格## 任务添加用户最后活跃时间 - **目标**追踪用户最近一次发起API请求的时间。 - **字段设计** - 名称last_active_at - 类型TIMESTAMP / DateTime (支持时区) - 默认值NULL - 索引考虑添加索引以支持按活跃度查询后续评估。 - **更新策略**在用户认证通过后立即更新AuthMiddleware/Interceptor。 - **完成证据** 1. User模型/实体已包含该字段。 2. 数据库迁移脚本已生成且可回滚。 3. 下一循环中间件代码已更新并包含更新该字段的逻辑。为什么这么做这个“最小规格书”是人类和模型共享的、唯一的“真相源”。它记录了目标、决策、边界和验证方法。当模型在后续循环中“失忆”或新人接手时这份文档提供了完整的上下文。它取代了散落在对话历史中的碎片化信息是项目知识的核心沉淀。“反向同步”机制也要求将验证后的结果如测试通过写回这里使其始终保持最新。3.4 约束四无批准不执行 —— 关键检查点控制规则在实施代码变更前必须给出一个检查点并等待人类的明确批准。操作示例 模型在完成了规格书草拟和计划后不应该直接去执行ALTER TABLE命令或修改模型文件。它应该输出**计划执行的操作** 1. 创建数据库迁移文件YYYYMMDDHHMMSS_add_last_active_at_to_users.rb (或对应ORM的迁移)。 2. 修改app/models/user.rb添加last_active_at字段声明及必要的属性设置。 3. 可选运行迁移的dry-run命令预览SQL。 **请求批准**以上变更将直接影响数据库结构和核心模型。请确认规格书无误并批准执行。为什么这么做这是人类“控制平面”发挥作用的核心时刻。检查点迫使模型暂停给人类一个介入的机会去评估计划的风险、检查是否有遗漏、或者调整优先级。你可以批准、可以要求修改、也可以直接否决。这确保了所有对系统状态的改变都是经过人类深思熟虑后授权的极大降低了“模型跑飞”带来的破坏性风险。3.5 约束五证据验收 —— 从“声称完成”到“证明完成”规则任务的完成必须由测试结果、日志输出、手动检查或外部反馈等客观证据来证明而不是模型说一句“完成了”。操作示例 模型在执行完迁移和修改后不能只说“已完成”。它必须提供**完成证据** 1. **迁移执行输出**[粘贴rails db:migrate或类似命令的成功输出日志]。 2. **模型验证**运行了User.new.valid?返回true检查了User实例是否响应last_active_at方法。 3. **数据库验证**在数据库客户端中执行DESCRIBE users;确认字段已添加。 4. **回滚测试**执行了rails db:rollback STEP1并确认字段被移除然后再次rails db:migrate恢复验证可逆性。为什么这么做这是将协作从“主观信任”转向“客观验证”的关键。在传统人机对话中我们常常需要反复追问“真的好了吗测试跑过了吗”。证据验收机制将“完成”的定义标准化、客观化。它要求模型提供可验证的工件这不仅能建立信任更重要的是这些证据会被“反向同步”回规格书成为项目历史的一部分为后续维护和审计提供依据。4. 完整工作流实战以“实现用户活跃度查询API”为例让我们通过一个更复杂的例子串联起sdd-riper-one-light的完整工作流。假设我们的任务是“我们需要一个API端点返回最近7天最活跃的TOP 100用户用于运营分析。”4.1 第一循环任务拆解与规格锚定人类指令使用 sdd-riper-one-light 处理此任务。 暂不修改代码。 首先给我 - 你对任务的理解 - 本次循环的核心目标 - 一份最小规格书/摘要 - 完成契约何谓完成如何证明 - 后续行动步骤 - 潜在风险 - 验证方法 等待我的批准后再执行。模型输出节选**我的理解** 任务是为运营后台提供一个查询接口返回最近7天内最活跃的TOP 100用户。活跃度定义为last_active_at字段的更新频率。这需要 1. 确定“活跃度”的计算逻辑是简单按最后活跃时间排序还是计算7天内的活跃次数。 2. 设计API端点路径、方法、参数、响应格式。 3. 实现数据查询逻辑可能涉及复杂的数据库查询与分页。 4. 考虑性能因为查询users全表可能很慢。 **本次循环核心目标**与您对齐需求细节并创建初始的、包含关键决策的规格书。 **最小规格书草案** markdown ## 任务用户活跃度查询API - **目标**提供运营分析用的用户活跃度数据。 - **关键决策待定** - 活跃度定义A) 按last_active_at倒序B) 按7天内activity_logs表记录数。 - API设计路径(/api/admin/active_users)查询参数时间范围、分页。 - 性能是否需要为last_active_at或activity_logs.user_id添加索引是否需要缓存 - **完成证据**规格书经评审确认并包含明确的决策。完成契约本循环完成的标准是您审阅并批准这份规格书草案特别是对“关键决策待定”部分做出明确指示。后续行动根据批准的规格书进入下一循环进行数据库索引评估与API控制器骨架搭建。潜在风险若活跃度定义不清可能导致返工。若未考虑性能API可能超时。验证方法您对规格书草案的书面批准。**人类操作**我审阅后回复“批准。选择活跃度定义A按最后活跃时间倒序。API路径为GET /api/internal/analytics/active-users支持limit参数默认100响应JSON格式包含id, name, last_active_at。优先评估性能必要时添加索引。” ### 4.2 第二循环数据库优化与API骨架 模型将我的决策反向同步更新到规格书中然后开启新循环。 **核心目标**评估查询性能风险创建数据库索引如需并生成API控制器骨架代码。 **模型输出计划**“1. 分析users表数据量和last_active_at索引情况。2. 若无索引生成添加索引的迁移文件。3. 创建ActiveUsersController骨架包含路由配置。请求批准。” **人类批准后**模型执行并提交证据 1. 数据库分析报告如EXPLAIN 查询计划显示全表扫描。 2. 生成的索引迁移文件内容。 3. 生成的控制器骨架代码和路由配置。 4. 运行rails routes确认路由已添加。 ### 4.3 第三循环业务逻辑实现与测试 **核心目标**在控制器中实现查询逻辑并编写单元测试。 模型会基于规格书实现类似以下的代码并提供证据 ruby # app/controllers/api/internal/analytics/active_users_controller.rb def index limit params.fetch(:limit, 100).to_i users User.where(‘last_active_at ?‘, 7.days.ago) .order(last_active_at: :desc) .limit(limit) .select(:id, :name, :last_active_at) render json: users end证据包括1. 完整的控制器代码。2. 对应的RSpec单元测试文件测试了正常查询、limit参数、无数据情况。3. 所有测试通过的绿色输出。4.4 第四循环集成与验收核心目标进行集成测试或手动验收确保API按预期工作。模型可能会提供一个简单的cURL命令或Postman集合让我手动测试。或者如果项目有集成测试框架它会运行并提交通过的集成测试日志作为证据。在整个流程中规格书被持续更新最终包含了所有决策、实现细节和测试证据的链接。每个循环都通过“批准”门控每个阶段都有“证据”验收。即使中途我离开另一个开发者或未来的我也能通过这份规格书和检查点历史迅速理解上下文并接手。5. 高级技巧与避坑指南从“会用”到“精通”在实际使用sdd-riper-one-light超过几个月后我积累了一些超越基础工作流的技巧和常见问题的解决方案。这些经验能帮助你更平滑地驾驭AI协作。5.1 如何定义“恰到好处”的检查点检查点设置得太密你会不胜其扰拖慢进度设置得太松则失去控制意义。我的经验法则是状态改变点任何会改变系统持久化状态的操作之前必须设检查点。这包括运行数据库迁移、安装/删除依赖、修改环境配置、执行部署脚本。架构决策点当模型需要做出影响较大的架构选择时例如引入新的第三方服务、定义核心数据模型的关系、选择关键算法。模糊需求澄清点当任务描述存在模糊性模型提出几种可能方案时要求它暂停并列出选项由你决策。循环边界自然地将一个“核心目标”的完成作为一个检查点。在进入下一个目标前批准上一次的成果。个人心得我习惯在给模型任务时就预先声明“在修改任何现有文件、运行迁移或安装新gem前必须请求批准”。这提前设定了预期。5.2 “反向同步”到底怎么做规格书应该写多细反向同步是保证规格书价值的生命线。它不是简单地把代码复制过去而是记录决策和结果。记录决策当你在检查点批准了某个方案例如选择使用Sidekiq而不是Active Job模型应该将这一决策及简要理由更新到规格书的“决策记录”部分。链接证据规格书中“完成证据”部分应该包含指向具体工件的链接或引用。例如“[查询逻辑实现见 commit abc123]”、“[性能测试报告见test/performance/active_users_api_test.rb]”。保持精简规格书不是API文档。它应该聚焦于“为什么”和“是什么”而不是“怎么做”。代码细节留在代码里。一个判断标准是一个新人开发者阅读这份规格书后能否理解系统的设计意图和约束而不是复制出每一行代码。5.3 当模型“跑偏”或陷入死循环时怎么办即使有检查点模型有时也会在某个子问题上钻牛角尖或者提出的方案越来越复杂。这时你需要主动干预叫停并重置上下文直接告诉模型“停止当前循环。我们似乎偏离了核心目标。让我们回顾一下规格书中的核心目标[粘贴目标]。你当前尝试解决的[X]问题对于实现这个目标是必需的吗优先级如何”提供更具体的约束如果模型在技术选型上犹豫不决直接给出约束。“我们不引入新的消息队列请基于现有的Redis设计解决方案。”手动分解任务如果任务本身太复杂模型难以分解你可以亲自做一次分解然后交给模型分步执行。“我们将任务分解为三步1. ... 2. ... 3. ... 现在请执行第一步核心目标是...”利用“证据”要求进行测试当模型声称完成了某项功能但你不确定时不要直接问“好了吗”而是要求具体的证据。“请运行针对边界条件X的单元测试并将结果输出作为证据。”5.4 如何与团队协作推广这套工作流sdd-riper-one-light的个人收益明显但在团队中推广能产生网络效应。从共享规格书开始在团队项目中建立一个/docs/specs/目录每个重要特性或模块都有一个对应的规格书文件。鼓励大家在开始开发前先用这个框架和模型一起撰写规格草案。标准化提交信息在Git提交信息中引用相关的规格书章节或决策记录。例如“feat: add active-users API (#spec-12)”。代码审查关注“为什么”在审查AI生成的代码时审查者不仅要看代码本身还要对照规格书看实现是否满足了约定的目标和约束。这使审查焦点从“代码风格”更多转向“设计一致性”。将“检查点批准”融入团队流程对于高风险变更可以要求开发者在合并请求描述中明确列出本次变更经过的“AI-人类协作检查点”和对应的批准证据如对话片段、测试结果。6. 标准版与轻量版的选择策略何时使用 sdd-riper-one项目中也提供了更重量级的sdd-riper-one标准协议。它并非过时而是在特定场景下更有价值。理解它们的区别能让你做出正确选择。特性维度sdd-riper-one-light(轻量版)sdd-riper-one(标准版)核心哲学驾驭与协作。承认模型是事件行动者人类控制平面。训练与规范。提供明确的、阶段化的流程来引导模型。流程强度轻约束仅几个关键检查点。高度灵活。强约束明确的“研究-计划-执行-评审”阶段门控。规格书最小真相源动态更新聚焦决策和证据。详细的事前规格更接近传统设计文档。适用场景日常编码、探索性任务、Bug修复、原型开发。你和模型已建立一定默契。团队规范建立期、高风险复杂重构、跨项目协调、需要严格审计追溯的任务。人类介入频率较低仅在关键决策点和风险点。较高每个阶段都需要人类评审和批准。产出物可工作的代码 轻量级、活的规格书。可工作的代码 详尽的设计与审计文档。我的实践建议个人或敏捷团队将sdd-riper-one-light作为默认选项。它解放了生产力适应快速变化的需求。复杂任务启动时如果任务非常庞大或模糊可以先用标准版的“研究”和“计划”阶段来梳理思路生成一个扎实的规格基础然后再切换到轻量版进行迭代开发。团队引入新人时让新成员先用标准版工作一段时间。严格的流程能帮助他们建立与AI协作的纪律性理解每个环节的重要性。熟练后再过渡到轻量版。高合规性要求项目金融、医疗等领域对变更追溯有严格要求标准版提供的完整阶段记录和审计线索更具价值。本质上sdd-riper-one为你和你的团队提供了一个“训练轮”和“安全网”。当你对协作充满信心且任务在舒适区内时轻量版的效率优势无与伦比。当你面对未知水域或需要绝对可靠时标准版的严格流程能给你带来安全感。最理想的状态是你能在两者间无缝切换根据任务情境选择最合适的“鞍具”。