특화된 AI 에이전트 만들기: 개발자, 테스터, 리뷰어, 문서화 담당자

단 하나의 범용 AI 에이전트가 있다면 편리하게 들릴 것입니다. 단 하나의 프롬프트로 티켓을 읽고, 코드를 작성하고, 테스트를 생성하고, 보안을 검토하고, 문서를 업데이트하며, 풀 리퀘스트 (Pull Request)를 생성하는 에이전트 말입니다.

좋은 아이디어입니다.

하지만 실제 엔지니어링 작업에서는, 하나의 거대한 에이전트가 명확한 직무를 가진 여러 개의 작은 에이전트보다 성능이 떨어지는 경우가 많습니다. 그 이유는 소프트웨어 작업에는 서로 다른 사고 방식 (modes of thinking)이 존재하기 때문입니다. 코드를 작성하는 것은 코드를 테스트하는 것과 같지 않습니다. 코드를 리뷰하는 것은 코드를 문서화하는 것과 같지 않으며, 보안 분석은 릴리스 노트 (release-note) 작성과 같지 않습니다. 훌륭한 AI 아키텍처 (architecture)는 이러한 차이점들을 하나의 프롬프트로 평탄화하는 대신, 그 차이를 존중합니다.

범용 에이전트의 문제점

범용 에이전트는 보통 다음과 같은 프롬프트를 받습니다:

당신은 시니어 엔지니어입니다. 작업을 구현하고, 테스트를 작성하며, 코드를 리뷰하고,
문서를 업데이트하고, PR을 생성하세요.

이는 작은 데모에서는 작동할 수 있지만, 실제 프로젝트에서는 다음과 같은 문제를 일으킵니다:

- 에이전트가 책임을 혼동합니다.
- 자신의 가정을 너무 관대하게 리뷰할 수 있습니다.
- 더 빨리 끝내기 위해 테스트를 건너뛸 수 있습니다.
...

인간도 동일한 문제를 겪으며, 바로 그 때문에 팀은 구현, 리뷰, QA, 보안, 문서화, 릴리스를 서로 다른 프로세스로 분리합니다. 특화된 에이전트 (Specialized agents)도 동일한 개념을 따릅니다.

특화된 에이전트는 제어하기가 더 쉽습니다

특화된 에이전트는 좁은 직무를 가지며, 좁은 직무는 정의하기가 훨씬 쉽습니다:

- 무엇을 읽을 수 있는지
- 무엇을 수정할 수 있는지
- 어떤 명령어를 실행할 수 있는지
...

예를 들어, 테스터 에이전트 (Tester Agent)는 테스트 파일만 수정할 수 있도록 허용할 수 있습니다:

agent: tester
can_read:
  - app/**
...

이는 범용 에이전트에게 모든 것에 대한 열쇠를 넘겨주는 것보다 훨씬 안전합니다.

개발자 에이전트 (Developer Agent)

Developer Agent (개발자 에이전트)는 제한된 범위 내의 변경 사항을 구현합니다. 모든 것을 책임질 필요는 없습니다. 이 에이전트의 주요 임무는 명확한 수락 기준 (Acceptance Criteria)을 충족하는 가장 작고 안전한 코드 변경을 수행하는 것입니다.

좋은 입력 예시:

## Task (작업)
양식 제출 후 주간 알림이 중복되는 현상을 방지하십시오.

...

예상되는 동작:

- 관련 파일 읽기
- 현재 동작을 간략하게 설명
- 허용된 파일만 수정
...

출력 예시:

## Developer Agent Report (개발자 에이전트 보고서)

변경 사항:
...

무엇이 빠져 있는지 주목하십시오. Developer Agent는 전체 작업이 완료되었다고 표시하지 않습니다. 대신 무엇을 변경했는지, 그리고 여전히 확인이 필요한 부분이 무엇인지 보고한 뒤 작업을 중단합니다.

Tester Agent (테스터 에이전트)

Tester Agent는 가설(Assumptions)이 틀렸음을 증명하려고 시도합니다. 이 에이전트의 임무는 구현 결과가 좋아 보이게 만드는 것이 아니라, 동작을 입증하는 것입니다.

좋은 작업 예시:

- 보고된 버그에 대한 회귀 테스트 (Regression Test) 추가.
- 날짜 경계값에 대한 엣지 케이스 (Edge-case) 테스트 추가.
- 집중 테스트 스위트 (Focused Test Suite) 실행.
...

Laravel 테스트 예시:

public function test_user_with_submitted_form_does_not_receive_reminder(): void
{
    Notification::fake();
...

강력한 Tester Agent는 통과된 사항뿐만 아니라, 검증할 수 없었던 사항도 보고합니다:

## Tester Agent Report (테스터 에이전트 보고서)

추가된 테스트:
...

이 "커버되지 않음 (not covered)" 섹션이 바로 가치 있는 부분입니다. 왜냐하면 구현이 여전히 입증되지 않은 지점이 정확히 어디인지 알려주기 때문입니다.

Reviewer Agent (리뷰어 에이전트)

Reviewer Agent는 코드 리뷰어처럼 변경 사항(Diff)을 읽습니다. 훌륭한 리뷰어는 단순히 작업물을 칭찬하기만 하지 않습니다. 이 에이전트는 다음 사항을 확인해야 합니다:

- 변경 사항이 최소한인가?
- 이름이 명확한가?
- 동작이 잘못된 레이어 (Layer)에 숨겨져 있는가?
...

리뷰 출력 예시:

## Reviewer Agent Findings (리뷰어 에이전트 조사 결과)

### Concern (우려 사항): 주간 경계가 서버 시간대 (Timezone)에 의존함
...

Reviewer Agent가 유용한 이유는 바로 마찰 (Friction)을 만들어내기 때문이며, 훌륭한 엔지니어링에는 적절한 위치에서의 마찰이 반드시 필요합니다.

Security Agent (보안 에이전트)

Security Agent (보안 에이전트)는 리스크 (Risk)에 집중하며, 기본적으로 회의적인 태도를 유지해야 합니다.

체크리스트 (Checklist):

- 권한 확인 (authorization checks)
- 인증 우회 (authentication bypass)
- SQL 인젝션 (SQL injection)
...

프롬프트 예시 (Example prompt):

보안 리스크를 확인하기 위해 이 diff를 검토하세요. 파일을 수정하지 마세요.
심각도 (severity), 파일, 이유, 그리고 권장 사항 (recommendation)과 함께 발견 사항을 반환하세요.

출력 예시 (Example output):

## Security Agent Report (보안 에이전트 보고서)

### Medium (중간): 권한 확인 누락 (Missing authorization check)
...

Security Agent (보안 에이전트)는 보통 읽기 전용 (read-only)이어야 합니다. 보안 패치 (Security patches)는 Developer Agent (개발자 에이전트) 또는 사람을 거쳐야 합니다. 그래야 리스크를 찾아내는 에이전트와 그 주변 코드를 조용히 재작성하는 에이전트가 동일인이 되지 않기 때문입니다.

Documentation Agent (문서화 에이전트)

Documentation Agent (문서화 에이전트)는 구현 세부 사항을 사람이 읽을 수 있는 가이드로 변환합니다. 다음과 같은 항목을 업데이트할 수 있습니다:

- README
- docs 폴더
- API 예시 (API examples)
...

입력 예시 (Example input):

동작 변경 사항:
사용자가 현재 주간 양식을 제출하면 주간 알림이 건너뛰어집니다.

...

문서 업데이트 예시 (Example documentation update):

### 주간 알림 자격 (Weekly Reminder Eligibility)

사용자가 이미 제출한 경우 주간 알림을 받을 자격이 없습니다...

이것은 가장 가치가 높은 특화된 에이전트 중 하나입니다. 엔지니어들이 바쁠 때 가장 먼저 잊히는 것이 바로 문서화이기 때문입니다.

Orchestrator Agent (오케스트레이터 에이전트)

Orchestrator Agent (오케스트레이터 에이전트)는 다른 에이전트들을 조정하며, 핵심 규칙은 스스로 모든 일을 해서는 안 된다는 것입니다. 이 에이전트의 역할은 다음과 같습니다:

- 작업 분할 (split the task)
- 에이전트 할당 (assign agents)
- 컨텍스트 전달 (pass context)
...

워크플로우 예시 (Example workflow):

Orchestrator (오케스트레이터)
  ↓
Analysis Agent (분석 에이전트): 관련 파일 찾기
...

오케스트레이터는 구조를 만들고, 특화된 에이전트들은 집중된 결과물을 만들어냅니다.

에이전트가 업무를 인계하는 방법 (How agents hand off work)

인계(Handoff)는 구조화되어야 합니다. 타입이 지정된 산출물 (typed artifact)이 더 효과적일 수 있는 상황에서 모호한 문단을 전달하지 마세요.

분석 에이전트 (Analysis Agent)에서 개발 에이전트 (Developer Agent)로의 인계 예시:

{
  "task": "양식 제출 후 중복되는 주간 알림 방지",
  "relatedFiles": [
...

이와 같이 타입이 지정된 산출물은 다음 에이전트가 사용하기 더 쉽고, 사람이 검토하기에도 더 용이합니다.

실용적인 에이전트 팀 구성

다음은 간단한 구성 예시입니다:

agents:
  analysis:
    role: "관련 코드를 찾고 현재 동작을 설명함"
...

이 설정은 복잡하지 않으며, 그것이 핵심입니다. 작게 시작할 수 있습니다.

마지막 생각

특화된 에이전트의 목적은 AI 아키텍처를 화려하게 만드는 것이 아닙니다. AI를 더 제어하기 쉽게 만드는 것이 목적입니다.

개발 에이전트 (Developer Agent)는 구현합니다. 테스터 에이전트 (Tester Agent)는 검증합니다. 리뷰어 에이전트 (Reviewer Agent)는 이의를 제기합니다. 보안 에이전트 (Security Agent)는 보호합니다. 문서화 에이전트 (Documentation Agent)는 설명합니다. 오케스트레이터 에이전트 (Orchestrator Agent)는 조정합니다. 이러한 구조는 실제 엔지니어링 팀이 이미 일하는 방식을 반영하며, 그것이 바로 이 방식이 효과적인 이유입니다.

하나의 거대한 에이전트는 데모에서 인상적으로 보일 수 있습니다. 하지만 프로덕션 (production) 환경에서 버티는 것은 집중된 에이전트들로 구성된 작은 팀입니다.

사용된 출처

사용된 출처

• Claude Code subagents documentation: https://code.claude.com/docs/en/sub-agents
• Claude Code permissions documentation: https://code.claude.com/docs/en/permissions
• Anthropic writing effective tools for agents: https://www.anthropic.com/engineering/writing-tools-for-agents
• Model Context Protocol tools specification: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

원래는 nazarboyko.com에 게시되었습니다.