【Claude Code 활용】 테스트 실행과 결과 해석을 맡기기

Claude Code의 커맨드 실행 능력

Claude Code는 bash 도구를 사용하여 터미널 커맨드를 직접 실행할 수 있습니다. 실행 결과를 읽고 "성공인지 실패인지", "다음에 무엇을 해야 하는지"를 스스로 판단하며, 에러가 발생할 경우 원인을 조사하여 수정까지 수행합니다.

이 "실행 → 해석 → 수정" 사이클을 자율적으로 돌릴 수 있다는 점이 단순한 코드 생성 도구와의 큰 차이점입니다.

실제로 맡겨 보았다: 동작 확인 스크립트 실행

agent01의 각 Step에는 동작 확인 스크립트가 준비되어 있습니다. 예를 들어 Step 08의 show_diff 구현 후에는 아래 스크립트를 실행하여 완료 조건을 확인했습니다.

def test_show_diff_direct() -> None:
"""show_diff의 단위 테스트 (LLM 미사용)."""
print("=" * 50)
...

Claude Code는 python src/step08_diff.py를 실행하고, 출력을 보고 "차이점(diff)이 올바르게 표시되고 있는지", "테스트 1~3이 모두 통과했는지"를 판단했습니다.

완료 조건 작성법

구현 지시서에는 "완료 조건" 체크리스트를 마련해 두었습니다. Claude Code는 이 체크리스트를 참조하며 자기 확인을 수행합니다.

## 완료 조건
- [ ] `python src/step08_diff.py`를 실행하여 에러 없이 완료할 것
- [ ] 테스트 1(일반적인 차이점)에서 unified diff 형식의 출력을 얻을 것
...

"동작 확인 스크립트를 실행하여 완료 조건 체크리스트를 확인해 주세요"라는 지시만으로, Claude Code가 실행·확인·보고까지 일련의 작업을 수행했습니다.

Windows 환경에서의 트러블슈팅 사례

Step 01 구현 중에 Claude Code가 스스로 인코딩 문제를 발견하고 수정한 사례가 있었습니다.

발생한 문제:

UnicodeEncodeError: 'cp932' codec can't encode character '✅'

Windows의 기본 인코딩은 cp932 (Shift_JIS)이기 때문에, UTF-8 이모지(✅ 등)를 표준 출력(standard output)으로 출력하려고 하면 에러가 발생했습니다.

Claude Code에 의한 수정:

에러 메시지를 읽은 Claude Code는 각 스크립트의 상단에 아래 행을 자동으로 추가했습니다.

import sys
sys.stdout.reconfigure(encoding="utf-8")
sys.stdin.reconfigure(encoding="utf-8")

에러 원인 특정, 수정 코드 생성, 동작 확인까지 일련의 작업을 모두 자율적으로 수행했습니다.

CLAUDE.md에는 "동작 확인이 완료된 것만 커밋할 것"이라는 규칙을 기재해 두었습니다. 이로 인해 Claude Code는 수정 후에 다시 스크립트를 실행하여 문제가 해결되었음을 확인한 뒤 커밋하는 행동을 취했습니다.

깨달은 점

테스트 주도(Test-Driven)에 가까운 개발 사이클이 자연스럽게 돌아감: 구현 지시서에 완료 조건을 명시해 둠으로써, Claude Code가 자발적으로 동작 확인을 수행하는 흐름이 만들어졌습니다. 이를 통해 "구현 → 테스트 → 커밋" 사이클이 사람의 개입 없이 완결되는 경우가 늘어났습니다.

에러 메시지가 그대로 수정의 힌트가 됨: Claude Code는 에러 메시지를 꼼꼼히 읽고 원인을 특정합니다. "cp932로 encode할 수 없다"는 메시지로부터 인코딩 문제를 즉시 이해한 것처럼, 에러 메시지가 풍부할수록 자율 수정의 정밀도가 높아집니다.

요약

Claude Code는 구현 후의 테스트 실행과 결과 해석을 자율적으로 수행합니다. 구현 지시서에 완료 조건 체크리스트를 마련해 둠으로써, "동작 확인 완료"라는 확신을 가지고 커밋으로 진행할 수 있는 운용이 실현되었습니다. 에러가 발생해도 스스로 수정까지 수행하기 때문에 인간의 개입이 최소한으로 줄어듭니다.

다음 회차

B6에서는 여러 파일을 가로지르는 변경을 Claude Code에게 맡긴 경험을 소개합니다. 도구 추가 시 3~4개 파일을 동시에 정확하게 업데이트한 사례를 전달해 드리겠습니다.

시리즈 링크 (Series B)

기사	제목
B1	Claude Code란 무엇인가 · 도입 및 초기 설정
...

Discussion