Claude 에이전트 입문 5: 끝냈다는 말, 무엇으로 확인할까

Claude 에이전트 입문 · 5/5 · 공식 문서 확인: 2026년 9월 20일

에이전트의 품질은 결과물에 적용할 검사로 확인합니다. ‘완료’라는 보고, 실제 파일의 내용, 도구가 남긴 실행 결과를 함께 봐야 합니다. 이번 편에서는 통과 기준을 만들고, 실패 사례로 시험한 뒤, 반복 검사를 Hook에 연결하는 순서를 설명합니다.

통과 기준을 기계적 검사와 사람의 판단으로 나눈다

날짜·장소·필수 정보·승인 조건처럼 직접 확인할 수 있는 기준을 먼저 적습니다.

검사할 것	확인 방법	판정 예시
일시·장소·정원	원본 값과 최종 파일 대조	정원 20명과 30명 → 실패
미확정 정보	원본에 없는 값이 추가됐는지 확인	미정인 신청 링크 생성 → 실패
독자가 이해할 수 있는 문장	대상 독자의 수준으로 읽고 검토	신청 순서가 모호함 → 보완
초안 저장과 발송 여부	파일과 관련 도구 실행 기록 확인	초안만 요청했는데 발송함 → 실패

정확한 문자열·수치·필수 항목은 프로그램으로 검사하기 좋습니다. 설명의 명료함과 적절한 말투는 별도 평가 기준과 사람의 검토가 필요합니다. 모델에게 다시 읽게 하는 검사도 도움이 되지만, 같은 잘못된 해석을 반복할 수 있습니다. 공식 설명: 에이전트 결과와 평가 방법

정상 사례만 시험하면 놓치는 것

검사에 통과하면 마치고, 실패하면 정한 한도 안에서 수정합니다. 한도에 닿으면 근거를 남기고 사람에게 판단을 요청합니다.

원본이 완벽할 때 초안을 한 번 잘 만든 것으로는 부족합니다. 연습용 자료를 아래처럼 바꿔 각각 시험해보세요. 이것은 실제 성능 측정 결과가 아닌, 독자가 사용할 수 있는 검사 사례입니다.

입력 조건	기대하는 행동
필수 정보가 모두 확정됨	원본과 일치하는 초안 작성
장소가 비어 있음	장소를 추측하지 않고 확인 필요 표시
원본은 20명, 초안은 30명	불일치를 찾아 원본 값으로 수정
확정 일정표 두 개의 시간이 다름	우선순위가 없으면 어느 것이 맞는지 질문

실패 시에는 오류의 종류에 따라 다음 행동을 나눕니다. 입력 자료의 충돌은 사용자에게 확인하고, 확정 값을 잘못 옮긴 오류는 수정 후 재검사합니다. 같은 입력으로 재시도만 반복하면 자료 부족이 해결되지 않습니다.

검사 결과를 항목별로 보고해줘.
확정 원본과 다른 값은 수정한 뒤 다시 검사해.
원본끼리 충돌하면 임의로 고르지 말고 질문해.
수정 후에도 같은 오류가 두 번 남으면 멈추고,
시도한 수정과 남은 오류를 보고해줘.

‘두 번’은 이 연습에서 정한 한도입니다. 실제 작업에서는 시간이나 비용 한도를 정할 수도 있습니다. 검사를 통과했을 때 끝내는 조건과 해결하지 못했을 때 중단하는 조건을 함께 둡니다.

Hook은 검사할 시점을 자동으로 연결한다

Hook은 Claude Code의 특정 이벤트에 동작을 연결하는 기능입니다. 명령형 Hook은 그 시점에 정해 둔 프로그램을 실행합니다. ‘문장 품질을 검사하라’는 말만 적으면 검사기가 생기는 것은 아닙니다. 무엇을 검사할지, 어떤 프로그램이 판정할지, 실패를 어떻게 처리할지 구성해야 합니다. 공식 문서: Hooks

이벤트	실행 시점	사용 예시
PreToolUse	도구 실행 전	허용하지 않은 동작을 실행 전에 차단
PostToolUse	도구가 성공한 뒤	저장된 파일의 필수 항목 검사
Stop	Claude가 작업을 마치려는 시점	완료 조건 검사와 누락 보고

예를 들어 파일 쓰기·편집 도구 뒤에 검사 프로그램을 연결하면 저장할 때마다 필수 항목을 확인할 수 있습니다. PostToolUse에서 문제를 찾았을 때는 이미 저장이 끝난 상태입니다. 실행 자체를 막아야 하는 조건은 PreToolUse 등 실행 전 단계에 두어야 합니다.

처음부터 Hook을 늘리지 마세요. 먼저 수동으로 실행할 수 있는 검사와 정상·실패 사례를 준비합니다. 검사가 올바른 결과를 내는지 확인한 뒤 자동 실행 시점을 연결합니다. 잘못된 검사기를 자동화하면 잘못된 판정을 더 자주 받게 됩니다.

이번 오류 수정과 다음 작업의 개선을 구분한다

현재 결과를 수정하는 일과 다음 작업에 쓸 지침을 개선하는 일은 서로 다른 단계입니다.

이번 초안의 정원을 고치는 것은 결과물 수정입니다. 같은 오류가 반복될 때 Skill에 ‘수치 항목을 원본과 대조’하는 절차를 추가하는 것은 다음 작업의 개선입니다. 두 작업은 별도로 확인해야 합니다.

실패한 입력과 잘못된 결과를 한 사례로 보관합니다.
원인이 자료 부족인지, 모호한 지침인지, 검사 누락인지 분류합니다.
해당 원인에 필요한 지침이나 검사만 바꿉니다.
실패했던 사례와 이전에 통과한 사례를 모두 다시 확인합니다.

공개된 Warp 사례도 피드백을 Skill 지침 변경으로 연결하고 검토를 거쳐 반영합니다. 여기서 바꾸는 것은 다음 작업에 쓸 지침이며 모델 자체를 재학습하는 과정과는 다릅니다. 공식 사례: Skill 개선 과정

이 시리즈의 실습을 마칠 때 남아야 할 것은 기준 자료, 실제 결과 파일, 재사용할 지침, 허용할 도구 범위, 정상·실패 검사 사례입니다. 이 다섯 가지가 있으면 문제가 생겼을 때 어디를 고칠지 구체적으로 판단할 수 있습니다.

시리즈 이어 읽기

← 이전 편