Claude Code 작업 완료를 증거로 남기는 검증 체크리스트

금요일 밤, 저는 Claude Code에게 “글 한 편 써서 공개까지 처리해 둬”라고 부탁하고 잠들었습니다. 다음 날 아침 로그를 보니 “완료했습니다. 글을 공개했습니다”라고 자신만만하게 적혀 있더군요. 안심하고 공개 URL을 열었는데, 화면에 떠 있는 건 이전 글의 제목이었습니다.

빌드는 통과했습니다. URL도 200을 돌려줬고요. 그런데 h1 태그는 다른 페이지 그대로였습니다. 변경 내용 확인을 AI에게 통째로 맡겨 두고, 저는 “동작했다”는 말 하나만 믿고 있었던 겁니다.

이때 깨달았습니다. 걸린 건 Claude Code의 똑똑함이 아니라 제 “작업을 닫는 방식”이었다는 걸요. AI에게 맡기는 범위를 넓힐수록, 끝난 뒤에 “실제로 무엇이 확인된 건지”를 내 손에 남겨 두지 않으면 거짓 완료 보고에 매번 걸려 넘어집니다.

이 글에서는 그 “증거를 남기는 틀”을, 복사해서 바로 쓸 수 있는 코드와 함께 소개합니다.

핵심 요약

• AI의 “끝났습니다”를 믿지 않는다. 빌드·공개 URL·h1·동선까지, 기계로 확인한 증거만 완료의 근거로 삼는다.
• 편집을 시작하기 전에 “이번 작업에서 무엇을 확인할지”를 한 문장으로 정하고, 검증 명령어도 미리 정해 둔다.
• 공개 후에는 매번 같은 순서(h1 → canonical → 본문 첫머리 → 동선)로 눈으로 확인한다. 순서를 고정하면 빠뜨림이 줄어든다.
• 증거(스크린샷·URL·다음에 볼 숫자)를 한 줄짜리 메모로 남기면, 다음 날의 나나 자동 운영이 같은 판단을 다시 하지 않아도 된다.
• 완벽한 글을 한 번에 내는 것보다, 다음 날에도 검증할 수 있는 글을 내는 쪽이 운영으로서는 더 강하다.

왜 “끝났습니다”만으로는 사고가 나는가

Claude Code는 작업의 중간 경과를 문장으로 요약해 줍니다. 이게 까다로운 점인데, 요약은 정말로 잘됐을 때나 잘 안 됐을 때나 대체로 같은 표정으로 돌아옵니다.

빌드가 통과했다는 건 “문법이 깨지지 않았다”는 증거일 뿐입니다. 공개 URL이 200을 돌려주는 것도 “서버가 무언가를 돌려줬다”는 것뿐이고요. 그 무언가가 이번에 만들었어야 할 글인지 아닌지는 별개의 이야기입니다.

제 금요일 사고도 빌드와 200은 둘 다 통과했습니다. 무너진 건 URL과 페이지 내용이 일치하는가, 이 한 가지뿐이었습니다. 여기를 아무도 보지 않았던 거죠.

그래서 완료 판단은 AI의 말이 아니라, 내가 정한 확인 항목을 하나씩 지워 나간 결과에 둡니다. 확인을 진행하는 토대가 불안하다면, 먼저 Claude Code 시작하기에서 기본 흐름을 맞춰 두면 이 글의 절차가 더 잘 들어옵니다.

15분 만에 도는 검증 루프

매번 제각각인 순서로 확인하면 바쁜 날에는 반드시 어딘가를 건너뜁니다. 순서를 고정해서, 머리를 쓰지 않고도 돌릴 수 있는 형태로 만듭니다.

1. 이번 작업에서 “무엇이 확인되면 완료인가”를 한 문장으로 적는다. 예: “이 slug의 글이 올바른 h1으로 공개 URL에 떠 있을 것”.
2. 편집을 시작하기 전에 확인에 쓸 명령어(빌드나 diff 표시)를 정해 둔다. 끝난 뒤에 찾지 않는다.
3. 변경했으면 diff → 빌드 → 공개 URL 순서로 본다. 도중에 마음이 바뀌어도 이 순서는 무너뜨리지 않는다.
4. 공개 URL에서 h1·canonical·본문 첫머리·동선이 의도대로 놓여 있는지 눈으로 본다.
5. 남은 위험과 “다음에 할 가장 작은 한 수”를 한 줄만 메모로 남긴다.

여기서 중요한 건, AI에게 맡기는 범위와 사람이 정하는 범위를 처음에 갈라 두는 것입니다.

공정	AI에게 맡겨도 되는 것	사람이 판단하는 것
주제 선정	기존 제목을 읽고 후보를 낸다	최종적으로 무엇을 쓸지
집필	본문·코드·제목의 초안	거짓이나 오래된 정보가 섞이지 않았는지
검증	빌드 실행·diff 요약	공개 URL 내용이 올바른지의 최종 확인
공개	공개 명령어 실행	삭제·운영 반영 등 되돌릴 수 없는 작업의 승인

