name: sop-structure description: 在结构化标准操作程序时使用，包括正确的部分、组织和Markdown格式。覆盖SOP的解剖和部分组织。 allowed-tools:

读取
写入
编辑
Bash
Grep
Glob

SOP 结构

结构良好的SOP遵循一致的模式，使其易于理解、维护和执行。本技能涵盖了有效SOP的解剖和如何组织部分。

关键概念

标准SOP解剖

每个SOP应包括以下核心部分：

标题：清晰、以行动为导向的描述
概述：目的和用例的简要总结
参数：可配置的输入以提高可重用性
先决条件：所需的工具、知识或设置
步骤：执行的顺序说明
成功标准：如何验证完成
错误处理：当出现问题时该怎么做
相关SOPs：相关工作流程的链接

文件命名约定

SOP文件必须使用 .sop.md 扩展名：

✅ deployment-checklist.sop.md
✅ code-review-security.sop.md
✅ database-migration.sop.md

❌ deployment.md (缺少 .sop)
❌ checklist.sop.txt (错误文件类型)
❌ SOP-Deployment.md (格式不正确)

最佳实践

标题部分

# {行动动词} {具体结果}

短格式：使用kebab-case文件名
长格式：使用标题大小写标题

示例：

# 生成API文档

# 使用TDD实现功能

# 审查拉取请求以进行安全检查

概述部分

概述应回答三个问题：

什么：这个SOP实现了什么？
何时：何时应该使用这个SOP？
为什么：为什么使用这种方法？

## 概述

本SOP指导您通过测试驱动开发(TDD)实现新功能。在需要高正确性信心的功能时使用。TDD确保全面的测试覆盖并减少回归风险。

参数部分

在开始时定义所有可配置输入：

## 参数

- **输入变量**：{variable_name} - 描述和示例值
- **配置**：{config_option} - 可用选项 (option1, option2, option3)
- **路径**：{file_path} - 预期格式和约束

示例：

## 参数

- **仓库路径**：{repository_path} - Git仓库的绝对路径
- **输出格式**：{output_format} - 文档格式 (markdown, html, pdf)
- **详细程度**：{verbosity} - 细节级别 (简洁, 标准, 全面)
- **包括测试**：{include_tests} - 是否包括测试示例 (是, 否)

先决条件部分

列出所需的工具、知识和设置：

## 先决条件

### 所需工具
- 工具名称 (版本 X.X 或更高)
- 另一个工具 (版本 Y.Y 或更高)

### 所需知识
- 理解概念 A
- 熟悉技术 B

### 所需设置
- 环境变量 {VAR_NAME} 必须设置
- 配置文件 {config.json} 必须存在

示例：

## 先决条件

### 所需工具
- Node.js (v18 或更高)
- npm (v8 或更高)
- Git (v2.30 或更高)

### 所需知识
- 理解 JavaScript/TypeScript
- 熟悉测试框架
- Git工作流程基础

### 所需设置
- package.json 存在于项目根目录
- 测试框架已安装 (Jest, Vitest, 或 Mocha)
- Git仓库已初始化

步骤部分

结构化步骤层次化：

## 步骤

1. 第一个主要步骤
   - 子步骤或细节
   - 另一个子步骤
   - 附加上下文

2. 第二个主要步骤
   - 实施细节
   - 预期结果

3. 第三个主要步骤
   - 具体操作
   - 验证步骤

带有验证：

## 步骤

1. 分析代码库结构
   - 识别主要入口点
   - 映射目录组织
   - 列出依赖项
   - **验证**：确认所有入口点都有文档记录

2. 提取模式
   - 识别设计模式
   - 记录数据流
   - 记录架构决策
   - **验证**：验证模式正确识别

3. 生成文档
   - 创建概述部分
   - 记录公共API
   - 添加使用示例
   - **验证**：确保文档构建无错误

成功标准部分

定义可衡量的结果：

## 成功标准

- [ ] 具体可衡量的结果1
- [ ] 具体可衡量的结果2
- [ ] 具体可衡量的结果3
- [ ] 所有测试通过
- [ ] 文档完整

示例：

## 成功标准

- [ ] 所有新代码测试覆盖率 ≥ 90%
- [ ] 所有测试通过无警告
- [ ] 代码通过lint检查，零错误
- [ ] 文档包括使用示例
- [ ] 更改遵循现有代码模式

错误处理部分

提供常见故障的指导：

## 错误处理

### 错误：{错误名称或代码}

**症状**：错误如何表现

**原因**：为什么发生此错误

**解决方案**：
1. 第一个故障排除步骤
2. 第二个故障排除步骤
3. 如果步骤失败，替代方法

示例：

## 错误处理

### 错误：测试运行失败

**症状**：测试运行器以错误代码退出，测试未执行

**原因**：缺少依赖项、测试框架配置不正确或环境问题

**解决方案**：
1. 验证测试框架是否安装：`npm list {test-framework}`
2. 检查测试配置文件是否存在且有效
3. 确保 NODE_ENV 设置正确
4. 如果问题持续，重新安装依赖项：`rm -rf node_modules && npm install`

### 错误：构建期间类型错误

**症状**：TypeScript编译器报告类型不匹配

**原因**：不正确的类型注释或缺少类型定义

**解决方案**：
1. 运行类型检查器：`npx -y --package typescript tsc`
2. 查看错误消息以查找具体类型问题
3. 添加必要的类型注释
4. 如果需要，安装缺少的 @types 包

示例

完整SOP结构示例

# 部署应用到生产环境

## 概述

本SOP指导您安全地将应用更改部署到生产环境。在代码审查批准和成功的暂存部署后使用。这确保一致的部署过程并减少生产事件。

## 参数

