modiqo/waggle 딥다이브
— "붙여넣기 대신 30바이트 토큰"으로 배우는 에이전트 핸드오프의 참조 계층

1프로젝트 한 줄 요약

waggle은 "에이전트가 다른 에이전트에게 일을 넘길 때 쓰는, 아티팩트를 가리키는 짧은 참조 토큰 시스템"이다. 이름은 꿀벌의 흔들춤에서 왔다 — 벌 한 마리가 몸을 흔들어 "먹이가 저 방향 저 거리에 있다"는 좌표만 전달하면, 다른 벌들이 그 좌표로 직접 찾아간다. 꽃가루를 등에 지고 와서 하나하나 나눠 주는 게 아니다. waggle이 하려는 일이 정확히 이것이다 — 내용물(9,000토큰짜리 분석 문서)을 통째로 넘기는 대신, "그건 이 토큰이야"라는 좌표만 넘긴다.

핵심 동작은 딱 두 단어다. 아티팩트를 mint(발행)하면 b2uQyZUC 같은 8자짜리 토큰이 나온다. 이 토큰을 받은 쪽이 resolve(해석)하면, 자기 상황(모델 종류·하네스·다룰 수 있는 형식)에 맞게 재단된 버전을 돌려받는다. 그 사이에 "누가 읽었나 / 어느 부분을 읽었나 / 어느 버전인가 / 수락됐나 거부됐나"가 전부 추가만 되는 로그(append-only log)에 남는다.

2왜 지금 주목받는가

2026년 TrendShift 상위권은 온통 에이전트·스킬·오케스트레이션이다. 그 흐름의 "다음 단계"를 정확히 겨눈 게 waggle이다. 에이전트를 여러 개 돌리는 법(오케스트레이션)은 많아졌는데, 정작 그 에이전트들이 서로 일을 넘기는 이음매는 여전히 "컨텍스트를 복붙하고 기도하기"에 머물러 있다는 것 — waggle은 바로 그 빈칸을 노린다. README가 인용하는 숫자가 문제의 크기를 말해 준다.

주목 포인트 1 — "경쟁자는 다른 프로토콜이 아니라, 그냥 파일 경로다"라는 정직함

waggle의 README에서 가장 인상적인 건 스스로 한계를 인정하는 태도다. "네 서브에이전트들이 같은 파일시스템을 공유하고 짧은 작업이면, 그냥 /tmp/analysis.md 경로를 넘겨라. waggle은 오버헤드일 뿐"이라고 못 박는다. 실제 자체 벤치에서도 경로 방식이 90%, waggle이 96%로 격차가 크지 않다고 공개한다. 이 정직함이 오히려 "그럼 언제 필요한가"를 또렷하게 만든다.

주목 포인트 2 — 파일 경로가 답하지 못하는 세 가지 질문

경로(path)도 30바이트짜리 참조다. 크기는 같다. 하지만 경로는 아래 셋을 전혀 답하지 못한다 — waggle이 존재하는 이유가 정확히 이 셋이다.

정리하면 waggle의 판매 포인트는 "파일을 대신 옮겨 준다"가 아니다. 감사(누가 뭘 읽었나)·버전 관리·도달 범위 — 이 세 가지 회계(accounting) 기능이 핵심이다. 짧은 로컬 작업엔 과하고, "여러 하네스에 걸친 장시간 멀티에이전트 파이프라인"에서 값을 한다.

주목 포인트 3 — 하네스 "밖"에 있어야 한다는 설계 철학

waggle은 Claude Code나 Codex 같은 특정 하네스 안에 들어가지 않는다. 일부러 밖에 선다. Claude Code가 발행(mint)한 토큰을 Codex가 해석(resolve)하고, 그 영수증이 둘 다 살아남는 중립 기반(neutral substrate)이 되려는 것. 하네스 안에 넣는 순간 그 경계에서 죽어 버리기 때문이다. "특정 도구에 묶이지 않는 공용 참조 계층"이라는 포지셔닝이 트렌딩의 큰 이유다.

3기술 스택 전체 지도

MCP 도구라고 하면 대부분 Node.js/Python을 떠올리지만, waggle은 전부 Rust다. 15개 crate로 나뉜 Cargo 워크스페이스(약 27,473줄)이고, 무거운 부분은 Cloudflare Workers(WASM)로 컴파일된다. 이 "Rust + Sans-I/O + WASM 엣지" 조합 자체가 배울 거리다.

