sop-maintenance

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SOP Maintenance

SOP维护

SOPs require ongoing maintenance to remain accurate and useful. This skill covers strategies for keeping SOPs current, managing versions, and ensuring SOPs evolve with your systems.

SOP需要持续维护才能保持准确和实用。本技能涵盖保持SOP与时俱进、管理版本以及确保SOP随系统演进的策略。

Key Concepts

核心概念

SOP Lifecycle

SOP生命周期

Creation: Initial SOP development
Active Use: SOP is being executed regularly
Update: Modifications to reflect changes
Deprecation: SOP is outdated but referenced
Archive/Removal: SOP is no longer needed

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

Why SOPs Become Outdated

SOP过时的原因

Technology Changes: Tools, frameworks, or languages updated
Process Evolution: Workflows improve or change
Environment Changes: Infrastructure or deployment changes
Discovery: Better approaches found through experience
External Dependencies: Third-party services change APIs

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

Best Practices

最佳实践

Version Control for SOPs

SOP的版本控制

Treat SOPs as code:

bash

undefined

将SOP视为代码：

bash

undefined

Store SOPs in git repository

my-sops/ ├── .git/ ├── deployment/ │ ├── deploy-web-app.sop.md │ └── rollback-deployment.sop.md ├── development/ │ ├── code-review.sop.md │ └── feature-implementation.sop.md └── README.md


**Commit Messages:**

```bash
git commit -m "feat(deployment): add health check step to deploy-web-app.sop"
git commit -m "fix(code-review): correct security checklist items"
git commit -m "docs(development): update feature-implementation with new test framework"


**提交信息：**

```bash
git commit -m "feat(deployment): add health check step to deploy-web-app.sop"
git commit -m "fix(code-review): correct security checklist items"
git commit -m "docs(development): update feature-implementation with new test framework"

SOP Versioning

SOP版本管理

Include version information in SOP metadata:

markdown

undefined

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

markdown

undefined

Deploy Application to Production

Version: 2.1.0 Last Updated: 2025-12-05 Author: DevOps Team Status: Active

Changelog

v2.1.0 (2025-12-05)

Added automated rollback triggers
Updated health check thresholds

Added automated rollback triggers
Updated health check thresholds

v2.0.0 (2025-11-15)

Migrated to Kubernetes from Docker Swarm
Added canary deployment steps

Migrated to Kubernetes from Docker Swarm
Added canary deployment steps

v1.0.0 (2025-09-01)

Initial deployment SOP

undefined

Initial deployment SOP

undefined

Keeping SOPs Current

保持SOP与时俱进

Regular Review Schedule:

markdown

undefined

定期审查计划：

markdown

undefined

SOP Maintenance Schedule

SOP维护计划

Monthly: Review frequently-used SOPs (deployment, incident response)
Quarterly: Review all active SOPs for accuracy
After Major Changes: Update SOPs when systems change
Post-Incident: Update SOPs based on lessons learned


**Maintenance Checklist:**

```markdown

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


**维护检查清单：**

```markdown

SOP Review Checklist

SOP审查检查清单

Prerequisites are still accurate
Tools/versions are current
Steps reflect actual process
Parameters are still relevant
Success criteria are measurable
Error handling covers common issues
Related SOPs are still valid
Examples use current syntax

undefined

前提条件仍然准确
工具/版本是最新的
步骤反映实际流程
参数仍然相关
成功标准可衡量
错误处理覆盖常见问题
相关SOP仍然有效
示例使用当前语法

undefined

Deprecating SOPs

废弃SOP

When an SOP is outdated:

markdown

undefined

当SOP过时：

markdown

undefined

⚠️ DEPRECATED: Deploy Using Docker Swarm

Status: DEPRECATED as of 2025-11-15 Replaced By: deploy-kubernetes.sop.md Reason: Migrated infrastructure from Docker Swarm to Kubernetes

Migration Guide

If you need to migrate from this SOP:

Review new Kubernetes deployment SOP
Understand key differences in deployment process
Update CI/CD pipelines to use new SOP
Archive Docker Swarm configurations

If you need to migrate from this SOP:

Review new Kubernetes deployment SOP
Understand key differences in deployment process
Update CI/CD pipelines to use new SOP
Archive Docker Swarm configurations