- **环境**：{environment} - 目标环境 (暂存, 生产)
- **版本**：{version} - 语义版本号 (例如, 1.2.3)
- **回滚计划**：{rollback_plan} - 如果部署失败，策略 (自动, 手动)

## 先决条件

### 所需工具
- kubectl (v1.24 或更高)
- Docker (v20.10 或更高)
- AWS CLI (v2.0 或更高)

### 所需知识
- 理解Kubernetes部署
- 熟悉应用架构
- 访问生产监控仪表板

### 所需设置
- 生产凭证在 ~/.kube/config 中配置
- Docker注册表认证设置
- 监控警报配置

## 步骤

1. 部署前验证
   - 验证 {version} 通过了所有暂存测试
   - 确认数据库迁移准备就绪
   - 检查回滚程序有文档记录
   - **验证**：所有测试通过，迁移已审查

2. 构建和推送容器镜像
   - 构建带标签 {version} 的Docker镜像
   - 在镜像上运行安全扫描
   - 推送到容器注册表
   - **验证**：镜像成功推送，无关键漏洞

3. 应用数据库迁移
   - 备份生产数据库
   - 在备份上测试迁移
   - 将迁移应用到生产
   - **验证**：迁移已应用，数据库可访问

4. 部署应用
   - 使用新镜像更新Kubernetes部署
   - 监控Pod启动和健康检查
   - 验证应用响应正确
   - **验证**：所有Pod健康，健康检查通过

5. 部署后验证
   - 在生产上运行冒烟测试
   - 在监控中检查错误率
   - 验证关键功能工作
   - 监控15分钟
   - **验证**：错误率正常，冒烟测试通过

## 成功标准

- [ ] 应用版本 {version} 已部署
- [ ] 所有健康检查通过
- [ ] 错误率在正常范围内
- [ ] 数据库迁移成功应用
- [ ] 监控显示无异常
- [ ] 关键用户流程测试和工作

## 错误处理

### 错误：Pod启动失败

**症状**：Pod卡在CrashLoopBackOff，未达到就绪状态

**原因**：配置错误、资源限制或依赖不可用

**解决方案**：
1. 检查Pod日志：`kubectl logs -n production <pod-name>`
2. 描述Pod以查看事件：`kubectl describe pod -n production <pod-name>`
3. 验证配置与暂存匹配
4. 如果无法解决，执行回滚计划

### 错误：健康检查失败

**症状**：负载均衡器从轮换中移除Pod，服务降级

**原因**：应用启动问题、数据库连接性或资源耗尽

**解决方案**：
1. 检查应用日志中的错误
2. 验证数据库连接性
3. 检查资源利用率
4. 如果需要，扩展资源
5. 如果在5分钟内无法解决，执行回滚计划

### 错误：部署后高错误率

**症状**：监控显示500错误峰值，延迟增加

**原因**：破坏性更改、不兼容的依赖或配置不匹配

**解决方案**：
1. 立即执行 {rollback_plan}
2. 捕获错误日志进行分析
3. 在暂存环境中测试修复
4. 修复验证后安排新部署

## 相关SOPs

- **回滚程序**：如果部署失败或出现关键问题，执行
- **数据库迁移**：数据库模式更改的详细过程
- **事件响应**：如果部署导致生产事件，遵循
- **暂存部署**：在生产部署前完成

常见模式

代码分析SOP模板

# {分析|审查|审计} {目标} 的 {质量方面}

## 概述
{1-2句话：什么，何时，为什么}

## 参数
- **目标**：{target} - 要分析的内容
- **深度**：{depth} - 分析彻底性
- **输出格式**：{format} - 结果格式

## 先决条件
{所需工具、知识、设置}

## 步骤
1. 识别范围和边界
2. 收集相关信息
3. 执行分析
4. 记录发现
5. 生成推荐

## 成功标准
- [ ] 所有区域分析完成
- [ ] 发现记录有示例
- [ ] 推荐可操作

## 错误处理
{常见问题和解决方案}

## 相关SOPs
{补充工作流程}

实施SOP模板

# 使用 {方法论} 实施 {功能}

## 概述
{1-2句话：什么，何时，为什么}

## 参数
- **功能描述**：{description}
- **框架**：{framework}
- **测试覆盖**：{coverage}

## 先决条件
{所需工具、知识、设置}

## 步骤
1. 设计功能接口
2. 创建测试
3. 实施功能
4. 重构和优化
5. 记录更改

## 成功标准
- [ ] 功能满足要求
- [ ] 测试通过，覆盖 ≥ {coverage}
- [ ] 文档更新

## 错误处理
{常见问题和解决方案}

## 相关SOPs
{补充工作流程}

反模式

避免这些结构错误：

缺少参数
- ❌ 在步骤中硬编码值
- ✅ 在开始时定义参数
不清楚的先决条件
- ❌ 假设工具已安装
- ✅ 明确列出所需工具和版本
模糊的成功标准
- ❌ “代码应该质量好”
- ✅ “代码通过lint检查，0错误，测试覆盖 ≥ 80%”
无错误处理
- ❌ 仅描述顺利路径
- ✅ 包括常见故障和解决方案
部分组织不良
- ❌ 步骤在参数之前，成功标准与步骤混合
- ✅ 一致的部分顺序：概述 → 参数 → 先决条件 → 步骤 → 成功标准 → 错误处理

SOP结构技能Skill sop-structure

SOP 结构

关键概念

标准SOP解剖

文件命名约定

最佳实践

标题部分

概述部分

参数部分

先决条件部分

步骤部分

成功标准部分

错误处理部分

相关SOPs部分

示例

完整SOP结构示例

常见模式

代码分析SOP模板

实施SOP模板

反模式

相关技能