Claude Code 에이전트 사용 방법: 설정, 도구, 권한 및 샌드박스 워크플로

Claude Code 에이전트를 잘 사용하려면 Claude Code를 채팅 창이 아닌 에이전트 루프로 취급하세요. 변경하려는 리포지토리 내에서 시작하고, 명확한 프로젝트 지침을 제공하며, 실제로 필요한 도구만 연결하고, 권한을 엄격하게 유지하며, 워크플로가 위험이 낮은 로컬 편집을 넘어설 때는 격리된 런타임에서 실행을 수행하세요. 이것이 유용한 코딩 세션과 비용이 많이 들고 복잡한 세션의 차이입니다.

주요 질문이 Claude Code 자체보다 더 광범위하다면 아키텍처 관점을 위해 코딩 에이전트란 무엇인가요?부터 시작하세요. 먼저 도구를 결정하는 중이라면 Claude Code vs Cursor를 비교하세요. 이 가이드는 더 좁은 범위를 다룹니다. 실제로 Claude Code 에이전트를 사용하는 방법입니다.

사람들이 일반적으로 "Claude Code 에이전트"라고 부르는 것

대부분의 개발자가 "Claude Code 에이전트"를 검색할 때는 다음 두 가지 중 하나를 의미합니다.

1. Claude Code 자체가 자율적인 코딩 에이전트로 작동하는 것.
2. 여러 전문화된 에이전트, 도구 또는 서브에이전트가 Claude Code 워크플로 내에서 작동하는 것.

둘 다 유효합니다. Claude Code는 이미 에이전트형 코딩 도구처럼 동작합니다. 리포지토리를 검사하고, 파일을 편집하고, 명령을 실행하며, 결과에 반응할 수 있습니다. Anthropic은 또한 MCP 도구 통합, 훅, 서브에이전트와 같은 관련 구성 요소를 문서화하므로, 이 용어가 종종 복수형으로 나타나는 이유입니다.

실용적인 모델은 간단합니다.

• Claude Code 는 호스트 워크플로입니다.
• 모델 은 계획 및 다음 단계 결정을 처리합니다.
• 도구 는 파일 액세스, 명령, 브라우저, API 및 외부 시스템을 제공합니다.
• 권한 은 Claude가 묻지 않고 수행할 수 있는 작업을 결정합니다.
• 샌드박스 는 코드 및 도구 실행을 위한 안전한 장소를 제공합니다.

이 다섯 가지 계층을 분리하면 Claude Code를 훨씬 더 안정적으로 운영할 수 있습니다.

1단계: Claude Code 설치 및 올바른 디렉터리에서 시작

Anthropic은 Claude Code를 설치 가능한 CLI로 문서화합니다. 표준 설치 경로는 다음과 같습니다.

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

중요한 세부 사항은 설치만이 아닙니다. 작업하려는 리포지토리에서 Claude Code를 시작하세요. Claude Code는 현재 디렉터리, 로컬 프로젝트 지침 및 프로젝트 범위의 도구 구성을 읽습니다.

리포지토리가 새 것이라면 다음을 실행하세요.

/init

그러면 프로젝트별 지침을 위한 시작 CLAUDE.md 파일이 생성됩니다. Claude가 모든 세션에서 기억해야 할 사항(선호하는 테스트 명령, 코딩 표준, 아키텍처 경계, 리뷰 기대 사항, 신중하게 다루어야 할 파일)을 위해 사용하세요.

이것은 대부분의 사용자가 예상하는 것보다 더 중요합니다. 리포지토리별 지침이 없는 Claude Code 에이전트는 일반적으로 성능이 부족한 것이 아니라 지정이 부족 한 것입니다.

2단계: 에이전트가 실제로 실행할 수 있는 작업 제공

Claude Code는 작업에 구체적인 결과물과 검증 단계가 포함될 때 가장 잘 작동합니다.

좋은 예:

• “/login에 속도 제한을 추가하고, 테스트를 업데이트하고, 영향을 받는 테스트 파일을 실행하세요.”
• “청구 서비스를 새 클라이언트로 리팩터링한 다음 해당 패키지의 단위 테스트를 실행하세요.”
• “보안 및 정확성 문제에 대해 이 PR diff를 검토하세요.”

약한 프롬프트는 일반적으로 정확히 잘못된 방식으로 모호합니다.

• “이 코드를 개선하세요.”
• “앱을 더 좋게 만드세요.”
• “프로젝트를 확인하세요.”

에이전트형 코딩 도구는 완료 지점이 명시적일 때 더 잘 작동합니다. 자율성을 원한다면 성공을 정의하세요. 탐색을 원한다면 범위를 정의하세요.

3단계: 필요한 도구만 구성

Claude Code는 외부 도구를 위해 MCP(Model Context Protocol)를 사용합니다. 실제로 MCP 서버는 브라우저, 데이터베이스, 이슈 트래커, GitHub, 코드 러너 및 내부 서비스를 위한 확장 표면입니다.

가장 일반적인 설정 명령은 다음과 같습니다.

claude mcp add playwright -- npx -y @playwright/mcp@latest

그러면 Claude에 브라우저 자동화 도구가 제공됩니다. Anthropic의 MCP 문서 및 빠른 시작 가이드는 다른 서버에도 동일한 패턴을 다룹니다.

핵심 운영 규칙은 절제 입니다. 언젠가 필요할 수도 있는 모든 도구를 첨부하지 마세요. 작업에 맞는 가장 작은 도구 세트를 첨부하세요. 너무 많은 도구는 시작 노이즈를 증가시키고, 작업 표면을 넓히며, 도구 선택을 덜 예측 가능하게 만듭니다.

대부분의 리포지토리 작업에서 적절한 시작 세트는 다음과 같습니다.

• 로컬 파일 및 셸 액세스
• 웹 QA가 필요한 경우 하나의 브라우저 도구
• 작업이 외부 시스템에 의존하는 경우 하나의 이슈 또는 문서 도구

그 외의 모든 것은 그 자리를 증명해야 합니다.

4단계: 권한을 나중 생각이 아닌 의도적으로 사용

안전한 Claude Code 워크플로와 무모한 워크플로의 가장 큰 차이점 중 하나는 권한 규율입니다.

Claude Code는 도구 실행이 실제 위험 경계이기 때문에 권한 제어를 노출합니다. 파일을 읽는 것과 설치 스크립트를 실행하거나, 디렉터리를 삭제하거나, 외부 서비스에 액세스하는 것은 다릅니다.

세션이 다음을 수행할 수 있는 경우 특히 프로젝트 초기에 /permissions를 사용하세요.

• 많은 파일에 쓰기
• 셸 명령 실행
• 패키지 설치
• 비밀 또는 내부 시스템 액세스
• 부작용이 있는 MCP 도구 호출

올바른 설정은 작업에 따라 다릅니다.

• 탐색적 디버깅의 경우 일반적으로 실행 전에 묻는 것이 더 안전한 기본값입니다.
• 반복적이고 범위가 잘 정의된 리포지토리 작업의 경우 허용 규칙이 중단을 줄일 수 있습니다.
• 위험도가 높은 명령이나 민감한 경로의 경우 거부 규칙을 명시적으로 유지해야 합니다.

이것은 많은 팀이 잘못된 최적화를 하는 지점이기도 합니다. 권한을 너무 넓게 열어 마찰을 줄인 다음 프롬프트 문구만으로 제어를 회복하려고 합니다. 이는 잘못된 접근 방식입니다. 프롬프트는 지침입니다. 권한은 강제 수단 입니다.

5단계: 실제 에이전트 루프 이해

Claude Code는 내부에서 무슨 일이 일어나고 있는지 이해하면 강력하게 느껴집니다.