Original SOP (for reference only)

[Keep original content for historical reference]

undefined

[Keep original content for historical reference]

undefined

Managing SOP Collections

管理SOP集合

Directory Organization:

bash

sops/
├── active/              # Currently used SOPs
│   ├── deployment/
│   ├── development/
│   └── operations/
├── deprecated/          # Outdated but may be referenced
│   └── legacy-deployments/
└── templates/           # SOP templates for creating new SOPs
    ├── analysis.template.sop.md
    ├── implementation.template.sop.md
    └── deployment.template.sop.md

Index File:

markdown

undefined

目录组织：

bash

sops/
├── active/              # Currently used SOPs
│   ├── deployment/
│   ├── development/
│   └── operations/
├── deprecated/          # Outdated but may be referenced
│   └── legacy-deployments/
└── templates/           # SOP templates for creating new SOPs
    ├── analysis.template.sop.md
    ├── implementation.template.sop.md
    └── deployment.template.sop.md

索引文件：

markdown

undefined

SOP Index

Active SOPs

Deployment

deploy-web-app.sop.md - v2.1.0 - Deploy web application to production
rollback-deployment.sop.md - v1.5.0 - Rollback failed deployment

deploy-web-app.sop.md - v2.1.0 - Deploy web application to production
rollback-deployment.sop.md - v1.5.0 - Rollback failed deployment

Development

code-review.sop.md - v3.0.0 - Review code changes
tdd-implementation.sop.md - v2.2.0 - Implement features with TDD

code-review.sop.md - v3.0.0 - Review code changes
tdd-implementation.sop.md - v2.2.0 - Implement features with TDD

Deprecated SOPs

deploy-docker-swarm.sop.md - DEPRECATED - Use deploy-web-app.sop.md instead

undefined

deploy-docker-swarm.sop.md - DEPRECATED - Use deploy-web-app.sop.md instead

undefined

Examples

示例

Example 1: Updating SOP for Tool Change

示例1：针对工具变更更新SOP

Before (using old test framework):

markdown

undefined

更新前（使用旧测试框架）：

markdown

undefined

Run Test Suite

Steps

Run tests with Mocha
bash
```
npm run test
```
Check coverage with Istanbul
bash
```
npm run coverage
```


**After (updated for Vitest):**

```markdown

Run tests with Mocha
bash
```
npm run test
```
Check coverage with Istanbul
bash
```
npm run coverage
```


**更新后（适配Vitest）：**

```markdown

Run Test Suite

Version: 2.0.0 Last Updated: 2025-12-05 Changes: Migrated from Mocha to Vitest

Steps

Run tests with Vitest
bash
```
npm run test
```
Check coverage (built into Vitest)
bash
```
npm run test:coverage
```

Run tests with Vitest
bash
```
npm run test
```
Check coverage (built into Vitest)
bash
```
npm run test:coverage
```

Migration Notes

If migrating from v1.x (Mocha):

Vitest uses same syntax for most assertions
Coverage is built-in (no separate Istanbul step)
Tests run significantly faster

undefined

If migrating from v1.x (Mocha):

Vitest uses same syntax for most assertions
Coverage is built-in (no separate Istanbul step)
Tests run significantly faster

undefined

Example 2: Adding Environment Variable Support

示例2：添加环境变量支持

Updated SOP with env var support:

markdown

undefined

添加环境变量支持的更新后SOP：

markdown

undefined

Configure SOP Paths

Overview

Configure custom SOP paths using environment variable or configuration file. This allows teams to maintain organization-specific SOPs alongside built-in ones.

Parameters

SOP Paths: {sop_paths} - Colon-separated directory paths

SOP Paths: {sop_paths} - Colon-separated directory paths

Methods

Method 1: Environment Variable (Recommended)

Set

AGENT_SOP_PATHS

environment variable:

bash

undefined

Set

AGENT_SOP_PATHS

environment variable:

bash

undefined

In ~/.zshrc or ~/.bashrc

export AGENT_SOP_PATHS="~~/my-team-sops:~~/project-sops"

Or inline for single use

AGENT_SOP_PATHS="~/my-sops" strands-agents-sops mcp

undefined

