| name | sop-workflow |
| description | Execute development tasks following the SOP 5-Step workflow (Requirement → Architecture → Implementation → Verification → Delivery). Use this skill for all development tasks to ensure quality and traceability. This skill enforces stage gates, deliverables, and Definition of Done (DoD). Always use this skill when the user asks you to implement a feature, fix a bug, or refactor code, especially when they mention SOP or stage gates. |
SOP 五步法工作流
标准化开发流程，确保每个任务都经过完整的需求分析、架构设计、实现编码、审查验证和测试交付。
流程概览
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ SOP-01 │ → │ SOP-02 │ → │ SOP-03 │ → │ SOP-04 │ → │ SOP-05 │
│ 需求理清 │ │ 架构设计 │ │ 实现编码 │ │ 审查验证 │ │ 测试交付 │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
核心原则：
- 阶段门禁：每个阶段必须通过检查点才能进入下一阶段
- 前置依赖：按依赖顺序执行（数据 → API → 前端 → UI）
- 完成定义：满足 DoD 才能汇报"成功"
- 未对齐不开工：目标、范围、验收标准未明确前，不进入实现阶段
通用执行约束
以下约束在整个 SOP 五步法中始终生效：
- 行动前先思考，写代码前先阅读现有文件和已有实现
- 对外输出保持简洁，但判断过程必须充分、严谨
- 优先局部编辑，不轻易整文件重写
- 不重复阅读已经读过的文件，除非文件已变化或确有验证需要
- 完成前必须做测试、校验或最小可行验证
- 禁止奉承式开场和无信息量收尾
- 方案优先追求简单直接
- 用户当前会话中的明确指令优先级最高
阶段门禁（所有步骤生效）
进入任何阶段前必须确认：
SOP-01: 需求理清
目标：将模糊需求转化为明确的规格说明
检查点
交付物
-
功能清单
## 功能清单: MCP 配置页面
### 核心功能
- [ ] 查看 MCP 配置列表
- [ ] 新增 MCP 配置
- [ ] 编辑 MCP 配置
- [ ] 删除 MCP 配置
### 扩展功能
- [ ] 批量导入配置
- [ ] 配置模板导出
-
流程图（Mermaid）
graph TD
A[开始] --> B{配置存在?}
B -->|是| C[加载配置]
B -->|否| D[创建默认配置]
C --> E[显示配置列表]
D --> E
-
验收准则（Given-When-Then）
## AC-001: 新增 MCP 配置
**Given**: 用户在 MCP 配置页面
**When**: 点击"新增配置"按钮并填写表单
**Then**:
- 配置保存成功
- 列表自动刷新
- 显示成功提示
阶段退出条件
- 所有检查点完成
- 用户确认需求理解正确
- 若仍存在关键歧义，不得进入 SOP-02 / SOP-03
SOP-01 扩展参考：需求分析详细手册
对齐闸门
在需求对齐完成前，不得进入实现。必须先明确以下三项：
- 目标：到底要解决什么问题
- 范围：这次包含什么，不包含什么
- 验收：怎样才算完成
分析流程
理解用户意图 → 提问澄清细节 → 确认对齐目标 → 输出需求文档
标准提问清单
| 方面 | 关键问题 |
|---|
| 目标 | 这个功能主要解决什么问题？用户完成什么任务时需要这个功能？成功的标准是什么？ |
| 范围 | 包含哪些具体操作？有什么明确不包含的吗？是否需要兼容现有数据？ |
| 验收 | 怎样算这个功能完成了？有没有必须满足的条件？异常情况如何处理？ |
| 非功能 | 有多少用户会使用？有没有性能要求？安全方面有什么考虑？ |
需求确认模板
### 目标
{一句话描述要解决的问题}
### 范围
**包含**：
- [ ] 功能点 1
- [ ] 功能点 2
**不包含**（本次不做）：
- 功能点 3（后续迭代）
### 验收标准 (AC)
**基于 Given-When-Then 格式**
### 非功能需求
- 性能：{...}
- 安全：{...}
- 兼容：{...}
需求分级
- P0 - 关键（Must Have）: 阻塞发布的功能、核心业务流程
- P1 - 重要（Should Have）: 显著改善体验、用户明确期望
- P2 - 期望（Nice to Have）: 锦上添花、资源允许时做
- P3 - 低优先级（Later）: 未来考虑、不确定性高
常见陷阱
- 假设已知: 即使看起来简单的需求，也应确认理解是否正确。
- 范围蔓延: 把后续迭代的功能也抢进本次范围。
- 验收标准模糊: 如"页面要好看"，应改为"页面风格与现有设计系统一致"。
- 忽视非功能需求: 任何复杂功能都应问一句并发量和安全考量。
SOP-02: 架构设计
目标：确定技术方案
检查点
交付物
-
接口文档
## POST /api/mcp/configs
**描述**: 创建 MCP 配置
**请求体**:
```json
{
"name": "string",
"type": "stdio|sse",
"command": "string",
"args": ["string"]
}
响应:
{
"id": "uuid",
"name": "string",
"created_at": "datetime"
}
-
模型定义
class MCPConfig(BaseModel):
id: UUID
name: str
type: Literal["stdio", "sse"]
command: str
args: List[str]
created_at: datetime
updated_at: datetime
-
架构决策记录（如需）
## ADR-001: 使用 SQLite 存储 MCP 配置
**状态**: 已接受
**背景**: 需要本地持久化存储 MCP 配置
**决策**: 使用 SQLite 而非 PostgreSQL
**理由**:
- 零配置，开箱即用
- 配置数据量小，无需分布式存储
- 简化部署流程
阶段退出条件
SOP-03: 实现编码
目标：按规范实现代码
检查点
编码规范
后端（Python/FastAPI）:
- 使用
APIRouter，禁止直接用 app
- 响应模型必须显式定义
- 数据库操作必须异步
- 错误必须使用
HTTPException，格式统一
前端（React/TypeScript）:
- React 19 + TypeScript 5.9
- Tailwind CSS 4
- shadcn/ui + Base UI
- 禁止内联样式，统一使用 Tailwind
- 必须使用
cn() 工具函数合并类名
- 竞态防护：所有副作用操作使用请求锁
- 组件卸载时取消未完成请求
交付物
阶段退出条件
- 代码通过 Lint/类型检查
- 核心功能有单元测试
- 代码审查通过（自审）
SOP-04: 审查验证
目标：分级质量验证
分级验证体系
| 级别 | 名称 | 检查内容 | 执行者 |
|---|
| L0 | 自测 | 功能正确性、边界处理 | 开发者 |
| L1 | 静态检查 | Lint、类型检查、格式化 | CI/自动化 |
| L2 | 人工审查 | 代码质量、架构合规 | 代码审查者 |
| L3 | 集成测试 | 端到端、接口契约 | QA/自动化 |
L0 自测检查清单
L1 静态检查清单
ruff check .
mypy .
npm run lint
npm run type-check
L2 人工审查要点
- 架构设计是否被正确实现
- 代码是否简洁可维护
- 是否有明显性能问题
- 安全规范是否遵守
L3 集成测试
- 接口契约一致性
- 状态切换一致性（接口成功、状态回写、UI 展示一致）
阶段退出条件
- L0-L2 验证通过
- 切换类功能一致性通过
- 无阻塞问题
SOP-05: 测试交付
目标：完整交付
检查点
交付检查清单
代码交付：
文档交付：
质量交付：
完成定义（DoD）
仅当以下全部满足，才能汇报"成功"：
快速参考
| 阶段 | 核心产出 | 退出条件 |
|---|
| SOP-01 需求理清 | 功能清单、验收准则 | 需求确认 |
| SOP-02 架构设计 | 接口契约、模型定义 | 方案确认 |
| SOP-03 实现编码 | 源代码、单元测试 | Lint/测试通过 |
| SOP-04 审查验证 | L0-L3 验证通过 | 质量门禁 |
| SOP-05 测试交付 | 完整交付物 | DoD 满足 |
常见场景速查
场景 1：Bug 修复
- 如果 Bug 简单（1-2 行改动）：可快速走完全流程，重点在 L0 验证
- 如果 Bug 复杂：完整执行 SOP-01 到 SOP-05
场景 2：功能增强
- 必须完整执行 SOP-01（需求分析）
- 评估架构影响，可能需要 SOP-02
- 按正常流程执行 SOP-03 到 SOP-05
场景 3：紧急 Hotfix
- 可并行执行：一边修复，一边补文档
- 但必须在 24 小时内补齐所有 SOP 文档
严格执行 SOP，不得跳过——质量来自流程，而非运气。
