Claude Code: 터미널 기반 코딩 에이전트

우리는 지난 몇 년간 소프트웨어 개발 방식에 혁명적인 변화를 가져온 AI 도구들을 경험했습니다. 초기에는 ChatGPT가 생성해주는 코드를 IDE로 복붙하다가, 깃허브 Copilot이나 Cursor와 같은 도구들이 코딩을 도와주는 시대를 지나 이제 새로운 패러다임이 등장하고 있습니다. 바로 Anthropic이 선보인 CLI(명령줄 인터페이스) 기반의 AI 코딩 도구, Claude Code입니다.

단순한 코드 완성이 아닌, 작업 위임의 시대

Claude Code는 단순히 코드를 완성해주거나 코드를 생성하는 도구를 넘어섭니다. 이 도구의 핵심에는 사용자의 고차원적인 지시를 이해하고 목표 달성을 위해 필요한 여러 단계를 자율적으로 계획하고 실행하는 코딩 에이전트(Agent) 시스템이 자리 잡고 있습니다.

이는 기존의 그래픽 인터페이스(GUI) 편집기 기반의 GitHub Copilot이나 Cursor와 같은 도구들과 근본적으로 다른 철학입니다. 예를 들어, 깃허브 Copilot이 우리가 코드를 작성하는 과정을 보조하며 타이핑 속도를 높여주는 동승자 역할을 한다면, Claude Code는 전체 작업을 위임받아 수행하는 개발 파트너에 더 가깝습니다.

이러한 에이전트적 특성은 실제 작업에서 명확히 드러납니다. Claude Code에게 깃허브 이슈 101번을 수정해줘라고 명령하면, Claude Code 단순히 코드 한 줄을 제안하는 것에 그치지 않습니다.

이슈 세부 사항을 파악하고, 관련 코드베이스를 탐색하며, 필요한 변경사항을 구현하고, 심지어 커밋 및 풀 리퀘스트를 생성하는 복잡한 과정을 스스로 처리할 수 있습니다. 개발자는 모든 단계를 세부적으로 지시하는 대신, 고차원적인 목표에 집중하고 Claude에게 실행 부담을 위임할 수 있게 됩니다.

CLI 기반의 터미널이 핵심 인터페이스인 이유

Claude Code가 VS Code와 같은 전통적인 IDE에 플러그인 형태로 통합되면서도 터미널 기반의 CLI를 중심으로 작동하는 것은 단순한 디자인 결정이 아닙니다. 복잡한 작업을 자율적으로 수행하는 AI에게는 사용자의 명확한 명령을 받고, 작업 수행 중 필요한 권한을 요청하며, 진행 상황을 보고하는 구조가 필수적입니다. 터미널은 이러한 ‘명령-수행-보고’ 사이클에 최적화된 인터페이스입니다.

또한, 터미널 환경은 Claude가 bash와 같은 외부 시스템 도구들과 자연스럽게 통합하여 파일 시스템을 탐색하고, 쉘 명령어를 실행하며, Git과 상호 작용하는 것을 가능하게 합니다. 이러한 터미널 중심의 접근 방식은 Claude Code가 고차원적인 요구 사항을 처리하고 전체 개발 워크플로우를 자율적으로 실행할 수 있도록 하는 전략적 기반이 됩니다.

시작하기: 설치와 기본 사용법

Claude Code는 npm을 통해 간단히 설치할 수 있습니다:

$ npm install -g @anthropic-ai/claude-code

설치가 완료되면, Claude Code는 터미널에서 claude 명령을 실행하는 것만으로 사용할 수 있습니다. 특히 VS Code의 통합 터미널에서 실행하면 확장 프로그램이 자동으로 설치되어 IDE 내에서 파일 참조나 진단 오류를 자동으로 공유하는 등 에이전트 기능을 극대화할 수 있습니다.

Claude Code는 두 가지 방식으로 명령을 받습니다.

