독립된 컨텍스트의 subagent에는 grill-with-docs를 전달하라

TL;DR

• subagent는 **독립된 컨텍스트 (Independent Context)**로 동작한다. 메인의 긴 대화를 이어받지 않기 때문에 "눈치껏 해달라"는 것이 전혀 통하지 않는다. 전달된 문맥이 전부다. 따라서 빈약한 지시를 던지면 빈약한 결과물이 돌아온다. 병렬로 3개를 돌리면 빈약한 결과물 3개가 나란히 놓이게 된다.
• Matt Pocock의 grill-with-docs는 머릿속의 암묵적인 전제를 캐물어서 CONTEXT.md / ADR로 **외부화 (Externalize)**하는 기술이다. 이 두 가지는 서로의 단점을 보완한다. subagent의 "문맥이 전달되지 않는" 약점을, grill-with-docs의 "문맥을 외부화하는" 출력이 정확히 메워준다.

subagent는 "눈치껏 해주지 않는다"

Claude Code의 subagent(Agent 도구로 실행되는, 독립된 컨텍스트를 가진 Claude 인스턴스)는 메인 에이전트의 컨텍스트를 이어받지 않는다. 이는 설계상의 강점으로, 메인 대화가 아무리 길어져도 subagent의 작업은 오염되지 않는다.

하지만 뒤집어 말하면, 다음과 같은 성질을 갖게 된다.

메인 대화에서 쌓아 올린 전제, 경위, 암묵적인 합의를 subagent는 전혀 알지 못한다.

사람 상대라면 "평소처럼", "아까 말한 그거"로 통한다. subagent에게는 통하지 않는다. 전달된 지시에 적혀 있지 않은 것은 subagent에게 존재하지 않는 것이다. 적혀 있지 않은 부분은 subagent가 자신의 해석으로 멋대로 채워 넣는다.

실제로 직접 해보고 쓴맛을 보았다. "Issue #1234를 구현해줘" 정도로 던지면, subagent는 모호한 부분을 각자의 해석으로 채워 구현해 온다. 병렬로 3개를 실행하면, 마무리가 허술한 구현물이 3개 동시에 올라온다. 리뷰와 재작업(rework)도 3배가 된다. 병렬화는 빈약한 지시를 빈약한 성과로 증폭시키는 장치이기도 하다.

subagent를 잘 사용하는 열쇠는 결국 이것에 달려 있다.

모호함이 없는 명시적인 문맥만 전달할 수 있다면, subagent는 독립적으로 완수할 수 있다. 문제는 그 문맥을 어떻게 준비하느냐이다.

grill-with-docs는 암묵적인 전제를 외부화한다

그 "명시적인 문맥"을 만드는 도구가 바로 Matt Pocock의 grill-with-docs(SKILL.md)였다. 이름만 보고 "문서로 정리하는 기술"이라고 생각했으나, 실제로는 전혀 달랐다. 계획을 기존의 도메인 모델(Domain Model)에 대해 가차 없이 캐묻는 기술이다.

Matt Pocock 본인의 정의(의역)는 다음과 같다.

공통 이해에 도달할 때까지, 이 계획의 모든 측면에 대해 가차 없이 인터뷰한다. 설계 트리의 각 가지를 내려가며, 결정 간의 의존 관계를 하나씩 해소한다.

구체적인 동작은 다음과 같다.

• 질문을 하나씩 던지고, 답변을 기다린 후 다음으로 진행한다. 코드로 답을 낼 수 있는 것은 묻지 않고 코드를 탐색하여 확인한다. 모호하거나 다의적인 용어가 나오면 정전적인(canonical) 용어를 제안하며 다듬는다. "당신은 'account'라고 말했지만, Customer인가 User인가. 별개의 것이다."
• 용어집(CONTEXT.md)과 모순되는 용어 사용은 즉시 지적한다. 코드와 어긋나는 주장이 나오면 모순을 드러낸다.
• 결정이 굳어지면 그 자리에서 한다. CONTEXT.md(용어집)와 ADR을 업데이트한다. CONTEXT.md는 구현 상세를 갖지 않는 용어집 역할에 충실하며, ADR은 "되돌리기 어렵다・문맥 없이는 놀라움을 산다・진정한 트레이드오프(Trade-off)가 있다"라는 3가지 조건이 갖춰졌을 때만 신중하게 작성한다.

