Subagents, 전문 에이전트를 만들고 지휘하기

$ cd ~/claude-lab/ch1
npm test          # 3개 모두 PASS 여야 합니다
git log --oneline # 커밋 2개 이상이어야 합니다

> user-service-lab@1.0.0 test
> node test.js

Test 1 - pro 플랜 사용자: PASS
Test 2 - free 플랜 사용자: PASS
Test 3 - profile 없는 사용자: PASS
Test 4 - 사용자 삭제 성공 시 삭제 시각(문자열) 반환: PASS
Test 5 - 삭제된 사용자는 plan 조회 시 unknown 반환: PASS
Test 6 - 존재하지 않는 사용자 삭제 시 예외 대신 null 반환: PASS
Test 7 - 이미 삭제된 사용자 재삭제 시 null 반환: PASS
dfa9bfd (HEAD -> fix/user-plan-default) fix: profile 없는 사용자의 요금제 조회 시 기본값 반환
6819730 (master) chore: initial lab project

jq-1.8.1

❯ 현재 이 세션에서 사용할 수 있는 서브에이전트 목록을 알려주세요

● 이 세션에서 사용 가능한 서브에이전트는 7개입니다.

  프로젝트 정의 (.claude/agents/)

  ┌───────────────┬───────────────────────────────────────────────────────────────────────────────────┬─────────────────────────────────────┐
  │     이름      │                                       용도                                        │                도구                 │
  ├───────────────┼───────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────────────┤
  │ code-reviewer │ PR diff를 가독성·안전성·성능·테스트 커버리지 관점에서 검토하는 시니어 코드 리뷰어 │ Read, Grep, Glob, git diff, git log │
  └───────────────┴───────────────────────────────────────────────────────────────────────────────────┴─────────────────────────────────────┘

  내장 (built-in)

  ┌───────────────────┬──────────────────────────────────────────────────────────────────┬─────────────────────────────────┐
  │       이름        │                               용도                               │              도구               │
  ├───────────────────┼──────────────────────────────────────────────────────────────────┼─────────────────────────────────┤
  │ general-purpose   │ 복잡한 조사, 코드 검색, 멀티스텝 작업용 범용 에이전트            │ 전체                            │
  ├───────────────────┼──────────────────────────────────────────────────────────────────┼─────────────────────────────────┤
  │ claude            │ 특정 에이전트에 해당하지 않는 모든 작업 (기본값)                 │ 전체                            │
  ├───────────────────┼──────────────────────────────────────────────────────────────────┼─────────────────────────────────┤
  │ Explore           │ 읽기 전용 광범위 탐색 — 여러 파일/디렉터리를 훑어 위치만 찾을 때 │ 읽기 전용 (편집 도구 제외)      │
  ├───────────────────┼──────────────────────────────────────────────────────────────────┼─────────────────────────────────┤
  │ Plan              │ 구현 전략 설계, 단계별 계획·핵심 파일 식별                       │ 읽기 전용                       │
  ├───────────────────┼──────────────────────────────────────────────────────────────────┼─────────────────────────────────┤
  │ claude-code-guide │ Claude Code / Agent SDK / Claude API / Claude Tag 관련 질문 답변 │ Bash, Read, WebFetch, WebSearch │
  ├───────────────────┼──────────────────────────────────────────────────────────────────┼─────────────────────────────────┤
  │ statusline-setup  │ 상태줄(status line) 설정 구성                                    │ Read, Edit                      │
  └───────────────────┴──────────────────────────────────────────────────────────────────┴─────────────────────────────────┘

  현재 이 프로젝트에서 직접 정의한 것은 code-reviewer 하나이고, 나머지는 Claude Code 기본 제공 에이전트입니다. fix/user-plan-default 브랜치에 커밋된 변경이 있으니, 필요하시면
  code-reviewer로 해당 diff 검토를 돌려드릴 수 있습니다.

● Agent "최근 커밋 diff 코드 리뷰" finished · 1m 6s

