AI 코딩 도구 대부분은 에디터 안에서 동작한다.
Claude Code는 터미널에서 실행되고, 채팅으로 답변만 주는 게 아니라 프로젝트의 파일을 직접 읽고 수정하며 빌드 같은 명령어까지 실행한다.
1. Claude Code란 무엇인가?
Claude Code는 Anthropic이 만든 터미널 기반 코딩 에이전트다.
프로젝트 디렉토리 안에서 실행되며, 자연어 요청을 받아 파일 수정과 명령어 실행까지 직접 수행한다.
| 구분 | 일반 AI 채팅 | Claude Code |
|---|---|---|
| 동작 위치 | 웹/앱 | 터미널 |
| 파일 접근 | X | O |
| 코드 수정 | 복사-붙여넣기 | 직접 수정 |
| 명령어 실행 | X | O (빌드·테스트) |
웹 채팅과의 차이는 코드를 복사해 붙여넣는 왕복이 없다는 점이다.
수정 대상을 에이전트가 직접 찾고, 고치고, 검증 명령으로 확인하는 데까지 한 세션 안에서 끝난다.
2. 설치 및 시작
설치는 npm 전역 설치가 기본이다.
Node.js 없이 쓰는 네이티브 설치 스크립트도 함께 제공된다.
# npm
npm install -g @anthropic-ai/claude-code
# macOS / Linux 네이티브 설치
curl -fsSL https://claude.ai/install.sh | bash프로젝트 디렉토리로 이동해 claude를 실행하면 대화형 세션이 시작된다.
첫 실행 시 Anthropic 계정 인증을 거친다.
cd my-project
claude3. 기본 사용법
세션 안에서는 자연어로 요청한다.
프로젝트 구조 설명 같은 탐색 요청부터 특정 함수 리팩토링 같은 수정 요청까지 형식 제약은 없다.
파일을 수정하거나 명령어를 실행하기 전에는 기본적으로 승인을 요구한다.
어떤 파일을 어떻게 바꾸는지 diff로 보여주고, 수락해야 적용된다.
처음에는 이 승인 단계가 번거로웠는데, 지금은 에이전트가 무엇을 하려는지 따라가는 창구로 쓰고 있다.
세션이 시작되면 프로젝트 루트의 CLAUDE.md 파일을 자동으로 읽는다.
프로젝트 개요, 빌드 명령어, 지켜야 할 규칙을 여기에 적어두면 매 세션 반복 설명이 필요 없다.
이 문서를 잘 관리할수록 매 세션에 반복해 설명할 일이 줄어든다.
4. 실제로 맡기는 작업
4.1 규칙 문서 운용
이 블로그 저장소가 좋은 예시다.
글의 줄바꿈 규칙, Mermaid 코드 펜스 사용법, 강조색 제한 같은 프로젝트 고유 규칙이 많은데, 요청할 때마다 프롬프트로 설명하기엔 양이 많다.
문서화하기 전에는 매번 규칙을 다시 알려줘야 했고, 빼먹으면 결과물이 어긋났다.
지금은 저장소 루트의 CLAUDE.md에 개요와 주의사항을 두고, 글 작성 가이드 같은 상세 규칙은 별도 워크플로우 문서로 분리해 CLAUDE.md에서 가리키게 했다.
에이전트가 규칙을 어긴 지점이 발견되면 그 자리에서 해당 문서에 한 줄을 추가한다.
프롬프트는 세션이 끝나면 사라지지만 문서는 다음 세션에도 남기 때문에, 같은 지적을 반복하는 일이 눈에 띄게 줄었다.
4.2 리팩토링과 빌드 에러 수정
코드 작업은 범위가 명확한 것부터 맡긴다.
deprecated API를 새 버전으로 교체하는 식의 기계적인 멀티파일 수정은 사람이 하면 지루하고 누락이 생기기 쉬운데, 에이전트에게 잘 맞는다.
프로젝트를 스캔해 대상을 찾고, 여러 파일을 고치고, 바뀐 내용을 요약해준다.
빌드 에러 수정은 루프를 돈다는 점이 좋다.
빌드를 실행하고, 에러 메시지를 읽고, 파일을 고친 뒤 다시 빌드해서 통과할 때까지 반복한다.
사람이 하던 수정-빌드-확인 반복을 에이전트가 대신하므로, 타입 에러가 연쇄적으로 발생하는 리팩토링 뒤처리 시간을 줄여준다.
5. 한계
가장 자주 부딪히는 한계는 도메인 지식이다.
매칭이나 정산처럼 비즈니스 규칙이 코드 바깥의 기획 문서나 팀의 암묵지에 있는 로직은 일반적인 패턴으로 수렴하려는 경향이 있다.
도메인 맥락을 주석이나 규칙 문서로 제공하면 정확도가 올라가지만, 문서화되지 않은 암묵지는 결국 검토 단계에서 사람이 잡아야 한다.
컨텍스트 크기 제한이나 최신 라이브러리 지식 같은 공통 한계는 AI 코딩 도구 비교 글에서 다뤘다.
6. 검증 워크플로우
요청은 작게, 구체적으로 쪼갠다.
프로젝트 전체 리팩토링 같은 요청은 결과 diff가 너무 커서 검토가 불가능하고, 특정 함수에 에러 핸들링을 추가하는 수준이면 변경을 눈으로 따라갈 수 있다.
작업 전에 git checkout -b로 브랜치를 만들고, 작업 후에는 git diff로 변경을 확인한 뒤 테스트와 빌드를 직접 돌린다.
커밋할 때는 git add -p로 선택적으로 스테이징하면 의도하지 않은 수정을 걸러낼 수 있다.
에이전트가 수정했더라도 커밋하는 사람은 나다.
검증을 건너뛴 수정은 리뷰나 장애 대응에서 더 큰 비용으로 돌아온다.
마무리
Claude Code는 범위가 명확한 수정과 반복 작업에 활용하기 좋다.
요령을 하나만 꼽자면, 프롬프트를 다듬는 것보다 CLAUDE.md와 규칙 문서를 다듬는 쪽이 오래 남는다.
도구가 바뀌어도 프로젝트의 규칙 문서는 자산으로 남기 때문이다.