루프는 일반적으로 다음과 같습니다.

1. Claude가 작업 및 프로젝트 컨텍스트를 읽습니다.
2. 다음 유용한 단계를 계획합니다.
3. 파일을 읽거나 도구를 호출합니다.
4. 코드를 편집하거나 명령을 실행합니다.
5. 출력을 확인합니다.
6. 발생한 상황에 따라 계획을 수정합니다.
7. 요청된 결과가 완료되면 중지됩니다.

이 루프는 에이전트 워크플로가 일반적인 챗봇 사용과 다른 이유를 설명합니다. 모델은 코드를 생성할 뿐만 아니라 도구, 파일, 명령 출력 및 중간 실패 전반에 걸쳐 상태를 조정합니다.

실제 리포지토리 작업에서 가장 중요한 부분은 일반적으로 첫 번째 답변이 아닙니다. 첫 번째 테스트 실패, 린트 오류 또는 환경 불일치 이후의 복구 단계 입니다.

6단계: 전문화가 도움이 될 때 서브에이전트 사용

Claude Code는 이제 서브에이전트를 지원합니다. 하나의 범용 에이전트가 모든 작업에 항상 가장 적합한 것은 아니기 때문입니다.

서브에이전트는 워크플로가 전문화의 이점을 얻을 때 유용합니다. 예를 들어:

• 구현을 위한 하나의 에이전트
• 코드 리뷰를 위한 하나의 에이전트
• 문서화를 위한 하나의 에이전트
• 테스트 조사를 위한 하나의 에이전트

이것이 모든 프로젝트에 스웜이 필요하다는 의미는 아닙니다. 작은 리포지토리에서는 여러 에이전트가 가치를 더하는 것보다 오버헤드를 더 빨리 증가시킬 수 있습니다. 그러나 반복 가능한 핸드오프가 있는 팀의 경우 서브에이전트는 더 좁은 지침과 책임을 인코딩할 수 있게 해주므로 유용합니다.

운영 원칙은 좋은 엔지니어링 팀이 이미 사용하는 것과 동일합니다. 경계가 유용할 만큼 명확할 때 역할을 분리하세요.

두 번째 에이전트가 존재하는 이유를 설명할 수 없다면 아마 필요하지 않을 것입니다.

7단계: 제어 및 감사 가능성을 위해 훅 사용

훅은 Claude Code 세션이 워크플로의 특정 지점에서 예측 가능한 검사를 트리거하도록 하려는 경우 올바른 답입니다.

예:

• 파일 편집 후 포매팅 실행
• 쓰기 작업 후 파일 변경 사항 기록
• 보호된 경로를 건드리는 명령 차단
• 로컬 감사 추적에 이벤트 전송

훅이 중요한 이유는 모델이 매번 모든 정책을 기억하는 데 의존하지 않도록 워크플로를 만들기 때문입니다. 특정 작업 범주 후에 항상 단계가 수행되어야 한다면 세션 프롬프트로 충분하기를 바라지 말고 해당 경계를 자동화하세요.

이는 특히 Claude Code가 일회성 개인 도구가 아닌 반복 가능한 팀 프로세스의 일부가 될 때 중요합니다.

Claude Code 에이전트 스택에서 Novita의 위치

Claude Code는 에이전트 인터페이스입니다. 전체 스택이 아닙니다.

팀이 Claude Code를 진지하게 사용하기 시작하면 두 가지 별도의 인프라 질문이 나타납니다.

1. 추론을 처리할 모델 백엔드는 무엇인가?
2. 도구 실행은 실제로 어디에서 실행되어야 하는가?

이것이 바로 Novita가 자연스럽게 적합한 지점입니다.

백엔드 유연성을 위한 Novita LLM API 사용

Novita는 Claude Code 스타일 워크플로를 위한 Anthropic 호환 엔드포인트를 문서화합니다. 즉, Claude Code 상호 작용 패턴을 유지하면서 모델 트래픽을 하나의 기본 경로 대신 Novita 호스팅 모델로 보낼 수 있습니다.

