引言

随着Claude 4.6等大语言模型在Cursor IDE这类AI原生编辑器中的深度应用，Vibe-Coding已成为新一代开发范式——开发者通过自然语言描述需求、业务意图甚至模糊的产品直觉，即可由AI辅助完成代码设计、编写、重构全流程，极大降低了机械编码的劳动成本，提升了迭代效率。但与此同时，能力越强的模型越容易出现核心痛点：过度主动的擅自修改、无授权的逻辑重构、需求传递中的严重失真、大代码库下的上下文漂移，最终导致现有业务逻辑被破坏、隐性bug激增，甚至给复杂项目带来灾难性后果。

本文将深度解析由Cursor社区沉淀的两大核心AI开发Skill——Riper-5 Mode与SDD规范，并构建一套双轮驱动的Vibe-Coding规范化开发SOP。该SOP在保留Vibe-Coding高效性的同时，从流程与内容两个维度实现了AI辅助开发的全链路可控，彻底解决Claude 4.6等模型的失控问题，让AI辅助开发从“玩具级demo验证”升级为“工业级复杂项目交付”的标准能力。

一、核心概念的出处、定义与设计本质

1.1 Vibe-Coding：AI原生开发的范式革命与固有缺陷

Vibe-Coding是指以自然语言为核心交互载体，以开发者的业务意图、产品直觉为核心输入，由AI大模型完成代码实现的开发模式。其核心优势在于打破了“需求-设计-编码”的传统线性流程，实现了需求与实现的快速对齐，极大缩短了开发周期。

但其固有缺陷与模型能力正相关：模型的创造性越强，越容易出现越权操作与需求偏离。尤其是Claude 3.7，其强大的代码理解与生成能力，伴随着显著的“过度 eager”特性——经常在未获得开发者明确授权的情况下，擅自修改现有逻辑、新增未约定的功能、重构代码结构，最终导致“AI写得越快，bug修复越慢”的困境。

1.2 Riper-5 Mode：给AI套上缰绳的流程可控协议

出处

Riper-5 Mode由Cursor官方论坛用户原创并开源，核心设计目标是彻底解决Claude 3.7在Cursor IDE中的失控问题。作者基于日均12小时的高强度AI辅助开发经验，经过多轮试错优化，最终形成了这套严格的阶段化操作协议，已被大量Cursor开发者验证可显著提升AI执行的准确率与可控性。

核心定义

RIPER-5是5个权限严格隔离、流程完全互斥的开发阶段的缩写：Research（调研）、Innovate（构思）、Plan（规划）、Execute（执行）、Review（校验）。其核心设计本质是：将软件开发的完整生命周期拆分为原子化的阶段，每个阶段明确划定AI的允许操作、禁止行为与核心目标，通过强制的模式声明与人工绝对控制权，彻底杜绝AI的越权操作与自主决策。

1.3 SDD Skill：锚定AI输出的内容可控规范

出处

SDD（Software Design Document）Skill是Cursor社区沉淀的、经过大量项目验证的标准化文档驱动开发规范，核心是将AI辅助开发的全流程信息，拆分为固定结构、固定职责的Markdown文件，为AI的所有操作提供明确的文档锚点，从根源上解决上下文漂移、需求失真、输出无据可依的问题。

核心定义

SDD Skill严格遵循固定的文件结构与职责边界，核心文件体系如下：

• 01_requirements.md：存储用户故事与业务需求，作为全流程的唯一需求源
• 02_interface.md：定义技术栈、数据结构与接口规范，完成需求到技术的映射
• 03_implementation.md：编写详细的实现逻辑与执行清单，作为AI编码的唯一依据
• 04_test.md：设计全量测试用例，作为最终交付的校验标准
• AI_CHANGELOG.md：记录AI的所有变更操作，实现全链路可追溯

其核心设计本质是：通过分层级的文档体系，构建“需求-设计-实现-测试-追溯”的全链路锚定，让AI的每一次输出都有明确的依据，彻底杜绝无中生有、偏离需求的问题。

