제7강: 목표, 계획, 협업: 단독 요원에서 군단으로

한 줄 요약: 혼자서 합내기에는 벅찬 큰 작업은 「에이전트 군단」에게 맡기세요——목표(goal) 는 「왜 하는가」를 영구적으로 기록하고, 계획(plan) 은 대조 가능한 협업 상태로 자리 잡으며, 백그라운드 작업(tasks) 과 할 일(todo) 이 진행 상황을 추적하고, 서브에이전트(subagent) 가 각자의 하위 작업을 맡고, 워크플로(workflow) 스크립트가 모두를 질서 있는 파이프라인으로 편성합니다. 단독 작전에서 군단 협업으로.

1. 사용자 스토리: 큰 작업을 군단에 어떻게 나눌 것인가

여러분이 DSH 사용자로서 큰 작업을 맡긴다고 상상해 보세요. 「회사의 코드베이스를 구 프레임워크에서 새 프레임워크로 마이그레이션」하는 작업입니다. 이 작업은 너무 커서, 하나의 에이전트가 한 번에 처리하면 엉망이 됩니다——먼저 분해하고, 다음으로 분담하고, 진행하면서 대조해야 합니다. 전체 과정은 여섯 단계로 나눌 수 있습니다.

1. 목표 세우기(goal): 먼저 「마이그레이션 완료」라는 전체 목표를 명확히 하고 영구적으로 저장합니다——세션이 중단되거나 재시작되어도 에이전트는 자신이 어디로 가야 하는지 알고 있습니다.
2. 계획 세우기(plan): Plan Mode에서 큰 작업을 단계로 나눕니다. 현황 조사 → 마이그레이션 방안 설계 → 일괄 수정 → 검토 및 회귀 확인. 모든 단계가 협업 상태에 기록되어, 사람과 에이전트가 언제든 「지금 어느 단계까지 왔는지」를 대조할 수 있습니다.
3. 할 일 나열하기(todo): 각 단계를 다시 체크 가능한 목록 항목으로 나눕니다. 예를 들어 「구 API를 사용하는 모든 파일 나열」, 「각 파일의 마이그레이션 변경 사항 생성」 등입니다.
4. 백그라운드 작업 돌리기(tasks): 시간이 오래 걸리는 일(전체 코드베이스 스캔, 일괄 컴파일 등)은 백그라운드로 돌려, 메인 에이전트가 마냥 기다리지 않게 합니다. 언제든 진행 상황을 관찰하거나, 작업을 취소하거나, 완료 알림을 기다릴 수 있습니다.
5. 서브에이전트에게 위임하기(subagent): 「현황 조사」는 조사 담당에게, 「일괄 수정」은 프로그래머에게, 「결과 검토」는 검토 담당에게 맡깁니다——각 서브에이전트가 하나의 하위 작업을 맡아 각자의 일을 합니다.
6. 워크플로(workflow)로 편성하기: 위의 서브에이전트들을 파이프라인으로 잇는 스크립트를 작성합니다. 먼저 조사, 다음 코딩, 마지막 검토. 각 단계는 병렬로 진행할 수도 있고, 결과는 오케스트레이터로 통합되어 돌아옵니다.

아래 그림은 이 「군단 작전」의 조감도입니다. 오케스트레이터(메인 에이전트 또는 workflow)가 아래로 위임하고, 목표·계획·작업·할 일이 처음부터 끝까지 가로지르는 하나의 궤도처럼 흐륵며, 서브에이전트는 각자의 역할을 다하고, 마지막에 결과가 모여 돌아옵니다.

이제 이 여섯 개의 역량 패밀리를 하나씩 살펴 보겠습니다——모두 DSH 소스 코드에 실제로 존재하는 패키지(package)에서 온 것으로, 각각 명확한 책임과 마운트 지점을 가지고 있습니다.

2. 목표와 계획: 「무엇을 할 것인가」에 근거를 부여하고 재개 가능하게 하기

2.1 goal: 영구화된 동일 세션 목표

