byteforce

CPN 한국어 자습서 · 러닝패스 2 / 4 — Building with the Claude API

Anthropic 앱

Claude Code 실전

Claude Code in action

Claude Code를 "코드만 짜주는 도구"가 아니라 옆자리에서 함께 일하는 또 한 명의 엔지니어로 보는 시각을 익힙니다. 셋업부터 기능 설계·테스트·커밋까지 위임하고, init·CLAUDE.md·계획/TDD 워크플로로 Claude의 효과를 끌어올립니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · Anthropic 기술 스태프

Claude Code를 직접 다뤄 보도록, 함께 작업할 작은 프로젝트를 하나 준비했습니다. 이 강의에 첨부된 zip 파일에 소스가 들어 있습니다. 내려받아 압축을 풀고, 그 새 프로젝트 디렉터리에서 코드 에디터를 여세요.

프로젝트를 열면 곧장 ReadMe를 따라 셋업하고 싶을 텐데, 그 전에 Claude Code에 대해 꼭 이해할 점이 있습니다. Claude Code는 단지 코드를 대신 써 주는 도구가 아닙니다. 물론 그것도 할 수 있지만, 그게 전부가 아닙니다. 오히려 Claude Code를 이 프로젝트를 옆에서 함께 진행하는 또 한 명의 엔지니어로 보는 게 좋습니다. 평소 프로젝트에서 거치던 거의 모든 작업 — 초기 셋업부터 새 기능 설계, 배포, 지원까지 — 을 Claude에게 온전히 위임할 수 있습니다.

이 프로젝트를 진행하며 Claude를 적극 활용합니다. 셋업을 시키고, 새 기능을 계획하고, 테스트와 코드를 쓰게 합니다. 그리고 뒤에서는 조금 다른 프로젝트로, Claude Code가 프로덕션 환경의 에러를 자동으로 찾아 고치게 하는 모습도 보여 드립니다.

에디터에서 터미널을 열고 claude를 실행해 Claude Code를 띄웁니다. 그리고 첫 지시를 줍니다 — ReadMe 파일의 내용을 읽고, 거기 적힌 셋업 지시들을 실행해 달라고요. Claude는 여러 도구를 써서 그 파일을 읽고, 일련의 명령을 실행합니다. 새 가상환경을 만들고, 활성화하고, 의존성을 설치합니다.

그게 끝나면, Claude가 프로젝트를 더 잘 이해하도록 돕는 명령을 실행합니다 — init 명령입니다. 이 명령을 실행하면 Claude가 코드베이스를 자동으로 스캔해 프로젝트의 전반적인 아키텍처와 코딩 스타일 등을 파악합니다. 끝나면 그 결과를 CLAUDE.md라는 특별한 파일에 적습니다. 이후 Claude를 다시 실행할 때마다 이 파일이 컨텍스트로 자동 포함됩니다. 참고로 CLAUDE 파일에는 세 종류가 있습니다 — Project · Local · User. 잠시 뒤 다시 언급됩니다.

init 명령을 실행할 때 Claude가 특별히 집중했으면 하는 영역을 지시로 덧붙일 수도 있습니다. 저는 init을 실행하면서 "MCP 도구를 정의하는 법에 대한 상세 노트를 포함하라"는 특별 지시를 넣어 봤습니다. 끝나고 생성된 CLAUDE.md를 보면, 맨 위에는 앞으로 실행할 만한 중요한 명령들이 나열되고, 우리가 쓴 코딩 스타일이 정리되며, 제가 특별히 요청한 대로 MCP 도구 정의에 관한 정보까지 들어 있습니다.

프로젝트는 시간이 지나며 바뀝니다. 코딩 스타일을 바꾸거나 명령을 추가할 수도 있죠. 그럴 때는 이 파일을 직접 손으로 고치거나, init을 다시 실행하면 됩니다. 다시 실행하면 Claude가 CLAUDE.md 내용을 갱신합니다.

아주 작은 단축법으로, #(파운드)을 치고 파일에 덧붙이고 싶은 특정 노트를 적을 수 있습니다. Claude에게 아주 구체적인 작은 지시를 주는 도구로, 이후 모든 요청에 포함됩니다. 저는 예를 들어 "함수 인자에는 항상 적절한 타입을 붙여라" 같은 지시를 넣어 봅니다. 실행하면 이 노트를 어디에 넣을지 묻는데, 바로 여기서 Project · Local · User 메모리가 등장합니다. 제 경우 이 프로젝트에서 함께 일하는 모두와 공유하고 싶은 노트라 Project 메모리에 넣습니다. 그러면 CLAUDE.md의 Code Style 아래나 맨 아래쯤에 방금 넣은 노트가 보입니다.

