Claude Code 스킬로 검증 루프 구축하기

대부분의 에이전틱 코딩 세션은 하나의 루프를 따릅니다. 변경을 요청하면 Claude가 컨텍스트를 수집하고, 작업을 실행하고, 결과를 검증한 뒤, 필요하다면 다시 컨텍스트 수집 단계로 돌아갑니다.

검증은 에이전트가 응답하기 전에 자신의 작업을 확인하는 과정입니다. Claude는 이미 코드베이스 내의 결정론적 신호, 즉 타입 체커, 린터, 테스트, 런타임 오류 등을 관찰해 일부 검증을 수행합니다. Claude가 스스로 파악하지 못하는 부분은 결국 개발자가 직접 기능을 확인하는 단계로 남게 됩니다.

하지만 이런 수동 확인 단계도 검증 루프로 전환할 수 있습니다. Claude Code에서 검증 루프란 Claude가 작업 결과를 확인하고 수정을 시도하는 반복 프로세스를 말합니다.

이 글에서는 가장 일반적인 검증 루프 유형을 소개하고, Anthropic 내부에서 실제로 사용하는 방식을 보여드립니다. 그리고 평소에 직접 수행하던 확인 작업을 스킬로 전환해, Claude가 스스로 피드백 루프를 완성하고 반복 작업을 처리하는 동안 다른 일에 집중할 수 있는 방법을 알아봅니다.

기본 제공 검증 루프

커스텀 검증 루프 설계에 앞서, Claude가 기본으로 지원하는 다양한 검증 루프를 파악해두면 도움이 됩니다. 대표적인 기능과 활용 방식은 다음과 같습니다.

• /verify 스킬: 애플리케이션을 빌드하고 실행해 변경 사항을 확인합니다.
• 툴체인: Claude는 린터 등 제공된 모든 도구의 오류 코드와 경고를 감지해 대응합니다. CLAUDE.md에 빌드 및 테스트 명령어를 명시해두면 Claude가 추론할 필요 없이 바로 활용할 수 있어 좋습니다.
• 코드 리뷰 (리서치 프리뷰): 활성화된 저장소의 PR에 자동으로 리뷰를 수행하는 관리형 멀티 에이전트 서비스입니다. 발견된 문제를 직접 수정해 푸시하거나, 해당 코멘트에 @claude를 멘션해 루프를 자동으로 닫을 수 있습니다(GitHub Actions를 미리 설정한 경우).
• GitHub Actions: 검증 스킬을 실행하는 작업을 정의해두면, 로컬에서 실행하던 것과 동일한 검사가 모든 푸시나 PR마다 자동으로 실행됩니다.
• 스펙 검증: 저장소 내 마크다운 스펙을 기준으로 각 변경 사항을 검증하고, 위반 사항을 수정하는 스킬입니다.
• Claude Managed Agents의 루브릭 (베타): 별도의 그레이더 에이전트가 루브릭을 기준으로 결과를 검증하는 관리형 에이전틱 서비스입니다. 검증에 실패하면 자동으로 재작업 루프가 시작됩니다.

검증 루프 작성하기

기존 프로젝트에서 Claude가 새 기능을 구현할 때마다 똑같은 수정을 반복하고 있다면, 이제 그 과정을 커스텀 검증 루프로 만들 때입니다. 첫 번째 단계는 매번 반복하는 작업을 빠짐없이 적어보는 것입니다.

새 프로젝트를 시작하며 프로젝트의 동작 방식을 정립해야 하는 경우도 마찬가지입니다. 신규 팀원에게 첫날 전달하듯, 모범 사례를 평문으로 작성해두세요.

검증 항목 자체를 어떻게 표현해야 할지 막막하다면, 먼저 Claude에게 모범 사례를 물어보고 거기서 수정해나가는 방법도 있습니다. 일반적인 내용에서 달라지는 몇 가지 지점, 바로 그 차이가 핵심적으로 담아야 할 내용입니다.

Pro tip: 검증 항목이 반드시 정성적일 필요는 없습니다. "백필 단계 없이 컬럼을 삭제하는 마이그레이션은 거부한다"처럼 결정론적인 규칙도 충분히 해당됩니다. 범용 린터로는 잡을 수 없지만, 프로젝트 전용 린터라면 잡아낼 수 있는 규칙이죠. 직접 반복해서 수동으로 적용하던 확인 작업이라면 무엇이든 루프로 전환할 자격이 있습니다.