소스 리포지토리의 packages/goal/README.zh.md 정의는 한 단락뿐이지만 매우 중요합니다.

에이전트 세션의 영구적 목표 상태로, 이를 소비하는 모델 지향 도구 및 이행(continuation) 정책과는 독립적이다. goal 상태는 소속 세션 로그의 일부이며, 소비자는 dsh-goal에 의존하고 구체적인 에이전트 루프에는 절대 의존하지 않는다.

뜯어 보면 세 가지 요점이 있습니다.

• 영구화: goal은 「세션의 영구적 목표 상태」이지, 모델이 머릿속에 임시로 기억하는 한 문장이 아닙니다. 세션 로그의 일부입니다——1장의 「실행은 재구성 가능」을 기억하시나요? 로그가 곧 진실이며, 목표도 로그의 일부로서 마찬가지로 복원하고 재생할 수 있습니다.
• 소비자로부터의 독립: goal 상태와 「그것을 어떻게 사용하는가」는 분리되어 있습니다. 이를 소비하는 주체로는 모델 지향 도구(tool-goal, 모델이 목표를 읽고 업데이트할 수 있게 함), 사용자 지향 명령(command-goal, 명령줄이나 화면에서 목표를 확인할 수 있게 함), 그리고 이행 정책(goal-round-driver, 「동일 세션 목표 이행」 담당)이 있을 수 있습니다.
• 구체적인 루프에 의존하지 않음: 소비자는 dsh-goal이라는 역량 인터페이스에만 의존하며, 특정 에이전트 루프 구현에 절대 묶이지 않습니다——이것이 바로 2장에서 다룬 「심(seam)」입니다. 역량 정의, 제공자, 소비자 세 자가 분리되어, 어느 쪽이든 단독으로 교체할 수 있습니다.

goal 패밀리는 네 개의 패키지로 구성됩니다.

goal과 「재개」의 관계: 목표를 왜 영구화해야 할까요? 에이전트가 긴 작업을 실행하는 동안 세션이 중단되거나, 복원되거나, fork될 수 있기 때문입니다. 「무엇을 달성해야 하는가」가 로그의 일부로 영구적으로 존재하는 한, 어떤 체크포인트에서 세션을 재구성하든 에이전트는 자신이 왜 여기 있는지, 다음에 어디로 가야 하는지를 압니다——이것이 「재개」의 토대입니다.

2.2 plan: 로그에 기록되는 협업 상태

packages/plan/README.zh.md 역시 한 문장으로 본질을 짚어 냅니다.

Plan mode는 에이전트별로 기록되는 협업 상태이지, 범용 모드 레지스트리나 역량 심이 아니다.

• 에이전트별로 기록: plan 상태는 특정 에이전트에 붙어 「이 에이전트가 현재 무엇을 계획하고 있고, 어느 단계까지 왔는지」를 기록합니다——전역 모드 스위치가 아니라 에이전트를 따라다니는 것입니다.
• 범용 모드 레지스트리가 아님: 전역 모드를 전환하는 레지스트리도, 교체 가능한 역량 심도 아닙니다. 그저 협업 상태입니다. 오케스트레이터(또는 사용자)와 에이전트가 이를 통해 「다음에 무엇을 할 것인지, 경계는 어디인지」를 맞춥니다.
• 로그에 기록: plan의 모든 단계(단계 경계 포함)는 세션 로그에 기록되므로, 계획의 변천 역시 근거를 갖추어 검토·복원·fork할 수 있습니다.

한 문장으로 역할 분담을 기억하세요. goal은 「왜 하는가」에 답하고, plan은 「어떻게 하고, 어디까지 했는가」에 답합니다.

3. 백그라운드 작업과 할 일: 진행 상황은 어디서 오는가

3.1 jobs: 장시간 실행 도구를 위한 백그라운드 프로토콜

packages/jobs/README.zh.md는 이 패밀리를 이렇게 설명합니다.

