목차
Claude Code는 프로젝트 디렉터리에서 파일을 읽고, 명령을 실행하며, 변경사항을 diff로 제안하는 터미널 기반 코딩 에이전트다. 이 튜토리얼은 작은 Python CLI를 예시로 계획 → 구현 → 검증 → 디버깅을 반복하는 방법을 다룬다. 핵심은 에이전트에게 코드를 한 번에 맡기는 것이 아니라, 각 단계의 기대 결과를 사람이 검토 가능한 산출물로 바꾸는 데 있다.
준비: 빈 저장소와 짧은 지침
Claude Code를 설치·로그인한 뒤, 새 프로젝트에서 Git과 CLAUDE.md를 먼저 준비한다. 지침 파일은 길게 쓰기보다 언어 버전, 타입 힌트, 의존성 원칙처럼 반복해서 지킬 규칙만 둔다.
curl -fsSL https://claude.ai/install.sh | bash
mkdir mini-contacts && cd mini-contacts
git init
claude# Project Conventions
- Python 3.14 이상, PEP 8과 네 칸 들여쓰기를 사용한다.
- 공개 함수에는 타입 힌트를 쓴다.
- 필요한 경우에만 외부 의존성을 추가한다.1. 계획 모드에서 구현 계약 만들기
처음부터 “만들어 줘”라고 하기보다 Plan 모드에서 명세를 준다. 예를 들어 CSV 연락처 CLI라면 명령, 파일 경로, 패키지 구조, 오류 동작을 함께 적는다.
add는 이름·이메일·전화번호를 CSV에 추가하고,
list는 표 형태로 출력하는 Python CLI를 만든다.
argparse를 사용하고 저장 경로는 --path로 바꿀 수 있게 한다.
파일 구조, 함수 시그니처, 예외 처리, 테스트 순서를 먼저 제안해 줘.계획에서 다음을 확인한다.
- 파일별 책임과 공개 함수가 겹치지 않는가
- 파일 없음, 잘못된 CSV 헤더 같은 실패 경로가 있는가
- 실제로 실행할 검증 명령이 있는가
2. diff 단위로 구현하고 즉시 검증하기
계획을 승인한 뒤 구현을 요청하되, 한 번에 큰 변경을 받았다면 패키지 구조·저장 계층·CLI 순서로 나눠 검토한다. 각 의미 있는 단계가 끝날 때 Git에 커밋하면 에이전트의 다음 제안이 잘못됐을 때도 안전하게 돌아갈 수 있다.
python -m mini_contacts list
python -m mini_contacts add \
--name "Alice" --email "[email protected]" --phone "555-1234"
python -m mini_contacts list
git add . && git commit -m "Add contact CLI"3. 기존 버그를 재현 가능한 입력으로 고치기
디버깅 요청에는 “고쳐 줘”보다 오류 메시지, 재현 명령, 기대값을 함께 준다. Claude Code가 코드베이스를 탐색한 뒤 가설을 세우게 하고, 수정 전 실패 테스트와 수정 후 통과 결과를 모두 확인한다.
`python -m mini_contacts list --path /tmp/bad.csv`에서
잘못된 헤더가 조용히 무시된다. 기대 동작은 오류 메시지와 종료 코드 1이다.
원인을 찾고, 먼저 실패를 재현하는 테스트를 추가한 뒤 최소 변경으로 고쳐 줘.운영 체크리스트
| 단계 | 사람이 확인할 것 |
|---|---|
| 계획 | 요구사항·파일 구조·예외·검증 명령 |
| 구현 | diff의 권한 범위와 의존성 추가 |
| 실행 | 정상 경로와 실패 경로의 실제 출력 |
| 커밋 | 되돌릴 수 있는 작은 단위인지 |
| 새 세션 | 이전 결론과 다음 할 일이 문서·커밋에 남았는지 |
관련 문서
- claude-code — Claude Code의 기능과 설정
- claude-code-tips-best-practice — 프로젝트에서 안전하게 사용하는 원칙
- agent-harness — 테스트·Git·지침 파일을 에이전트 실행 환경으로 설계하는 방법
참고 자료
- How to Use Claude Code to Write and Debug Python — Real Python (2026-08-19)