AI 엔지니어와 알아보는 Claude Code 공략집 - 2편
1편에서는 Claude Code를 설치하고, 터미널에서 프로젝트 폴더를 여는 흐름까지 정리했다. 2편에서는 Claude Code를 실제 프로젝트에서 안전하게 쓰는 방법을 정리한다. 초점은 명령어를 많이 외우는 것이 아니라, 프로젝트를 열고, 요청하고, 변경사항을 검토하고, 되돌릴 수 있는 기본 작업 흐름을 몸에 익히는 데 있다.
Claude Code는 터미널에서 실행되는 에이전트형 코딩 도구다. Anthropic은 Claude Code를 코드베이스를 이해하고, 파일을 수정하고, 테스트를 실행하고, Git 작업을 도와주는 도구로 설명한다. 이 글에서는 Claude Code 공식 문서의 기본 개념을 기준으로, 초보자가 실수하기 쉬운 지점을 단계별로 분리해서 다룬다.
Claude Code는 터미널에서 프로젝트를 읽고 수정하는 개발 워크플로우 안에서 사용된다.
1. 2편에서 다룰 범위
2편의 핵심은 설치 이후의 첫 사용이다. Claude Code를 실행하는 것 자체는 어렵지 않지만, 처음 사용하는 사람에게는 다음 단계가 더 어렵다.
- 어떤 폴더에서 실행해야 하는지 판단한다.
- Claude에게 무엇을 요청해야 하는지 문장으로 작성한다.
- Claude가 파일을 바꾸겠다고 할 때 허용해도 되는지 판단한다.
- 변경된 파일을 직접 확인한다.
- 마음에 들지 않는 변경을 되돌린다.
- 반복 작업을 줄이기 위해 프로젝트 규칙을 남긴다.
이 글에서는 위 과정을 하나의 기본 루프로 정리한다. 흐름은 폴더 선택 -> 현재 상태 확인 -> 작은 요청 -> 변경 검토 -> 테스트 -> 커밋이다.
2. 프로젝트 폴더를 먼저 이해한다
Claude Code는 현재 터미널이 위치한 폴더를 기준으로 작업한다. 그래서 Claude를 실행하기 전에 가장 먼저 해야 할 일은 “내가 지금 어느 폴더에 있는가”를 확인하는 것이다.
터미널에서 현재 위치를 확인하는 명령은 다음과 같다.
pwd
macOS와 Linux에서는 pwd가 현재 디렉터리 경로를 출력한다. Windows PowerShell에서는 다음 명령으로 현재 위치를 볼 수 있다.
Get-Location
초보자에게 가장 중요한 원칙은 프로젝트 최상위 폴더에서 Claude Code를 실행하는 것이다. 프로젝트 최상위 폴더는 보통 다음 파일이나 폴더가 있는 위치다.
.gitpackage.jsonpyproject.tomlrequirements.txtREADME.mdsrcapp
예를 들어 Next.js 프로젝트라면 package.json과 next.config.js가 있는 위치가 기준이 된다. Python FastAPI 프로젝트라면 pyproject.toml, requirements.txt, app 폴더가 있는 위치가 기준이 되는 경우가 많다.
Claude Code를 실행하기 전에는 현재 위치가 프로젝트 루트인지 확인해야 한다.
3. Claude Code 실행 전 체크리스트
Claude Code를 실행하기 전에 프로젝트가 안전한 상태인지 확인해야 한다. 여기서 말하는 안전한 상태는 “현재 변경사항을 내가 알고 있고, 문제가 생기면 되돌릴 수 있는 상태”를 뜻한다.
Git 프로젝트라면 먼저 상태를 확인한다.
git status
출력에 nothing to commit, working tree clean과 비슷한 문장이 보이면 작업 디렉터리가 깨끗한 상태다. 반대로 수정된 파일이 이미 있다면 Claude Code를 실행하기 전에 그 수정이 내가 만든 것인지 확인해야 한다.
변경 내용을 자세히 볼 때는 다음 명령을 사용한다.
git diff
처음에는 git diff 출력이 길고 낯설 수 있다. 그래도 최소한 어떤 파일이 바뀌었고, 어떤 줄이 추가 또는 삭제되었는지는 확인하는 습관이 필요하다. Claude Code가 파일을 수정한 뒤에도 같은 명령으로 결과를 확인하게 된다.
Git에 아직 익숙하지 않은 경우에도 이 두 명령은 먼저 익혀야 한다.
git status: 어떤 파일이 변경되었는지 확인한다.git diff: 파일 안에서 어떤 내용이 바뀌었는지 확인한다.
Claude Code는 편리한 도구지만, 변경의 최종 책임은 개발자에게 있다. 자동으로 수정된 코드를 검토하지 않고 실행하거나 커밋하는 방식은 피해야 한다.
4. Claude Code를 실행한다
프로젝트 최상위 폴더로 이동한 뒤 Claude Code를 실행한다.
claude
Anthropic의 Claude Code quickstart는 프로젝트 폴더에서 claude 명령을 실행해 대화를 시작하는 흐름을 안내한다. 이 방식은 일반적인 채팅 UI와 다르게, Claude가 현재 코드베이스를 읽고 작업할 수 있다는 점이 핵심이다.
처음 실행하면 인증이나 권한 관련 안내가 나올 수 있다. 이 단계에서 터미널에 표시되는 문장을 그대로 읽는 것이 중요하다. 특히 파일 읽기, 파일 수정, 명령 실행과 관련된 요청은 무조건 허용하지 않는다.
처음 입력할 프롬프트는 작아야 한다. 예를 들어 다음처럼 시작한다.
이 프로젝트 구조를 초보자도 이해할 수 있게 설명해 줘. 아직 파일은 수정하지 말고, 주요 폴더와 실행 방법만 정리해 줘.
이 프롬프트에는 중요한 제한이 들어 있다.
- 프로젝트 구조 설명만 요청한다.
- 파일 수정은 하지 말라고 명시한다.
- 실행 방법을 정리하라고 요청한다.
처음부터 “전체 리팩터링해 줘”라고 요청하면 변경 범위가 커진다. 초보자는 큰 변경을 검토하기 어렵다. 그래서 첫 요청은 읽기와 설명 중심으로 시작하는 편이 안전하다.
처음에는 읽기 전용 요청으로 프로젝트 구조를 설명받는 흐름이 안전하다.
5. 좋은 프롬프트는 작업 범위를 좁힌다
Claude Code를 잘 쓰려면 프롬프트를 길게 쓰는 것보다 작업 범위를 정확히 좁히는 것이 중요하다. 코딩 에이전트는 요청이 모호할수록 더 많은 파일을 읽고, 더 넓은 범위의 변경을 제안할 수 있다.
좋은 요청은 보통 다음 요소를 포함한다.
- 목표: 무엇을 하려는지 적는다.
- 범위: 어떤 파일 또는 폴더만 다룰지 적는다.
- 금지 조건: 하지 말아야 할 일을 적는다.
- 검증 방법: 어떤 명령으로 확인할지 적는다.
- 출력 형식: 설명, 계획, diff 요약 등 원하는 형태를 적는다.
예시는 다음과 같다.
src/components/LoginForm.tsx 파일만 보고, 로그인 버튼이 비활성화되는 조건을 설명해 줘. 아직 코드는 수정하지 마. 마지막에는 수정이 필요해 보이는 지점만 bullet로 정리해 줘.
파일 수정을 요청할 때는 더 구체적으로 적는다.
src/components/LoginForm.tsx 파일에서 이메일 형식 검증 메시지를 더 명확하게 바꿔 줘. UI 구조는 바꾸지 말고, 문구와 validation 함수만 수정해 줘. 수정 후 어떤 줄이 바뀌었는지 요약해 줘.
테스트까지 포함할 때는 검증 명령을 함께 적는다.
회원가입 폼의 비밀번호 검증 로직을 수정해 줘. 수정 범위는 src/features/signup 아래로 제한해 줘. 변경 후 npm test -- signup 명령으로 확인해 줘.
이런 방식은 Claude에게도 좋고, 작업을 검토하는 사람에게도 좋다. 범위가 좁으면 실패했을 때 되돌리기 쉽고, 성공했을 때도 변경 이유를 설명하기 쉽다.
6. 계획을 먼저 받는 습관
Claude Code를 처음 사용할 때는 곧바로 수정 요청을 하기보다 계획을 먼저 받는 방식이 안전하다.
이 버그를 고치기 전에 먼저 원인을 추정하고, 확인해야 할 파일 목록과 수정 계획을 작성해 줘. 아직 파일은 수정하지 마.
이 요청은 Claude가 바로 코드를 바꾸지 않게 만든다. 먼저 어떤 파일을 볼지, 어떤 가설을 세우는지, 어떤 순서로 수정할지 확인할 수 있다.
계획을 받은 뒤에는 다음 기준으로 판단한다.
- 설명한 문제가 실제 증상과 맞는가.
- 확인하려는 파일이 문제와 관련 있어 보이는가.
- 수정 범위가 지나치게 넓지 않은가.
- 테스트 또는 검증 방법이 포함되어 있는가.
계획이 너무 넓다면 다시 좁힌다.
수정 범위가 넓어 보여. 우선 src/api/auth.ts와 src/features/login 폴더만 대상으로 다시 계획을 세워 줘.
계획이 납득되면 그때 수정 요청을 한다.
좋아. 방금 계획대로 수정해 줘. 단, public API 이름은 바꾸지 말고, 수정 후 diff 요약을 먼저 보여 줘.
이 흐름은 실무에서도 유용하다. 에이전트에게 일을 맡기되, 작업 방향을 사람이 통제하는 구조가 된다.
7. 권한 요청을 읽는 방법
Claude Code는 파일을 읽거나 수정하거나 명령을 실행하는 과정에서 권한 확인을 요청할 수 있다. 권한 확인 화면은 초보자에게 가장 부담스러운 부분 중 하나다. 하지만 기준을 나누면 판단이 쉬워진다.
상대적으로 안전한 요청은 다음과 같다.
- 프로젝트 내부 파일 읽기
- 특정 소스 파일 수정
- 테스트 명령 실행
- 린트 명령 실행
- 타입 체크 명령 실행
주의가 필요한 요청은 다음과 같다.
- 프로젝트 전체 파일 대량 수정
- 삭제 명령 실행
- 패키지 설치
- 네트워크 요청이 포함된 명령 실행
- 환경 변수나 인증 파일 접근
- 홈 디렉터리나 시스템 폴더 접근
특히 .env, .npmrc, SSH 키, 클라우드 인증 파일 같은 민감한 파일은 다룰 때 주의해야 한다. Anthropic은 Claude Code의 보안 모델과 권한 제어를 security 문서에서 설명한다. 핵심은 에이전트가 개발 환경 안에서 강력한 작업을 수행할 수 있으므로, 권한 허용을 작업 단위로 판단해야 한다는 점이다.
초보자 기준으로는 다음 원칙을 적용하면 된다.
- 내가 이해하지 못한 명령은 허용하지 않는다.
- 삭제, 설치, 배포 관련 명령은 한 번 더 확인한다.
- 민감한 파일을 읽으려는 요청은 거절한다.
- 테스트와 타입 체크처럼 검증 목적이 분명한 명령부터 허용한다.
8. 변경사항은 반드시 Git으로 확인한다
Claude가 파일을 수정한 뒤에는 바로 실행하거나 커밋하지 않는다. 먼저 Git 상태를 확인한다.
git status
변경된 파일 목록을 본 뒤 diff를 확인한다.
git diff
변경 파일이 많다면 파일별로 확인할 수 있다.
git diff src/components/LoginForm.tsx
검토할 때는 다음 순서로 본다.
- 내가 요청한 파일만 바뀌었는가.
- 요청하지 않은 기능 변경이 들어갔는가.
- 삭제된 코드가 있는가.
- 테스트 코드가 함께 수정되었는가.
- 설정 파일이 의도치 않게 바뀌었는가.
Claude가 만든 변경을 취소하려면 Git을 사용한다. 특정 파일만 되돌릴 때는 다음 명령을 사용할 수 있다.
git restore src/components/LoginForm.tsx
모든 변경을 되돌리는 명령도 있지만, 초보자는 매우 신중해야 한다.
git restore .
이 명령은 현재 작업 디렉터리의 변경을 되돌릴 수 있다. 직접 작성한 변경까지 함께 사라질 수 있으므로 실행 전에 git status와 git diff로 상태를 확인해야 한다.
Claude Code가 만든 변경사항은 git diff로 직접 검토해야 한다.
9. 테스트와 실행 확인을 분리한다
코드 변경이 끝났다면 검증이 필요하다. 검증은 크게 세 단계로 나눌 수 있다.
- 정적 검사: 타입 체크, 린트
- 자동 테스트: unit test, integration test
- 수동 확인: 브라우저 또는 API 호출로 직접 확인
JavaScript 또는 TypeScript 프로젝트에서는 다음 명령을 자주 사용한다.
npm run lint
npm test
npm run build
Python 프로젝트에서는 다음 명령이 자주 쓰인다.
pytest
python -m pytest
ruff check .
mypy .
Claude에게 검증까지 요청할 때는 명령을 명시하는 편이 좋다.
수정 후 npm run lint와 npm test를 실행해 줘. 실패하면 실패 원인을 요약하고, 바로 추가 수정하지 말고 먼저 나에게 설명해 줘.
여기서 “바로 추가 수정하지 말고 먼저 설명해 줘”라는 조건이 중요하다. 테스트 실패 후 에이전트가 연쇄적으로 많은 파일을 수정하는 상황을 줄일 수 있다.
10. CLAUDE.md로 프로젝트 규칙을 남긴다
Claude Code를 반복해서 사용할수록 같은 설명을 계속 입력하는 일이 생긴다. 예를 들어 프로젝트 구조, 코딩 스타일, 테스트 명령, 금지해야 할 작업은 매번 설명하기 번거롭다.
Claude Code는 프로젝트별 지침을 남기는 방식으로 CLAUDE.md를 사용할 수 있다. Anthropic의 memory 문서는 Claude Code가 프로젝트와 사용자 수준의 메모리를 통해 작업 맥락을 유지하는 방식을 설명한다.
초보자에게는 먼저 프로젝트 루트에 CLAUDE.md를 두는 방식이 이해하기 쉽다. 예시는 다음과 같다.
# Project Guide for Claude
## Project overview
이 프로젝트는 Next.js 기반 웹 애플리케이션이다.
## Commands
- 개발 서버: npm run dev
- 린트: npm run lint
- 테스트: npm test
- 빌드: npm run build
## Rules
- UI 컴포넌트는 src/components 아래에 둔다.
- API 호출 로직은 src/lib/api 아래에 둔다.
- package.json 변경은 요청받았을 때만 수행한다.
- .env 파일은 읽거나 수정하지 않는다.
- 대규모 리팩터링 전에는 먼저 계획을 작성한다.
## Response style
- 수정 전에는 간단한 계획을 먼저 설명한다.
- 수정 후에는 변경 파일과 검증 결과를 요약한다.
이 파일은 에이전트에게 프로젝트의 기본 규칙을 알려주는 역할을 한다. 중요한 점은 너무 많은 내용을 넣지 않는 것이다. 실제로 지켜야 할 규칙과 자주 사용하는 명령 위주로 짧게 유지하는 편이 좋다.
반복되는 프로젝트 규칙은 CLAUDE.md에 짧고 명확하게 남기는 편이 좋다.
11. 슬래시 명령을 이해한다
Claude Code에는 대화 중 사용할 수 있는 슬래시 명령이 있다. Anthropic은 slash commands 문서에서 내장 명령과 커스텀 명령의 사용 방식을 설명한다.
초보자 관점에서는 모든 명령을 외울 필요가 없다. 처음에는 다음 종류의 명령이 있다는 정도만 이해하면 된다.
- 현재 대화나 설정을 확인하는 명령
- 도움말을 보는 명령
- 작업 맥락을 정리하는 명령
- 반복 프롬프트를 줄이는 커스텀 명령
슬래시 명령은 일반적인 자연어 요청과 다르게 Claude Code 자체의 동작을 제어하는 데 쓰인다. 예를 들어 특정 작업 절차를 커스텀 명령으로 만들어 두면, 매번 긴 프롬프트를 입력하지 않아도 된다.
커스텀 명령을 처음부터 만들 필요는 없다. 먼저 자연어 프롬프트로 충분히 사용해 보고, 같은 요청을 반복하게 될 때 명령으로 정리하는 편이 좋다.
12. 설정 파일과 개인 설정은 분리한다
Claude Code 설정은 프로젝트 설정과 개인 설정을 나누어 생각해야 한다. 팀 프로젝트에서 모든 사람이 공유해야 하는 규칙과, 내 로컬 환경에서만 필요한 설정은 성격이 다르다.
Anthropic의 settings 문서는 Claude Code 설정의 범위와 우선순위를 설명한다. 초보자는 다음 기준으로 이해하면 충분하다.
- 프로젝트 규칙: 팀이 함께 지켜야 하는 내용
- 개인 규칙: 내 응답 선호나 로컬 작업 습관
- 민감 정보: 설정에 넣지 않아야 하는 값
API 키, 토큰, 비밀번호, 개인 접근 키는 설정 파일이나 CLAUDE.md에 직접 적지 않는다. 이런 값은 환경 변수나 비밀 관리 도구로 다루어야 한다.
프로젝트 문서에 남겨도 되는 내용은 다음과 같다.
- 테스트 명령
- 빌드 명령
- 폴더 구조
- 코딩 컨벤션
- 금지된 자동 수정 범위
프로젝트 문서에 남기면 안 되는 내용은 다음과 같다.
- 실제 API 키
- 운영 서버 접속 정보
- 개인 토큰
- 비밀번호
- 고객 데이터
13. 초보자용 첫 실습 시나리오
아래 시나리오는 Claude Code를 처음 사용하는 사람이 따라 하기 좋은 순서다. 중요한 점은 한 번에 큰 작업을 맡기지 않는 것이다.
13.1 현재 프로젝트 설명 받기
이 프로젝트의 폴더 구조와 실행 방법을 초보자 기준으로 설명해 줘. 아직 파일은 수정하지 마.
이 단계에서는 읽기만 수행한다. Claude의 설명과 실제 README.md, package.json 내용을 비교해 본다.
13.2 테스트 명령 찾기
이 프로젝트에서 테스트, 린트, 빌드를 실행하는 명령을 찾아서 정리해 줘. package.json이나 문서 파일을 기준으로 설명해 줘. 파일은 수정하지 마.
이 단계에서는 프로젝트의 검증 명령을 파악한다. 이후 변경 작업의 안전장치가 된다.
13.3 작은 문구 수정 맡기기
src/components 안에서 로그인 버튼 문구를 렌더링하는 파일을 찾아 줘. 찾은 뒤 버튼 문구만 "로그인하기"로 바꿔 줘. 다른 UI 구조는 수정하지 마.
수정이 끝나면 직접 확인한다.
git status
git diff
13.4 검증 실행하기
방금 변경과 관련해서 실행할 만한 가장 작은 검증 명령을 제안해 줘. 바로 실행하지 말고, 왜 그 명령이 적절한지 먼저 설명해 줘.
설명이 납득되면 실행을 허용한다.
13.5 커밋 메시지 초안 받기
현재 git diff를 기준으로 커밋 메시지 후보를 3개 작성해 줘. Conventional Commits 형식으로 작성해 줘.
커밋은 사람이 직접 수행한다. 초보자는 Claude에게 커밋까지 자동으로 맡기기보다, 변경 내용을 검토한 뒤 직접 커밋하는 흐름을 먼저 익히는 편이 좋다.
14. 실무에서 자주 쓰는 요청 템플릿
Claude Code에 익숙해지기 전에는 템플릿을 복사해서 쓰는 편이 안정적이다.
14.1 읽기 전용 분석
다음 문제를 분석해 줘. 아직 파일은 수정하지 마.
문제:
- 여기에 증상을 적는다.
원하는 출력:
- 원인 후보
- 확인해야 할 파일
- 수정 계획
- 검증 방법
14.2 제한된 수정
아래 범위 안에서만 수정해 줘.
목표:
- 여기에 목표를 적는다.
수정 가능 범위:
- src/features/example
수정 금지:
- package.json
- .env
- public API 이름
수정 후:
- 변경 파일 요약
- 실행한 검증 명령
- 남은 위험 요소
14.3 테스트 실패 분석
아래 테스트 실패 로그를 분석해 줘. 아직 파일은 수정하지 마.
로그:
```text
여기에 실패 로그를 붙여 넣는다.
원하는 출력:
- 실패 원인 요약
- 가장 가능성 높은 수정 위치
- 추가로 확인할 명령
### 14.4 리팩터링 계획
```text
이 코드를 리팩터링하기 전에 계획만 세워 줘. 동작 변경은 없어야 한다.
대상:
- 여기에 파일 또는 폴더를 적는다.
제약:
- public interface 변경 금지
- 테스트가 없으면 먼저 테스트 추가 제안
- 한 번에 5개 이하 파일만 수정
15. 흔한 실수와 대응 방법
초보자가 Claude Code를 사용할 때 자주 겪는 문제는 대체로 비슷하다.
첫 번째는 너무 큰 요청을 하는 것이다. “전체 코드를 개선해 줘” 같은 요청은 변경 범위가 넓고 검토가 어렵다. 파일 하나, 함수 하나, 테스트 하나처럼 작은 단위로 나누는 편이 좋다.
두 번째는 변경사항을 확인하지 않는 것이다. Claude가 수정했다고 해서 바로 맞는 것은 아니다. git diff 확인은 선택이 아니라 기본 절차다.
세 번째는 테스트 실패 후 자동 수정을 계속 허용하는 것이다. 테스트가 실패하면 원인을 먼저 설명하게 하고, 사람이 수정 방향을 확인한 뒤 진행해야 한다.
네 번째는 민감 정보를 프롬프트나 문서에 붙여 넣는 것이다. 에이전트가 프로젝트 파일을 읽고 명령을 실행할 수 있는 환경에서는 비밀값 관리가 더 중요하다.
다섯 번째는 프로젝트 규칙을 매번 말로만 전달하는 것이다. 반복되는 규칙은 CLAUDE.md에 정리해 두면 작업 품질이 안정된다.
16. 2편의 기본 작업 루프
상태 확인, 계획 요청, 작은 수정, diff 검토, 검증을 반복하는 구조가 Claude Code 사용의 기본이다.
정리하자면 2편의 핵심 루프는 다음과 같다.
1. 프로젝트 루트로 이동한다.
2. git status로 현재 상태를 확인한다.
3. claude를 실행한다.
4. 먼저 읽기 전용 분석을 요청한다.
5. 계획을 검토한다.
6. 작은 범위로 수정을 허용한다.
7. git diff로 변경을 확인한다.
8. 테스트 또는 린트를 실행한다.
9. 결과가 납득되면 직접 커밋한다.
10. 반복 규칙은 CLAUDE.md에 남긴다.
Claude Code를 잘 쓰는 기준은 “얼마나 많은 일을 한 번에 시키는가”가 아니다. 사람이 이해할 수 있는 단위로 일을 나누고, 각 단계마다 검토 가능한 상태를 유지하는 것이 핵심이다. 이 원칙을 지키면 초보자도 터미널 기반 에이전트 도구를 안정적으로 사용할 수 있다.