이 패밀리는 장시간 실행되는 도구에 대해 관찰, 취소, 대기, 완료 알림을 위한 소유자별 격리 백그라운드 작업 프로토콜을 제공한다.

• 장시간 실행되는 도구: 전체 코드베이스 스캔, 일괄 컴파일, 원격 요청…… 이런 시간이 오래 걸리는 도구 호출은 에이전트의 메인 루프를 막을 수 없으므로 백그라운드로 별냅니다.
• 소유자별 격리: 각 작업은 그것을 만든 에이전트에 속하며, 다른 에이전트가 함부로 개입할 수 없습니다——「각자 맡은 일에 책임을 지는」 규율의 보장입니다.
• 네 가지 역량: 관찰(진행 상황과 스냅샷 보기), 취소(더 이상 필요 없으면 중단), 대기(작업이 끝날 때까지 블로킹한 뒤 계속), 완료 알림(다 끝나면 능동적으로 알려 줌).

패밀리 구성: jobs/가 작업 레지스트리와 라이프사이클 규약(ctx.jobs)을 정의하고, jobs-local/이 프로세스 로컬 레지스트리 구현을 제공하며, tool-jobs/가 작업 제어와 완료 알림을 모델에 공개합니다(ctx.tools에 등록).

주목할 점은 tool-jobs가 작업 종류와 무관한(kind-agnostic) 백그라운드 잡 컨트롤러라는 것입니다. 백그라운드 bash 명령, 터미널의 terminal_send, 백그라운드 서브에이전트——이 모두가 동일한 job_output / job_list / job_kill 세 개의 도구로 읽기, 나열, 종료됩니다. 생산자는 각자 JobKindMap을 확장하여 자신의 id 네임스페이스를 선언하지만, 모델 쪽에서 보이는 것은 항상 동일한 인터페이스입니다(출처: docs/tool-catalog.zh.md).

3.2 todo: 세션 자신의 할 일 목록

packages/todo/README.zh.md는 그 위치를 이렇게 정합니다.

모델 지향 todo 역량. 하나의 에이전트 세션이 이 목록을 소유하므로 단일 제품 패키지이다. 교체 가능한 제공자 규약은 존재하지 않는다.

• 하나의 세션이 하나의 목록을 소유: todo는 전역으로 공유되지 않고, 바로 현재 이 에이전트 세션의 체크리스트입니다.
• 모델 지향: 모델은 이 항목들을 읽고, 추가하고, 체크하고, 정리할 수 있습니다.
• plan과의 역할 분담: plan은 「로드맵」(어떻게 갈 것인가), todo는 「체크리스트」(지금 어디까지 했고, 무엇이 남았는가)입니다. plan을 보며 전체 리듬을 파악하면서, todo에 체크하여 각 단계가 완료됐음을 확인할 수 있습니다.

4. 위임: 「혼자 하는 일」에서 「하나의 군단」으로

4.1 세 가지 위임 방식: spawn, fork, 외부 제공자

packages/subagent/README.zh.md는 서두에 이렇게 밝힙니다.

이 패밀리는 하나의 에이전트가 작업을 서브에이전트에 위임할 수 있게 한다. 여러 이름 붙은 제공자가 동일한 컨텍스트에서 공존할 수 있다.

이 패밀리의 핵심 패키지는 다음과 같습니다.

세 가지 방식의 암기법:

• spawn: 완전히 새로운 인스턴스. 서브에이전트는 백지에서 시작하며 부모 세션에서 무슨 일이 있었는지 모릅니다. 자기 완결적인 프롬프트를 주면 바로 일을 시작합니다. 완전히 독립적인 하위 작업(예: 「어떤 디렉터리에 어떤 파일이 있는지 조사」)에 적합합니다.
• fork: 접두사 상속. 서브에이전트는 부모 에이전트의 완료된 히스토리에서 시작하므로 자연스럽게 컨텍스트를 갖고 있습니다. 「대화를 이어 가야」 하는 연속성 작업(예: 「위의 분석을 바탕으로 구현을 계속 작성」)에 적합합니다.
• 외부 위임: 프로세스 외 에이전트. ACP 프로토콜, Codex, Claude Code 또는 DSH SDK를 통해 「진짜 남의 집 에이전트」를 시작하고, 일을 외주 맡기고, 결과를 다시 받아 옵니다.

