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

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

mkdir -p ~/claude-lab/ch1/src && cd ~/claude-lab/ch1

cat > package.json << 'EOF'
{
  "name": "user-service-lab",
  "version": "1.0.0",
  "description": "Claude Code Workshop sample project",
  "type": "module",
  "scripts": { "test": "node test.js" }
}
EOF

cat > src/users.js << 'EOF'
// 사용자 데이터 저장소
// 주의: 일부 사용자는 profile 필드가 없음 (마이그레이션 미수행 상황)
export const users = [
  { id: 1, name: "Kim", profile: { email: "kim@example.com", plan: "pro" } },
  { id: 2, name: "Lee", profile: { email: "lee@example.com", plan: "free" } },
  { id: 3, name: "Park" }
];
EOF

cat > src/userService.js << 'EOF'
import { users } from "./users.js";

export function getUser(id) {
  return users.find((u) => u.id === id);
}

export function getUserPlan(id) {
  const user = getUser(id);
  return user.profile.plan;
}
EOF

cat > test.js << 'EOF'
import { getUserPlan } from "./src/userService.js";

function check(name, fn, expected) {
  const actual = fn();
  console.log(`${name}: ${actual === expected ? "PASS" : `FAIL (got ${actual})`}`);
}

check("Test 1 - pro 플랜 사용자", () => getUserPlan(1), "pro");
check("Test 2 - free 플랜 사용자", () => getUserPlan(2), "free");
check("Test 3 - profile 없는 사용자", () => getUserPlan(3), "unknown");
EOF

git init -q
git config user.name  >/dev/null 2>&1 || git config user.name "lab"
git config user.email >/dev/null 2>&1 || git config user.email "lab@example.com"
git add -A && git commit -q -m "chore: initial lab project (with bug)"

cat > src/userService.js << 'EOF'
import { users } from "./users.js";

export function getUser(id) {
  return users.find((u) => u.id === id);
}

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

git add -A && git commit -q -m "fix: handle users without profile"
npm test && git log --oneline

jq --version || sudo dnf install -y jq

cd ~/claude-lab/ch1
mkdir -p .claude/agents

cat > .claude/agents/code-reviewer.md << 'EOF'
---
name: code-reviewer
description: |
  PR diff를 검토하여 가독성, 안전성, 성능, 테스트 커버리지 관점에서
  개선 사항을 제안하는 시니어 코드 리뷰어. 사용 시점: 코드 리뷰가
  필요하다고 사용자가 요청하거나 git diff 검토가 필요한 경우.
tools: Read, Grep, Glob, Bash(git diff:*), Bash(git log:*)
model: sonnet
---
당신은 10년 경력의 시니어 소프트웨어 엔지니어입니다.

# 검토 우선순위
1. 안전성: null 참조, race condition, 입력 검증 누락
2. 가독성: 명명, 함수 크기, 주석 필요성
3. 성능: 알고리즘 복잡도, 불필요한 I/O
4. 테스트: 새 코드의 테스트 커버리지

# 출력 형식
- Severity: high | medium | low
- 파일:라인, 문제 설명, 권장 수정안
EOF

claude

cat > .claude/agents/dangerous-test.md << 'EOF'
---
name: dangerous-test
description: 의도적 권한 테스트용 에이전트. 사용 시점: 사용자가 이름으로 직접 지정할 때만.
tools: Read, Grep
model: haiku
---
당신은 테스트 에이전트입니다.
파일을 분석하고 결과를 보고하세요.
EOF

sed -i.bak 's/^tools: Read, Grep$/tools: Read, Grep, Edit/' .claude/agents/dangerous-test.md
grep '^tools:' .claude/agents/dangerous-test.md   # tools: Read, Grep, Edit 확인

claude

git checkout -- src/users.js
rm -f .claude/agents/dangerous-test.md .claude/agents/dangerous-test.md.bak

cat > .claude/agents/test-writer.md << 'EOF'
---
name: test-writer
description: |
  기존 코드의 테스트 커버리지를 분석하고 누락된 엣지 케이스, 분기,
  예외 경로에 대한 테스트를 작성. 사용 시점: 커버리지 부족이 확인되거나
  새 함수에 테스트가 필요한 경우.
tools: Read, Grep, Glob, Edit, Write, Bash(npm test:*)
model: sonnet
---
당신은 테스트 자동화 전문가입니다.

# 작업 절차
1. 대상 함수의 시그니처와 분기 구조 분석
2. 기존 테스트 파일이 있다면 스타일 일치
3. 정상 케이스, 엣지 케이스, 예외 케이스 모두 커버
4. 테스트 작성 후 실제로 실행하여 통과 확인

# 작성 원칙
- 테스트 하나가 한 가지만 검증
- 의미 있는 테스트 이름
- AAA 패턴 (Arrange Act Assert)
EOF

cat > .claude/agents/docs-writer.md << 'EOF'
---
name: docs-writer
description: |
  README, API 문서, 아키텍처 결정 문서(ADR)를 코드와 일치하도록 작성하거나
  업데이트. 사용 시점: 신규 기능 추가 후 문서 작성이 필요하거나 기존 문서가
  코드와 불일치할 때.
tools: Read, Grep, Glob, Edit, Write, Bash(git log:*)
model: sonnet
---
당신은 기술 문서 작성가입니다.

# 문서 종류별 가이드
- README: 프로젝트 개요, 설치, 사용법, 예시
- API 문서: 함수 시그니처, 파라미터, 반환값, 예시
- ADR: Context, Decision, Consequences 형식

# 작성 원칙
- 코드와 실제 동작이 일치해야 함
- 예시는 실제로 실행 가능한 것
- 한국어와 영어 혼용 가능, 일관성 유지
EOF

ls .claude/agents/

git diff HEAD~1 | claude -p \
  "code-reviewer 에이전트로 이 diff를 검토해 주세요" \
  --output-format json > review-result.json

head -c 400 review-result.json

# jq가 있다면: 요약과 high severity만 추출
jq '.summary' review-result.json
jq '.issues | map(select(.severity == "high"))' review-result.json 2>/dev/null

# jq가 없다면
python3 -m json.tool review-result.json | head -30

name: PR Check with Subagents
on: pull_request

jobs:
  comprehensive-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: npm install -g @anthropic-ai/claude-code

      # 직렬: code-reviewer 먼저 실행 후 결과 보고
      - name: Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "code-reviewer 에이전트로 git diff origin/main..HEAD를 검토해 주세요" \
            --output-format text > review.md

      # 병렬 요청: 테스트와 보안을 한 번에
      - name: Tests + Security
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p "다음을 모두 점검해 주세요: 1) 테스트 커버리지 부족 2) 보안 이슈" \
            --output-format json > result.json

      # 결과를 PR 코멘트로 게시
      - uses: peter-evans/create-pr-comment@v1
        with: { body-path: review.md }