code-quality

用途：这是一套不可协商的代码质量标准，用于约束 AI 代理写出的代码风格。资料指出，AI 生成的代码虽然能跑，但每次会话的命名、嵌套层级和错误处理方式都会有细微差异，长期累积会导致同一套错误处理、命名约定和魔法数字出现多种写法；本标准旨在把这种漂移收敛为零。\n\n主要能力与用法：\n1）测试驱动开发的四层验证框架。第 1 层单元测试，隔离测试单个函数、计算、状态变换与数据格式化，覆盖正常路径与边界情况；第 2 层集成测试，验证多个模块如何协作，如 API 返回结构、组件渲染、数据库查询、状态管理接线；第 3 层行为测试，用 Playwright 等工具端到端测试完整用户流程与相邻流程是否回归；第 4 层人工验证，检查自动化测试无法判断的视觉效果、动画手感、真实设备与屏幕尺寸。TDD 原则要求第 1 至 3 层先于实现代码编写，测试初始应全部失败，随后写最小代码使其通过，再重构，第 4 层作为最终关卡。\n2）测试质量要求。采用 Arrange-Act-Assert 结构，一个测试只验证一个概念，名称描述行为而非实现，测试须隔离、确定性、快速、可读。\n3）代码结构。优先使用提前返回与守卫子句，最大嵌套深度 3 层，函数约不超过 30 行、参数不超过 3 至 4 个，遵循单一职责；导入须显式、分组、无通配符与未使用项；删除死代码与注释掉的代码；可读性优先于炫技。\n4）错误处理。边界处快速失败，按操作类型捕获具体异常（如文件操作用 OSError、JSON 解析用 JSONDecodeError、网络用 ConnectionError 与 TimeoutError），禁止空的 except、禁止吞掉错误；仅在 CLI main 或 API 请求处理器等顶层边界允许宽泛捕获，并需记录完整异常。\n5）命名规范。用介词或命名参数表达数据流向，通过朗读测试；布尔量用 is、has、should、can、will、did 前缀；禁止缩写与单字符变量，需完整拼写 id、url、api、db、io 等公认技术缩写。\n6）常量与清晰度。非 0、1、-1、True、False、None、空字符串的字面量都需提取为具名常量，并按含义命名；布尔参数应改为命名参数或选项对象；默认不可变，避免修改入参。\n7）文档。公开函数、方法与类必须有 docstring，包含用途、参数、返回值、副作用、可能错误与示例；注释通过删除测试判断是否必要。\n\n适用场景与限制：适合在 AI 辅助编码、代码评审与重构中作为强制标准。资料未提供安装命令、URL 使用步骤、收费或价格、平台支持信息，这些内容暂未提供。