4.2 위임 이후: 통신과 제어

위임은 「던져 놓고 손 떼기」가 아닙니다. 일련의 제어 도구가 함께 제공됩니다.

• tool-subagent/: 위임 작업(위임 개시)을 모델에 공개합니다.
• tool-subagent-control/: 자식 메시지 전송 및 열거 작업(자식에게 새 일을 맡기고, 현재 어떤 자식이 있는지 확인)을 모델에 공개합니다.
• tool-subagent-report/: 자식에서 부모로의 보고 채널(자식이 일을 마친 뒤 결과를 어떻게 돌려주는가)을 제공합니다.

또한 서브에이전트는 백그라운드 실행을 지원합니다. 서브에이전트를 백그라운드에서 천천히 일하게 두고, 그동안 자신의 일을 계속하다가, 나중에 메시지 채널을 통해 추가 작업을 덧붙일 수 있습니다——이것이 소스 문서에서 말하는 「재개 가능한 백그라운드 서브에이전트」입니다.

5. workflow: 스크립트 구동 멀티 에이전트 오케스트레이션

5.1 모델이 작성하는 오케스트레이션 워크플로

packages/workflow/README.zh.md는 한 문장으로 요약합니다.

이 패밀리는 subagent를 통해 모델이 작성한 오케스트레이션 워크플로를 실행하고, 범용 도구와 고정 정책 도구를 모델에 공개한다.

뜯어 보면 세 가지 키워드가 있습니다.

• 모델이 작성: 오케스트레이션 스크립트는 사람이 하드코딩해 둔 흐름이 아니라, 모델(또는 여러분)이 적은 오케스트레이션 로직입니다——「먼저 무엇을 하고, 다음에 무엇을 하고, 무엇을 병렬로 할 수 있는지」를 시스템에 알려 줍니다.
• subagent를 통해 실행: 스크립트 속 「일하는 사람」은 모두 서브에이전트입니다. 스크립트는 단계(예: 「조사」「코딩」「검토」)를 정의할 수 있고, 같은 단계 안에서 여러 서브에이전트가 병렬로 진행되며 서로를 블로킹하지 않습니다. 이것이 바로 「군단」의 모습입니다.
• 범용 도구와 고정 정책 도구: 스크립트는 범용 오케스트레이션 역량(에이전트 시작, 작업 묶음의 파이프라인 처리, 여러 병렬 작업 결과의 취합 등)과 함께 고정 정책 도구도 사용할 수 있습니다——예를 들어 tool-ralph/: 매번 완전히 새로운 에이전트로 고정 흐름을 실행하는 Ralph 워크플로로, 「매 라운드 이전 기억을 갖고 오지 않고 공유 작업 공간에만 의존하는」 반복형 작업에 적합합니다.

기술적 세부 사항: 워크플로 스크립트는 독립된 worker thread에서 실행되어 호스트 이벤트 루프와 격리됩니다. 다만 리포지토리 문서가 명확히 강조하듯, 이는 보안 경계를 구성하지 않습니다——실행 방식상의 격리일 뿐이며, 보안 경계는 여전히 샌드박스와 승인이 담당합니다(제4강 참조).

패밀리 구성: workflow/가 워크플로 실행과 라이프사이클 이벤트(ctx.workflowEngine)를 정의하고, workflow-worker-thread/가 스레드에서 스크립트를 실행하며, tool-workflow/가 범용 워크플로 실행을 모델에 공개하고, tool-ralph/가 고정 Ralph 워크플로를 공개합니다.

5.2 subagent와 workflow의 역할 분담

