253 lines
7.6 KiB
Markdown
253 lines
7.6 KiB
Markdown
# Sub-Agent Review Checklists
|
||
|
||
5 个子 Agent 的完整检查清单。每个子 Agent 在独立 git worktree 中工作。
|
||
|
||
---
|
||
|
||
## Agent 1: Security & Compliance (安全与合规)
|
||
|
||
### 1.1 Injection (注入漏洞)
|
||
- SQL 注入：字符串拼接 SQL、未使用参数化查询
|
||
- 命令注入：exec/system/os.Command/subprocess 拼接用户输入
|
||
- XSS：未转义的用户输入写入 HTML/DOM
|
||
- XXE：XML 解析器未禁用外部实体
|
||
- SSRF：用户可控 URL 用于服务端请求，缺少白名单
|
||
- LDAP 注入：LDAP 查询拼接用户输入
|
||
- SSTI：用户输入直接传入模板引擎
|
||
- 路径穿越：文件操作中未校验 `../`
|
||
- Header 注入：HTTP 响应头拼接用户输入 (CRLF)
|
||
- Log 注入：日志中拼接未净化的用户输入
|
||
|
||
### 1.2 Authentication & Authorization
|
||
- 缺少认证：敏感 API 端点未要求身份验证
|
||
- 越权访问：缺少资源归属校验（水平越权）
|
||
- 权限提升：普通用户可执行管理员操作（垂直越权）
|
||
- 会话管理：Session fixation、不安全 cookie、缺少超时
|
||
- JWT：弱签名算法 (none/HS256)、未验证签名、token 泄露
|
||
- OAuth：开放重定向、state 缺失、token 存储不安全
|
||
- 默认凭证：代码中预设的用户名密码
|
||
|
||
### 1.3 Secrets & Sensitive Data
|
||
- 硬编码密钥：API key、密码、token、连接字符串写在源码
|
||
- 密钥泄露：.env 提交版本控制、明文密码
|
||
- 日志泄露：敏感数据出现在日志/错误信息中
|
||
- API 响应泄露：接口返回超出必要范围的用户数据
|
||
- 错误信息泄露：堆栈、内部路径、数据库结构暴露
|
||
|
||
### 1.4 Cryptography
|
||
- 弱哈希：MD5/SHA1 用于密码或安全场景
|
||
- 不安全随机数：math/rand 替代 CSPRNG
|
||
- ECB 模式：AES-ECB 等不安全加密模式
|
||
- 硬编码 IV/Salt
|
||
- 缺少完整性校验：加密但未做 HMAC/AEAD
|
||
|
||
### 1.5 Dependency Security
|
||
- 已知漏洞：依赖清单中的 CVE
|
||
- 过时依赖：已停止维护的库
|
||
- 依赖来源：非官方源、typosquatting
|
||
- 许可证合规：GPL 等传染性许可证混入商业项目
|
||
|
||
### 1.6 Privacy & Data Protection
|
||
- PII 未加密存储或传输
|
||
- 缺少数据过期/删除机制
|
||
- 跨境传输未考虑地域合规
|
||
|
||
---
|
||
|
||
## Agent 2: Architecture & Design (架构与设计)
|
||
|
||
### 2.1 Design Principles
|
||
- SRP：类/函数/模块承担过多职责
|
||
- OCP：修改核心逻辑而非通过扩展点添加
|
||
- LSP：子类/实现违反父类/接口契约
|
||
- ISP：接口过大，强迫实现不需要的方法
|
||
- DIP：高层模块直接依赖低层实现
|
||
|
||
### 2.2 Architectural Patterns
|
||
- 分层违规：跨层直接调用
|
||
- 循环依赖：包/模块间循环引用
|
||
- 上帝对象：单类承载过多数据和行为
|
||
- 过度抽象：不必要的工厂/策略/装饰器
|
||
- 模式误用：强行套用不适合的设计模式
|
||
- 配置管理：硬编码环境相关值
|
||
|
||
### 2.3 API Design
|
||
- 一致性：同系统 API 风格不一致
|
||
- 向后兼容：破坏性变更未版本控制
|
||
- 幂等性：写操作缺少幂等保证
|
||
- 批量操作：逐条处理导致 N+1 网络请求
|
||
- 分页：大列表缺少分页/游标
|
||
- 错误响应：格式不统一、缺少错误码
|
||
|
||
### 2.4 Error Handling Strategy
|
||
- 错误传播：底层错误未包装丢失上下文
|
||
- 错误类型：字符串替代结构化错误
|
||
- 恢复策略：缺少重试/降级/断路器
|
||
- 边界处理：系统边界缺少防御性检查
|
||
|
||
### 2.5 Module Boundaries
|
||
- 接口定义：模块间通过实现而非接口通信
|
||
- 数据共享：模块间共享可变数据结构
|
||
- 事件/消息：同步调用链过长
|
||
- 领域模型：贫血模型、逻辑散落 Service 层
|
||
|
||
---
|
||
|
||
## Agent 3: Performance & Resource (性能与资源)
|
||
|
||
### 3.1 Algorithm & Data Structure
|
||
- 热路径上 O(n^2) 或更高复杂度
|
||
- 不当数据结构：线性查找替代哈希
|
||
- 循环内重复计算
|
||
- 不必要的排序/遍历
|
||
|
||
### 3.2 Database Performance
|
||
- N+1 查询：循环内逐条查询
|
||
- 缺少索引：WHERE/JOIN 字段未建索引
|
||
- 全表扫描
|
||
- 大事务持锁过久
|
||
- 连接池未配置或配置不当
|
||
- SELECT * 替代指定字段
|
||
|
||
### 3.3 Memory Management
|
||
- 内存泄漏：未释放引用、全局缓存无上限
|
||
- 循环内创建大对象/切片
|
||
- 未使用缓冲 I/O、一次性读取大文件
|
||
- 循环内字符串拼接
|
||
- 高频对象未使用池化
|
||
|
||
### 3.4 Concurrency Performance
|
||
- 全局锁替代细粒度锁
|
||
- 热点资源锁竞争
|
||
- 无限制创建 goroutine/线程
|
||
- 对只读数据加锁
|
||
- 无缓冲通道导致阻塞
|
||
|
||
### 3.5 I/O Performance
|
||
- 异步上下文中阻塞调用
|
||
- HTTP 客户端未复用连接
|
||
- 大响应未压缩
|
||
- 大数据一次性加载替代流式
|
||
|
||
### 3.6 Caching
|
||
- 频繁重复计算/查询未缓存
|
||
- 缓存穿透：不存在 key 反复查 DB
|
||
- 缓存雪崩：大量 key 同时过期
|
||
- 更新后未失效缓存
|
||
- 无界缓存导致 OOM
|
||
|
||
### 3.7 Resource Leaks
|
||
- 文件句柄：打开未关闭
|
||
- HTTP response body 未关闭
|
||
- 数据库查询结果集未关闭
|
||
- Timer/Ticker/订阅未取消
|
||
- Goroutine/线程启动后永不退出
|
||
|
||
---
|
||
|
||
## Agent 4: Reliability & Data Integrity (可靠性与数据完整性)
|
||
|
||
### 4.1 Error Handling
|
||
- 静默吞错：空 catch、忽略返回 error
|
||
- 泛型 catch：catch(Exception e)
|
||
- 错误消息缺少上下文 (who/what/why)
|
||
- 库代码中 panic/os.Exit
|
||
- 关键路径缺少 recover/降级
|
||
|
||
### 4.2 Null Safety
|
||
- 空指针解引用：未检查 nil/null
|
||
- Optional/Maybe 未正确解包
|
||
- 空集合直接取下标
|
||
- 长链式调用中环节返回 null
|
||
|
||
### 4.3 Concurrency Safety
|
||
- 数据竞争：无保护读写共享变量
|
||
- 死锁：多锁嵌套、不一致加锁顺序
|
||
- check-then-act 未加锁
|
||
- 非线程安全 Map 并发使用
|
||
- 向已关闭 channel 发送数据
|
||
|
||
### 4.4 Transaction & Consistency
|
||
- 多步数据库操作未包裹事务
|
||
- 不恰当的事务隔离级别
|
||
- 跨服务缺少补偿/Saga
|
||
- 异步处理缺少确认/重试
|
||
- 重试产生重复数据
|
||
|
||
### 4.5 Timeout & Retry
|
||
- HTTP/DB/RPC 调用未设超时
|
||
- 无限重试或缺少退避
|
||
- 调用链超时未传递/收缩
|
||
- 缺少断路器保护
|
||
|
||
### 4.6 Boundary Conditions
|
||
- 整数溢出：大数、类型截断
|
||
- 浮点精度：金额用浮点数
|
||
- 时区未明确
|
||
- UTF-8 多字节未处理
|
||
- 空集合边界
|
||
- 并发 first/last、空队列竞态
|
||
|
||
### 4.7 Graceful Shutdown
|
||
- 缺少 SIGTERM/SIGINT 处理
|
||
- 关闭时未等待进行中请求
|
||
- 未释放 DB 连接、文件句柄
|
||
- 内存中待写数据丢失
|
||
|
||
---
|
||
|
||
## Agent 5: Code Quality & Observability (代码质量与可观测性)
|
||
|
||
### 5.1 Complexity
|
||
- 函数圈复杂度 > 15
|
||
- 深层嵌套 > 4 层
|
||
- 函数超过 100 行
|
||
- 参数超过 5 个
|
||
- 单文件超过 500 行
|
||
|
||
### 5.2 Duplication
|
||
- 大段相似代码 > 10 行
|
||
- 相同业务逻辑多处独立实现
|
||
- 魔法数字/字符串多处出现
|
||
|
||
### 5.3 Naming & Readability
|
||
- 不符合语言惯例的命名
|
||
- 含义模糊：data/info/temp/result
|
||
- 同一概念不同命名
|
||
- 布尔命名不是 is/has/can/should
|
||
- 不通用缩写降低可读性
|
||
|
||
### 5.4 Dead Code & Tech Debt
|
||
- 未调用的函数、未使用的变量/导入
|
||
- 被注释的代码块
|
||
- TODO/FIXME/HACK 遗留
|
||
- 使用 deprecated API
|
||
|
||
### 5.5 Test Quality
|
||
- 关键业务路径缺少测试
|
||
- 断言仅检查"不报错"
|
||
- 缺少边界和异常路径测试
|
||
- 测试间隐式依赖
|
||
- 过度 mock
|
||
- 依赖时间/网络等外部状态
|
||
|
||
### 5.6 Logging
|
||
- 关键决策点缺少日志
|
||
- ERROR 级别用于非错误场景
|
||
- 字符串拼接而非结构化日志
|
||
- 日志含密码/token/PII
|
||
- 热路径过度日志
|
||
|
||
### 5.7 Observability
|
||
- 缺少业务指标（请求量、延迟、错误率）
|
||
- 跨服务缺少 trace ID
|
||
- 缺少 liveness/readiness 探针
|
||
- 关键故障路径缺少告警
|
||
|
||
### 5.8 Build & Deploy
|
||
- 构建结果依赖环境状态
|
||
- 缺少 lock 文件
|
||
- 开发/生产配置差异未文档化
|
||
- 迁移脚本缺少回滚方案
|
||
- 大功能上线缺少 feature flag
|