점진적 공개: 에이전트 시스템을 들여다보는 CLI 창

이 글의 수치는 게시 시점(2026년 1월) 기준입니다. 최신 수치는 팀 페이지를 참고하세요.

에이전트 시스템은 설계상 불투명합니다. 결정을 내리고, 도구를 호출하며, 수십 명의 전문가에 걸쳐 작업을 조율합니다. 하지만 무언가 잘못되었을 때 — 혹은 그저 무슨 일이 일어나고 있는지 이해하고 싶을 때 — 어디를 봐야 할까요?

답은 점진적 공개입니다. 정확히 필요한 만큼의 복잡성을, 정확히 필요한 시점에 드러내는 계층화된 인터페이스입니다.

불투명성 문제

현대의 에이전트 오케스트레이션 시스템에는 다음과 같은 것들이 있을 수 있습니다.

• 저마다 다른 역량을 가진 40개 이상의 전문 에이전트
• 내부 자동화와 벤더 통합에 걸친 700개 이상의 스킬
• 행동을 형성하는 470개 이상의 아키텍처 결정
• 외부 역량을 제공하는 수십 개의 MCP 도구 서버

이 복잡성은 의도적입니다. 에이전트는 좋은 결정을 내리기 위해 도메인 지식, 코드 인텔리전스, 데이터베이스 스키마 같은 풍부한 컨텍스트에 접근해야 합니다. 하지만 그 풍부함이 곧 가시성 문제를 만들어냅니다.

어떤 에이전트가 데이터베이스 마이그레이션을 처리하는지 어떻게 알 수 있을까요? 어떤 결정이 검색 시스템의 랭킹 동작을 형성했을까요? 아키텍처 자문 에이전트는 어떤 도구에 접근할 수 있을까요?

구조화된 접근 수단이 없다면, 여러분은 소스 코드를 읽거나 문서가 최신이기를 바라는 수밖에 없습니다.

아키텍처로서의 점진적 공개

점진적 공개는 단순한 UI 패턴이 아닙니다. 아키텍처적 원칙입니다. 정보를 계층으로 조직하되, 각 계층이 이전보다 더 깊어지도록 하여, 사용자가 자신의 질문에 답을 얻는 수준에서 멈출 수 있게 합니다.

에이전트 시스템에서 이는 점점 더 깊어지는 CLI 명령들로 옮겨집니다.

단계	명령	답하는 질문
1	orkestra system status	모든 것이 건강한가?
2	orkestra agents list	어떤 에이전트가 존재하는가?
3	orkestra agents info <name>	이 에이전트는 무엇을 하는가?
4	orkestra decisions search	왜 이런 방식으로 동작하는가?
5	Maguyva MCP 도구	코드를 보여줘

각 단계는 자연스러운 후속 질문에 답합니다. 곧바로 5단계로 뛰어넘어야 할 필요는 거의 없습니다.

1단계: 시스템 건강 상태

첫 번째 질문은 항상 이것입니다. 모든 것이 작동하고 있는가?

$ orkestra system status

on
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

하나의 명령. 네 개의 숫자. 시스템이 설정되어 있고 레지스트리가 채워져 있는지 알기에 충분합니다.

에이전트 수가 예기치 않게 줄어들거나 스킬이 로드에 실패하면, 여기서 가장 먼저 보게 됩니다. 로그를 뒤질 필요가 없습니다.

2단계: 에이전트 인벤토리

시스템이 건강하다는 것을 확인했다면, 다음 질문은 이것입니다. 무엇을 쓸 수 있는가?

$ orkestra agents list

이는 구조화된 데이터를 반환합니다. 에이전트 이름, 설명, 모델 선호도, 도메인 커버리지입니다. 출력은 기본적으로 JSON이라서 필터링을 위해 jq로 파이프하기 쉽습니다.

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

데이터베이스 작업을 처리하는 에이전트가 필요하신가요? search 명령이 범위를 좁혀줍니다.

$ orkestra agents search "database"

이는 이름, 설명, 역량을 훑습니다. 40개의 에이전트 정의를 읽지 않고도 알맞은 전문가를 찾을 수 있습니다.

3단계: 에이전트 심층 탐구

관련 있어 보이는 에이전트를 찾았나요? info 명령이 모든 것을 드러내 줍니다.

$ orkestra agents info architecture-advisor

출력에는 다음이 포함됩니다.

• 메타데이터: 이름, 카테고리, 모델 선호도, 설명
• 도메인: 이 에이전트가 다루는 지식 영역
• 아이덴티티: 성격 특성(설계자, 전략가, 지식 설계자)
• 도구 가이드: 컨텍스트에 주입되는 도구 문서
• 도구: 이 에이전트가 접근할 수 있는 MCP 도구의 전체 목록

실제로 보이는 모습의 예시입니다.

on
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

이는 이 에이전트가 정확히 무엇을 할 수 있는지 알려줍니다. 소스 코드가 필요 없습니다.

4단계: 결정의 고고학

