AI/claude

Claude Code 팀 사용법 3편: 서브에이전트에게 맡기고 검증하는 법

agentnote 2026. 10. 4. 10:41

요약. Claude Code(클로드 코드) 서브에이전트에게 일을 맡겼다면, 끝났는지는 "다 했습니다" 알림이 아니라 git 커밋으로 확인합니다. 30분이 지나도 커밋이 없으면 메인 에이전트가 직접 마무리합니다. 배포 전에는 검사 명령 하나로 여섯 단계를 정해진 순서대로 돌리고, 마지막 확인은 브라우저에서 눈으로 합니다.

이 글은 "Claude Code 팀 사용법" 4편 연재 중 3편입니다. 프론트엔드·백엔드가 있는 웹 시스템을 여러 명이 함께 개발하는 팀 기준입니다. 데이터 분석이나 문서 작업, 혼자 쓰는 작은 스크립트처럼 상황이 다르면 맞지 않는 규칙도 있습니다.

서브에이전트 작업 완료를 확인하는 규칙이 세 번 바뀐 이야기

1편에서 소개한 여덟 가지 중 5번은 "맡긴 일이 됐는지는 git으로 확인한다"입니다. 이 규칙만 처음부터 이런 모양이 아니었습니다. 세 번 바뀌었고, 바뀔 때마다 시간을 크게 날린 뒤였습니다.

1차, 알림을 기다렸습니다. 일을 쪼개 에이전트에게 맡기고 "다 했습니다"가 오기를 기다렸습니다. 그런데 에이전트가 아무 말 없이 멈춘 채 몇 시간씩 있었습니다. 목록에는 계속 살아 있는 것으로 보이니 기다리는 쪽은 알 수가 없었습니다.

2차, 알림 대신 커밋을 봤습니다. 알림은 참고만 합니다. 커밋이 생겼으면 알림이 없어도 일은 된 것입니다. 에이전트가 일을 다 끝내고 커밋 직전에 죽은 적이 있었는데, 처음부터 커밋을 봤다면 바로 알았을 일이었습니다.

3차, 커밋도 안 오면 메인 에이전트가 직접 마무리합니다. 기다리는 시간에 대략 30분이라는 상한을 뒀습니다. 그 시간을 넘으면 에이전트가 죽은 것으로 봅니다. 메인 에이전트가 남은 작업을 확인해 직접 커밋합니다. 이렇게 회수해서 잃은 작업은 없었습니다.

정리하면 지금 규칙은 이렇습니다. 알림은 참고용이고, 판단은 커밋으로 합니다. 30분이 지나도 커밋이 없으면 메인 에이전트가 마무리합니다.

그림 1. "끝났다"를 판단하는 기준은 알림 → 커밋 → 메인 에이전트 순으로 바뀌었습니다.

Claude Code 에이전트에게 일을 나눠 맡기는 이유

팀 안내 문서에서 "이 부분이 제일 중요하다"고 적은 곳이 여기입니다. 일이 크면 에이전트를 여러 개 띄워 나눠 맡깁니다. 여기서 에이전트는 내 세션이 따로 띄운 Claude입니다. 자기 기억을 따로 갖고 한 가지 일만 합니다. 편한 만큼 위험해서, 가장 크게 데인 곳도 여기입니다.

나눠 맡기는 이유는 단순합니다. 한 세션은 큰 계획을 끝까지 가지 못합니다. 한 번에 기억할 수 있는 양(컨텍스트)이 정해져 있어서 뒤로 갈수록 앞을 잊습니다. 그래서 계획을 먼저 파일로 확정합니다. 일 하나마다 새 에이전트에게 깨끗한 기억을 줍니다. 진행 상황은 커밋으로 읽습니다.

맡기고 기다릴 때 지키는 규칙은 네 가지입니다.

규칙 1. "다 했습니다" 알림을 믿지 않는다

실제로 두 번 있었던 일입니다. 에이전트가 일을 다 끝내고 커밋 직전에 죽었는데 알림이 오지 않았습니다. 죽은 줄 모르고 알림만 기다리며 몇 시간을 앉아 있었습니다. 그래서 판단 기준을 "알림이 왔나"에서 "저장소가 움직였나"로 바꿨습니다.

git log --oneline -3   # 커밋이 생겼나
git status --short     # 안 끝낸 게 남아 있나

