⚡

SOP维护Skill sop-maintenance

SOP维护技能用于确保标准操作程序（SOP）的准确性、相关性和同步性，通过版本控制、定期更新和弃用管理来保持SOP与系统变化同步。关键词：SOP维护，版本控制，流程文档，DevOps，项目管理，文档管理。

DevOps 0 次安装 0 次浏览 更新于 3/25/2026

名称: sop-维护 描述: 用于更新、版本控制、弃用或维护现有标准操作程序时使用。涵盖保持SOP的准确性、相关性和与实现变化的同步性。 允许工具:

  • Read
  • Write
  • Edit
  • Bash
  • Grep
  • Glob

SOP 维护

SOP需要持续维护以保持准确性和实用性。本技能涵盖保持SOP最新、管理版本以及确保SOP随系统演变的策略。

关键概念

SOP 生命周期

  1. 创建: 初始SOP开发
  2. 活跃使用: SOP定期执行
  3. 更新: 修改以反映变化
  4. 弃用: SOP已过时但仍被引用
  5. 归档/移除: SOP不再需要

SOP 变得过时的原因

  • 技术变化: 工具、框架或语言更新
  • 流程演进: 工作流程改进或变化
  • 环境变化: 基础设施或部署变化
  • 发现: 通过经验找到更好方法
  • 外部依赖: 第三方服务更改API

最佳实践

SOP 的版本控制

将SOP视为代码：

# 将SOP存储在git仓库中
my-sops/
├── .git/
├── deployment/
│   ├── deploy-web-app.sop.md
│   └── rollback-deployment.sop.md
├── development/
│   ├── code-review.sop.md
│   └── feature-implementation.sop.md
└── README.md

提交消息:

git commit -m "feat(deployment): 在deploy-web-app.sop中添加健康检查步骤"
git commit -m "fix(code-review): 更正安全检查清单项"
git commit -m "docs(development): 使用新测试框架更新feature-implementation"

SOP 版本控制

在SOP元数据中包含版本信息：

# 部署应用到生产

**版本**: 2.1.0
**最后更新**: 2025-12-05
**作者**: DevOps团队
**状态**: 活跃

## 变更日志

### v2.1.0 (2025-12-05)
- 添加自动回滚触发器
- 更新健康检查阈值

### v2.0.0 (2025-11-15)
- 从Docker Swarm迁移到Kubernetes
- 添加金丝雀部署步骤

### v1.0.0 (2025-09-01)
- 初始部署SOP

保持SOP最新

定期审查计划:

## SOP 维护计划

- **每月**: 审查高频使用SOP（部署、事件响应）
- **每季度**: 审查所有活跃SOP的准确性
- **重大变化后**: 系统变化时更新SOP
- **事件后**: 根据经验教训更新SOP

维护清单:

## SOP 审查清单

- [ ] 先决条件仍准确
- [ ] 工具/版本当前
- [ ] 步骤反映实际流程
- [ ] 参数仍相关
- [ ] 成功标准可测量
- [ ] 错误处理覆盖常见问题
- [ ] 相关SOP仍有效
- [ ] 示例使用当前语法

弃用SOP

当SOP过时时：

# ⚠️ 弃用: 使用Docker Swarm部署

**状态**: 自2025-11-15起弃用
**替代**: deploy-kubernetes.sop.md
**原因**: 基础设施从Docker Swarm迁移到Kubernetes

## 迁移指南

如果需要从此SOP迁移：
1. 查看新的Kubernetes部署SOP
2. 了解部署过程的关键差异
3. 更新CI/CD管道以使用新SOP
4. 归档Docker Swarm配置

## 原始SOP（仅供参考）

[保留原始内容以供历史参考]

管理SOP集合

目录组织:

sops/
├── active/              # 当前使用的SOP
│   ├── deployment/
│   ├── development/
│   └── operations/
├── deprecated/          # 过时但可能被引用
│   └── legacy-deployments/
└── templates/           # 创建新SOP的模板
    ├── analysis.template.sop.md
    ├── implementation.template.sop.md
    └── deployment.template.sop.md