AGENT_SOP_PATHS="~/my-sops" strands-agents-sops mcp

undefined

Method 2: Command Line Argument

Pass paths directly to MCP server:

bash

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

Pass paths directly to MCP server:

bash

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

Method 3: Configuration File

Add to Claude Code settings:

json

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

Add to Claude Code settings:

json

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

Precedence

Command line
```
--sop-paths
```
(highest priority)
```
AGENT_SOP_PATHS
```
environment variable
Default paths (built-in SOPs only)

Custom SOPs override built-in SOPs with matching names.

undefined

Command line
```
--sop-paths
```
(highest priority)
```
AGENT_SOP_PATHS
```
environment variable
Default paths (built-in SOPs only)

Custom SOPs override built-in SOPs with matching names.

undefined

Example 3: Post-Incident SOP Update

示例3：事件后SOP更新

Adding error handling based on production incident:

markdown

undefined

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

markdown

undefined

Deploy Application to Production

Version: 2.2.0 Last Updated: 2025-12-05 Changes: Added database connection pool check after incident #1234

Changelog

v2.2.0 (2025-12-05)

Added database connection pool verification step
Updated error handling for connection failures
Added monitoring alert validation

Reason: Production incident #1234 caused by connection pool exhaustion

Added database connection pool verification step
Updated error handling for connection failures
Added monitoring alert validation

Reason: Production incident #1234 caused by connection pool exhaustion

Steps

Pre-deployment verification

Verify staging deployment healthy
Check database migrations ready

NEW: Verify database connection pool configuration

bash

# Check pool settings
kubectl get configmap db-config -o yaml | grep -A5 pool

# Validate pool size matches expected load
# MUST be ≥ (expected_connections * 1.5)

Deploy application [... existing steps ...]

Post-deployment verification

Run smoke tests
Monitor error rates

NEW: Verify database connection pool metrics

bash

# Check active connections
# MUST be < 80% of pool size
curl https://monitoring.example.com/metrics/db-pool

Pre-deployment verification

Verify staging deployment healthy
Check database migrations ready

NEW: Verify database connection pool configuration

bash

# Check pool settings
kubectl get configmap db-config -o yaml | grep -A5 pool

# Validate pool size matches expected load
# MUST be ≥ (expected_connections * 1.5)

Deploy application [... existing steps ...]

Post-deployment verification

Run smoke tests
Monitor error rates

NEW: Verify database connection pool metrics

bash

# Check active connections
# MUST be < 80% of pool size
curl https://monitoring.example.com/metrics/db-pool

Error Handling

NEW: Error: Database Connection Pool Exhausted

Symptoms: Application unable to acquire database connections, requests timing out

Cause: Pool size insufficient for load, connection leaks, or slow queries

Resolution:

Immediate: Scale up connection pool size

bash

kubectl patch configmap db-config --patch '{"data":{"pool_size":"100"}}'
kubectl rollout restart deployment app

Monitor connection usage for 5 minutes
If issue persists, execute rollback
Post-incident: Review slow query logs and optimize

undefined

Symptoms: Application unable to acquire database connections, requests timing out

Cause: Pool size insufficient for load, connection leaks, or slow queries

Resolution:

Immediate: Scale up connection pool size

bash

kubectl patch configmap db-config --patch '{"data":{"pool_size":"100"}}'
kubectl rollout restart deployment app

Monitor connection usage for 5 minutes
If issue persists, execute rollback
Post-incident: Review slow query logs and optimize

undefined

Common Patterns

常见模式

Template for SOP Update

SOP更新模板

markdown

undefined

markdown

undefined

{SOP Title}

Version: {new_version} Last Updated: {date} Changes: {summary of changes}

Changelog

v{new_version} ({date})

{change 1}
{change 2}
{change 3}

Reason: {why these changes were made}

{change 1}
{change 2}
{change 3}

Reason: {why these changes were made}

v{previous_version} ({date})

[Previous changes]

[Rest of SOP content]

undefined

undefined

Template for Deprecation Notice

废弃通知模板

markdown

undefined

markdown

undefined

⚠️ DEPRECATED: {Old SOP Title}

Status: DEPRECATED as of {date} Replaced By: {new-sop-file.sop.md} Reason: {why deprecated} Support End Date: {when will this be removed}