二、核心原理深度解析

2.1 Riper-5 Mode的底层设计逻辑

Riper-5的核心价值，是通过权限隔离、人工确权、闭环校验三大核心机制，把开发的决策权完全交还给开发者，AI仅作为严格的执行者，从根源上解决模型的失控问题。

1. 阶段互斥与权限隔离机制

Riper-5将开发全流程拆分为5个完全互斥的阶段，每个阶段都明确划定了允许操作与禁止行为，形成了严格的权限边界：

• 调研阶段仅允许信息收集，禁止任何方案构思
• 构思阶段仅允许方案 brainstorming，禁止具体的计划与实现
• 规划阶段仅允许详细的执行方案设计，禁止任何代码编写
• 执行阶段仅允许严格按照计划落地，禁止任何创造性修改
• 校验阶段仅允许计划与实现的对比校验，禁止任何代码调整

这种设计彻底杜绝了“写代码时擅自改需求、做设计时擅自写实现”的越权行为，让AI在正确的阶段做正确的事。

2. 强制模式声明与人工绝对确权机制

协议明确了两条不可协商的元规则：

• AI的每一次回复，必须以[MODE: 模式名称]开头，从交互层面强制锚定当前阶段，避免上下文漂移导致的模式越权
• 模式切换必须由开发者发出精确的指令，AI没有任何自主切换的权限

这两条规则将开发流程的控制权完全锁定在开发者手中，AI无法自主推进流程，彻底解决了模型“自作主张”的核心痛点。

3. 计划-执行-校验的闭环机制

Riper-5构建了严格的闭环校验体系：规划阶段输出的原子化checklist，是执行阶段的唯一依据；校验阶段必须逐行对比实现与计划的一致性，哪怕是微小的偏差也必须明确标记。

这种闭环设计确保了AI的实现100%匹配预先确认的方案，彻底杜绝了实现偏离设计、需求在传递中失真的问题。

2.2 SDD Skill的底层设计逻辑

SDD Skill的核心价值，是通过分层锚定、标准化接口、全链路追溯三大机制，为AI的所有操作提供明确的内容依据，解决大上下文下的信息丢失与需求失真问题。

1. 分层级的需求传递与锚定机制

SDD的5个文件形成了自顶向下的需求传递链路，每一层都有明确的输入与输出，且必须严格对齐上一层的内容：

• 需求层（01_requirements.md）是全流程的唯一真值源，所有设计、实现、测试都必须严格对齐用户故事与验收标准
• 设计层（02_interface.md）完成业务需求到技术架构的映射，必须完全覆盖需求层的所有要求
• 实现层（03_implementation.md）将技术设计转化为可执行的步骤，必须严格匹配设计层的接口与数据结构
• 测试层（04_test.md）基于需求层的验收标准设计测试用例，作为最终交付的校验依据

这种分层锚定机制，确保了需求从提出到落地的全链路无失真，避免了AI在大上下文下的信息丢失与理解偏差。

2. 标准化的Skill接口机制

SDD规范固定了文件名、文件结构与职责边界，形成了标准化的AI Skill接口。无论是项目级复用、团队级协作，还是跨项目的规则迁移，AI都可以快速识别每个文件的职责与操作规范，无需重复的指令对齐，极大提升了AI辅助开发的稳定性与可复用性。

3. 全链路的变更追溯机制

AI_CHANGELOG.md强制要求AI的每一次变更都必须记录对应的模式、文档锚点、执行清单项与详细修改内容，实现了AI生成代码的全链路可追溯。一旦出现问题，开发者可以快速定位变更的根因，无需在海量的AI生成内容中手动排查。

2.3 双轮驱动的核心价值：流程+内容的双重可控

Riper-5与SDD Skill的结合，形成了Vibe-Coding范式下的完美互补：

• Riper-5解决了流程可控的问题，给AI的操作划定了严格的阶段边界，确保AI在正确的时间做正确的事
• SDD Skill解决了内容可控的问题，给AI的操作提供了明确的文档锚点，确保AI的所有输出都有明确的依据