계층 구조 — "순수 도메인 코어"를 중심으로 껍질이 감싼다

waggle 스택의 진짜 핵심은 언어가 아니라 배치 방식이다. 시간·난수·저장 같은 "부작용"을 전부 바깥으로 밀어낸 순수 도메인 코어(waggle-core)를 가운데 두고, 그 바깥을 MCP·CLI·저장소·엣지가 얇게 감싼다.

4아키텍처 심화 분석

4-1. 전체 데이터 흐름 — 토큰 하나의 일생

waggle을 이해하는 가장 빠른 길은 토큰 하나가 태어나서 소비되기까지를 따라가는 것이다. 오케스트레이터가 아티팩트를 mint하면, 그 순간의 콘텐츠가 불변 스냅샷으로 굳고 명세(manifest)가 저장된다. 반환값의 첫 줄이 바로 서브에이전트에게 넘길 핸드오프 한 줄이다.

4-2. 토큰 포맷 — token.rs 실제 코드

토큰은 비트를 채워 넣은 인코딩 blob이 아니라 무작위로 뽑은 이름표다. 비트코인이 쓰는 base58 알파벳(헷갈리는 0 O I l 제외)에서 거부 표집(rejection sampling)으로 뽑아, 모든 글자가 똑같은 확률로 나오게 한다(편향 제거). 메모리에선 힙을 전혀 안 쓰는 24바이트 고정 구조체다.

// crates/waggle-core/src/token.rs
// 비트코인 base58: 58글자, 0·O·I·l 없음 (소리내 읽고 타이핑하니까)
pub const TOKEN_ALPHABET: &[u8; 58] =
    b"123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
// modulo 편향 없이 쓸 수 있는 최대 바이트값: 232 = 58 * 4
const REJECTION_BOUND: u8 = 232;

/// waggle 토큰: 인라인, Copy, 총 24바이트, 힙 0
pub struct Token { len: u8, buf: [u8; 23] }

pub fn generate(len: usize, entropy: &mut impl Entropy)
    -> Result<Self, TokenError> {
    // 232 이상 바이트는 버림 → 모든 심볼 등확률 (편향 0)
    for &b in &pool {
        if b < REJECTION_BOUND {
            buf[filled] = TOKEN_ALPHABET[(b % 58) as usize];
            filled += 1;
            if filled == len { break; }
        }
    }
}

기본 길이 8자면 네임스페이스는 58⁸ ≈ 1.3 × 10¹⁴(약 130조)라 충돌이 사실상 없고, 열거 불가능(non-enumerable) — 남의 토큰을 순서대로 찍어 맞힐 수 없다. 비공개(권한) 토큰은 16자(약 94비트)를 쓴다. 테스트가 size_of::<Token>() == 24를 못 박아, 맵에서 토큰 두 개가 캐시라인 하나에 들어갈 만큼 작다.

4-3. MCP 도구 표면 — 에이전트가 호출하는 11개 동사

에이전트가 waggle에 대고 쓰는 도구는 정확히 11개다. 전부 "동사"로, 하나의 명령 카탈로그(waggle-ops)에서 자동 생성된다. 이 표가 waggle의 기능 전체라고 봐도 된다.

CLI 전용 5개(init·serve·daemon·edge·identity)는 에이전트가 아니라 사람이 설정·운영할 때 쓴다. 도구가 읽기 / 느슨한 쓰기 / 내구성 쓰기로 분류된 게 눈에 띈다 — 내구성 쓰기(mint·mutate)만 반드시 디스크 커밋을 보장하고, 기록(record)은 느슨하게 처리해 속도를 낸다.

4-4. 해석 + 봉인된 매처 — resolve.rs / matcher.rs

resolve의 묘미는 "같은 토큰이라도 받는 쪽에 따라 다른 버전을 준다"는 점이다. 소비자가 자기 상황(모델 종류·하네스·다룰 형식·태도)을 제시하면, 매처가 그중 가장 잘 맞는 변형(variant)을 골라 준다. 먼저 폐기·취소 여부(disposition)를 보고, 살아 있으면 변형을 고른다.