표준 환경 패턴은 다음과 같습니다.

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_AUTH_TOKEN="<your-novita-api-key>"
export ANTHROPIC_MODEL="qwen/qwen3-coder-480b-a35b-instruct"

이 설정은 도구 계층을 다시 구축하지 않고 다양한 코딩 모델을 벤치마킹하려는 경우 유용합니다.

또한 Claude Code의 사용성은 원하지만 단일 모델 운영 가정을 원하지 않는 팀을 위한 더 자연스러운 경로를 만듭니다. 인터페이스는 익숙하게 유지되고 백엔드는 테스트 가능해집니다.

실행 격리를 위한 Novita Agent Sandbox 사용

문제의 두 번째 절반은 실행입니다.

작은 로컬 파일만 읽고 쓰는 Claude Code 에이전트는 하나의 문제입니다. 명령을 실행하고, 패키지를 설치하고, 브라우저를 실행하고, 종속성을 다운로드하거나, 프로덕션과 유사한 시스템을 건드리는 Claude Code 에이전트는 또 다른 문제입니다.

이때 격리된 런타임이 선택 사항이 아니라 설계의 일부가 됩니다.

Novita Agent Sandbox는 정확히 이 계층을 위해 위치합니다. 코드 실행, 파일 시스템 작업, 브라우저 자동화 및 장기 실행 에이전트 워크플로를 위한 격리된 환경입니다. 즉, 부작용이 발생하는 스택의 부분을 다룹니다.

깔끔한 정신 모델은 다음과 같습니다.

• Claude Code 를 에이전트 워크플로에 사용
• Novita LLM API 를 모델 라우팅 및 실험에 사용
• Novita Agent Sandbox 를 안전한 실행 경계에 사용

추론과 실행을 분리하는 것은 일반적으로 더 나은 장기 아키텍처입니다.

동일한 워크플로 내에서 실용적인 오픈 모델 옵션

Claude Code가 잘 작동하게 되면 다음 질문은 일반적으로 "이것이 에이전트를 사용할 수 있나요?"가 아닙니다. "매일 사용하기에 어떤 백엔드가 가치가 있을까요?"입니다.

이것이 바로 오픈 가중치 코딩 모델이 매우 실용적인 방식으로 흥미로워지는 지점입니다. 팀이 Claude Code의 인터페이스를 좋아하지만 더 저렴한 실험이나 더 많은 공급자 유연성을 원한다면 오픈 모델이 적절한 다음 벤치마크가 될 수 있습니다.

신뢰할 수 있는 후보 중 하나는 Novita의 Anthropic 호환 경로를 통한 Qwen3-Coder-480B-A35B-Instruct 입니다. 모든 작업에서 Claude의 보장된 대체품으로 취급할 필요는 없습니다. 닫힌 대안과 동일한 평가 세트에 속하는 심각한 코딩 모델 옵션으로 취급해야 합니다.

이것이 많은 팀이 자연스럽게 전환하는 지점입니다.

• 에이전트 워크플로 유지
• 도구 유지
• 권한 모델 유지
• 백엔드를 변경하고 실제 작업 결과 비교

작업이 최첨단 추론보다는 리포지토리 탐색, 간단한 구현 및 도구 호출에 의해 지배된다면 오픈 모델이 테스트를 정당화할 만큼 경쟁력이 있을 수 있습니다.

이것은 Novita 설정의 유용한 점 중 하나입니다. 벤치마크를 마이그레이션 프로젝트로 전환하지 않고도 익숙한 Claude Code 워크플로 내에서 이 질문을 비교할 수 있습니다.

Claude Code 에이전트를 사용할 때 흔한 실수

대부분의 실패는 에이전트형 코딩 자체의 아이디어가 아니라 워크플로 설계에서 비롯됩니다.

