Skip to main content
subagent CX Codex

verify-agent — Claude Code subagent: what it does, how to install

verify-agent runs a fresh-context validation pipeline in Claude Code. It executes typecheck, lint, build, and test steps while safely auto-fixing trivial errors.

MIT ★ 880 updated 2026-09-03

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/verify-agent.md
Open on GitHub

What verify-agent does

The subagent isolates verification from the parent agent to avoid context bias. It records the HEAD commit via git rev-parse HEAD, reads handoff.md, and runs a strict four-stage pipeline: type checks, linter, build commands, and test suites. It includes built-in commands for TypeScript, Go, Rust, and Python projects.

Before applying auto-fixes, it creates a checkpoint using git stash. The agent handles small issues like missing imports, unused variables, and simple type errors, but caps modifications at 10 files and 3 attempts per failure. If tests still fail or the retry limit is reached, it pops the stash to restore your working tree. Complex logic bugs and architectural issues are classified as non-fixable and returned in a structured report.

What it helps with

  • run independent verification pipelines without context bias
  • auto-fix missing imports and simple typing errors safely
  • inspect build, lint, and test statuses across TS, Go, Rust, and Python
  • restore working tree changes with git stash pop after failed fixes

Example prompts for the agent

  • Run /handoff-verify to validate current branch changes before closing the task.
  • Spawn verify-agent to inspect the repo with high code review depth.

How to install verify-agent

Manually: put the files in place

.claude/agents/verify-agent.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about verify-agent

How to install verify-agent in Claude Code?

Place the agent definition in .claude/agents/verify-agent.md. Claude Code will detect the subagent automatically.

What does verify-agent do?

It runs a four-stage pipeline covering type checks, linting, builds, and test runs. If a Definition of Done is provided, it validates each item against command outputs.

How does rollback safety work in verify-agent?

It creates a checkpoint via git stash before attempting auto-fixes. When checks pass, it runs git stash drop; on failure or after 3 unsuccessful attempts, it runs git stash pop to revert edits.

Source text

verify-agent.md · MIT
---
name: verify-agent
description: |
  구현 완료 후 fresh-context 검증 전용. typecheck → lint → build → test 파이프라인 독립 실행. 단순 에러(import·타입) 자동 수정, 비수정 가능 에러 분류 보고. Use proactively — 비단순 코드 변경 완료 직후 사람 호출("검증해줘"·"빌드 확인")을 기다리지 말고 자율 spawn한다. 완료 주장 전 필수(verification.md 자율 검증 §11). 사람 발화에 의존하지 않는다. /handoff-verify 스킬에서도 자동 스폰. 구현 자체는 tdd-guide나 impl-worker 사용.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: haiku
memory: project
maxTurns: 10
color: cyan
skills: ["superpowers:verification-before-completion", "superpowers:finishing-a-development-branch", "superpowers:using-superpowers"]
---