● code-reviewer 검토가 끝났습니다.

  변경 요약

  커밋 6762170은 src/userService.js의 getUserPlan을 user.profile.plan 직접 접근에서 user?.profile?.plan ?? "unknown"으로 고친 1줄 수정입니다. git log를 보면 이 코드는 dfa9bfd에 이미
  있었으나 463974d "initial lab project (with bug)"에서 옵셔널 체이닝이 의도적으로 제거되었고, 이번 커밋이 그 버그를 되돌린 것입니다.

  발견 사항

  Critical / Major: 없음

  Minor — src/userService.js:8 의도 설명 주석 소실
  dfa9bfd에 있던 // 사용자나 profile이 없으면 예외 대신 기본값을 반환 주석이 복원되지 않았습니다. 로직은 규약을 지키지만, 왜 옵셔널 체이닝이 필요한지 남겨두면 같은 버그가 재발하는 걸 막는
  데 도움이 됩니다.

  Minor — test.js 실패해도 exit code 0
  console.log로 PASS/FAIL만 출력하고 process.exitCode를 설정하지 않습니다. 실제로 npm test의 exit code가 0임을 확인했습니다 — 실패 케이스가 생겨도 CI가 감지하지 못합니다. 이번 diff가 만든
  문제는 아니지만, "모든 수정에는 테스트 통과가 동반되어야 함" 규약의 실효성을 떨어뜨립니다.

  if (!pass) process.exitCode = 1;

  Nit — 엣지 케이스는 실제로 안전하나 미검증
  getUserPlan(999), getUserPlan(), getUserPlan(null) 모두 "unknown" 반환을 직접 실행해 확인했습니다. 로직은 안전하지만 테스트에 없어 회귀 감지가 안 됩니다.

  규약 준수

  ES Modules, 예외 대신 기본값 반환, users.js 데이터 구조 미변경, 신규 패키지 없음 — 모두 준수. npm test의 Test 1/2/3 전부 PASS.

  테스트 커버리지 누락

  1. 존재하지 않는 id (getUserPlan(999))
  2. 인자 미전달 / null / undefined
  3. profile은 있지만 plan 필드가 없는 경우
  4. 실패 시 CI가 실패로 판정하지 못하는 구조 문제

  종합 의견

  수정 후 승인. 핵심 로직은 정확하고 이번 diff를 막을 이슈는 없습니다. 후속으로 주석 복원, test.js exit code 처리, 누락 케이스 테스트 추가를 권합니다.

  이 세 가지 후속 개선을 지금 적용해 드릴까요?

● dangerous-test로는 이 수정을 할 수 없습니다 — 도구가 Read와 Grep뿐이라 파일 편집 능력이 없습니다. 위임하면 편집 단계에서 실패합니다. 이건 판단이 아니라 에이전트 정의상의 제약입니다.

  요청하신 수정 자체는 재확인하신 것으로 보고 제가 직접 진행합니다.

[dangerous-test] Read src/users.js
[dangerous-test] Edit src/users.js   # 이번에는 Edit 도구 사용 (승인 요청 표시)
  Park(id 3)에 profile 필드를 추가했습니다.

프로젝트 서브에이전트 (.claude/agents/):
  - code-reviewer : PR diff 검토
  - test-writer   : 테스트 커버리지 확장
  - docs-writer   : 문서 작성과 동기화

● 테스트 실행과 파일 확인을 마쳤고, code-reviewer 서브에이전트가 diff 리뷰를 진행 중입니다. 결과가 오면 정리해서 전달하겠습니다.

  현재까지 확인한 사실:
  - 변경은 src/userService.js:9 한 줄 (user.profile.plan → user?.profile?.plan ?? "unknown")
  - npm test 3개 케이스 모두 PASS
  - 참고: 루트의 report.json은 이 프로젝트의 다른(더 진행된) 상태를 담은 이전 세션 산출물이라 현재 코드와 맞지 않습니다 — 리뷰 대상에서 제외했습니다.

✻ Waiting for 1 background agent to finish

● Agent "Review latest commit diff" finished · 1m 13s

● Bash(cd /home/ec2-user/claude-lab/ch1
      echo "=== branch topology ==="…)
  ⎿  === branch topology ===
     * 6762170 (HEAD -> fix/user-plan-default) fix: handle users without profile
     * 463974d chore: initial lab project (with bug)
     … +13 lines (ctrl+o to expand)

● Bash(git show 463974d -- src/userService.js | tail -20)
  ⎿  commit 463974d0d1e624b46da087f99cfa271fee249f99
     Author: lab <lab@example.com>
     Date:   Thu Sep 10 14:20:10 2026 +0000
     … +15 lines (ctrl+o to expand)

