整洁代码

问题从哪来

用大模型改代码时，常见输出是：逐行注释、先写「首先我们导入…」的教程腔、为两行逻辑单独建 utils.ts、深层 if 嵌套，以及报错后长篇解释却不直接修。更麻烦的是，代理在任务收尾时跳过 lint、跑错角色的验证脚本，或看到脚本输出就擅自改代码而不先和用户对齐。

这类问题不是「模型不够聪明」，而是缺少一套可执行的编码契约：写什么、不写什么、改文件前要查什么、完成前要验什么。

技能如何工作

本技能把整洁代码收成务实、以解决方案为中心的规则集，而不是课堂讲义。

核心原则包括单一职责、DRY、保持简单、YAGNI、童子军规则——都指向「能跑、能读、改动面可控」。

命名与函数有硬约定：变量表意图（userCount 而非 n），函数用动词+名词，布尔用 is/has/can 疑问式；函数理想 5–10 行、最多约 20 行，参数偏好 0–2 个，单一抽象层级，避免意外改输入。

结构与风格强调卫语句、扁平优于嵌套（约最多两层）、小函数组合、相关代码就近。对 AI 的行为也写死三条：要功能就写代码；报 bug 就修；不清楚就问，别猜。

反模式表直接禁止：显而易见注释、为一行代码抽函数、为两个对象建工厂、单函数 utils 文件、魔法数字、上帝函数等。

改文件前强制自问：谁 import 了本文件、本文件依赖谁、哪些测试覆盖、是否共享组件；同一任务里要连同依赖一起改，不要留下坏 import 或未同步的接口。

完成前自检对照：目标是否精确达成、必要文件是否都改、是否验证可运行、lint/类型是否过、边界是否漏。

验证脚本按代理角色映射（前端 UX/可访问性、后端 API、安全扫描、测试运行器等）；任意代理可跑通用 lint、类型覆盖率、i18n。规则是：只跑自己角色对应脚本；流程为运行 → 解析输出 → 向用户总结 → 等确认再修 → 修完重跑——禁止忽略输出或未经询问自动修复。

适用边界

• 这是代理侧写作与改动习惯的约束，不替代你们仓库已有的 ESLint/Prettier/架构规范；两者应一致，冲突时以项目为准。
• 文档中的验证脚本路径指向 ~/.claude/skills/... 下的配套技能；若本地未安装对应技能，映射表应视为「有则必跑」的约定，而不是本技能自带的可执行物。
• 技能明确立场：用户要的是能工作的代码，不是编程课——在需求模糊时仍会要求先问清楚，而不是用冗长说明代替实现。