两者结合，构建了“流程+内容”的双重可控体系，既保留了Vibe-Coding自然语言驱动的高效性，又彻底解决了其不可控、不可追溯、易出错的核心缺陷，让AI辅助开发真正适配工业级的复杂项目交付。

三、规范化开发SOP全流程详解

本SOP将Riper-5的5个阶段与SDD的文档体系深度融合，形成了端到端的AI辅助开发标准流程，每个阶段都明确了输入、输出、操作规范、禁止行为与退出条件。

阶段1：RESEARCH模式 - 需求对齐与现状调研

模式声明

[MODE: RESEARCH]

核心目标

纯信息收集与现状理解，100%对齐业务需求，掌握现有代码库的结构与逻辑，不做任何创造性操作。

对应SDD操作

完成01_requirements.md的全量编写，明确用户故事、验收标准、需求边界、非功能需求与约束条件。

操作规范

• 仅允许读取项目文件、梳理代码结构、询问需求澄清问题、记录现有业务逻辑与技术约束
• 仅输出事实性的观察结果与澄清问题，不做任何方案建议、构思或预判

禁止行为

• 禁止任何形式的解决方案建议、技术选型讨论、实现思路构思
• 禁止任何代码编写、重构建议、功能设计相关的内容

退出条件

开发者显式发出ENTER INNOVATE MODE指令，且01_requirements.md已完成并获得开发者确认。

阶段2：INNOVATE模式 - 技术方案构思与选型

模式声明

[MODE: INNOVATE]

核心目标

基于已确认的需求，完成技术方案的 brainstorming 与可行性评估，不做具体的实现设计。

对应SDD操作

完成02_interface.md的框架设计，明确技术栈选型、模块划分、核心数据结构、接口定义与依赖关系。

操作规范

• 仅允许讨论可选的技术方案、架构设计思路，分析各方案的优劣、风险与可行性
• 所有方案均以可能性的形式呈现，不做最终决策，仅向开发者提供选型参考

禁止行为

• 禁止编写具体的实现计划、详细的技术规格、执行步骤清单
• 禁止任何代码编写，包括示例代码、伪代码与代码片段

退出条件

开发者显式发出ENTER PLAN MODE指令，且技术方案已确认，02_interface.md的核心内容已对齐。

阶段3：PLAN模式 - 详细设计与执行清单输出

模式声明

[MODE: PLAN]

核心目标

输出可100%落地的详细技术规格，形成原子化的执行checklist，确保执行阶段无需任何创造性决策。

对应SDD操作

完成03_implementation.md的详细实现逻辑编写、04_test.md的全量测试用例设计，最终输出标准化的IMPLEMENTATION CHECKLIST。

操作规范

• 仅允许编写详细的实现计划，包括精确的文件路径、函数名、修改内容、逻辑流程与测试用例
• 最终必须输出编号的、原子化的执行checklist，每个清单项对应一个不可拆分的操作

禁止行为

• 禁止任何形式的代码实现，哪怕是示例代码、伪代码
• 禁止任何未在需求与设计中明确的创造性决策

退出条件

开发者显式批准全量计划，并发出ENTER EXECUTE MODE指令，执行checklist已获得最终确认。

阶段4：EXECUTE模式 - 严格按计划实现

模式声明

[MODE: EXECUTE]

核心目标

100%严格执行PLAN阶段输出的checklist，不做任何偏离、优化或创造性添加。

对应SDD操作

按照checklist完成代码编写，同步更新AI_CHANGELOG.md，记录每一项变更的详细内容、对应清单项与文档锚点。

操作规范

• 仅允许实现checklist中明确列出的内容，严格遵循计划中的文件路径、函数定义与逻辑要求
• 执行过程中遇到任何需要偏离计划的问题，立即终止执行，返回PLAN模式

禁止行为

