클로드 코드로 AI가 자기 결과물을 검사하게 만들기

며칠 전에 앤트로픽이 클로드 코드에서 검증 루프를 만드는 공식 가이드를 냈어요. 검증 루프라는 말이 좀 낯선데, 클로드한테 뭔가를 시킨 다음 그 결과가 기준에 맞는지 검사하는 일까지 클로드한테 맡기는 구조예요. 일을 시키는 것까지는 다들 하는데, 그 검사를 사람이 아니라 클로드가 스스로 하게 만든다는 게 이 가이드의 핵심이더라고요.

저는 이 대목에서 좀 찔렸어요. 저는 클로드한테 원고를 시킬 때마다 나온 걸 제 눈으로 읽고, 과장된 표현은 없는지 앞 문장이랑 골격만 같고 숫자만 바꾼 데는 없는지 매번 다시 짚어줬거든요. 고쳐 오면 또 읽고 또 짚어주고요. 클로드한테 일은 넘겼는데 검사는 여전히 제 몫이었어요.

그런데 이 가이드대로면 그 반려 사유를 한 번만 파일에 적어두면 돼요. 그다음부터는 클로드가 결과를 낼 때마다 그 파일을 스스로 돌려보고, 걸리는 데를 고친 뒤에 통과한 것만 저한테 올려요. 가이드 표현을 빌리면 사람은 뭔가 문제가 커져서 자기한테 올라올 때만 손을 대고요. 이 구조가 뭔지부터 오늘 제 작업에 심는 법까지 찾아본 걸 풀어볼게요.

클로드 코드가 일하는 세 단계

클로드가 뭔가를 처리하는 방식은 원래 세 단계가 도는 고리예요. 필요한 정보를 모으고, 실제로 코드를 고치거나 글을 쓰고, 그 결과가 맞는지 확인하는 순서죠. 가이드는 이 세 번째 확인하는 자리를 눈여겨봐요.

사람이 도맡던 세 번째 칸, 검증

앞의 두 단계는 원래 클로드가 알아서 해요. 문제는 세 번째인데, 지금까지 이 자리는 대부분 제가 채웠어요. 제가 결과를 읽어보고 맞다 아니다를 판단하는 식이었거든요.

가이드는 이 판단을 매번 사람이 하지 말라고 해요. 기준을 미리 정해두고 클로드가 스스로 대조하게 만들라는 거고요. 검증을 사람 눈이 아니라 미리 정해둔 기준에 맡기는 게 검증 루프의 전부예요.

판정이 분명한 일은 클로드 몫

이게 되는 이유는 맞다 틀리다가 딱 나뉘는 신호가 있어서예요. 코드 쪽에는 타입 검사기나 린터, 테스트처럼 결과가 분명하게 나오는 도구가 있거든요. 린터는 코드가 정해둔 규칙을 어겼는지 자동으로 짚어주는 도구고요. 이런 신호가 있으면 클로드가 자기 결과를 스스로 대조해서 틀린 데를 고치고 다시 돌려볼 수 있어요.

꼭 대단한 검사만 되는 것도 아니에요. 가이드는 지울 데이터를 미리 옮겨두는 단계 없이 데이터 칸을 통째로 지우는 변경은 거부한다는 식으로, 판정이 딱 떨어지는 규칙 하나도 훌륭한 검증이라고 봐요. 애매한 취향을 다루는 검사가 아니어도 이 자리에 들어올 자격이 있다는 거죠.

검증 기준은 스킬 파일에 문장으로

여기서 제일 마음에 든 건, 이 검증 기준을 대단한 코드로 짜는 게 아니라는 점이었어요. 그냥 평범한 문장으로 적어요.

이름, 설명, 도구가 담긴 맨 위 세 줄

스킬은 .claude/skills 폴더에 두는 파일 한 장이에요. 스킬이 뭔지는 지난 편에서 따로 다뤘는데, 클로드가 필요할 때 꺼내 쓰는 작업 설명서라고 보면 돼요.