• 자연어 명령: “package.json에 새로운 의존성을 추가해줘” 또는 “이 함수에서 성능 병목이 있는지 확인해줘”와 같이 복잡한 요청을 자연어로 전달할 수 있습니다.
• 슬래시 명령어: /를 입력하여 사용하는 정형화된 명령어입니다. 세션 관리, 설정 변경, 특정 워크플로우 처리를 위해 사용됩니다.

특히 Esc 키를 사용하여 작업을 중단하는 기능은 Claude Code가 단순히 명령어 라인을 실행하는 것이 아니라, 고유한 ‘에이전트 작업’을 수행하고 있음을 보여줍니다.

프로젝트 컨텍스트 관리: CLAUDE.md의 힘

대규모 언어 모델을 개발에 활용할 때 가장 어려운 점 중 하나는 프로젝트의 전체적인 맥락을 유지하는 것입니다. Claude Code는 이 문제를 해결하기 위해 CLAUDE.md라는 특별한 파일을 도입했습니다. 이 파일은 Claude가 세션을 시작할 때 자동으로 컨텍스트에 가져오는 ‘프로젝트 메모리’ 역할을 합니다.

CLAUDE.md 파일에는 다음과 같은 정보를 문서화할 수 있습니다.

• 프로젝트의 핵심 파일 경로
• 코드 스타일 가이드라인
• 테스트 지침
• 개발 환경 설정 및 특이사항
• 자주 사용하는 쉘 스크립트

/init 명령을 실행하면 Claude가 프로젝트 구조를 기반으로 이 파일을 자동으로 생성해줍니다. 이 파일을 활용하면 Claude는 매번 동일한 정보를 반복 학습할 필요 없이 프로젝트의 맥락을 즉시 파악하고, 일관된 코딩 스타일을 유지하며, 정확한 지침을 따를 수 있습니다. 이는 Claude가 단순히 일회성 작업을 처리하는 도구가 아니라, 장기적인 프로젝트에 대한 ‘기억’을 구축하고 유지할 수 있는 진정한 에이전트임을 보여줍니다.

인간과 AI의 협업: 에이전트 기반 워크플로우

Claude Code는 사용자의 작업 스타일에 맞춰 세 가지 워크플로우 모드를 제공합니다. Shift+Tab으로 쉽게 전환할 수 있습니다.

• 기본 모드: 모든 파일 수정에 대해 사용자에게 명시적인 승인을 요청합니다. 신중한 작업이나 Claude Code를 처음 사용할 때 적합합니다.
• 자동 승인 모드 (auto): Claude가 파일을 자동으로 수정합니다. 반복적이거나 신뢰도가 높은 작업에 유용합니다.
• 계획 모드 (plan): 코드를 작성하기 전에 먼저 상세한 계획을 제안합니다. 복잡한 작업이나 새로운 시스템 설계 단계에서 AI와 함께 설계를 검토할 때 유용합니다.

이러한 모드들은 인간 개발자의 사고 과정과 유사한 “탐색-계획-코딩-커밋” 워크플로우를 구축하는 데 필수적입니다. 이 워크플로우는 다음과 같이 진행됩니다.

• 탐색 (Explore): Claude에게 CLAUDE.md나 관련 파일 등을 읽게 하여 문제의 전체적인 맥락을 파악합니다.
• 계획 (Plan): 계획 모드를 활성화하거나 프롬프트에 “생각해”라는 단어를 사용하여 Claude가 문제 해결에 대한 심층적인 계획을 수립하게 합니다.
• 코딩 (Code): 계획이 승인되면 Claude가 실제로 솔루션을 코드로 구현하고, 필요한 쉘 명령어나 편집 작업을 스스로 수행합니다.
• 커밋 (Commit): 작업이 완료되면 Claude에게 결과물을 커밋하고 풀 리퀘스트를 생성하도록 요청하여 작업을 마무리합니다.

