Claude Code Harness Lite: 초보자를 위한 안전한 변경 발판

Claude Code를 처음 실제 저장소에 쓰는 사람의 첫 실수는 나쁜 프롬프트가 아닙니다. 경계 없이 너무 많은 일을 맡기는 것입니다. Harness Lite는 아주 작은 안전 발판입니다. 먼저 읽고, 그다음 수정하고, 증거를 남기고, 공개 URL과 수익 CTA를 확인합니다.

이 글은 Claude Code harness engineering의 입문 버전입니다. 낯선 저장소라면 repo map first pass와 permission receipt pattern을 함께 사용하면 변경 범위를 설명하기 쉬워집니다.

작업보다 먼저 경계를 쓴다

Harness Lite는 Claude Code를 약하게 만드는 장치가 아닙니다. 변경을 설명 가능하게 만드는 장치입니다. 어떤 파일을 읽을지, 어떤 파일을 수정할지, 어떤 영역은 제외할지, 어떤 명령으로 증명할지, 배포 후 어떤 공개 페이지를 볼지 먼저 정합니다.

콘텐츠 사이트나 제품 페이지에서는 이 순서가 특히 중요합니다. 글, 무료 PDF 폼, Gumroad 링크, 상담 링크가 가까이 있기 때문입니다. 작은 문구 수정도 검색 유입이 등록이나 구매로 이어지는 길을 끊을 수 있습니다.

harness_lite:
  owner: "Masa"
  scope:
    allowed:
      - "read repository"
      - "edit selected files"
      - "run build or test"
    blocked:
      - "delete unrelated files"
      - "touch secrets"
      - "hide failed verification"
  proof:
    - "git diff reviewed"
    - "build command recorded"
    - "public URL opened"
    - "CTA path checked"

복사해서 쓰는 시작 프롬프트

이 저장소에서 아주 작은 변경 하나만 안전하게 하고 싶습니다.
아직 파일을 수정하지 마세요.
다음을 반환하세요:
1. 먼저 읽어야 할 파일
2. 안전하게 수정할 수 있는 파일
3. 범위 밖으로 둘 영역
4. 가장 작은 검증 명령
5. 공개 URL에서 확인할 h1, canonical, hero image, CTA
6. 무료 PDF, Gumroad, 상담 링크를 보호하는 주의점

핵심은 구현을 바로 요청하지 않는 것입니다. 먼저 경계를 받고, 다음 메시지에서 변경 하나와 검증 하나만 요청합니다.

검증을 작은 객체로 만든다

수정 뒤에는 proof receipt를 채우게 합니다. 아래 JavaScript는 단순하지만, commit 전 최소 조건을 눈에 보이게 만듭니다.

const proof = {
  goal: "change one small thing",
  filesChanged: 2,
  commands: ["npm run build"],
  publicUrlChecked: true,
  ctaChecked: true,
};

export function isReadyToCommit(receipt) {
  return receipt.filesChanged <= 3 &&
    receipt.commands.length > 0 &&
    receipt.publicUrlChecked &&
    receipt.ctaChecked;
}

console.log(isReadyToCommit(proof)); // true이면 commit 전 최소 조건을 통과한 것입니다

이렇게 하면 build는 통과했지만 공개 URL을 보지 않은 상태, 200 OK지만 다른 글이 보이는 상태, 본문은 맞지만 Gumroad 또는 상담 CTA가 틀린 상태를 분리할 수 있습니다.

실제 사용 예

• Astro 글 수정은 MDX 하나, hero image 하나, 관련 제품 페이지 하나로 제한합니다. 배포 뒤 h1, 본문 첫 부분, canonical, 무료 PDF 폼, Gumroad 버튼, 상담 링크를 확인합니다.
• React의 작은 수정은 대상 컴포넌트, 가까운 테스트, 스크린샷 또는 Storybook 확인으로 제한합니다. 인증, 결제, secret, migration은 첫 변경에서 제외합니다.
• 팀 도입에서는 CLAUDE.md에 안전한 명령, 보호 영역, receipt 형식, rollback 메모를 남깁니다. 다음 사람은 같은 규칙을 다시 설명하지 않아도 됩니다.

