저의 CLAUDE.md에는 ## TDD First라는 섹션이 있었습니다. 단 여섯 줄이었고, 매우 명확했습니다. 저는 이를 작성하는 데 20분을 소비했습니다. 그러고 나서 제가 Claude Code에게 TDD (테스트 주도 개발)를 요청했던 기능들을 대상으로 지난 30일간의 커밋 (commit) 감사를 실시했고, 10번 중 6번은 테스트 파일이 소스 파일보다 나중에 커밋되었다는 사실을 발견했습니다.

"테스트가 먼저 실패했고, 그 후에 수정했다"는 뜻이 아닙니다. 소스 파일이 커밋되는 시점에 테스트 파일은 존재하지도 않았습니다.

이 글은 제가 어떻게 이를 잡아냈는지, 왜 이런 일이 계속 발생했는지, 그리고 Claude를 마침내 진정한 Red-Green-Refactor (레드-그린-리팩터) 사이클로 밀어 넣은 두 단계의 해결책(프롬프트와 PreToolUse 훅 (hook)의 조합)에 대한 이야기입니다. 이 글은 Claude가 자신 있게 틀린 일을 저지르는 과정에서 의도치 않게 만들어진 시리즈의 세 번째 편입니다. 첫 번째는 Claude가 세 번 연속으로 버그를 숨겼던 사건이었고, 두 번째는 코드가 세 번 꼬일 때까지 명세서 (specs) 작성을 거부했던 사건이었습니다. 이번 이야기는 TDD에 관한 것이며, 패턴은 동일합니다. 모델은 동의하고, 모델은 진행하며, 모델은 토큰 (tokens) 비용이 발생하는 프롬프트의 부분을 건너뜁니다.

30일간의 감사

감사는 우연히 이루어졌습니다. 저는 디버깅 (debugging) 습관에 대해 글을 쓰고 있었고, 저의 커밋 히스토리 (commit history)가 제가 주장하는 바와 일치하는지 확인하고 싶었습니다. 그래서 Claude Code와 함께 진행해 온 프로젝트의 지난 30일간의 기록을 git log --name-only --pretty=format:'%h %ai %s' 명령어로 추출한 뒤, 기능을 기준으로 커밋들을 그룹화했습니다. 총 10개의 기능이었습니다. 각 기능에 대해 소스 파일을 처음 건드린 커밋의 타임스탬프 (timestamp)와 테스트 파일을 처음 건드린 커밋의 타임스탬프를 기록했습니다.

열 가지 기능 중 여섯 가지에서 소스 파일이 먼저 커밋되었습니다. 그 간격은 90초에서 23분 사이였습니다. 두 가지 사례에서는 소스 코드가 이미 기능 브랜치(feature branch)로 배포된 후, 이후의 수정 단계에서 테스트 파일이 동일한 커밋으로 함께 커밋되었습니다. 한 가지 사례에서는 테스트 파일이 전혀 없었으며

Claude Code 커뮤니티의 여러 사람들이 동일한 점을 지적해 왔습니다. aihero.dev의 TDD 기술 분석 글에서는 이를 다음과 같이 설명합니다: 테스트 작성자(test writer)와 구현자(implementer)가 동일한 컨텍스트 윈도우(context window)를 공유할 때, 구현자의 사고가 테스트 작성자의 사고로 유출되어 첫 실행 시 편리하게 통과되는 테스트를 만들게 됩니다. 이것은 TDD가 아닙니다. 그것은 "통과하도록 사후 수정된 테스트(tests retrofitted to pass)"입니다. alexop.dev의 red-green-refactor 루프 포스트에서는 유일하고 신뢰할 수 있는 해결책은 에이전트가 진행 도중에 무시할 수 없는 훅(hooks)이나 기술(skills)을 사용하여 모델 외부에서 사이클을 강제하는 것이라고 주장합니다.