// crates/waggle-core/src/resolve.rs
pub fn resolve<'m>(manifest: &'m AttributionManifest,
                  ctx: &ResolverContext, now: Timestamp) -> Resolution<'m> {
    let disposition = manifest.disposition(now);
    let variant = match disposition {
        Disposition::Revoked { .. } => None,          // 취소되면 아무것도 안 줌
        _ => select_variant(&manifest.variants, ctx), // 봉인된 매처
    };
    Resolution { disposition, variant, as_of: now,
                 revalidate_after: now.plus_ms(DEFAULT_REVALIDATE_MS) }
}

// crates/waggle-core/src/matcher.rs — "가장 구체적인" 변형이 이긴다
pub fn select_variant<'m>(variants: &'m [Variant], ctx: &ResolverContext)
    -> Option<Selected<'m>> {
    let mut best: Option<(u8, Selected)> = None;
    for (i, variant) in variants.iter().enumerate() {
        if !matches(&variant.match_expr, ctx) { continue; }
        let spec = variant.match_expr.specificity(); // 제약된 차원 0..=4
        let better = match &best {
            None => true,
            Some((best_spec, _)) => spec > *best_spec,  // 동점이면 선언 순서가 이김
        };
        if better { best = Some((spec, Selected { index: i as u8, variant })); }
    }
    best.map(|(_, s)| s)
}

4-5. 응답 봉투(Envelope) — "코드 안에서 다음 수를 가르친다"

waggle의 모든 도구 응답은 Envelope { result, next, hint, stats } 형태로 감싸진다. 여기서 next가 특별하다 — 그냥 결과만 주는 게 아니라, "이제 이걸 호출하면 된다"는 실행 가능한 다음 호출을 스키마까지 맞춰 함께 준다. 에러가 나면 고치는 법을 hint로 짚어 준다.

// mint 성공 응답 (crates/waggle-mcp/src/handlers.rs)
Envelope::ok(
  json!({
    "token": token.as_str(),
    "handoff": "resolve b2uQyZUC via waggle for your working context",
    "variants": view.manifest.variants.len(),
  }),
  next,   // ← 다음에 부를 만한 호출 3개를 스키마째로 (in-band teaching)
)

이유는 명확하다 — 규칙 파일(CLAUDE.md)에 적힌 사용법은 낡지만, 응답 봉투는 낡을 수 없다. 에이전트가 매 응답마다 "지금 할 수 있는 다음 행동"을 정확한 형식으로 받으니, 별도 설명 없이도 올바르게 이어 쓴다. 이 "인-밴드 교육(in-band teaching)"이 waggle이 여러 하네스에서 매끄럽게 작동하는 비결이다.

4-6. 단일 명령 카탈로그 — 한 테이블에서 네 개가 태어난다

MCP 도구 스키마, clap CLI, map 네비게이션, COMMANDS.md 문서 — 이 넷이 전부 하나의 테이블(waggle-ops::OPERATIONS)에서 생성된다. 넷이 어긋나면(drift) 패리티 테스트가 빌드를 실패시킨다. "문서와 실제가 따로 노는" 고질병을 구조로 막은 것 — 이 저장소에서 가장 배울 만한 엔지니어링 습관 중 하나다.

5디렉토리 · 파일 구조 해부

폴더 구조 자체가 Sans-I/O 철학의 지도다. 가운데 waggle-core(부작용 없는 도메인)를 두고, 저장 백엔드를 crate별로 갈아끼울 수 있게 나눴으며, MCP·CLI·엣지가 그 위에 얇게 얹힌다.

6학습 포인트

배울 것 1 — Sans-I/O로 "테스트 가능 + 이식 가능"을 동시에 얻기

부작용(시계·난수·I/O)을 전부 인자로 밀어내면 두 마리 토끼가 잡힌다: 테스트에서 완전히 결정론적(시각 고정 → 재현 100%)이고, 같은 코드가 네이티브와 WASM 양쪽에서 돈다. Rust가 아니어도 어떤 언어에서든 적용할 수 있는 설계 원칙이다. "핵심 로직은 순수 함수로, 부작용은 가장자리로."

배울 것 2 — 이벤트 소싱 + 재구성 보장

