Claude Code 서브에이전트로 병렬 작업 시작하기

Claude Code 활용

Claude Code를 쓰다 보면 한 작업이 끝날 때까지 기다려야 하는 순간이 의외로 많아요. 서브에이전트를 활용하면 리뷰·테스트·린트를 동시에 돌릴 수 있어요. 병렬 실행의 원리부터 실전 예시, 주의할 점까지 한 번에 정리했어요.

📌 3줄 요약

• 서브에이전트는 메인 대화와 별개로 독립된 작업을 병렬 수행하는 보조 에이전트예요.
• run_in_background 옵션과 CLAUDE.md 규칙 설정으로 자동 병렬 실행이 가능해요.
• 읽기 전용 작업끼리 병렬로 돌리고, 수정 작업은 한 에이전트에 모으는 것이 핵심 원칙이에요.

📑 목차

• 1. 서브에이전트란 무엇이고 왜 필요한가
• 2. 백그라운드 병렬 실행을 설정하는 방법
• 3. 코드 리뷰와 테스트를 동시에 돌리는 실전 예시
• 4. 병렬 실행 시 주의할 점과 활용 팁

서브에이전트란 무엇이고 왜 필요한가

Claude Code를 쓰다 보면 한 가지 작업이 끝날 때까지 기다려야 하는 상황이 자주 생겨요. 코드 리뷰를 요청하면 그 결과가 나올 때까지 테스트 실행을 시킬 수 없는 식이에요. 파일 수가 적을 때는 크게 불편하지 않지만, 프로젝트 규모가 커지면 이 대기 시간이 점점 부담이 돼요. 특히 리뷰, 테스트, 린트를 순서대로 돌리면 각 단계가 끝날 때마다 멍하니 기다리는 시간이 생기죠.

🔍 서브에이전트(subagent)는 메인 대화와 별개로 독립된 작업을 수행하는 보조 에이전트예요. 마치 팀원에게 업무를 나눠주듯, Claude Code에게 여러 작업을 동시에 맡길 수 있어요. 메인 에이전트가 전체 흐름을 관리하는 오케스트레이터 역할을 하고, 서브에이전트가 각각의 세부 작업을 독립적으로 처리하는 구조예요.

쉽게 말해, 혼자 일하던 방식에서 팀으로 일하는 방식으로 바뀌는 거예요.

핵심은 "병렬 처리"예요. 코드 리뷰와 테스트를 순차적으로 돌리면 각각 2분씩 총 4분이 걸리지만, 병렬로 돌리면 2분이면 끝나요. 이 시간 차이는 작업 횟수가 늘어날수록 더 크게 벌어져요. 하루에 10번 커밋을 한다고 가정하면, 순차 실행은 40분, 병렬 실행은 20분으로 매일 20분을 아낄 수 있어요.

서브에이전트는 Claude Code의 Agent 도구를 통해 호출돼요. 별도의 설치나 플러그인 없이, Claude Code가 이미 갖고 있는 기본 기능이에요. 터미널에서 Claude Code를 실행할 수 있는 환경이라면 바로 사용할 수 있어요.

 

💬 제가 직접 써보니, 단순한 작업 하나를 시킬 때는 차이를 못 느껴요. 하지만 파일이 10개 이상인 프로젝트에서 리뷰와 테스트를 동시에 돌리면 체감 속도가 확실히 달라져요. 처음에는 "정말 동시에 돌아가는 건가?" 의심이 들었는데, 두 작업의 결과가 거의 동시에 돌아오는 걸 보고 확신하게 됐어요.

백그라운드 병렬 실행을 설정하는 방법

서브에이전트를 병렬로 실행하려면 run_in_background 옵션을 사용해야 해요. 이 옵션을 켜면 해당 에이전트가 백그라운드에서 독립적으로 실행되고, 완료 시 알림을 받아요. 포그라운드(foreground)로 실행하면 결과가 돌아올 때까지 다른 작업을 할 수 없지만, 백그라운드로 실행하면 기다리는 동안 다른 에이전트를 추가로 띄울 수 있어요. 즉, 백그라운드 옵션이 병렬 실행의 핵심 스위치인 셈이에요.

💡 팁: CLAUDE.md 파일에 서브에이전트 호출 규칙을 미리 적어두면 편리해요. 예를 들어, "코드 리뷰는 code-reviewer 에이전트에게, 테스트는 test-runner 에이전트에게 위임한다"는 식으로 역할을 정의해요. 이렇게 해두면 매번 구두로 설명하지 않아도 Claude Code가 규칙에 따라 알아서 에이전트를 분배해줘요.