이 시점에서 프로젝트에 새 파일이 하나 추가됐고, 이 프로젝트는 Git으로 관리됩니다. 보통이라면 터미널을 열어 이 파일을 스테이징하고 커밋하겠지만, Claude에게 시키면 훨씬 빠릅니다. "모든 변경을 스테이징하고 커밋해 줘"라고 하면, Claude가 변경 사항을 살펴 설명적인 커밋 메시지를 쓰고 파일을 커밋합니다.

다음으로, 코드를 쓸 때 Claude의 효과를 높이는 기법을 보여 드립니다. 이 프로젝트에 새 기능을 추가합니다 — 아주 작고 단순한 MCP 서버에, Word 문서나 PDF 파일을 읽어 Markdown으로 변환하는 도구를 더합니다. 그냥 "Word/PDF → Markdown 변환 도구를 만들어 줘"라고 지시할 수도 있습니다. 하지만 조금만 더 공을 들이면 Claude의 효과를 극적으로 높일 수 있습니다. Claude Code는 효과 배수기(effort multiplier)라고 생각하세요 — 지시에 약간의 노력을 들이면 훨씬 더 좋은 결과가 돌아옵니다.

두 가지 워크플로를 보여 드립니다. 첫 번째는 계획 워크플로로 세 단계를 거칩니다. 먼저, 만들려는 기능과 관련 있다고 아는 코드베이스의 부분을 짚어 Claude에게 그 파일들을 읽고 분석하라고 합니다. 예를 들어 Tools 디렉터리의 Math.py(이미 만들어진 도구 예시)와, 유용한 함수 binary_document_to_markdown이 든 document.py를 읽게 합니다. 둘째, 만들고 싶은 기능을 설명하고 해결책을 계획만 하라고 합니다 — 아직 코드는 쓰지 말라고 명시합니다. Claude는 구현에 필요한 단계들을 꽤 잘 정리한 계획을 내놓습니다. 셋째, 그 계획을 실제로 구현하라고 합니다. Claude는 document.py와 main.py를 갱신하고, 새 도구를 위한 테스트를 작성한 뒤 테스트 스위트를 돌려 통과를 확인합니다. 요약 메시지를 보면, 제가 명시적으로 요청하지 않았는데도 존재하지 않거나 지원되지 않는 파일 타입에 대한 에러 처리까지 적절히 추가했다고 알려 줍니다.

같은 기능을 만드는 또 다른 방법도 보여 드립니다. 그 전에, 방금 쓴 코드를 stash로 치워 깨끗한 상태로 돌아갑니다. 두 번째 기법은 테스트 주도 개발(TDD) 워크플로입니다. 역시 사전에 약간의 노력이 들지만 Claude의 효과를 크게 높입니다. 먼저 /clear 명령으로 대화 기록을 비워 컨텍스트를 리셋합니다(이전 해결책을 베끼지 못하게요). 그다음 관련 파일 두 개를 다시 읽게 합니다. 이어서 이 기능을 평가할 만한 테스트들을 생각해 보라고 아주 분명히 지시하고 — 역시 아직 코드는 쓰지 말라고 합니다. 돌아온 제안은 아주 탄탄합니다. 6·7·8번 테스트는 지금 단계엔 다소 특수해서, 1~5번 테스트만 구현하라고 합니다. 마지막으로, 이 테스트들이 통과하도록 코드를 써 달라고 합니다. 좋습니다 — 모든 테스트가 통과합니다.

넘어가기 전에 한 번 더 강조합니다. Claude Code는 효과 배수기입니다. 아주 단순한 지시만 줘도 Claude는 최선을 다하지만, 여러분 쪽에서 약간의 노력을 보태면 그 효과를 극적으로 끌어올릴 수 있습니다.

이 장에서 배우는 것What you'll learn

약 12분
1

Claude Code = 코드 머신이 아니라 함께 일하는 또 한 명의 엔지니어

2

claude 실행 → ReadMe 읽고 셋업 실행(가상환경·의존성)을 위임

3