되돌릴 수 없는 작업만큼은, 처음에는 전부 “사람에게 물어본다”로 기울여 둡니다. 안전하다고 확인된 작업부터 나중에 자동으로 격상하면 됩니다. 이 선 긋기의 사고방식은 권한 관리 가이드에서 자세히 정리했습니다.

복사해서 쓰는 요청문 템플릿

검증을 매번 처음부터 말로 풀어 쓰면 그날의 기분에 따라 빠뜨림이 생깁니다. Claude Code에 건네는 요청문을 틀로 만들어 두면 확인 항목이 안정됩니다.

이 글을 공개했습니다. 완료 보고 전에 다음을 확인하고 결과를 표로 돌려주세요.
- 빌드는 성공했는가(명령어와 종료 코드도 적는다)
- 공개 URL의 h1이 이번 slug의 글 제목과 일치하는가
- canonical이 같은 slug를 가리키는가
- 본문 첫머리가 이전 글이나 메인 페이지의 재탕이 아닌가
- 동선(무료 PDF·교재·상담)이 독자의 상황에 맞는 순서로 놓여 있는가
확인하지 못한 항목은 "미확인"이라고 정직하게 적어 주세요. 추측으로 "OK"라고 적지 마세요.

마지막 한 문장이 효과적입니다. “추측으로 OK라고 적지 마라”고 명시하지 않으면, AI는 확인하지 않은 항목까지 어쩐지 좋은 표정으로 “문제없음”이라고 돌려줍니다. 요청문을 짜는 방법 자체를 끌어올리고 싶다면 프롬프트 설계 응용편도 함께 읽어 보세요.

복사해서 동작하는 검증 스크립트

여기가 오늘의 본체입니다. 공개 URL을 가져와서 h1이 의도한 제목인지를 기계적으로 판정합니다. Node.js(18 이상)만으로 동작합니다. AI의 “끝났습니다”가 아니라, 이 스크립트의 판정을 완료의 근거로 삼습니다.

// verify-publish.mjs
// 사용법: node verify-publish.mjs <공개 URL> "<기대하는 h1 제목>"
// 예: node verify-publish.mjs https://claudecode-lab.com/ko/blog/foo/ "글 제목"

const [url, expectedH1] = process.argv.slice(2);

if (!url || !expectedH1) {
  console.error("URL과 기대하는 h1 제목, 2개를 넘겨주세요.");
  process.exit(2);
}

// 공개 페이지를 가져온다
const res = await fetch(url, { redirect: "follow" });
const html = await res.text();

// h1과 canonical을 대략 뽑아낸다(엄밀한 파서는 불필요)
const h1 = (html.match(/<h1[^>]*>(.*?)<\/h1>/is)?.[1] ?? "")
  .replace(/<[^>]+>/g, "")
  .trim();
