Engineering Playbook

---
name: engineering-playbook
description: 工程保障团队完整手册。覆盖代码审查、架构设计、事故响应、技术债管理、测试策略、部署检查、调试、站会、系统设计和技术文档全流程。当涉及任何工程技术相关的请求时自动触发。
argument-hint: "<描述你需要工程团队帮助的事项>"
---

# 工程保障团队手册 (Engineering Playbook)

本手册覆盖工程保障团队的全部 10 项核心能力。主理人根据用户需求自动选择合适的工作流。

---

## 1. 代码审查 (Code Review)

对代码变更进行结构化审查，聚焦安全、性能、正确性和可维护性。

**触发词**: 审查代码、review PR、代码安全吗、帮我看看这段代码

### 审查维度

| 维度 | 关注点 |
|------|--------|
| **安全** | SQL 注入、XSS、CSRF、密钥泄露、SSRF、路径遍历 |
| **性能** | N+1 查询、内存泄漏、O(n²) 热路径、缺失索引、资源泄漏 |
| **正确性** | 边界条件、竞态、错误处理、差一错误、类型安全 |
| **可维护性** | 命名、函数拆分、耦合度、测试覆盖、文档 |

### 输出格式

```markdown
## 代码审查: [PR/文件名]

### 🔴 严重 (Must Fix)
- [问题] — 文件:行号 — 建议修复

### 🟡 建议 (Should Fix)
- [问题] — 文件:行号 — 建议修复

### 🟢 可选 (Nice to Have)
- [建议] — 理由

### 总结
安全: [✅/⚠️/❌] | 性能: [✅/⚠️/❌] | 正确性: [✅/⚠️/❌] | 可维护性: [✅/⚠️/❌]
```

---

## 2. 架构决策 (Architecture)

创建架构决策记录 (ADR) 或评估系统设计方案。

**触发词**: 架构选型、技术方案对比、ADR、该用 X 还是 Y

### 输出 — ADR 格式

```markdown
# ADR-[编号]: [标题]

**状态:** 提议 | 已接受 | 已弃用
**日期:** [日期] | **决策者:** [人员]

## 背景
[情况和约束]

## 考虑的方案
### 方案 A: [名称]
| 维度 | 评估 |
|------|------|
| 复杂度 | [低/中/高] |
| 成本 | [评估] |
| 可扩展性 | [评估] |
| 团队熟悉度 | [评估] |
**优点:** ... | **缺点:** ...

### 方案 B: [名称]
[同上格式]

## 权衡分析 → 决策 → 后果 → 行动项
```

**提示**: 预先说明约束（时间、QPS、预算）会大幅提升建议质量。

---

## 3. 系统设计 (System Design)

从需求到架构的完整系统设计流程。

**触发词**: 设计系统、怎么架构、API 设计、数据建模

### 框架

1. **需求收集** — 功能需求 + 非功能需求（规模/延迟/可用性/成本）+ 约束
2. **高层设计** — 组件图 + 数据流 + API 契约 + 存储选型
3. **深入设计** — 数据模型 + API 端点 + 缓存策略 + 队列设计 + 错误处理
4. **扩展与可靠性** — 负载估算 + 扩展策略 + 故障转移 + 监控告警
5. **权衡分析** — 每个决策的 trade-off，标注需重新审视的点

---

## 4. 事故响应 (Incident Response)

从分级到复盘的完整事故响应流程。

**触发词**: 故障、事故、P0/P1、服务挂了、incident

### 事故分级

| 级别 | 定义 | 响应时间 |
|------|------|---------|
| P0 | 核心服务不可用，影响所有用户 | 立即 |
| P1 | 主要功能降级，影响部分用户 | 15 分钟内 |
| P2 | 次要功能异常，有 workaround | 1 小时内 |
| P3 | 不影响用户，内部问题 | 下一个工作日 |

### 响应流程

```
检测 → 分级 → 组建团队 → 状态通知 → 调查 → 缓解 → 修复 → 复盘
```

### 复盘模板

```markdown
## 事故复盘: [标题]
**级别:** P[X] | **持续时间:** [X]h [X]m | **影响:** [用户数/影响范围]

### 时间线
[HH:MM] 事件/动作

### 根因
[技术根因] → [流程根因]

### 改进项
| 优先级 | 改进项 | 负责人 | 截止日 |
|--------|--------|--------|--------|
```