커밋이 있으면 알림과 상관없이 다음으로 넘어갑니다. 커밋되지 않은 변경이 남아 있으면 그 에이전트는 죽은 것으로 봅니다. 되살리려고 씨름하지 않습니다. 메인 에이전트가 남은 변경을 확인해서 직접 커밋합니다. 실제로 그렇게 회수했고, 잃은 작업은 없었습니다. 대략 30분이 넘어가면 메인 에이전트가 반드시 직접 확인합니다.

규칙 2. 에이전트 목록은 "살아 있다"는 증거가 아니다

리뷰를 맡긴 에이전트 하나가 조용히 멈춘 적이 있습니다. 그런데 목록에는 계속 "26분 전, 살아 있음"으로 보였습니다. 그 표시만 믿고 밤새 기다렸습니다. 아침에 세어 보니 떠 있는 에이전트가 수십 개였고, 메모리를 수 GB 먹고 있었습니다. 대부분 전날 쓰고 남은 잔해였습니다. 그런데 그날 밤새 기다린 그 검증을 직접 해 보니 1초도 안 걸렸습니다.

그래서 규칙을 정했습니다. 리뷰는 보통 1~3분이면 끝납니다. 10분 안에 안 끝나면 메인 에이전트(내가 직접 말을 거는 세션)가 확인합니다. 메인 에이전트가 리뷰 에이전트에게 한 번 재촉해 보되 답을 기다리지는 않습니다. 답이 안 오면 리뷰 에이전트를 중단시키고, 메인 에이전트가 그 검증을 직접 돌려 봅니다.

규칙 3. 다 쓴 에이전트는 스스로 안 죽는다

에이전트는 일을 끝냈어도 프로세스가 남아서 메모리를 먹습니다. 그래서 세션을 마칠 때 정리합니다. 여기서 순서가 중요합니다. 에이전트가 떠 있던 화면(판)을 치워도 프로세스는 따로 살아 있기 때문입니다.

  1. 지금 몇 개가 떠 있는지 먼저 셉니다.
  2. 지금 일하는 하나만 남기고 정리합니다.
  3. 내 세션의 죽은 화면만 회수합니다.

죽이기 전에 대상 개수를 꼭 셉니다. 1번을 건너뛰고 2번부터 하면 일하던 에이전트를 날립니다. tmux 서버 전체를 끄는 명령(tmux kill-server)은 살아 있는 에이전트까지 죽이니 쓰지 않습니다. 끄는 명령은 환경마다 달라서 순서만 적습니다.

그림 2. 정리는 "세기 → 남기기 → 회수" 순서입니다. 세기를 건너뛰면 일하던 에이전트를 날립니다.

규칙 4. 여러 세션이 같은 폴더를 쓴다

저희 팀은 여러 세션이 같은 폴더에서 동시에 일합니다. 그래서 커밋할 때는 경로를 지정합니다(git commit -- <경로>). 경로 없이 커밋하면 옆 세션이 만든 파일이 같이 딸려 들어갑니다. 커밋 전에는 git branch --show-current로 지금 브랜치를 확인합니다. 옆 세션이 브랜치를 바꿔 놨을 수 있기 때문입니다.

개발 DB에 뭔가 쓰기 전에는 팀에 먼저 알립니다. 실제로 옆 세션이 관측하려고 준비해 둔 데이터를 지운 적이 있습니다.

배포 전 검사: 명령 하나, 여섯 단계

배포 전에 기억할 것은 검사 명령 하나입니다. 팀에서는 make 명령 하나로 묶었습니다. 내 컴퓨터에서 도는 검사와 서버(CI, 코드를 올릴 때마다 자동으로 검사하는 서버)에서 도는 검사가 같은 파일 하나를 씁니다. 그래서 "제 로컬에선 됐는데요"가 생길 자리가 없습니다. 검사는 여섯 단계를 정해진 순서로 돕니다.

