clean-code

核心用法

Clean Code 是一个纯文档型的 AI 编程规范技能，旨在指导 AI Agent 编写简洁、务实、可维护的代码。它不执行任何代码，而是通过系统化的规则约束 AI 的输出行为。核心用法包括：遵循五大编程原则（SRP 单一职责、DRY 不重复、KISS 保持简单、YAGNI 不做过度设计、Boy Scout 改善遗留代码）；严格执行命名规范（意图明确的变量、动词+名词的函数、疑问形式的布尔值、全大写常量）；控制函数粒度（20行以内、只做一件事、最多3个参数、无副作用）；优化代码结构（卫语句提前返回、扁平化嵌套、组合小函数、相关代码就近放置）。

显著优点

该技能的最大价值在于建立了 AI 编程的"共同语言"，解决了 AI 生成代码常见的过度工程化问题。其优点体现在：一是极致的实用性，直接给出可执行的规则而非抽象理论，如"函数最多20行"比"保持函数短小"更具操作性；二是场景化指导，针对 AI 特性设计了专属风格（用户要功能就直接写、报bug就直接修、需求不清就问）；三是强制的质量门禁，要求编辑文件前必须分析依赖关系，避免牵一发而动全身；四是完善的验证体系，为不同专业角色（前端、后端、移动端、安全、性能等）配置了对应的自动化检查脚本，确保代码交付质量。

潜在缺点与局限性

作为规范型技能，其局限性也较为明显：首先，规则刚性可能抑制特定场景下的灵活性，例如20行函数限制在复杂业务逻辑中可能需要刻意拆分，反而降低可读性；其次，验证脚本依赖外部 Python 环境，若项目未配置对应脚本或环境缺失，则无法执行强制检查；第三，规范主要针对通用编程，对特定框架（如 React Hooks 规则、Rust 所有权模式）或领域（如嵌入式、数据科学）的针对性不足；最后，纯文档属性意味着它无法主动拦截违规代码，实际效果完全依赖 AI 的遵循程度，缺乏强制性约束机制。

适合的目标群体

该技能最适合以下场景和团队：追求代码简洁性的初创团队或开源项目，需要快速建立编码共识；使用 AI 辅助编程的开发者，希望减少 AI 生成代码的"废话"和过度设计；代码审查流程较轻的团队，需要前置的质量把控机制；多角色协作的项目（前端、后端、移动端、安全审计等），需要统一的交付标准。对于已有严格代码规范的大型企业，可作为 AI 编程的补充参考；对于编程初学者，也能从中学习到务实的工程思维。

使用风险

常规风险主要包括：性能方面，验证脚本的批量执行可能增加 CI 耗时，尤其在大型代码库中；依赖项方面，脚本依赖 Python 环境和特定库，跨平台兼容性需验证；误用风险，过度追求"无注释"可能导致复杂算法缺乏必要说明，或新手误解"直接写代码"为忽略需求分析；版本同步风险，技能版本（2.0）与项目实际使用的验证脚本版本可能不匹配，导致检查标准不一致。建议团队在使用前根据实际技术栈调整规则阈值，并建立规范本身的迭代机制。