编程开发 编辑复核
复杂代码块注释草稿
只为真正需要上下文的算法、兼容性或安全边界写短注释，避免把代码翻译成冗余旁白。
PROMPT WORKBENCH
复制后替换变量
保留结构，先填真实信息，再把结果交给模型运行。
你是一名可维护性审查工程师。请只给难以从代码本身推导出的原因、约束和风险写注释，能通过重命名或拆函数解决的问题不要堆注释。
先区分已知事实、合理假设和待核验信息；没有依据的内容写“待验证”，不要为了完整而猜测。
请按以下结构输出：
1. 识别复杂逻辑背后的业务、协议、性能或安全约束
2. 生成短注释并说明放置位置
3. 指出应该通过代码结构而不是注释解决的重复或误导
4. 列出未来变更时需要同步的测试和文档
输入变量：
- 代码片段（{{code}}）：提供最小且脱敏的复杂代码。
- 上下文（{{context}}）：说明调用方、历史兼容和不能改变的行为。
- 风险（{{risk}}）：描述代码容易被误改的地方。
- 注释规范（{{style}}）：说明项目注释长度和语言。
约束：保留用户的真实语气和业务边界；把事实、推断与建议分开；涉及日期、价格、版本、法规或安全的内容写明来源和采集时间。HOW TO USE
使用说明
- 注释写完回看代码是否已经足够清楚，能删就删。
- 把关键约束补到测试或 ADR，避免只存在于注释。
WHEN IT FITS
适用判断
适合这些情况
- 某段代码逻辑绕，接手的人容易看错。
- 实现里有非显而易见的取舍，需要留下缘由。
- 你能提供完整的代码上下文。
换个做法更好
- 代码本身可以改清楚：改名字和拆函数比加注释更有效。
- 你要写的是对外文档：用《API 文档与示例请求生成》。
- 代码逻辑直白：加注释只是噪音。
FAILURE MODES
常见翻车与修正
- 注释把代码翻译成中文，读注释和读代码信息量一样。
要求注释只写代码看不出来的东西：为什么这么做、有什么约束、试过哪些不行的方案。
- 注释描述的行为和代码实际做的不一致。
模型可能误解了逻辑。要求每条注释标注它依据的是哪几行，方便你逐条核对。
- 每个函数每一行都加了注释。
在输入里限定注释数量，要求只标注真正需要解释的位置，并说明为什么这几处需要。
ACCEPTANCE
怎么判断输出合格
- 注释写的是原因和约束，不是代码复述。
- 每条注释都能对应到具体代码行，便于核对。
- 数量克制，只覆盖真正难懂的部分。
- 没有描述与代码行为不符的内容。
SAFETY BOUNDARY
使用边界
- 模型会把代码做了什么复述一遍当注释，真正需要写的是为什么这么做；复述型注释删掉。
- 注释里不要写入内部系统地址、账号和未公开的业务规则细节。