순서 무엇을 보나 왜 이 순서인가
① 마이그레이션 번호 DB 변경 번호가 겹치는지 겹치면 뒤 단계가 전부 무의미해진다
② 구조 검사 경로, API 목록, 없는 이름, 파일 크기 제일 빠르고 제일 자주 깨진다. 먼저 돌려 빨리 실패하는 게 낫다
③ 스키마 올리기 임시 DB에 표를 만든다 ④가 쓸 테이블을 먼저 만든다
④ 동작 테스트 계산, 화면 격자, 캐시, 업로드, 요약 같은 기능 묶음 관련 테스트끼리 묶어 차례로 돌린다. 실패하면 어느 기능이 문제인지 바로 안다
⑤ 프론트 타입 검사 → 단위 테스트 타입 검사가 진짜 검사다
⑥ API 응답 모양 확인 서버를 실제로 띄워, 화면이 기대하는 응답 모양(필드 이름·자료형)과 맞는지 ⑤의 프론트 테스트는 가짜 응답을 써서, 서버가 필드 이름을 바꿔도 통과해 버린다

일부러 검사에 안 넣은 것

예전 화면과 숫자를 대조하는 검사는 자동 검사에 넣지 않았습니다. 이 검사가 실패하면 "집계 규칙이 바뀌었다"는 뜻입니다. 그게 의도한 변경인지 실수인지는 사람이 판단해야 합니다. 그래서 집계 규칙을 건드렸을 때만 손으로 돌립니다.

배포에서 조심할 것 세 가지

  • 배포는 "지금 폴더 내용"을 빌드합니다. 푸시한 커밋이 아닙니다. 그래서 배포가 도는 동안에는 파일을 고치지 않습니다.
  • 배포 명령에 파이프(|)를 걸면 실패가 성공으로 보입니다. 파이프로 이으면 종료 코드(명령이 성공했는지 알려 주는 숫자)가 뒤쪽 명령의 것이 됩니다. 그래서 배포 명령에는 파이프를 걸지 않습니다.
  • 로그만 보고 "됐다"고 했다가 화면이 그대로였던 적이 있습니다. 그래서 마지막 확인은 브라우저로, 눈으로 합니다.

그림 3. 세 가지 모두 "됐다"고 보이는데 실제로는 안 된 경우입니다.

자주 겪는 문제: 증상만 보면 원인을 잘못 짚는 것들

팀에서 실제로 겪은 문제입니다. 모두 증상만 보고는 원인을 엉뚱한 데서 찾기 쉽습니다.

이런 증상이면 진짜 원인은 이렇게
"반영했습니다"라는데 안 돼 있다 폴더만 보고 판단했는데 커밋엔 없었다 git show HEAD:<파일>로 확인
DB 변경 번호가 겹쳤다 내 컴퓨터 기준으로만 봤다 원격 기준으로 확인(git ls-tree origin/main <폴더>)
커밋에 남의 파일이 섞였다 여러 세션이 같은 폴더를 쓴다 git commit -- <경로>로 경로 지정
파일 크기 검사가 이유 없이 빨갛다 검사가 세는 줄 수가 wc -l보다 1 크다 한도를 올리지 말고 주석을 줄인다
타입 검사는 통과인데 실행하면 죽는다 맥에서 파일명 대소문자 충돌(xyz.ts / Xyz.tsx). 타입 검사가 못 잡는다 그런 파일명 짝을 아예 만들지 않는다
CSS를 고쳤는데 화면에서만 안 먹는다 클래스 이름이 다른 데와 겹쳤다 이름에 접두어를 붙이고 브라우저에서 확인
브라우저로 잰 숫자가 이상하다 탭이 뒤에 있으면 애니메이션이 안 돈다 잴 때 document.hidden부터 찍는다
"API 응답 모양 테스트가 있으니 괜찮겠지" 건너뛰도록 설정돼 있었고 개발 DB 데이터도 0건이라 실제로는 한 번도 안 돌았다 테스트 "이름"을 증거로 읽지 않는다
배포는 됐다는데 화면이 그대로다 배포가 푸시한 커밋이 아니라 지금 폴더를 빌드했다 배포 중에는 파일을 고치지 않는다
git이 403에 "clock skew"라고 한다 시계가 아니라 키체인이 만료된 인증을 물고 있다 그 호스트의 인증 정보만 초기화
새로 만든 CSS가 화면에 안 나온다 스타일 목록 파일에 한 줄(import)을 안 적었다 조각을 만들면 목록에 한 줄 추가
프론트 테스트가 이유 없이 빨갛다 저장소 맨 위에서 돌렸다 프론트 폴더로 이동해서 돌린다

