| 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 设计、数据建模
框架
- 需求收集 — 功能需求 + 非功能需求（规模/延迟/可用性/成本）+ 约束
- 高层设计 — 组件图 + 数据流 + API 契约 + 存储选型
- 深入设计 — 数据模型 + API 端点 + 缓存策略 + 队列设计 + 错误处理
- 扩展与可靠性 — 负载估算 + 扩展策略 + 故障转移 + 监控告警
- 权衡分析 — 每个决策的 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、为什么报错、定位问题
调试流程
- 复现 — 稳定复现步骤、确认环境和条件
- 隔离 — 缩小范围（二分法、去除变量）
- 诊断 — 查日志、追踪调用链、检查近期变更
- 修复 — 修复 + 验证 + 回归测试
- 防范 — 添加监控/测试/文档，防止再发
6. 测试策略 (Testing Strategy)
设计有效的测试策略，平衡覆盖率、速度和维护成本。
触发词: 怎么测试、测试策略、测试计划、写测试
测试金字塔
/ E2E \ 少量, 慢, 高置信度
/ 集成测试 \ 适量, 中等速度
/ 单元测试 \ 大量, 快, 聚焦
按组件策略
| 组件类型 | 测试重点 |
|---|
| API 端点 | 业务逻辑单元测试 + HTTP 层集成测试 + 契约测试 |
| 数据管道 | 输入验证 + 转换正确性 + 幂等性 |
| 前端 | 组件测试 + 交互测试 + 视觉回归 + 无障碍性 |
| 基础设施 | 冒烟测试 + 混沌工程 + 负载测试 |
重点覆盖: 业务关键路径、错误处理、边界条件、安全边界、数据完整性。
7. 技术债管理 (Tech Debt)
系统性识别、分类和优先排序技术债。
触发词: 技术债、该重构什么、代码健康度
分类
| 类型 | 示例 | 风险 |
|---|
| 代码债 | 重复逻辑、差的抽象 | Bug、开发减速 |
| 架构债 | 该拆分的单体 | 扩展瓶颈 |
| 测试债 | 低覆盖率、不稳定测试 | 回归上线 |
| 依赖债 | 过期库、无维护依赖 | 安全漏洞 |
| 文档债 | 缺少 Runbook | 新人上手难 |
| 基础设施债 | 手动部署、无监控 | 事故恢复慢 |
优先级公式
优先级 = (影响 1-5 + 风险 1-5) × (6 - 工作量 1-5)
8. 部署检查 (Deploy Checklist)
部署前系统性检查，确保安全上线。
触发词: 部署检查、发布前检查、上线清单
检查清单
9. 站会 (Standup)
从近期活动中生成结构化站会更新。
触发词: 站会、standup、今天做什么
输出格式
## 站会 — [日期]
### 昨天
- [已完成事项，附工单引用]
### 今天
- [计划事项，附工单引用]
### 阻塞
- [阻塞事项，附上下文和谁能帮忙]
10. 技术文档 (Documentation)
编写高质量的技术文档：README、API 文档、Runbook。
触发词: 写文档、README、API 文档、Runbook
文档类型
| 类型 | 受众 | 核心内容 |
|---|
| README | 新接手者 | 项目是什么、怎么跑、怎么贡献 |
| API 文档 | 调用方 | 端点、参数、示例、错误码 |
| Runbook | 运维 | 操作步骤、故障排查、应急预案 |
| ADR | 团队 | 为什么这样设计（见「架构决策」章节） |
README 模板
# 项目名称
[一句话描述]
## 快速开始
[3 步内跑起来]
## 架构
[高层架构图 + 简要说明]
## 开发
[环境搭建、运行、测试]
## 部署
[怎么上线]
## 贡献
[分支策略、PR 规范、代码风格]