실패 사례

자주 보이는 실패는 “전부 확인하고 고쳐줘”라고 시작하는 것입니다. Claude Code는 넓게 움직이고 diff가 커지며 증거가 흐려집니다. 또 다른 실패는 로컬 build만 보고 끝내는 것입니다. 공개 URL이 HTTP 200을 반환해도 fallback 페이지나 오래된 글일 수 있습니다.

수익 경로에서도 문제가 생깁니다. 본문은 무료 PDF를 안내하지만 글 아래 CTA는 다른 상품으로 보냅니다. 다국어 글에서 Gumroad가 현재 영어 상품 중심이라는 설명이 없습니다. 상담 링크는 있지만 어떤 경우에 상담이 필요한지 말하지 않습니다. Harness Lite는 이 확인을 작업 안에 넣습니다.

무료 PDF, Gumroad, 상담 경로

명령과 안전 습관을 익히는 중이면 free cheatsheet부터 사용하세요. review, debugging, refactoring 프롬프트를 반복해서 만든다면 50 Prompt Templates가 맞습니다. 권한, CLAUDE.md, hooks, MCP, CI/CD가 병목이면 Setup Guide를 보세요. 팀 도입이나 수익 경로 설계가 필요하면 상담으로 이동합니다.

이 글에서 확인한 것

이 글은 가벼운 harness, 시작 프롬프트, 검증 객체, 실제 예시, 실패 사례, 무료 PDF와 Gumroad와 상담 경로를 함께 배치했습니다. 다음에 볼 숫자는 이 slug에서 발생한 PDF 등록, Gumroad 클릭, 상담 페이지 방문입니다.

공개 후 운영 메모

이 패턴을 실제로 쓸 때는 “파일이 생겼다”에서 멈추지 않습니다. 공개 URL에서 독자가 다음 행동을 고를 수 있어야 완료입니다. 모바일 폭으로 h1, 본문 첫 부분, hero image, 무료 PDF 폼, Gumroad 링크, 상담 링크를 봅니다. 본문이 맞아도 글 끝 CTA가 다른 상품으로 가면 수익 경로는 아직 끝난 것이 아닙니다.

다국어 글은 slug가 같다고 충분하지 않습니다. 일본어, 영어, 중국어, 한국어, 스페인어, 프랑스어, 독일어, 포르투갈어, 힌디어, 인도네시아어 각각에서 본문 첫 부분과 CTA 문구가 해당 언어인지 확인합니다. 제목만 번역되고 본문이나 CTA가 영어라면 독자는 다음 단계를 신뢰하기 어렵습니다.

다음 개선에서는 PV만 보지 않습니다. PDF signup 시작, Gumroad 클릭, Products 방문, Training 방문, 국가별 유입, 검색 source를 같은 brief에 넣습니다. Claude Code는 이 숫자가 있을 때 무료 asset, Prompt Templates, Setup Guide, 상담 중 무엇을 강화할지 더 잘 판단합니다.

처음 실습할 때는 도입 문단 하나나 내부 링크 하나만 바꾸는 식으로 범위를 줄이는 편이 좋습니다. 수정 전에 Claude Code에게 건드리면 안 되는 영역을 쓰게 합니다. 예를 들면 결제, 환경 변수, 기존 상품 페이지, 상담 폼입니다. 수정 뒤에는 diff 크기, 실행한 명령, 확인한 공개 URL, 다음에 봐야 할 숫자를 짧게 보고하게 합니다. 이렇게 하면 자동화가 강해도 작업이 흩어지지 않고, 글 업데이트가 무료 PDF, Gumroad, 상담 경로와 연결됩니다. 트래픽 증가는 시작점이고, 실제 목표는 독자가 다음 행동으로 이동했는지 확인하는 것입니다.