engineering-playbook

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

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

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

---

1. 代码审查 (Code Review)

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

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

审查维度

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

输出格式

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

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

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

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

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

---

2. 架构决策 (Architecture)

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

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

输出 — ADR 格式

# 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	不影响用户，内部问题	下一个工作日

响应流程

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

复盘模板

## 事故复盘: [标题]
**级别:** 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、今天做什么

输出格式

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

---

10. 技术文档 (Documentation)

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

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

文档类型

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

README 模板

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

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

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

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

## 部署
[怎么上线]

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