브라우저로 숫자를 재는 문제는 두 번이나 틀렸습니다. 그래서 지금은 재기 전에 document.hidden(탭이 가려져 있는지 알려 주는 값)부터 찍습니다.

팀에서 안 하기로 한 것 10가지

규칙보다 금지가 짧아서 외우기 쉽습니다.

안 하는 것 왜
뭘 쓸지 정하기 전에 파일부터 열기 스킬이 "어떻게 찾아볼지"까지 정해 줍니다
맡겨 놓고 알림만 기다리기 git이 사실입니다. 30분 동안 커밋이 없으면 메인 에이전트가 직접 확인합니다
큰 파일을 통째로 읽히기 컨텍스트가 찹니다. 필요한 부분만 짚어 줍니다
배포 명령에 파이프 걸기 실패가 성공처럼 보입니다
빌드가 붙이는 버전 숫자(?v=) 손으로 고치기 빌드가 알아서 붙입니다
파일 크기 한도 올리기 대신 주석을 줄입니다
테스트 "이름"을 증거로 읽기 실제 출력을 봅니다
현업에 나갈 자료를 임시 폴더에 두기 이틀 뒤에 못 찾습니다. docs/에 둡니다
남의 settings.local.json 복사하기 개인 파일입니다. 필요한 권한은 쓰면서 쌓입니다
개발 DB에 말없이 쓰기 옆 세션이 그 데이터로 뭔가 준비 중일 수 있습니다

에 맡길 때 두 줄만

다음에 에이전트에게 일을 맡기면, 알림 대신 30분쯤 뒤에 아래 두 줄을 쳐 보세요.

git log --oneline -3
git status --short

더 깊이: 공식 문서로 보는 서브에이전트

에이전트가 따로 기억을 갖는 이유. Claude Code 공식 문서 Subagents는 서브에이전트가 메인 대화와 분리된 자기 컨텍스트에서 일한다고 설명합니다. 이 글에서 "일 하나마다 새 에이전트에게 깨끗한 기억을 준다"고 한 것이 이 구조 덕분입니다. 저희 팀은 결과를 알림이 아니라 저장소에 남은 커밋으로 읽습니다.

절차를 스킬로 고정하기. 저희 팀은 절차를 superpowers 플러그인 하나로 통일했습니다. 이 플러그인의 skills 폴더에는 /subagent-driven-development, /dispatching-parallel-agents, /verification-before-completion, /finishing-a-development-branch 같은 스킬이 있습니다. 이름 그대로 계획을 에이전트에게 나눠 맡기는 절차와, "됐습니다"라고 말하기 전에 검증하는 절차입니다.

사람에게 묻게 하는 일. 배포, git push, git reset, git checkout은 매번 사람에게 묻도록 권한을 설정해 뒀습니다. 이 글의 규칙 4처럼 여러 세션이 같은 폴더를 쓰면 checkout 한 번이 옆 세션의 작업을 덮을 수 있기 때문입니다. 권한 설정은 공식 문서 Configure permissions에 있습니다.

자주 묻는 질문

Q. Claude Code 에이전트가 끝났는지 어떻게 확인하나요? 알림 대신 저장소를 봅니다. git log에 커밋이 생겼으면 끝난 것입니다. 30분이 지나도 커밋이 없고 변경만 남아 있으면 멈춘 것으로 보고 메인 에이전트가 마무리합니다.

Q. 에이전트 목록에 "살아 있음"이라고 나오면 믿어도 되나요? 아닙니다. 멈춘 에이전트도 목록에는 살아 있는 것으로 보일 수 있습니다. 리뷰가 10분 안에 안 끝나면 메인 에이전트가 직접 확인합니다.

Q. 테스트가 다 통과했는데 왜 브라우저로 또 보나요? 가짜 응답을 쓰는 테스트는 서버가 바뀌어도 통과합니다. 배포 로그가 성공이어도 화면이 그대로일 수 있습니다.

다음 4편은 "숫자로 고르기와 화면 만들기"입니다.

연재 목차: Claude Code 팀 사용법

출처

  • Claude Code 문서, Subagents: https://code.claude.com/docs/en/sub-agents
  • Claude Code 문서, Configure permissions: https://code.claude.com/docs/en/permissions
  • Claude Code 문서, Settings: https://code.claude.com/docs/en/settings
  • obra/superpowers (MIT): https://github.com/obra/superpowers