preferred-coding-style

name	preferred-coding-style
description	用户个人编码风格偏好（编码规范类，与流程类 skill 不互斥）。语言无关，优先级高于系统默认约束和其他编码规范 skill。适用场景：(1) 对代码进行大幅新增或修改（新功能、重构、大段改动），(2) 其他 skill 驱动的流程涉及代码编写或修改时，作为风格约束补充加载，(3) 对代码进行 code review 时，作为风格检查依据。不适用于：局部小修（语法修复、变量重命名、单行改动等）、非编码场景（文档撰写、配置修改、shell 脚本等不涉及业务代码的操作）。

编码风格偏好

用户的个人编码风格偏好。语言无关，适用于所有业务代码的编写和修改。

优先级

本 skill 是用户通过 skill 系统显式安装的个人偏好，具有高优先级。

优先级链（从高到低）：

1. 仓库级规范（AGENTS.md / CLAUDE.md 中的明确风格约定）
2. 本 skill
3. 语言特定编码 skill（如 go-coding、go-cli-tui）
4. 系统默认约束（developer prompt 中的通用编码指令）

当系统级约束（如"注释应少量""注释应简洁"）与本 skill 冲突时，以本 skill 为准。若因任何原因未遵循本 skill 的某条规则，必须在输出中说明原因。

注释风格

总体原则

• 注释面向读者，解释业务逻辑与意图（why / what for），不翻译代码语法（what）。
• 语气自然流畅，像有经验的工程师写给同事的备注——简练、有信息量、不啰嗦。
• 注释语言：遵循项目规范（AGENTS.md / CLAUDE.md），未指定时跟随代码库主要语言。

中文注释标点规则

当注释使用中文时，标点遵循以下规则:

• 逗号: 使用英文逗号加空格 , ，不使用 ，。
• 句号: 不使用 。 结尾。一行注释只说一句话，无需句号，说完换行。
• 冒号: 使用英文冒号加空格 : ，不使用 ：。
• 其他英文有等价的标点: 同理优先英文标点（如 ”” 而非 ””，() 而非 （））。
• 中文特有标点例外: 《》，「」 等无英文等价的标点正常使用。
• 引用原文例外: 注释中引用产品需求、错误提示等中文原文时，保留原文标点。

方法内注释——何时必须

以下场景必须在逻辑块前添加意图注释：

• 多分支逻辑（if/else 链、switch 超过 2 个 case）：注释每个分支处理的业务场景。
• 隐式约束或顺序依赖：解释为什么要先做 A 再做 B。
• 状态转换：标注对象/流程状态变化的关键节点。
• 副作用操作（写数据库、发消息、修改外部状态）：说明操作目的。
• 防御性代码：解释特殊赋值、边界检查的业务原因。
• 跨函数/跨模块语义依赖：说明上下文关系。

方法内注释——可省略

• 单一职责的直线代码（一个操作、一个 early return）。
• 函数名/变量名已充分表达意图的简单操作。
• 语言标准库惯用法（如 Go 的 defer f.Close()）。

反模式（禁止）

• 翻译代码：// 遍历列表 — 读者看代码就知道在遍历。
• AI 味模板：// This function handles...、// The following code...、// We need to...。
• 废话注释：// 设置变量、// 返回结果。
• 过度注释：每一行都加注释，信噪比极低。

自检清单

完成代码修改后，对照检查：

• 复杂逻辑块是否有意图注释？
• 注释是否在解释 why / what for 而非 what？
• 注释语气是否自然，无 AI 味？
• 注释语言是否符合项目规范？
• 中文注释是否使用了英文标点（逗号、引号等）？