[Claude Code] 터미널에서 직접 코드를 수정하는 AI 에이전트 활용법

Claude Code는 터미널에서 실행되는 AI 에이전트다. 채팅만 하는 게 아니라, 직접 파일을 읽고, 수정하고, 명령어를 실행한다.

1. Claude Code란?

일반적인 AI 채팅과 다른 점:

핵심: Claude Code는 내 프로젝트 디렉토리에서 실행되며, 파일을 읽고 직접 수정할 수 있다.

2. 설치 및 시작

# 설치 (npm)
npm install -g @anthropic-ai/claude-code
 
# 또는 직접 다운로드
# https://claude.ai/code
 
# 프로젝트 디렉토리에서 실행
cd my-project
claude

첫 실행 시 Anthropic 계정 연동이 필요하다.

3. 기본 사용법

터미널에서 claude를 실행하면 대화형 모드가 시작된다:

$ claude
 
Claude Code v1.x.x
Type your request...
 
> 이 프로젝트 구조 설명해줘
 
Analyzing project structure...
[파일 목록과 설명 출력]
 
> src/utils.ts 파일의 함수들 리팩토링해줘
 
Reading src/utils.ts...
[파일 수정 제안 및 적용]

자주 쓰는 명령:

• 파일 설명 요청
• 코드 리팩토링
• 테스트 코드 작성
• 버그 수정
• 문서화

4. 잘 되는 것들

4.1 멀티파일 리팩토링

> 이 프로젝트에서 deprecated된 API 찾아서 새 버전으로 교체해줘

Claude Code가 알아서:

1. 프로젝트 전체 스캔
2. 해당 패턴 찾기
3. 여러 파일 동시 수정
4. 수정 내용 요약

4.2 테스트 코드 생성

> src/services/UserService.ts에 대한 단위 테스트 작성해줘

• 파일을 읽고 함수 분석
• 테스트 파일 생성
• edge case 포함

4.3 빌드 에러 수정

> npm run build 실행하고 에러 수정해줘

• 빌드 명령어 실행
• 에러 메시지 분석
• 관련 파일 수정
• 다시 빌드해서 확인

5. 한계점

5.1 컨텍스트 크기

프로젝트가 너무 크면 전체를 파악하기 어렵다.

# 컨텍스트 초과 시
> 이 프로젝트 전체 리팩토링해줘
 
"Context too large, please narrow down the scope"

해결: 범위를 좁혀서 요청

> src/api/users 폴더만 리팩토링해줘

5.2 도메인 지식

비즈니스 로직이나 도메인 특화 코드는 정확도가 떨어진다.

# 게임 서버 특화 로직
> 매칭 알고리즘 최적화해줘
 
# AI가 일반적인 패턴만 알고 있음

해결: 충분한 컨텍스트 제공 (주석, 문서)

5.3 최신 라이브러리

학습 데이터 기준일 이후의 API는 모를 수 있다.

> Next.js 15의 새 기능 적용해줘
 
# 최신 API를 모를 수 있음

해결: 공식 문서 링크 제공 또는 예시 코드 첨부

6. 효과적으로 쓰는 팁

6.1 작은 단위로 요청

# 너무 큰 요청
> 이 프로젝트 전체 리팩토링해줘
 
# 작은 단위
> UserService의 createUser 함수만 리팩토링해줘

6.2 구체적으로 요청

# 모호한 요청
> 코드 개선해줘
 
# 구체적인 요청
> 이 함수에서 에러 핸들링 추가하고, 타입을 더 엄격하게 수정해줘

6.3 검증은 직접

# Claude Code가 수정한 후
> npm run test  # 테스트 실행
> npm run build # 빌드 확인

AI가 수정한 코드는 반드시 검증

6.4 Git 활용

# 작업 전 브랜치 생성
git checkout -b refactor/user-service
 
# Claude Code 작업 후
git diff  # 변경사항 확인
git add -p  # 선택적 스테이징

7. 실제 워크플로우

나는 이렇게 사용한다:

1. 새 브랜치 생성
   git checkout -b feature/xxx

2. Claude Code 실행
   claude

3. 요청 및 수정
   > [구체적인 요청]

4. 변경사항 확인
   git diff

5. 테스트 실행
   npm run test

6. 커밋
   git commit -m "..."

핵심: AI가 수정하더라도 최종 책임은 개발자에게 있다.

마무리

Claude Code는 터미널 기반 AI 에이전트다. 복잡한 리팩토링이나 멀티파일 수정에 적합하다.

잘 쓰려면:

• 작은 단위로, 구체적으로 요청
• 검증은 직접 수행
• Git으로 변경사항 관리