Agentic Validators

Agentic Validators

Goal

Turn “agent wrote code” into “agent wrote code and the change is validated automatically.”

This skill helps you:

• choose the right validation strategy (per-file vs repo-wide)
• implement post-tool-use and stop hooks
• create narrow validators (fast, deterministic checks)
• structure work so multiple agents can run in parallel without losing correctness

Mental model

• Agents are non-deterministic; validators are deterministic.
• Context is fragile; validation + logs are durable.
• Prefer small, fast checks close to the change (per-file) + a final global gate (repo-wide).

When to use which hook

Post-tool-use hook (best default)

Use when:

• you want immediate feedback after edits
• you can validate the specific file(s) that were touched
• you want high signal without running the full test suite

Typical checks:

• formatting (prettier/black)
• linting (eslint/ruff)
• typecheck for that file/module (tsc --noEmit with project config)

Stop hook (end-of-run gate)

Use when:

• you need repo-wide invariants
• you want one last “exit criteria” check

Typical checks:

• unit tests
• build
• integration tests

Step-by-step: add validators to a repo

1) Identify file types and fast checks

• JS/TS: prettier + eslint + typecheck
• Python: ruff + pytest (optional)
• Go: gofmt + go test (optional)

2) Implement per-file validator(s)

• A validator should be:
• fast (<5–30s)
• deterministic
• clear output
• safe to run repeatedly

3) Wire into hooks

• Implement post-tool-use hook calling validator with the file path.

4) Add logs

• Write to a predictable location (e.g., .agent-logs/validators.log)

5) Add a stop-hook “final gate”

• Run the broader checks once.

Example validator patterns

Pattern A: “format + lint” for a touched file

• Format file
• Lint file
• If any change was made by formatter, fail and ask agent to re-run with formatter changes committed

Pattern B: “contract test”

• For touched module, run a focused unit test subset

Pattern C: “readme/docs invariant”

• If docs changed, run markdown lint + link checker

Parallelism pattern

If you have many similar files (CSV, configs, docs):

• spawn one subagent per file
• each subagent runs its own post-tool-use validator
• aggregator agent only accepts results where validators passed

Common failure modes & fixes

• Validator too slow → split into fast per-file checks + slower stop hook.
• Validator flaky → remove network calls, pin versions, add retries only where safe.
• Agent ignores tool docs → write a short “constitution” section and point to reference files.

References

• See Hook recipes
• See Validator design checklist

Hook recipes (Claude Code-style)

Note: Exact hook configuration differs by agent/IDE. Adapt these patterns to your environment.

Recipe 1: post-tool-use validate touched file

• Inputs: tool name + file path(s)
• Action: run a validator script with the file path
• Output: non-zero exit on failure so the agent must fix

Recipe 2: stop hook final gate

Run once on agent stop:

• tests
• build
• lint (repo-wide)

Recipe 3: logging

Write:

• timestamp
• agent id / session id (if available)
• command run
• pass/fail

Prefer line-oriented logs.

Validator design checklist

A good validator is:

• Deterministic (no network, minimal randomness)
• Fast (seconds, not minutes)
• Focused (one responsibility)
• Clear (actionable error messages)
• Idempotent (safe to re-run)

Minimum recommended set

• formatter
• linter
• unit tests (small subset)
• final gate (repo-wide)