BSWEN의 Claude Code TDD 기술 워크스루를 포함하여 커뮤니티 분석 글에서 계속해서 눈에 띄는 또 다른 점은, 제가 그동안 무시해 왔던 Anthropic의 가이드라인과 동일한 내용입니다: Claude는 구현을 수정하는 대신 테스트를 통과하도록 변경할 때가 있습니다. 구현 전에 테스트를 먼저 커밋하면, 그런 일이 발생했을 때 살펴볼 수 있는 디프(diff)가 남습니다. 저 역시 그렇게 하지 않았습니다.

결국 모델은 테스트 우선(test-first) 방식에 대한 약한 사전 확률(weak prior)을 가지고 있었고, 저는 이를 보완할 만한 워크플로(workflow)조차 갖추지 못한 상태였습니다. 돌이켜보니 10번 중 6번이라는 수치는 매우 납득이 갑니다. 놀라운 점은 그 수치가 고작 6번이었다는 사실입니다.

처음에 시도했지만 실패했던 방법들

훅(hook)을 도입하기 전에, 저는 프롬프트 엔지니어링(prompt engineering)을 더 강하게 시도해 보았습니다. 이것은 대부분의 사람들이 시도하는 방식이며, 목표 지점 근처까지는 데려다주지만 결국 도달하게 하지는 못합니다.

시도 1 — CLAUDE.md에 ## TDD First 추가. 이미 적용되어 있던 방식입니다. 10번 중 6번은 이를 무시했습니다. 헤더가 너무 일반적이어서, 모델은 이를 제약 조건(constraint)이 아닌 단순한 분위기(vibe)로 받아들였습니다.

시도 2 — 프롬프트에 명시적인 Red-phase(레드 단계) 지침 포함. 저는 "tests/X_test.py에 [기능]에 대한 실패하는 테스트를 작성하세요. 아직 구현(implementation)은 작성하지 마세요. 테스트를 실행하고 다음 단계로 넘어가기 전에 실패를 확인하세요."라는 문구를 붙여넣기 시작했습니다. 이를 통해 10번 중 약 8번 정도는 성공했습니다. 더 나아졌지만, 10번 중 2번은 모델이 속임수를 쓰는 것을 발견했습니다. 대개 실제로 실패해야 할 부분을 모킹(mock) 처리하는 방식으로 테스트를 작성하곤 했습니다.

시도 3 — Red와 Green을 위한 별도의 프롬프트. 두 개의 메시지를 사용했습니다. 첫 번째 메시지: 실패하는 테스트를 작성하고, 멈추고, 실행한 뒤, 실패 내용을 보여줄 것. 두 번째 메시지(제가 실패 내용을 직접 확인한 후에만): 이제 구현을 작성할 것. 이것이 처음으로 진짜 TDD(Test-Driven Development)의 냄새가 나는 결과를 얻은 방식이었습니다. 문제는 제가 두 번의 턴 동안 물리적으로 키보드 앞에 있어야 했다는 점이며, 만약 기능 구현 중간에 컨텍스트 스위칭(context-switch)을 하여 자리를 비우면, 다음 Claude 세션은 기꺼이 이 두 단계를 다시 하나로 합쳐버린다는 것이었습니다.

시도 3에서 얻은 교훈은 프롬프트는 '조언'일 뿐이라는 것입니다. 모델은 조언을 무시할 수 있습니다. TDD를 강제하기 위해서는 모델이 무시할 수 없는 무언가가 필요했습니다. 그 무언가가 바로 훅(hook)입니다.

루프를 깨뜨린 PreToolUse 훅

Claude Code의 훅(hook) 시스템을 사용하면 도구 호출(tool calls)이 실행되기 전에 이를 가로챌 수 있습니다. Write 또는 Edit에 대한 PreToolUse 훅은 모델이 건드리려는 파일 경로를 가져옵니다. 만약 모델이 src/foo.py에 쓰려고 시도하는데 현재 실패하는 tests/foo_test.py가 없다면, 훅은 exit 2를 반환할 수 있으며, Claude Code는 이를 "이 도구 호출은 거부되었습니다. 여기 이유가 있으니 다시 시도하세요"라고 처리합니다.

다음은 pytest를 사용하는 Python 프로젝트에서 제가 성공한 가장 작은 규모의 버전입니다:

{
  "hooks": {
    "PreToolUse": [
...

스크립트는 도구 호출 페이로드 (tool call payload)에서 파일 경로를 읽어와, src/X.py를 tests/X_test.py로 매핑하고, 테스트 파일이 존재하는지 확인한 뒤, pytest tests/X_test.py --no-header -q를 실행합니다. 만약 pytest가 0으로 종료되면 (성공하면) 2를 반환하며 종료합니다. 테스트가 아직 존재하지 않거나 현재 테스트가 실패하는 경우, 훅 (hook)은 수정을 허용합니다. 만약 테스트가 존재하고 이미 통과하고 있다면, 훅은 "src/X.py를 수정하기 전에 tests/X_test.py에 실패하는 테스트가 반드시 존재해야 합니다. 실패하는 테스트를 먼저 작성하세요." 와 같은 메시지와 함께 수정을 차단합니다. 이 메시지는 모델의 다음 턴 컨텍스트 (next-turn context)에 전달됩니다. 모델에게는 선택권이 없습니다.

예외적인 상황들도 있습니다. 테스트 파일이 잘못된 이유로 통과할 수도 있는데, 훅은 이를 잡아내지 못합니다. 소스에서 테스트 경로로의 매핑은 프로젝트마다 다르며, 제 것은 하드코딩 (hardcoded) 되어 있습니다. 그리고 저는 탈출구 (escape hatch)를 마련해 두었는데, 첫 번째 줄에 # tdd-bypass: refactor라는 매직 코멘트 (magic comment)를 넣는 방식입니다. 이는 리팩터링 (refactor) 커밋을 위해, 즉 새로운 실패하는 테스트 없이 진정으로 수정을 하고 싶을 때 사용합니다. 리팩터링은 동작을 추가하는 것이 아니라 보존해야 하기 때문입니다. 훅은 이 탈출구를 존중하지만, 제가 주말에 검토할 파일에 그 사용 기록을 모두 남깁니다. 첫 주에는 탈출구 로그에 22개의 항목이 있었지만, 둘째 주에는 4개로 줄었습니다. 이 숫자가 줄어드는 것이 바로 핵심입니다.

30일 후 재실행 결과

훅을 도입한 지 30일 후에 동일한 감사를 수행했습니다. 동일한 프로젝트, 동일한 종류의 기능, 동일한 프롬프트 (prompt) 스타일을 사용했습니다. 수치는 다음과 같습니다:

• 테스트 파일을 먼저 커밋함: 10개 중 9개 (10개 중 4개에서 상승)
• 소스와 동일한 커밋에 테스트 파일을 커밋했으나, 파일 수정 타임스탬프 (file-modification timestamps) 기준으로 테스트를 먼저 작성함: 10개 중 1개
• 소스 이후에 테스트 파일을 커밋함: 10개 중 0개

테스트가 소스와 동일한 커밋에 포함되었던 유일한 기능은 제가 매직 코멘트로 정당하게 우회했던 12줄짜리 설정 헬퍼 (config helper)였습니다. 따라서 규칙이 적용되었을 때 TDD가 준수된 측면에서 보면, 수치는 10개 중 10개입니다.

이 훅 (hook)이 Claude를 규율 잡힌 TDD 실천가로 만들었다고 주장하고 싶지는 않습니다. 그렇지 않았습니다. 모델은 여전히 가끔

프롬프트 (prompts) 대 훅 (hooks) 대 MCP 서버 (MCP servers)를 어떻게 계층화할지 (어떤 종류의 규칙에 어떤 계층을 사용해야 하는지)에 대한 전체적인 그림을 보고 싶다면, Practical Claude Code에 정리해 두었습니다. 그중에서도 훅 (hooks) 장은 제가 계속해서 다시 읽게 되는 부분입니다.

출처:

• TDD with Claude Code (FlorianBruniaux/claude-code-ultimate-guide)
• How to Implement TDD with Claude Code TDD Skill (BSWEN, Mar 2026)
• My Skill Makes Claude Code GREAT At TDD (aihero.dev)
• Forcing Claude Code to TDD: an agentic red-green-refactor loop (alexop.dev)
• Claude Code Best Practices: Planning, Context Transfer, TDD (DataCamp)