• 禁止任何未在计划中明确的修改、优化、重构或功能新增
• 禁止任何自主决策解决问题的行为，所有偏差必须先回到计划阶段对齐

退出条件

checklist所有项执行完成，开发者显式发出ENTER REVIEW MODE指令。

阶段5：REVIEW模式 - 全链路校验与闭环

模式声明

[MODE: REVIEW]

核心目标

逐行校验实现与计划的一致性，标记任何偏差，完成全链路的文档闭环与交付确认。

对应SDD操作

校验代码实现与03_implementation.md、checklist的一致性，校验测试用例与04_test.md的匹配度，更新所有SDD文档与AI_CHANGELOG.md，输出最终的校验结论。

操作规范

• 必须逐行对比计划与实现，明确标记任何偏差，无论大小
• 必须输出明确的校验结论，明确实现与计划是否完全匹配

禁止行为

• 禁止任何代码修改、重构或新增实现
• 禁止任何对计划的重新解读或需求调整

退出条件

校验完成，所有偏差已修复，文档闭环完成，开发者确认最终交付。

四、核心Skill文件源码与使用说明

以下两份Skill文件可直接在Cursor IDE中使用，支持项目级规则配置、单聊天线程激活两种方式。

4.1 Riper-5 Mode Skill 源码

目录结构

riper-5-mode/
└── SKILL.md

skill 内容

---
name: riper-5-mode
description: 严格的5阶段（Research/Innovate/Plan/Execute/Review）AI辅助开发操作协议，解决大模型在 IDE 中的越权修改、逻辑破坏、擅自决策问题，实现开发流程全链路可控。适用于 IDE 中基于 Claude 的代码开发、需求落地、复杂项目迭代场景。
metadata:
  author: Cursor Community
  version: "1.0.0"
  created: 2026-03-08
allowed-tools: Read Write FileSystem Bash(git:*)
---

# Riper-5 Mode: Strict AI Development Operational Protocol
## Core Definition
RIPER-5 is a permission-isolated, sequential development framework consisting of 5 mutually exclusive modes: Research, Innovate, Plan, Execute, Review. This protocol locks development decision-making authority to the developer, eliminating unauthorized modifications, logic breakage, and over-eager behavior of LLMs in AI-assisted coding workflows.

## Non-Negotiable Meta Rules
1. You MUST begin EVERY response with your current mode in brackets, with no exceptions. Format: `[MODE: MODE_NAME]`
2. You CANNOT transition between modes without the developer's EXPLICIT verbal signal
3. You have NO authority to make independent decisions outside the scope of the currently declared mode
4. Any violation of this protocol requires you to immediately revert to the last valid mode and state, and notify the developer

## Mode Transition Signals
Only switch modes when the developer sends the EXACT command:
- `ENTER RESEARCH MODE`
- `ENTER INNOVATE MODE`
- `ENTER PLAN MODE`
- `ENTER EXECUTE MODE`
- `ENTER REVIEW MODE`
Without these exact signals, you MUST remain in your current mode.

## Mode-Specific Specifications
### [MODE: RESEARCH]
#### Purpose
Pure information gathering and existing state understanding ONLY
#### Permitted Actions
- Reading and parsing project files, directory structures, and existing codebase logic
- Asking clarifying questions about requirements, business logic, or existing implementation
- Documenting factual observations of the current codebase state, dependencies, and constraints
#### Forbidden Actions
- Any form of solution suggestions, implementation ideas, or planning
- Any code writing, refactoring recommendations, or feature design
- Any creative or speculative statements about potential changes
#### Exit Condition
Remain in this mode until the developer explicitly signals to move to the next mode

---

### [MODE: INNOVATE]
#### Purpose
Brainstorming potential technical approaches and solution possibilities ONLY
#### Permitted Actions
- Discussing potential solution ideas, architectural options, and technical approaches
- Analyzing advantages, disadvantages, risks, and feasibility of each proposed idea
- Seeking developer feedback on proposed possibilities
#### Forbidden Actions
- Concrete implementation planning, detailed technical specifications, or step-by-step execution plans
- Any code writing, including example code or pseudo-code
- Presenting ideas as final decisions or mandatory requirements
#### Exit Condition
Remain in this mode until the developer explicitly signals to move to the next mode

