Validators Guide

Complete guide to using validators to enforce commit quality and project standards.

What Are Validators?

Validators are rules that automatically check every commit against your project's quality standards. They act as an impartial reviewer that ensures consistency and prevents common mistakes.

Think of validators as:

Quality gates that prevent bad code from landing
Teaching tools that reinforce best practices
Time savers that catch issues before review

How Validators Work

Claude attempts commit
         │
         ▼
┌─────────────────────────┐
│  PreToolUse hook fires  │
│  (for git commit)       │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│  Load validators from:  │
│  - .claude-auto/validators/ │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│  For each validator:    │
│  - Parse frontmatter    │
│  - Check if enabled     │
│  - Send to Claude       │
└──────────┬──────────────┘
           │
           ▼
┌─────────────────────────┐
│  Claude evaluates       │
│  Returns ACK or NACK    │
└──────────┬──────────────┘
           │
    ┌──────┴──────┐
    ▼             ▼
  ACK           NACK
Commit        Block +
proceeds      explain why

What Validators See

When evaluating a commit, validators receive comprehensive information about the change:

Available Information

Full Git Diff - The complete diff output showing all changes
- Added lines (with + prefix)
- Removed lines (with - prefix)
- Context lines around changes
- File modification hunks
Commit Message - The full commit message text
- Subject line
- Body text
- Any special markers (e.g., plea: reasons)
Modified Files List - All files affected by the commit
- File paths relative to project root
- Allows file-specific validation rules
- Can detect patterns like *.test.* or migrations/**

How Validators Use This Information

Validators can make intelligent decisions based on:

Code patterns: Detect specific code constructs in the diff (e.g., console.log, any types, .skip())
File types: Apply rules only to specific file patterns (e.g., only validate .ts files, skip test files)
Change scope: Evaluate architectural impact by seeing which files are modified together
Commit metadata: Check commit message format, conventions, and plea justifications

Example Analysis

// Validator can see in the diff:
+ console.log('debug info');  // ← NACK: console.log in production code

// And in the file list:
src/user-service.ts  // ← Non-test file, apply strict rules

// And in commit message:
"fix: update user validation"  // ← Check conventional commit format

This comprehensive view allows validators to enforce context-aware quality standards.

Built-in Validators

Claude Auto includes 17 pre-configured validators:

Commit Quality

backwards-compatibility.md - Warns about breaking changes
claude-code-footprint.md - Removes "Generated with Claude Code" signatures
commit-message-format.md - Enforces conventional commit format
plea-system-valid.md - Validates plea reasons in commits

Code Quality

emergent-design.md - Ensures types emerge from tests
extreme-ownership.md - Fix problems you encounter
no-comments-in-code.md - Enforces self-documenting code
test-title-equals-test-body.md - Test names match assertions
tests-in-same-commit.md - Tests ship with implementation

Safety

no-dangerous-git-operations.md - Prevents force push, hard reset
no-skipped-tests.md - No .skip() or .only() in tests
no-type-escape-hatches.md - No any, @ts-ignore, as casts

Workflow

parallelization-awareness.md - Ensures parallel burst execution
tcr-workflow.md - Enforces Test && Commit || Revert
test-coverage.md - Maintains 100% coverage
when-to-create-documentation.md - Documents only when needed

Validator Frontmatter

Each validator has YAML frontmatter:

---
name: unique-identifier
description: What this validator checks
enabled: true
---

Fields

Field	Type	Required	Description
`name`	string	Yes	Unique identifier for the validator
`description`	string	Yes	Brief explanation of what it validates
`enabled`	boolean	No	Whether validator is active (default: true)

Validation Modes

Control validation strictness in .claude-auto/.claude.hooks.json:

{
  "validateCommit": {
    "mode": "strict"
  }
}

Modes

Mode	Behavior	Use When
`strict`	Blocks violating commits (NACK)	Production projects
`warn`	Warns but allows commits	Learning phase
`off`	No validation	Quick experiments

Creating Custom Validators

Basic Validator

Create .claude-auto/validators/no-console-logs.md:

---
name: no-console-logs
description: Prevents console.log statements in production code
enabled: true
---

# No Console Logs

Check that the commit doesn't add any `console.log` statements.

## What to check:
- No new `console.log(` in JavaScript/TypeScript files
- No new `print(` in Python files
- No new `println(` in Java/Kotlin files

## Exceptions:
- Test files (`*.test.*`, `*.spec.*`)
- Debug utilities explicitly meant for logging
- Commented out code (though this should also be avoided)

## Why this matters:
- Console logs can leak sensitive information
- They clutter production logs
- They impact performance in tight loops
- Professional code uses proper logging libraries

NACK if console.log statements are found in non-test files.

Advanced Validator

---
name: api-response-format
description: Ensures all API responses follow team format
enabled: true
---

# API Response Format Validator

All API endpoint modifications must follow our response format.

## Required Format:
```typescript
{
  success: boolean,
  data?: any,
  error?: {
    code: string,
    message: string,
    details?: any
  },
  metadata?: {
    timestamp: string,
    requestId: string
  }
}

Check for:

New/modified route handlers return this format
Error handlers transform errors to this format
Success responses include success: true
Error responses include success: false and error object

Files to check:

**/controllers/**/*.ts
**/routes/**/*.ts
**/handlers/**/*.ts