스킬로 만들기

반복되는 단계를 검증 루프로 만드는 가장 일반적인 방법은 스킬로 작성하는 것입니다. 스킬을 가장 빠르게 만들려면 skill-creator 플러그인을 설치한 뒤 Claude의 인터뷰를 따라가면 됩니다.

예시:

/skill-creator Create a skill for verifying frontend changes end-to-end. Interview me about my workflow.

물론 직접 작성하는 방법도 있습니다. 프로젝트 내 .claude/skills/ 디렉터리에 마크다운 파일을 추가하면 됩니다. 가장 단순한 검증 스킬은 몇 줄의 프론트매터와 본문으로 구성됩니다.

# .claude/skills/verify-log-hygiene/SKILL.md
---
name: verify-log-hygiene
description: Check that error logs include the request ID and never
  include the request body. Use 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 any user-supplied payload.

Report each violation with file:line, then fix it: add the request ID
where it's missing and strip the payload from the log call.

전체 스키마와 설계 철학은 스킬 구축 완전 가이드에서 확인할 수 있습니다.

실행 환경에 맞는 검증 방식 선택하기

다음으로는 검증 루프가 어떻게 시작될지, 즉 독립 실행, 임베디드, 체인, PR 연동 중 어떤 방식을 택할지 결정해야 합니다.

독립 실행 (Standalone)

결과물이 생성된 뒤 직접 호출하는 방식입니다. 모든 상황에 적용되지는 않지만 필요할 때 꺼내 쓸 수 있는 횡단 관심사 검사에 적합합니다. 커밋 전 보안 스캔, PR 전 접근성 감사, 저장소 전체의 라이선스 헤더 검증 등이 대표적입니다. 다양한 워크플로에서 활용하고 싶지만, 코드 변경마다 자동으로 실행되는 것은 원하지 않는 경우에 유용합니다.

단, 매번 직접 실행해야 한다는 부담이 있습니다. 모든 변경 후 반복적으로 실행하게 된다면, 독립 실행 방식의 한계에 도달한 것입니다. 그 시점이 오면 임베디드나 체인 방식으로 전환할 때입니다.

임베디드 (Embedded)

생성 스킬의 일부로 자동 실행되는 방식입니다. 특정 워크플로에 종속된 검사이며, 이제 워크플로가 별도 요청 없이 검사를 직접 실행합니다.

가장 간단한 방법은 생성 스킬의 본문 끝에 한 줄을 추가하는 것입니다.

# .claude/skills/scaffold-component/SKILL.md
---
name: scaffold-component
description: Scaffold a new React component under src/components/, including the component file, its co-located test, and an index export. Use when the user asks to create a new component.
allowed-tools: [Read, Write, Edit, Bash, Glob]
---

# Scaffold a new React component

Given a component name (PascalCase), create the following under `src/components/<Name>/`:

1. `<Name>.tsx`: function component with a typed props interface and a default export.
2. `<Name>.test.tsx`: React Testing Library test that renders the component and asserts it mounts without throwing.
3. `index.ts`: re-export the default and any named exports.

Follow the patterns in `src/components/Button/` as the reference. Match the import alias style (`@/components/...`) used throughout the codebase.

# code continues...

After creating the component file, run eslint on it and
address any errors before reporting completion.

임베드가 제대로 동작하는지 확인하려면, 새로운 태스크에서 스킬을 호출해 추가한 단계가 출력 결과의 일부로 실행되는지 확인하세요. 실행되지 않는다면 스킬의 설명이나 앞선 지시사항이 추가된 검사를 불러오지 못하는 것입니다.

임베디드 방식은 직접 작성했거나 프로젝트 수준에서 설치해 SKILL.md 파일을 직접 제어할 수 있는 스킬에만 적용할 수 있습니다. 기본 제공 스킬이나 업데이트 시 덮어씌워지는 플러그인 관리 스킬에는 이 방식을 사용할 수 없으며, 그런 경우에는 체인 방식을 활용하세요.

여러 워크플로에 걸친 검사라면 임베디드보다 독립 실행 방식이 적합합니다. 어떤 컨텍스트에서도 자유롭게 호출할 수 있어야 하기 때문입니다.

