ShipGuard

自信交付，次次可靠。

ShipGuard 是一种以“关卡”（gate）为驱动的 AI 辅助软件开发工作流。它解决了 AI 辅助开发中的核心问题：输入一句话，输出大量未经文档说明的变更，导致隐性破坏无处不在。

按需加载 references/ 目录下的文档。首次关联项目时，运行入门问卷以生成 PROJECT.md。

何时启用

• 对共享或生产代码库发起任何代码变更请求时
• 当用户明确表达“构建 / 修复 / 重构 / 添加 / 修改 / 优化”等意图时
• 当变更可能影响数据库 Schema、模型、共享服务、鉴权模块，或涉及超过 3 个文件时
• 当项目中已存在 .dev-workflow/PROJECT.md 文件时（自动加载）

核心原则

无确认计划，不写代码。
无验证交付，不合并代码。
无回归验证，不关闭任务。
绝不出现意外。

共设六道关卡。每道关卡均需用户显式确认（✅）后方可进入下一阶段。跳过任一关卡须用户主动覆盖（override）。唯一例外：低风险变更（见《执行策略》）。

请求 → [G0 需求接入+测试用例] → [G1 影响分析] → [G2 构建] → [G3 功能 QA] → [G4 回归测试] → [G5 经验沉淀] → 关闭

项目入门（首次使用）

ShipGuard 首次关联项目时，在处理任何请求前，请先完成以下问卷：

【ShipGuard 项目初始化】

我需要了解这个项目，让我问你几个问题：

① 项目名称和一句话描述？
② 技术栈？（前端框架 / 后端语言 / 数据库 / 部署方式）
③ 当前阶段？开发中 / 生产运行中 / 维护期
④ 核心业务主流程是什么？（用户视角，列出 3-5 个关键步骤）
⑤ 哪些模块绝对不能出问题？（出问题直接影响生产或客户）
⑥ 已知的「永远不做」有哪些？（过去踩过的坑）
⑦ 谁是需要确认的负责人？
⑧ 有没有特殊部署限制？（如：DB 迁移必须备份、重启必须在低峰期）

用户作答后，AI 自动扫描项目结构，并生成 PROJECT.md：

# PROJECT.md — ShipGuard 项目档案

Project: 
Stack: 
Stage: 

## Critical Paths (变更始终需确认)
1. 
2. 
...

## Protected Modules
- : 

## Hard Rules (永远不做)
- 

## Owner


## Deployment Constraints
- 

Generated: YYYY-MM-DD
Last updated: YYYY-MM-DD

用户确认 PROJECT.md 后，方可启动任何后续工作。该文件是所有后续会话的唯一可信来源（source of truth）。

项目目录结构

ShipGuard 在项目根目录下维护一个 .dev-workflow/ 目录：

.dev-workflow/
  PROJECT.md              # 项目档案（入门时生成）
  CHANGELOG.md            # 自动维护的变更日志
  requirements/           # 每个 NR 对应一个文件
    NR-YYYYMMDD-NN.md
  changes/                # 每个 CR 对应一个文件（含影响分析、变更清单与结果）
    CR-YYYYMMDD-NN.md
  test-cases/
    all-test-cases.md     # 累积式测试用例注册表（自动更新）
  regression/
    CR-YYYYMMDD-NN-regression.md
  lessons/
    hard-rules.md         # 永久性规则，永不失效
    lessons.md            # 历史经验条目，按日期归档

每次新会话启动时：自动加载 PROJECT.md + lessons/hard-rules.md + lessons/lessons.md。这些文件构成 AI 跨会话的持久化记忆。

任务类型与执行策略

在执行前，须对每个请求进行分类。类型决定允许的操作范围及是否需要用户确认。

关键路径规则：任何触及 PROJECT.md > Critical Paths 中所列路径的变更，无论表面规模大小，均自动升级为“需用户确认”。AI 不得自行将关键路径变更降级为“低风险”。

拆分规则：当一个请求横跨两类任务（例如：修复缺陷 + 新增字段），必须拆分为两个独立的 CR。严禁在一个 CR 中混合任务类型。

范围蔓延规则：若实施过程中实际范围超出 G1 评估结果，须立即中止并发出《范围变更通知》。严禁静默扩大范围。

关卡 0 — 需求接入 + 测试用例定义

立即输出一张需求理解卡。此时不得编写任何代码。

【需求理解卡 #NR-YYYYMMDD-NN】
原始需求：
任务类型：🎨 UI微调 / 🐛 Bug Fix / ✨ Feature / 📋 Product / 🏗️ Architecture / 📄 Docs
执行策略：直接执行 / 需要确认

理解：<具体的行为描述，非复述原文>
范围：<涉及哪些模块 / 页面 / API>
排除：<明确不变更的内容>
假设：<存在的歧义及其解决方式>
已知风险：<来自 hard-rules.md 和 lessons.md 中与此请求相关的内容>

Test Cases：
  TC-01【正常流程】 → 
  TC-02【正常流程】 → 
  TC-03【边界条件】 → 
  TC-04【异常流程】 → 

✅ 确认（含 Test Cases）后开始 / ❌ 有误，请纠正

测试用例（TC）规则：

• 正常流程 (Happy path)：核心功能按预期运行
• 边界条件 (Edge case)：空数据、极值、异常状态
• 异常流程 (Error path)：失败时系统行为
• 每个 TC 必须包含具体、可验证的预期结果——禁用“应正常工作”等模糊表述
• TC 由用户与 AI 共同定义：AI 提出建议，用户确认；AI 不得单方面决定

将确认后的 NR 写入 .dev-workflow/requirements/NR-YYYYMMDD-NN.md。

关卡 1 — 变更影响分析

NR 确认后，输出一张变更影响分析卡。此时仍不得编写任何代码。

【变更影响分析 #CR-YYYYMMDD-NN】
关联需求：#NR-YYYYMMDD-NN

改动文件：
  - path/to/file（风险：低/中/高，原因：）

影响范围：
  直接：<直接受影响的功能>
  间接：<潜在受影响的模块>
  无影响：<明确排除的模块>

改动量：小(<20行) / 中(20-100行) / 大(>100行)
风险等级：🟢低 / 🟡中 / 🔴高
DB变更：无 / 有（迁移脚本：）
需要重启：无 / api / worker / all
预计耗时：

风险说明：<🔴高风险时必填>
回滚方案：<出错时如何回退>
关联回归模块：

✅ 开始开发 / ❌ 重新评估

风险等级定义：

• 🟢 低：单文件、纯 UI、不涉及共享逻辑
• 🟡 中：多文件、API 变更、逻辑修改
• 🔴 高：DB 迁移、模型变更、共享服务、鉴权、关键路径、涉及 >5 个文件

将确认后的 CR 骨架写入 .dev-workflow/changes/CR-YYYYMMDD-NN.md。

关卡 2 — 实施

严格在任务类型所限定的范围内执行。规则如下：

• 仅可修改 G1 中列出的文件。新增文件 = 立即中止并发出《范围变更通知》
• 原子化变更：每次提交一个逻辑单元，而非一个文件
• 若发现未预期的复杂性，须立即中止并上报，待确认后再继续

完成后，在 CR 文件末尾追加变更清单：

【变更清单 #CR-YYYYMMDD-NN】
状态：已完成 ✅

文件变更：
  path/to/file
    + 
    ~ 
    - 

配套操作：
  迁移：