AX 팁 11 — 근거 없는 「모두 통과」 되돌리기

작성

  • AX 팁
  • Claude Code
  • 개발 환경 자동화
  • 훅

Claude Code 가 「이 브랜치는 삭제해도 됩니다」「조건을 모두 통과했습니다」라고만 쓰고 끝내면, 어떤 조건을 어떻게 확인했는지 알 수 없습니다. 그래서 턴이 끝날 때 도는 Stop 훅이 답에 이런 결론 문장이 있는지 보고, 조건별 판정 줄(표나 목록)이 2개 미만이면 답을 한 번 되돌려 조건표를 다시 쓰게 했습니다. 훅은 판정이 맞는지까지는 볼 수 없어서 형식만 강제합니다. 이 글은 다른 탭의 승인 대기를 알아채던 지난 편에 이은 연재 열한 번째 편입니다.

점검표를 보며 결과를 확인하는 개발자 AI 생성 이미지

왜 「모두 통과」라는 말이 위험했을까?

AI 가 쓴 결론 문장은 자신 있게 읽힙니다. 문제는 그 문장 뒤에 확인하지 않은 조건이 숨어 있어도 겉으로는 티가 나지 않는다는 점입니다. 조건이 다섯 개인데 세 개만 보고 「모두 통과」라고 쓴 답을, 저는 같은 종류의 실수로 두 번 겪었습니다.

두 번 다 사람이 뒤늦게 빠진 조건을 찾아냈습니다. 그래서 「더 조심하라」는 규칙 문장을 추가하는 대신, 결론 문장이 나오는 순간 기계적으로 확인하는 장치를 만들기로 했습니다.

훅이 대신 조건을 검증할 수 있을까?

없습니다. 어떤 조건이 있어야 하는지는 그 일의 맥락 안에 있어서 훅이 알 수 없습니다. 그래서 훅이 하는 일은 딱 둘입니다. 하나는 답에 「삭제 가능」「조건 모두 통과」 같은 결론 문장이 있는지 보는 것이고, 다른 하나는 그 답에 통과·충족·누락 같은 판정어가 든 표 줄이나 목록 줄이 2개 이상 있는지 보는 것입니다.

판정 줄이 2개 이상이면 조건을 하나씩 따져 봤다는 최소한의 흔적이 있다고 보고 통과시킵니다. 「삭제 가능 여부를 확인하겠습니다」처럼 결론이 아니라 질문인 문장은 정규식에서 따로 빼 두었습니다.

어떻게 걸러낼까?

판별 코드는 정규식 세 개와 짧은 함수 하나입니다.

CLAIM_RE = re.compile(r"삭제\s*가능(?!\s*(?:여부|한지|할지|성))"
                      r"|(?:조건|요건|기준)[^\n.]{0,12}(?:모두|전부)\s*(?:통과|충족|만족)")
ITEM_RE = re.compile(r"^\s*(?:\||[-*]\s|\d+[.)]\s)")        # 표 줄·목록 줄
VERDICT_RE = re.compile(r"통과|충족|만족|미충족|누락|\b(?:OK|FAIL)\b")

def problem(text):
    m = CLAIM_RE.search(text or "")
    if not m: return None
    items = [l for l in text.splitlines() if ITEM_RE.match(l) and VERDICT_RE.search(l)]
    return None if len(items) >= 2 else m.group(0)

답 텍스트는 Stop 훅 입력의 마지막 메시지를 쓰고, 없으면 대화 기록 파일의 끝부분에서 마지막 사용자 입력 뒤의 답을 찾습니다. 작업 폴더가 프로젝트 저장소가 아니면 검사하지 않습니다.

되돌릴 때 무엇을 요구할까?

Stop 훅이 {"decision": "block", "reason": "..."} 를 출력하면 Claude Code 는 멈추지 않고 그 reason 을 읽고 계속 일합니다. 공식 훅 문서에 이 동작과, 무한 반복을 막기 위해 stop_hook_active 값을 확인하라는 안내가 있습니다. 제 훅은 이 값이 참이면 곧바로 통과시켜서 한 턴에 한 번만 되돌립니다.

