Quality Gates Configuration

Quality gates are one of the most important configurations in CLAUDE.md — they define the minimum quality standard for code Claude Code produces, a floor that must never be crossed.

1. What Are Quality Gates

1.1 Defining Quality Gates

Quality gates are not “suggestions” or “best practices” — they are non-negotiable baseline rules.

❌ Suggestions / Best Practices

”Try to avoid using the any type"

"It’s recommended to add error handling"

"Unit tests are suggested”

Claude may “use its judgment”

✅ Quality Gates

”Never use the any type"

"Error handling is mandatory"

"All tests must pass”

Claude will follow them strictly

1.2 The Problem Without Quality Gates

Without explicit quality gates, Claude may:

Cut corners
”For simplicity, skipping error handling here”
Simplify
”Using any for now, will improve types later”
Punt
”Feature works, TODO: add tests”
Forget to check
Commit directly without running the linter
🚫

The core problem: Without gates, low-quality code slips into the project. These issues are often only discovered later, and fixing them costs far more than getting them right the first time.

1.3 Gates vs. Suggestions

TypePhrasingHow Claude interprets itExample
GateNever / Must / Prohibited100% mandatory”Never use any”
SuggestionTry to / Recommended / SuggestedMay use judgment”Try to avoid any”

2. Two Types of Quality Gates

Quality gates fall into two categories: mandatory pre-commit checks (must pass before committing) and absolute prohibition list (never allowed under any circumstances).

Mandatory Pre-Commit Checks
CHECK BEFORE COMMIT
Quality gates that must pass
Absolute Prohibition List
NEVER ALLOWED
Behaviors never permitted

2.1 Mandatory Pre-Commit Checks (Must Pass)

These are automated checks that must pass before any code is committed. If any one fails, the commit cannot proceed.

Four Mandatory Checks
1. Linter Check
Zero warnings, zero errors
eslint . —max-warnings 0
2. Test Check
All tests must pass
npm test / pytest
3. Format Check
Code is correctly formatted
prettier —check .
4. Type Check
TypeScript strict mode passes
tsc —noEmit

Configuration example:

## Mandatory Pre-Commit Checks
 
**All of the following checks must pass before any commit is allowed:**
 
1. **Linter Check**: `npm run lint` must produce zero warnings and zero errors
2. **Test Check**: `npm test` must pass completely
3. **Format Check**: `npm run format:check` must pass
4. **Type Check**: `npm run type-check` must pass
 
**Important**: If any check fails, it must be fixed before committing. Never use `--no-verify` to bypass checks.
⚠️

Key point: Require “zero warnings, zero errors” — not “try to reduce warnings.” Vague standards get exploited.


2.2 Absolute Prohibition List (Never Allowed)

These behaviors are prohibited under any circumstances, with no exceptions.

Absolute Prohibition List
Never commit code that fails tests
Even “just a small change” must pass the test suite
Never use TODO/FIXME in final code
No “to be completed” placeholders in committed code
Never skip error handling
Every operation that can fail must have error handling
Never hardcode secrets/credentials
Must use environment variables, even in development
Never use the any type
Use unknown instead, then apply type guards
Never swallow exceptions
Caught exceptions must be logged or re-thrown

Configuration example:

## Absolute Prohibition List
 
**The following behaviors are never allowed, with no exceptions:**
 
### Code Quality
- Never commit code that fails tests
- Never use TODO/FIXME/HACK in final code
- Never skip error handling
- Never swallow exceptions (empty catch blocks)
- Never use magic numbers (define constants instead)
 
### Type Safety
- Never use the any type (use unknown + type guards)
- Never use @ts-ignore (fix the root issue)
- Never disable ESLint rules (eslint-disable)
 
### Security
- Never hardcode secrets, passwords, or tokens
- Never include sensitive data in code
- Never trust unvalidated user input
🚫

Watch your wording: Use “never” not “don’t”, use “must” not “should.” Strong language makes Claude enforce rules more strictly.


3. Full Configuration Template

Here is a complete template you can copy directly into your CLAUDE.md:

## Quality Gates
 
**Important: The following rules are absolute minimums with no exceptions whatsoever**
 
### Mandatory Pre-Commit Checks (All Must Pass)
 
Before committing any code, ensure all of the following checks pass:
 
1. **Linter Check**
   - Command: `npm run lint`
   - Standard: zero warnings, zero errors
   - Never use `eslint-disable` to bypass rules
 
2. **Test Check**
   - Command: `npm test`
   - Standard: all tests must pass
   - New code must have corresponding tests
 
3. **Format Check**
   - Command: `npm run format:check`
   - Standard: all files are correctly formatted
 
4. **Type Check** (TypeScript projects)
   - Command: `npm run type-check`
   - Standard: no errors under TypeScript strict mode
 
### Absolute Prohibition List (Never Allowed)
 
The following behaviors are prohibited under any circumstances:
 
