Agent Detection Kit Catching unexpected Claude behavior — when you can't read every line

4 TIERS  CI · Hooks · Agents · Obs
3–5 MIN  human attention per PR
WEEKLY  hygiene review cycle

1Machine / CI ~60-70%

Runs on every PR. Most issues stop here.
Lint / formatPrettier, Ruff
Typestsc, mypy
SecretsGitleaks
SASTSemgrep, CodeQL
DepsDependency Review
Size>600 lines = fail
Coverage Δ>1% drop = fail
Runtime Δ>2× = warn
New TODOsblock
.only / .skipblock

2Hooks in-flight

Fires as Claude works. Logs, flags, blocks.
log-bashaudit trail
block-dangerouscurl|sh, force push
flag-sensitiveauth, payments, infra
detect-antipatternsTODOs, prints, secrets
auto-formatprettier / ruff
session-summaryread this daily

Locations

# hooks live here
.claude/hooks/*.sh
# outputs
.claude/logs/

3Subagents you invoke

Read-only reviewers. Periodic.
  • pr-reviewer — before every non-trivial merge
  • security-reviewer — any auth / crypto / payments PR
  • architecture-auditor — weekly, audits drift vs ADRs

Invocation

# In Claude Code:
> Use pr-reviewer on #42

> Use security-reviewer
  on src/auth/

> Use architecture-auditor
  for last 7 days on main

4Outcomes runtime

What slipped through tiers 1–3 shows up here.
Sentry errors↑ post-deploy
p99 latency↑ on touched routes
Test runtime↑ >2× / week
Slow queriesnew patterns
Bundle size↑ >10% / week
Dep count+5 in a sprint
CPU / RAM↑ no feature launch
Alert ratepages / week
Signal fires → what did we deploy? → what did Claude write? → root cause.

→PR Triage 3–5 min

  • 30s — PR description. Does approach fit?
  • 5s — CI badges. All green?
  • 30s — git diff --name-only --diff-filter=A. New files in expected places?
  • 30s — Bot-posted Change Summary comment
  • 30s — .claude/logs/sensitive.log today
  • 2min — Spot-check 1–2 judgment-call files
  • → Merge staging, let obs watch 24h
  • → Promote prod only after signals clean

↻Feedback Loop that day

Unexpected behavior → rule that prevents recurrence goes in the appropriate layer that day.
Hard never-dosettings.json deny / hook
Domain procedure.claude/skills/*
Always-relevantCLAUDE.md
Complex scenariodocs/runbooks/*
Architecturenew docs/decisions/*

Rituals

  • Each session end: skim session-summaries.md
  • Each PR: 3–5 min triage + subagent if sensitive
  • Friday 20 min: weekly-review.sh + architecture-auditor
  • Monthly 60 min: CLAUDE.md <200 lines, retire unused skills, ask→allow

⚠Red Flags

Stop routine triage. Investigate.
  • PR touches auth/payments, description doesn't
  • New files in unfamiliar directories
  • Dep count grew >5 in one PR
  • Coverage drop on a "refactor"
  • Multiple hook blocks (fighting rules)
  • Same class of fix in 3+ PRs (missing rule)
  • Sentry spike within 1h of merge
  • Test runtime jumped, test count didn't
  • CLAUDE.md past 250 lines (prune)

×Human-Only

Detection catches mechanical. These need judgment.
  • Whether solution fits user's real problem
  • Unwritten product invariants
  • Maintainability for current team
  • Behavior changes tests cover identically
  • Customer-facing text / pricing / emails

Permanent rules

  • Never merges own PRs
  • Never deploys to production
  • Never ships user-facing change w/o approval
  • Never touches code without matching tests