[AI 주식 알람] Claude Code 서브에이전트를 6개로 나눈 기준

앞선 글에서는 Cursor, Claude Code, Antigravity가 같은 프로젝트 규칙과 스킬을 공유하도록 하네스 구조를 정리했다.

이번 글에서는 그 구조 위에서 Claude Code 서브에이전트를 왜 여섯 개로 나눴는지 정리한다.

처음에는 메인 세션 하나로 모든 작업을 처리했다. 하지만 Prisma 스키마 수정, AI 카드 생성, UI 작업이 같은 컨텍스트에 섞이면서 작업 범위가 자주 흐트러졌다.

DB 작업을 하다가 갑자기 Tailwind 클래스를 수정하거나, 화면 작업 중 관련 없는 API 구조까지 바꾸려는 식이었다.

그래서 하나의 에이전트가 모든 것을 처리하게 두는 대신, 프로젝트의 책임 영역에 따라 역할을 나눴다.

1. 먼저 현재 스택과 맞지 않는 에이전트를 지웠다

저장소에는 초기 스캐폴드에서 사용하던 Java/Spring, Gradle, JPA/QueryDSL, Redis/Kafka, Flutter 관련 에이전트가 남아 있었다.

현재 프로젝트는 Next.js, Prisma, Vercel AI SDK 중심이기 때문에 모두 제거했다.

CLAUDE.md에도 다음과 같이 명시했다.

Java/Spring, Gradle, JPA/QueryDSL, Redis/Kafka,
Flutter 관련 에이전트는 스택이 변경되지 않는 한 다시 생성하지 않는다.

사용하지 않는 에이전트가 남아 있으면 잘못된 기술 스택이 다시 작업 후보로 등장할 수 있다.

서브에이전트를 추가하기 전에 후보군부터 정리한 이유다.

2. 파일 위치가 아니라 책임 영역으로 나눴다

서브에이전트의 경계는 폴더가 아니라 SRS의 요구사항 영역을 기준으로 정했다.

에이전트	담당 영역
nextjs-decision-layer	App Router, RSC 데이터 로드, 미들웨어, 라우팅
prisma-data-layer	Prisma 스키마, 마이그레이션, DB 쿼리
vercel-ai-gemini-cards	streamObject, 카드 스키마, Zod 검증, No Call
posthog-onesignal-analytics	이벤트, 분석, cron, push
shadcn-ui-ux	Tailwind, shadcn, 카드 UI, 접근성
document-updater	README, docs/, 하네스 문서 동기화

예를 들어 추천 카드가 화면에 나오지 않는 문제도 원인에 따라 담당이 달라진다.

카드 생성 문제
→ vercel-ai-gemini-cards

데이터 저장 문제
→ prisma-data-layer

RSC 전달 문제
→ nextjs-decision-layer

화면 레이아웃 문제
→ shadcn-ui-ux

하나의 기능을 통째로 맡기는 대신, 독립적으로 판단할 책임을 나눈 것이다.

3. 각 에이전트에 도메인별 금지 규칙을 넣었다

역할을 나눈 가장 큰 이유는 각 영역에 필요한 하드 룰을 구체적으로 적용하기 위해서였다.

이 프로젝트에서는 제품 분석 이벤트를 Prisma DB에 저장하지 않고 PostHog에 위임한다.

그래서 prisma-data-layer에는 다음 규칙을 넣었다.

EventLog 또는 NotificationLog Prisma 모델을 다시 만들지 않는다.

posthog-onesignal-analytics에는 다음 규칙을 넣었다.

제품 이벤트를 저장하기 위한 POST /api/events나
Prisma 기반 이벤트 로그를 만들지 않는다.

같은 제품 결정을 서로 다른 계층에서 각각 막는 구조다.

DB 담당
→ 이벤트 테이블 생성 금지

분석 담당
→ 이벤트 저장 API 생성 금지

UI 에이전트에도 별도 제한을 넣었다.