이 파일 맨 위에 정해진 칸 세 개가 있어요. 스킬 이름, 이 스킬을 언제 꺼낼지 알려주는 설명, 그리고 이 스킬이 쓸 수 있는 도구 목록이고요. 이 세 줄을 프런트매터라고 부르는데, 클로드가 이 스킬을 언제 펼칠지 정하는 이름표인 셈이에요. 그 아래로는 검사 절차를 그냥 말로 풀어 써요.

가이드가 든 예시를 옮기면 이런 모양이에요.

---
name: verify-log-hygiene
description: 에러 로그에 요청 ID가 들어갔는지, 요청 본문은 안 들어갔는지 점검. 로그나 에러 처리 코드가 바뀌면 사용.
allowed-tools: [Read, Edit, Grep]
---
지금 바뀐 부분에서 에러를 처리하는 경로의 로그를 읽는다.
로그마다 요청 ID가 있는지, 요청 본문이나 헤더 같은 사용자 입력이 딸려 들어가진 않았는지 확인한다.
어긋난 데는 파일과 줄 번호로 짚고, 그 자리를 고친다.

보면 조건문 하나 없이 한국어로 옮겨도 될 문장들이에요. 무엇을 통과로 볼지, 걸리면 어떻게 고칠지를 말로 적어둔 게 전부고요.

매번 하던 반려 사유가 곧 규칙

이 방식이 반가웠던 건, 제가 이미 채팅으로 매번 말하던 반려 사유가 곧 이 문장들이라서예요. 출처 없이 단정하지 말라거나, 앞 문장이랑 골격만 같고 숫자만 바꾼 복붙은 안 된다거나, 소제목을 두 절씩 뭉쳐 장황하게 늘어놓지 말라거나 하는 걸 그 자리에 적으면 그대로 검사 스킬이 돼요. 매번 눈으로 잡아내던 걸 굳이 셀 수 있는 숫자로 바꾸지 않아도 된다는 게 이 방식의 장점이에요. 다만 애매한 취향까지 다 문장으로 잡히진 않아서, 저는 딱 떨어지는 반려 사유부터 적고 미묘한 흐름은 여전히 제 눈에 남겨둬요.

검사를 거는 네 가지 자리

같은 검사 스킬이라도 언제 돌게 하느냐를 네 가지로 걸 수 있어요. 가이드가 정리해준 순서대로 볼게요.

따로 부르기, 기억해야 하는 부담

평소엔 가만히 있다가 제가 필요할 때 직접 부르는 방식이에요. 보안 점검이나 접근성 확인처럼 매번 돌릴 필요는 없고 가끔 교차로 보는 것들에 맞고요. 단점은 부르는 걸 제가 기억해야 한다는 거예요. 바쁘면 한 번씩 빼먹기 쉽죠.

만드는 스킬에 심기, 안 시켜도 딸려오는 검사

뭔가를 만드는 스킬 맨 끝에 검사를 자동으로 붙이는 방식이에요. 예를 들어 화면 요소를 만드는 스킬 끝에 만든 파일에 린터를 돌리고 오류를 고친 뒤 끝내라고 한 줄 붙이면, 제가 따로 시키지 않아도 검사가 딸려서 돌아요. 이건 제가 직접 만든 스킬에만 되고, 남이 만들어 배포한 스킬은 못 건드려요.

스킬끼리 잇기, 한 번에 끝까지

한 스킬이 끝나면 다음 스킬을 부르는 방식이에요. 가이드가 든 예를 옮기면, 버그를 잡는 스킬로 훑고, 지저분한 부분을 정리하는 스킬로 다듬고, 실제로 동작하는지 확인하는 스킬을 거친 뒤, 직접 만든 가이드라인 대조 스킬로 마무리해요. 하나가 끝날 때 다음이 자동으로 물려서 검사된 결과가 쭉 이어지는 거고요.

모든 PR에 같은 게이트

체인이 무르익으면 같은 절차를 팀 전체에 걸 수 있어요. PR은 바꾼 코드를 합치기 전에 검토받는 단계인데, 여기에 검사를 걸어두면 누가 올리든 제가 통과한 것과 똑같은 관문을 지나요. 팀 표준을 각자의 성실성에 기대지 않고 배관으로 박아두는 셈이죠.

