Subagents

문제

조사할 것이 많아서 서브에이전트를 띄웠는데, 보고를 대화로 받으려니 중간에 잘리고 부모 컨텍스트도 함께 두꺼워집니다. 리뷰어를 여럿 붙여도 같은 결함을 놓칩니다.

추천

노이즈가 큰 조사는 서브에이전트에 맡기고 결론은 파일로 받습니다. 리뷰어를 여럿 붙일 때는 수를 늘리기 전에 기준점부터 다르게 줍니다.

이유

서브에이전트는 자신만의 컨텍스트 윈도에서 돌고, 끝나면 요약만 부모에게 보고합니다. 이 구조가 서브에이전트를 조사에 적합하게 만듭니다. 로그를 뒤지고, 파일을 대량으로 읽고, 여러 후보를 grep해서 좁히는 작업은 그 과정에서 나온 노이즈가 결론보다 큽니다. 그 노이즈를 부모 컨텍스트에 올리지 않고 서브에이전트 안에 가둔 채 요약만 받는 것이 이득입니다.

반대로 작업 자체가 메인 컨텍스트를 필요로 한다면 서브에이전트는 도움이 되지 않습니다. 지금까지 나눈 대화, 이미 읽어둔 파일, 사용자와 합의된 결정이 계속 필요한 작업을 서브에이전트에 넘기면 그 컨텍스트를 처음부터 다시 설명해야 합니다. 결과적으로 서브에이전트 안에서 같은 조사를 반복하게 됩니다. 위임할 가치가 있는지는 “이 작업이 지금까지의 대화 맥락 없이도 답이 나오는가”로 가늠합니다.

긴 보고는 대화 메시지가 아니라 파일로 받습니다. 조사 결과가 길면 메시지 도중에 잘리기 쉽습니다. 잘린 뒤 다시 받으려면 같은 요청을 반복해야 합니다. 처음부터 “결론만 파일에 써 달라”고 지시하면 이 문제가 생기지 않습니다.

위임은 서브에이전트를 하나 띄우는 것으로 끝나지 않습니다. 위임한 뒤에도 결과가 부족하면 같은 서브에이전트에 후속 지시를 보내 조사를 이어갑니다. 매번 새 서브에이전트를 띄워 맥락을 처음부터 설명하는 것보다 낫습니다.

리뷰어를 여럿 붙여도 기준점이 같으면 놓치는 결함도 같습니다. 여러 명의 리뷰어가 모두 같은 스펙 문서나 체크리스트만 보고 검증하면, 그 문서에 없는 조합의 결함은 리뷰어 수와 무관하게 전부 통과합니다. 자세한 사례는 Code Review에 있습니다. 수를 늘리기 전에 리뷰어마다 다른 기준점(다른 관점, 다른 우선순위, 다른 입력)을 줘야 놓치는 결함이 줄어듭니다.

cwd가 고정된 서브에이전트에서는 ExitWorktree 자체가 막힙니다. isolation: "worktree"나 explicit cwd로 띄운 서브에이전트는 parent session의 process-wide working directory를 바꾸게 된다는 이유로 ExitWorktree 호출이 거부됩니다. 그 안에서는 Bash cd를 쓰고, 정리는 세션 종료 시 하네스에 맡기거나 수동 git 경로로 갑니다.

Skills와 Agents는 용도가 다릅니다. Skills는 /skill-name으로 여는 대화형 워크플로 (allowed-tools로 범위를 잡습니다)이고, Agents는 독립 실행 서브태스크(tools로 범위를 잡습니다)입니다. 커스텀 서브에이전트는 .claude/agents/{name}.md(프로젝트) 또는 ~/.claude/agents/{name}.md(전역)에 name·description·tools frontmatter로 정의합니다. tools:를 생략하면 전체 허용이고, 명시하면 접근 도구를 좁혀 범위와 보안을 함께 통제합니다.

예시

서브에이전트에 조사를 맡길 때, 결과는 메시지가 아니라 파일로 받습니다.

<코드베이스 영역>을 조사해서 결론만 docs/notes/investigation.md 에 써줘.
파일 덤프는 필요 없고, 근거와 출처 경로만 남겨줘.

커스텀 서브에이전트 정의:

---
name: reviewer-a
description: 스펙 준수 여부를 검증합니다
tools: Read, Grep, Bash
---

하지 말 것

긴 보고를 대화 메시지로 받으려 하기. 도중에 잘리기 쉽습니다. 처음부터 파일에 쓰게 시킵니다.

리뷰어 수만 늘리기. 같은 체크리스트만 쓰는 리뷰어를 여럿 붙이면 같은 결함을 리뷰어 수만큼 반복해서 통과시킵니다.

cwd 고정 서브에이전트 안에서 ExitWorktree를 호출하려 하기. 거부당합니다. Bash cd로 대체합니다.