역할 분담을 명확히 적을수록 에이전트가 혼동 없이 자기 임무에 집중할 수 있어요.

 

실제 호출 구조는 간단해요. Claude Code 대화창에서 "이 코드를 리뷰하면서 동시에 테스트도 돌려줘"라고 요청하면, 오케스트레이터가 두 개의 서브에이전트를 동시에 생성해요. 내부적으로는 하나의 메시지에 두 개의 Agent 도구 호출이 포함되는 방식이에요. 사용자 입장에서는 자연어로 요청하기만 하면 되니까, 복잡한 설정 없이도 병렬 실행을 시작할 수 있어요.

⚠️ 주의: 두 작업 사이에 의존성이 없어야 해요. 리뷰 결과를 받아야 테스트를 돌릴 수 있는 구조라면 병렬 실행이 불가능해요. 독립적인 작업인지 먼저 판단하고, 독립적이라면 병렬로 보내는 것이 원칙이에요. 의존성이 있는 작업은 순차적으로 실행해야 오류를 방지할 수 있어요.

의존성 판단이 헷갈릴 때는 "A의 결과 없이 B를 시작할 수 있는가?"라고 자문해보면 명확해져요.

💬 제가 처음 시도했을 때는 의존성 판단을 잘못해서 에러가 났어요. 테스트가 빌드 결과에 의존하는 구조였는데 동시에 돌린 것이 원인이었어요. 빌드를 먼저 완료한 뒤 테스트만 병렬로 분리하니 깔끔하게 해결됐어요. 이 경험 이후로 저는 항상 작업 간 의존 관계를 먼저 그려보고 나서 병렬 여부를 결정하고 있어요.

코드 리뷰와 테스트를 동시에 돌리는 실전 예시

가장 흔한 병렬 조합은 코드 리뷰와 단위 테스트(unit test) 동시 실행이에요. 두 작업은 서로 다른 관점에서 코드를 검증하므로 의존성이 없어요. 리뷰는 코드의 구조와 로직을 사람의 시선으로 점검하고, 테스트는 실제 실행 결과가 기대값과 일치하는지 확인해요. 이 둘을 동시에 돌리면 코드 품질을 두 방향에서 한꺼번에 검증할 수 있어요.

Claude Code에 다음과 같이 지시해요. "src 폴더의 변경된 파일을 리뷰하고, 동시에 tests 폴더의 테스트를 전부 실행해줘." 이 한 문장이면 Claude Code가 알아서 두 개의 서브에이전트를 생성해요.

이렇게 요청하면 Claude Code는 내부적으로 두 개의 서브에이전트를 생성해요. 하나는 코드 리뷰를 담당하고, 다른 하나는 npm test 또는 pytest 같은 테스트 명령을 실행해요. 각 에이전트는 독립된 컨텍스트에서 작업하기 때문에 서로의 진행 상황에 영향을 주지 않아요.

 

두 에이전트가 각자 작업을 마치면, 결과가 메인 대화로 자동 합류돼요. 리뷰에서 발견된 문제점과 테스트 통과 여부를 한 화면에서 확인할 수 있어요. 먼저 완료된 에이전트의 결과부터 표시되고, 나머지도 완료되는 즉시 이어서 보여줘요. 결과를 한눈에 비교할 수 있으니 어떤 문제를 먼저 수정할지 우선순위를 정하기도 쉬워요.

더 나아가면 세 가지 작업도 동시에 가능해요. 코드 리뷰, 테스트 실행, 타입 체크(type check)를 한꺼번에 돌리는 식이에요. 타입 체크는 TypeScript 프로젝트에서 특히 유용한데, tsc --noEmit 명령 하나로 전체 타입 오류를 잡아낼 수 있어요. 세 작업을 순차적으로 돌리면 6분 이상 걸리는 것이 병렬로는 2분 안에 끝나요.

CLAUDE.md에 아래처럼 작성해두면 매번 지시하지 않아도 자동으로 병렬 실행돼요.

 

💬 제가 실전에서 가장 유용하게 쓴 조합은 리뷰와 린트(lint) 검사 병렬 실행이었어요. 린트는 코드 스타일을, 리뷰는 로직을 각각 검증하니 놓치는 부분이 거의 없었어요. ESLint나 Prettier 같은 도구가 이미 설정돼 있다면, 서브에이전트가 해당 명령을 바로 실행해주기 때문에 추가 설정이 필요 없어요.

