From team-standards
Defines 7 universal coding standards (naming, function atomicity, layering, no magic values, comments) for any source code language. Auto-triggers on writing or reviewing code.
How this skill is triggered — by the user, by Claude, or both
Slash command
/team-standards:coding-standards-commonThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> 适用于一切源码语言。语言专属规则(如 `java-coding-standards` 的阿里黄山版独占条款、`dart-coding-standards` 的 Effective Dart·dartdoc 独占条款、`korepos-backend-service` 的 Flutter backend 规则)在此基础上叠加,不重复。
适用于一切源码语言。语言专属规则(如
java-coding-standards的阿里黄山版独占条款、dart-coding-standards的 Effective Dart·dartdoc 独占条款、korepos-backend-service的 Flutter backend 规则)在此基础上叠加,不重复。触发链路:
coding-standards-common(通用) →{language}-coding-standards(语言专属)。任何源码 Edit/Write 前先满足本 skill 的 7 条铁律,再走语言专属。
MAX_RETRY_COUNTUpperCamelCase;方法/变量名 lowerCamelCase(语言惯例允许时)is_ / get_ 前缀(JSON / POJO 反序列化兼容性问题)XxxImpl;数据/传输/展示对象用 XxxDO/DTO/VO,禁混用get,获取列表 list,统计 count,插入 save/insert,删除 remove/delete,修改 update_xxxStep 私有方法,主方法只做编排 + 事务 + 日志§2 的 80 行硬阈值从代码量约束;本条从业务语义约束。两者叠加:先按业务场景拆,再看每个分支是否还需要按代码量拆。1-100 期扩展既有 service 时最常违反——加新业务类型时阻力最小的方式是"在已有方法里 +一个 else if",但这会让两种业务定位的逻辑黏死,未来变更相互波及、无法独立测试。
_handleTypeA() / _handleTypeB() 私有方法,主方法只做分流派发architecture-ddd-lite-fullstack 「函数级业务场景分流」节common/services/ / common/backend_infra/services/ 等),不要塞进同一 public 方法用 if-else 区分orchestrator 或原子能力层common/ 或等价的原子能力目录,禁复制粘贴0 / 1 / -1、true / false、空串 ""、空集合、单元测试断言字面量state == 3、item_type=1)MAX_RETRY = 3)用 const 并写一行 WHY 注释说明阈值依据== / equals;金额类用 BigDecimal 或差值 ≤ 容差(POS 场景常用 ±0.005)立场:类、方法、核心代码块都必须写注释,但每档都有「简要」上限。优先讲 WHY、当前职责、约束;不允许把变更历史、设计史、实现步骤流水写进源码。
注释放置原则(总纲):注释主要落在声明位置——类 / 字段 / 方法头。函数体内除 §5.3 六类核心块外不写注释;逻辑的可读性靠拆函数 + 命名表达,不靠行内注释堆砌。函数体里冒出大段行内注释,基本等于"该拆的函数没拆""命名没起好"——先改代码结构,而不是补注释。每一档都遵循"一句话讲清"的最短表达,多余的删。
反复违规的 AI 行为:私有方法 / 内部代码块上方堆 5-12 行 dartdoc / 行内 WHY 注释解释"前端契约演变 / 旧实现 vs 新实现 / 上下游字段口径 / 不走本分支也不受影响"。先用这 4 问自检,有 1 项答错就回去删:
git-commit-standards 控制(默认中文 body),设计 / bug / 知识图谱文档语言由对应 doc skill 控制。判断准绳:不要把"英文是行业默认"当成默认,不要把"中文更亲切"当成默认,也不要把"原文件是英文"当成默认。沟通语言就是默认——读你代码的下一个人多半就是这次会话里的协作者。
写清:
只保留「当前职责 + 最容易误改的不变量」。算法主干 / 数据源选型 / 复合场景推演 / 长篇契约说明不进类注释——移到 design doc / 业务文档。把类头写成一篇几十行的小设计文档是最常见的超标形态,1-3 行讲不下的,说明它属于文档而不是源码。
写清(只在不自解释时写):
// 金额,单位分 / // 状态机当前态,见 OrderState)amount: 金额 = 废话,删)userId / createTime / name)省略注释,不要为凑注释而注释payAmount / tipAmount 口径,字段就别再逐个复述)写清:
只对「原子能力方法」和「领域服务 / focused service 的公开类」可写「职责 / 不负责」契约清单——不负责 那部分正是 §5.1 要保留的「最容易误改的边界」,对人和 AI(知识图谱沉淀)都有效:
/// 原子能力:登记退款终态
///
/// 职责:1. 更新退款状态 2. 写退款流水 3. 发本地事件
/// 不负责:1. 调支付渠道 2. 校验退款金额 3. 更新订单支付状态
Future<void> registerRefundSuccess(RefundOrder order) async {}
硬约束(否则退化成 §5.1 禁止的「类注释 = 小设计文档」):
以下场景必加行内注释:
// 评分阈值:>=70 视为通过)// 用 ConcurrentHashMap 因多线程并发)// 最大修正次数,超过不再重试)// 向量库不可用时降级为纯 LLM 分析)// TODO(zhangkai): 等 v1.22 接入新协议后删除)本节是注释禁令的唯一规则源。bug 修复 / 联调 / 删冗余 / 重构 / 新功能 / 任何源码 Edit/Write 都遵循同一份红线,
bugfix-coding-style不再重复定义,只承担"bug 修复期推荐写法 + 旧标记顺手清理"的应用层指引。
[BUGFIX] / [DEPRECATED] / [ADDED] / [REWRITTEN] / [MODIFIED] / [FIX] / [FIXED] / 日期标记 / 版本号标记 / PR 号 / Issue 号 / Ticket 号 / 内部流水号引用(如 // 详见 v6 调整流水 2026-04-25 条目)→ 进 git commit body / bug doc / design doc// ===== [ADDED 2026-04-28] 校验链路 + 分摊编排私有方法 ===== / // --- xxx --- 风格的分节标题带日期)→ 全删,文件结构用方法分组 + 类层级表达,不用注释画分割线getUser: 获取用户)TODO(负责人): 原因:负责人必填(问责到人,不是甩锅)、原因必填、禁止带日期。反例:无原因 / 无负责人的裸 // TODO(噪声);带日期的 // TODO(zhangkai 2026-04): ...(日期归 VCS / 任务系统)。能开任务的优先开任务,而不是把 TODO 长期留在源码-- 注释(drift customSelect / JDBC / MyBatis 拼接 SQL / 任何字符串字面量里的 SQL):SQL 经常被复制调试、拼接、压缩、日志输出,内嵌 -- 是噪声,还让 DAO 读起来像"SQL 文档"。口径说明放到 customSelect(或等价调用)之前的宿主语言注释(Dart ///·// / Java //),且遵守行内 WHY ≤1 行。注:check-comment-density.js 会先剥离字符串字面量再判定,抓不到 SQL 串里的 --,这条靠本规则 + 评审 + comment-cleanup注释密度是信号,不是达标项:单文件注释占比畸高(如 >40%)、或连续注释块超过 6 行,基本等于"该拆的函数没拆 / 该迁的背景没迁"。降密度靠拆函数 + 命名自解释 + 把复杂背景迁到 design doc,不靠继续堆注释。
check-comment-density.js只机械抓连续块,占比畸高靠本条 + 评审判断。
列项是抽象规则,字面表是 AI 训练数据里最常学到的反模式具象样本。看到字面就该回避,不要让"规则我懂但具体代码我不确定"成为豁免理由。
| 反例字面 | 原因 |
|---|---|
// [BUGFIX 2026-04-30] 旧实现用 transaction_no 反查... | 变更日期 / 原因属于 git log,不属于代码 |
// [DEPRECATED 2026-04-25] 这段以前是 X,现在改成 Y | 完全属于 commit message |
// [ADDED 2026-04-25] 对齐云端 RefundServiceImpl#handleX(L1063-1070) | 对齐依据应放方法 doc comment 的"对齐云端"段(不带日期),或写进 design / bug 文档 |
// [REWRITTEN 2026-04-28] 按 xxx 重写... 后接旧实现问题 / 新实现步骤 / 未来版本计划 | 变更流水 + 设计文档摘要,应写进 commit body / 设计文档;源码只保留当前行为和必要 WHY |
大段被 // 注释的旧代码 | 增加噪声、容易腐烂、git 已经留底 |
// ===== [ADDED 2026-04-28] 校验链路 + 分摊编排私有方法 ===== 风格分节标题 | section divider 注释 = 文件结构没拆好;用方法分组 + 类层级表达,不用画注释分割线,更不要在分割线里夹日期 / 版本 |
// 详见 v6 调整流水 2026-04-25 条目 | 引用易失效;让读者跳到外部文档才能理解的代码不合格 |
// PR #1234 / Issue #56 / Linear ticket KP-789 | 同上 |
// TODO(zhangkai 2026-04): 这里以后再优化 | 日期是噪声(归 VCS / 任务系统),且无具体原因。正确:// TODO(zhangkai): 等 v1.22 协议接入后删——负责人 + 原因、不带日期;更应开任务 |
// 查询用户 / // 判断为空 / // 遍历集合 / // 设置状态(紧贴下一行同义代码) | 复述代码 what,零信息量。删——靠命名自解释,要写就写 why(// 异步退款需等回调,此处先返回) |
| 函数头连续十几行说明"旧实现忽略 A/B/C、新实现第 1/2/3 步、理论上一定完成、v1.1 计划" | 函数头注释过载。当前职责写在 doc comment,步骤说明拆到对应代码块附近 |
私有方法 _validateXxx 上方写 12 行 dartdoc 讲"前端契约 / 早期版本曾要求 X / 现已统一为 Y / 再加会双计" | 私有方法不是公开接口,契约演变史 ≠ 当前职责。1-2 行讲"当前校验什么"即可;契约迁移属于 commit body / bug doc。函数名 _validateMethodsAmountSum 已自解释,旧契约描述全删 |
| 代码块上方堆 5 行行内注释讲"cancel 桥接路径 / 联台按 scaleRatio 缩 / 否则与 income_refund_service_fee_amount 口径不一致 / UI 部分退款入口不走本分支不受影响" | §5.3 行内注释硬阈值 1 行。"另一分支怎么走 / 不走本分支也不受影响" = 旁路场景影响面叙事,归反向索引 / design doc。压成 1 行 WHY 或彻底删 |
resolveOrderBusinessState 方法头把分支条件、状态码映射、fallback 完整复述一遍(下面代码本身直观) | 复述代码 = 噪声。压成 1-2 行讲算法意图:"按云端算法据 payType/orderState/pickUpState 推导业务状态,未知值兜底待下单",不逐条翻译代码 |
RefundTipPolicyService 类头 60+ 行写关键契约 / 算法主干 / 数据源选型 / 复合场景推演 | 类注释写成了小设计文档(§5.1)。类头只留当前职责 + 最易误改的不变量,算法主干 / 选型 / 场景推演进 design doc |
CancelRefundPlanner 注释"新增订单类型时第 1/2/3 步怎么做" | 扩展 / 维护指南 ≠ 当前代码契约,进维护文档 / design doc,源码删 |
RefundTxSnapshot 类头已解释 payAmount/tipAmount,字段上再逐个解释一遍 | 类头与字段重复(§5.1.5)。类头讲整体口径,字段只补非自解释点,同一信息不写两遍 |
| 函数体内连续多段讲"反结 / 金额维度 / 失败信号 / retry 冲正"(占函数大半篇幅) | 函数体大段流水账违反 §5 放置原则 + §5.3。有价值的 WHY 压成少量核心规则行内注释,复杂背景移 design doc / 业务文档 |
customSelect 的 SQL 字符串里堆 7 行 -- tip_amount 在联合支付时.../-- 复制写到 orders 上.../-- 与 bill.tip_amount 同口径...(refund_products_dao.dart) | 内嵌 SQL 不写 -- 注释。压成 1 行放到 customSelect 之前的 Dart 注释:// 联单 tip 是整桌快照,取 MAX 避免兄弟桌重复累加,SQL 串本身保持干净 |
判定准绳:删掉这条注释,下一个改这段代码的人会不会犯错?会则保留(短句),不会则删。
机械兜底(v1.29 起):
hooks/check-comment-density.js(PreToolUse Write/Edit/MultiEdit,默认 warn)扫本次新增内容的注释,命中变更标记 / 日期 / 工单号 / 带元信息分节线 / 版本流水措辞 + 超长注释块时 stderr 提示。hook 只抓客观无歧义项,prose 式实现史 / 私有方法契约史仍靠本节规则 + 评审判断,不能因"hook 没报"就放行。TEAM_STANDARDS_COMMENT_HOOK=block升级硬阻断、=off 关闭。
立场:改了逻辑就要校对周边注释。过期注释比没有注释更糟——它会主动误导下一个读你代码的人;历史版本说明 / 废话注释会污染文件、消耗后续阅读者的注意力。改到哪,清到哪。
发现以下任意形态,改到该方法 / 代码块时一并删干净,不留痕:
// [BUGFIX] xxx、// [DEPRECATED]、// [ADDED v1.2]、// 2024-03-15 修改、// PR#1234 调整// 原本用 HashMap,后改为 ConcurrentHashMap、// 这里之前有个 bug,现在修了、// v1.0 写法,v2.0 重构// 兼容老版本 xxx(老版本已下线)、// 为了 v1.x 用户保留(已不需要)// 暂时这么写、// 待优化(没有 owner / 没有触发条件,本质是垃圾 TODO)// / /* */ 包起来的死代码,直接删这些信息属于 git commit body / design doc / bug doc,不属于源码。源码只回答"现在是什么、为什么这么写"。
// getUser: 获取用户、/** 用户ID */ Long userId(字段名已自解释)i++; // i 加 1、return null; // 返回 null// xxx、// TODO(无内容)、/** */ 空 doc 块bugfix-coding-style skill 完全对齐:bug 修复 PR 里禁止新增任何"修了什么 bug / 之前怎么错的"的源码注释,要写进 commit message 或 bug doc类 1–3 行,方法 1–2 行,代码块 1 行。写不下就说明你想塞实现细节,那部分应该进文档而不是源码。
catch 必须处理或显式往上抛,禁空 catche.getMessage()(等价于把堆栈丢了)try-catch 做流程控制finally 中禁 return(会吞掉 try 的返回值或异常)catch 块必须手动回滚事务common/services/ / common/backend_infra/services/ 等)| 通用 skill(本文件) | 语言 / 框架专属 skill |
|---|---|
| 命名表意 / 函数原子 / 层次分明 / 零魔法值 / 注释三档 / 异常不静默 / 删冗余 | java-coding-standards: 包装类比较、SimpleDateFormat、SLF4J 占位符、HashMap 容量、BigDecimal 比较、JDK8+ DateTimeFormatter、SQL 列名规范、索引规则等 Java / 数据库独占条款 |
| 同上 | korepos-backend-service: backend 目录结构、BackendInfra 边界、一接口一 service、Service 禁裸 SQL、跨 feature 业务原子能力、长方法拆 step、DB 字段值枚举绑定等 Flutter backend 独占条款 |
| 同上 | bugfix-coding-style: 禁源码内变更日志 / 函数头不堆复盘 / 复杂逻辑就近 WHY(本 skill §5.4 与之完全对齐) |
| 同上 | arch-lint: Flutter 5 类架构违规自动检测 |
触发顺序:任何源码 Edit/Write 前,先满足本 skill 的 7 条铁律 → 再走语言/框架专属 skill 的独占条款 → 最后由 coding-violation-log 在用户纠错时登记差异。
写代码前 / 提交前过一遍以下 7 项,有 ❌ 必须改:
data / info / temp?Provides 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.
npx claudepluginhub exception-coder/team-standards --plugin team-standards