실전 개발자 가이드
개발자가 Claude 사용하는 방법: Claude Code, API, 에이전트 워크플로
터미널이 새로운 IDE가 되었지만, 신뢰의 단위는 여전히 diff다.
개발자는 Anthropic의 Claude를 세 가지 방식으로 사용한다. 기획과 리뷰를 위한 대화 상대로, 터미널에서 직접 실행하는 Claude Code로, 그리고 자체 API 기반 제품을 움직이는 모델로. 이 페이지에서는 각 방식에서 개발자가 Claude를 사용하는 방법을 코드 리뷰, 테스트 작성, 도구 사용을 위한 실제 프롬프트와 함께 살펴보고, AI가 작성한 코드가 프로덕션에 도달하기 전 안전하게 지키는 습관도 함께 다룬다.
개발자가 Claude 사용하는 방법은 결국 세 가지 화면으로 정리된다. 기획과 코드 리뷰를 위한 Claude AI 채팅 인터페이스, 저장소를 읽고 파일을 직접 수정하는 터미널 네이티브 에이전트 개발을 위한 Claude Code, 그리고 자체 제품에 도구 사용과 에이전트 워크플로를 구축하기 위한 Anthropic API다. 대부분의 개발자는 채팅에서 시작해 반복적인 수정과 테스트 작업을 Claude Code로 옮기고, Claude 기반 기능을 출시할 때가 되면 API를 찾는다. AI가 작성한 코드를 안전하게 지키는 습관은 다른 코드를 안전하게 지키는 습관과 같다. 작은 diff, 테스트, 그리고 머지 전 리뷰다.
게시일 · 최종 검토일
무료 레슨 · 계정 필요 없음Claude를 사용하는 세 가지 방법세 가지 모드5분무료 레슨 시작하기핵심 요약
- 개발자의 Claude 활용은 세 가지 화면에 걸쳐 있다. 기획과 코드 리뷰를 위한 채팅, 터미널 작업을 위한 Claude Code, 자체 도구 사용과 에이전트 기능을 구축하기 위한 Anthropic API다.
- Claude Code는 저장소를 읽고, 코드베이스 전반의 파일을 수정하고, 테스트 스위트를 실행하고, 변경사항을 커밋할 수 있다. 이 모든 것이 평범한 터미널 세션 안에서 이루어진다.
- 도구 사용을 활용하면 Claude가 직접 정의한 함수를 호출할 수 있어, 요청에 답하는 과정에서 데이터베이스를 조회하거나 내부 API를 호출하거나 스크립트를 실행할 수 있다.
- 코드 리뷰는 막연하게 '내 코드 좀 봐줘'라고 하는 것보다, 구체적인 diff와 확인할 구체적인 기준을 Claude에게 짚어줄 때 가장 효과적이다.
- Claude는 테스트를 작성하고 실행할 수 있지만, 생성된 코드를 안전하게 지키는 습관은 다른 기여자의 코드를 안전하게 지키는 습관과 같다. 작은 diff, 통과하는 테스트 스위트, 그리고 머지 전 사람의 리뷰다.
- CLAUDE.md 파일부터 시작하자. 스택, 명령어, 컨벤션을 Claude에게 알려주는 짧은 프로젝트 기준 문서로, Claude가 더 이상 추측하지 않도록 해준다.
Claude AI vs. Claude Code vs. Anthropic API
| 화면 | 적합한 작업 | 실행 위치 |
|---|---|---|
| Claude AI (채팅) | 기획, 아키텍처 논의, 붙여넣은 diff나 스택 트레이스 리뷰 | 브라우저 또는 데스크톱 앱 |
| Claude Code | 여러 파일 수정, 테스트 스위트 실행, 실제 저장소에서의 자율 작업 | 프로젝트 디렉터리 안의 터미널 |
| Anthropic API | 도구 사용을 포함해 자체 제품에 Claude 기반 기능이나 에이전트 구축하기 | HTTPS로 호출되는 애플리케이션 코드 |
복사해서 붙여넣기
오늘 바로 쓸 수 있는 프롬프트
특정 기준에 따라 풀 리퀘스트 diff 리뷰하기
지금 Python FastAPI 서비스의 풀 리퀘스트 diff를 리뷰하고 있다. SQL 인젝션 위험, 요청 본문에 대한 입력 검증 누락, 파라미터화되지 않은 데이터베이스 쿼리를 구체적으로 확인해줘. 각 문제를 파일과 라인 번호와 함께 나열하고, 왜 문제인지 설명하고, 수정 방법을 제안해줘. 포맷팅이나 스타일에 대해서는 언급하지 마.
자신의 스택에 맞게 언어, 프레임워크, 플래그로 표시하고 싶은 구체적인 위험을 바꿔서 사용하자.
기존 스타일에 맞는 테스트 작성하기
tests/test_orders.py에 있는 기존 테스트를 보고 구조, 픽스처, 네이밍 컨벤션을 정확히 똑같이 맞춰줘. orders/service.py에 있는 새 refund_order 함수에 대한 단위 테스트를 작성해줘. 성공적인 환불, 이미 환불된 주문에 대한 환불 시도, 원래 결제 금액을 초과하는 환불, 이 세 가지 경우를 다뤄줘. pytest와 기존 목(mock) 패턴을 사용해.
pytest, Jest, Vitest 등 실제 사용하는 테스트 파일과 프레임워크를 가리키게 하자.
전체 컨텍스트로 불안정한 테스트 디버깅하기
이 테스트가 CI에서는 간헐적으로 실패하는데 로컬에서는 통과해: [테스트 이름과 에러 붙여넣기]. 여기 테스트 파일, 이 테스트가 다루는 함수, 그리고 최근 CI 실패 로그 세 개가 있어. 수정안을 제안하기 전에 불안정성의 가능한 원인들을 먼저 짚어보고, 아직 확신이 서지 않는 부분이 있다면 명확히 말해줘.
버그를 기억에 의존해 설명하지 말고 실제 로그와 파일 내용을 붙여넣자.
Anthropic API용 도구 사용 함수 설계하기
Anthropic API로 에이전트를 만들고 있는데, 내부 REST API에서 고객의 주문 상태를 조회해야 해. 입력 파라미터용 JSON 스키마를 포함한 도구 정의를 작성하고, 결과로 나온 tool_use 블록을 처리해서 tool_result를 Claude에게 다시 보내는 Python 코드를 보여줘.
내부 API와 파라미터를 자신의 서비스 구조에 맞게 바꾸자.
새 프로젝트용 CLAUDE.md 작성하기
이 저장소의 package.json, README, 폴더 구조를 살펴본 다음, 우리 기술 스택, 테스트와 개발 서버를 실행하는 명령어, API 라우트 네이밍 컨벤션, 그리고 새 기여자가 첫 변경을 하기 전에 알아야 할 모든 것을 문서화한 CLAUDE.md 파일을 작성해줘.
프로젝트 시작 시 한 번 실행하고, 컨벤션이 바뀔 때마다 업데이트하자.
코드를 건드리기 전에 여러 파일에 걸친 리팩터링 계획 세우기
현재 세 개의 컨트롤러에 흩어져 있는 결제 로직을 하나의 PaymentService 클래스로 추출하고 싶어. 코드를 작성하기 전에, 현재 결제 로직이 들어 있는 모든 파일을 나열하고, 새 클래스의 public 메서드를 제안하고, 리팩터링 과정에서 유지해야 할 세 가지 현재 구현 간의 동작 차이를 짚어줘.
두세 개 이상의 파일에 영향을 주는 변경이라면 먼저 계획부터 요청하자.
여기서 시작
모든 개발자가 시작해야 할 무료 레슨
짧은 레슨 세 개만으로 Claude의 존재를 아는 단계에서 프로젝트 기준 문서를 갖춘 실제 Claude Code 세션을 운영하는 단계까지 갈 수 있다. 그날 바로 실제 업무에 사용하기에 충분한 수준이다.
세 가지 화면
개발자가 실제로 Claude를 사용하는 방식
개발자에게 Claude는 하나의 도구가 아니다. 세 가지이며, 지금 맡은 작업에 어떤 것이 맞는지 아는 것이 실력의 대부분이다.
Claude AI 채팅
아키텍처 논의, 붙여넣은 diff나 에러 메시지 리뷰, 코드 작성에 들어가기 전 설계를 고민하는 데 적합하다.
Claude Code
저장소를 읽고, 코드베이스 전반의 파일을 수정하고, 테스트 스위트를 실행하고, 지시에 따라 변경사항을 커밋할 수 있는 터미널 네이티브 에이전트다.
Anthropic API
모델과 도구 사용을 결합해 Claude를 자체 제품에 구축할 수 있다. 데이터베이스를 조회하는 지원 봇, IDE 내 어시스턴트, 무인으로 실행되는 파이프라인 등이다.
에이전트 워크플로
도구 사용을 루프와 결합한다. Claude가 호출할 도구를 정하고, 결과를 읽고, 다음 단계를 정하는 과정을 작업이 끝날 때까지 반복한다.
Claude Code
Claude Code란 무엇이고, 어떻게 시작해야 할까?
Claude Code는 코드베이스 안에서 직접 Claude와 함께 작업할 수 있는 Anthropic의 커맨드라인 도구다. 코드를 채팅창에 복사해 넣고 답을 다시 붙여넣는 대신, 프로젝트 디렉터리에서 실행하면 요청하는 작업의 맥락으로 파일, git 히스토리, 테스트 구성을 읽어들인다.
일반적인 세션은 이런 모습이다. 저장소에서 터미널을 열고 Claude Code를 실행한 다음, POST 엔드포인트에 레이트 리미팅을 추가하는 것 같은 작업을 평범한 언어로 설명한다. 관련 파일을 읽고, 변경이 영향을 미치는 파일 수에 관계없이 수정안을 제안하고 적용하고, 테스트 스위트를 실행한 뒤, 무엇을 바꿨는지와 테스트 통과 여부를 알려준다.
Claude Code가 에디터 플러그인과 다른 지점은 다음 한 줄이 아니라 작업 전체를 대상으로 움직인다는 점이다. 여러 단계로 이루어진 변경을 계획하고, 각 단계를 실행하고, 테스트가 실패하면 알아차리고, 수정을 시도하는 일을 당신의 지시 하나 안에서 모두 해낼 수 있다. 실행 전에 계획을 읽고 커밋 전에 diff를 리뷰함으로써 당신은 계속 그 과정에 관여하게 된다.
가장 먼저 설정할 가치가 있는 것은 프로젝트 루트에 CLAUDE.md 파일을 두는 것이다. 스택, 빌드와 테스트 명령어, 네이밍 컨벤션, 그리고 새 기여자가 첫날 알아야 할 그 밖의 모든 것을 평범한 언어로 짧게 적어둔 파일이다. 일단 존재하면 Claude Code는 추측하는 대신 매 세션 시작 시 이를 자동으로 읽는다.
실제 업무
개발자들이 이번 주에 실행하는 워크플로
보안 중심 코드 리뷰
일반적인 리뷰를 요청하는 대신, diff와 구체적인 위험 유형(인증 우회, 인젝션, 검증되지 않은 입력)을 Claude에게 짚어준다.
테스트 작성 및 실행
Claude는 기존 테스트 패턴과 프레임워크를 읽고, 스타일에 맞는 테스트를 작성하고, 실행하고, 실패에 대해 반복 수정한다.
여러 파일에 걸친 리팩터링
두세 개 이상의 파일에 영향을 주는 작업이라면 먼저 계획부터 요청한다. 어떤 파일이 바뀌는지, 새 구조가 어떤 모습인지, 어떤 동작이 바뀌어서는 안 되는지.
재현하기 어려운 버그 디버깅
실패하는 테스트, 테스트 대상 함수, 실제 실패 로그를 전달한 다음, 수정안을 제안하기 전에 원인을 먼저 추론하게 한다.
낯선 코드베이스 파악하기
Claude에게 요청이 코드베이스를 거쳐가는 경로를 추적하고 흐름을 설명해달라고 요청한다. 처음부터 코드를 읽는 것보다 대개 더 빠르다.
Anthropic API
도구 사용, 에이전트, 그리고 Anthropic API로 구축하기
Anthropic API는 채팅창을 통해서가 아니라 Claude를 직접 자체 제품 안에 넣는 방법이다. 프롬프트를 담아 요청을 보내면 응답이 돌아오는데, 다른 HTTP API와 같은 형태이기 때문에 Python 서비스든 Node 앱이든 그 밖의 어떤 백엔드 스택이든 이미 운영 중인 환경에 그대로 맞춰 들어간다.
도구 사용은 단일 요청-응답 호출을 에이전트에 더 가까운 무언가로 바꿔주는 기능이다. Claude가 접근할 수 있는 도구를 설명하는데, 각각은 이름, 설명, 입력값에 대한 JSON 스키마를 가진 함수다. 예를 들면 주문 ID를 받는 lookup_order 함수 같은 것이다. Claude가 질문에 답하기 위해 그 도구가 필요하다고 판단하면, 평범한 답변 대신 tool_use 블록을 반환한다. 당신의 코드는 실제 함수 호출을 실행하는데, 그것이 시스템에서 무엇을 의미하든, 즉 데이터베이스 쿼리든 API 호출이든 스크립트든, 결과를 tool_result로 Claude에게 다시 보낸다. Claude는 그 결과를 읽고 계속 진행한다.
실용적인 의미에서 에이전트란 이 루프를 한 번 이상 돌리는 것일 뿐이다. Claude가 도구를 고르면, 당신이 실행하고, Claude가 결과를 읽고 다음 도구를 고르는 과정을 작업이 끝나거나 답하기에 충분한 정보를 얻을 때까지 반복한다. Model Context Protocol은 이런 도구와 연결을 일관된 방식으로 설명하기 위한 표준으로, 같은 도구 정의가 프로젝트마다 처음부터 새로 연결할 필요 없이 서로 다른 클라이언트에서도 동작할 수 있게 해준다.
스트리밍은 알아둘 만한 또 다른 요소다. 전체 응답을 기다리는 대신, API는 토큰이 생성되는 대로 바로 돌려보낼 수 있는데, 이것이 채팅 인터페이스와 실시간 코드 제안이 느리지 않고 즉각적으로 느껴지게 만드는 이유다.
안전하게 유지하기
Claude의 코드 변경을 안전하게 지키는 방법
여기에 AI만의 특별한 것은 없다. 다른 기여자의 코드를 안전하게 지키는 것과 같은 규율을 일관되게 적용하는 것일 뿐이다.
diff를 작게 유지하기
한 번에 하나의 변경만 요청한다. 파일 다섯 개짜리 diff는 10분이면 리뷰할 수 있지만, 파일 쉰 개짜리 diff는 대충 넘어가게 되는데, 바로 그때 버그가 빠져나간다.
머지 전에 테스트, 후가 아니라
같은 작업의 일부로 Claude에게 테스트를 작성하거나 업데이트하게 하고, 테스트가 통과해야만 diff를 완료된 것으로 본다.
diff를 직접 읽기
Claude가 무엇을 왜 바꿨는지 설명할 수는 있지만, 코드를 커밋하는 사람은 여전히 그것을 실제로 읽었어야 할 책임이 있다.
프롬프트에 비밀 정보를 절대 붙여넣지 않기
API 키, 자격 증명, 고객 데이터는 Slack 메시지에 넣어서는 안 되는 것과 마찬가지로 채팅 기록이나 Claude Code 세션에도 넣어서는 안 된다.
컨벤션을 한 번 가르쳐두기
스택, 명령어, 스타일 가이드를 담은 CLAUDE.md 파일은 세션 시간을 잡아먹는 반복적인 수정 요청을 줄여준다.
시작하는 곳
개발자를 위한 시작 경로
개발자로서 Claude 사용이 처음이라면, 가장 빠른 길은 짧은 레슨 세 개를 순서대로 듣는 것이다. The Three Modes 코스에 있는 The Three Ways to Use Claude부터 시작하자. 위에서 다룬 것과 같은 채팅, Claude Code, API의 구분을 정리해주기 때문에, 터미널을 열기 전에 어떤 화면을 써야 할지 알 수 있다.
그다음에는 같은 The Three Modes 코스에 있는 Claude Code: Build With Words로 넘어가자. 실제 Claude Code 세션이 어떤 모습인지, 즉 평범한 언어로 작업을 설명하고, 저장소를 읽고 수정을 적용하는 과정을 지켜보고, 배포 전에 결과를 리뷰하는 과정을 보여준다.
세 번째는 The Practitioner Setup 코스에 있는 CLAUDE.md: your project spine다. 여기서 Claude가 매 세션마다 스택, 명령어, 컨벤션을 다시 추측하지 않도록 막아주는 파일을 작성하는 법을 배우는데, 이것이 이후 모든 세션을 더 빠르게 만들어주는 단 하나의 습관이다.
이 세 가지를 마치고 나면, The Practitioner Setup 코스의 나머지 부분에서는 훅과 자동화, MCP 서버를 통해 Claude를 스택에 연결하는 법, 그리고 주간 운영자 워크플로를 구축하는 법을 다루는데, 개발자로서 Claude를 사용하는 일상의 습관이 진짜로 쌓이는 지점이 바로 여기다.
한계
Claude가 틀리는 지점, 그리고 여전히 당신의 책임으로 남는 것
Claude는 확신에 차서 틀릴 수 있다. 당신이 생각하지 못한 엣지 케이스를 놓친 채 당신이 준 테스트는 통과하는 수정안을 제안하거나, 존재하지 않는 라이브러리 함수를 사용할 수도 있다. 그 결과물을 이미 내려진 결정이 아니라, 빠르고 박식한 협업자가 내놓은 강력한 초안으로 취급하자.
생성된 코드는 사람이 작성한 코드와 같은 보안 리뷰가 필요하고, 특정 코드베이스에서 어디서 실수하는 경향이 있는지 파악하기 전인 처음 몇 번은 오히려 더 많은 주의가 필요하다고 봐야 한다. 유창한 코드를 쓰는 도구에서 나왔다는 이유만으로 인증, 결제, 사용자 데이터를 다루는 부분에 대한 보안 중심 검토를 건너뛰지 말자.
기밀 소스 코드, 고객 데이터, 자격 증명은 조직의 정책을 먼저 확인하지 않고 어떤 AI 도구에도 넣어서는 안 된다. 데이터 처리 정책이나 고객 기밀 유지 의무가 있는 곳에서 일한다면, 검토자가 사람이 아니라 모델이라는 이유로 그 의무가 바뀌지는 않는다.
마지막으로, 자율성은 스위치가 아니라 다이얼이다. Claude Code는 허용하면 테스트를 실행하고 심지어 스스로 커밋까지 할 수 있지만, 전문가다운 습관은 공유 브랜치나 프로덕션에 도달하기 전에 사람의 리뷰 단계를 남겨두는 것이다. 신입사원이 입사 첫 달에 올리는 풀 리퀘스트에 바라는 것과 같은 관문이다.
Claude를 사용하는 세 가지 방법을 설명하는 무료 레슨 시작하기
개발자가 Claude 사용하는 방법을 읽는 것과 실제로 자신의 터미널에서 Claude Code를 실행해보는 것은 다른 일이다. Nightschool AI 커리큘럼은 첫 레슨부터 실습 중심이며, 이 페이지에서 다룬 것과 같은 채팅 대 Claude Code 대 API의 구분에서 시작한다.
자주 묻는 질문
개발자는 Claude를 어떻게 사용할까?
개발자는 대개 세 가지 화면에 걸쳐 Claude를 사용한다. 기획, 설계 논의, 붙여넣은 코드 리뷰를 위한 Claude AI 채팅 인터페이스, Claude가 실제 저장소를 읽고 수정하는 터미널 네이티브 작업을 위한 Claude Code, 그리고 도구 사용과 에이전트 루프를 포함해 자체 제품에 Claude를 구축하기 위한 Anthropic API다.
Claude Code란 무엇이고 어떻게 시작해야 할까?
Claude Code는 프로젝트 안에서 직접 Claude를 실행하는 커맨드라인 도구다. 저장소의 루트 디렉터리에서 실행한 다음 작업을 평범한 언어로 설명하면, 파일과 CLAUDE.md를 읽고, 수정을 적용하고, 테스트를 실행하고, 결과를 알려준다. 스택과 명령어를 설명하는 CLAUDE.md 파일을 먼저 준비해두면 초반 세션의 정확도가 훨씬 높아진다.
Claude는 코드 리뷰에 적합할까?
그렇다, 특히 보안 문제, 입력 검증 누락, 팀 컨벤션 준수 여부처럼 확인할 구체적인 diff와 구체적인 기준을 줬을 때 그렇다. 막연히 '내 코드 리뷰해줘'라고 할 때보다 구체적인 것을 확인하라고 요청했을 때 훨씬 더 강력한데, 사람 리뷰어도 명확한 리뷰 기준이 있을 때 더 좋은 결과를 내는 것과 같은 이치다.
Anthropic API는 어떻게 사용할까?
프롬프트를 담아 HTTP 요청을 보내면 텍스트 응답이 돌아오는데, 다른 API 호출과 같은 형태이기 때문에 Python, Node, 혹은 그 밖의 어떤 백엔드에서도 호출할 수 있다. 단순한 질문과 답변 이상의 것을 만들려면 도구 사용을 추가해 Claude에게 호출 가능한 함수를 주고, 그 결과로 오가는 tool_use와 tool_result 교환을 자신의 코드에서 처리하면 된다.
Claude의 도구 사용이란 무엇일까?
도구 사용을 이용하면 주문 조회나 데이터베이스 쿼리처럼 Claude가 호출할 수 있는 함수를 설명할 수 있는데, 각 함수는 이름과 입력값에 대한 JSON 스키마를 갖는다. Claude가 도구가 필요하다고 판단하면 평범한 답변 대신 tool_use 요청을 반환하고, 당신의 코드가 실제 함수를 실행해 결과를 다시 보내면 Claude가 이어서 진행한다. 이것이 대부분의 에이전트 워크플로의 기반이다.
Claude가 내 코드의 테스트를 작성해줄 수 있을까?
그렇다. Claude는 pytest, Jest, Vitest 등 기존 테스트 패턴과 프레임워크를 읽고, 스타일에 맞는 단위 테스트, 통합 테스트, 엔드투엔드 테스트를 작성할 수 있다. Claude Code에서는 직접 작성한 테스트를 실행하고 실패를 반복적으로 고칠 수도 있어서, 당신이 직접 디버깅해야 하는 테스트를 그냥 넘겨받는 것과는 다르다.
Claude의 코드 변경을 어떻게 안전하게 유지할까?
다른 기여자에게 바라는 것과 같은 규율을 유지하자. 광범위한 변경 대신 작은 diff를 요청하고, 머지되기 전에 테스트 통과를 요구하고, 커밋 전에 diff를 직접 읽고, 비밀 정보나 고객 데이터를 절대 프롬프트에 붙여넣지 않는다. CLAUDE.md 파일은 Claude가 컨벤션을 추측하면서 생기는 실수를 줄여준다.
Claude는 어떤 프로그래밍 언어를 지원할까?
Claude는 Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Ruby, PHP를 비롯한 주요 언어 전반에서 동작하며, React, Next.js, Django, FastAPI 같은 도구의 일반적인 프레임워크 패턴도 이해한다. Claude Code는 언어별 플러그인이 아니라 파일과 셸 명령어를 직접 다루기 때문에 터미널에서 실행되는 어떤 언어와도 함께 작동한다.
Claude Code는 설치가 무료일까?
Claude Code 자체는 설치가 무료다. 사용하려면 토큰 단위로 과금되는 Anthropic API 키나, Claude Code 접근 권한이 포함된 Claude 구독 플랜 중 하나가 필요하다. 커맨드라인 도구에 별도의 라이선스 비용이 추가되지는 않는다.