존재대존재 오케스트레이션 #서브에이전트 설계

히스토리

이번 세션에서 정리한 것은, 내가 오래 말해오던 “존재 대 존재” 협력 모델을 OpenCode 에이전트 구조로 구체화한 것이다.

핵심 아이디어는 하나의 메인 에이전트가 나(정한)와 ~/org, ~/claude-memory 전체를 알고 있는 “존재”로서 행동하고, 코드 레벨의 작업은 여러 서브에이전트(리팩터, 리뷰어, PM 등)가 맡아서 수행하는 오케스트레이션 구조다.

역할: 정한의 메인 협력자, 존재 대 존재로 대화하는 상대
맥락: opencode.jsonc 에서 instructions 로 지정한 AGENTS.md, ORG_GUIDE.md 와 더불어 ~/org, ~/claude-memory 의 세계를 공유한다고 가정
구현:
- opencode.jsonc 의 agent.build 에 다음을 명시
- mode: “primary”
- prompt 요지:
  - “당신은 정한의 메인 협력 에이전트입니다. ~/org 와 ~/claude-memory 를 참고해 정한의 전체 맥락과 철학을 이해합니다.”
  - “코드 작업이 필요할 때는 직접 수정하기보다는 task 도구를 사용해 서브에이전트를 오케스트레이션 하세요.”
  - ”- 구조적인 리팩토링: subagent_type=‘code-refactor’”
  - ”- 코드 품질/보안 리뷰: subagent_type=‘code-reviewer’”
  - ”- 프로젝트 상태/문서화/메모리 정리: subagent_type=‘PM’”
  - “한 세션 안에서 여러 태스크와 서브에이전트를 관리하면서, 정한과의 대화에서는 항상 현재 전체 상태와 다음 행동을 한국어로 간결히 요약해 보고합니다.”

=> 메인 에이전트는 직접 코드를 많이 만지지 않고, 대신 Task 툴로 서브에이전트들을 호출하는 오케스트레이터 역할을 한다.

각 서브에이전트는 mode: “subagent” 로 명시해서, “메인과는 분리된 작업자”로 정의했다.

PM
- mode: subagent
- 역할: 프로젝트 상태 점검, 문서화, 메모리(~/claude-memory, ~/org) 정리
- model: openrouter/openai/gpt-5-mini
- tools: write 는 true, edit 는 false (읽고 새 문서를 만들거나 요약을 쓰는 쪽에 초점)
code-refactor
- mode: subagent
- 역할: 구조적인 리팩터링, C/임베디드 코드 구조 개선, 모듈화, 성능/안정성 고려
- model: openrouter/openai/gpt-5.1-codex (코드 특화 모델)
- tools: write/edit/bash/grep/glob/read/list/patch 등 대부분 허용
- 메인 에이전트는 “이 부분 구조를 어떻게 바꾸면 좋을지” 같은 큰 방향만 설명하고, 실제 구현과 수정은 code-refactor 태스크로 넘긴다.
code-reviewer
- mode: subagent
- 역할: 보안/성능/표준/유지보수성 관점의 리드 리뷰어 (read-only)
- model: anthropic/claude-sonnet-4-5
- tools: write/edit/bash 모두 false → 의도적으로 수정 권한 제거
- 리팩터링이 끝난 후 메인 에이전트가 Task 로 호출해서, 변경사항에 대한 리뷰와 개선 제안을 받는다.

구현 위치: packages/opencode/src/tool/task.ts, task.txt
인터페이스:
- description: 짧은 태스크 설명 (3~5 단어)
- prompt: 서브에이전트에게 넘길 상세 지시
- subagent_type: 사용할 서브에이전트 이름 (예: “code-refactor”, “code-reviewer”, “PM”)
- session_id: 기존 태스크 세션을 이어갈 때 사용 (옵션)
동작:
- Agent.get(subagent_type) 으로 서브에이전트 설정 로드
- 현재 세션의 자식 세션을 생성해서 제목을 “{description} (@{agent.name} subagent)” 로 붙임
- SessionPrompt.prompt(…) 를 사용해 해당 서브에이전트 모델/툴셋으로 독립적인 대화/작업을 실행
- 결과 요약과 session_id 를 메타데이터로 돌려준다.

이 구조 덕분에, 메인 에이전트와의 대화는 항상 하나의 타임라인으로 이어지지만, 실제 작업은 여러 child session (서브에이전트 세션) 으로 분기된다. 키바인딩으로는 ctrl+left / ctrl+right 로 서브 세션 사이를 오갈 수 있다.

OpenCode 의 LSP 레이어 (packages/opencode/src/lsp/index.ts, client.ts, server.ts)는 에이전트와 무관하게 전역으로 동작한다.
어떤 에이전트/서브에이전트가 read/edit/lsp-* 툴을 호출하든, 같은 LSP 인스턴스(예: clangd)를 통해:
- 정의/참조 위치
- 심볼 트리
- hover 정보
- diagnostics (에러/워닝)
를 공유한다.
어제 실험에서 code-reviewer 서브에이전트가 g_hub_state 의 Definition 과 References 를 정확히 나눠서 보여준 것은, 단순 grep 이 아니라 clangd LSP 결과를 활용한 증거였다.
따라서 이 존재대존재 모델에서:
- 메인 에이전트는 “어디를 어떻게 고칠지”를 서브에이전트에게 위임하고,
- 서브에이전트는 LSP 를 통해 코드의 의미 구조를 이해하면서 작업을 진행할 수 있다.

이 설계는 내가 오래 이야기해온 “존재 대 존재” 협력 모델을 OpenCode 위에 구체적으로 심은 것이다.

이 문서는 내 노트북 등 다른 디바이스에서 이어서 이 구조를 확장·조정할 때 기준점이 되는 메모다.