5장. 확인과 테스트 — 확인 장치를 주고 증거를 받기
필수 이 단계를 따라가려면 꼭 읽으세요.한 줄 요약: AI는 일이 끝나 보이면 멈춥니다. 정말 끝났는지 알려 줄 확인 장치를 주면, AI가 스스로 고치고 다시 확인하는 고리를 돌립니다. 그리고 "다 통과했어요"라는 말 대신 증거(실행한 명령과 그 출력, 또는 화면)를 받으세요.
이 장은 2026년 11월 1일에 확인한 Claude Code·GitHub 공식 문서를 바탕으로 썼습니다. 3단계에서 결과를 원본 메모와 맞춰 본 습관이, 4단계에서는 "확인 장치"라는 이름으로 자동화됩니다.
왜 확인 장치가 필요한가
공식 모범 사례 문서는 이렇게 말합니다. Claude는 일이 끝나 보이면 멈춥니다. 실제로 끝났는지 알려 줄 것이 없으면, "끝나 보인다"가 판단의 전부가 됩니다.[1] 그러면 결국 내가 테스트 역할을 하게 되고, 실수는 내가 우연히 알아챌 때까지 그대로 남습니다.[2]
반대로 통과/실패로 답하는 무언가를 주면, Claude가 스스로 고리를 닫습니다. 바꾸고, 검사를 돌리고, 깨졌으면 출력을 읽고 고쳐 다시 돌립니다.[3]
| 확인 장치 없이 | 확인 장치를 주면 |
|---|---|
| "다 했어요" → 내가 열어 보고 틀린 곳 찾기 | 검사 실패 → Claude가 고침 → 다시 검사 → 통과 |
출처: 이 가이드의 정리(근거는 공식 문서)[3:1]
확인 퀴즈
확인 장치(통과/실패로 답하는 검사)를 주면 무엇이 달라질까요?
확인 장치의 종류
확인 장치는 Claude가 결과를 읽을 수 있는 것이면 무엇이든 됩니다. 공식 문서는 이런 것들을 예로 듭니다.[4]
- 테스트 파일: "할 일 5개가 다 보이나?"처럼 확인할 내용을 적어 둔 검사 파일
- 빌드 성공 여부: 4장에서 본 준비 과정(빌드)이 오류 없이 끝났는지
- 문법 검사기(linter, 린터): 코드의 맞춤법 검사기 같은 도구
- 출력 비교 스크립트: 결과를 미리 준비한 정답과 맞춰 보는 짧은 프로그램(스크립트)
- 브라우저 화면: 시안 옆에 놓고 비교한 실제 화면
할 일 보드는 빌드가 없는 웹 페이지라서, 테스트 파일과 브라우저 화면부터 써 보면 됩니다.
그런 장치가 있다면, CLAUDE.md에서 가장 쓸모 있는 한 줄은 그것을 돌리는 명령이라고까지 합니다.[5]
가장 쉬운 방법은 요청에 적는 것입니다. 설정 없이 오늘 바로 됩니다.[6]
할 일 보드를 고친 뒤에는 SPEC.md의 확인 기준을 하나씩 검사하고, 다 통과할 때까지 계속해 줘.데스크톱 앱에서는 Claude가 개발 서버(만든 웹 페이지를 내 컴퓨터에서만 미리 띄워 보는 작은 프로그램)를 켜고 앱 안의 브라우저 창에서 열어 자기 변경을 확인할 수 있습니다. 기본으로 편집할 때마다 자동으로 확인합니다.[7] 웹 페이지인 할 일 보드에 잘 맞는 장치입니다.
테스트를 만들어 달라고 할 때는 어떤 동작을 확인할지 구체적으로 말합니다.[8]
| 아쉬운 요청 | 나은 요청 |
|---|---|
| 테스트 만들어 줘 | 회의록의 할 일 5개가 화면에 모두 보이는지, 기한이 날짜 형식인지 확인하는 테스트를 만들어 줘 |
출처: 이 가이드의 예(요령은 공식 문서)[8:1]
확인 퀴즈
확인 장치가 이미 있다면, 공식 문서가 CLAUDE.md에서 가장 쓸모 있는 한 줄이라고 하는 것은 무엇일까요?
증거를 받기
어떤 장치를 쓰든 증거를 달라고 하세요. 실행한 명령과 그 출력, 또는 화면입니다.[9] "다 통과했어요"라는 말만으로는 알 수 있는 것이 거의 없고, 출력을 읽는 편이 직접 다시 돌리는 것보다 빠릅니다.[9:1]
방금 돌린 확인 명령과 그 출력을 그대로 보여 줘. 통과 몇 개, 실패 몇 개인지도.검사가 정말 검사하는지도 확인하세요. 일부러 틀리게 만들었을 때 실패하지 않는 검사는 장치가 아니라 장식입니다. 예를 들어 할 일 하나를 지운 채 돌려 보고, 검사가 실패하는지 봅니다.
확인 퀴즈
Claude가 "테스트를 다 통과했어요"라고 했을 때 이 가이드가 권하는 대응은 무엇일까요?
올릴 때마다 자동으로 — GitHub Actions
확인을 사람이 매번 시키지 않아도 되게 만들 수 있습니다. GitHub Actions는 빌드·테스트·배포를 자동으로 돌리는 GitHub의 기능입니다. 변경을 올릴 때마다 테스트를 돌리게 할 수 있습니다.[10]
공개 저장소에서는 GitHub이 제공하는 표준 실행기(검사를 대신 돌려 주는 GitHub의 컴퓨터)를 무료로 쓸 수 있습니다.[11]
처음부터 모든 자동화를 갖출 필요는 없습니다. 처음에는 위의 "요청에 적기"와 브라우저 확인만으로 충분합니다. 나중에 쓰고 싶어지면 설정 파일(언제 무엇을 돌릴지 적어 두는 파일)은 Claude에게 만들어 달라고 하면 됩니다.
조금 더 알아보기 (눌러서 펼치기)
확인 퀴즈
GitHub Actions에 대한 설명으로 맞는 것은 무엇일까요?
직접 해 보기
- 4장의
first-board브랜치에서, SPEC.md의 확인 기준을 검사하는 장치를 만들어 달라고 한다. - 검사를 돌리고, 실행한 명령과 출력을 그대로 보여 달라고 한다.
- 할 일 하나를 일부러 지운 채 다시 돌려, 검사가 실패하는지 본다. 확인한 뒤 되돌린다.
- 앱의 브라우저 창에서 할 일 보드를 열어, 할 일 수를 직접 세어 본다.
- 검사 명령을 CLAUDE.md에 한 줄로 적어 둔다.
이어지는 과제: 6장에서는 지금까지의 변경을 PR로 올리고 리뷰를 받습니다.
정리
- AI는 끝나 보이면 멈춘다. 통과/실패로 답하는 확인 장치를 주면 스스로 고치고 다시 확인한다.
- 확인 장치는 테스트·빌드·비교 스크립트·브라우저 화면 등 Claude가 결과를 읽을 수 있는 것이면 된다.
- "다 통과했다"는 말 대신 명령과 출력이라는 증거를 받는다. 일부러 틀려서 검사가 실패하는지도 본다.
- GitHub Actions는 올릴 때마다 자동으로 확인한다. 공개 저장소에서는 표준 실행기가 무료다.
용어 정리
| 용어 | 읽는 법 | 한 줄 뜻 |
|---|---|---|
| Test | 테스트 | 결과가 기대대로인지 자동으로 확인하는 검사 |
| CI | 씨아이 | 자주 합치고 자주 자동 확인하는 습관(지속적 통합) |
| GitHub Actions | 깃허브 액션즈 | 올릴 때마다 정해 둔 작업을 자동으로 돌리는 기능 |
| YAML | 야믈 | 자동 작업 설정에 쓰는 글 형식 |
이 장을 다 읽었나요?
기록은 이 브라우저에만 저장됩니다. 진행 현황은 전체 목차에서 볼 수 있어요.
다음 장: 6장. PR과 리뷰
참고 자료 (13개)
Claude Code 공식 문서, 「Best practices for Claude Code」. "Claude stops when the work looks done. If it has nothing to run that tells it whether the work actually is done, "looks done" is all it has to go on." code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "In practice that makes you the test suite, and every mistake sits there until you happen to notice it." code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "If you give it something that comes back pass or fail, Claude can close that loop itself." code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "The check can be almost anything, as long as Claude can read the result:" / "A test file" / "A build's exit code" / "A linter" / "A script that diffs output against a fixture" code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "If your repo already has one of these, the single most useful line in your
CLAUDE.mdis the command that runs it." code.claude.com (확인일 2026-11-01) ↩︎Claude Code 공식 문서, 「Best practices for Claude Code」. "In the prompt:
run the auth tests after, and keep going until they pass. Claude decides for itself when it's satisfied." code.claude.com (확인일 2026-11-01) ↩︎Claude Code 공식 문서, 「Desktop application」. "Claude can start a dev server and open it in the Browser pane to verify its changes." / "By default, Claude auto-verifies changes after every edit." code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Common workflows」. "When asking for tests, be specific about what behavior you want to verify." code.claude.com (확인일 2026-11-01) ↩︎
Claude Code 공식 문서, 「Best practices for Claude Code」. "Whichever option you use, ask Claude for evidence: the command it ran and its output, or the screenshot." / "reading the output is faster than rerunning the check yourself." code.claude.com (확인일 2026-11-01) ↩︎
GitHub 공식 문서, 「Quickstart for GitHub Actions」. "GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline." / "You can create workflows that run tests whenever you push a change to your repository, or that deploy merged pull requests to production." docs.github.com (확인일 2026-11-01) ↩︎
GitHub 공식 문서, 「Billing and usage」. "GitHub Actions usage is free for standard GitHub-hosted runners in public repositories, and for self-hosted runners." docs.github.com (확인일 2026-11-01) ↩︎
GitHub 공식 문서, 「Understanding GitHub Actions」. "Workflows are defined in the
.github/workflowsdirectory in a repository." docs.github.com (확인일 2026-11-01) ↩︎GitHub 공식 문서, 「Continuous integration」. "Committing code more often detects errors sooner and reduces the amount of code a developer needs to debug when finding the source of an error." / "GitHub runs your CI tests and provides the results of each test in the pull request, so you can see whether the change in your branch introduces an error." docs.github.com (확인일 2026-11-01) ↩︎