Code Health & Guardrails

Speed amplifies both good design and bad decisions. At agentic speed, a small quality issue compounds into technical debt within minutes. Guardrails ensure quality keeps pace with velocity.

The Guardrail Stack

Layer 1: Post-Edit Hooks (Instant)

Run automatically after every file edit. The configuration syntax varies by tool — see the Tool Configuration Reference for specifics. Example hook configuration:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "pnpm tsc --noEmit 2>&1 | head -20"
      },
      {
        "matcher": "Edit|Write",
        "command": "pnpm biome check --write $(git diff --name-only HEAD) 2>&1 | tail -5"
      }
    ]
  }
}

What this catches: Type errors, syntax errors, formatting issues — immediately.

Layer 2: Pre-Commit Hooks (Before Commit)

.husky/pre-commit

pnpm tsc --noEmit
pnpm biome check
pnpm vitest run --changed

What this catches: Type regressions, lint violations, test failures in changed files.

Layer 3: CI Pipeline (Before Merge)

.github/workflows/ci.yml

steps:
  - run: pnpm test
  - run: pnpm tsc --noEmit
  - run: pnpm biome check
  - run: pnpm vitest run --coverage
  - run: |
      COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
      if (( $(echo "$COVERAGE < 80" | bc -l) )); then
        echo "Coverage below 80%: $COVERAGE%"
        exit 1
      fi

Layer 4: AI Review (Before Merge)

Use a dedicated review agent:

Use the reviewer agent to check these changes for:
- Security vulnerabilities (OWASP Top 10)
- Logic errors and unhandled edge cases
- Missing test coverage
- Consistency with existing patterns

Code Health as AI Readiness

Research from CodeScene shows that code health directly impacts agent success rates:

Code Health Score	Agent Success Rate	Recommendation
9.5-10.0	High	Ideal for agentic work
8.0-9.4	Moderate	May need some refactoring first
Below 8.0	Low	Refactor before assigning to agents

Tip

Before assigning complex tasks to agents, check the code health of the target files. Unhealthy code (deeply nested functions, high complexity, poor modularity) increases agent failure rates and token waste. Refactor first, then implement.

Six Operational Patterns

Based on CodeScene’s research, these six patterns produce the best results:

1. Assess AI readiness before assigning tasks — Check code health scores
2. Safeguard at three levels — Continuous review, pre-commit, PR pre-flight
3. Refactor to expand the AI-ready surface — Break large functions, improve modularity
4. Encode principles in agent configuration — agent configuration files, skills, agent definitions
5. Use coverage as a behavioral guardrail — Set thresholds, enforce at PR level
6. Automate checks end-to-end — E2E tests agents can’t easily circumvent

Coverage as a Guardrail

Use coverage not as a vanity metric, but as a regression signal:

# Agent configuration file
## IMPORTANT
- Coverage must not decrease on any PR
- New functions MUST have tests
- If coverage drops, investigate before committing

Monitor coverage especially when agents iterate rapidly — they may delete or skip tests as a shortcut.

Key Takeaways

• Layer guardrails: post-edit hooks → pre-commit → CI → AI review
• Use deterministic tools (linters, type checkers) for style — not the LLM
• Code health scores predict agent success rates — refactor unhealthy code first
• Coverage is a regression signal, not a vanity metric
• Speed amplifies both quality and defects — guardrails are non-negotiable