Stats
Actions
Tags
From team-standards
Provides coding style rules for bug fixes and integration: no history comments, no deprecated markers, direct overwrite. Auto-activated for fix/alignment edits.
How this skill is triggered — by the user, by Claude, or both
Slash command
/team-standards:bugfix-coding-styleThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **本 skill 自 v1.17.0 起方向反转：禁止把变更历史写进代码内部，禁止保留注释式旧代码。** 之前版本要求的 `[DEPRECATED YYYY-MM-DD]` / `[ADDED YYYY-MM-DD]` / 注释保留旧代码段全部废止。变更历史默认归 git log / commit message 管；bug 文档 / 设计文档只沉淀长期业务事实，不重复源码变更流水。
本 skill 自 v1.17.0 起方向反转：禁止把变更历史写进代码内部，禁止保留注释式旧代码。 之前版本要求的
[DEPRECATED YYYY-MM-DD]/[ADDED YYYY-MM-DD]/ 注释保留旧代码段全部废止。变更历史默认归 git log / commit message 管；bug 文档 / 设计文档只沉淀长期业务事实，不重复源码变更流水。
代码只描述当前正确逻辑，只保留对当下读者有意义的"WHY 注释"，禁止任何形式的变更历史叙事和函数头大段说明。 修改/替换/删除已有代码时直接覆盖，不留旧代码副本；新增对齐补丁时直接添加，不打补丁标记。过气逻辑、曾经的错误实现、某次变更原因、日期、PR/Issue 编号都属于 Git 历史，不属于源码。
| 类型 | 处理方式 |
|---|---|
| 修改/替换/删除已有代码 | 直接改写。不要 // 注释保留旧实现，不要写 [DEPRECATED]/[BUGFIX]/[FIXED YYYY-MM-DD] 等标记。 |
| 新增之前缺漏的对齐代码 | 直接添加。不要写 [ADDED YYYY-MM-DD]、不要写"对齐云端 XX 第 N 行"作为头注释，不要引用调整流水编号。 |
| 方法 / 类 doc comment | 只写当前职责、输入输出语义、不变式和容易误用的业务约束；不要把设计文档、bug 复盘、实现步骤流水堆到函数头。 |
| 必要的 WHY 注释 | 复杂逻辑的解释优先贴近对应代码块，用 1-2 行说明"为什么这样做"；只有跨整个方法的不变式才上提到方法 / 类 doc comment。 |
| 旧规则的初衷 | 实际产生的问题 |
|---|---|
| 留对照证据方便快速回滚 | git 本身就是回滚锚点，注释段反而和实际代码脱节、容易腐烂 |
| code review 看"改了什么、为什么" | review 看 PR diff 即可；commit message + bug 文档讲"为什么"更准确 |
| 跨端联调时直接指原代码作凭据 | 联调结论应沉淀到 bug 文档 / 设计文档，不应靠源码注释当临时白板 |
| 让代码"留下故事" | 故事归 git history。源码每多一行噪声注释，下个读者多一份认知负担 |
coding-standards-common §5.4 + §5.4.1)本 skill 不再独立定义注释红线。 跨语言通用 + bug 修复 / 联调 / 删冗余 / 重构 / 新功能 / 任何源码改动的注释禁令以
coding-standards-common§5.4 列项清单 + §5.4.1 字面反例对照表为唯一来源。触发顺序里
coding-standards-common早就先于bugfix-coding-style必走(见CLAUDE.md「核心调用顺序」§11 → §10),不会漏读;以后新增注释反模式只改 common 一处,避免双地维护漂移。本 skill 只保留下方 bug 修复期独有的应用层指引:历史背景(为什么 v1.17 方向反转)、推荐写法 dart 代码示例、摆放位置示例、适用范围矩阵、遇到存量
[DEPRECATED]/[ADDED]注释顺手清理的边界、与其他 skill 的协作、红色警告对照表。
允许且鼓励的注释形式：
| 类型 | 例子 | 摆放位置 |
|---|---|---|
| 方法/类承担的隐藏不变式 | "字段映射约定：POS 回调 outTradeNO 对应本地 out_trade_no 而非 transaction_no" | 方法/类 doc comment |
| 当前行为摘要 | "按用户选择的 refundMethods 将可退池分摊到原支付流水" | 方法 doc comment，最多 1-3 行 |
| 与外部系统的字段语义对齐 | "对齐云端 PayV1ServiceImpl#refundOrderNotifyForKpayOffline" | 类 doc comment（不带日期/版本） |
| 单行非显然的业务约束 | // 加 ±0.005 浮点容差是为了让前端 toFixed(2) 与 Rust BigDecimal 的尾差不报错 | 该行上方 |
| 对易误解参数的语义说明 | /// [businessDate] 营业日（不一定等于 createTime 的日期） | 参数 doc tag |
判断准绳：删掉这条注释，下一个改这段代码的人会不会犯错？ 会则保留，不会则删。
旧规则的 A 类（DEPRECATED）/ B 类（ADDED）已废止。不论是修改还是新增，写法都一样：直接改、不留痕迹。需要解释 WHY 时，按上节"推荐写法"上提到 doc comment。
函数 / 类 doc comment 只承担当前读者理解入口所必需的信息：
以下内容不要写进函数头注释：
[REWRITTEN]、日期、版本号、PR/Issue、"旧实现 / 新实现"如果代码块确实复杂，把说明放到对应代码块上方，保持短句：
/// 按用户选择的退款方式，将可退池分摊到原支付流水。
///
/// 分摊结果保留原流水金额，用于后续按流水维度判断撤销资格。
Future<List<RefundTransactionAllocation>> allocateByRefundMethods(...) async {
final pool = await _eligibilityDao.queryRefundableTxPool(originalOrderId);
// 非现金退款只能消耗同 wireType 的原流水，避免跨渠道占用可退额度。
for (final method in nonCashMethods) {
_allocateSameWireType(pool, method);
}
// 现金退款先消耗现金池；外溢规则未启用时，剩余金额只记录日志不落库。
_allocateCashPool(pool, cashMethod);
}
/// 按 POS 回调的 outTradeNO 反查退款流水。
///
/// 字段映射约定：POS 回调字段 outTradeNO 对应本地 `order_transaction.out_trade_no`，
/// **不是** `transaction_no`（那是本地系统流水号 RTX/T...）。退款场景下两者必然不同。
///
/// 命中行须满足 `refund_flag=1`，确保只匹配退款流水而非原支付流水。
Future<RefundCallbackLookupResult?> lookupByOutTradeNo(String outTradeNo) async {
// Step 1: 退款流水
final transaction = await (db.select(db.orderTransaction)
..where((t) =>
t.outTradeNo.equals(outTradeNo) &
t.refundFlag.equals(1) &
t.deleted.equals(0))
..limit(1))
.getSingleOrNull();
// ...
}
对照反例：
// ❌ 禁止：变更日志、deprecated 旧代码、引用文档
//
// [BUGFIX 2026-04-30] 旧实现用 transaction_no 反查，原支付场景因 transaction_no
// 与 out_trade_no 同值（均为 T...）而凑巧命中；退款场景导致全部反查未命中。
// 详见 v6 调整流水 2026-04-30 条目。
// final transaction = await (db.select(db.orderTransaction)
// ..where((t) => t.transactionNo.equals(outTradeNo) & t.deleted.equals(0))
// ..limit(1))
// .getSingleOrNull();
final transaction = await ...; // 新代码
| 场景 | 是否适用 | 处理方式 |
|---|---|---|
| 联调期 bug 修复 | ✅ | 直接改写，逻辑说明上提方法 doc |
| 删除明确无效的 if/else 分支 | ✅ | 直接删，不留注释 |
| 方法体内逻辑修正（不改签名） | ✅ | 直接改；复杂代码块只在局部加短 WHY 注释 |
| 补上原本缺漏的对齐代码 | ✅ | 直接加，无需 ADDED 标记 |
| 新功能开发 | ✅ | 同样适用本规范 |
| 纯重命名 / IDE refactor | ✅ | 直接改 |
| 测试代码 / 配置文件 | ✅ | 直接改 |
本 skill 现在适用于所有源码改动，不再局限于轻量修订流水。
旧版本（v1.16 及以前）按规范留下的标记注释，编辑同一段代码时可顺手清理：
[DEPRECATED] + 注释保留的旧代码）：删除整段（头注释 + 旧代码）[ADDED] 头注释 + 实际代码）：删除头注释，保留代码本身这与旧版"AI 永不主动删除带标记注释"规则相反 —— 因为新规范本身就要求源码内不留这类注释。但仅限于"刚好在改这段代码"时顺手做，不必专开 PR 全仓清理。
| Skill | 关系 |
|---|---|
design-doc-required 第四·五步 | 走轻量修订流水分支时，代码改动遵循本 skill（直接改，不留变更日志） |
coding-violation-log | 用户若纠正本 skill 的执行（如又写了 BUGFIX 标记），由 coding-violation-log 登记 |
git-commit-standards | 变更原因写进 commit message body（中文 body），不入源码 |
bug-doc-required | bug 文档保留完整根因/修复历史；源码不重复这些信息 |
| 想法 | 正确处理 |
|---|---|
| "删了改不回去" | git revert 一条命令的事；源码里堆 deprecated 注释才是不可靠的回滚机制 |
| "Reviewer 看不懂为什么改" | 写在 commit message body / PR description / bug 文档里 |
| "我加了 [ADDED 日期] 显得有交代" | 是噪声不是交代；把对齐依据上提到方法 doc 的"对齐云端"段（不带日期） |
| "这段代码以前 bug 过，警示后人" | 加测试用例覆盖、写进 bug 文档；不在源码注释里复述故事 |
| "TODO 想标个日期方便回头查" | 别。开 issue / 任务卡，源码里只留"为什么这里需要 TODO"的内容（且更应避免） |
| "用户没说要清理，那就保留旧 DEPRECATED" | 错。本 skill v1.17 起规则反转，遇到就可以顺手清（限改同一段代码时） |
| "函数上写一大段，后面的人就不用翻文档了" | 错。函数头只写当前行为和必要约束；设计背景、旧实现问题、未来计划归文档和 Git 历史 |
npx claudepluginhub exception-coder/team-standards --plugin team-standardsProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.