AI 에이전트란 무엇인가, Claude Code로 이해하는 핵심 구조

AI 에이전트라는 이름은 챗봇부터 자동화 스크립트까지 폭넓게 붙는다. 그렇다면 Claude 자체가 에이전트일까, 아니면 작업 환경과 실행 절차까지 갖춰야 할까. Claude Code의 구조를 따라가면 이 경계를 비교적 선명하게 그릴 수 있다.

모델이 아니라 실행 통제권이 에이전트를 가른다

Anthropic은 ‘Building Effective Agents’에서 workflow와 agent를 구분한다. workflow는 코드가 미리 정한 경로로 LLM과 도구를 움직인다. agent는 모델이 다음 행동과 도구를 동적으로 고른다. 따라서 AI API를 호출한다고 모두 에이전트가 되지는 않는다.

입력을 요약해 정해진 데이터베이스에 저장하는 서비스는 LLM을 포함해도 workflow에 가깝다. 반대로 모델이 파일을 찾아 명령을 실행하고 결과에 따라 계획을 바꾸면 agent 성격이 강해진다.

실무자들의 대화에서 나온 “환경과 작업 매뉴얼의 결합”이라는 정의는 이 구분과 잘 맞는다. 다만 매뉴얼만 추가한다고 에이전트가 되지는 않는다. 모델이 관찰 결과를 받고 다음 행동을 선택하는 실행 루프가 있어야 한다.

Claude Code는 Claude 모델에 작업장을 붙인다

Claude는 텍스트와 도구 호출을 생성하는 모델이다. Claude Code는 그 모델이 코드베이스를 읽고 파일을 고치고 명령을 실행하도록 만든 agentic coding environment다. Anthropic 공식 문서도 도구가 결과를 돌려주고 모델이 다음 행동을 결정하는 반복 구조를 설명한다.

이 작업장은 네 요소로 나뉜다. `CLAUDE.md`는 프로젝트 규칙과 검증 명령을 전달하고 built-in tools와 MCP는 파일, 셸, 외부 서비스에 접근할 수단을 제공한다. 여기에 행동과 관찰을 반복하는 Claude Code의 agent loop, 그리고 허용 범위를 통제하는 권한 설정과 hooks가 더해진다.

그래서 “Claude가 하나의 에이전트”라는 표현은 사용 맥락에 따라 맞을 수 있다. Claude Code 세션 전체를 가리킨다면 자연스럽다. API에 전달되는 모델 하나만 가리킨다면 환경과 실행기가 빠진 설명이다.

작업 매뉴얼은 CLAUDE.md와 Skills로 나눈다

작은 팀이 코드 리뷰 에이전트를 만든다고 해보자. 먼저 저장소 루트의 `CLAUDE.md`에 언어 규칙, 금지 사항, 테스트 명령을 적는다. 공식 모범 사례는 이 파일을 짧고 검증 가능한 규칙으로 유지하라고 권한다.

반복 작업의 상세 절차는 `.claude/skills/code-review/SKILL.md`로 분리할 수 있다. 여기에 검사 순서와 판정 기준을 쓰고 `scripts/`에는 린터나 정적 검사기를 둔다. 입력은 변경된 파일과 요구사항이고 산출물은 심각도별 리뷰와 실행된 검사 결과가 된다.

역할을 독립시키려면 `.claude/agents/reviewer.md`를 만든다. YAML frontmatter에는 `name`, `description`, `tools`, `model`을 지정한다. 본문에는 리뷰 범위와 보고 형식을 시스템 지침으로 적는다. 프로젝트 전용 agent는 `.claude/agents/`, 사용자 공용 agent는 `~/.claude/agents/`에 둔다.

subagent는 별도 context에서 탐색하고 최종 결과만 부모 세션에 돌려준다.

테스트 로그처럼 길지만 독립적인 작업에 유용하다. 현재 공식 문서는 `isolation: worktree` 설정으로 별도 Git worktree에서 작업하는 방법도 안내한다.

정답이 정해졌다면 스크립트가 먼저다

AI와 스크립트의 경계는 작업의 불확실성으로 정할 수 있다. JSON 형식 검사, 파일명 확인, 테스트 실행처럼 판정 규칙이 고정됐다면 스크립트가 더 싸고 재현 가능하다. Anthropic의 Skill 개발 자료도 반복 코드와 결정적 검사는 `scripts/`에 두면 토큰을 아낄 수 있다고 설명한다.

요구사항 해석이나 원인 추론처럼 경로를 미리 열거하기 어렵다면 Claude가 맡을 이유가 생긴다. 예를 들어 리뷰 agent는 어떤 파일을 먼저 읽을지 판단할 수 있다. 실제 테스트 통과 여부는 셸 명령이 결정해야 한다.

hooks에도 같은 원칙이 적용된다.

command hook은 `PreToolUse`, `PostToolUse`, `Stop` 같은 시점에 고정 검사를 실행한다. 의미 판단이 필요할 때만 prompt 또는 agent hook을 쓴다. 모든 단계를 모델에 맡기면 비용과 변동성이 함께 커진다.

API 서비스는 통제 구조까지 설계해야 한다

Claude Agent SDK는 Claude Code의 agent loop를 Python이나 TypeScript 서비스에 넣는 경로를 제공한다.

개발자는 prompt와 허용 도구를 전달하고 결과 메시지를 스트리밍한다. `maxTurns`, 예산 상한, structured output을 설정하면 종료 조건과 출력 형태도 제한할 수 있다.

외부 데이터가 필요하면 MCP server를 연결한다. 작업별 지침과 agents, hooks, MCP 설정은 Claude Code plugin 한 묶음으로 배포할 수 있다. 서비스 요청이 들어오면 agent가 자료를 찾고 판단한 뒤 JSON 결과를 반환하는 구조가 만들어진다.

써본 사람들 사이에서는 역할을 좁힌 subagent가 context를 지키는 데 도움이 된다는 반응이 있다. 반면 긴 작업에서는 반복 호출과 비용이 늘고 지침을 놓칠 수 있다는 불만도 나온다. 매뉴얼을 길게 쓰는 방식만으로 해결하기 어려운 문제다.

개인 개발자와 소규모 팀에게 중요한 설계 단위는 거대한 자율 시스템이 아니다. 실패 조건을 스크립트와 hook으로 잠그고 애매한 한두 단계에만 모델의 선택권을 주는 편이 운영하기 쉽다. 에이전트의 실체는 모델명이 아니라 사람이 어디까지 경로를 고정하고 어디서부터 판단을 넘겼는지에 있다.