**Code Quality**
- Never commit code that fails tests
- Never use TODO/FIXME in final code
- Never skip error handling
- Never swallow exceptions (empty catch blocks)
- Never use magic numbers
 
**Type Safety**
- Never use the any type (use unknown instead)
- Never use @ts-ignore
- Never disable ESLint rules
 
**Security**
- Never hardcode secrets/credentials
- Never output sensitive data in logs
- Never skip input validation
 
### Handling Violations
 
If code is found to violate any of the above gates:
1. Must fix immediately
2. Cannot be bypassed in any way
3. Cannot be excepted as a "temporary solution"

4. Making Quality Gates Actually Work

Writing the configuration is not enough. Apply these techniques to ensure gates are truly enforced.

4.1 Use Strong Language

❌ Weak constraint words

• “Try to avoid using any”

• “It’s recommended to add error handling”

• “Don’t skip tests”

• “Should run the linter”

✅ Strong constraint words

• “Never use the any type”

• “Must add error handling”

• “Prohibited to skip tests”

• “Required to run linter”

4.2 Give Specific Standards

Vague standards get “flexibly interpreted” — specific standards can be strictly enforced.

Vague StandardSpecific Standard
”Reduce linter warnings""Zero warnings, zero errors"
"Write some tests""Coverage ≥ 80%"
"Pay attention to code quality""Functions no longer than 30 lines"
"Handle errors properly""Every try block must have a catch”

4.3 State the Consequences of Violations

Make clear to Claude the seriousness of crossing a quality gate:

## Consequences of Gate Violations
 
If code output violates any of the above gates:
- The code will be considered **unacceptable** and must be rewritten
- No "special circumstances" or "temporary solution" exceptions are accepted
- "Commit now, fix later" is not accepted

5. Customizing Gates for Your Team

The following gates apply to the vast majority of projects:

Universal Gate Checklist

✓ All tests must pass

✓ Never skip error handling

✓ Never hardcode sensitive information

✓ Linter check must pass

✓ Never commit code with TODO placeholders

5.2 Optional Gates (Add as Needed)

The following gates can be added based on team requirements:

Emoji Ban
”Never use emojis in code or comments”
Specific Code Style
”Never use var — must use const/let”
Coverage Requirement
”Test coverage must be ≥ 80%“
Comment Requirements
”Public APIs must have JSDoc”

5.3 Tech-Stack-Specific Gates

TypeScript Projects

• Never use any — use unknown instead
• Never use @ts-ignore
• Must enable strict mode
• Never use non-null assertions (!)

Python Projects

• Never use bare except
• Must use type annotations
• Never use eval/exec
• Must pass mypy checks

Frontend Projects

• Never manipulate the DOM directly (use framework methods)
• Never use inline styles in components (use CSS classes)
• Must handle loading and error states
• Never ignore accessibility attributes


6. FAQ

Q: What if Claude still violates a gate?

⚠️

Solution: Strengthen the constraint language and require Claude to self-check before submitting.

## Pre-Submission Self-Check
 
Before outputting final code, confirm each item:
 
- [ ] Did I use the any type? → If yes, change to unknown
- [ ] Are there empty catch blocks? → If yes, add error handling
- [ ] Are there TODO/FIXME comments? → If yes, complete them now
- [ ] Are there hardcoded configurations? → If yes, move to environment variables
- [ ] Did I run the linter? → If not, run it now
 
**Only output the code after all items are confirmed**

Q: What if gates are too strict and reduce efficiency?

Solution: Distinguish between “during development” and “at commit time” requirements.

## Development Process vs. Commit Standards
 
### During Development (can be relaxed)
- May use console.log for debugging
- May temporarily skip some tests
- May use simplified implementations
 
### At Commit Time (must be strict)
- Must remove all debug code
- Must ensure all tests pass
- Must be production-ready code

Q: How do I balance the number of gates?

Suggestion: Start with core gates, then add gradually.

Phase 1: Core Gates (3–5)

Start with the most important gates:

  • Tests must pass
  • Never skip error handling
  • Never hardcode secrets

Phase 2: Extended Gates (5–10)

After using for a while, expand based on problems you encounter:

  • Type safety related
  • Code style related
  • Security related

Phase 3: Team Customization (10–15)

Build the team’s complete, tailored gate checklist


7. Summary

Quality gates are one of the most important configurations in CLAUDE.md:

Key PointDescription
Set a clear floorUse “never” not “try to” — leave no room for ambiguity
Two types of gatesPre-commit checks + absolute prohibition list
Specific standards”Zero warnings” not “fewer warnings”
CustomizableAdjust to fit your tech stack and team needs

Working with other configurations:

  • Pair with Three-Phase Workflow: enforce quality checks during the implementation phase
  • Pair with Coding Standards: define specific code conventions
  • Pair with security standards: strengthen security-related gates

Next Steps


MIT 2026 © Nextra.
加入社群CC Club返回官网