重要任务使用以下六段结构。尖括号内容必须替换为项目实际值;不知道时写明“需要先调查”,不要保留含糊占位内容后直接执行。
目标:
<要改变的用户行为或系统行为>
上下文:
<权威需求、入口、错误、文件、日志、设计或相邻实现>
约束:
<必须保留的 API、数据、架构、安全、性能和依赖要求>
非目标:
<本次明确不处理的相邻问题>
完成条件:
<可观察行为、测试、检查、兼容性和性能阈值>
输出要求:
先调查并说明依据;复杂或有歧义时先给计划。完成后报告修改摘要、实际验证结果、未验证项和剩余风险。
不要把实现步骤写得过死,除非过程本身是安全或合规要求。应当控制结果、边界和证据,同时允许 AI 编程助手根据代码库现状选择最小实现。
目标:在 <产品区域> 增加 <具体行为>,服务于 <用户或调用方>。
上下文:先阅读 <需求/设计>、<入口模块>、相邻功能和现有测试。追踪从输入到状态变化及输出的完整路径。
约束:保持 <公共 API/数据/兼容性>;延续现有架构和组件模式;未经批准不增加依赖、不修改 Schema、不重构无关模块。
非目标:不处理 <相邻功能>,不改变 <既有行为>。
完成条件:
- 正常、空、错误和边界状态符合需求;
- 增加与风险相匹配的单元、集成、契约或端到端测试;
- 运行 <项目实际 lint/typecheck/test/build 命令>;
- 对用户界面完成 <浏览器/设备/可访问性> 验证;
- 公共契约、性能和安全影响已说明。
输出要求:修改前先报告调查结果和计划。完成后列出实际命令及结果、未运行的检查、兼容性影响和剩余风险。
目标:修复 <可观察错误>。
已知证据:<错误消息、复现步骤、日志、失败请求或问题编号>。不要假设报错位置就是根因。
调查要求:沿入口、调用链、状态变化和错误处理追踪根因;比较正常场景;区分由代码证明的事实和假设。
约束:保持 <公共行为>;实施最小修复;不通过吞异常、放宽校验、扩大 mock、删除断言或跳过测试掩盖问题。
完成条件:
1. 添加一个修复前稳定失败的回归测试;
2. 运行并记录预期失败;
3. 实施修复后该测试通过;
4. 运行相邻回归测试和 <项目检查命令>;
5. 验证错误、重试、并发或边界路径;
6. 说明为什么修复解决根因而不是症状。
如无法稳定复现,停止修改并报告缺失证据、建议的诊断信息和下一步实验。
目标:改善 <模块> 的 <可度量问题,例如重复、复杂度、依赖方向>,保持外部行为不变。
上下文:先列出公共接口、调用方、状态与现有测试,说明重构动机和最小边界。
约束:不增加新功能;不改变 API、持久化格式、错误语义和可观察副作用;不顺手重构相邻模块;每一步保持可构建、可测试。
计划要求:把重构拆成可独立 Review 的步骤,先补行为刻画测试,再移动或简化实现。若发现必须改变行为,停止并单独提出变更。
完成条件:
- 重构前后行为测试一致;
- 目标问题有明确改善证据;
- lint、类型检查、测试和构建通过;
- 最终 diff 不含格式化或重命名噪声;
- 报告仍存在的结构问题,不为未发生的需求创建抽象。
目标:为 <行为/风险> 补充有缺陷发现能力的测试,而不是提高数字覆盖率本身。
先调查:实现的不变量、公共行为、失败路径、已有测试层级和测试基础设施。
测试设计:优先通过公共接口观察行为;覆盖一个正常场景、关键边界和真实失败模式。仅在外部慢服务、时间、随机性或不可控系统边界使用 test double。
禁止:复制实现算法到测试;只断言函数被调用;过度 mock 内部细节;无理由更新大批快照;依赖真实生产服务或不稳定等待。
完成条件:
- 证明测试在实现被破坏时会失败;
- 测试可重复、相互隔离并有清晰失败信息;
- 运行目标测试和相邻测试;
- 说明选择该测试层级的理由及尚未覆盖的风险。
目标:把 <场景> 的 <延迟/吞吐/内存/CPU/包体积> 从 <基线> 改善到 <目标预算>。
上下文:使用 <Profile、Trace、查询计划、真实指标或 Benchmark> 定位瓶颈。没有测量证据前不要改代码。
约束:保持正确性、兼容性和可观察错误语义;不得用关闭校验、删除日志、无限缓存或降低数据一致性换取指标,除非明确批准。
完成条件:
- 使用代表性数据和固定环境记录优化前后结果;
- 添加或更新性能回归检查;
- 运行正确性测试;
- 报告测量方法、波动范围、资源取舍和最坏情况;
- 如果目标未达到,保留证据并说明下一瓶颈,不伪造成功结论。
对 <分支/commit/路径> 做安全审查。先建立信任边界、资产、攻击者能力、输入入口、身份与权限、敏感数据流和外部依赖。
重点检查:认证与授权、注入、路径/请求伪造、反序列化、Secrets、日志泄露、加密误用、依赖风险、竞态、资源耗尽和失败默认值。
每个发现必须给出:
- 严重度与依据;
- 文件和符号位置;
- 从攻击输入到影响的可达路径;
- 所需前置条件与受影响资产;
- 可验证的修复方向和建议测试。
区分已验证漏洞、合理怀疑和加固建议。不要为了增加发现数量而报告无可达路径的理论问题;不要自动修改生产凭据或安全策略。
审查当前分支相对 <基线分支> 的完整 diff,只报告会影响合并决策的具体问题。
按以下优先级检查:
1. 行为错误和遗漏边界;
2. API、Schema、数据和客户端兼容性;
3. 并发、事务、幂等、重试和资源生命周期;
4. 认证、授权、输入、Secrets 和隐私;
5. 性能退化与不可观测失败;
6. 缺失、无效或脆弱测试;
7. 无关修改和不必要复杂度。
每个发现包含严重度、文件位置、触发条件、具体影响、证据和最小修复方向。不要复述 diff,不报告纯个人风格偏好。若没有阻止合并的问题,明确说明“未发现问题”,并列出仍未覆盖的测试或环境风险。
Review 后不要立即盲目执行全部建议。先让 AI 编程助手或开发者逐项验证调用路径、运行条件和项目约定,再决定接受、调整或拒绝。