포인트는 출력이다. 캐묻는 결과, 자신의 머릿속에만 있었던 암묵적인 전제가 CONTEXT.md / ADR이라는 외부 파일로 쓰여진다. 요약과는 반대로, 정보를 깎아내는 것이 아니라 모호함을 없애고 판단의 근거를 더해가는 것이다.

왜 이 두 가지가 잘 맞물리는가

여기까지 오면 조합해야 하는 이유는 명백하다. 한쪽의 약점이 다른 쪽의 출력으로 정확히 메워지기 때문이다.

구분	subagent 단독 사용	grill-with-docs를 통할 때
보유한 문맥	메인의 암묵적 전제를 모름	CONTEXT.md에 전제가 명문화되어 있음
모호한 용어	각자의 해석으로 멋대로 채움	용어집으로 정의가 일관되게 고정됨
설계 판단	지시에 없으면 무시 또는 독단	ADR에 트레이드오프와 함께 기록됨
병렬로 3개 실행 시	허술한 구현물 3개 + 재작업 발생	동일한 전제에 따른 구현물 3개

subagent가 원하는 것은 "구현 세부 사항(implementation details)을 포함하지 않는, 모호함이 없는 공유 문맥(shared context)"이다. 그리고 grill-with-docs가 뱉어내는 CONTEXT.md는 바로 구현 세부 사항을 포함하지 않는 용어집으로서 설계되어 있다. 의도한 것은 아니겠지만, 출력 형태가 subagent의 입력 요구사항과 완벽하게 일치한다.

역방향도 성립한다. grill-with-docs로 문맥을 연마(grill)하더라도, "그래서 이 연마된 문맥을 누가 사용하는가"가 공중에 붕 뜨기 쉽다. 그 자리에 subagent가 병렬 구현의 수신자로서 자리 잡는다. 연마된 문맥을 여러 subagent가 동일한 전제를 공유하며 병렬로 소화해 나가는 것이다.

당신
│ /grill 1234 ← 암묵적인 전제를 추궁하여 CONTEXT.md / ADR로 외부화
▼
...

실제 플로우

순서가 중요하다. 연마한 다음에, 병렬로 흘려보낸다.

/grill로 연마하여 CONTEXT.md / ADR에 쓰기: worktree를 나누기 전에 계획을 추궁하고, 용어·경계·트레이드오프(trade-off)를 /grill로 연마하여 CONTEXT.md / ADR에 기록한다. 여기에 가장 많은 시간을 할애한다.

worktree로 분리하기: 연마된 문맥을 가지고 작업을 물리적으로 분리한다 (이전 기사의 구성).

subagent에게 위임하기: 지시의 본체를 쓰지 않고, "CONTEXT.md와 해당 ADR을 읽은 후 구현하라"고 참조시킨다. subagent는 모호함을 메울 필요가 없으며, 구현에 집중할 수 있다.

skill(스킬)화하면 다음과 같다.

# .claude/skills/grill.md
착수 전에 계획을 추궁하고, CONTEXT.md / ADR을 업데이트한다.
# .claude/skills/delegate.md
...

/grill을 건너뛰고 /delegate만 호출하면, 결국 "눈치채지 못하는 subagent에게 빈약한 지시를 전달하는" 상태로 되돌아간다. 연마하는 공정을 생략하면, 병렬화한 만큼 재작업(rework)이 늘어난다.

요약

내용
subagent의 성질	독립된 컨텍스트. 눈치채지 못함. 전달된 문맥이 전부임

subagent를 병렬로 돌리기 전에 해야 할 일이 있다. 머릿속의 암묵적인 전제를 subagent가 읽을 수 있는 형태로 외부화하는 것이다. grill-with-docs는 이를 위한 도구이며, 출력되는 CONTEXT.md는 subagent의 입력 요구사항과 딱 맞아떨어진다. 병렬화의 가치는 흘려보내는 양이 아니라, 흘려보내기 전에 문맥을 얼마나 연마했느냐에 따라 결정된다.

참고

• mattpocock/skills — grill-with-docs
• Claude Code — sub-agents
• 이전 글: Claude Code의 worktree + skills + subagent로 팀 개발 플로우를 구축한 이야기

이 기사는 Vottia의 제품 개발 과정에서 얻은 지식을 정리한 것입니다.

Discussion