Claude Code Harness Smoke Test: 에이전트를 믿기 전 15분 검증 루프

실제 업무에 가까운 Claude Code 작업은 큰 자동화부터 시작하지 않습니다. 먼저 작은 smoke test가 필요합니다. 읽을 파일, 수정할 파일, 절대 건드리지 않을 영역, 완료 증거를 먼저 정합니다.

이 글은 에이전트에게 어디까지 맡겨도 되는지 알고 싶은 초급자와 중급자를 위한 것입니다. 수익형 사이트라면 로컬 build뿐 아니라 무료 PDF, Gumroad 상품, 상담 경로도 같은 증거에 포함해야 합니다.

함께 읽기: Claude Code harness engineering, first repo audit checklist, permission safety ladder.

이 패턴이 효과적인 이유

harness smoke test는 모델이 항상 안전하다는 증명이 아닙니다. 작업 환경에 경계가 있는지 확인하는 절차입니다. 작은 글 수정도 PDF 폼이나 상품 링크, 상담 링크를 깨면 수익 경로가 망가집니다.

15분이면 매일 반복할 수 있습니다. 완벽한 CI보다 읽기 범위, 제한 수정, build, 공개 URL, 스크린샷을 작게 통과시키는 편이 현실적입니다.

실무 흐름

목표를 한 문장으로 쓰고 수정 가능한 파일을 세 개 이하로 제한한다
비밀값, 결제, 고객 데이터, 배포 설정을 금지 영역으로 적는다
수정 전에 build, diff, 공개 URL, 스크린샷 증거를 정한다
글과 랜딩 페이지는 무료 PDF, Gumroad, 상담 CTA까지 확인한다
run card를 남겨 다음 작업이 증거에서 시작되게 한다

상황	안전한 진행	증거
새 글	본문과 frontmatter만 허용하고 layout과 API는 읽기 전용으로 둔다	build와 공개 URL
상품 페이지	문구와 카드 순서만 바꾸고 구매 링크를 모두 대조한다	Gumroad 링크 확인
팀 도입	먼저 읽기 전용으로 점검하고 낮은 위험 수정 하나만 허용한다	diff와 스크린샷

복사해서 쓸 프롬프트와 코드

이 저장소에서 15분짜리 harness smoke test를 실행해 주세요. 아직 큰 수정은 하지 마세요. 목표, 수정 가능 파일, 금지 영역, 검증 명령, 공개 URL 확인, 무료 PDF/Gumroad/상담 CTA 확인 항목을 반환해 주세요.

const runCard = {
  slug: "claude-code-harness-smoke-test-loop",
  goal: "publish one safe content change",
  allowedFiles: ["site/src/content/blog-en/example.mdx"],
  blockedAreas: [".env", "billing/", "cloudflare/"],
  proof: ["npm.cmd run build", "public URL screenshot"],
  ctas: ["free PDF", "Setup Guide", "consultation"]
};

function readyForAgent(card) {
  return card.allowedFiles.length > 0 &&
    card.blockedAreas.length > 0 &&
    card.proof.some((item) => item.includes("build")) &&
    card.ctas.length >= 3;
}

console.log(readyForAgent(runCard) ? "ready" : "tighten scope");

이 코드는 모호한 에이전트 요청을 run card로 바꾸는 예입니다. PR 템플릿, 게시 체크리스트, 상담 준비 메모에 같은 구조를 쓸 수 있습니다.

세 가지 실제 예

Astro 글 게시

수정 범위를 본문, heroImage, CTA로 제한합니다. build가 성공해도 운영 페이지의 h1이나 CTA가 다른 글이면 실패입니다.

작은 UI 수정

버튼 문구만 바꿔도 모바일 줄바꿈과 터치 영역을 봅니다. 상품 버튼이면 링크도 같이 확인합니다.

팀 첫 도입

처음부터 코드를 쓰게 하지 않습니다. README, 권한, 테스트, 금지 영역을 정리하면 상담 안건이 됩니다.

피해야 할 실패 사례

처음부터 모든 것을 개선하라고 하면 범위가 커집니다.
로컬 build에서 멈추면 운영 fallback과 오래된 CTA를 놓칩니다.
Gumroad 링크를 확인하지 않으면 초급자 트래픽이 맞지 않는 상품으로 갈 수 있습니다.

다국어 글은 slug가 같아도 본문과 CTA가 낡아 있을 수 있습니다. frontmatter가 아니라 공개 화면을 봐야 합니다.

무료 PDF, Gumroad, 상담으로 연결하는 방법

명령이 아직 익숙하지 않다면 무료 치트시트부터 안내합니다. 권한, CLAUDE.md, hooks, MCP, CI가 문제라면 Setup Guide가 맞습니다.

review와 debug 요청을 매번 다시 쓴다면 50 Prompt Templates를 권합니다. 팀 rollout 설계가 필요하면 상담으로 연결합니다. 전체 자료 비교는 products에서 시작합니다.

게시 전후 확인할 것

게시 전에는 frontmatter, heroImage, 내부 링크, Gumroad 링크를 봅니다. 게시 후에는 모바일 폭에서 h1, 본문 시작, CTA 영역을 확인합니다. HTTP 200이어도 fallback이면 실패입니다.

다음에 볼 지표

이 slug의 검색 유입, PDF 시작, Gumroad 클릭, 제품 페이지 방문, 상담 페이지 방문을 봅니다. PV만 오르면 CTA 단계가 맞지 않는 것입니다.

30분 운영 리뷰

harness smoke test를 실제 작업에 넣었다면 가장 중요한 리뷰는 다음 날입니다. run log를 보고 허용 범위, 실제 변경 파일, 검증 명령, 확인한 공개 페이지를 하나의 증거로 적습니다. “페이지 확인”처럼 쓰지 말고 모바일 h1, 본문 시작, CTA 영역, Gumroad 링크, 상담 경로를 본 사실을 남깁니다.

그다음 작업자의 안심과 독자의 행동을 나눠 봅니다. 작업자 쪽에서는 금지 영역을 건드리지 않았는지, build 증거가 있는지, 공개 URL이 같은 slug인지, 번역 페이지에 영어 본문이 남지 않았는지 확인합니다. 독자 쪽에서는 명령이 필요한 사람은 무료 PDF, 반복 병목이 있는 사람은 Gumroad, workflow 설계가 필요한 사람은 상담으로 이어지는지 봅니다.

마지막으로 리뷰를 다음 규칙 하나로 바꿉니다. 문제 하나에 규칙 열 개를 추가하지 않습니다. layout 수정 전 질문하기, 운영 Gumroad URL 모두 클릭하기, 각 언어 본문 시작을 스크린샷으로 남기기처럼 매일 지킬 수 있는 작은 규칙이 오래갑니다.