tdd-engineering

name	tdd-engineering
description	使用 TDD 和通用工程规范创建、修改、重构或评审代码。用户要求实现功能、修复 bug、补测试、重构代码、评审改动，或希望在前端、后端、脚本、工具和应用开发中遵循测试优先与工程质量标准时使用本 skill。

TDD Engineering

本 skill 用于在日常软件开发中采用 TDD 和通用工程规范。目标不是机械地要求所有代码都先写测试，而是在行为、风险和反馈成本之间做务实取舍：重要行为先用测试钉住，简单改动快速实现并验证。

基本工作流

1. 先阅读项目现有代码、测试、README、脚本、配置和约定。
2. 明确本次改动的目标行为、输入输出、边界条件、失败路径和不做范围。
3. 判断是否需要测试先行；需要时先写一个最小失败测试或复现用例。
4. 用最小实现让测试通过，避免顺手重构无关代码。
5. 在测试保护下整理命名、结构、重复逻辑、类型边界和错误处理。
6. 运行最小必要验证，并在回复中说明改动范围、验证结果和未覆盖风险。

轻量 TDD 规则

优先测试先行的场景：

• 新增业务行为、状态流、数据转换、权限判断或关键交互。
• 修复 bug，尤其是回归问题、边界条件和用户已观察到的问题。
• 重构公共模块、公共组件、公共工具函数或跨模块逻辑。
• 修改 API 契约、数据模型、错误处理、缓存策略或异步流程。

可以先实现再验证的场景：

• 纯文案、样式微调、无行为变化的布局修正。
• 删除死代码、调整导入顺序、轻量配置变更。
• 项目缺少测试基础，且建立测试环境会显著扩大任务范围。

测试应关注外部可观察行为，而不是私有实现细节。不要为了覆盖率测试内部状态、私有函数调用顺序或框架实现细节。能通过公共接口、用户交互、命令输出或可见结果验证时，不直接测试内部结构。

通用编程规范

• 保持改动小而集中；不把无关重构混入功能修改。
• 优先使用项目已有框架、组件、工具函数、错误处理方式和测试风格。
• 使用清晰命名表达领域含义，避免过度抽象和一次性“万能”封装。
• 让数据流、状态变化和副作用边界显式可读。
• 对异步、失败、空数据、权限不足、重复提交和外部依赖失败等路径给出明确处理。
• 保持类型、schema、接口契约和运行时校验一致。
• 只在代码意图不明显或约束容易被破坏时添加简短注释。
• 避免引入未经请求的新依赖；确需引入时说明原因和替代方案。

前端补充

• 用用户视角定义行为：能看到什么、能点击什么、输入后发生什么、错误如何展示。
• 组件测试优先验证交互、渲染结果、可访问名称、禁用态、加载态、空态和错误态。
• 端到端测试用于覆盖关键路径，例如登录、创建、编辑、删除、结算、搜索和权限分支。
• 不把测试写成对 DOM 结构、CSS 类名或组件私有状态的脆弱断言，除非项目已有稳定约定。
• UI 实现要同时考虑桌面和移动视口，确保文本不溢出、控件不重叠、键盘和屏幕阅读器可用。

后端补充

• 优先测试公共契约，例如 API、service、domain、repository 或命令处理器的可观察行为。
• 覆盖鉴权、校验、事务、幂等、错误码、边界数据、并发风险和外部依赖失败。
• 数据库改动要考虑迁移、回滚、兼容旧数据和线上数据体量。
• 使用 mock 或 fake 时，只隔离外部不稳定依赖，不让 mock 调用本身成为测试目标。
• API 改动要确认请求字段、响应结构、错误格式、分页、版本策略和兼容性。

评审清单

完成前检查：

• 行为是否有测试或明确的人工验证路径。
• 是否覆盖正常路径、关键边界和失败路径。
• 是否遵循项目现有架构、命名、样式和测试风格。
• 是否存在无关改动、过度抽象、重复逻辑或隐藏副作用。
• 是否影响性能、可访问性、响应式布局、安全或兼容性。
• 是否运行了相关测试、lint、类型检查或构建命令。

如果无法运行验证，明确说明原因，并给出应运行的具体命令。