Claude Code의 검증 루프(verification loop)는 에이전트가 코드를 바꾼 뒤 테스트, 린트, 런타임 확인, 프로젝트별 체크를 실행하고 실패하면 다시 고치는 반복 구조다. Anthropic은 이 수동 점검 절차를 Skills로 포장하면 매번 사람이 기억하지 않아도 같은 검증을 재사용할 수 있다고 설명한다.
무엇을 Skill로 만들까
좋은 후보는 “매번 사람이 직접 확인하던 것”이다. 예를 들어 로그에 request ID가 빠졌는지, 마이그레이션이 backfill 없이 컬럼을 삭제하는지, 프론트엔드 변경이 접근성 기준을 깨뜨리는지 같은 규칙은 일반 linter가 모를 수 있다. 이런 규칙을 자연어 절차와 실행 명령으로 적으면 Claude Code가 작업 후 같은 루프를 반복할 수 있다.
네 가지 실행 방식
| 방식 | 언제 쓰나 | 예시 |
|---|---|---|
| Standalone | 필요할 때 명시적으로 호출 | 보안 점검, 라이선스 헤더 검사 |
| Embedded | 특정 생성 Skill 끝에 항상 실행 | React 컴포넌트 생성 후 eslint 실행 |
| Chained | 한 Skill이 다른 Skill을 이어 호출 | 코드 리뷰 → 단순화 → 검증 |
| PR gate | GitHub Actions 등에서 모든 PR에 실행 | 팀 공통 품질 기준 검증 |
처음부터 PR gate로 올리기보다 standalone으로 절차를 안정화하고, 반복 호출이 자연스러워지면 embedded나 chained로 옮기는 편이 낫다.
가장 작은 Skill 예시
name: verify-log-hygiene
description: Check error logs when the diff touches error handling or logging.
allowed-tools: [Read, Edit, Grep]
Read the error-handling paths in the current diff.
For each log call on an error path, confirm it includes the request ID
and does not pass the request body, headers, or user-supplied payload.
Report each violation with file:line, then fix it.핵심은 “검사한다”에서 끝내지 않고, 실패 시 어떤 파일을 읽고 어떤 수정까지 해야 하는지 명시하는 것이다. Skill은 모델에게 명령 하나를 주는 파일이 아니라, 팀의 반복 점검 절차를 압축한 운영 문서에 가깝다.
설계 팁
CLAUDE.md에 빌드, 테스트, 린트 명령을 정확히 적어 추론 비용을 줄인다.- 검증 기준을 모호한 선호가 아니라 관찰 가능한 실패 조건으로 쓴다.
- Skill이 너무 자주 실행되어 토큰 비용이 커지면 standalone으로 남긴다.
- UI, 보안, 데이터 마이그레이션처럼 일반 도구가 못 잡는 프로젝트 규칙부터 Skill화한다.
- 새 Skill은 실제 변경 작업에 붙여 호출해 보고, 검증 단계가 빠지지 않는지 확인한다.
언제 유용한가
- 개인이 매번 같은 리뷰 코멘트를 남긴다.
- 팀의 암묵지가 문서화되어 있지 않아 에이전트 결과 품질이 들쭉날쭉하다.
- CI는 통과하지만 제품 관점에서는 깨진 결과가 자주 나온다.
- agent-skills와 claude-code를 이미 쓰고 있고, 워크플로를 더 자동화하고 싶다.
관련 문서
- claude-code — 터미널에서 동작하는 Anthropic의 AI 코딩 에이전트
- agent-skills — AI 에이전트의 능력을 확장하는 스킬 시스템
- agent-skills-tips-pitfalls — 스킬 작성·리뷰에서 자주 나오는 실수
- ai-code-review-tips-agentic — AI 코드 리뷰를 에이전틱하게 운영하는 방법
- ai-agent-tips-loop-engineering — 루프 엔지니어링 설계법
참고 자료
- Building verification loops in Claude Code with skills — Anthropic Blog (2026-07-22)