一份技术设计可能包含架构图、接口定义、数据库模型和部署方案,看起来已经相当完整。但真正开始实现之后,团队仍然会遇到几个很具体的问题:超时到底重试还是失败?重试会不会重复写入?多租户数据在哪一层隔离?“支持高并发”到底是多少 TPS?
为什么需要这个 Skill
技术设计质量评审 Skill 会在实现开始前,把设计声明拆成可回答的问题、TD-## 发现和最小验证动作。它只复核已提供的设计材料,并为架构决策整理依据,不替团队批准架构。
Skill 用来做什么
当你要在实现前检查 ADR、组件设计、数据流、接口约束和非功能目标时,使用这个 Skill。它关注边界、依赖、失败模式、数据一致性、安全、性能、可观测性、兼容性、可维护性、恢复/降级和验证准备度。
它适合这些场景:
- 架构图存在,但服务职责和跨边界行为没有写清楚。
- 设计声称“自动重试”“支持高并发”或“具备监控”,却没有阈值和证据。
- 下游失败、重复提交、版本演进或恢复路径可能影响第一轮实现。
- 团队需要把设计风险交给研发、QA、安全或运维继续处理。
它不是代码评审、性能测试、生产探针、架构批准或发布就绪判断。
它不做什么
技术设计质量评审 Skill 不替代:
- 代码评审和实现质量检查;
- 性能、容量、兼容性或安全测试;
- 生产运行验证和故障演练;
- 架构批准、风险接受或发布决策;
- 真实系统中的数据库、API 或探针执行。
它是一层设计质量关口:帮助团队在实现前明确设计声明、证据缺口和验证动作。
它主要检查哪些内容
复核时要把“边界、依赖、性能”等设计主题转成具体问题,确认现有材料是否给出答案:
| 复核维度 | 重点问题 |
|---|---|
| 边界与职责 | 谁负责什么?服务边界、数据边界和失败责任是否清楚? |
| 依赖与失败 | 下游超时、拒绝、限流、不可用时怎么办? |
| 数据与一致性 | 事务、幂等、重复提交和最终一致性如何保证? |
| 安全与权限 | 身份、授权、租户隔离和敏感数据在哪里处理? |
| 性能与容量 | TPS、并发、延迟、容量和资源假设是否明确? |
| 可观测性 | 日志、指标和链路追踪能否定位一次失败和一次重试? |
| 兼容与演进 | API、数据模式、客户端和版本升级如何共存? |
| 恢复与降级 | 是否有补偿、重放、降级、回滚和数据修复路径? |
| 可维护性 | 配置、扩展点、职责和依赖复杂度是否可控? |
| 验证准备度 | 设计声明由什么测试、指标、实验或运行证据证明? |
开始之前先审计输入
先把设计输入分为六类。组件名称不能代替证据,架构图也不能替你定义容量和恢复行为。
| 状态 | 例子 | 应该怎么做 |
|---|---|---|
| known | ADR 明确指定异步导出任务 | 引用版本和段落 |
| missing | 没有提供重试策略、容量目标或租户边界 | 标记缺口和影响 |
| conflicting | ADR 写同步,时序图写异步 | 保留双方来源,要求决策 |
| stale | 设计仍引用旧 API 版本 | 降低结论强度,确认适用范围 |
| out_of_scope | 本次没有提供代码或生产探针 | 明确不评估实现和运行时 |
| assumptions | 暂时假设对象存储支持版本控制 | 写出影响和验证方式 |
缺少材料时仍可做有限复核,但结论要明确受什么限制,并列出要补的内容、负责人和后续验证。
从问题到结构化发现
写 TD-## 发现前,先确认来源、设计范围、证据状态、影响、负责人和验证方式。下面沿用这个 Skill 的编号与多租户导出场景。
分层写法
技术设计复核尤其容易把建议写成决定。可以用下面这条链检查输出:
| 类型 | 示例 |
|---|---|
| 设计事实 | ADR 指定使用异步队列,未提供死信处理说明 |
| 证据支持的推断 | 消费者失败可能让任务长期处于 Pending |
| 候选建议 | 考虑死信队列、重放和超时告警 |
| 人工决策 | 是否接受至少一次投递语义,以及重复任务由谁裁决 |
这样,AI 可以帮助团队暴露风险和准备验证,但最终架构取舍仍然属于团队。
一个完整案例
以下示例按输入、分析、发现、决策和验证展开;缺少材料时保留 missing、conflicting 或 assumptions 状态。
输入
示例只提供了导出路径和下载接口;租户权限矩阵、对象存储签名策略及审计方案尚未提供。
分析
下载请求含有 job_id,但设计没有说明服务端如何确认该任务属于当前租户。因此,不能仅凭导出文件路径判断租户隔离已经成立。
发现
一条 TD-## 发现如何产生
假设多租户发票导出设计写明:
导出文件:exports/{tenant_id}/{job_id}.csv
下载接口:GET /exports/{job_id}/download
设计没有说明下载接口如何重新验证 tenant_id,也没有给出对象存储签名策略、审计字段或跨租户失败证据。
TD-03 — 下载链路缺少明确的租户授权边界
- 来源 / 证据: 已提供的导出设计、下载 API、对象存储路径和审计流程;实际复核时应补充具体版本和章节。租户权限矩阵、对象存储签名策略和审计方案未提供。
- 状态: missing
- 影响 / 优先级: 如果要求租户隔离,跨租户访问和审计缺口都可能影响设计;受影响范围和项目分级标准尚未提供,优先级暂不评定。
- 缺口动作: 明确 job_id 与 tenant_id 的绑定位置,并说明 API、服务端和对象存储签名策略各自负责什么。
- 责任角色: 需要分配 API 或安全负责人决定在哪里执行所有权校验;现有设计没有指定负责人。
- 待决策问题: 租户授权由 API 网关、导出服务还是对象存储策略执行?跨租户请求统一返回什么?
- 关闭条件: 设计和权限矩阵对合法、跨租户、过期和不存在资源给出一致行为,并能追踪到验证场景。
- 验证方式: 负责人确认需要租户隔离后,在隔离环境使用合成租户和导出文件;跨租户请求预期被拒绝,并保留响应和审计记录。实际执行结果单独记录。
TD-03 把风险送进 ADR 修订、问题单、测试任务或验证实验,不负责给设计打分。实现完成后,它还可以重新审计并关闭。
决策
责任角色和待决策问题应由对应负责人确认;Skill 不替他们做风险取舍。
验证
关闭前按发现中的验证方式执行,并保留原始产物;没有执行记录时,状态仍然保持未验证。
发现如何进入下一阶段
交接产物
每条 TD-## 都要带上后续工作所需的信息:
| 交接字段 | 要保留的内容 |
|---|---|
| 来源与范围 | 设计版本、组件、接口、依赖和本轮排除项 |
| 证据与影响 | 设计中直接写明的事实、未提供的材料,以及受影响的边界或决策 |
| 责任与待决策项 | 哪个设计负责人要确认接口、所有权、失败语义或风险取舍 |
| 验证 | 最小场景、前置条件、预期行为、所需证据和停止条件 |
| 关闭条件 | 设计修改、独立验证和负责人验收分别要留下什么记录 |
下一步路由
按发现进入对应阶段,并带上尚未解决的约束:
| 交接方向 | 需要传递的内容 |
|---|---|
| 需求到设计复核 | 范围、约束、安全目标、非功能目标和待决策项 |
| 设计复核到实现 | TD 发现、已确认的决定、不变量、失败状态和验证夹具 |
| 实现到测试或运维 | 版本、修改后的边界、运行证据、日志、指标和剩余风险 |
复核只准备可执行的下一步,不会单独批准架构。
怎样准备更好的输入
最小输入包括:
- ADR、架构图、组件职责、数据流、接口契约和设计修订;
- 目标版本、环境、流量、数据分类、依赖和兼容范围;
- 失败、重试、超时、恢复、降级、权限和可观测性约束;
- 已有测试想法、指标、夹具、负责人和安全验证环境;
- 明确不提供的代码、生产数据或探针,以及需要人工决策的内容。
输出至少包括:
- 目标、版本、范围内外和六类输入审计;
- 十个设计维度的覆盖矩阵;
- 按 P0→P3 排序的 TD-## 发现;
- 实施前阻塞、缺口动作、责任角色、决策问题和最小验证;
- 事实、推断、候选建议、人工决策、假设和剩余风险。
只给一张架构图时,Skill 可以指出“看不到什么”;它不能从图名推断吞吐、SLO、故障恢复或安全边界。
和其他 Skill 怎么配合
- 安全需求复核: https://inaodeng.com/zh-cn/qaskills/security-requirement-review/
- 可观测性设计复核: https://inaodeng.com/zh-cn/qaskills/observability-design-review/
- 数据库设计质量复核: https://inaodeng.com/zh-cn/qaskills/database-design-quality-review/
- API 安全测试: https://inaodeng.com/zh-cn/qaskills/api-security-testing/
容易踩的坑
- 只检查架构图是否存在,不检查边界、失败和恢复路径。
- 把“支持高并发”“具备监控”当成已经定义的验证标准。
- 根据组件名称补造容量、延迟、SLA、责任人或根因。
- 把建议写成已批准架构,把设计复核写成构建或运行通过。
- 只给风险,不给证据、责任角色、关闭条件和验证动作。
安装与调用
npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh --skill technical-design-quality-review
请使用 technical-design-quality-review Skill。
任务:在实现前复核一个多租户发票导出服务。
输入材料:[ADR、数据流、API 契约、租户边界、存储方案、威胁说明和可观测性计划]
范围:[导出任务、对象存储、客户下载]
限制:[没有提供代码或生产探针]
先完成六类输入审计,再按设计覆盖矩阵输出 TD-##。分开设计事实、证据推断、候选建议和 Human 决策,并为高优先级发现给出关闭条件和验证方式。
提供接口、数据流、权限矩阵和验证环境后,复核结果可以逐项关联到设计决策;缺少这些输入时,应保留缺口和待确认项,不能只留下泛化建议。
实践建议
- 优先处理影响大的设计缺口,并请求足以解决问题的最小证据或安全检查。
- 分开记录设计事实、证据支持的推断、建议和人工决策;不要把假设写成结论。
常见问题
这个 Skill 会复核代码吗?
只有用户明确提供并纳入范围的代码才能作为证据;没有提供的实现不能被声称已经复核。
设计复核没有发现缺口,就代表构建会通过吗?
不代表。设计复核可以准备验证,但构建、兼容性、安全、性能和恢复仍需要独立执行证据。
架构师希望 AI 直接选一个方案怎么办?
可以输出候选方案、依据、风险和待决策问题;最终的架构取舍和风险接受仍由人工确认。
参考
源 Skill 与执行契约
-
技术设计质量评审提示词(执行契约): https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/technical-design-quality-review/prompts/technical-design-quality-review.md
-
技术设计质量评审 Skill 源目录(定义、智能体适配和评测资产): https://github.com/naodeng/awesome-qa-skills/tree/main/skills/zh/testing-types/technical-design-quality-review
设计文档存在只能证明文档存在。没有身份、时间、环境、输入和原始结果的执行结论,只能标记为 unverified、unexecuted 或 unassessed。
延伸阅读
- 技术设计质量评审详情页: https://inaodeng.com/zh-cn/qaskills/technical-design-quality-review/
- Awesome QA Skills 项目: https://github.com/naodeng/awesome-qa-skills
更多参考
- 个人网站链接:https://inaodeng.com/zh-cn/
- 微信公众号:软件测试同学
- AI 生成测试检测项目:https://github.com/AI-Native-QA-Lab/ai-test-auditor
- DeepSeek QA 工作台项目:https://github.com/naodeng/dsh-qa
- 更多 AI 测试技能:https://inaodeng.com/zh-cn/qaskills/
- 更多测试百科:https://inaodeng.com/zh-cn/wiki/
- 更多 AI 百科:https://inaodeng.com/zh-cn/AIWiki/