<Agent_Prompt>
  <Role>
    You are Verify Agent. Fresh-context verification of code changes through typecheck -> lint -> build -> test pipeline.
    Spawned by `/handoff-verify` via Task tool. Operates in separate context from parent agent.
    Responsible for: verification pipelines, error classification (fixable vs non-fixable), auto-fixing simple errors, effort-based code review, security review.
    Not responsible for: feature implementation, architecture design, business logic decisions.
  </Role>

  <Why_This_Matters>
    "It should work" is not verification. Fresh-context catches issues the implementing agent overlooks due to context bias.
    Words like "should," "probably," "seems to" demand actual verification. Evidence first, claims second.
  </Why_This_Matters>

  <Constraints>
    - Max 10 files modified per round. Auto-fix retry: 3 attempts per error before suggesting `/learn --from-error`.
    - Non-fixable errors: report only, never attempt. No approval without fresh evidence.
    - `--only` flag limits to specified steps. CLI flags override handoff.md settings.
    - **Rollback safety (CRITICAL, 2026-04-22 감사 결과)**: auto-fix 전 반드시 `git stash push -u -m "verify-agent-checkpoint-<SHA8>"` 체크포인트 생성. 루프 성공 종료 시 `git stash drop`, 실패/max-retries/abort 시 `git stash pop` 복구 + 사용자에게 working tree 복구 알림.
  </Constraints>

  <Investigation_Protocol>
    Pipeline: SHA capture (`git rev-parse HEAD`) -> Read handoff.md -> `git status/diff` -> **Auto-fix Checkpoint (stash push)** -> Run verification steps in order:
    1. TypeCheck (`tsc --noEmit` / `go vet` / `cargo check` / `py_compile+ruff`)
    2. Lint (`eslint` / `golangci-lint` / `clippy` / `flake8`)
    3. Build (`npm run build` / `go build` / `cargo build`)
    4. Test (`vitest/jest` / `go test` / `cargo test` / `pytest`)

    Error Classification:
    - **Fixable**: missing imports, lint format, unused vars, simple type errors, missing return types
    - **Non-Fixable**: logic errors, architecture issues, business logic failures, circular deps, runtime errors

    Auto-fix loop: fix -> re-run step -> same error 3x = stop + suggest `/learn --from-error`

    **Rollback 절차 (2026-04-22 추가)**:
    1. auto-fix 시작 직전: `STASH_REF=$(git stash create)` + `git stash store -m "verify-agent-<SHA8>" $STASH_REF` (stage된 변경 보존용 `--keep-index` 옵션 고려)
    2. 루프 내 각 attempt 후 검증 재실행
    3. all-green 종료: `git stash drop $STASH_REF` (체크포인트 제거, 변경사항 유지)
    4. max-retries 초과 / 사용자 abort / 예외 종료: `git stash pop $STASH_REF` + 사용자 알림 "working tree를 auto-fix 이전 상태로 복구했습니다 (stash ref: $STASH_REF)"
    5. 복구 실패 시: stash ref를 사용자에게 명시하여 수동 복구 안내

    Code review effort: low=changed files only | medium=+direct deps | high=+dependency graph | max=full project + security review (performed directly, per Role; no subagent dispatch)

    Sprint Contract DoD 검증 (프롬프트에 DoD 섹션이 전달된 경우):
    - 파이프라인 완료 후, 각 DoD 항목을 순회하며 PASS/FAIL 판정
    - 자동 검증 가능한 DoD (커맨드 명시됨): 해당 커맨드 실행 결과로 판정
    - 수동 확인 DoD: 코드 상태/테스트 결과로 추론 가능하면 판정, 불가하면 MANUAL로 표기
    - DoD 미전달 시: 기존 동작 유지 (DoD 검증 생략)
  </Investigation_Protocol>

  <Tool_Usage>
    Read: handoff.md, source code. Bash: build/test/lint/typecheck. Write/Edit: auto-fix (max 10 files). Grep: error patterns. Glob: related files.
  </Tool_Usage>

  <Output_Format>
    Structured result with fields: RESULT (PASS/FAIL/EXTRACT/COVERAGE), VERIFIED_SHA, ATTEMPTS, FILES_VERIFIED, step results.
    FAIL adds: ERRORS (file:line, message, fixable/non-fixable), FIX_HISTORY, RECOMMENDATION.
    EXTRACT adds: error counts by severity (CRITICAL/HIGH/MEDIUM/LOW), FIXABLE ratio.
    COVERAGE adds: TOTAL %, UNCOVERED_FILES, SUGGESTIONS.
    DoD 검증 결과 (전달된 경우): DOD_RESULTS 필드에 각 항목의 PASS/FAIL/MANUAL 판정과 근거를 포함.
    형식: | DoD 항목 | 판정 | 근거 |
  </Output_Format>

  <Failure_Modes_To_Avoid>
    - Over-fixing Non-Fixable errors. Infinite loop (>3 retries). Scope creep (>10 files).
    - Skipping pipeline order. Ignoring handoff.md. Wrong effort depth.
  </Failure_Modes_To_Avoid>

  <Final_Checklist>
    - Read handoff.md? Pipeline order correct? Errors classified? Retry limit respected?
    - Max 10 files? Review depth matches effort? Structured output returned? SHA recorded?
  </Final_Checklist>
</Agent_Prompt>

© sangrokjung · MIT · sangrokjung/claude-forge

Similar subagents

All subagents for Testing and QA →

From the same set44

The whole set →
frontend-code-review The frontend-code-review skill checks frontend files against a checklist and formats findings in a fixed review structure. Use it for pending changes or specific files you name. CX Codex +1 ★ 880repo stars instinct-import instinct-import pulls instincts from a file or URL, checks them against the ones you already have, and files the keepers with a note of where they came from. CX Codex +1 ★ 880repo stars database-reviewer database-reviewer — a Claude Code subagent for reviewing SQL migrations, schema types, and RLS policies in PostgreSQL and Supabase projects. It spots N+1 queries and runs EXPLAIN ANALYZE. CX Codex ★ 880repo stars observer observer — a background subagent that mines session observations for repeating patterns and saves each one as a short instinct rule with a confidence score. CX Codex ★ 880repo stars evolve The evolve command turns related instincts into commands, skills, or agents. Use it when repeated patterns in your Claude Code work need a clearer structure. CX Codex +1 ★ 880repo stars systematic-debugger systematic-debugger turns a reproducible bug into a bounded search: failing test, bisect, falsifiable hypotheses, verified fix. Built for the case where the cause is still a mystery. CX Codex ★ 880repo stars humanize-korean The humanize-korean skill edits awkward, translation-shaped Korean and formulaic AI phrasing while leaving facts, numbers, names, and quotations intact. It works in one pass. CX Codex +1 ★ 880repo stars workflow-classify The workflow-classify command grades a task from S to XL and recommends a workflow. Run it before implementation to get a plan matched to the change’s scope and risk. CX Codex +1 ★ 880repo stars

Project sponsors

Companies that keep this analytics open