에이전트에게 완료 지점 없이 광범위한 목표 부여

신뢰할 수 있는 결과를 원한다면 결과물과 이를 확인하는 방법을 지정하세요.

너무 많은 도구 첨부

더 많은 도구가 자동으로 Claude를 더 똑똑하게 만들지는 않습니다. 일반적으로 라우팅을 더 시끄럽게 만듭니다.

권한을 UX 성가신 것으로 취급

권한은 부작용을 위한 제어 평면입니다. 우회하지 말고 조정해야 합니다.

개발자 머신에서 직접 위험한 작업 실행

에이전트가 브라우저 자동화, 패키지 설치 또는 반복적인 명령 실행을 수행하는 경우 격리된 런타임을 사용하세요.

하나의 유용한 데모와 프로덕션 워크플로 혼동

Claude Code 데모는 5분 만에 좋아 보일 수 있습니다. 프로덕션 워크플로에는 정책, 감사, 런타임 격리 및 모델 선택 규율이 필요합니다.

대부분의 팀을 위한 권장 워크플로

실용적인 기본값을 원한다면 이 순서를 사용하세요.

1. 대상 리포지토리에서 Claude Code를 시작합니다.
2. /init을 실행하고 CLAUDE.md를 유용하게 만듭니다.
3. 작업에 필요한 MCP 도구만 첨부합니다.
4. 광범위한 실행 전에 /permissions를 구성합니다.
5. 워크플로가 실제 코드나 브라우저 단계를 실행할 때 샌드박스를 사용합니다.
6. 비용 가정을 표준화하기 전에 Novita를 통해 적어도 하나의 대체 백엔드를 벤치마킹합니다.

이 순서는 시스템을 이해하기 쉽게 유지합니다. 또한 제품 사용성, 모델 품질, 도구 확장 및 런타임 안전을 하나의 모호한 결정으로 혼합하지 않도록 합니다.

FAQ

Claude Code 자체가 에이전트인가요?

네. Claude Code는 일반 코드 완성 도구가 아닌 에이전트형 코딩 워크플로입니다. 파일을 검사하고, 코드를 편집하고, 명령을 실행하고, 도구 결과에 반응할 수 있습니다.

Claude Code 에이전트를 사용하려면 MCP가 필요한가요?

아니요. Claude Code는 로컬 리포지토리 액세스만으로도 유용합니다. MCP는 브라우저, 데이터베이스, API 또는 이슈 시스템과 같은 외부 도구가 필요할 때 중요해집니다.

Claude Code와 함께 샌드박스를 언제 사용해야 하나요?

워크플로가 코드를 실행하거나, 패키지를 설치하거나, 브라우저를 실행하거나, 호스트에서 직접 실행하고 싶지 않은 반복적인 부작용 작업을 수행할 때 사용하세요.

Claude Code가 Novita를 통해 모델을 사용할 수 있나요?

Novita는 Claude Code 스타일 워크플로를 위한 Anthropic 호환 설정을 문서화하므로, Claude Code 인터페이스를 유지하면서 모델 요청을 Novita 호스팅 모델로 라우팅할 수 있습니다.

여러 서브에이전트를 바로 사용해야 하나요?

일반적으로 아니요. 하나의 에이전트로 시작하고, 전문화가 혼란을 줄이는 데 충분히 명확할 때만 서브에이전트를 추가하세요.

추천 문서

• Claude Code 플러그인: MCP 도구가 Claude Code를 외부 기능으로 확장하는 방법
• 2026년 Claude Code 지원 모델: 어떤 것을 사용해야 하나요?
• 코딩 에이전트란 무엇인가요? 작동 방식과 구축 방법

2026년 8월 24일 확인된 출처: Anthropic Claude Code overview, Anthropic Claude Code settings and permissions, Anthropic Claude Code hooks, Anthropic Claude Code subagents, Anthropic Claude Code MCP, Novita Claude Code guide, Novita Sandbox overview.