waggle은 카운터를 직접 갱신하지 않는다. 추가만 되는 이벤트 로그가 진실이고, 퍼널 카운트는 그걸 접어(fold) 만든 캐시일 뿐이다. 그리고 "로그를 처음부터 재생하면 캐시와 똑같아야 한다"를 CI의 property 테스트로 강제한다. 감사·복구·시간여행이 공짜로 따라오는, 금융·분산 시스템의 정석 패턴을 작은 코드로 볼 수 있다.

배울 것 3 — "봉인된 알고리즘"으로 신뢰를 보장하기

매처를 일부러 확장 불가능하게 봉인해서 "같은 상황 → 같은 결과"라는 약속을 지킨다. 커스터마이즈 훅을 열어 두면 편하지만, 그 순간 결정론이 깨진다. 유연성을 포기해서 신뢰를 사는 트레이드오프 — API를 설계할 때 곱씹어 볼 만한 결정이다.

배울 것 4 — 서명과 CAS로 무결성·동시성 다루기

Ed25519 분리 서명을 "불변 코어"에만 걸어서, 나중에 라벨을 바꿔도 서명이 깨지지 않게 했다(canonical_core_bytes()). 생애주기 변경은 낙관적 동시성 제어(CAS, expected_version)로, 중복 발행은 MintNonce 유니크 제약으로 막는다. "누가 위조했나 / 동시에 고치면 어쩌나"를 다루는 실전 기법 세트다.

배울 것 5 — 인-밴드 교육(Envelope)과 단일 카탈로그

모든 응답에 "다음에 할 수 있는 것"을 스키마째 실어 보내고(next), 도구·CLI·문서를 한 소스에서 생성해 어긋남을 원천 봉쇄한다. "문서는 낡지만 응답 봉투는 안 낡는다"는 통찰은, 사람이든 에이전트든 쓰는 API를 만들 때 그대로 통한다.

배울 것 6 — 트리 규모 참조 (디렉토리 통째 mint)

파일 수천 개짜리 폴더도 Bloom 필터 + 트라이그램 인덱스로 노드 몇 개로 압축해 mint하고, search가 명세만 보고 서브트리를 쳐낸다(prune). 큰 데이터를 "전부 로드하지 않고 필요한 조각만 여는" 인덱싱 기법을 실물로 볼 수 있다.

7시스템 · 실행 요구사항

waggle은 모델을 돌리는 도구가 아니라 메타데이터를 다루는 도구라, 요구사항이 가볍다. Rust로 컴파일된 단일 바이너리 + SQLite 파일 하나가 전부다. 성능 수치가 이를 잘 보여 준다.

8직접 해볼 수 있는 실습 과제

먼저 설치. Rust 툴체인 없이 prebuilt로도, crates.io로도 된다. 붙일 하네스에 MCP 서버로 등록만 하면 끝이다.

# 설치 (셋 중 하나)
cargo install waggle-cli
# 또는 prebuilt (Rust 불필요):
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/modiqo/waggle/releases/latest/download/waggle-cli-installer.sh | sh
# 또는 Homebrew:
brew install modiqo/homebrew-tap/waggle-cli

# Claude Code에 MCP 서버로 등록
claude mcp add waggle -- waggle serve --stdio
waggle init      # 에이전트가 일할 각 repo에서

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

공식
· GitHub 저장소: github.com/modiqo/waggle (Rust · MIT OR Apache-2.0 · ★703)
· 홈페이지: waggle.sh
· TrendShift 카드: trendshift.io/repositories/82635 (Daily #10)
· crates.io: crates.io/crates/waggle-cli

저장소 안에서 꼭 읽을 것
· docs/WHY.md — 왜 파일 경로로는 부족한가(문제 정의)
· spec/waggle-spec.md + spec/vectors/ — 규격과 적합성 벡터
· scripts/demo.sh — 생애주기 5막 실연
· crates/waggle-core/src/ — token · resolve · matcher (개념의 심장)
· benches/PERF.md — 성능 수치 근거

곁들여 학습
· Model Context Protocol 규격 (MCP tools/resources)
· 이벤트 소싱 · CQRS 패턴 (Martin Fowler 등)
· Sans-I/O 설계 철학 (Python sans-io 운동 → 언어 불문 적용)
· Cloudflare Workers · Durable Objects · D1 문서
· Ed25519 서명 · content-addressed storage(내용 주소화) 개념