SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场windsurf-reliability-patterns

windsurf-reliability-patterns

编程与开发

查看项目

更新于 10-16 09:10

技能介绍

概述

本技能介绍安全使用 Windsurf Cascade 的可靠性模式：Git 检查点、增量任务范围划分、验证门禁与回滚策略。Cascade 的多文件编辑能力强大，但需要纪律约束以免破坏代码库。

前置条件

  • 已启用 Cascade 的 Windsurf
  • 已初始化 Git 仓库
  • 有可用的测试套件
  • 了解 Cascade 的 Write 模式

使用步骤

第 1 步：在 Cascade 之前始终提交

最重要的可靠性模式：在每个 Cascade 会话前创建干净的 Git 检查点。

# 在开始 Cascade 任务前
git add -A && git commit -m "checkpoint: before cascade session"

# Cascade 完成后：
git diff                                    # 审查所有更改
npm test && npm run typecheck               # 验证

# 如果结果良好：
git add -A && git commit -m "[cascade] add notification service"

# 如果结果不好：
git checkout -- .                           # 撤销全部更改
# 或选择性撤销：
git checkout -- src/problem-file.ts         # 撤销单个文件

第 2 步：为 Cascade 工作使用功能分支

# 为每个 Cascade 任务创建专用分支
git checkout -b cascade/add-notification-service

# 在该分支上执行 Cascade 工作
# ...

# 如果结果良好：
git checkout main && git merge cascade/add-notification-service

# 如果结果不好：
git checkout main && git branch -D cascade/add-notification-service
# 干净的起点，main 分支未被触碰

第 3 步：增量地划分任务范围

大型任务会导致 Cascade 做出难以审查的大范围更改。应拆分为多个步骤。

反面示例（过于宽泛）： 「重构认证系统，用 JWT 替代 session」 → Cascade 可能修改 30+ 个文件，难以审查，很可能有 bug

正面示例（增量）：

  • 步骤 1：「创建 src/services/jwt.ts，包含函数：generateToken、validateToken、refreshToken。使用 jose 库。」
  • 步骤 2：「创建 tests/services/jwt.test.ts，为这三个函数编写测试」
  • 步骤 3：「运行测试并修复所有失败」
  • 步骤 4：「更新 src/middleware/auth.ts，用 jwt.ts 替代 express-session。保留旧代码为注释。」
  • 步骤 5：「运行完整测试套件并修复所有失败」
  • 步骤 6：「删除 auth.ts 中注释掉的 session 代码」

每个步骤：审查 diff → 测试 → 提交 → 下一步

第 4 步：每次 Cascade 编辑后验证

#!/bin/bash
# scripts/cascade-validate.sh — 每次 Cascade 编辑后运行
set -euo pipefail

echo "=== Post-Cascade Validation ==="

# 类型检查
echo "1/4 TypeScript..."
npm run typecheck || { echo "FAIL: Type errors. Ask Cascade to fix."; exit 1; }

# Lint
echo "2/4 Lint..."
npm run lint || { echo "FAIL: Lint errors. Ask Cascade to fix."; exit 1; }

# 测试
echo "3/4 Tests..."
npm test || { echo "FAIL: Test failures. Ask Cascade to fix."; exit 1; }

# 构建
echo "4/4 Build..."
npm run build || { echo "FAIL: Build errors. Ask Cascade to fix."; exit 1; }

echo "ALL PASSED. Safe to commit."

第 5 步：使用 Cascade 检查点

Cascade 支持会话内的命名检查点：

  1. 启动 Cascade 任务
  2. 每个重要步骤后，Cascade 会显示一个回滚按钮
  3. 悬停到任意之前的步骤 → 点击回滚箭头 → 回滚到该点
  4. 警告：回滚不可逆（无法撤销一次回滚）
  5. 对于复杂任务，在 Cascade 步骤之间提交到 Git，作为更安全的保障

第 6 步：Cascade 约束模式

在提示词中添加约束，防止 Cascade 范围过宽：

范围约束：

  • 「只修改 src/services/ 中的文件」
  • 「不要更改任何现有测试」
  • 「除 src/services/auth.ts 外不要修改任何文件」
  • 「不要安装新依赖」

质量约束：

  • 「遵循其他服务中使用的 Result<T,E> 模式」
  • 「匹配 @src/services/payment.ts 的编码风格」
  • 「为所有边界情况添加错误处理」
  • 「为所有公共函数添加 JSDoc 注释」

安全约束：

  • 「不要修改数据库 schema」
  • 「不要更改任何 API 响应格式」
  • 「不要移除任何现有功能」
  • 「保持与现有调用方的向后兼容」

第 7 步：团队安全策略

  1. Cascade 前 Git 检查点 — 不可妥协
  2. 每个 Cascade 会话一个任务 — 不要混合重构与功能开发
  3. 审查每个文件 diff — 未阅读前绝不「全部接受」
  4. 接受后运行测试 — 提交前运行 npm test
  5. 标记 AI 提交 — 使用 [cascade] 前缀以便追溯
  6. 仅使用功能分支 — 绝不在 main/develop 上使用 Cascade
  7. 新任务重新开始 — 关闭旧的 Cascade 会话
  8. 缩小范围 — 具体文件优于模糊描述

错误处理

问题 原因 解决方案
Cascade 破坏了构建 未测试即接受 Git 回滚，添加 Cascade 后验证
修改了错误的文件 指令模糊 在提示词中指定精确文件路径
回滚中丢失了好的更改 回滚范围太大 使用功能分支，增量提交
Cascade 与之前的编辑矛盾 会话过长 为新任务开始新会话
测试通过但逻辑错误 AI 特有的 bug 模式 手动审查所有 Cascade 更改

示例

安全的 Cascade 工作流（完整）

set -euo pipefail
# 1. 分支
git checkout -b cascade/feature-name

# 2. 检查点
git add -A && git commit -m "checkpoint: pre-cascade" --allow-empty

# 3. Cascade 任务（在 Windsurf 中）
# ... Cascade 编辑文件 ...

# 4. 验证
npm run typecheck && npm test && npm run lint

# 5. 提交
git add -A && git commit -m "[cascade] implement feature-name"

# 6. 合并（审查后）
git checkout main && git merge cascade/feature-name
git branch -d cascade/feature-name

从糟糕的 Cascade 编辑中恢复

# 选项 1：撤销自检查点以来的所有更改
git checkout -- .

# 选项 2：撤销特定文件
git checkout -- src/broken-file.ts

# 选项 3：重置到上次提交
git reset --hard HEAD

# 选项 4：从糟糕的分支中拣选好的提交
git log cascade/feature-name --oneline  # 查找好的提交
git cherry-pick <good-commit-hash>

资源

  • Windsurf Cascade
  • Git Workflows

后续步骤

关于策略护栏，参见 windsurf-policy-guardrails。