이러한 단계별 접근 방식은 AI가 복잡한 문제 해결 과정을 투명하게 보여주어 개발자가 AI의 추론 과정을 이해하고 협력할 수 있게 합니다. 특히 Esc를 두 번 눌러 대화를 분기하는 기능은 AI가 제시한 계획이 잘못되었을 경우 사용자가 신속하게 개입하여 방향을 수정할 수 있게 합니다.

협업과 자동화: 다중 Claude 워크플로우 및 GitHub 통합

Claude Code는 단일 사용자의 생산성 향상을 넘어, 팀 단위의 복잡한 협업 워크플로우까지 지원합니다. Anthropic의 엔지니어들은 종종 여러 git 체크아웃을 별도의 폴더에 생성하고, 각 폴더에서 다른 Claude 인스턴스를 시작하여 작업을 분담한다고 합니다. 예를 들어, 한 Claude는 코드를 작성하게 하고, 다른 Claude는 해당 코드를 검토하거나 테스트하게 할 수 있습니다. 이는 마치 여러 명의 엔지니어가 각기 다른 역할을 수행하는 것과 유사한 협업 환경을 구축하는 것입니다.

또한, Claude는 gh CLI(GitHub 명령줄 도구)와의 통합을 통해 GitHub 이슈를 확인하고, 풀 리퀘스트를 생성하며, 댓글을 읽는 등의 작업을 수행할 수 있습니다. 이러한 기능은 Claude를 단순한 코딩 보조 도구에서 CI/CD(지속적 통합/지속적 배포) 파이프라인의 일부로 활용할 수 있는 잠재력을 제공합니다. ‘헤드리스 모드’를 사용하면 GitHub 이벤트에 의해 트리거되는 자동화 작업(예: 코드 린팅)을 설정할 수 있어, 반복적인 인프라 작업을 자동화하는 데 Claude를 활용할 수 있습니다.

문제 해결 및 디버깅을 위한 심층 분석

Claude Code는 코드 생성뿐만 아니라, 복잡한 문제 해결과 디버깅에 있어서도 뛰어난 추론 능력을 보여줍니다. IDE와의 통합 덕분에 린트, 구문 오류 등 진단 오류가 작업하는 동안 자동으로 Claude와 공유되어 즉각적인 피드백을 받을 수 있습니다.

복잡한 버그나 오류를 해결할 때는 Claude의 추론 능력을 극대화할 수 있는 전략을 활용하는 것이 효과적입니다. 오류 로그 전문을 Claude에 직접 붙여넣거나, 스크린샷이나 이미지 파일 경로를 제공하여 시각적 정보를 함께 전달할 수 있습니다. Claude는 표나 다이어그램을 포함한 다양한 시각적 정보를 처리하는 데 강점을 가지고 있기 때문에, 복잡한 다이어그램을 포함한 오류 보고서를 분석하는 데 특히 유용합니다.

많은 수의 린트 이슈를 수정하는 것과 같은 반복적인 디버깅 작업은 Claude에게 위임할 수 있습니다. Claude에게 린트 명령어를 실행하고, 모든 결과 오류를 파일 이름과 라인 번호가 포함된 마크다운 체크리스트로 작성하도록 지시한 후, 각 이슈를 하나씩 해결하도록 요청하면 작업 진행 상황을 투명하게 관리할 수 있습니다.

마치면서

터미널에서 직접 Opus, Sonnet, Haiku와 같은 Claude 모델과 협업하며 코딩 작업을 진행할 수 있는 Claude Code는 숙련된 페어 프로그래밍 파트너처럼, 개발자의 역량을 증강시키는 역할을 합니다. 소프트웨어 개발의 미래는 인간과 AI가 협력하는 방향으로 나아가고 있으며, Claude Code는 개발 워크플로우의 패러다임을 전환시키고 있습니다. Claude Code를 현명하게 활용한다면, 지루한 단순 코딩 작업에서 벗어나 더 창의적이고 고차원적인 문제 해결에 집중할 수 있을 것입니다.