init → 코드베이스 스캔 → CLAUDE.md에 기록 → 매 요청에 자동 컨텍스트

4

CLAUDE.md는 Project·Local·User 3종 + # 노트로 즉석 추가

5

"스테이징하고 커밋해 줘"로 Git 작업까지 위임

6

계획 워크플로(관련파일→계획만→구현) vs TDD 워크플로(/clear→읽기→테스트→통과까지 코드)

먼저 짚고 갈 용어
동료 엔지니어 시각
Claude Code를 코드 생성기가 아니라 셋업·설계·테스트·배포·지원을 함께 맡는 또 한 명의 엔지니어로 대하는 태도.
init · CLAUDE.md
init은 코드베이스를 스캔해 아키텍처·코딩 스타일을 파악하고 CLAUDE.md에 기록. 이후 모든 요청에 컨텍스트로 자동 포함.
Project · Local · User
CLAUDE.md 메모리 3종. Project=팀 공유, Local=내 로컬 전용, User=내 모든 프로젝트 공통.
# 노트 · /clear
#로 작은 지시를 CLAUDE.md에 즉석 추가(저장 위치 선택). /clear는 대화 기록을 비워 컨텍스트를 리셋.
효과 배수기
지시에 약간의 노력을 더하면(관련 파일 지정·계획·테스트) 훨씬 더 좋은 결과가 돌아온다는 원리.

코드 머신이 아니라, 동료 엔지니어

Another engineer on the team

Claude Code는 단지 코드를 대신 써 주는 도구가 아닙니다. 오히려 이 프로젝트를 옆에서 함께 진행하는 또 한 명의 엔지니어로 보는 게 좋습니다. 초기 셋업부터 기능 설계, 배포, 지원까지 평소 거치던 거의 모든 작업을 위임할 수 있습니다.

터미널 · Claude Code 실행 후 첫 지시
# 에디터에서 터미널을 열고 Claude Code 실행
$ claude

# 첫 지시 — 사람에게 말하듯
> ReadMe 파일을 읽고, 거기 적힌 셋업 지시를 실행해 줘.
  → Claude가 파일을 읽고 명령을 실행: 가상환경 생성 · 활성화 · 의존성 설치
출발점

ReadMe를 직접 따라 하기 전에, claude를 띄우고 "ReadMe를 읽고 셋업을 실행해 줘"라고 맡기는 것에서 시작합니다. Claude가 여러 도구로 파일을 읽고 가상환경·의존성까지 처리합니다.

init과 CLAUDE.md — 코드베이스를 기억하게

init & CLAUDE.md

/init을 실행하면 Claude가 코드베이스를 스캔해 아키텍처·코딩 스타일을 파악하고 CLAUDE.md에 기록합니다. 이 파일은 이후 모든 요청에 컨텍스트로 자동 포함됩니다.

Claude Code · /init (특별 지시 포함)
# Claude Code 안에서 실행하는 명령
/init MCP 도구를 정의하는 법에 대한 상세 노트를 포함해 줘.

# → 코드베이스 스캔 → CLAUDE.md 생성
#   · 자주 쓰는 명령 목록
#   · 이 프로젝트의 코딩 스타일
#   · (특별 요청) MCP 도구 정의 노트
CLAUDE.md · 코드베이스의 기억
/init코드베이스를 스캔해 아키텍처·코딩 스타일·주요 명령을 파악
→
CLAUDE.md파악한 내용을 한 파일에 기록 — 이후 모든 요청에 컨텍스트로 자동 포함
→
# 노트#으로 작은 지시를 즉석 추가 → 어느 메모리에 넣을지 선택
Project팀과 공유 — 함께 일하는 모두에게 적용되는 규칙(예: 함수 인자에 타입 붙이기).
Local이 프로젝트의 내 로컬 전용 노트. 다른 사람과 공유되지 않습니다.
User내가 작업하는 모든 프로젝트에 공통으로 적용되는 개인 설정.

코딩 스타일이 바뀌면 파일을 직접 고치거나 /init을 다시 실행하면 갱신됩니다. init에 "MCP 도구 정의 상세 노트 포함" 같은 특별 지시를 덧붙일 수도 있습니다.

# 노트와 커밋 위임

Quick notes & commits

#으로 작은 지시를 CLAUDE.md에 즉석 추가하고(저장 위치 선택), Git 스테이징·커밋도 한마디로 위임합니다.