병렬 실행 시 주의할 점과 활용 팁

병렬 서브에이전트를 사용할 때 가장 흔한 실수는 같은 파일을 동시에 수정하게 만드는 것이에요. 두 에이전트가 동일 파일을 편집하면 충돌이 발생하므로, 수정 작업은 반드시 하나의 에이전트에만 맡기세요. 예를 들어, 하나의 에이전트에게 코드 리팩토링을 시키면서 다른 에이전트에게도 같은 파일의 주석을 정리하라고 하면 충돌이 생겨요. 수정이 필요한 작업은 한 에이전트에게 모아서 맡기고, 나머지 에이전트는 읽기 전용 작업만 하도록 분리하는 것이 안전해요.

작업 유형	병렬 안전성	예시
읽기 전용	✅ 안전	코드 리뷰, 테스트, 정적 분석, 보안 스캔
서로 다른 파일 수정	⚠️ 주의	파일 A 리팩토링 + 파일 B 수정
같은 파일 수정	❌ 충돌 위험	동일 파일 리팩토링 + 주석 정리

보안 취약점 스캔, 의존성 검사, 코드 커버리지 측정도 읽기 전용 작업에 해당해요. 이런 작업들은 조합을 자유롭게 구성해서 한 번에 돌려도 문제가 없어요.

💡 팁: 서브에이전트에게 프롬프트를 작성할 때는 맥락을 충분히 제공해야 해요. 서브에이전트는 메인 대화의 내용을 모르기 때문에, 어떤 파일을 대상으로 무엇을 검증해야 하는지 명확하게 적어야 해요. "이 코드를 리뷰해줘"처럼 막연하게 요청하면 에이전트가 어디서부터 시작해야 할지 몰라서 시간이 오래 걸려요.

프롬프트에 대상 파일 경로, 검증 기준, 기대하는 결과 형식까지 적어주면 훨씬 정확하고 빠른 결과를 받을 수 있어요. 예를 들어 "코드 리뷰해줘"보다는 "src/auth 모듈의 로그인 함수에서 보안 취약점을 중심으로 리뷰해줘"가 훨씬 좋은 프롬프트예요. 범위가 넓을수록 에이전트가 헤매는 시간이 길어져요. 구체적인 파일 경로와 검증 관점을 명시하면 불필요한 탐색 시간을 줄일 수 있어요.

병렬 실행의 최대 장점은 피드백 루프(feedback loop)를 단축하는 것이에요. 코드를 수정하고, 리뷰와 테스트를 동시에 받고, 결과를 보고 다시 수정하는 사이클이 빨라져요. 이 사이클이 하루에 수십 번 반복된다는 점을 생각하면, 한 번의 사이클에서 1~2분을 아끼는 것만으로도 전체 생산성이 크게 올라가요. 특히 마감이 촉박한 프로젝트에서는 이 시간 절약이 결정적인 차이를 만들어요.

 

💬 제가 일주일 정도 병렬 실행을 활용해보니, 단점도 있었어요. 서브에이전트마다 컨텍스트(context)를 따로 소비하기 때문에 API 사용량이 늘어나는 점은 감안하셔야 해요. 무료 플랜이나 사용량 제한이 있는 환경에서는 병렬 실행 횟수를 조절하는 것이 좋아요. 그래도 작업 속도 향상이 워낙 크기 때문에, 파일이 많은 프로젝트에서는 병렬 실행을 기본으로 설정해두는 것을 권장해요.

💡 팁: 처음에는 2개 병렬로 시작해서 익숙해지면 3~4개로 늘려보는 것이 가장 안전한 접근법이에요.

✍️ 마치며

서브에이전트는 Claude Code의 작업 방식을 "순차"에서 "병렬"로 바꿔주는 핵심 기능이에요. 리뷰·테스트·린트처럼 독립적인 읽기 전용 작업을 동시에 돌리면 피드백 루프가 절반 이하로 줄어들어요. 의존성 판단만 정확히 하면 설정도 간단하고, CLAUDE.md에 규칙을 적어두면 자동화까지 가능해요. 오늘 바로 2개 병렬 실행부터 시작해보세요.

#ClaudeCode #서브에이전트 #병렬실행 #AI코딩 #개발생산성 #코드리뷰자동화