Claude Code, 어디까지 알고 쓰고 계신가요? 내부 구조를 한눈에 보여주는 비주얼 가이드

터미널 기반 AI 코딩, 제대로 이해하고 쓰자

요즘 AI 코딩 도구 하면 Cursor, GitHub Copilot 같은 이름이 먼저 떠오르죠. 그런데 Anthropic에서 만든 Claude Code라는 도구가 조금 다른 방향으로 주목받고 있어요. IDE 플러그인이 아니라 터미널에서 직접 돌아가는 에이전트거든요. 코드를 읽고, 수정하고, 테스트까지 알아서 돌려주는 방식이에요.

그런데 이 도구가 내부적으로 어떻게 동작하는지, 어떤 구조로 되어 있는지 제대로 파악하고 쓰는 분은 의외로 많지 않더라고요. 최근 공개된 "Claude Code Unpacked"라는 비주얼 가이드가 이 부분을 아주 깔끔하게 정리해줘서 소개해드리려 해요.

Claude Code는 어떻게 생겨먹었나

Claude Code의 핵심 아이디어는 간단해요. 터미널에서 자연어로 "이 함수 리팩토링해줘", "테스트 깨진 거 고쳐줘"라고 말하면, AI가 프로젝트 구조를 파악하고 직접 파일을 수정하는 거예요. 기존의 코드 자동완성과는 차원이 다른 접근이죠.

이게 뭐냐면, 기존 Copilot 같은 도구는 "커서가 있는 위치에서 다음 줄을 예측"하는 방식이에요. 반면 Claude Code는 프로젝트 전체를 맥락으로 잡고, 여러 파일을 넘나들면서 작업을 수행하는 에이전트 방식이에요. 마치 페어 프로그래밍하는 동료가 터미널 안에 들어와 있는 느낌이랄까요.

비주얼 가이드에서는 이 구조를 다이어그램으로 쪼개서 보여주는데요, 크게 보면 이렇게 동작해요:

1. 사용자 입력: 터미널에서 자연어 명령을 입력
2. 컨텍스트 수집: 프로젝트의 파일 구조, 코드 내용, Git 히스토리 등을 자동으로 읽어들임
3. 도구 호출(Tool Use): 파일 읽기, 편집, Bash 명령 실행, 검색 등의 도구를 AI가 직접 선택해서 사용
4. 반복 루프: 결과를 확인하고, 필요하면 추가 작업을 스스로 판단해서 반복

특히 3번이 핵심인데요, Claude Code는 단순히 텍스트를 생성하는 게 아니라 실제 시스템 도구를 호출하는 권한을 갖고 있어요. 파일을 만들고, 수정하고, 터미널 명령도 실행할 수 있죠. 이걸 Anthropic에서는 "tool use" 패턴이라고 부르는데, 쉽게 말해 AI에게 연장통을 쥐어준 거예요.

권한 모델과 안전장치

"AI가 내 파일을 마음대로 수정한다고?" 하고 불안해지실 수 있는데요, 비주얼 가이드에서 잘 설명해주는 부분이 바로 권한 모델이에요.

Claude Code는 세 가지 권한 모드를 제공해요. 파일 읽기 같은 안전한 작업은 자동 허용하고, 파일 수정이나 셸 명령 같은 위험할 수 있는 작업은 사용자에게 확인을 받는 구조예요. 원하면 특정 명령을 항상 허용하도록 설정할 수도 있고, 반대로 더 엄격하게 잠글 수도 있고요.

또 하나 재밌는 건 CLAUDE.md라는 파일이에요. 이건 프로젝트 루트에 놓는 설정 파일인데, "이 프로젝트에서는 테스트를 pytest로 돌려", "코드 스타일은 이렇게 해줘" 같은 지침을 적어두면 Claude Code가 매번 참고해요. 사람한테 온보딩 문서를 주는 것처럼, AI에게도 프로젝트 컨텍스트를 알려주는 거죠.

기존 AI 코딩 도구와 뭐가 다른가

지금 시장에 있는 AI 코딩 도구들과 비교해보면 위치가 명확해져요.

GitHub Copilot은 IDE 안에서 코드 자동완성에 초점을 맞추고 있어요. 최근에 에이전트 기능(Copilot Workspace 등)을 추가하고 있지만, 기본적으로는 "다음 줄 예측"이 핵심이에요.

Cursor는 IDE 자체를 AI 중심으로 새로 만든 케이스예요. 에디터 안에서 AI와 대화하면서 코드를 수정하는 방식인데, GUI 기반이라 시각적으로 보기 편해요.

Claude Code는 이 둘과 달리 터미널 네이티브예요. GUI가 없어요. 대신 기존 워크플로우에 자연스럽게 녹아들 수 있다는 장점이 있어요. vim을 쓰든, VSCode를 쓰든, 터미널만 열려 있으면 바로 쓸 수 있거든요. CI/CD 파이프라인에 넣거나, Git hook과 연동하는 것도 자연스러워요.

최근에는 Claude Code를 VSCode 확장이나 JetBrains 플러그인으로도 쓸 수 있게 됐고, 웹 앱(claude.ai/code)으로도 접근할 수 있어서 진입 장벽이 많이 낮아졌어요.

실무에서 어떻게 활용할 수 있을까

한국 개발자 입장에서 Claude Code가 특히 유용한 시나리오를 몇 가지 생각해보면요:

레거시 코드 파악할 때 — 새 프로젝트에 투입됐는데 문서가 부실할 때, "이 모듈이 뭐 하는 건지 설명해줘"라고 물어보면 코드를 읽고 구조를 설명해줘요. 주니어 개발자한테 특히 유용하겠죠.

반복 작업 자동화 — "모든 API 엔드포인트에 로깅 미들웨어 추가해줘" 같은 기계적이지만 손이 많이 가는 작업을 맡길 수 있어요.

코드 리뷰 보조 — PR 올리기 전에 "이 변경사항 리뷰해줘"라고 하면 잠재적인 버그나 개선점을 짚어줘요.

다만 주의할 점도 있어요. Claude Code가 실행하는 모든 명령은 결국 내 로컬 환경에서 돌아가는 거라, 프로덕션 서버에서 무분별하게 쓰면 위험할 수 있어요. 비주얼 가이드에서도 "되돌리기 어려운 작업은 반드시 확인을 거치라"고 강조하고 있고요.

비주얼 가이드가 알려주는 것

이번에 공개된 비주얼 가이드의 가장 큰 가치는, 이런 내부 동작 원리를 다이어그램과 플로우차트로 깔끔하게 정리해줬다는 거예요. 공식 문서만 읽으면 "그래서 어떻게 돌아가는 건데?"라는 의문이 남기 쉬운데, 이 가이드는 각 단계를 시각적으로 보여주니까 전체 그림이 한눈에 들어와요.

특히 도구 호출 흐름, 권한 체계, 컨텍스트 윈도우 관리 방식 같은 부분은 Claude Code를 효율적으로 쓰려면 반드시 이해해야 하는 내용이에요. 도구를 잘 쓰려면 도구가 어떻게 작동하는지 알아야 하는 건 당연한 이치잖아요.