체인 (Chained)

하나의 스킬이 끝날 때 다른 스킬을 호출하며, 검증된 여러 단계가 end-to-end로 이어지는 방식입니다.

Anthropic의 Claude Code 팀도 이 방식을 일상적으로 활용합니다. /code-review로 버그를 찾고, /simplify로 diff를 정리하고, /verify 스킬로 전체 동작을 확인합니다. 그리고 UI 관련 변경이 있으면 DESIGN.md의 가이드라인을 기준으로 커스텀 /design 스킬이 추가로 검사를 수행합니다.

수정할 수 없는 스킬에 검증을 추가할 때도 체인 방식이 유용합니다. 아래처럼 원본 스킬을 호출한 뒤 검증 스킬을 이어서 실행하는 커스텀 래퍼 스킬을 만들면 됩니다.

# .claude/skills/safe-refactor/SKILL.md
Run /simplify on the current diff first.
When /simplify finishes, invoke /verify-no-public-api-changes.

"/simplify 실행 후 항상 /verify를 돌린다"는 개인 습관이 "/simplify 완료 시 /verify가 자동으로 실행된다"는 약속으로 바뀝니다. 이제 체인이 전체 개발 사이클을 알아서 처리하며, 개발자는 에스컬레이션이 발생할 때만 개입하면 됩니다.

단계들이 서로 독립적이어서 개별로 실행하고 싶은 경우라면 체인 방식을 굳이 사용할 필요는 없습니다. 체인은 유연성을 줄이는 대신 자동화를 얻는 방식이기 때문입니다. 또한 체인된 검증 루프는 토큰 소비를 늘릴 수 있으므로, 팀 전체에 배포하기 전에 충분히 테스트해보는 것이 좋습니다.

모든 PR에 적용하기

본인의 변경에서 체인이 안정적으로 동작한다면, 동일한 프로세스를 모든 PR에 적용할 수 있습니다. 팀원의 변경도 개인 변경과 동일한 검증 단계를 통과하게 되며, 체인을 직접 호출했는지 여부는 중요하지 않습니다. 이 인프라는 이미 작성한 체인에서 한 발짝 더 나아간 것입니다. 동일한 스킬, 동일한 루브릭, 동일한 기준이 작성자의 주의력과 무관하게 일관되게 적용됩니다.

여기서부터 검증은 개인 인프라를 넘어 팀 인프라가 됩니다. 매주 2분을 아끼려고 작성했던 검사가 이제는 모든 변경에서 팀원 모두의 2분을 아껴줍니다. 체인이 아직 변경 중이라면 PR 전체 게이트 적용은 잠시 미루세요. 수정 사항 하나하나가 팀 전체에 노출되는 이벤트가 되기 때문입니다.

프로세스에 익숙해지면 이제 루프 엔지니어링을 본격적으로 확장할 준비가 된 것입니다. 무엇을 자동화하든, 어떤 환경에서 실행하든 검증 루프를 만드는 과정은 언제나 동일합니다.

1. 이번 주 가장 자주 반복한 수동 후속 작업 하나를 골라보세요.
2. 먼저 기본 제공 /verify 스킬을 사용해보고 작업 흐름에 도움이 되는지 확인하세요.
3. 신규 팀원에게 첫날 전달하듯, 절차를 평문으로 작성해보세요.
4. skill-creator에 전달하거나, .claude/skills/ 디렉터리에 마크다운 파일을 직접 추가하세요.
5. 새 태스크에서 스킬을 호출해 검사가 출력 결과에 포함되는지 확인하고, 필요하면 반복해서 개선하세요.
6. 스킬 체인을 실험해 end-to-end 검증 흐름을 만들어보세요.

Claude에게 더 많은 것을 명확히 지정할수록, 첫 번째 응답이 원하는 결과에 더 가깝게 나올 가능성이 높아집니다. 더 이상 손댈 필요 없는 수정 작업들이 사라지면, 그 집중력은 어떤 스킬로도 대신할 수 없는, 오직 사람만이 할 수 있는 고유한 작업에 쏟을 수 있습니다.

검증 루프 시작하기 Claude Code.

이 글은 Claude Code 팀 소속 Delba de Oliveira가 작성했습니다.