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:
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
| Type | Phrasing | How Claude interprets it | Example |
|---|---|---|---|
| Gate | Never / Must / Prohibited | 100% mandatory | ”Never use any” |
| Suggestion | Try to / Recommended / Suggested | May 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).
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.
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.
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 inputWatch 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 Standard | Specific 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 accepted5. Customizing Gates for Your Team
5.1 Universal Gates (Recommended for All Projects)
The following gates apply to the vast majority of projects:
✓ 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:
5.3 Tech-Stack-Specific Gates
• Never use any — use unknown instead
• Never use @ts-ignore
• Must enable strict mode
• Never use non-null assertions (!)
• Never use bare except
• Must use type annotations
• Never use eval/exec
• Must pass mypy checks
• 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 codeQ: 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 Point | Description |
|---|---|
| Set a clear floor | Use “never” not “try to” — leave no room for ambiguity |
| Two types of gates | Pre-commit checks + absolute prohibition list |
| Specific standards | ”Zero warnings” not “fewer warnings” |
| Customizable | Adjust 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
- Coding Standards Configuration — define code style conventions
- Three-Phase Workflow Configuration — ensure quality checks are executed
- Back to Configuration Guide Home