索引文件:

# SOP 索引

## 活跃SOP

### 部署
- [deploy-web-app.sop.md](active/deployment/deploy-web-app.sop.md) - v2.1.0 - 部署Web应用到生产
- [rollback-deployment.sop.md](active/deployment/rollback-deployment.sop.md) - v1.5.0 - 回滚失败部署

### 开发
- [code-review.sop.md](active/development/code-review.sop.md) - v3.0.0 - 审查代码变更
- [tdd-implementation.sop.md](active/development/tdd-implementation.sop.md) - v2.2.0 - 使用TDD实现功能

## 弃用SOP

- [deploy-docker-swarm.sop.md](deprecated/deploy-docker-swarm.sop.md) - 弃用 - 使用deploy-web-app.sop.md代替

示例

示例1: 为工具变更更新SOP

之前（使用旧测试框架）：

# 运行测试套件

## 步骤

1. 使用Mocha运行测试

   ```bash
   npm run test

  1. 使用Istanbul检查覆盖率

    npm run coverage


**之后（更新为Vitest）：**

```markdown
# 运行测试套件

**版本**: 2.0.0
**最后更新**: 2025-12-05
**变更**: 从Mocha迁移到Vitest

## 步骤

1. 使用Vitest运行测试

   ```bash
   npm run test

  1. 检查覆盖率（内置Vitest）

    npm run test:coverage

迁移说明

如果从v1.x（Mocha）迁移：

  • Vitest对大多数断言使用相同语法
  • 覆盖率内置（无需单独Istanbul步骤）
  • 测试运行显著更快

### 示例2: 添加环境变量支持

**更新SOP以支持环境变量：**

```markdown
# 配置SOP路径

## 概述

使用环境变量或配置文件配置自定义SOP路径。
这允许团队在维护内置SOP的同时维护组织特定的SOP。

## 参数

- **SOP路径**: {sop_paths} - 冒号分隔的目录路径

## 方法

### 方法1: 环境变量（推荐）

设置`AGENT_SOP_PATHS`环境变量：

```bash
# 在~/.zshrc或~/.bashrc中
export AGENT_SOP_PATHS="~/my-team-sops:~/project-sops"

# 或单次使用内联
AGENT_SOP_PATHS="~/my-sops" strands-agents-sops mcp

方法2: 命令行参数

直接传递路径到MCP服务器：

strands-agents-sops mcp --sop-paths ~/my-sops:~/team-sops

方法3: 配置文件

添加到Claude Code设置：

{
  "mcpServers": {
    "agent-sops": {
      "command": "strands-agents-sops",
      "args": ["mcp"],
      "env": {
        "AGENT_SOP_PATHS": "~/my-sops:~/team-sops"
      }
    }
  }
}

优先级

  1. 命令行--sop-paths（最高优先级）
  2. AGENT_SOP_PATHS环境变量
  3. 默认路径（仅内置SOP）

自定义SOP覆盖具有匹配名称的内置SOP。


### 示例3: 事件后SOP更新

**基于生产事件添加错误处理：**

```markdown
# 部署应用到生产

**版本**: 2.2.0
**最后更新**: 2025-12-05
**变更**: 事件#1234后添加数据库连接池检查

## 变更日志

### v2.2.0 (2025-12-05)
- 添加数据库连接池验证步骤
- 更新连接失败的错误处理
- 添加监控告警验证

*原因: 生产事件#1234由连接池耗尽引起*

## 步骤

1. 部署前验证
   - 验证暂存部署健康
   - 检查数据库迁移就绪
   - **新**: 验证数据库连接池配置
     ```bash
     # 检查池设置
     kubectl get configmap db-config -o yaml | grep -A5 pool

     # 验证池大小匹配预期负载
     # 必须 ≥ (预期连接数 * 1.5)
     ```

2. 部署应用
   [... 现有步骤 ...]