에이전트는 문서화된 결정에 따라 행동합니다. 무언가가 특정한 방식으로 동작하는 이유를 이해해야 할 때, 결정 레지스트리가 단일 진실 공급원입니다.

$ orkestra decisions search "agent"

이는 일치하는 아키텍처 결정을 반환합니다.

on
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

각 결정은 완전한 출처를 갖습니다. 언제 만들어졌는지, 왜, 어떤 트레이드오프가 고려되었는지, 어떤 커밋이 이를 구현했는지입니다.

$ orkestra decisions info DEC-SR-049

on
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

이는 수동으로 유지되는 것이 아니라 커밋에서 채굴되기 때문에 항상 최신 상태로 유지되는 아키텍처 문서입니다.

5단계: 직접적인 코드 인텔리전스

메타데이터가 아니라 실제 구현을 봐야 할 때, Maguyva의 MCP 도구가 직접적인 접근을 제공합니다.

에이전트 세션 안에서:

mcp__maguyva__intelligent_search
  query: "agent context loading"

이는 관련 코드를 찾기 위해 시맨틱, 텍스트, AST 검색을 자동으로 라우팅합니다. 특정 심볼의 경우:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

의존성 분석의 경우:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

이것들은 단순한 grep 대체품이 아닙니다. 그래프를 인식하고, 시맨틱하게 인덱싱되어 있으며, 에이전트 자체를 구동하는 것과 동일한 코드 인텔리전스와 통합되어 있습니다.

레지스트리 전반의 통합 검색

때로는 어떤 레지스트리에 답이 있는지 모를 수 있습니다. 통합 검색은 모든 것을 아우릅니다.

$ orkestra search "database" --summary

on
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

다섯 개의 레지스트리에서 254건이 일치했습니다. 요약은 어디를 더 깊이 파고들어야 할지 알려줍니다. 세부 결과를 위해서는 --summary을 제거하거나, 출력을 관리 가능하게 유지하려면 --limit 5을 추가하세요.

이것이 중요한 이유

점진적 공개는 단순한 편의성의 문제가 아닙니다. 복잡한 시스템과 상호작용하는 방식 자체를 바꿉니다.

디버깅이 다루기 쉬워집니다. 에이전트가 예상치 못한 결정을 내리면, 로그를 grep하지 않습니다. 그 에이전트가 어떤 도구에 접근할 수 있는지(agents info), 어떤 결정이 그 행동을 형성하는지(decisions search) 확인하고, 필요하다면 구현을 추적합니다(intelligent_search).

온보딩이 빨라집니다. 새로운 팀원은 전체 코드베이스를 읽을 필요가 없습니다. system status로 시작해, agents list로 탐색하고, 이해되지 않는 무언가에 부딪혔을 때만 더 깊이 들어갑니다.

문서가 최신 상태를 유지합니다. CLI가 에이전트를 설정하는 것과 동일한 레지스트리에서 읽어오기 때문에, 출력은 항상 정확합니다. 문서가 말하는 것과 시스템이 하는 것 사이에 표류가 없습니다.

인터페이스로서의 CLI

웹 대시보드를 만들 수도 있었습니다. 방대한 문서를 쓸 수도 있었습니다. 대신 우리는 단일 진실 공급원에서 읽어오는 CLI를 만들었습니다.

CLI에는 다음과 같은 장점이 있습니다.

• 조합 가능: jq을 통해 출력을 파이프하고, 스크립트와 통합할 수 있습니다
• 스크립트화 가능: 점검을 자동화하고, 보고서를 생성합니다
• 빠름: 페이지 로딩도, 인증 절차도 없습니다
• 정확함: 캐시된 표현이 아니라 실제 설정을 읽습니다

미학보다 정확성이 중요한 시스템에서는 CLI가 이깁니다.

여러분만의 점진적 공개 만들기

에이전트 시스템을 구축하고 있다면, 사용자가 이를 어떻게 들여다볼지 고려하세요.

1. 건강 체크로 시작하세요. 모든 것이 작동하는지 알려주는 하나의 명령.
2. 인벤토리 뷰를 제공하세요. 무엇을 하는지 설명하기 전에 무엇이 존재하는지 나열하세요.
3. 목표가 명확한 쿼리를 가능하게 하세요. 규모가 커지면 검색이 훑어보기를 이깁니다.
4. 출처를 노출하세요. 사용자가 결정을 그 기원까지 추적할 수 있게 하세요.
5. 코드 인텔리전스와 연결하세요. 결국 사용자는 구현을 봐야 합니다.

각 계층은 후속 질문에 답합니다. 빈도순으로 만드세요. 대부분의 사용자는 2단계나 3단계에서 멈춥니다. 파워 유저만 5단계에 도달합니다.

목표는 모든 것을 노출하는 것이 아닙니다. 정확히 필요한 것을, 정확히 필요한 시점에 노출하는 것입니다. 그것이 에이전트 아키텍처에 적용된 점진적 공개입니다.