AI & 코딩

클로드 코드에서 Agent를 만드는 방법은 ?

디지털가드너 (Digital Gardener) 2026. 6. 4. 00:06

Claude Code에서 커스텀 Agent(에이전트)를 구축하는 방법은 크게 세 가지로 나눌 수 있습니다. 내장된 서브에이전트 기능을 사용해 특정 역할(코드 리뷰, 테스트 작성 등)을 전담하게 하거나, CLAUDE.md와 MCP 서버를 통해 에이전트의 성격과 도구를 확장하는 방식입니다.

1. /agents 명령어로 커스텀 서브에이전트(Subagent) 생성하기

가장 직관적이고 최신 버전에 최적화된 방법입니다. 메인 세션과 분리된, 독립적이고 특화된 에이전트를 만들 수 있습니다.

  1. 터미널에서 Claude Code를 실행한 뒤, 프롬프트 창에 /agents를 입력합니다.
  2. 에이전트 관리 인터페이스가 열리면 Create new agent(새 에이전트 생성)를 선택합니다.
  3. 핵심 설정(Configuration) 진행:
    • Location: 에이전트를 모든 프로젝트에서 쓸지(Personal), 현재 프로젝트에서만 쓸지 지정합니다.
    • Model: 작업 성격에 맞게 지정합니다. 코드의 구조를 분석하거나 속도가 중요하다면 Sonnet, 고도의 추론이 필요하다면 Opus 4.8을 추천합니다.
    • Tools: 에이전트의 권한을 제어합니다. 단순히 코드를 검토만 하는 에이전트라면 'Read-only' 도구만 활성화하여 안전하게 격리할 수 있습니다.
    • Memory: 에이전트가 코드베이스 패턴이나 이전의 수정 사항을 기억하게 하려면 User scope를 선택합니다.
  4. 프롬프트 자동화 (Generate with Claude):
    • 직접 시스템 프롬프트를 적을 수도 있지만, Generate with Claude를 선택해 "보안 취약점과 성능을 검토하는 코드 리뷰 에이전트를 만들어줘"라고 지시하면 Claude가 알아서 이름과 최적화된 프롬프트를 생성해 줍니다.
  5. 설정 요약을 확인하고 저장(s 또는 Enter)하면 즉시 서브에이전트가 활성화되어 메인 대화 중 언제든 작업을 위임할 수 있습니다.

2. CLAUDE.md를 활용한 프로젝트 맞춤형 에이전트화

Claude Code 자체를 현재 진행 중인 프로젝트에 완벽하게 동기화된 전담 에이전트로 만들고 싶을 때 사용하는 파일입니다.

  • 프로젝트 최상위 루트 디렉토리에 CLAUDE.md라는 마크다운 파일을 생성합니다.
  • 해당 파일 안에 프로젝트 개요, 사용하는 기술 스택, 코딩 컨벤션, 아키텍처 규칙, 절대 하지 말아야 할 금지 사항 등을 명확히 적어둡니다.
  • Claude Code는 매 세션이 시작될 때마다 이 파일을 자동으로 읽어 컨텍스트(Context)로 삼기 때문에, 매번 반복해서 규칙을 설명하지 않아도 해당 프로젝트의 '시니어 개발자'처럼 일관성 있게 동작합니다.

3. MCP(Model Context Protocol) 서버를 통한 외부 도구 연동

에이전트에게 단순한 코드 생성을 넘어 외부 API를 호출하거나 데이터베이스에 접근하는 실질적인 '행동 능력'을 부여하고 싶을 때 사용합니다.

  • claude mcp add 명령어를 사용해 에이전트에 다양한 외부 서버를 연결할 수 있습니다.
  • 예시 (특정 로컬 디렉토리 전용 접근 권한 부여):
  • Bash
     
    claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Projects
  • 이 외에도 GitHub MCP를 연결해 커밋 히스토리와 PR을 관리하게 하거나, Playwright MCP를 연결해 코드를 짠 뒤 브라우저를 띄워 E2E 테스트까지 스스로 수행하는 강력한 자동화 에이전트를 구축할 수 있습니다.

요약하자면, 간단한 역할 분담은 /agents로, 프로젝트 전체의 일관성 부여는 CLAUDE.md로, 에이전트의 물리적/외부 권한 확장은 MCP 서버를 활용하여 목적에 맞는 완벽한 개발 환경을 조립해 보시길 바랍니다.

 

4. 성공적인 구축을 위한 'BLAST 프레임워크'

에이전트가 엉뚱한 길로 빠지지 않고 이 복잡한 업무를 완벽히 수행하게 하려면, 올바른 지시를 내리는 것이 중요합니다. 이를 위한 BLAST 프레임워크를 소개합니다.

  • Blueprint (청사진): 가장 중요합니다. 최종적으로 이루고자 하는 명확한 목표(North Star)를 설정합니다.
  • Links (링크): 목적 달성에 필요한 외부 도구(Google Workspace, 웹 검색을 위한 Firecrawl, 크롤링을 위한 Apify 등)를 연결합니다.
  • Architecture (구조): AI가 일관된 결과를 내도록 논리적 구조를 잡아줍니다.
  • Style (스타일): 최종 결과물(예: HTML 대시보드)의 디자인이나 톤앤매너를 지정합니다.
  • Trigger (트리거): 에이전트가 작동을 시작하는 방아쇠(조건)를 설정합니다.

에이전트에게 지시를 내릴 때는 '목표 달성에 꼭 필요한 최소한의 로직만 사용할 것', '데이터를 기반으로 판단할 것'과 같은 명확한 원칙을 함께 전달하는 것이 좋습니다.

 

저작자표시 비영리 변경금지 (새창열림)