Migration Guide

To migrate from this SOP to {new SOP}:

Key Differences:
- {difference 1}
- {difference 2}
Migration Steps:
- {step 1}
- {step 2}
Breaking Changes:
- {breaking change 1}
- {breaking change 2}

To migrate from this SOP to {new SOP}:

Key Differences:
- {difference 1}
- {difference 2}
Migration Steps:
- {step 1}
- {step 2}
Breaking Changes:
- {breaking change 1}
- {breaking change 2}

References

New SOP: {new-sop-title}
Migration Guide: [link]
Announcement: [link to announcement]

New SOP: {new-sop-title}
Migration Guide: [link]
Announcement: [link to announcement]

Original SOP (for historical reference)

[Keep original content below this line]

undefined

[Keep original content below this line]

undefined

Anti-Patterns

反模式

Avoid These Maintenance Mistakes:

No Version Tracking
- ❌ Updating SOPs without tracking changes
- ✅ Use version numbers and changelog
Ignoring Deprecated SOPs
- ❌ Leaving outdated SOPs without deprecation notice
- ✅ Clearly mark deprecated SOPs and provide alternatives
Breaking Changes Without Notice
- ❌ Silently changing SOP behavior
- ✅ Version bump and migration guide for breaking changes
No Review Schedule
- ❌ Only updating SOPs when they break
- ✅ Regular review schedule for all SOPs
Poor Change Communication
- ❌ Updating SOPs without notifying users
- ✅ Announce significant SOP changes to team

避免这些维护错误：

无版本跟踪
- ❌ 更新SOP但不跟踪变更
- ✅ 使用版本号和变更日志
忽略废弃SOP
- ❌ 保留过时SOP但不添加废弃通知
- ✅ 清晰标记废弃SOP并提供替代方案
无通知的破坏性变更
- ❌ 静默更改SOP行为
- ✅ 版本升级并提供迁移指南以应对破坏性变更
无审查计划
- ❌ 仅在SOP失效时才更新
- ✅ 为所有SOP制定定期审查计划
变更沟通不畅
- ❌ 更新SOP但不通知用户
- ✅ 向团队宣布重大SOP变更

Maintenance Workflow

维护工作流

Regular Maintenance

定期维护

markdown

undefined

markdown

undefined

Monthly SOP Maintenance

Review high-frequency SOPs
- Check execution logs for failures
- Review any reported issues
- Update based on user feedback
Validate SOP accuracy
- Run through critical SOPs manually
- Verify tools/versions are current
- Test examples still work
Update documentation
- Fix any inaccuracies found
- Add clarifications where needed
- Update related SOPs
Commit and communicate changes
- Commit updates with descriptive messages
- Announce changes in team channel
- Update SOP index

undefined

Review high-frequency SOPs
- Check execution logs for failures
- Review any reported issues
- Update based on user feedback
Validate SOP accuracy
- Run through critical SOPs manually
- Verify tools/versions are current
- Test examples still work
Update documentation
- Fix any inaccuracies found
- Add clarifications where needed
- Update related SOPs
Commit and communicate changes
- Commit updates with descriptive messages
- Announce changes in team channel
- Update SOP index

undefined

Post-Change Maintenance

变更后维护

markdown

undefined

markdown

undefined

After System Changes

When infrastructure, tools, or processes change:

Identify affected SOPs

bash

# Search for SOPs mentioning changed component
grep -r "docker" sops/*.sop.md

Update each affected SOP
- Update version number
- Add changelog entry
- Modify affected steps
- Update examples
Test updated SOPs
- Run through new workflow
- Verify all steps work
- Check success criteria still valid
Review dependencies
- Check related SOPs need updates
- Update SOP index
- Notify team of changes

undefined

When infrastructure, tools, or processes change:

Identify affected SOPs

bash

# Search for SOPs mentioning changed component
grep -r "docker" sops/*.sop.md

Update each affected SOP
- Update version number
- Add changelog entry
- Modify affected steps
- Update examples
Test updated SOPs
- Run through new workflow
- Verify all steps work
- Check success criteria still valid
Review dependencies
- Check related SOPs need updates
- Update SOP index
- Notify team of changes

undefined