{
  "decision": "block",
  "reason": "결론 문장이 있는데 조건별 대조가 없습니다. 조건 | 근거(파일:줄) | 판정 표로 다시 쓰고, 대조하지 않은 조건이 있으면 결론을 빼고 「확인 범위 N%, 남은 조건: …」으로 바꾸십시오."
}

요구 사항의 핵심은 마지막 문장입니다. 못 본 조건이 있다면 결론을 버리고 확인한 범위와 남은 조건을 적게 합니다. 확신 대신 확인 범위를 말하게 하는 것입니다.

Stop 훅의 판정 흐름턴이 끝남 → 결론 문장이 있나?; 결론 문장이 있나? → 그대로 통과 (아니오); 결론 문장이 있나? → 판정 줄이 2개 이상? (예); 판정 줄이 2개 이상? → 그대로 통과 (예); 판정 줄이 2개 이상? → 답을 되돌려 조건표를 요구 (아니오)아니오예예아니오턴이 끝남결론 문장이 있나?판정 줄이 2개 이상?답을 되돌려 조건표를요구그대로 통과
Stop 훅의 판정 흐름 — 결론 문장 - 판정 줄 수 - 한 번만 되돌림

훅에는 어떻게 연결했을까?

설정 파일의 Stop 이벤트에 명령 하나를 등록하는 것이 전부입니다.

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "python3 hooks/claim-check.py" }] }]
  }
}

지금은 무엇이 달라졌나?

이 훅은 2026-10-09 에 처음 넣었고, 그때 파일은 96줄이었습니다. 시험은 9건으로, 결론 문장만 있는 답이 막히는지, 조건표가 있으면 통과하는지, 질문형 문장과 두 번째 Stop 은 통과하는지, 대화 기록의 마지막 답을 찾는지를 확인합니다. 2026-11-04 기준 같은 파일은 다른 점검이 더해져 1,093줄입니다.

「모두 통과」라는 답훅 전: 결론만 있어도 그대로 끝남, 빠진 조건은 나중에 사람이 발견, 확인 범위가 보이지 않음 → 훅 후: 근거 줄이 없으면 한 번 되돌림, 조건표나 확인 범위로 다시 씀, 빠진 조건이 그 자리에서 드러남훅 전결론만 있어도 그대로끝남빠진 조건은 나중에사람이 발견확인 범위가 보이지않음훅 후근거 줄이 없으면 한번 되돌림조건표나 확인 범위로다시 씀빠진 조건이 그자리에서 드러남
「모두 통과」라는 답

가장 큰 변화는 결론을 읽기 전에 근거를 먼저 보게 된 점입니다. 대가도 있습니다. 형식만 보기 때문에 판정 줄을 두 개 적어 두면 내용이 엉터리여도 통과하고, 되돌려진 답은 한 번 더 길어집니다.

자주 묻는 질문

훅이 판정이 맞는지도 확인하나요?

확인하지 않습니다. 훅은 결론 문장과 판정 줄의 개수만 보며, 조건이 무엇이어야 하는지는 일마다 달라서 사람이나 별도의 검토 단계가 봐야 합니다. 이 훅은 「대조했다는 흔적 없이 결론 내기」를 막는 첫 번째 그물일 뿐입니다.

왜 규칙 문장만 쓰지 않고 훅으로 만들었나요?

문장으로 적어 둔 규칙은 AI 가 읽고도 놓칠 수 있습니다. 기계적으로 판정되는 것은 훅으로 막고 문서에는 한 줄만 남기는 쪽이 같은 실수를 덜 반복했습니다.

되돌림이 무한히 반복되지 않나요?

Stop 훅 입력의 stop_hook_active 가 참이면 검사를 건너뛰고 통과시키므로 한 턴에 한 번만 되돌립니다. 이 값을 확인하라는 안내는 공식 훅 문서에 있습니다.

사이트를 만들어볼까요?

무료 상담 받기