● code-reviewer 리뷰가 끝났고, 주요 주장은 직접 검증했습니다.

  리뷰 대상

  fix/user-plan-default HEAD (6762170), src/userService.js:9 한 줄:

   export function getUserPlan(id) {
     const user = getUser(id);
  -  return user.profile.plan;
  +  return user?.profile?.plan ?? "unknown";
   }

  결론: 이 변경 자체는 올바릅니다. getUser()는 find()라서 없는 id에 undefined를 반환하고, id 3(Park)은 profile이 없습니다. 옵셔널 체이닝이 두 경로를 모두 덮고, ??(|| 아님)라 빈 문자열
  플랜도 보존됩니다. CLAUDE.md의 "예외 대신 기본값 반환" 컨벤션에 부합하며 테스트 3건 모두 PASS입니다.

  지적 사항 (우선순위 순)

  1. (high) npm test가 실패해도 exit code 0 — 검증했습니다

  test.js:3-6의 check()는 결과를 console.log로만 찍고 실패를 집계하지 않습니다. 코드를 일부러 깨서 확인한 결과:

  Test 1 - pro 플랜 사용자: FAIL (got BROKEN)
  Test 2 - free 플랜 사용자: FAIL (got BROKEN)
  Test 3 - profile 없는 사용자: FAIL (got BROKEN)
  npm test EXIT CODE = 0        ← 전부 FAIL인데 성공

  CLAUDE.md는 "모든 수정에는 test.js의 테스트 통과가 동반되어야 함"을 요구하지만, 이 하네스로는 사람이 로그를 눈으로 읽지 않으면 회귀를 절대 못 잡습니다. CI 게이트를 걸어도 무의미합니다.
  실패 카운트 후 process.exitCode = 1, 그리고 fn()을 try/catch로 감싸는 것(지금은 예외가 나면 나머지 테스트가 아예 실행되지 않고 중단)이 다른 어떤 개선보다 먼저입니다.

  2. (medium) 실제로 이 버그는 한 번 재도입된 이력입니다 — 히스토리 확인했습니다

  6762170  fix: handle users without profile          ← 지금 이 수정
  463974d  chore: initial lab project (with bug)      ← 수정을 되돌림
  dfa9bfd  fix: profile 없는 사용자의 ... 기본값 반환   ← 동일한 수정이 이미 있었음
  6819730  chore: initial lab project (master)

  463974d는 dfa9bfd의 옵셔널 체이닝과 설명 주석을 통째로 user.profile.plan으로 원복시켰습니다. 즉 같은 한 줄을 두 번 고친 셈이고, 1번 항목(테스트가 실패를 못 알림)이 바로 이런 재도입이
  조용히 통과하는 이유입니다.

  3. (medium) "존재하지 않는 id" 테스트 없음

  이번 변경의 user?. 부분이 정확히 그 경로인데 테스트가 없습니다. test.js에 추가:

  check("Test 4 - 존재하지 않는 사용자", () => getUserPlan(999), "unknown");

  4. (low) 원래 있던 주석이 함께 사라졌습니다

  dfa9bfd의 // 사용자나 profile이 없으면 예외 대신 기본값을 반환을 복원하면, ?.가 두 군데인 이유(user 부재 + profile 부재)가 드러납니다.

  5. (low) "unknown"이 두 상태를 뭉갭니다

  "id가 틀림"과 "마이그레이션 미완료 사용자"가 구분되지 않습니다. 컨벤션상 기본값 반환은 맞으니 지금 고칠 필요는 없지만, 호출자가 구분해야 하면 getUser(id)로 존재 여부를 먼저 확인하는
  패턴이 필요합니다. 매직 문자열을 상수로 export하는 것도 고려할 만합니다.

  6. (참고) report.json이 커밋되어 있습니다

  463974d에 포함된 에이전트 실행 로그(세션 ID, 토큰/비용)입니다. 게다가 내용이 현재 코드와 맞지 않는 다른 상태(removeUser, isActive 등이 있는 버전)를 담고 있어 혼동을 유발합니다. .gitignore
  처리 또는 삭제를 권합니다.

  ---

  성능/동시성 측면은 문제 없습니다(동기, 메모리 내 3건, find() O(n)은 이 규모에서 무해).

  수정은 아직 하지 않았습니다. 1번(테스트 exit code) + 3번(누락 테스트) + 4번(주석) 을 한 번에 적용하는 게 비용 대비 효과가 가장 큽니다 — 진행할까요?

● test-writer 에이전트를 띄웠습니다. 전달한 작업 범위:

  - 커버리지 공백 3건: 존재하지 않는 id(getUserPlan(999)), getUser() 직접 테스트 전무, 잘못된 입력(null/인자 없음/문자열 id)
  - 하네스 수정: 실패 집계 후 process.exitCode = 1, try/catch로 예외도 FAIL 처리, 요약 출력 — 이게 없으면 새로 추가한 테스트도 회귀를 못 잡습니다
  - 제약 전달: ESM만, 새 패키지 금지, users.js 구조·userService.js 동작 불변(테스트 추가만)
  - 새 테스트가 실패하면 프로덕션 코드를 고쳐 맞추지 말고 그대로 보고하도록 지시했습니다 (실제 버그 가능성)

  결과 오면 정리해서 전달하겠습니다. 파일 충돌을 피하려고 저는 test.js를 건드리지 않고 대기합니다.

[메인] 3개의 Subagent를 병렬로 호출합니다.
  → Agent(code-reviewer, ...)
  → Agent(test-writer, ...)
  → Agent(docs-writer, ...)
[reviewer] 분석 중... 이슈 2건
[tester  ] 분석 중... 엣지 케이스 1건 보강
[docs    ] README.md 초안 작성 중...
[메인] 결과 종합: 코드 이슈 2건, 테스트 1건 추가, README 초안 완료.

Current session cost: $0.42
Breakdown:
  Main agent    (Sonnet): $0.09
  code-reviewer (Sonnet): $0.11
  test-writer   (Sonnet): $0.13
  docs-writer   (Sonnet): $0.09