const canonical = html.match(/<link[^>]+rel=["']canonical["'][^>]+href=["']([^"']+)["']/i)?.[1] ?? "";

// 항목을 하나씩 지워 나간다
const checks = {
  http200: res.status === 200,
  h1Match: h1 === expectedH1,
  canonicalMatch: canonical.includes(new URL(url).pathname),
};

console.table(checks);

const allOk = Object.values(checks).every(Boolean);
if (!allOk) {
  console.error("미확인이거나 불일치한 항목이 있습니다. 공개를 아직 완료로 취급하지 않습니다.");
  console.error(`가져온 h1: ${h1 || "(비어 있음)"}`);
  process.exit(1);
}

console.log("증거가 모였습니다. 완료로 취급해도 됩니다.");

실행은 이것뿐입니다.

node verify-publish.mjs https://claudecode-lab.com/ko/blog/foo/ "글 제목"

h1Match가 false라면, 바로 제 금요일 사고와 같은 상태입니다. URL은 살아 있는데 내용이 다른 거죠. 종료 코드가 0이 아닌 한, 공개를 “완료”라고 부르지 않습니다. 이것만 규칙으로 정해도 거짓 완료 보고가 앞단에서 멈춥니다.

이런 장면에서 효과가 있다

1. 글 공개 작업 HTTP 200만 보고 성공으로 착각하기 쉬운 장면입니다. 위 스크립트로 h1과 canonical이 같은 slug를 가리키는지 확인하면, 이전 글 재탕이나 메인 페이지로의 폴백을 공개 전에 걸러낼 수 있습니다.

2. 동선(CTA) 교체 무료 PDF나 교재로 가는 버튼을 옮겼다면, 스크린샷과 “다음에 볼 숫자”를 같은 메모 줄에 남깁니다. 나중에 “그 변경으로 등록이 늘었나”를 기억이 아니라 기록으로 추적할 수 있게 됩니다.

3. 설정이나 권한 변경 CLAUDE.md나 권한 설정을 바꿨을 때야말로, 변경 전후로 같은 검증 명령어를 통과시킵니다. 설정을 쓰는 방식에 불안이 남는다면, CLAUDE.md 작성법을 먼저 정리해 두면 검증의 전제가 맞춰집니다.

함정과 그 고치는 법

솔직히 말하면, 저는 이 틀에 정착하기까지 같은 구덩이에 몇 번이나 빠졌습니다.

첫 번째는, 한 번의 작업으로 전부 고치려다 확인할 수 없을 만큼 큰 diff를 만드는 것. 40개 파일이 움직인 diff는 사람도 AI도 다 읽지 못합니다. 고치는 법은 단순합니다. 한 번의 작업에서 확인할 것을 한 문장으로 좁힌다. 다 확인할 수 없는 크기가 되면 작업을 쪼갭니다.

두 번째는, 로컬 빌드가 통과한 시점에 완료로 취급하는 것. 로컬에서 동작하는 것과 공개 URL에 올바르게 뜨는 것은 별개입니다. 고치는 법은, 위 스크립트를 공개 후에 반드시 한 번 통과시키는 것입니다. 이걸 절차에 끼워 넣기 전까지는 저도 몇 번이나 내용이 다른 페이지를 공개했습니다.

세 번째는, 동선을 늘리기만 하고 독자가 어디로 가면 되는지 설명하지 않는 것. 버튼을 3개 늘어놓아도 고를 수 없으면 의미가 없습니다. 고치는 법은, 독자의 상황(아직 조작이 불안하다 / 반복 작업으로 지쳐 있다 / 팀 도입을 고민 중이다)마다 어느 동선이 맞는지 본문에 한마디 덧붙이는 것입니다.

자주 묻는 질문

Q. 빌드가 통과하면 그걸로 완료 아닌가요? 빌드는 문법이 깨지지 않았다는 증거일 뿐입니다. 공개 URL의 내용이 이번 글인지 아닌지는 별개 문제입니다. h1과 canonical까지 봐야 비로소 완료입니다.

Q. 검증 스크립트는 매번 손으로 돌리나요? 처음에는 손으로 충분합니다. 절차가 안정되면 공개 명령어 바로 뒤에 자동으로 돌아가는 형태로 키웁니다. 종료 코드가 0이 아니면 공개를 멈춘다, 이런 운영으로 만들면 사고가 줄어듭니다.

Q. AI에게 검증도 전부 맡기면 안 되나요? 읽고 요약하는 작업은 맡겨도 됩니다. 다만 “공개 URL의 내용이 올바른가”의 최종 판단과 되돌릴 수 없는 작업의 승인은 사람이 갖습니다. 여기를 넘기면 거짓 완료 보고를 멈출 사람이 없어집니다.

Q. 비개발자도 이 점검을 돌릴 수 있나요? 돌릴 수 있습니다. 스크립트는 복사해서 동작하고, 눈으로 보는 절차는 순서를 외우기만 하면 됩니다. 명령어 자체가 불안하다면 비개발자를 위한 설명부터 들어가면 무리가 없습니다.

Q. 메모는 무엇을 남기면 충분한가요? “이번에 확인한 것” “남은 위험” “다음의 가장 작은 한 수” 3가지면 됩니다. 긴 회의록은 불필요합니다. 다음 날의 내가 같은 판단을 다시 하지 않게 하는 것, 그것만이 목적입니다.

실제로 시도한 결과

금요일의 내용 다른 페이지 공개 사고 이후, 저는 완료의 기준을 “AI가 뭐라고 했는가”에서 “스크립트의 종료 코드가 0인가”로 바꿨습니다.

실제로 verify-publish.mjs를 10편 정도의 공개에 통과시켜 봤더니, 2편에서 h1Match가 false를 돌려줬습니다. 둘 다 200은 돌려주고 있어서, 얼핏 봐서는 알아챌 수 없는 녀석들이었죠. 스크립트가 없었다면 또 재탕 페이지를 공개했을 겁니다.

눈으로 보는 순서를 고정한 것도 효과가 있었습니다. h1 → canonical → 본문 첫머리 → 동선, 하고 늘 같은 순서로 보게 했더니 “어, 여기 전에도 건너뛰었네” 하는 빠뜨림이 거의 사라졌습니다. 판단을 머릿속에서 하지 않고 절차로 빼낸 만큼 밤의 확인이 가벼워진 게 실감됩니다.

똑똑한 AI를 찾는 것보다, 넘어져도 알아챌 수 있는 구조를 먼저 놓는다. 멀리 돌아가는 듯 보여도 이게 가장 빠르다는 게 지금의 결론입니다.

이 검증의 틀을 팀의 표준으로 삼고 싶다, 혹은 자사 공개 플로우에 끼워 넣고 싶은 단계라면 연수·상담에서 함께 설계합니다. Claude Code 공식 문서는 Anthropic 문서에서 확인할 수 있습니다.