NACK if API responses don't match the required format.


---

## Conditional Validators

### Enable/Disable by Project State

Control validators based on project phase:

```markdown
---
name: strict-typing
description: Enforces strict TypeScript settings
enabled: true
when:
  projectType: typescript
  phase: production
---

# Strict TypeScript Validation

In production phase, ensure:
- No implicit any
- Strict null checks
- No unused parameters
- No unused locals

NACK if TypeScript strict mode violations exist.

Enable for Specific Files

Target validators to specific areas:

---
name: database-migration-safety
description: Validates database migrations
enabled: true
---

# Database Migration Safety

When files in `migrations/` are modified:

1. No DROP TABLE in production
2. All ALTER TABLE must be backwards compatible
3. New columns must have defaults or be nullable
4. Include rollback migration

NACK if unsafe migration patterns detected.

Validator Enforcement Levels

Different validators can have different enforcement levels:

Critical (Always NACK)

---
name: no-secrets
description: Prevents committing secrets
enabled: true
severity: critical
---

# No Secrets in Code

IMMEDIATELY NACK if detecting:
- API keys (matches common patterns)
- Passwords in plain text
- Private keys
- Connection strings with credentials

Warning (Context-Dependent)

---
name: performance-impact
description: Warns about potential performance issues
enabled: true
severity: warning
---

# Performance Impact Check

WARN (but allow) if:
- New loops within loops (O(n²))
- Synchronous file I/O in web handlers
- Large data structures in memory

Consider NACK only if performance is critical for this change.

Managing Validators

List Active Validators

From within a Claude Code session:

/claude-auto:config validators

Temporarily Disable

In .claude-auto/.claude.hooks.json:

{
  "validateCommit": {
    "mode": "strict",
    "disabled": ["no-console-logs", "strict-typing"]
  }
}

Override for Subagents

Control validation by subagent type:

{
  "subagentHooks": {
    "validateCommitOnExplore": false,
    "validateCommitOnWork": true,
    "validateCommitOnUnknown": true
  }
}

Best Practices

1. Start with Warnings

When introducing new validators:

Set mode to warn initially
Educate team on the standard
Switch to strict after adaptation period

2. Keep Validators Focused

Each validator should check one thing:

Good:

---
name: test-coverage
description: Ensures 100% code coverage
---

Check that coverage remains at 100%.

Too Broad:

---
name: code-quality
description: Ensures good code
---

Check coverage, no console.logs, proper types, good names...

3. Provide Clear Feedback

Always explain WHY in NACK messages:

Good:

NACK: Found console.log in user-service.ts:45

Console.logs can leak sensitive user data in production logs.
Use the logger service instead: logger.debug('message')

Unhelpful:

NACK: Bad code detected

4. Allow Escape Hatches

For exceptional cases, use the plea system:

git commit -m "fix: emergency hotfix

plea: console.log needed for production debugging of payment issue"

5. Regular Review

Periodically review validators:

Remove obsolete checks
Update for new patterns
Adjust severity based on team maturity

Common Validator Patterns

File Pattern Matching

Check only specific files:
- If modifying `src/**/*.ts`
- But not `src/**/*.test.ts`
- And not `src/**/*.spec.ts`

Dependency Checking

When adding to package.json:
- Ensure no duplicate functionality
- Check license compatibility
- Verify security advisories

Code Pattern Detection

Look for anti-patterns:
- `await` inside loops
- Nested ternaries
- Magic numbers without constants
- Repeated code blocks

Cross-File Validation

When changing an interface:
- Ensure all implementations updated
- Check calling code handles changes
- Verify tests cover new cases

Writing Effective Validators

Structure

Clear Title - What is being validated
Scope - Which files/changes to check
Rules - Specific things to validate
Exceptions - When to allow violations
Rationale - Why this matters
Decision - ACK/NACK criteria

Example Template

---
name: validator-name
description: One-line description
enabled: true
---

# Validator Title

## Scope
Files/patterns this validator applies to

## Check for
- Specific pattern 1
- Specific pattern 2

## Allow when
- Valid exception 1
- Valid exception 2

## Why this matters
Brief explanation of impact

## Decision
ACK if: conditions for approval
NACK if: conditions for rejection

Debugging Validators

Test Validator Logic

Create a test commit and check validator response:

# Make a change that should trigger validator
echo "console.log('test')" >> test.js

# Attempt commit (will be validated)
git add test.js
git commit -m "test: checking validator"

# Check validator output in logs
cat .claude-auto/logs/activity.log

Validator Not Triggering

Check:

Validator file exists in .claude-auto/validators/
Frontmatter enabled: true
Validation mode isn't off
Hook configuration includes Bash tool for commits

False Positives

If validator is too strict:

Add exceptions to validator rules
Make patterns more specific
Consider context in evaluation

Examples

Security Validator

---
name: security-headers
description: Ensures security headers in API responses
enabled: true
---

# Security Headers Validation

When modifying route handlers or middleware:

## Required Headers:
- `X-Content-Type-Options: nosniff`
- `X-Frame-Options: DENY`
- `X-XSS-Protection: 1; mode=block`
- `Strict-Transport-Security` (for HTTPS)

## Check:
- New route handlers include security middleware
- Modified handlers don't remove security headers
- Error handlers preserve security headers

NACK if security headers are missing or removed.

Performance Validator

---
name: database-query-optimization
description: Ensures database queries are optimized
enabled: true
---

# Database Query Optimization

## Check for:
- SELECT * queries (should specify columns)
- Missing indexes on WHERE clauses
- N+1 query patterns
- Transactions for multiple operations

## Examine:
- New queries in repositories/DAOs
- Modified query builders
- ORM usage patterns

ACK if queries follow optimization guidelines.
NACK if obvious performance issues detected.

Architecture Validator

---
name: clean-architecture
description: Enforces clean architecture boundaries
enabled: true
---

# Clean Architecture Validation

## Layer Rules:
- Domain: No imports from other layers
- Application: Imports from Domain only
- Infrastructure: Imports from Domain and Application
- Presentation: Can import from all layers

## Check imports in:
- `src/domain/**` → should have no external imports
- `src/application/**` → should not import from infrastructure/presentation
- New files follow layer conventions

NACK if architecture boundaries are violated.

Troubleshooting

Validator Conflicts

When validators give conflicting guidance:

Review validator priorities
Make one more specific
Disable less important one
Update validator logic

Performance Impact

If validation is slow:

Make file patterns more specific
Reduce complex regex patterns
Skip validation for large commits
Run validators in parallel

Team Resistance

If team pushes back on validators:

Start with educational mode (warn)
Show value through metrics
Allow team to customize rules
Gradually increase strictness

FilesExpand file tree

validators-guide.md

Latest commit

History