质量红线配置
质量红线是 CLAUDE.md 中最重要的配置之一——它定义了 Claude Code 输出代码的最低质量标准,是不可逾越的底线。
一、什么是质量红线
1.1 质量红线的定义
质量红线不是”建议”或”最佳实践”,而是必须遵守的底线规则。
❌ 建议/最佳实践
”尽量避免使用 any 类型"
"建议添加错误处理"
"推荐写单元测试”
↓
Claude 可能会”灵活处理”
✅ 质量红线
”绝不使用 any 类型"
"必须添加错误处理"
"测试必须全部通过”
↓
Claude 会严格遵守
1.2 没有红线的问题
没有明确的质量红线时,Claude 可能会:
核心问题:没有红线,“偷工减料”的代码就会混入项目。而这些问题往往在后期才被发现,修复成本远高于一开始就做对。
1.3 红线 vs 建议
| 类型 | 语气 | Claude 的理解 | 示例 |
|---|---|---|---|
| 红线 | 绝不/必须/禁止 | 必须 100% 遵守 | ”绝不使用 any” |
| 建议 | 尽量/推荐/建议 | 可以灵活处理 | ”尽量避免 any” |
二、两类质量红线
质量红线分为两类:提交前强制检查(必须通过才能提交)和绝对禁止清单(绝不允许出现)。
2.1 提交前强制检查(必须通过)
这些是代码提交前必须通过的自动化检查,任何一项失败都不能提交。
配置示例:
## 提交前强制检查
**以下检查必须全部通过,否则不允许提交:**
1. **Linter 检查**:`npm run lint` 必须零警告零错误
2. **测试检查**:`npm test` 必须全部通过
3. **格式化检查**:`npm run format:check` 必须通过
4. **类型检查**:`npm run type-check` 必须通过
**重要**:如果任何一项检查失败,必须先修复后再提交。绝不使用 `--no-verify` 跳过检查。关键点:要求”零警告零错误”,而不是”尽量减少警告”。模糊的标准会被利用。
2.2 绝对禁止清单(绝不允许)
这些是任何情况下都不允许出现的行为,没有例外。
配置示例:
## 绝对禁止清单
**以下行为绝不允许,没有例外:**
### 代码质量
- 绝不提交未通过测试的代码
- 绝不使用 TODO/FIXME/HACK 作为最终代码
- 绝不跳过错误处理
- 绝不吞掉异常(空 catch 块)
- 绝不使用魔法数字(必须定义常量)
### 类型安全
- 绝不使用 any 类型(用 unknown + 类型守卫)
- 绝不使用 @ts-ignore(解决根本问题)
- 绝不禁用 ESLint 规则(eslint-disable)
### 安全相关
- 绝不硬编码密钥、密码、Token
- 绝不在代码中包含敏感信息
- 绝不信任未验证的用户输入注意措辞:使用”绝不”而非”不要”,使用”必须”而非”应该”。强硬的语气能让 Claude 更严格地遵守规则。
三、完整配置模板
以下是可以直接复制到 CLAUDE.md 使用的完整配置:
## 质量红线
**重要:以下规则是绝对底线,没有任何例外情况**
### 提交前强制检查(必须全部通过)
在提交任何代码之前,必须确保以下检查全部通过:
1. **Linter 检查**
- 命令:`npm run lint`
- 标准:零警告、零错误
- 绝不使用 `eslint-disable` 绕过规则
2. **测试检查**
- 命令:`npm test`
- 标准:所有测试必须通过
- 新增代码必须有对应测试
3. **格式化检查**
- 命令:`npm run format:check`
- 标准:所有文件已正确格式化
4. **类型检查**(TypeScript 项目)
- 命令:`npm run type-check`
- 标准:TypeScript 严格模式下无错误
### 绝对禁止清单(绝不允许)
以下行为在任何情况下都不允许:
**代码质量**
- 绝不提交未通过测试的代码
- 绝不使用 TODO/FIXME 作为最终代码
- 绝不跳过错误处理
- 绝不吞掉异常(空 catch 块)
- 绝不使用魔法数字
**类型安全**
- 绝不使用 any 类型(用 unknown 替代)
- 绝不使用 @ts-ignore
- 绝不禁用 ESLint 规则
**安全相关**
- 绝不硬编码密钥/凭证
- 绝不在日志中输出敏感信息
- 绝不跳过输入验证
### 违反红线的处理
如果发现代码违反以上任何一条红线:
1. 必须立即修复
2. 不能使用任何方式绕过
3. 不能以"临时方案"为由例外四、如何让红线真正生效
仅仅写了红线配置是不够的,还需要注意以下技巧让红线真正生效。
4.1 语言要强硬
❌ 弱约束词
• “尽量避免使用 any”
• “建议添加错误处理”
• “不要跳过测试”
• “应该运行 linter”
✅ 强约束词
• “绝不使用 any 类型”
• “必须添加错误处理”
• “禁止跳过测试”
• “强制运行 linter”
4.2 给出具体标准
模糊的标准会被”灵活解读”,具体的标准才能被严格执行。
| 模糊标准 | 具体标准 |
|---|---|
| ”减少 linter 警告" | "零警告、零错误" |
| "写一些测试" | "覆盖率 ≥ 80%" |
| "注意代码质量" | "函数不超过 30 行" |
| "处理好错误" | "每个 try 块必须有 catch” |
4.3 说明违反后果
让 Claude 明白违反红线的严重性:
## 违反红线的后果
如果输出的代码违反以上任何一条红线:
- 该代码将被视为**不合格**,需要重新编写
- 不接受任何"特殊情况"或"临时方案"的例外
- 不接受"先提交再修复"的做法五、根据团队定制红线
5.1 通用红线(推荐所有项目)
以下红线适用于绝大多数项目:
✓ 测试必须全部通过
✓ 绝不跳过错误处理
✓ 绝不硬编码敏感信息
✓ Linter 检查必须通过
✓ 绝不提交带 TODO 的代码
5.2 可选红线(按需添加)
以下红线可根据团队需要添加:
5.3 技术栈特定红线
• 绝不使用 any,用 unknown 替代
• 绝不使用 @ts-ignore
• 必须开启 strict 模式
• 绝不使用非空断言 (!)
• 绝不使用 bare except
• 必须使用类型注解
• 绝不使用 eval/exec
• 必须通过 mypy 检查
• 绝不直接操作 DOM(使用框架方法)
• 绝不在组件中使用 inline style(使用 CSS 类)
• 必须处理加载和错误状态
• 绝不忽略 accessibility 属性
六、常见问题
Q: Claude 还是会违反红线怎么办?
解决方案:加强约束语言,并要求 Claude 在提交前自查。
## 提交前自查清单
在输出最终代码之前,必须逐项确认:
- [ ] 是否使用了 any 类型?→ 如果是,改用 unknown
- [ ] 是否有空 catch 块?→ 如果是,添加错误处理
- [ ] 是否有 TODO/FIXME?→ 如果是,现在就完成
- [ ] 是否有硬编码的配置?→ 如果是,改用环境变量
- [ ] 是否运行了 linter?→ 如果没有,现在运行
**只有全部确认通过,才能输出代码**Q: 红线太严格导致效率降低怎么办?
解决方案:区分”开发时”和”提交时”的要求。
## 开发过程 vs 提交标准
### 开发过程中(可以宽松)
- 可以使用 console.log 调试
- 可以暂时跳过部分测试
- 可以使用简化的实现
### 提交时(必须严格)
- 必须删除所有调试代码
- 必须确保所有测试通过
- 必须是生产就绪的代码Q: 如何平衡红线数量?
建议:从核心红线开始,逐步添加。
第一阶段:核心红线(3-5 条)
先添加最重要的红线:
- 测试必须通过
- 绝不跳过错误处理
- 绝不硬编码密钥
第二阶段:扩展红线(5-10 条)
使用一段时间后,根据遇到的问题扩展:
- 类型安全相关
- 代码风格相关
- 安全相关
第三阶段:团队定制(10-15 条)
形成团队特有的完整红线清单
七、总结
质量红线是 CLAUDE.md 中最重要的配置之一:
| 要点 | 说明 |
|---|---|
| 明确底线 | 用”绝不”而非”尽量”,不给模糊空间 |
| 两类红线 | 提交前检查 + 绝对禁止清单 |
| 具体标准 | ”零警告”而非”减少警告” |
| 可定制 | 根据技术栈和团队需求调整 |