---

### [MODE: PLAN]
#### Purpose
Creating exhaustive, 100% actionable technical specifications and implementation checklists ONLY
#### Permitted Actions
- Writing detailed technical specifications with exact file paths, function names, module boundaries, and modification details
- Defining sequential, atomic implementation steps with no ambiguous requirements
- Designing test case frameworks and acceptance criteria aligned with requirements
#### Forbidden Actions
- Any form of code implementation, including example code, pseudo-code, or code snippets
- Any creative decision-making not explicitly documented in the plan
#### Mandatory Final Step
Convert the full approved plan into a numbered, sequential `IMPLEMENTATION CHECKLIST`, with each atomic action as a separate, executable line item:

IMPLEMENTATION CHECKLIST:
1.[Specific atomic action with exact file and modification details]
2.[Specific atomic action with exact file and modification details]
...
n. [Final atomic action to complete implementation]

#### Core Requirement
The plan must be comprehensive enough that NO creative decisions are required during the execution phase
#### Exit Condition
Remain in this mode until the developer explicitly approves the full plan and signals to move to the next mode

---

### [MODE: EXECUTE]
#### Purpose
Implementing EXACTLY what was defined in the approved Mode 3 plan ONLY
#### Permitted Actions
- Only implementing the exact steps defined in the developer-approved `IMPLEMENTATION CHECKLIST`
- Updating the AI changelog with each completed action, aligned with the checklist
#### Forbidden Actions
- Any deviation, improvement, optimization, or creative addition not explicitly listed in the approved plan
- Any modification to files or logic not covered in the checklist
- Any independent decision-making to resolve issues without returning to Plan mode
#### Entry Requirement
Only enter this mode after receiving the EXPLICIT `ENTER EXECUTE MODE` command from the developer
#### Deviation Handling
If ANY issue requiring a deviation from the approved plan is found, you MUST immediately halt execution, notify the developer, and return to PLAN mode
#### Exit Condition
Remain in this mode until all checklist items are completed, and the developer explicitly signals to move to the next mode

---

### [MODE: REVIEW]
#### Purpose
Ruthlessly validating the implementation against the approved plan ONLY
#### Permitted Actions
- Line-by-line comparison between the final implementation and the approved Mode 3 plan/checklist
- Explicitly flagging any deviation from the plan, no matter how minor
- Verifying that all requirements and acceptance criteria are met
#### Forbidden Actions
- Any code modifications, refactoring, or new implementation
- Any re-interpretation of the plan or requirements
#### Deviation Reporting Format
`DEVIATION DETECTED: [exact description of the deviation, including file path, line number, and difference between plan and implementation]`
#### Mandatory Conclusion
You MUST output one of the following explicit verdicts:
- `IMPLEMENTATION MATCHES PLAN EXACTLY`
- `IMPLEMENTATION DEVIATES FROM PLAN`
#### Exit Condition
Remain in this mode until all deviations are resolved, and the developer confirms the final verdict

## Edge Case Handling
1. If context loss causes rule forgetting, re-load this skill file and re-declare the current valid mode
2. If the developer sends ambiguous mode transition commands, ask for clarification instead of making assumptions
3. If the plan has logical conflicts, return to PLAN mode instead of making independent adjustments during execution
4. For simple single-file tasks, the developer may explicitly skip non-essential modes, but you must still declare the current mode for every response

## Validation
Validate this skill with the official skills-ref tool:

4.2 SDD Skill 源码

目录结构

sdd-development-standard/
└── SKILL.md

skill 内容

---
name: sdd-development-standard
description: 标准化的软件设计文档（SDD）分层开发规范，定义固定职责的文档体系，实现AI辅助开发的需求全链路锚定、上下文稳定、变更可追溯。适用于 IDE中复杂项目的需求管理、架构设计、代码实现与测试全流程管控。
metadata:
  author: Cursor Community
  version: "1.0.0"
  created: 2026-03-08
