Claude Code

Claude Code는 Anthropic이 만든 에이전트형 코딩 도구로, 저장소를 읽고 파일을 고치며 명령을 실행하는 여러 단계의 개발 작업을 대화로 처리합니다. 터미널과 데스크톱 앱, IDE 확장, 웹, 자동화 환경에서 같은 작업 흐름을 제공합니다.

저장소에서 어떻게 작업하는가

Claude Code는 현재 파일에 코드 한 줄을 제안하는 자동 완성 도구보다 넓은 범위를 다룹니다. 사용자가 “로그인 뒤 원래 페이지로 돌아오지 않는 문제를 찾아 고쳐 줘”라고 요청하면 관련 파일을 검색하고, 인증 흐름과 테스트를 읽고, 수정안을 적용한 뒤 필요한 명령으로 결과를 확인할 수 있습니다. 각 단계에서 새로 얻은 정보를 다음 판단에 사용하는 에이전트 작업 방식입니다.

작동 방식 공식 문서는 Claude Code가 프로젝트 파일, 터미널, Git 상태, CLAUDE.md, 자동 메모리와 사용자가 구성한 확장 기능에 접근한다고 설명합니다. 접근 범위는 실행 환경과 권한 설정에 따라 달라집니다. 로컬 세션은 사용자의 컴퓨터에서 실행되고, 클라우드 세션은 격리된 원격 환경에서 저장소를 받아 작업하며, 원격 제어는 브라우저 화면으로 로컬 세션을 다룹니다.

Claude Code를 CLI로만 설명하면 현재 사용 표면을 놓치게 됩니다. 터미널의 claude 명령 외에도 데스크톱 앱, VS Code와 JetBrains 확장, claude.ai/code, Slack, CI/CD 파이프라인에서 시작할 수 있습니다. 웹 사용 문서에 따르면 웹의 클라우드 세션은 별도 환경에서 계속 실행되고, 사용자는 브라우저나 모바일 앱에서 진행 상황을 확인하고 방향을 바꿀 수 있습니다. 다만 로컬에만 있는 파일과 설정은 자동으로 클라우드 세션에 전달되지 않습니다.

권한과 프로젝트 지침은 어떻게 작동하는가

Claude Code가 파일과 명령을 다루는 범위는 권한 설정이 제한합니다. 권한 설정 문서는 도구, 파일 경로와 도메인에 allow, ask, deny 규칙을 적용할 수 있다고 설명합니다. 읽기는 허용하되 배포 명령은 매번 묻게 하거나, 비밀 파일은 읽지 못하게 막는 식입니다. 운영체제 수준의 샌드박스는 터미널 명령의 파일·네트워크 접근을 제한하는 별도 층입니다.

CLAUDE.md에는 프로젝트에서 항상 따라야 할 규칙과 문맥을 적습니다. 예를 들어 “패키지를 추가하지 말 것”, “수정 뒤 이 명령으로 타입 검사를 실행할 것”, “공개 API 이름은 바꾸지 말 것” 같은 지침을 저장소와 함께 관리할 수 있습니다. Claude Code는 세션마다 이 파일을 읽으므로 반복 설명을 줄일 수 있지만, 문서에 금지 사항을 적었다는 사실만으로 강제 보안 경계가 생기지는 않습니다. 중요한 제한은 권한 규칙, 샌드박스, 저장소 보호 설정으로 함께 집행해야 합니다.

로컬, 웹, 데스크톱은 같은 지침을 읽을 수 있어도 실제로 보이는 파일이 다를 수 있습니다. 클라우드 세션은 보통 원격 저장소의 커밋된 상태에서 시작하므로 로컬의 미추적 파일이나 사용자 전용 설정이 빠질 수 있습니다. 반대로 로컬 세션은 현재 작업 트리의 커밋하지 않은 변경까지 봅니다. 같은 요청을 다른 환경에서 실행할 때는 기준 브랜치, 필요한 설정과 비밀 정보의 전달 범위를 먼저 확인해야 합니다.

MCP, Skills, 서브에이전트는 무엇이 다른가

Claude Code의 확장 기능은 역할이 서로 다릅니다. 확장 기능 개요는 CLAUDE.md를 매 세션 읽는 상시 문맥, Skills를 필요할 때 불러오는 지식과 작업 절차, MCP를 외부 서비스와 도구의 연결, 서브에이전트를 별도 문맥에서 수행하는 위임 작업으로 구분합니다. 각 기능은 필요한 곳에서 함께 사용할 수 있습니다.

예를 들어 데이터베이스 배포를 자동화한다고 가정해 보겠습니다. CLAUDE.md에는 운영 데이터베이스를 직접 수정하지 않는 팀 규칙을 둡니다. Skill에는 마이그레이션 점검 순서와 되돌리기 절차를 적습니다. MCP 서버는 실제 데이터베이스 상태를 조회하는 도구를 제공하고, 서브에이전트는 애플리케이션 코드와 마이그레이션 파일을 분리해 검토할 수 있습니다. 권한 규칙은 조회와 변경 도구 중 무엇을 허용할지 결정합니다.

Skills와 서브에이전트도 자주 헷갈립니다. Skill은 현재 대화에 절차나 참고 지식을 불러올 수 있고, 설정에 따라 별도 문맥에서 실행될 수도 있습니다. 서브에이전트는 자기 지침과 도구, 독립된 컨텍스트를 가지고 작업한 뒤 주 세션에 요약을 돌려줍니다. MCP는 Claude Code가 외부 기능을 호출하는 통로이고, 판단은 Claude Code가 합니다. 복잡한 작업을 나눌 때는 정보가 필요한지, 외부 연결이 필요한지, 별도 작업 문맥이 필요한지를 먼저 구분해야 합니다.

도입 초기에는 저장소를 설명해 달라는 읽기 작업부터 시작하고, 변경 diff와 명령 결과를 직접 검토하는 편이 좋습니다. 반복 규칙은 CLAUDE.md에, 긴 절차는 Skill에 옮기고, 외부 시스템이 필요할 때 MCP를 추가합니다. 서브에이전트는 조사 범위가 크거나 서로 독립된 검토가 있을 때 사용합니다. 도구 수를 늘리는 것보다 각 확장의 책임과 권한을 좁게 정하는 일이 안정적인 코드 작업에 더 중요합니다.