3. 部署后验证
   - 运行冒烟测试
   - 监控错误率
   - **新**: 验证数据库连接池指标
     ```bash
     # 检查活跃连接
     # 必须 < 池大小的80%
     curl https://monitoring.example.com/metrics/db-pool
     ```

## 错误处理

### 新: 错误: 数据库连接池耗尽

**症状**: 应用无法获取数据库连接，请求超时

**原因**: 池大小不足以负载，连接泄漏，或慢查询

**解决**:

1. 立即: 扩大连接池大小

   ```bash
   kubectl patch configmap db-config --patch '{"data":{"pool_size":"100"}}'
   kubectl rollout restart deployment app
  1. 监控连接使用5分钟
  2. 如果问题持续，执行回滚
  3. 事件后: 审查慢查询日志并优化

## 常见模式

### SOP 更新模板

```markdown
# {SOP标题}

**版本**: {新版本}
**最后更新**: {日期}
**变更**: {变更摘要}

## 变更日志

### v{新版本} ({日期})
- {变更1}
- {变更2}
- {变更3}

*原因: {为什么进行这些变更}*

### v{前一版本} ({日期})
[先前变更]

## [SOP其余内容]

弃用通知模板

# ⚠️ 弃用: {旧SOP标题}

**状态**: 自{日期}起弃用
**替代**: {新SOP文件.sop.md}
**原因**: {为什么弃用}
**支持结束日期**: {何时将被移除}

## 迁移指南

从此SOP迁移到{新SOP}：

1. **关键差异**:
   - {差异1}
   - {差异2}

2. **迁移步骤**:
   - {步骤1}
   - {步骤2}

3. **破坏性变更**:
   - {破坏性变更1}
   - {破坏性变更2}

## 参考

- 新SOP: [{新SOP标题}]({新SOP文件.sop.md})
- 迁移指南: [链接]
- 公告: [链接到公告]

---

## 原始SOP（供历史参考）

[在此行下方保留原始内容]

反模式

避免这些维护错误:

  1. 无版本跟踪

    • ❌ 更新SOP而不跟踪变更
    • ✅ 使用版本号和变更日志

  2. 忽略弃用SOP

    • ❌ 留下过时SOP而无弃用通知
    • ✅ 清晰标记弃用SOP并提供替代方案

  3. 无通知的破坏性变更

    • ❌ 静默更改SOP行为
    • ✅ 版本提升和破坏性变更的迁移指南

  4. 无审查计划

    • ❌ 仅在SOP中断时更新
    • ✅ 所有SOP的定期审查计划

  5. 差劲的变更沟通

    • ❌ 更新SOP而不通知用户
    • ✅ 向团队宣布重大SOP变更

维护工作流

常规维护

## 每月SOP维护

1. 审查高频SOP
   - 检查执行日志中的失败
   - 审查任何报告的问题
   - 基于用户反馈更新

2. 验证SOP准确性
   - 手动运行关键SOP
   - 验证工具/版本当前
   - 测试示例仍有效

3. 更新文档
   - 修复发现的任何不准确
   - 在需要处添加澄清
   - 更新相关SOP

4. 提交和沟通变更
   - 用描述性消息提交更新
   - 在团队频道中宣布变更
   - 更新SOP索引

变更后维护

## 系统变更后

当基础设施、工具或流程变化时：

1. 识别受影响的SOP

   ```bash
   # 搜索提及变更组件的SOP
   grep -r "docker" sops/*.sop.md

  1. 更新每个受影响的SOP

    • 更新版本号
    • 添加变更日志条目
    • 修改受影响的步骤
    • 更新示例

  2. 测试更新的SOP

    • 运行新工作流
    • 验证所有步骤有效
    • 检查成功标准仍有效

  3. 审查依赖项

    • 检查相关SOP是否需要更新
    • 更新SOP索引
    • 通知团队变更

## 相关技能

- **sop-authoring**: 以高质量创建新SOP
- **sop-structure**: 有效组织SOP
- **sop-rfc2119**: 使用精确的需求关键词