[AI] Claude Code 서브 에이전트로 AI에게 일 맡기는 법 (1/3)

· IT기술 › AI

이 블로그는 오래된 Spring MVC + JSP 구조로 만들어져 있었다. 이번에 프론트엔드는 Vue 3, 백엔드는 Spring Boot 로 새로 만들고 서버도 옮겼다. 이 작업의 대부분을 AI 코딩 도구인 Claude Code 에 맡겼다. 나는 방향을 정하고 결과를 확인하는 쪽에 가까웠다.

해 보니 AI를 잘 쓰는 데는 프롬프트 한 줄보다 일하는 구조가 더 중요했다. 이번 시리즈에서는 그 과정에서 배운 것을 세 편으로 나눠 정리할 것이다. 첫 편은 AI에게 일을 맡기는 방법이다.

1. 역할을 나눈 팀으로 만든다

처음부터 대화 하나에 모든 일을 시키지 않았다. 대신 역할별 에이전트(Agent)를 따로 만들었다. 담당 에이전트마다 범위와 지침을 적은 정의 파일을 둔다. PM 역할은 내가 대화하는 메인 세션이 맡고, 그 지침은 CLAUDE.md 에 적었다.

  • PM : 계획·위임·검수만 한다. 코드는 직접 쓰지 않는다.
  • 프론트엔드, 백엔드 도메인, 백엔드 API : 각자 맡은 폴더와 파일만 수정한다.
  • DBA, 보안, QA, 인프라 : 스키마, 보안 리뷰, 검수, 서버 구성을 맡는다.

사람이 PM 메인 세션에 방향을 주고, PM 이 프론트엔드·백엔드 도메인·백엔드 API·DBA·보안·QA·인프라 담당에게 위임하고 보고를 받으며, 모두가 CLAUDE.md 결정 기록을 읽는 구조

PM 이 위임하고 담당이 보고하며, 모두 같은 지침 문서를 읽는다.

사람으로 치면 팀장 한 명과 담당자 여럿을 둔 셈이다. 그렇다면 왜 굳이 나눌까? 한 에이전트가 모든 것을 하면 맥락이 금방 가득 차고, 고친 범위도 흐려진다. 담당을 나누면 "이 파일은 누가 바꿨는가"가 분명해져 검토가 쉬워진다. 참고로 Claude Code 의 서브에이전트는 각자 별도의 맥락에서 실행된다.

순서도 정해 두었다. 백엔드 기능 하나는 DBA → 도메인 → API 순서로 넘겼고, 파일이 겹치지 않는 작업만 동시에 진행했다.

2. 결정 사항은 지침 문서에 쌓는다

Claude Code 는 시작할 때 프로젝트의 CLAUDE.md 를 읽어 들인다. 나는 이 파일을 결정 기록장처럼 썼다. "에디터는 무엇으로 한다", "비밀번호 규칙은 이렇다" 같은 결정이 나올 때마다 날짜와 함께 한 줄씩 추가했다.

대화는 끝나면 사라지지만 문서는 남는다. 다음 날 새 대화를 열어도 AI가 같은 결정 위에서 일을 이어 간다. 같은 질문을 두 번 받지 않는 것도 장점이다. 다만 결정이 바뀌면 옛 문장을 지우거나 무엇으로 대체됐는지 꼭 적어야 한다. 서로 다른 지시가 함께 남아 있으면 AI는 그중 하나를 골라 버린다.

3. 위임할 때 넣을 것

일을 넘길 때는 아래 항목을 빠짐없이 넣게 했다.

  • 목표와 완료 조건 (어떤 테스트가 통과하면 끝인지)
  • 참고할 문서와 기존 코드 경로
  • API 명세서 (주소, 요청·응답 형태)
  • 앞 단계 담당이 만든 결과 (서비스, 오류 코드, 스키마 등)

새로 시작한 에이전트는 자기 정의 파일과 CLAUDE.md 는 받지만, 앞선 대화 내용은 보지 못한다. 그 두 문서에 없는 내용은 요청문이 전부다. 내가 당연하게 여긴 것도 적어 주지 않으면 AI는 그럴듯하게 추측해서 채운다.

4. 보고는 짧게, 상세는 파일로

에이전트가 긴 보고를 그대로 돌려주면 PM 의 맥락이 금방 찬다. 그래서 보고를 두 단계로 나눴다. 전체 내용은 날짜가 붙은 보고 파일에 쓰고, PM 에게는 15줄 이내 요약과 결정이 필요한 사항, 파일 경로만 보낸다. PM 은 필요할 때만 파일을 연다.

PM 이 목표·완료 조건, 참고 문서·코드 경로, API 계약·앞 단계 결과를 담은 위임 프롬프트를 보내면, 담당 에이전트가 전체 내용은 상세 보고 파일에 쓰고 PM 에게는 15줄 이내 요약과 결정 필요 사항·파일 경로만 보내는 흐름

요청은 자세히, 보고는 짧게 받고 상세 내용은 파일에 남긴다.

이렇게 쌓인 보고 파일은 50개가 넘었다. 나중에 "그때 왜 이렇게 정했지?"를 찾을 때도 쓸모가 있었다.


이렇게 AI에게 일을 나눠 맡기는 방법을 알아보았다. 돌아보면 AI를 혼자 다 해 주는 도구가 아니라 지침이 필요한 팀원으로 대하는 것이 출발점이었던 것 같다.

다음 포스팅에서는 AI가 "완료했다"고 한 결과를 어떻게 검증했는지 정리할 것이다.

참고