개인 작업이라면 두 번째, 만드는 스킬에 심기부터 시작하는 게 실패가 제일 적어요. 가이드도 체인이 아직 자주 바뀌는 동안엔 팀 전체 관문부터 세우진 말라고 하고요.

오늘 만드는 첫 검사 스킬

그럼 이걸 실제로 어떻게 시작하냐면, 저는 세 단계로 접근했어요.

반복한 지적 세 개 고르기

지난 대화를 떠올려 보면, 제가 클로드한테 똑같은 지적을 반복하고 있는 게 분명 있어요. 저는 원고에서 출처 없이 단정하지 말라는 것, 앞 문장이랑 골격만 같고 숫자만 바꾸지 말라는 것, 소제목을 두 절씩 뭉치지 말라는 것 이 세 개를 제일 자주 말하고 있더라고요. 처음부터 다 적을 필요 없이 제일 자주 걸리는 것부터 골라요.

스킬 파일 한 장에 문장으로

그 세 개를 아까 그 파일 형식에 그대로 옮겨요. 맨 위에 이름이랑 설명 한 줄, 그 아래에 이러이러하면 반려하고 걸린 데는 파일과 줄로 짚어 그 자리만 고치라고 말로 적는 거고요. 없던 규칙을 새로 만드는 게 아니라, 제가 이미 매번 하던 말을 문장으로 굳히는 것뿐이에요.

만드는 스킬 끝에 한 줄

처음부터 거창하게 팀 전체에 걸 필요 없어요. 원고 쓰는 스킬 맨 끝에 끝내기 전에 이 검사 스킬을 돌리고 걸리면 그 구간만 고치라고 한 줄 붙이는 걸로 충분하고요. 이게 아까 네 가지 중 두 번째 방식이고 개인 작업엔 이게 제일 덜 깨져요. 저는 사실 예전부터 원고를 저장하면 자동으로 도는 점검 하나를 쓰고 있었는데, 이번 가이드를 보고서야 이게 그 패턴이었구나 싶었어요.

검사까지 넘긴 뒤 남는 사람 몫

정리하면, 검증 루프는 새 기술이라기보다 태도에 가까워요. 클로드한테 일은 시키면서 검사는 내가 붙들고 있던 걸, 검사 기준까지 문장으로 넘겨서 클로드가 스스로 통과할 때까지 고치게 두는 거거든요. 그러면 저는 같은 지적을 반복하는 대신, 정말 판단이 필요한 문제가 올라올 때만 손을 대면 돼요.

솔직히 저도 이걸 체계적으로 정리해서 쓰던 건 아니에요. 점검 하나 걸어두고도 절반은 여전히 눈으로 다시 보고 있었거든요. 이번 가이드 덕에 그동안 채팅에 흩어져 있던 반려 사유를 한 파일로 모아야겠다는 생각이 들었어요.

혹시 클로드한테 똑같은 지적을 세 번 넘게 반복한 적이 있다면, 그 한 문장을 오늘 스킬 파일에 옮겨보시길 권해요. 저는 그 한 줄부터 시작해볼 참인데, 어떤 지적을 제일 먼저 넘기게 될지 저도 궁금하네요.

검증 스킬이 취향까지 잡아주나요

그건 아니에요. 맞다 틀리다가 딱 나뉘는 규칙은 잘 잡는데, 미묘한 취향이나 글의 흐름은 여전히 사람 몫이더라고요. 그래서 저는 명확한 반려 사유부터 넘기고, 애매한 건 제 눈에 남겨두는 쪽으로 나눠요.

코드를 몰라도 만들 수 있나요

검사 기준 자체는 코드가 아니라 문장이라 적는 건 어렵지 않아요. 다만 스킬 파일을 만들고 거는 건 클로드 코드라는 도구를 쓰는 일이라, 앞선 편에서 다룬 설치랑 기본 세팅은 먼저 해두는 게 편하고요.