• subagent = 단일 「인력」: 하나의 하위 작업을 맡아 끝나면 결과를 넘깁니다. 일대일 위임에 적합합니다.
• workflow = 전체 「프로젝트 관리 스크립트」: 많은 인력을 파이프라인으로 배열하고 순서와 병렬을 결정하는 역할입니다. 일대다, 다단계 오케스트레이션에 적합합니다.
• 실무에서는 둘을 겹쳐 쓰는 경우가 많습니다. workflow 스크립트 안에서 서브에이전트를 시작하는 호출은 낮은 수준에서 subagent의 제공자를 거칩니다——workflow가 총지휘관이고, subagent가 병사입니다.

6. 앞의 두 장과의 관계: 두 줄기를 잇기

• 1장(DSH 첫걸음): 에이전트 프레임워크의 기본 사상 강의에서 「멀티 에이전트 오케스트레이션」을 다뤘습니다——하나의 작업을 여러 에이전트에 나누어 하나는 조사, 하나는 코드 작성, 하나는 검토를 담당하고 프레임워크가 이들을 편성한다는 이야기입니다. 이번 강의는 그 사상을 DSH에 실제로 존재하는 여섯 개의 역량 패밀리——goal, plan, tasks, todo, subagent, workflow——로 구체화하는 것입니다. 1장이 「비전」이라면, 이번 강의는 「부품 목록」입니다.
• 2장(논문 정독): Cordis 논문의 핵심은 「컴포넌트」와 시공간적 합성 가능성——시스템의 모든 것이 합성 가능하고 교체 가능한 컴포넌트라는 것입니다. 이번 강의의 각 역량 패밀리는 바로 컴포넌트로서, ctx 컨텍스트의 각 키에 등록되고 「역량 정의 / 제공자 / 소비자」의 심 구조를 따릅니다. 가장 전형적인 예가 subagent입니다. 여러 이름 붙은 제공자(spawn, fork, ACP, Codex, Claude Code, dsh-sdk)가 같은 ctx.subagents 키 아래에서 공존하며, 위임 방식을 바꾸고 싶으면 제공자를 바꾸면 됩니다——이것이 바로 「콘센트 갈아 끼우기」식 교체 가능성입니다.

핵심 포인트 복습

이번 강의는 정보량이 적지 않지만, 다음 다섯 문장만 기억하면 충분합니다.

1. 목표 goal: 영구화된 동일 세션 목표로, 세션 로그의 일부입니다——이것이 있어야 「재개」가 가능하며, 소비자는 구체적인 에이전트 루프에 의존하지 않습니다.
2. 계획 plan: 에이전트별로 기록되는 협업 상태이지 전역 모드 스위치가 아닙니다. 모든 단계가 로그에 기록되어 대조·복원할 수 있습니다.
3. 백그라운드 작업 tasks + 할 일 todo: tasks는 장시간 실행 도구에 소유자별 격리 프로토콜(관찰, 취소, 대기, 완료 알림)을 제공하고, todo는 세션 자신이 소유하는 체크 가능한 목록입니다.
4. 위임 subagent: spawn은 완전히 새로운 인스턴스, fork는 부모 세션 히스토리를 상속, 외부 제공자(ACP, Codex, Claude Code, dsh-sdk)는 프로세스 외 에이전트에 일을 외주합니다. 위임 후에는 제어 도구와 보고 채널도 있습니다.
5. 워크플로 workflow: 모델이 작성하는 오케스트레이션 스크립트로, subagent를 통해 단계별로 병렬 실행되고 고정 정책 도구(Ralph)도 갖추고 있습니다——이 모두가 ctx에 등록된 교체 가능한 컴포넌트입니다.

🚀 다음 강의(제8강)에서는 「자기 진화: 에이전트가 스스로를 개조하다」를 다룹니다. 이번 강의의 「심형 컴포넌트 + 교체 가능한 제공자」가 있기에 에이전트가 실행 중에 자신의 역량을 검사하고, 마운트하고, 언마운트할 수 있다는 것을 알게 될 것입니다——군단을 지휘하는 것에서, 자신의 장비를 개조하는 것으로.