allowed-tools: Read Write FileSystem
---

# SDD (Software Design Document) Development Standard
## Core Definition
This specification defines a modular, document-driven AI-assisted development framework with a fixed layered file structure and clear responsibility boundaries. All AI operations MUST be anchored to the corresponding document, ensuring full traceability, requirement alignment, and context stability in complex coding projects.

## Fixed File Structure & Responsibility Boundaries
All files MUST be stored in the root directory of the project, with exact filenames and fixed usage rules as defined below. Document modification must follow the top-down order, no reverse modification is allowed without explicit developer approval.

---

### 01_requirements.md - User Requirements & User Stories
#### Core Purpose
The single source of truth for all business requirements, user needs, and acceptance criteria. All subsequent design, implementation, and testing MUST be strictly aligned with the content of this file.
#### Mandatory Content Structure
1. **Feature Overview**: High-level description of the feature/module, business objectives, and scope boundaries
2. **User Stories**: Standardized format: `As a [user role], I want [feature], so that [business value]`
3. **Acceptance Criteria**: Clear, testable pass/fail conditions for each user story
4. **Non-Functional Requirements**: Performance, security, compatibility, and other non-business requirements
5. **Constraints & Limitations**: Technical constraints, dependency limits, and out-of-scope content
#### Operation Rules
- This file may only be modified with explicit developer approval
- All requirements must be traceable to a user story in this file
- Any deviation from the requirements in this file must be explicitly flagged to the developer

---

### 02_interface.md - Tech Stack & Data Structures
#### Core Purpose
Define the technical architecture, module boundaries, data models, and interface specifications, bridging business requirements and technical implementation.
#### Mandatory Content Structure
1. **Tech Stack Selection**: Exact programming language, framework, library versions, and dependency list
2. **Module Architecture**: High-level module division, dependency graph, and responsibility boundaries for each module
3. **Core Data Structures**: Exact definition of all data models, including field names, types, constraints, and relationships
4. **Interface Specifications**: Exact API definitions, including request/response formats, endpoint paths, HTTP methods, and error codes
5. **Dependency Management**: Third-party dependencies, internal module dependencies, and version constraints
#### Operation Rules
- This file may only be modified after the corresponding content in `01_requirements.md` is approved
- All data structures and interfaces must be aligned with the user stories in `01_requirements.md`
- No implementation details or executable code may be included in this file

---

### 03_implementation.md - Detailed Implementation Logic
#### Core Purpose
Define the exact, step-by-step implementation logic for all features, serving as the only valid input for code execution.
#### Mandatory Content Structure
1. **Implementation Overview**: High-level implementation flow and module execution order
2. **File-by-File Implementation Details**: Exact file paths, function names, parameter definitions, and core logic for each file to be modified/created
3. **Error Handling Strategy**: Exact error handling logic, exception types, and fallback mechanisms
4. **Performance Optimization Details**: Specific optimization measures aligned with non-functional requirements
5. **Final Implementation Checklist**: Atomic, sequential execution steps for code implementation
#### Operation Rules
- This file may only be modified after the corresponding content in `02_interface.md` is approved
- All implementation details must be strictly aligned with the data structures and interfaces in `02_interface.md`
- No executable code may be included in this file, only logical descriptions and implementation specifications
- The final checklist must be comprehensive enough that no creative decisions are required during code execution

---

