实战技巧配置指南质量红线配置

质量红线配置

质量红线是 CLAUDE.md 中最重要的配置之一——它定义了 Claude Code 输出代码的最低质量标准,是不可逾越的底线。

一、什么是质量红线

1.1 质量红线的定义

质量红线不是”建议”或”最佳实践”,而是必须遵守的底线规则

❌ 建议/最佳实践

”尽量避免使用 any 类型"

"建议添加错误处理"

"推荐写单元测试”

Claude 可能会”灵活处理”

✅ 质量红线

”绝不使用 any 类型"

"必须添加错误处理"

"测试必须全部通过”

Claude 会严格遵守

1.2 没有红线的问题

没有明确的质量红线时,Claude 可能会:

“偷懒"
"为了简洁,这里省略错误处理"
"简化"
"先用 any,后续再优化类型"
"先凑合"
"先实现功能,TODO: 添加测试"
"忘记检查”
直接提交代码,没运行 linter
🚫

核心问题:没有红线,“偷工减料”的代码就会混入项目。而这些问题往往在后期才被发现,修复成本远高于一开始就做对。

1.3 红线 vs 建议

类型语气Claude 的理解示例
红线绝不/必须/禁止必须 100% 遵守”绝不使用 any”
建议尽量/推荐/建议可以灵活处理”尽量避免 any”

二、两类质量红线

质量红线分为两类:提交前强制检查(必须通过才能提交)和绝对禁止清单(绝不允许出现)。

提交前强制检查
CHECK BEFORE COMMIT
必须通过的质量门禁
绝对禁止清单
NEVER ALLOWED
绝不允许出现的行为

2.1 提交前强制检查(必须通过)

这些是代码提交前必须通过的自动化检查,任何一项失败都不能提交。

四项强制检查
1. Linter 检查
零警告、零错误
eslint . —max-warnings 0
2. 测试检查
所有测试必须通过
npm test / pytest
3. 格式化检查
代码已正确格式化
prettier —check .
4. 类型检查
TypeScript 严格模式通过
tsc —noEmit

配置示例

## 提交前强制检查
 
**以下检查必须全部通过,否则不允许提交:**
 
1. **Linter 检查**`npm run lint` 必须零警告零错误
2. **测试检查**`npm test` 必须全部通过
3. **格式化检查**`npm run format:check` 必须通过
4. **类型检查**`npm run type-check` 必须通过
 
**重要**:如果任何一项检查失败,必须先修复后再提交。绝不使用 `--no-verify` 跳过检查。
⚠️

关键点:要求”零警告零错误”,而不是”尽量减少警告”。模糊的标准会被利用。


2.2 绝对禁止清单(绝不允许)

这些是任何情况下都不允许出现的行为,没有例外。

绝对禁止清单
绝不提交未通过测试的代码
即使”只是小改动”也必须跑测试
绝不使用 TODO/FIXME 作为最终代码
不能留下”待完成”的占位符
绝不跳过错误处理
每个可能失败的操作都必须有错误处理
绝不硬编码密钥/凭证
必须使用环境变量,即使是开发环境
绝不使用 any 类型
用 unknown 替代,然后进行类型守卫
绝不吞掉异常
捕获的异常必须记录或重新抛出

配置示例

## 绝对禁止清单
 
**以下行为绝不允许,没有例外:**
 
### 代码质量
- 绝不提交未通过测试的代码
- 绝不使用 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 可选红线(按需添加)

以下红线可根据团队需要添加:

Emoji 禁用
”绝不在代码/注释中使用 emoji”
特定代码风格
”绝不使用 var,必须用 const/let”
覆盖率要求
”测试覆盖率必须 ≥ 80%“
注释要求
”公开 API 必须有 JSDoc”

5.3 技术栈特定红线

TypeScript 项目

• 绝不使用 any,用 unknown 替代
• 绝不使用 @ts-ignore
• 必须开启 strict 模式
• 绝不使用非空断言 (!)

Python 项目

• 绝不使用 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 中最重要的配置之一:

要点说明
明确底线用”绝不”而非”尽量”,不给模糊空间
两类红线提交前检查 + 绝对禁止清单
具体标准”零警告”而非”减少警告”
可定制根据技术栈和团队需求调整

与其他配置的配合

下一步


MIT 2025 © Nextra.
CC Club返回官网