Claude Code는 앤트로픽이 만든 터미널 기반 코딩 에이전트예요. 설치까지는 어렵지 않은데, 막상 실행하고 나면 무엇을 어떻게 시켜야 결과가 좋은지 몰라서 헤매는 경우가 많아요. 이 글은 설치가 끝났다고 가정하고, 프로젝트 폴더에서 실제로 작업을 맡길 때 쓰는 방법에 집중해요.
시작하는 기본 흐름
작업할 프로젝트 폴더로 이동한 뒤 터미널에서 claude 명령을 실행하면 대화형 세션이 열려요. 이 세션은 현재 폴더를 작업 범위로 삼아서 파일을 읽고, 수정하고, 명령을 실행해요. 그래서 시작하기 전에 어느 폴더에서 실행하는지가 중요해요.
처음에는 “이 프로젝트 구조를 설명해줘”처럼 읽기만 하는 요청으로 시작하는 게 안전해요. 코드베이스를 이해시킨 뒤에 수정 요청을 하면 엉뚱한 파일을 건드릴 확률이 줄어요.
한 번만 결과를 받고 끝내는 방식도 있어요. claude 뒤에 질문을 붙여서 실행하거나 -p 옵션으로 결과만 출력하게 하면, 스크립트 안에서도 활용할 수 있어요.
CLAUDE.md로 프로젝트 규칙 알려주기
Claude Code는 세션을 시작할 때 프로젝트 루트의 CLAUDE.md 파일을 읽어요. 여기에 프로젝트 개요, 코딩 컨벤션, 자주 쓰는 명령어, 지켜야 할 주의사항을 적어두면 매번 같은 설명을 반복하지 않아도 돼요.
내용은 짧고 구체적일수록 좋아요. “테스트는 pytest로 실행”, “타입 힌트 필수”, “환경 변수 파일은 커밋 금지” 같은 한 줄 규칙이 잘 먹혀요. 반대로 긴 설명문은 핵심이 묻혀요.
- 프로젝트 개요: 무엇을 하는 프로젝트이고 어떤 기술 스택을 쓰는지 몇 줄로 적어요.
- 실행 명령어: 빌드, 테스트, 린트 명령을 그대로 적어두면 Claude가 작업 후 스스로 검증해요.
- 금지 사항: 건드리면 안 되는 폴더나 파일, 지켜야 할 규칙을 명시해요.
사용자 홈 폴더에 두는 전역 설정 파일도 있어서, 모든 프로젝트에 공통으로 적용할 선호는 거기에 적을 수 있어요.
자주 쓰는 슬래시 명령어
세션 안에서 슬래시(/)로 시작하는 명령을 입력하면 도구 자체를 제어할 수 있어요. 버전마다 목록이 조금씩 바뀌니 /help로 현재 명령을 확인하는 습관을 들이세요.
- /help: 사용 가능한 명령과 안내를 보여줘요.
- /clear: 대화 기록을 비우고 새 작업을 시작해요. 다른 주제로 넘어갈 때 쓰면 불필요한 맥락이 줄어요.
- /compact: 대화를 요약해서 압축해요. 긴 세션에서 맥락이 무거워졌을 때 유용해요.
- /init: 프로젝트를 분석해서 CLAUDE.md 초안을 만들어줘요.
- /model: 사용할 모델을 바꿔요.
슬래시 명령 중에는 사용자가 직접 만든 커스텀 명령도 있어요. 반복하는 작업 프롬프트를 저장해두고 명령어 하나로 호출할 수 있어요.
권한 모드와 승인 방식
Claude Code는 파일을 수정하거나 명령을 실행하기 전에 사용자에게 승인을 물어봐요. 처음에는 매번 확인하면서 어떤 작업을 하는지 눈으로 익히는 게 좋아요.
승인 프롬프트가 너무 잦으면 자주 쓰는 안전한 명령을 허용 목록에 넣을 수 있어요. 설정 파일에 허용할 명령을 지정하면 해당 명령은 묻지 않고 실행해요. 읽기 전용 명령부터 허용하는 것을 추천해요.
계획 모드도 유용해요. 코드를 바로 고치지 않고 먼저 어떻게 할지 계획만 세우게 하는 모드라서, 큰 변경 전에 방향을 확인하기 좋아요. 계획이 마음에 들면 그때 실행을 승인해요.
작업을 잘 맡기는 요령
요청은 구체적일수록 결과가 좋아요. “로그인 기능 만들어줘”보다 “이메일과 비밀번호로 로그인하는 API를 추가하고, 기존 사용자 모델을 활용하고, 테스트도 작성해줘”처럼 범위와 조건을 함께 적으세요.
- 작게 나눠 요청: 큰 기능은 단계별로 쪼개서 요청하면 각 단계를 확인하며 진행할 수 있어요.
- 검증 방법 제시: “테스트가 통과할 때까지 수정해줘”처럼 성공 기준을 주면 스스로 확인하며 작업해요.
- 파일 지정: 수정할 파일이나 참고할 파일을 이름으로 알려주면 탐색 시간이 줄어요.
결과가 마음에 들지 않으면 처음부터 다시 쓰기보다 무엇이 잘못됐는지 짧게 알려주고 수정을 요청하세요. 잘못된 방향으로 길어진 세션은 /clear로 정리하고 새로 시작하는 편이 나아요.
마무리
Claude Code를 잘 쓰는 첫걸음은 CLAUDE.md로 규칙을 알려주고, 읽기 요청으로 시작해 작은 단위로 작업을 맡기는 거예요. 권한 모드와 계획 모드를 활용하면 의도하지 않은 수정을 막을 수 있어요. 명령어는 버전에 따라 달라질 수 있으니 /help로 확인하면서 익혀보세요.