### 04_test.md - Test Cases
#### Core Purpose
Define all test cases to validate the implementation meets the requirements, serving as the standard for final delivery review.
#### Mandatory Content Structure
1. **Test Scope**: Test coverage boundaries, including unit tests, integration tests, end-to-end tests, and edge case tests
2. **Test Environment**: Exact environment requirements, dependency versions, and test setup steps
3. **Test Cases**: For each user story, detailed test cases with: Test ID, Corresponding User Story ID, Preconditions, Test Steps, Expected Results, Acceptance Criteria
4. **Edge Case Tests**: Boundary conditions, error scenarios, and abnormal input test cases
5. **Performance Test Benchmarks**: Exact performance metrics and pass/fail thresholds
#### Operation Rules
- This file may only be modified after the corresponding content in `01_requirements.md` and `03_implementation.md` is approved
- All test cases must be strictly aligned with the acceptance criteria in `01_requirements.md`
- No implementation code may be included in this file, only test specifications

---

### AI_CHANGELOG.md - AI Operation Changelog
#### Core Purpose
Full traceability of all AI-generated modifications, ensuring every change has a clear origin, purpose, and corresponding document anchor.
#### Mandatory Entry Format
Each change entry MUST follow this exact format:

[Timestamp] - [Change Type: Feature Implementation / Bug Fix / Refactor / Documentation Update]
+ Corresponding SDD Document Anchor: [File Name + Section ID]
+ Corresponding Implementation Checklist Item: [Checklist Number]
+ Detailed Change Description: Exact files modified, line numbers changed, and core content of the modification
+ Developer Approval Status: [Approved / Pending]

#### Operation Rules
- This file MUST be updated immediately after completing any code modification or document update
- Every entry must have a clear anchor to the corresponding SDD document
- No changes may be made to the codebase without a corresponding entry in this file
- All entries must be approved by the developer before being merged into the main branch

## Global Operation Rules
1. All AI operations MUST be anchored to the corresponding SDD document. No unanchored operations are allowed
2. Document modification must follow the top-down order: `01_requirements.md` → `02_interface.md` → `03_implementation.md` → `04_test.md`
3. All code implementation must be strictly based on the content of `03_implementation.md`
4. All review operations must be based on the content of `04_test.md` and the approved implementation plan
5. Keep individual reference files focused, avoid deeply nested reference chains, use relative paths from the project root when referencing files

## Progressive Disclosure Guidelines
- Metadata (name and description) is loaded at startup for skill matching
- Full `SKILL.md` content is loaded when the skill is activated
- Detailed reference material should be moved to the `references/` directory, loaded only when required
- Keep the main `SKILL.md` under 500 lines for optimal context efficiency

## Validation
Validate this skill with the official skills-ref tool:

4.3 使用方式

1. 项目级规则配置（推荐）：将两份文件放入项目的.cursor/rules/目录下，Cursor会自动加载为项目级规则，所有项目内的聊天线程都会自动激活该规范。
2. 单线程激活：将文件保存为Markdown文件，拖拽到Cursor的聊天窗口中，即可为当前聊天线程激活对应的规则，不影响其他线程。
3. 用户级规则配置：将内容粘贴到Cursor设置的Rules面板中，作为全局用户规则，所有Cursor窗口都会默认激活该规范。

五、优势对比与最佳实践

5.1 核心优势对比

对比维度	传统Vibe-Coding	传统AI辅助开发	Riper-5 + SDD 规范化SOP
可控性	极低，AI可自主决策、越权操作	中等，依赖单次指令约束	极高，流程与内容双重锁定，无授权不可操作
需求对齐度	低，易出现需求失真与偏离	中等，依赖上下文窗口大小	极高，全链路文档锚定，需求无失真传递
代码bug率	高，擅自修改易引入隐性bug	中等，需人工逐行校验	极低，计划-执行-校验闭环，100%匹配设计
上下文稳定性	差，大代码库下易出现上下文漂移	中等，需频繁补充上下文	优秀，模块化文档锚定，无上下文溢出问题
可追溯性	无，AI变更无记录，问题无法定位	弱，仅能通过聊天记录追溯	全链路可追溯，每一次变更都有明确记录与锚点
大型项目适配性	极差，仅适用于单文件demo开发	中等，适用于中小型项目	优秀，模块化设计适配大型复杂项目与团队协作
迭代效率	极高，但bug修复成本极高	中等，需频繁人工纠偏	高，前期需求对齐成本低，无后期bug修复成本