상세 페이지 첫 화면에는 방향, 가격 범위,
보유 기간, 이유와 신뢰도 정보를 먼저 표시한다.

Raw 차트 위젯은 primary fold에 배치하지 않는다.

이렇게 하면 작업할 때마다 사람이 ADR과 SRS를 다시 설명하지 않아도 된다.

4. 도구 권한보다 중요한 것은 변경 범위였다

여섯 에이전트는 대부분 비슷한 도구를 사용한다.

Read, Edit, Write, Grep, Glob, Bash

차이는 사용할 수 있는 도구보다 다음 항목에서 나온다.

• 어떤 영역을 담당하는가
• 어떤 파일을 수정할 수 있는가
• 반드시 확인해야 하는 SRS와 ADR은 무엇인가
• 무엇을 변경하면 안 되는가
• 완료 전에 어떤 검증을 해야 하는가

서브에이전트를 나눈 목적은 권한을 잘게 나누는 것보다, 각 영역에서 잘못된 판단을 하지 않도록 책임 범위를 좁히는 데 있었다.

5. document-updater를 따로 둔 이유

여섯 개 중 document-updater는 기능을 구현하지 않는 에이전트다.

코드는 바뀌었지만 README나 docs/가 그대로 남아 있으면 오래된 문서가 다시 AI 에이전트의 입력으로 사용될 수 있다.

그래서 커밋 전에 다음 내용을 확인하도록 했다.

• 파일 경로
• 실행 방법
• 환경변수
• API 구조
• 현재 구현 상태

다만 PRD와 SRS의 요구사항 의미까지 자동으로 바꾸지는 못하게 했다.

REQ ID, Acceptance Criteria, 제품 범위는
사람의 확인 없이 변경하지 않는다.

문서 동기화와 요구사항 변경은 별도의 작업으로 구분했다.

6. 작은 수정에는 서브에이전트를 쓰지 않는다

모든 작업을 서브에이전트에 맡기는 것은 오히려 비효율적이었다.

다음 작업은 메인 세션에서 바로 처리한다.

• 오타와 문구 수정
• 단순한 스타일 변경
• 파일 하나에서 끝나는 명확한 수정
• 별도의 도메인 판단이 필요 없는 작업

반면 다음 작업은 서브에이전트에 위임한다.

• 여러 파일에 걸친 변경
• Prisma, AI, UI처럼 전문 판단이 필요한 작업
• SRS나 ADR 확인이 필요한 작업
• 현재 컨텍스트와 분리해 검토할 작업
• 코드와 문서 동기화 작업

서브에이전트는 작업이 클 때 무조건 사용하는 기능이 아니라, 책임 경계가 흐려질 때 사용하는 구조라고 판단했다.

마무리

여섯이라는 숫자를 먼저 정한 것은 아니다.

프로젝트에서 독립적으로 판단해야 하는 책임을 나누다 보니 다음 여섯 영역이 남았다.

Next.js 애플리케이션 구조
Prisma 데이터 계층
AI 카드 생성
분석과 알림
UI와 사용자 경험
문서 동기화

전체 기준을 정리하면 다음과 같다.

현재 스택과 맞지 않는 에이전트 제거
→ 요구사항 영역별 책임 분리
→ 도메인별 금지 규칙 정의
→ 변경 가능 범위 제한
→ 작은 작업은 메인 세션에서 처리

서브에이전트를 나눈 목적은 에이전트 수를 늘리는 것이 아니라, 하나의 컨텍스트에 너무 많은 판단을 맡기지 않는 것이었다.

다음 편에서는 하네스 설계에서 벗어나, 처음 만든 주식 예측 모델이 왜 랜덤워크보다도 낮은 성능을 보였고 이를 어떻게 다시 설계했는지 정리할 예정이다.

프로젝트 저장소

https://github.com/hy2207/ai-stock-alarm-app

GitHub - hy2207/ai-stock-alarm-app