Claude Code · # 노트와 커밋 위임
# 작은 지시를 CLAUDE.md에 즉석 추가
# 함수 인자에는 항상 적절한 타입을 붙여라

# → 어디에 넣을지 선택: Project / Local / User
#   팀과 공유하고 싶다 → Project 메모리

# 변경을 Git에 위임
> 모든 변경을 스테이징하고 커밋해 줘.
  → 변경을 살펴 설명적 커밋 메시지를 쓰고 커밋
팁

# 노트는 이후 모든 요청에 포함되는 영구 지시입니다. 반면 일회성 작업(커밋 등)은 그냥 평범한 문장으로 부탁하면 됩니다 — Claude가 변경을 살펴 커밋 메시지까지 써 줍니다.

효과 배수기 — 계획 vs TDD 워크플로

Effort multiplier

같은 기능(document_path_to_markdown — Word/PDF를 Markdown으로)을 두고, 지시에 약간의 노력을 더하는 두 워크플로를 비교합니다. 둘 다 Claude가 훨씬 복잡한 문제를 안정적으로 풀게 해 줍니다.

효과 배수기 · 두 워크플로 비교 — 탭을 눌러 단계를 펼쳐 보세요

단계를 미리 설계해 Claude가 한 번에 하나씩 집중하게 합니다. 관련 맥락을 먼저 읽히고, 코드 대신 계획만 받은 뒤, 그 계획을 구현시킵니다.

  1. 관련 파일 읽기기능과 관련 있는 코드를 짚어 줍니다 — 도구 예시 tools/math.py, 변환 함수가 든 document.py를 읽고 분석하라고 지시.
  2. 계획만 요청 (코드 X)만들 기능(document_path_to_markdown — PDF/Word 경로를 받아 Markdown 반환)을 설명하고 구현 단계를 계획만 하라고 명시.
  3. 계획 구현그 계획을 실제로 구현. Claude가 document.py·main.py를 갱신하고 테스트까지 작성·실행 — 요청 안 한 에러 처리도 알아서 추가.

핵심 · 미리 단계를 나누면 Claude가 한 번에 하나에 집중해 품질이 오릅니다.

테스트를 먼저 만들고, 그 테스트가 통과할 때까지 코드를 쓰게 합니다. 사전 노력은 더 들지만 효과가 큽니다.

  1. /clear + 관련 파일 읽기대화 기록을 비워 컨텍스트를 리셋(이전 해결책을 베끼지 않게). 그다음 관련 파일 두 개를 다시 읽힙니다.
  2. 테스트 후보 생각 (코드 X)이 기능을 평가할 만한 테스트들을 생각만 하라고 분명히 지시 — 아직 코드는 쓰지 않습니다.
  3. 테스트 1~5 구현제안 중 너무 특수한 6·7·8번은 빼고, 가장 관련 있는 1~5번 테스트만 구현하라고 합니다.
  4. 통과할 때까지 코드 작성그 테스트들이 모두 통과하도록 코드를 써 달라고 합니다 — 통과가 곧 완료 기준이 됩니다.

핵심 · 테스트가 명확한 목표가 되어 Claude가 그 기준을 충족할 때까지 스스로 다듬습니다.

두 워크플로 모두 약간의 사전 노력으로 훨씬 복잡한 문제를 맡길 수 있게 합니다 — 이것이 효과 배수기입니다.

정리 & 점검

Recap & check
핵심 정리
  • Claude Code는 코드 머신이 아니라 함께 일하는 또 한 명의 엔지니어 — 셋업·설계·테스트·커밋까지 위임.
  • /init → 코드베이스 스캔 → CLAUDE.md(Project·Local·User) → 매 요청에 자동 컨텍스트.
  • #으로 작은 지시를 즉석 추가, "스테이징하고 커밋해 줘"로 Git까지 위임.
  • 효과 배수기 — 계획 워크플로(관련파일→계획만→구현)와 TDD 워크플로(/clear→읽기→테스트→통과까지 코드).

Q1/init 명령이 하는 일은?

Q2CLAUDE.md 메모리 3종을 바르게 짝지은 것은?

Q3TDD 워크플로에서 코드를 쓰기 전에 하는 일은?

MEMBER SESSION REQUIRED · REGISTRATION IS FREE

여기부터는 등록한 분에게 열립니다.

전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 76개 레슨을 끝까지 읽을 수 있습니다.

등록하고 이어서 읽기

이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.