5.2 最佳实践

1. 模块化拆分适配大代码库：针对大型项目，必须按照“分离关注点”原则拆分为独立的原子模块，每个模块对应独立的SDD文档，确保单个模块的内容完全适配模型的上下文窗口，避免上下文溢出导致的规则失效。
2. 严格的模式切换规范：必须使用协议规定的精确指令进行模式切换，禁止使用模糊的自然语言指令，避免模型误判导致的模式越权；哪怕是简单的需求，也需遵循模式流程，培养模型的规则遵循习惯。
3. 文档先行的开发原则：所有AI代码操作必须先有对应的SDD文档锚点，禁止无文档的直接编码；文档修改必须遵循自顶向下的顺序，禁止反向修改导致的需求与实现脱节。
4. 异常处理的标准化流程：执行阶段遇到任何需要偏离计划的问题，必须立即终止执行，返回PLAN模式更新计划与checklist，重新获得开发者批准后，再进入EXECUTE模式，禁止AI自主解决问题。
5. 团队级的规范统一：将Riper-5与SDD Skill作为团队的AI辅助开发标准规范，统一所有开发者的AI交互流程，降低团队协作的沟通成本，提升代码质量的一致性。

六、常见问题与解决方案

问题1：AI擅自切换模式，不遵循模式声明规则

解决方案：将Riper-5规则放在项目级规则的最顶部，提升规则的优先级；将大型项目拆分为小模块，避免上下文溢出导致的规则丢失；如果出现规则失效，重新拖拽riper-5.md文件到聊天窗口，重新激活协议规则。

问题2：Plan模式下AI擅自编写代码，不遵循禁止规则

解决方案：在Plan模式的输入指令中，重复强调“仅输出计划与checklist，禁止任何代码实现，包括示例代码”；在SDD的03_implementation.md规则中，明确禁止任何可执行代码的写入，仅允许逻辑描述。

问题3：RESEARCH与INNOVATE模式的边界模糊，无法明确切换时机

解决方案：两个模式的核心边界是“是否进行创造性操作”。RESEARCH模式是纯信息收集，仅搞清楚“现在是什么样”，不做任何方案构思；INNOVATE模式是纯方案 brainstorming，基于已理解的现状，构思“未来可以怎么样”。简单来说，当你完全搞懂了现有状态与需求，就可以切换到INNOVATE模式。

问题4：大型代码库中，AI频繁违反规则，无法稳定执行

解决方案：按照Riper-5原作者的设计理念，重构代码为高度模块化的树状结构，每个模块拆分为最小的原子单元，遵循严格的分离关注点原则，确保单个模块的内容可以完全放在模型的上下文窗口中；每次仅针对单个模块进行操作，避免一次性加载整个代码库。

问题5：上下文漂移，AI忘记已确认的SDD文档内容

解决方案：每次模式切换时，在指令中明确引用对应的SDD文档锚点；将核心的需求与设计内容，放在聊天线程的靠前位置，避免上下文滚动导致的信息丢失；大型项目拆分为多个独立的聊天线程，每个线程仅处理单个模块的开发。

结语

AI辅助开发的范式正在快速迭代，大语言模型的能力越强，越需要一套完善的规范与协议来约束其行为，让其能力真正服务于开发者的需求，而不是带来额外的成本。Riper-5 Mode与SDD Skill的结合，本质上是给强大的AI模型套上了精准的“缰绳”，让AI从一个不可控的“野生助手”，升级为一个严格遵循指令、高效可靠的工业级开发工具。

这套SOP不仅解决了模型的失控问题，更构建了一套AI原生开发的标准化流程，无论是个人开发者的快速迭代，还是团队级的复杂项目交付，都能在保留Vibe-Coding高效性的同时，实现全流程的可控、可追溯、可复用。未来，随着AI模型能力的持续提升，这种规范化的开发流程，必将成为AI原生开发的行业标准。