---

## 5. 调试 (Debug)

结构化调试方法：复现 → 隔离 → 诊断 → 修复。

**触发词**: 帮我排查、debug、为什么报错、定位问题

### 调试流程

1. **复现** — 稳定复现步骤、确认环境和条件
2. **隔离** — 缩小范围（二分法、去除变量）
3. **诊断** — 查日志、追踪调用链、检查近期变更
4. **修复** — 修复 + 验证 + 回归测试
5. **防范** — 添加监控/测试/文档，防止再发

---

## 6. 测试策略 (Testing Strategy)

设计有效的测试策略，平衡覆盖率、速度和维护成本。

**触发词**: 怎么测试、测试策略、测试计划、写测试

### 测试金字塔

```
        /  E2E  \         少量, 慢, 高置信度
       / 集成测试 \        适量, 中等速度
      /   单元测试  \      大量, 快, 聚焦
```

### 按组件策略

| 组件类型 | 测试重点 |
|---------|---------|
| API 端点 | 业务逻辑单元测试 + HTTP 层集成测试 + 契约测试 |
| 数据管道 | 输入验证 + 转换正确性 + 幂等性 |
| 前端 | 组件测试 + 交互测试 + 视觉回归 + 无障碍性 |
| 基础设施 | 冒烟测试 + 混沌工程 + 负载测试 |

**重点覆盖**: 业务关键路径、错误处理、边界条件、安全边界、数据完整性。

---

## 7. 技术债管理 (Tech Debt)

系统性识别、分类和优先排序技术债。

**触发词**: 技术债、该重构什么、代码健康度

### 分类

| 类型 | 示例 | 风险 |
|------|------|------|
| 代码债 | 重复逻辑、差的抽象 | Bug、开发减速 |
| 架构债 | 该拆分的单体 | 扩展瓶颈 |
| 测试债 | 低覆盖率、不稳定测试 | 回归上线 |
| 依赖债 | 过期库、无维护依赖 | 安全漏洞 |
| 文档债 | 缺少 Runbook | 新人上手难 |
| 基础设施债 | 手动部署、无监控 | 事故恢复慢 |

### 优先级公式

优先级 = (影响 1-5 + 风险 1-5) × (6 - 工作量 1-5)

---

## 8. 部署检查 (Deploy Checklist)

部署前系统性检查，确保安全上线。

**触发词**: 部署检查、发布前检查、上线清单

### 检查清单

- [ ] **代码**: 所有测试通过、代码已审查、无待处理 TODO
- [ ] **依赖**: 依赖锁定、无已知漏洞、兼容性确认
- [ ] **数据库**: 迁移脚本就绪、可回滚、已备份
- [ ] **配置**: 环境变量就位、Feature Flag 状态正确
- [ ] **监控**: 告警配置、关键指标仪表盘、日志级别
- [ ] **回滚**: 回滚方案明确、回滚步骤可在 X 分钟内完成
- [ ] **通知**: 利益相关方已通知、维护窗口已确认

---

## 9. 站会 (Standup)

从近期活动中生成结构化站会更新。

**触发词**: 站会、standup、今天做什么

### 输出格式

```markdown
## 站会 — [日期]
### 昨天
- [已完成事项，附工单引用]
### 今天
- [计划事项，附工单引用]
### 阻塞
- [阻塞事项，附上下文和谁能帮忙]
```

---

## 10. 技术文档 (Documentation)

编写高质量的技术文档：README、API 文档、Runbook。

**触发词**: 写文档、README、API 文档、Runbook

### 文档类型

| 类型 | 受众 | 核心内容 |
|------|------|---------|
| README | 新接手者 | 项目是什么、怎么跑、怎么贡献 |
| API 文档 | 调用方 | 端点、参数、示例、错误码 |
| Runbook | 运维 | 操作步骤、故障排查、应急预案 |
| ADR | 团队 | 为什么这样设计（见「架构决策」章节） |

### README 模板

```markdown
# 项目名称
[一句话描述]

## 快速开始
[3 步内跑起来]

## 架构
[高层架构图 + 简要说明]

## 开发
[环境搭建、运行、测试]

## 部署
[怎么上线]

## 贡献
[分支策略、PR 规范、代码风格]
```