Maguyva 블로그

따라다니는 컨텍스트

Mon, 07 Sep 2026 00:00:00 GMT

Cursor의 인덱서는 Cursor 안에서는 훌륭합니다. 탭 완성, 인라인 편집, 채팅, 그리고 그 창 안의 에이전트는 이미 Cursor가 열린 워크스페이스를 위해 운영하는 프로젝트 인덱스 위에 앉아 있습니다. Cursor가 여러분이 코드를 쓰는 유일한 표면이고, 그 인덱스가 이미 올바른 파일을 찾아준다면, 거기 머무르세요. 그것이 정직한 “그대로 있기” 사례이며, 이 페이지의 첫 문장이 될 자격이 있습니다.

이 글은 흔한 한 주의 나머지 절반에 관한 이야기입니다. 같은 저장소가 Claude Code에서도 열리고, Codex CLI에서 질문받고, 두 번째 머신에서 검토되고, CI에서 돌아가는 에이전트가 질의합니다. 질문은 “어느 인덱서가 더 나은가”가 아닙니다. 질문은 한 창에서 에이전트가 신뢰하는 지도가 다음 창에서 신뢰하는 지도와 같은가입니다.

Maguyva가 바로 그 따라다니는 지도입니다. 원격 MCP 코드베이스 컨텍스트 레이어입니다. 에이전트는 다른 MCP 도구를 질의하는 것과 똑같은 방식으로 이를 질의합니다. 결과는 줄 번호가 붙은 순위화된 경로로 돌아옵니다. Cursor는 여전히 에디터입니다. 움직이는 것은 컨텍스트입니다.

Cursor의 인덱서는 무엇을 위한 것인가

Cursor의 내장 인덱싱은 채팅, 에이전트, 에디터 내 검색이 모델의 원시 컨텍스트 창에 들어가는 것에만 의존하지 않고 관련 코드를 가져올 수 있도록 존재합니다. IDE에는 옳은 설계입니다. 이 인덱스는 Cursor 고유의 것입니다. MCP 서버가 아니며 다른 어떤 클라이언트에서도 접근할 수 없습니다.

작동 방식은, 이 글을 쓰는 시점의 Cursor 공식 문서와 Cursor 자신의 설명에 따르면 이렇습니다: 주된 검색 경로는 더 이상 클라우드 임베딩 인덱스가 아닙니다. Cursor 팀은 커뮤니티 포럼에서, 현재 모델들이 살아있는 트리를 스스로도 충분히 잘 탐색하기 때문에 전용 시맨틱/임베딩 기반 검색이 grep 기반 검색으로 대체되어 축소되고 있다고 밝혔습니다. 그 자리를 대신하는 것이 Instant Grep으로, n-그램, 역색인 목록, 블룸 필터로 구축된 로컬 검색 인덱스이며, 메모리 매핑된 조회 테이블에 보관되어 질의가 서버가 아니라 개발자 자신의 머신에서 해결됩니다.

인덱스 자체는 저장소 자신의 .git/cursor/ 디렉터리 안에, 특정 git 커밋에 고정되어 존재합니다. 그 커밋 이후의 변경 사항은 다시 스캔을 촉발하는 대신 그 위에 층으로 쌓이며, 로컬 상태가 만들어진 대상과 크게 어긋났을 때만 인덱스가 다시 만들어집니다. .git 안에 있기 때문에 절대 추적되지도, 푸시되지도 않습니다 — 폴더를 삭제하면 인덱스는 사라집니다. git으로 추적되는 콘텐츠만 대상이 되므로 .gitignore는 구조적으로 지켜지며, .cursorignore는 읽기 경로에서 강제됩니다. 이제 그 경로에는 서버 측 임베딩 단계도, 원격 벡터 데이터베이스도 없습니다. 이전 문서는 클라우드 지원 설계 — 청크 암호화, 머클 트리 동기화, 팀원 간 인덱스 재사용 — 을 설명했지만, Cursor 팀은 그 설계가 축소되고 있다고 밝혔으므로 이 글은 더 이상 그것을 현재 상태로 설명하지 않습니다.

에디터 안의 눈에 띄는 강점은 Cursor의 Explore 서브에이전트입니다. 더 빠른 모델로 자기 자신의 컨텍스트 창에서 여러 병렬 검색을 실행하고 관련 있는 결과만 반환할 수 있어, 메인 대화가 검색 결과로 부풀지 않습니다. 이는 에디터 안에서의 진짜 강점입니다. 유지하세요.

멀티 루트 워크스페이스도 지원됩니다: 열린 각 폴더의 컨텍스트가 에이전트에게 제공됩니다. worktree 같은 일부 git 의존 기능은 멀티 루트 설정에서 비활성화되며, Cloud Agents는 멀티 루트 워크스페이스를 전혀 지원하지 않습니다.

이 중 어느 것도 Cursor를 떠날 이유가 아닙니다. 그것이 사는 곳에서 훌륭한 지도에 대한 정확한 설명일 뿐입니다.

“따라다닌다”는 것이 실제로 의미하는 것

지도는 같은 질문이 하나 이상의 클라이언트에서 열어볼 수 있는 인용과 함께 같은 종류의 답을 돌려줄 때 따라다닙니다.

Cursor에서: “parseConfig는 어디에 정의되어 있고, 누가 호출하나요?”
Claude Code에서, 같은 저장소에서: 같은 질문.
Cursor 창을 한 번도 연 적 없는 검토용 머신의 Codex CLI에서: 같은 질문.
MCP를 말하는 CI 에이전트에서: 같은 호스팅된 스냅샷을 상대로 같은 질문.

각 표면이 자기만의 사설 인덱스를 만든다면, 여러분에게는 하나의 지도가 있는 게 아닙니다. 서로 어긋나는 여러 캐시가 있는 것입니다. 에디터 인덱스는 디스크 위 트리에 대해서는 최신일 수 있습니다. CLI 세션은 하루 뒤처져 있을 수 있습니다. CI 작업은 다른 체크아웃을 보고 있을 수 있습니다. 그래도 에이전트는 여전히 확신에 차 있는 것처럼 들릴 것입니다.

Cursor의 인덱서가 이 문제를 풀도록 되어 있지 않습니다. 에디터 안에 살기 때문에, 그것이 만드는 컨텍스트는 그 에디터를 위한 것입니다. CLI, CI 파이프라인, 또는 다른 에디터도 필요한 독자는 그 표면들을 위한 별도 도구가 필요합니다. 이는 범위의 사실이지, 결함이 아닙니다. Maguyva가 바로 그 별도 도구입니다.

Cursor 인덱서의 공개된 언어 수는 이 글이 사용할 수 있는 자료에 명시되어 있지 않습니다. Maguyva는 279개 이상의 언어와 텍스트 기반 기술을 공개하고 있습니다. Cursor의 가격도 여기서는 그대로 옮기지 않습니다. 그들의 가격 페이지를 참고하세요. Maguyva는 좌석이 아니라 워크스페이스 단위로 과금하며, 색인된 규모와 워크스페이스 크기에 따라 $0, $19, $49, $149의 공개 요금제를 제공합니다.

하나의 호스팅된 지도, 모든 MCP 클라이언트

Maguyva는 원격 MCP 서버입니다. GitHub를 연결하고, 저장소를 선택하면, 클라우드 파이프라인이 심볼과 그래프 엣지, 순위화된 지도를 구축합니다. 이미 사용 중인 클라이언트의 MCP 설정에 API 키를 추가합니다. Maguyva는 Cursor를 포함해 24개의 문서화된 MCP 클라이언트에 대한 설정 가이드를 제공하며, 표준 MCP 설정을 지원하는 다른 MCP 호환 클라이언트에도 연결할 수 있습니다.

작업 환경이 Cursor라면 Cursor 설정 페이지가 에디터별 경로입니다. 같은 서버가 Claude Code, VS Code, Windsurf, Codex CLI 등에도 응답합니다. 에디터를 바꾸지 않습니다. 모든 에이전트에게 검색, 심볼, 의존성 분석, 파일 조회, 저장소 컨텍스트, 결정론적 유틸리티 워크플로에 걸친 동일한 도구 표면 — 11개의 고객용 MCP 도구 — 을 제공합니다. 시맨틱, 구조적, 그래프, 텍스트 검색이 순위화된 결과로 융합됩니다.

그것이 이동성의 이점입니다. 오늘 아침 Cursor에서 검증한 인용은 오늘 밤 Codex CLI가 돌려줄 인용과 같은 형태입니다. 파일 경로와 줄 번호. 열어보세요. 틀렸다면 보입니다. 맞다면 다음 수정이 착륙할 자리가 생깁니다. 승인된 주장은 더 적은 환각 편집이지, 모든 편집이 옳다는 약속이 아닙니다.

최신성은 공개되어 있습니다. 스냅샷에는 타임스탬프가 찍혀 있어 에이전트가 어떤 버전의 트리를 읽고 있는지 알 수 있습니다. 재구축 주기는 무료 플랜에서는 매일, 유료 플랜에서는 매시간입니다. 정직한 한계는 동기화되지 않은 로컬 작업입니다: 작업 트리에만 존재하는 변경 사항은 아직 호스팅된 지도에 없습니다. 이 한계는 어느 클라이언트에서 질의하든 동일하며, 바로 그것이 요점입니다. 클라이언트 간 드리프트는 더 이상 두 번째 숨은 한계가 아닙니다.

문서는 모든 클라이언트에 적용되는 활성화 루프를 제공합니다: 이미 아는 저장소를 색인하고, 클라이언트를 연결하고, 검증할 수 있는 질문을 하세요. Cursor에서 한 번 해보세요. 실제로 검토하는 날 사용하는 CLI에서 다시 해보세요. 두 답변이 같은 핸들러를 인용한다면, 지도가 따라다닌 것입니다.

두 지도가 나란히 공존하는 방법

둘 다 사용하세요. 비교 페이지 식의 대안 관계가 아닙니다.

디스크 위 프로젝트를 위해 Cursor의 인덱서를 계속 켜두세요. Explore, Instant Grep, 에디터 내 에이전트가 그것을 쓰게 하세요. 그 루프는 네이티브하고 빠릅니다.
Cursor에 Maguyva를 MCP 서버로 추가해서, 같은 세션이 호스팅된 워크스페이스 지도도 질의할 수 있게 하세요. Cursor는 문서화된 Maguyva 클라이언트입니다. 한쪽 인덱스를 선택하고 다른 쪽을 지우는 게 아닙니다.
저장소를 다루는 Claude Code, Codex CLI, 또는 다른 어떤 MCP 클라이언트에도 같은 Maguyva 서버를 추가하세요. 하나의 API 키 형태. 하나의 워크스페이스.
CI 에이전트가 MCP 호환이라면, 같은 서버를 가리키게 하세요. 노트북이 읽은 것과 같은 타임스탬프 스냅샷을 읽을 것입니다.

에디터 인덱스는 여전히 “지금 이 창의 디스크에 무엇이 있는가”에 가장 좋은 도구입니다. 호스팅된 지도는 “오늘 이것을 만질 모든 에이전트에게 이 워크스페이스가 어떻게 보이는가”에 가장 좋은 도구입니다. 이 문장들은 서로 경쟁하지 않습니다.

워크스페이스 할당량은 가격 페이지에 공개되어 있습니다: 저장소, 색인된 줄 수, 사용자 수를 워크스페이스 단위로 청구합니다. 에이전트와 사람은 같은 사용자 수를 공유합니다. 이미 평가할 수 있는 저장소로 무료로 시작하세요. 인용이 트리와의 접촉에서 살아남은 뒤에야 워크스페이스를 늘리세요.

이 페이지가 주장하지 않는 것

Cursor의 인덱서가 약하거나, 불완전하거나, 에디터를 바꿀 이유라고 주장하지 않습니다. 이 글의 첫 문장이 그 반대입니다.

Maguyva가 Instant Grep이나 Explore 서브에이전트를 대체한다고 주장하지 않습니다. 그것들은 Cursor의 기능입니다. Cursor 안에 남아 있습니다.

두 제품 중 어느 쪽에 대해서도 언어 수, 지연 시간 수치, 토큰 절감치를 지어내지 않습니다. 알려지지 않은 수치는 공개되지 않은 채로 남습니다.

푸시되지 않은 로컬 작업이 호스팅된 지도에 있는 척하지 않습니다. 타임스탬프가 찍힌 스냅샷이 그 한계를 눈에 보이게 합니다. 그것을 없애주지는 않습니다.

테스트는 평범합니다. 이미 아는 저장소를 색인하세요. 검증할 수 있는 질문을 하세요, 먼저 Cursor에서, 그다음 두 번째 MCP 클라이언트에서. 따라다니는 컨텍스트란 양쪽에서 같은 인용을 얻는 것입니다.

// same map, wherever you opened it.

지도가 먼저, 리뷰는 그다음

Mon, 07 Sep 2026 00:00:00 GMT

풀 리퀘스트의 양쪽에는 서로 다른 두 가지 일이 있습니다. 에이전트가 쓰기 전에는 곧 바꿀 트리의 지도가 필요합니다. 에이전트가 PR을 연 뒤에는, 그 변경을 시스템의 나머지와 대조해 읽고 사람이 행동할 수 있는 코멘트를 남기는 무언가가 있어야 합니다.

이 두 일은 둘 다 “코드베이스를 이해하는 것”을 포함하기 때문에 멀리서 보면 비슷해 보입니다. 같은 제품이 아닙니다. 하나는 “이 변경이 어디에 착륙해야 하는가”에 답합니다. 다른 하나는 “줄 단위 린터가 놓칠, 이 diff가 무엇을 망가뜨렸는가”에 답합니다. 이 둘을 섞으면 더 나쁜 초안과 더 시끄러운 리뷰가 나옵니다.

이 글은 공동 워크플로 가이드입니다. Maguyva는 에이전트가 먼저 질의하는 지도입니다. Greptile은 그다음 PR에 코멘트를 다는 리뷰 에이전트입니다. 이 짝은 구조적으로 상호 보완적입니다: Maguyva는 풀 리퀘스트를 리뷰하지 않고, Greptile은 에이전트가 그것들을 쓰는 데 사용한 컨텍스트 레이어를 대체하지 않습니다.

이 분리가 유용한 이유

훈련 사전 지식과 붙여넣은 몇 개의 파일에서 출발하는 코딩 에이전트는 그럴듯한 경로를 지어내 편집할 것입니다. 그것이 잘못된 파일 실패이며, 검색 문제입니다. Maguyva는 원격 MCP 코드베이스 컨텍스트 레이어입니다: 시맨틱, 구조적(AST), 그래프/의존성, 텍스트 검색이 순위화된 결과로 융합되며, 심볼 조회와 파일 조회도 있습니다. 근거 있는 답변은 path/file.ext:line 형태로 돌아오므로, 패치가 존재하기 전에 실패를 거부할 수 있습니다. 주장은 겸손함을 유지합니다: 더 적은 환각 편집. 모델은 여전히 추측할 수 있습니다. 다만 첫 단계가 더 이상 추측이 아닐 뿐입니다.

Greptile은 AI 코드 리뷰 에이전트입니다. 그들 자신의 표현으로, 코드베이스에 대한 완전한 이해로 모든 풀 리퀘스트를 자동으로 리뷰하며, 시스템 전체가 아니라 파일을 개별적으로 확인하는 전통적인 린터와 대비시킵니다. 설정은 GitHub 또는 GitLab 앱을 설치하고 저장소를 선택하는 것입니다. 운영할 로컬 인덱스가 없습니다. 호스팅은 Greptile Cloud이며(요청 시 제공되는 보고서와 함께 SOC 2 Type II 준수를 표명합니다), 기업을 위한 자체 호스팅 옵션도 제공됩니다.

그들 자신의 번호 매긴 흐름은 이렇습니다: 연결하고 모든 함수, 클래스, 의존성의 의존성 그래프를 구축한다; 모든 풀 리퀘스트에서, 그 전체 저장소 그래프를 사용해 변경을 분석하고 약 3분 안에 제안된 수정과 함께 PR 코멘트로 결과를 게시한다; 각 코멘트는 팀이 이미 사용하는 코딩 에이전트에게 문제를 넘길 수 있다. 그들은 또한 팀의 코딩 표준을 학습하고 시끄러운 제안을 줄이기 위해 시간이 지남에 따라 이전 사람의 PR 코멘트를 읽는다고 밝히고 있습니다. 그들의 학습 시스템은 적응하는 데 2~3주가 필요하다고 밝히고 있습니다.

이것은 리뷰이지 초안 작성이 아닙니다. Greptile의 강점은 이미 PR에 착륙한 변경에 대한 전체 저장소 그래프 컨텍스트이며, 그다음 그 결과를 Claude Code, Codex, Conductor, Cursor, 또는 Devin에게 보내는 닫힌 루프입니다. Maguyva의 강점은 그 변경이 쓰이기 전에 에이전트가 질의한 순위화된 지도입니다. 둘 다 사용하세요. 어느 쪽에게도 다른 쪽의 일을 시키지 마세요.

Maguyva–Greptile의 퍼스트파티 제품 통합은 명시되어 있지 않습니다. 그럴 필요도 없습니다. Maguyva는 MCP를 통해 에이전트와 대화합니다. Greptile은 그들의 앱을 통해 GitHub나 GitLab과 대화합니다. 둘은 풀 리퀘스트에서 만납니다. 접착용 스크립트도, 하나를 다른 하나로 연결하는 크론도 없습니다. 각 제품이 이미 자기 소유의 표면에 앉아 있기 때문에 이 짝에는 bash가 필요 없습니다.

이것이 아닌 것

이것은 Greptile을 깎아내리는 글이 아닙니다. “리뷰어를 바꾸라”는 글도 아닙니다. Greptile은 2024년 3월 5일 Y Combinator W24 기업으로 Hacker News에 출시되었고, 그 스레드는 많은 사람이 처음으로 이 제품을 알게 된 방법입니다. 그렇게 알게 되었다면 계속 쓰세요. 이 페이지는 그 루프에서 빠진 앞부분입니다: Greptile이 보는 PR이 이미 올바른 파일을 겨냥하도록 에이전트를 먼저 근거 있게 만드는 것.

Greptile의 마케팅 자료는 리뷰 속도와 버그 포착 주장을 앞세웁니다. 이를 독립적으로 검증된 수치가 아니라 Greptile 자신의 주장으로 취급하세요. 이 글은 그것들을 사실로 반복하지 않습니다.

언어 커버리지도 같은 종류의 정직함입니다. Greptile은 나열된 목록이 아니라 모든 프로그래밍 언어를 커버한다는 프레임을 지원에 씌우며, 정확한 숫자는 명시되어 있지 않습니다. Maguyva는 279개 이상의 언어와 텍스트 기반 기술을 공개하며, 질문이 기술적일 때는 사이트에 기술적 구분(파서 기반 AST 대 텍스트 전용)도 함께 공개합니다. 서로 다른 제품이 서로 다른 주장을 하는 것입니다. 섞지 마세요.

Greptile의 가격은 이 글이 사용할 수 있는 자료에 명시되어 있지 않습니다. 유료 플랜은 존재합니다. 그들의 가격 페이지를 참고하세요. Maguyva는 좌석이 아니라 워크스페이스 단위로 과금합니다. 플랜은 무료로 시작합니다. 워크스페이스 수치가 필요하다면 가격 페이지에 공개된 등급이 나와 있습니다.

워크플로

세 개의 이름 붙은 단계입니다. 이 순서대로 실행하세요. 이 짝을 처음 시도할 때는 어느 것도 건너뛰지 마세요.

1. Maguyva 컨텍스트

이미 아는 저장소 하나를 색인하세요. 이미 코드를 쓰는 MCP 클라이언트를 연결하세요 — Claude Code, Cursor, Codex CLI, VS Code, Windsurf, 또는 다른 MCP 호환 클라이언트. Maguyva는 24개의 문서화된 MCP 클라이언트에 대한 설정 가이드가 있으며, 표준 MCP 설정을 지원하는 다른 클라이언트에도 연결할 수 있습니다.

누군가 한 줄이라도 쓰기 전에 평가할 수 있는 질문을 하세요. “세션 만료는 어디서 처리되고, 무엇이 그것을 호출하는가?“는 “인증을 고쳐줘”보다 더 나은 첫수입니다. 인용을 요구하세요. file.ext:line 결과를 여세요. 심볼을 따라가세요. 곧 건드릴 의존성을 확인하세요.

Maguyva는 검색, 심볼, 의존성 분석, 파일 조회, 저장소 컨텍스트, 결정론적 유틸리티 워크플로에 걸친 11개의 고객용 MCP 도구를 제공합니다. 네 가지 검색 모드가 순위화된 결과로 융합되며, 이름을 이미 알고 있을 때는 find_symbol가 별도의 도구입니다. 문서는 가장 짧은 경로를 설명합니다: 무료로 시작하고, 이미 아는 저장소를 색인하고, 클라이언트를 연결한 다음, 검증할 수 있는 질문을 하세요.

스냅샷에는 타임스탬프가 찍혀 있어 에이전트가 어떤 버전의 트리를 읽고 있는지 알 수 있습니다. 정직한 한계는 동기화되지 않은 로컬 작업입니다. 변경 사항이 작업 트리에만 존재하고 푸시되지 않았다면, 호스팅된 지도는 아직 그것을 담고 있지 않습니다. 지시 파일(CLAUDE.md, AGENTS.md)은 여전히 관례와 건드리지 말아야 할 것을 위해 여기 속합니다. 그것들은 살아있는 지도가 아닙니다. 행동에는 그것들을 쓰고, 사실에는 Maguyva를 쓰세요.

인용이 저장소와의 접촉에서 살아남기 전에는 에이전트가 PR을 열게 하지 마세요. 그 게이트가 이 단계의 전체 목적입니다.

2. 에이전트 PR

같은 에이전트가 이제 이미 비용을 지불하고 있는 클라이언트에서 변경을 씁니다. Maguyva는 에디터도 리뷰어도 아닙니다. 에이전트는 여전히 diff를 만듭니다. 여러분은 여전히 이미 하던 대로 GitHub나 GitLab에서 풀 리퀘스트를 엽니다.

달라져야 할 것은 첫 파일입니다. PR은 실제로 그 동작을 구현하는 핸들러, 깨질 호출자, 변경이 잘못되었을 때 실패할 테스트를 명시해야 합니다. 1단계를 건너뛰었다면, 3단계는 잘못된 패키지에 착륙한 변경에 코멘트를 쓰느라 시간을 씁니다. Greptile은 여전히 체계적인 문제는 찾을 수 있습니다. 그것이 환각 경로에서까지 회복해야 하는 것은 아닙니다.

PR의 범위를 좁게 유지하세요. 근거 있는 첫 파일이 모듈을 다시 쓸 면허는 아닙니다. 이 상호 보완적인 짝은 에이전트가 지도를 가지고 하나의 일을 하고, 그다음 리뷰어에게 한정된 diff에서 다른 일을 해달라고 요청할 때 작동합니다.

3. Greptile 리뷰

Greptile은 이미 GitHub나 GitLab 앱을 통해 저장소에 연결되어 있습니다. 새 풀 리퀘스트에서 자신이 구축한 전체 저장소 그래프를 사용해 변경을 분석하고, 제안된 수정과 함께 코멘트로 결과를 게시합니다. 그들 자신의 자료는 이 과정을 약 3분으로 잡습니다.

코멘트는 신중한 팀원을 읽듯이 읽으세요: 인용된 위치를 열고, 발견이 진짜인지 판단한 다음, 행동하세요. Greptile이 “Fix with your Agent”를 제공하는 곳에서는, 파일 경로, 줄 번호, 제안된 코드를 담은 문제를 Claude Code, Codex, Conductor, Cursor, 또는 Devin에게 보냅니다. “Fix All”은 리뷰의 모든 문제를 한 번에 보냅니다. 그들은 또한 이 인계를 위해 Greptile MCP와 Claude Code 플러그인도 제공합니다. Maguyva는 그 이름 붙은 대상 목록에 없습니다. 그 부재는 문제가 아닙니다. Maguyva는 이미 1단계에서 자기 일을 마쳤습니다. PR을 쓴 코딩 에이전트가 수정 페이로드를 받아야 할 대상입니다.

Greptile의 학습 시스템이 팀이 실제로 남기는 코멘트에 적응하는 처음 2~3주 동안은 잡음을 예상하세요. 그것이 그들이 밝힌 일정이지, 이 짝의 결함이 아닙니다. 사람의 리뷰는 여전히 루프 안에 있습니다. Greptile은 자동화된 첫 통과이지, 머지 버튼이 아닙니다.

Greptile 코멘트가 에이전트가 1단계에서 한 번도 질의하지 않은 파일을 가리킨다면, 그것은 유용한 신호입니다. 지도가 호출자를 놓쳤거나, 에이전트가 인용을 건너뛴 것입니다. 코멘트에 맞춰 초안을 고치세요. 리뷰어를 끄지 마세요.

이 보완 관계를 정직하게 유지하는 법

Maguyva가 항상 먼저입니다. 잘못된 파일에 대한 PR 리뷰는 여전히 잘못된 파일에 대한 리뷰입니다.
Greptile은 항상 그다음입니다. 잘 인용된 초안이라도 여전히 시스템 전체 수준의 diff 읽기가 필요합니다.
Maguyva에게 PR 코멘트를 게시해 달라고 요청하지 마세요. 그렇게 하지 않습니다.
Greptile에게 에이전트가 여전히 경로를 고르는 중일 때의 첫 검색 레이어가 되어 달라고 요청하지 마세요. 그것은 그들의 GitHub나 GitLab 앱이 위해 만들어진 일이 아닙니다.
둘을 “동기화”하는 bash 파이프라인을 지어내지 마세요. PR이 인터페이스입니다.
양쪽을 독립적으로 검증하세요. 이미 아는 저장소를 색인하세요. 검증할 수 있는 질문을 하세요. 그다음 작은 PR을 열고 Greptile이 실제로 뭐라고 코멘트하는지 읽으세요.

이름을 붙이고 나면 이 루프는 평범합니다. 지도가 먼저. 에이전트 PR. 리뷰가 그다음. 각 제품은 자신이 잘하는 풀 리퀘스트 쪽에 남습니다.

// map first. review second. in that order.

로컬 인덱서 없이 AI 에이전트에게 대규모 저장소의 컨텍스트 주기

Fri, 14 Aug 2026 00:00:00 GMT

대규모 저장소는 컨텍스트 창에 들어가지 않으며, 진짜 모노레포에 노트북 인덱서를 돌려본 적이 있다면 거기에도 편하게 들어가지 않는다는 걸 압니다 — RAM이 치솟고, 첫 인덱싱에 한 시간이 걸리고, 에이전트는 다음 세션을 시작할 때도 여전히 어떤 파일이 중요한지 추측합니다.

흔한 답은 에디터 옆에 인덱서를 돌리는 것이고, 한 대의 머신에 편하게 들어가는 저장소라면 좋은 답입니다. 모노레포가 이미 Cursor에서 빠르게 색인되고, 지도가 필요한 곳이 거기뿐이라면, 이 글은 더 보탤 게 없습니다 — 건너뛰세요.

이 글은 다른 경우 — 에이전트가 대규모 저장소의 질의 가능한 지도가 필요하고, 그것을 얻기 위해 로컬 인덱서를 돌리고 싶지 않을 때 — 에 관한 것입니다.

로컬 인덱서가 잘못된 도구인 경우

로컬 인덱스는 코드가 그것을 질의할 머신 위에 산다고 가정하며, 진짜 모노레포 규모에서는 이 가정이 단일 에디터 안에서조차 팽팽해집니다. 저장소는 노트북에 계속 데워둘 만한 크기를 그저 넘어섭니다: 하나의 패키지에서 작업하는 동안 영향 범위은 세 디렉터리 너머에 있고, 200만 줄짜리 트리의 첫 콜드 인덱싱은 두 번 겪고 싶은 일이 아닙니다 — 여러분의 머신에서도, 그 트리를 한 번도 클론한 적 없는 CI 러너에서도. 아니면 팀 동료가 자기 머신이 같은 인덱스를 힘겹게 통과하기를 기다리지 않고, 여러분과 같은 지도를 질의할 수 있어야 할 수도 있습니다.

이 중 어느 것도 좋은 에디터 인덱서를 버릴 이유는 아닙니다. 여러분의 어떤 에이전트든 MCP를 통해 질의할 수 있는 호스팅된 지도도 함께 가질 이유입니다.

그리고 규모의 문제는 “붙여넣기엔 파일이 너무 많다”는 것보다 더 깊습니다. 큰 트리에서 흥미로운 질문은 거의 “이 파일을 보여줘”가 아닙니다 — 어떤 파일인지, 어떤 심볼인지, 어떤 호출자인지, 어떤 테스트인지입니다. src/을 나열하고 처음 세 개의 결과를 읽는 것으로 시작하는 에이전트는 apps/api에 있는 핸들러와 packages/sdk에 있는 생성된 클라이언트를 아무렇지 않게 놓칠 것입니다. 필요한 것은 전체 트리로부터 구축되고, 순위가 매겨지고, 인용된 검색입니다.

“대규모 저장소의 컨텍스트”가 실제로 의미하는 것

프롬프트에 파일을 쏟아붓는 것은 컨텍스트가 아닙니다 — 트리의 더 작고 더 나쁜 사본일 뿐입니다. 여러분의 에이전트가 실제로 필요한 것은 질문을 하고 인용된 답을 돌려받는 것입니다: 이 심볼은 어디에 정의되어 있고 누가 호출하는지, 지금 바꾸려는 모듈에 무엇이 의존하는지, 어떤 테스트 파일이 이 동작을 커버하는지, 그리고 트리가 지난 분기가 아니라 지금 어떻게 생겼는지.

이 답들은 다른 사람들의 저장소에 대한 모델의 기억이 아니라 여러분의 저장소로부터 구축된 인덱스에서 나와야 하고, 그 인덱스는 에이전트의 컨텍스트 창이 아닌 다른 어딘가에 살아야 합니다. 이 문제에서는 여러분의 노트북이 아닌 다른 어딘가에도 살아야 합니다.

지시 파일이 여러분을 위해 해줄 수 없는 또 하나: CLAUDE.md와 AGENTS.md는 관례와 행동을 위한 올바른 자리지만, 200만 줄짜리 트리의 살아있고, 순위화되고, 질의 가능한 지도는 아닙니다. 행동에는 규칙을 쓰고, 사실에는 저장소 인텔리전스를 쓰세요.

클라우드에서 지도를 만들고, 어떤 클라이언트에서든 질의하기

Maguyva는 원격 MCP 코드베이스 컨텍스트 레이어입니다. GitHub를 연결하고, 저장소를 선택하면, 클라우드 파이프라인이 트리를 파싱하고 심볼과 그래프 엣지를 구축하고 순위화된 지도를 유지하는 동안 자리를 뜨면 됩니다 — 로컬 인덱서는 결코 없습니다.

코드를 푸시하면, 변경된 파일은 점진적으로 파싱되고, 그래프와 랭킹 레이어는 일정에 따라 재구축됩니다: 무료 플랜에서는 매일, 유료 플랜에서는 매시간. 모든 스냅샷에는 타임스탬프가 찍혀 있어 에이전트가 어떤 버전의 트리를 읽고 있는지 알 수 있습니다. 여기서 정직한 한계는 동기화되지 않은 로컬 작업입니다 — 작업 트리에만 존재하고 한 번도 푸시된 적 없는 변경 사항은 아직 호스팅된 지도에 없습니다.

그다음 이미 사용하는 클라이언트의 MCP 설정에 API 키를 추가해 연결합니다. 24개의 문서화된 MCP 클라이언트에 대한 설정 가이드가 있으며, 표준 설정을 지원하는 다른 MCP 호환 클라이언트도 연결할 수 있습니다. Cursor가 여러분의 근거지라면 Cursor 페이지가 그 경로를 안내합니다. 같은 서버가 Claude Code, VS Code, Windsurf, Codex CLI 등에도 응답합니다.

에디터를 바꾸지 않습니다. 검색, 심볼, 의존성 분석, 파일 조회, 저장소 컨텍스트에 걸친 도구 표면 — 11개의 MCP 도구 — 을 279개 이상의 언어와 텍스트 기반 기술을 아우르는 커버리지와 함께 에이전트에게 제공합니다. 이는 몇 년 전에 이미 단일 언어가 아니게 된 모노레포에서 생각보다 더 중요합니다.

답변은 줄 번호가 붙은 파일 경로로, 근거를 갖춘 채 돌아옵니다. 시맨틱, 구조적, 그래프, 텍스트 검색이 순위화된 결과로 융합되어, “parseConfig에 무엇이 의존하는가” 같은 질문이 grep 덤프나 단일 시맨틱 조각이 아니라 실제로 중요한 몇 곳을 돌려줍니다.

구체적인 방법

회사 전체를 색인하는 것으로 시작하지 마세요. 실제로 통하는 경로는 이렇습니다:

이미 잘 아는 저장소 하나를 고르세요 — 손으로 평가할 수 있는 패키지가 가진 가장 큰 트리보다 낫습니다.
무료로 시작하세요: 저장소 3개, 색인 5만 줄, 11개 도구 전부, 월간 질의 한도 없음. 대표 저장소가 그보다 크다면, 가격 페이지에 색인된 규모별 워크스페이스 등급($0, $19, $49, $149)이 좌석 수가 아니라 나와 있습니다.
GitHub를 연결하고 첫 색인이 끝나기를 기다리세요. 로컬에서 아무것도 컴파일하지 않습니다.
MCP 클라이언트를 연결하세요 — 몇 줄의 설정. Maguyva는 원격 MCP 서버이므로 플러그인도, 확장도, 채택해야 할 두 번째 에디터도 없습니다.
검증할 수 있는 질문을 하나 하세요. “parseConfig에 무엇이 의존하는가?” 또는 “로그인 세션 만료는 어디서 처리되는가?” 그런 다음 인용된 file.ext:line 결과를 열어 눈앞의 트리와 대조하세요.
인용이 그 대조를 견뎌낸 뒤에야 에이전트가 편집하게 하세요.

첫 저장소가 잘 맞고 트리가 크다면, 색인된 줄 수와 재구축 주기에 맞춰 워크스페이스를 올리세요. 사람과 에이전트는 같은 사용자 수를 공유합니다 — Maguyva는 좌석이 아니라 워크스페이스 단위로 과금하므로 — 세 번째 에이전트를 루프에 추가해도 비용이 들지 않습니다.

활성화 테스트는 문서가 모든 첫 실행에 권장하는 것과 같습니다: 이미 아는 저장소를 색인하고, 검증할 수 있는 질문을 하세요. 대규모 저장소라고 테스트가 달라지지 않습니다. 다만 잘못된 첫 파일의 대가가 더 커질 뿐입니다.

연결한 뒤 지켜볼 것

세 가지를 지켜보세요. 최신성: 유료 플랜은 매시간, 무료 플랜은 매일 재구축되며, 푸시되지 않은 로컬 작업은 지도에 없을 것입니다 — 그것이 여러분이 감수하는 거래입니다. 범위: 보관된 모든 포크가 아니라 대표적인 저장소 집합을 색인하세요. 무료 등급은 답이 유지할 가치가 있는지 알아보도록 의도적으로 규모가 잡혀 있습니다. 그리고 검증: 경로와 줄 번호를 인용하지 못하는 대규모 저장소 지도는 그저 더 느린 추측 엔진일 뿐이니, 에이전트가 패치를 내놓기 전에 위치를 보여주게 하세요.

그런 다음 작은 저장소에서 하던 것과 같은 테스트를 실행하세요. 이미 아는 저장소를 색인하세요. 검증할 수 있는 질문을 하세요. 지도가 진짜라면, 여러분의 에이전트는 더 이상 차가운 트리에서 출발하지 않습니다.

// no laptop got hot building this map.

AI 코딩 에이전트가 파일 경로를 환각하는 이유

Fri, 14 Aug 2026 00:00:00 GMT

그 징후는 잘못된 함수 본문이 아닙니다. 존재하지 않는 파일에 대한, 또는 존재하지만 그 동작을 구현하지 않는 파일에 대한 확신에 찬 편집입니다.

여러분은 세션 만료 수정을 요청했습니다. 에이전트는 src/auth/session.ts을 열었습니다. 그 경로는 그럴듯합니다. 또한 틀렸습니다. 진짜 핸들러는 두 번의 리팩터링 전에 이름이 바뀐 apps/api/src/middleware/expiry.ts에 있습니다. 에이전트가 여러분에게 거짓말한 것이 아닙니다. 훈련 사전 지식과 이미 컨텍스트 창에 있던 것을 조합해 경로 모양의 문자열을 완성한 것입니다.

이것이 실제 저장소에서 흔한 실패 양상입니다. 모델은 코드를 쓸 수 있습니다. 실수는 쓸 잘못된 위치를 고르는 데 있습니다.

에이전트가 경로를 지어내는 이유

코딩 에이전트는 도구를 가진 다음 토큰 예측 모델입니다. “세션 만료를 고쳐줘”라고 말하면, 무엇이든 읽거나 패치하기 전에 파일 하나를 지목해야 합니다. 아직 근거 있는 지도가 없다면, 다음으로부터 경로를 구성합니다:

다른 저장소에서 본 명명 관례. src/auth/session.ts는 흔한 형태입니다.
대화에 이미 있는 파일들. 지금 중요한 것이 아니라 지난주에 붙여넣은 파일일 수도 있습니다.
우연히 실행한 디렉터리 목록. 큰 트리에서는 불완전합니다.
지시 파일들. CLAUDE.md과 AGENTS.md는 에이전트에게 어떻게 행동할지 알려줍니다. 심볼이나 호출자, 현재 경로의 살아있는 인덱스가 아닙니다.

이 중 어느 출처도 오늘의 이 저장소에 대한 지도가 아닙니다. 모델은 다른 모든 공백을 채우는 방식으로 이 공백을 채웁니다: 확률이 높은 이어짐으로요. 그 이어짐은 종종 진짜 경로처럼 보입니다. 어떤 때는 파일이 존재하고 올바른 파일 옆에 있습니다. 어떤 때는 지난달 머지된 브랜치에 존재했습니다. 어떤 때는 한 번도 존재한 적이 없습니다.

에이전트가 올바른 문자열을 애초에 검색하지 않는다면, 여기서는 grep도 여러분을 구하지 못합니다. 에이전트는 경로를 추측하고, 그 경로가 돌려준 것을 읽고, 편집했습니다. 첫 번째 잘못된 단계는 경로였지, 패치가 아니었습니다.

파일을 읽는 것도 올바른 파일을 찾는 것과 같지 않습니다. Claude Code, Cursor, Codex와 비슷한 도구들은 여러분이 가리키는 무엇이든 열 수 있습니다. 질문은 그것들이 편집하기 전에 올바른 파일, 중요한 심볼, 의존성, 테스트, 영향 범위을 믿을 만하게 찾아내는가입니다. 지도 없는 파일 접근은 여전히 추측으로 시작합니다.

잘못된 파일 편집은 검색 문제다

지어낸 경로를 성격 결함이 아니라 검색 실패로 다루세요.

에이전트가 편집을 허락받기 전에 path/file.ext:line를 반드시 반환해야 한다면, 두 가지 일이 일어날 것입니다. 첫째, 여러분은 인용을 열고 10초 안에 작업을 거부할 수 있습니다. 둘째, 에이전트는 실제로 트리를 아는 무언가를 질의해야 할 것입니다.

그것이 코드베이스 컨텍스트 레이어의 일입니다. 시맨틱 검색만으로는 충분하지 않습니다. “세션 만료처럼 들리는” 조각도 여전히 폐기된 패키지에 착륙할 수 있습니다. 문자열을 알 때는 정확한 텍스트도, 이름을 알 때는 심볼 조회도, 형태를 알 때는 구조적 검색도, 호출자와 영향 범위이 필요할 때는 의존성 그래프도 필요합니다.

Maguyva는 MCP 호환 코딩 에이전트를 위한 그 레이어입니다. 에디터가 아닙니다. Claude Code, Cursor, Codex CLI, VS Code, Windsurf, 그리고 다른 MCP 클라이언트는 있던 그 자리에 남아 있습니다. 에이전트는 한 줄을 건드리기 전에 순위화된 지도를 질의합니다.

그 주장은 의도적으로 겸손합니다: 더 적은 환각 편집. Maguyva는 모델에게서 추측하는 능력을 빼앗지 않습니다. 기본 첫 단계를 “그럴듯한 경로를 지어내기”에서 “순위화되고 인용된 위치를 요청하기”로 바꿀 뿐입니다.

근거 있는 답변은 어떤 모습인가

“세션 만료가 어디서 처리되는가”에 대한 유용한 답변은 문단이 아닙니다. 짧은 위치 목록입니다:

apps/api/src/middleware/expiry.ts:48 - 핸들러
apps/web/src/lib/auth-client.ts:112 - 호출자
apps/api/tests/expiry.test.ts:20 - 변경이 잘못되면 실패할 테스트

여러분은 그 줄들을 열어볼 수 있습니다. 틀렸다면, 멈춥니다. 맞다면, 에이전트가 편집해도 됩니다. 검증이 핵심이지, 슬로건이 아닙니다.

Maguyva는 검색, 심볼, 의존성 분석, 파일 조회, 저장소 컨텍스트, 결정론적 유틸리티 워크플로에 걸친 11개의 고객용 MCP 도구를 제공합니다. 네 가지 검색 모드(시맨틱, 구조적, 그래프/의존성, 텍스트)가 순위화된 결과로 융합되며, 심볼 조회는 별도의 MCP 도구(find_symbol)입니다. 근거 있는 답변은 파일 경로와 줄 번호와 함께 돌아오므로, 눈앞의 트리에 견주어 평가할 수 있습니다.

문서는 가장 짧은 경로를 설명합니다: 무료로 시작하고, 이미 아는 저장소를 색인하고, 클라이언트를 연결한 다음, 검증할 수 있는 질문을 하세요.

첫 편집을 바꾸는 루프

새로운 워크플로 종교가 필요한 게 아닙니다. 첫 쓰기 전에 한 단계만 더 필요합니다.

이미 평가할 수 있는 질문을 하세요. “로그인과 세션 만료를 처리하는 코드는 무엇인가”가 “인증을 고쳐줘”보다 낫습니다.
인용을 요구하세요. “인증 모듈”의 요약이 아니라 파일 경로와 줄 번호.
인용된 파일을 여세요. 심볼을 따라가세요. 곧 건드릴 의존성을 확인하세요.
그런 다음에야 에이전트가 패치하게 하세요.

2단계가 쓸 만한 것을 아무것도 돌려주지 않는다면, 에이전트는 경로를 즉흥적으로 만들어낼 수 없습니다. 다시 검색하거나, 여러분이 가리켜 줍니다. 그 하나의 게이트가 더 적은 환각 편집을 만들어냅니다. 모델은 같은 모델입니다. 바뀐 것은 지도입니다.

지시 파일은 여전히 중요합니다. 유지하세요. 관례, 리뷰 규칙, 건드리지 말아야 할 것을 위해 쓰세요. 인덱스가 되어 달라고 요청하지 마세요. 세 개의 중요한 디렉터리를 나열한 CLAUDE.md은 패키지가 분할된 다음 주에 낡아버립니다. 질의 가능한 지도는 저장소가 업데이트되면 업데이트됩니다.

관련된 실패는 거의 맞는 파일입니다: 동작이 auth-client.ts에 있는데 에이전트가 auth.ts을 열거나, 소스 대신 생성된 파일을 패치하거나, 이름이 일치한다는 이유로 packages/legacy의 사본을 편집합니다. 인용이 그런 실수를 불가능하게 만들지는 않습니다. diff가 착륙하기 전에 그것들을 눈에 보이게 만들 뿐입니다.

지도가 여러분을 위해 고쳐주지 않는 것

무엇을 얻는지에 대해 냉정해지세요. 근거 있는 지도가 모든 편집을 옳게 만들지는 않습니다 — 에이전트는 여전히 정확히 올바른 파일에서 나쁜 패치를 쓸 수 있습니다. 코드베이스가 동적 디스패치, 리플렉션, 몽키패칭에 의존한다면, 일부 심볼 조회는 원하는 것보다 빈약하게 돌아올 것입니다. 런타임 간접성이 어떤 정적 인덱스에게든 그런 짓을 하기 때문입니다. 그리고 백분율을 바라고 있다면 — “환각 경로 X% 감소” — 여기서는 찾지 못할 것입니다. 여러분 자신 말고는 아무도 여러분의 저장소에 대한 그 숫자를 정직하게 측정할 수 없기 때문입니다.

기대할 수 있는 것은 더 좁고 더 유용합니다: 에이전트는 추측된 경로로 편집을 시작하는 것을 멈춥니다. 그 첫 단계가 진짜 지도에 근거를 두게 되고, 더 적은 환각 편집은 거기서 나옵니다. 인용 이후의 모든 것 — diff를 읽는 것, 패치를 판단하는 것 — 은 여전히 항상 그래왔듯 여러분의 일입니다.

이 테스트는 거의 아무것도 들지 않습니다: 이미 아는 저장소를 색인하고 검증할 수 있는 질문을 하세요. 예전에 당했던 경로부터 시작하세요. 인용이 틀렸다면, 즉시 보일 것입니다. 맞다면, 여러분 에이전트의 다음 편집은 착륙할 더 나은 자리를 갖게 됩니다.

// it doesn't know the file. it knows how to find it.

우리가 코드 검색을 voyage-4-large로 업그레이드한 이유

Tue, 09 Jun 2026 00:00:00 GMT

이 글의 벤치마크 수치는 게시 시점(2026년 6월)의 RTEB 리더보드를 반영합니다. 리더보드는 계속 바뀌므로, 순위는 영구적인 사실이 아니라 특정 시점의 스냅샷으로 받아들이세요.

시맨틱 검색의 품질은 그 기반이 되는 임베딩의 품질에 달려 있습니다.

에이전트가 Maguyva에게 “우리가 재시도를 어디서 처리하나”라고 물을 때, 이는 “retry”라는 단어를 grep하는 것이 아닙니다. 의미를 묻는 것입니다. 백오프 루프, 서킷 브레이커, 불안정한 호출을 감싸는 그 무언가를요. 이 질문은 코드를 공간 속의 한 점으로 바꾸고 이웃을 찾는 벡터 모델이 답합니다. 더 나은 모델을 고르면, 제품 안의 모든 시맨틱 쿼리가 조용히 더 날카로워집니다.

그래서 우리는 우리 것을 바꿨습니다. 2026년 6월 기준, Maguyva의 코드 임베딩은 voyage-code-3을 대체한 voyage-4-large 위에서 실행됩니다.

벤치마크

우리는 이 결정을 감으로 내리지 않았습니다. 공개된 검색 임베딩 벤치마크(RTEB)는 실제 검색 작업으로 임베딩 모델의 순위를 매기는데, Code 리더보드에서 voyage-4-large는 **전체 1위(90.86)**를 차지하고 있습니다. gemini-embedding-2-preview(90.26)보다 앞서고, 특히 우리가 이미 사용하고 있던 모델인 voyage-code-3(89.73, 3위)보다도 앞섭니다.

절대적인 차이는 작습니다. 하지만 이는 공개된 벤치마크에서, 우리가 신경 쓰는 바로 그 작업 — 의미로 코드를 검색하는 것 — 에서 올바른 방향으로의 차이입니다.

우리가 받아들이는 트레이드오프: 바이너리 양자화

대부분의 “우리는 모델을 업그레이드했다”는 글이 빠뜨리는 부분이 여기 있습니다.

Maguyva는 완전 정밀도(full-precision) 벡터를 저장하지 않습니다. 우리는 바이너리 양자화된 임베딩을 저장합니다. 2048차원 벡터 각각은 2048비트 시그니처로 압축됩니다. 벡터당 256바이트입니다. 이 시그니처들은 해밍 거리(Hamming distance)로 검색되며, 테넌트별로 인덱싱되고 파티셔닝됩니다.

이는 의도적인 트레이드오프입니다. 바이너리 양자화는 검색 정밀도를 일부 포기하는 대신, 별도의 벡터 데이터베이스 없이도 저장 공간을 대폭 줄이고 거리 계산을 빠르고 저렴하게 처리할 수 있게 합니다. 워크스페이스마다 전체 저장소를 인덱싱하는 제품에게는, 벤치마크 점수의 마지막 소수점을 짜내는 것보다 이 경제성이 더 중요합니다.

voyage-4-large는 저장 레이어의 마이그레이션을 강제하지 않고도 이 설계에 들어맞습니다. voyage-code-3과 동일하게 2048차원 출력을 만들어내므로, 우리의 bit(2048) 컬럼과 해밍 검색 경로는 바뀌지 않았습니다. 모델은 좋아졌지만, 스키마는 그대로 남았습니다.

코드는 시작에 불과했다

Maguyva는 코드 인텔리전스 도구입니다. 하지만 우리는 스스로도 첫 번째 고객이며, 이를 다른 것에도 겨냥합니다. 코드와 나란히 우리 저장소에 존재하는 마크다운 말이죠. 아키텍처 결정 기록, 런북, 계약서, 재무 및 정책 문서 — 이 모든 것이 Git으로 버전 관리되고, 모두 동일한 MCP 서버 뒤에 있으며, 소스 코드뿐 아니라 문서 전체에 걸친 시맨틱 인덱스입니다.

바로 이것이 voyage-4-large의 폭넓음이 중요한 이유입니다. 동일한 RTEB 계열의 리더보드에서 이 모델은 재무 1위, 헬스케어 1위, 전체 텍스트 검색 1위입니다. Google의 Gemini Embedding, Cohere의 Embed v4, OpenAI의 text-embedding-3-large보다 앞섭니다. (Voyage는 RTEB의 공동 제작자이므로, 우리는 이를 완벽하게 중립적인 심판이라기보다는 강력한 공개 신호로 받아들입니다. 하지만 이는 비공개 홀드아웃 세트에서 모든 주요 상용 모델과 정면으로 벤치마크된 것입니다.) 에이전트를 위해 올바른 함수를 찾아주는 것과 동일한 인덱스가 계약서의 올바른 조항이나 정책의 올바른 문구를 찾아줍니다. 그리고 그 도메인들에서 voyage-4-large는 타협이 아니라 선두주자입니다.

우리가 프리미엄 임베딩에 비용을 지불하는 이유

검색을 하는 더 저렴한 방법이 있고, 그중 상당수는 무료입니다. BM25와 그 친척들 같은 렉시컬 검색은 키워드를 매칭하고, 로컬에서 실행되며, 비용이 들지 않습니다. BGE, Nomic, embeddinggemma 같은 오픈소스 임베딩 모델은 진짜로 괜찮은 시맨틱 검색을 제공하고, GPU 한 대 값으로 직접 호스팅할 수 있습니다. Maguyva도 무료인 쪽을 사용합니다. 모든 쿼리는 텍스트, AST, 그래프, 시맨틱 검색을 융합합니다. 우리가 아끼지 않는 부분은 시맨틱 레이어입니다.

우리는 무료 모델을 직접 호스팅하는 대신 프리미엄 임베딩인 voyage-4-large에 토큰당 비용을 지불하는데, 여기에는 두 가지 이유가 있습니다. 첫째, 코드가 “retry”라는 단어를 한 번도 쓰지 않고 backoff와 circuit breaker라고 말할 때, 키워드 검색만으로는 “우리가 재시도를 어디서 처리하나”에 답할 수 없습니다. 의미야말로 임베딩의 존재 이유이며, 우리가 다루는 도메인에서 오픈 모델은 프리미엄 모델에 뒤처집니다. 일반 텍스트에서는 몇 점 뒤처지고, 코드, 계약서, 재무 같은 틈새 영역에서는 더 크게 뒤처집니다. 둘째, 우리 경험상 검색 품질은 반대편의 모델보다 더 크게 최종 답변을 좌우합니다. 강력한 에이전트라도 잘못된 컨텍스트를 받으면 여전히 틀린 답을 하고, 애초에 주어지지 않은 문서는 절대 보지 못합니다.

그래서 프리미엄 임베딩은 우리가 인덱싱하는 모든 저장소와 문서에 비례해 늘어나는 토큰당 청구서이고, 우리는 이를 의도적으로 지불합니다. 사용자가 얻는 결과 — 올바른 함수 혹은 올바른 조항 — 를 위해서라면, 우리는 이 트레이드오프가 그럴 만한 가치가 있다고 생각합니다.

솔직한 부분

Voyage 자체 문서는 여전히 voyage-code-3을 코드 최적화 모델로 표시하고 있습니다. 그렇다면 왜 옮겼을까요?

우리가 벤더의 모델 표만이 아니라 공개 벤치마크를 읽었기 때문이고, 그 벤치마크가 코드 검색에서 voyage-4-large를 1위에 올려놓았기 때문입니다. 이는 미래를 내다보는 결정이었습니다. 더 새롭고 대체로 더 강력한 모델을 골라, 중요한 작업들에 대한 공개 리더보드로 그것을 검증하는 것입니다. 우리가 그 베팅을 편하게 할 수 있는 이유는 근거가 폭넓기 때문입니다. voyage-4-large는 코드에서만 이기는 것이 아니라, 재무, 헬스케어, 전체 검색에서도 선두를 달립니다.

묵묵히 받쳐주는 기반

시맨틱 검색, 태스크 컨텍스트 수집, 근거 기반 Q&A까지, 우리가 노출하는 모든 도구는 결국 검색으로 귀결됩니다. 검색기가 개선되면, 반대편의 에이전트는 더 나은 근거를 얻고, 잘못된 방향으로 덜 빠지며, 자신의 답을 올바른 코드에 — 혹은 올바른 조항이나 올바른 정책에 — 근거하게 됩니다. 더 날카로운 임베딩 모델은 화려한 기능이 아닙니다. 다른 모든 것을 받쳐주는 기반이며, 우리는 그 기반의 품질을 한 단계 높였습니다. 여러분은 눈치채지 못할 것입니다. 그것이 핵심입니다.

언어 재귀적 자기 개선: 약 280개 언어에 걸친 코드 인텔리전스 갈아내기

Tue, 26 May 2026 00:00:00 GMT

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

Maguyva는 약 280개 언어의 소스 코드에서 심볼, 참조, 의존성 그래프를 추출합니다. 각 언어는 커스텀 tree-sitter 핸들러 — 쿼리, 휴리스틱, 엣지 케이스 — 로 이루어져 있으며, 모든 핸들러는 저마다의 방식으로 미묘하게 틀릴 수 있습니다. 메서드 호출이 읽기(read)로 잘못 표기되는 경우. 함수가 잘못된 감싸는 스코프에 귀속되는 경우. 실제로는 존재하지 않는 관계가 만들어지는 경우.

이런 것들은 일일이 검수할 수 없습니다. 어떤 팀도 280개 문법 전체의 추출 결과를 읽고 나쁜 엣지를 짚어낼 수는 없습니다. 그래서 흥미로운 질문은 “우리 추출이 정확한가”가 아니라 “이 정도 규모에서 모든 루프에 사람이 개입하지 않고도 어떻게 틀렸다는 것을 알아낼 것인가”입니다. 우리의 답은 언어 재귀적 자기 개선입니다. 언어 에이전트가 주도하는 품질 루프, 판정자 역할을 하는 LLM, 그리고 우리가 계속 다시 배우는 하나의 규칙입니다. 초록불이 곧 정답은 아니라는 것이죠.

초록불이 곧 정답은 아니다

모든 언어는 픽스처(fixture) 스위트를 갖고 있으며, 릴리스 게이트는 이를 정확도, 구조적 무결성, 완전성, 품질, 성능이라는 다섯 가지 차원에서 채점합니다. 언어는 픽스처에서 정밀도 ≥ 0.95, 재현율 ≥ 0.99, F1 ≥ 0.97을 만족하고 통계적 신뢰를 위한 예상 엣지가 최소 20개 이상일 때만 GREEN이 됩니다. 그 밑으로는 YELLOW나 RED이며, 출시되지 않습니다.

그 게이트는 필요조건이지 충분조건은 아닙니다. 픽스처는 우리가 작성한 픽스처를 기준으로 검증됩니다. 즉 우리가 이미 생각해낸 케이스들을 담고 있을 뿐입니다. 핸들러는 자신의 픽스처에서는 완벽하면서도, 실제 코드에서만 나타나는 패턴 — 매크로 관용구, 제네릭 바운드 메서드, 아무도 픽스처를 작성하지 않은 언어 기능 — 을 여전히 망가뜨릴 수 있습니다. GREEN은 픽스처를 통과했다는 뜻입니다. 실제 저장소가 깔끔하게 추출된다는 뜻은 아닙니다. 그래서 루프는 픽스처를 뒤로하고 야생을 들여다봐야 합니다.

내부 루프: 무작위 점검, 판정, 수정, 증명

핵심 루프는 한 번에 한 언어씩 실행됩니다.

        ┌──────────────────────────────────────────────────────────┐
        │                                                          │
        ▼                                                          │
  1. corpus run ── clone real-world repos, extract relationships   │
        │                                                          │
        ▼                                                          │
  2. spot-check 100 edges (seed 42, then seed 123 to cross-check)  │
        │                                                          │
        ▼                                                          │
  3. LLM judge classifies every sampled edge:                      │
        CORRECT · FALSE_POSITIVE · TYPE_ERROR ·                    │
        SCOPE_ERROR · METADATA_ERROR                               │
        │                                                          │
        ▼                                                          │
  4. fix ONE thing — handler .py, .scm query, or config           │
        │                                                          │
        ▼                                                          │
  5. re-validate — F1 + re-classify + manifest diff (no regressions)│
        │                                                          │
   better? ──no──► revert, try a different fix ────────────────────┤
        │ yes                                                       │
        ▼                                                           │
  6. promote the fix into fixtures (a permanent regression guard) ──┘

이것이 헛돌지 않고 실제로 작동하게 만드는 몇 가지 요소가 있습니다.

판정자는 API 호출이 아니라 에이전트 자신입니다. “LLM 판정”이라고 할 때, 이는 언어 에이전트 스스로가 샘플링된 각 엣지를 실제 소스와 대조하며 읽고, 고정된 5가지 범주의 분류 기준으로 분류한다는 뜻입니다. 이 엣지는 올바른가, 거짓양성인가, 관계는 맞지만 타입이 틀렸는가, 잘못된 스코프에 붙었는가, 아니면 잘못된 메타데이터를 담고 있는가? 이 채점 기준이 게임의 전부입니다. “오류율 23%“라는 말은 그것이 실제 결함인지 판정자의 오산인지 알기 전까지는 무의미합니다.

한 가지를 고치고, 그다음 증명하라. 매 반복은 정확히 하나의 편집 가능한 자산만 변경한 뒤, 고정된 하니스를 다시 실행하고, F1이 개선되고 재분류 결과가 더 나아 보일 때만 그 변경을 유지합니다. 그렇지 않으면 되돌립니다. 추측에 기반한 수정을 한꺼번에 몰아넣거나 “더 나아질 것 같다”는 식은 없습니다. 변경은 스스로 자리를 증명하거나 사라집니다. 그리고 수정이 정착되면 픽스처 스위트로 승격됩니다. 그렇게 하면 그 수정이 고친 버그는 조용히 다시 돌아올 수 없습니다. 바로 이 승격 단계가 루프를 단순한 반복이 아니라 재귀적으로 만드는 부분입니다. 매 회차는 다음 회차의 검증 기준(오라클)을 더 단단하게 만듭니다.

우리가 계속 다시 배우는 교훈: 지표는 과잉 보고한다

여기 함정이 있고, 우리는 그 함정에 그대로 걸어 들어갔습니다. 2차적인 코퍼스 지표들 — 추출된 대상이 해석 가능한 심볼을 갖지 못하는 빈도, 얼마나 많은 심볼이 “고아”처럼 보이는지 등등 — 은 문제를 크게 과잉 보고합니다. 이들은 대부분 버그가 아니라 패러다임의 부산물입니다.

가장 명확한 예: llvm은 한때 “심볼 없는 소스” 비율이 73%로 나타나 재앙 수준으로 낙인찍힌 적이 있습니다. 파고들어 보니 실제 정확도는 **98.5%**였습니다. “누락된 심볼”의 거의 전부는 정당한 외부 참조 — 표준 라이브러리, 프레임워크, 저장소 밖에 존재하는 코드로의 호출 — 였습니다. 그 지표는 핸들러의 결함이 아니라 언어 자체의 속성을 측정하고 있었던 것입니다. Zig, COBOL, Odin 같은 언어는 65~70%의 “고아” 비율을 보이면서도 완전히 정확합니다. COBOL은 실제 오류가 0건이었습니다.

만약 그 수치들이 작업을 이끌게 두었다면, 우리는 이미 옳았던 핸들러를 “고치는” 데 몇 주를 쓰면서 조용하지만 진짜인 버그가 있는 언어들은 무시했을 것입니다. 결론은 단호합니다. 집계 지표는 기껏해야 대략적인 분류(triage) 신호일 뿐입니다. 진짜 품질 신호는 엣지 분류를 곁들인 무작위 점검입니다. 실제 저장소의 실제 엣지들을 하나하나 살펴보고 판정하는 것이죠. 직관보다 데이터를 우선하되, 어떤 데이터가 진실을 말하고 있는지 알고 난 뒤에야 그렇습니다.

외부 루프: 마라톤이 아니라 플릿

280개 언어를 한 번에 하나씩 처리한다면 영원히 끝나지 않을 것입니다. 그래서 내부 루프는 여러 언어를 병렬로 실행하는 외부 루프로 감싸여 있습니다.

   pick a wave of near-GREEN / high-error languages
        │
        ▼
   fan out 10–15 agents, each ISOLATED in its own git worktree,
   each grinding ONE language, committing to its own branch
        │
        ▼
   orchestrator integrates serially: file-scoped apply, then
   `manifest diff` — any cross-language regression blocks the batch
        │
        ▼
   gated push (reviewed and confirmed) ──► rotate to the next wave

각 에이전트는 서로를 밟지 않도록 일회용 워크트리에서 작업합니다. 오케스트레이터는 이들의 수정 사항을 한 번에 하나씩 통합하며, 매번 전체 매니페스트 리그레션 체크를 거칩니다. 자기 언어에는 도움이 되지만 다른 세 언어를 조용히 망가뜨리는 변경은 반영되지 않습니다. 통합은 무언가가 푸시되기 전에 게이트를 거치고 확인됩니다. 리그레션 게이트는 무엇이 안전한지를 결정하고, 무엇이 출시되는지는 여전히 사람이 결정합니다. 그런 다음 풀(pool)은 다음 언어 집합으로 순환하고, 전체 과정이 다시 실행됩니다.

아직 완벽하지 않은 것들

판정자도 틀릴 수 있고, 그 틀림에는 방향성이 있습니다. 컨텍스트가 너무 적은 상태로 실행되는 에이전트는 과잉 보고하는 경향이 있습니다. 한 배치에서는 8개 언어가 5~20%의 오류율로 플래그되었지만, 살펴보니 실제 언어별 버그는 단 하나였습니다. 나머지는 그 언어 고유의 의미론을 놓친 판정자의 실수였습니다(한 줄의 소스가 정당하게 여러 엣지를 만들어내는 경우, 파라미터 바인딩이 대입으로 모델링되는 경우, 식별자마다 참조가 생기는 언어 등). 그래서 우리는 두 개의 시드로 샘플링하고 교차 검증하며, 판정자와 픽스처 사이의 불일치를 확정된 판결이 아니라 가장 흥미로운 신호로 취급합니다. 때로는 픽스처 쪽이 틀린 것일 수도 있으니까요.

우리는 또한 목표에 대해 솔직합니다. 목표는 명백히 실제 오류 0건입니다. 하지만 “0”은 언어별로 조금씩 갈아나가는 방향일 뿐, 한 번에 체크되는 항목이 아닙니다. 늘 또 다른 관용구를 가진 또 다른 저장소가 있으니까요.

주장하는 것이 아니라 증명해내는 것

Maguyva가 에이전트를 위해 하는 모든 일 — 심볼 찾기, 의존성 추적, 인용된 코드로 질문에 답하기 — 은 그 아래 깔린 추출이 옳다는 전제 위에 서 있습니다. 280개 언어에 걸쳐 “옳다”는 것은 주장할 수 있는 것이 아닙니다. 실제 코드를 상대로 끊임없이 증명해내야 하는 것입니다. 이 루프가 바로 우리가 그것을 증명하는 방법입니다. 자기 지표를 의심하고, 모든 변경을 증명하며, 각 수정을 다음 리그레션에 대한 보호막으로 바꾸는 자율적인 무작위 점검-수정 순환입니다. 화려하지 않습니다. 하지만 우리가 “여러분의 언어를 지원합니다”라고 말하고 그 말을 진심으로 할 수 있게 해주는 작업입니다. 초록불은 쉽습니다. 정답은 증명해내야 합니다.

다중 모달 융합 검색: 모든 쿼리에 맞는 검색기를 고르는 법

Wed, 15 Apr 2026 00:00:00 GMT

과거 설계 안내: 이 2026년 4월 글은 당시의 라우팅 설계를 설명하며, 현재 기본 동작을 설명하는 글이 아닙니다. 아래의 9월 정정은 측정 관련 주장만 다룹니다. 현재 라우팅, 프리셋, 명시적 모달리티 제어는 작동 방식을 참고하세요.

검색 쿼리는 하나의 단일한 것이 아닙니다.

“parseConfig는 어디서 정의되었나”는 정확한 심볼을 원합니다. 하나의 정밀한 위치를, 빠르게. “인증은 어떻게 동작하나”는 의미를 원합니다. 하나의 개념을 설명하는 관련 코드의 퍼짐을요. “이 함수를 바꾸면 무엇이 깨지나”는 의존성 그래프를 원합니다. “문자열 ECONNREFUSED를 찾아줘”는 리터럴 일치를 원합니다. 영리한 것은 필요 없이요.

grep은 리터럴 일치에 탁월하고 일부 참조 탐색에도 유용하지만, 의존성 그래프도 아니고 의미를 이해하지도 못합니다. 임베딩은 시맨틱 측면을 다루지만, 정확한 문자열이나 영향도 분석에는 잘못된 도구입니다. 대부분의 코드 검색 도구는 하나의 엔진을 고르고 모든 쿼리가 그 선택과 함께 살아가게 만듭니다. Maguyva는 고르지 않습니다. 어떤 종류의 질문을 받았는지 파악한 뒤, 그 질문에 걸맞은 비율로 네 가지 검색기를 섞습니다.

네 가지 방식

내부적으로는 코드를 찾는 네 가지 독립적인 방법이 있습니다.

semantic (시맨틱) — Voyage 바이너리 임베딩을 이용한 벡터 검색. 의미로 코드를 찾습니다.
text (텍스트) — 트라이그램 매칭. 리터럴, 오류 문자열, 정확한 식별자를 찾습니다.
structural (구조적) — AST 쿼리. 정의, 시그니처, 언어 구성 요소를 찾습니다.
graph (그래프) — 의존성 그래프. 호출자, 피호출자, 영향 범위를 찾습니다.

각각은 서로 다른 부류의 질문에 강합니다. 관건은 눈앞의 쿼리에 각각을 얼마나 신뢰할지 결정하는 것입니다.

의도 분류

어떤 검색이든 실행되기 전에, 가벼운 분류기가 쿼리를 신뢰도 점수와 함께 여섯 가지 의도 중 하나로 분류합니다. 이는 의도적으로 저렴합니다. 순서가 있는 휴리스틱으로, 첫 매치가 이기는 방식입니다. 핫 패스에서 실행되고 1~2밀리초만 추가되기 때문입니다.

def , class , func , import … 로 시작 → find_definition (신뢰도 0.95)
“who calls”(호출자), “usages of”(사용처), “references to”(참조) → find_references (0.90)
“impact”(영향), “blast radius”(영향 범위), “what depends on”(무엇이 의존하는지) → impact_analysis (0.90)
인용된 "string"이나 traceback 같은 오류 토큰 → exact_match (0.85~0.90)
CamelCase나 snake_case 형태의 식별자 → find_definition (0.60~0.80)
“how”(어떻게), “why”(왜), “explain”(설명), “architecture”(아키텍처) → understand_code (0.75)
아무것도 일치하지 않음 → understand_code, 낮은 신뢰도 (0.40)

각 의도는 네 가지 방식에 걸친 가중치 프로필을 갖습니다. 실제 수치는 다음과 같습니다.

의도	semantic	text	structural (AST)	graph
find_definition	0.2	0.1	0.6	0.1
find_references	0.1	0.2	0.2	0.5
understand_code	0.5	0.2	0.2	0.1
find_similar	0.4	0.3	0.2	0.1
impact_analysis	0.1	0.1	0.1	0.7
exact_match	0.0	0.9	0.1	0.0

그래서 “parseConfig는 어디서 정의되었나”는 AST에 크게 의존합니다(0.6). “인증은 어떻게 동작하나”는 시맨틱 벡터에 의존합니다(0.5). “무엇이 이것에 의존하나”는 거의 전부 그래프입니다(0.7). “ECONNREFUSED를 찾아줘”는 거의 전부 트라이그램입니다(0.9). 임베딩 모델은 완전히 꺼집니다. 정확한 문자열에는 시맨틱 유사도가 정확히 잘못된 도구이기 때문입니다.

빠른 경로와 융합된 경로

분류기가 확신할 때 — 점수 ≥ 0.85 — 이고 쿼리가 일반적인 것이라면, Maguyva는 융합을 완전히 건너뛰고 단일한 지배적 방식으로 곧장 라우팅합니다. “X는 어디서 정의되었나”는 네 개의 검색기가 필요 없습니다. 지금 당장 AST 인덱스가 필요할 뿐입니다. 이 직접 경로는 fusion_strategy: "direct"로 다시 보고됩니다.

모호한 것은 모두 융합을 거칩니다. 네 가지(혹은 기본 프리셋에서는 세 가지) 방식이 병렬로 실행되어 각자 자신의 순위 목록을 반환하고, 우리는 이를 결합합니다.

가중 상호 순위 융합(Weighted Reciprocal Rank Fusion)

이질적인 검색기들을 융합하는 것은 말처럼 쉽지 않습니다. 코사인 유사도 0.82와 트라이그램 점수 137, 그래프 중심성 0.004는 같은 척도 위에 있지 않기 때문에 그냥 더할 수 없습니다. 상호 순위 융합(Reciprocal Rank Fusion)은 원본 점수를 버리고 각 엔진이 매긴 순위만 남김으로써 이 문제를 피해 갑니다. 하나의 방식에서 나오는 결과의 기여도는 다음과 같습니다.

contribution = weight × 1 / (k + rank + 1)

여기서 rank는 해당 방식의 목록에서의 위치이고, k는 스무딩 상수입니다. 둘 이상의 엔진이 찾아낸 모든 결과에 대해서는 방식들에 걸쳐 기여도가 합산됩니다. 검색기들 사이의 합의는 자연스럽게 위로 떠오릅니다. 우리는 기본 프리셋에서 k = 40을, thorough에서는 60을 사용합니다(quick은 시맨틱 전용으로 실행되므로 그곳에서는 융합이 전혀 작동하지 않습니다). 원조 RRF 연구는 범용 검색에 대해 k = 60을 채택했지만, 우리는 조금 더 날카로운 값을 기본값으로 삼아 방식들 사이의 상위권 합의에 조금 더 무게를 둡니다. 그리고 이를 수동으로 조정하는 것은 권장하지 않습니다.

여기에 더해, 결과는 그래프 중요도 부스트를 갖습니다. 허브 — 전체 코드베이스가 의존하는 함수 — 는 동일한 텍스트 관련성이라도 눈에 띄지 않는 말단 노드보다 순위가 높아야 하므로, 우리는 각 기여도에 다음을 곱합니다.

boost = min(1 + 0.3 × ln(1 + centrality), 1.5)

중심성은 파이프라인이 미리 계산한 PageRank/차수 지표에서 나오며, 부스트는 1.5배로 제한되어 인기 있는 함수가 더 관련성 높은 무명 함수를 완전히 파묻을 수 없게 합니다. 마지막으로 우리는 벤더, 빌드, 아카이브 경로의 결과 순위를 낮추고, 파일당 최선의 청크로 중복을 제거합니다.

아직 완벽하지 않은 것

의도 분류기는 학습된 모델이 아니라 정규식의 집합입니다. 일반적인 쿼리 형태를 휴리스틱으로 처리하고, 모호한 쿼리는 understand_code와 시맨틱에 무게를 둔 조합으로 폴백합니다. 이 글의 이전 버전은 결과가 없는 검색의 비율을 약 15%에서 5% 미만으로 낮춘 것을 이미 달성한 개선으로 설명했습니다. 실제로 2025년 12월 제안서에 기재된 것은 추정 기준치와 목표였으며, 이를 뒷받침하는 쿼리 집합이나 측정 기록은 제공되지 않았습니다. 개선을 달성했다는 해당 주장을 철회합니다. 원본 근거와 정정 사항을 확인하세요. 분류기를 학습된 모델로 교체하지 않은 이유는 저렴한 현행 버전이 빠르고 의도된 라우팅 역할에 충분하며, 틀렸지만 자신만만한 분류기보다 정직한 폴백이 낫기 때문입니다. 가중치 자체도 수동으로 고른 사전 설정값이지, 수집하지 않는 클릭 데이터에서 학습한 것이 아닙니다.

도구가 아니라 질문을 던지세요

에이전트는 grep을 써야 할지, 임베딩을 써야 할지, 호출 그래프를 써야 할지 알아야 할 필요가 없어야 합니다. 그저 평범한 말로 질문을 던지고 올바른 답을 받아야 합니다. 다중 모달 융합이야말로 find_symbol, 시맨틱 검색, 의존성 분석이 하나의 쿼리 인터페이스 뒤에 자리할 수 있게 해주는 것입니다. 시스템이 질문의 형태를 읽고 그에 맞는 검색기를 조용히 조립합니다. 임베딩을 채점하는 모델도 중요하지만, 언제 그것을 쓰지 않을지 아는 것도 마찬가지로 중요합니다. 각 쿼리에 맞는 도구를 고르는 것은 그 자체로 하나의 품질이며, 우리는 이를 호출자에게 떠넘기기보다는 우리가 책임지고 싶습니다.

// you bring the question. it brings the tools.

에이전트 관찰가능성: 훅, Alloy, 그리고 Grafana

Tue, 24 Mar 2026 00:00:00 GMT

에이전트 시스템은 이상한 방식으로 고장 납니다.

때로는 모델이 문제입니다. 때로는 도구가 문제입니다. 때로는 MCP 서버는 멀쩡한데, 에이전트가 엉뚱한 전문 에이전트를 골랐거나, 세션의 절반을 예상치 못한 셸 작업에 쓰거나, 겉으로는 생산적으로 보이는 루프 안에서 조용히 비용만 태우기도 합니다.

이 차이를 볼 수 없다면, 여러분은 에이전트 시스템을 실제로 운영하는 것이 아니라 그저 추측하고 있는 것입니다.

그래서 우리는 우리 자신의 워크플로를 위한 관찰가능성 스택을 만들었습니다. Claude Code, Codex, Claude 훅 이벤트, Codex 알림(notify) 이벤트, 네이티브 OpenTelemetry, 그리고 반대편의 Grafana Alloy와 Grafana Cloud까지요.

흥미로운 부분은 “대시보드를 만들었다”가 아닙니다. 흥미로운 부분은 단일 피드로는 전체 그림을 얻을 수 없었기 때문에 텔레메트리를 두 개의 서로 다른 스트림으로 나눠야 했다는 점입니다.

문제: 에이전트 텔레메트리는 파편화되어 있다

최신 코딩 에이전트는 이미 어느 정도의 텔레메트리를 내보냅니다. 도움은 되지만 충분하지는 않습니다.

네이티브 OTEL은 다음과 같은 질문에 답하기 좋습니다.

요청을 몇 번 보냈는가?
세션 비용은 얼마였는가?
스팬과 트레이스는 어디에 있는가?
지연 시간이 튀었는가?

반면 다음과 같은 질문에는 훨씬 취약합니다.

에이전트가 어떤 MCP 서버에 의존했는가?
이 실패는 Bash, 내장 파일 도구, 아니면 MCP 호출에서 발생했는가?
실제로 어떤 스킬이 활성화되었는가?
어떤 종류의 서브에이전트가 디스패치되었는가?
세션이 유의미한 작업을 하고 있었는가, 아니면 그냥 헛돌고 있었는가?

이 두 번째 부류의 질문은 트레이스보다 훅에 더 가까이 있습니다.

하지만 그 반대도 성립합니다. 가장 중요한 성능 관련 질문 중 일부는 훅보다 트레이스에 더 가까이 있습니다.

지연 시간이 실제로 어디서 쌓였는지, 어떤 스팬이 느렸는지, 아니면 세션이 도구 실행이 아니라 모델 호출에 시간을 태웠는지 알고 싶다면, 시맨틱 이벤트뿐 아니라 트레이스 데이터도 필요합니다.

최종적으로 도달한 아키텍처

우리는 두 개의 텔레메트리 경로를 나란히 운영합니다.

Claude Code
  native OTEL -> Alloy -> Grafana Cloud
  hooks        -> send_event.py -> Grafana Cloud Loki

Codex
  native OTEL -> Alloy -> Grafana Cloud
  notify hook -> codex_notify.py -> shared Loki schema

이 분리는 의도적입니다.

또한 비대칭적이기도 합니다. Claude Code는 훨씬 풍부한 라이프사이클 훅 인터페이스를 제공합니다. Codex는 네이티브 OTEL과 알림(notify) 인터페이스를 제공하므로, 우리는 두 런타임이 동일한 제어 수단을 노출한다고 가정하는 대신 더 얇은 턴 완료 이벤트를 동일한 로그 스키마로 정규화합니다.

네이티브 OTEL은 기본 스트림을 제공합니다. 런타임 자체에서 나오는 로그와 트레이스, 그리고 런타임이 실제로 내보내는 경우의 메트릭입니다.

훅과 알림 이벤트는 시맨틱 레이어를 제공합니다. PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SubagentStop, SkillActivated 같은 것들, 그리고 에이전트 동작을 디버깅할 때 우리가 실제로 신경 쓰는 분류된 메타데이터입니다. 여기서는 Claude Code가 더 풍부한 이벤트 스트림을 제공합니다. Codex는 더 얇지만 여전히 유용한 정규화된 스트림을 제공합니다.

훅이 애초에 존재하는 이유

우리의 훅 파이프라인은 이벤트가 Loki에 도달하기 전에 이를 보강합니다.

단순히 “도구가 실행됐다”라고만 말하는 대신, 우리는 이벤트를 다음과 같은 필드로 분류합니다.

tool_type: builtin, mcp, skill, agent, bash
mcp_server: 어떤 MCP 백엔드가 호출을 처리했는지
bash_cli: 셸 명령어 계열
subagent_type: 어떤 종류의 전문 에이전트가 디스패치되었는지
agent_tool: 출처가 Claude Code인지 Codex인지

이는 운영상 중요한 질문들을 던질 수 있다는 뜻입니다.

{service_name="claude-code-hooks"} | agent_tool="codex-cli"
{service_name="claude-code-hooks"} | tool_type="mcp"
{service_name="claude-code-hooks"} | json | bash_cli="git"

이런 필드들은 겉치레용이 아닙니다. “에이전트가 느리게 느껴졌다”와 “에이전트가 지난 10분을 도구 실패율이 높은 셸 위주의 git 작업에 썼다”의 차이를 만들어내는 것들입니다.

보기보다 이상하지 않은 구현 세부 사항 하나: 공유 Loki 스트림은 이벤트가 Codex에서 왔을 때도 여전히 service_name="claude-code-hooks"를 레이블로 사용합니다. 런타임 간의 진짜 구분은 agent_tool에서 일어납니다.

Alloy가 중간에 자리하는 이유

이 구성에서 Grafana Alloy는 단순한 포워더가 아닙니다. 정책 경계입니다.

우리는 Claude Code와 Codex의 네이티브 OTEL 스트림을 localhost:4318의 로컬 Alloy 프록시로 향하게 한 뒤, Alloy가 페이로드를 정리하게 하고 나서야 Grafana Cloud로 전달합니다.

이것이 중요한 이유는, 가공되지 않은 원본 에이전트 텔레메트리가 분석에는 유용하지만 인덱싱된 레이블로는 끔찍한 고카디널리티 필드로 가득하기 때문입니다.

session_id
prompt_id
토큰 수
소요 시간
도구 파라미터 블롭

모든 것을 인덱싱하면 레이블 폭발과 끔찍한 하루를 맞이하게 됩니다.

그래서 Alloy는 우리를 위해 세 가지 일을 합니다.

아주 적은 수의 저카디널리티 레이블만 인덱싱된 상태로 유지합니다.
시끄럽지만 유용한 필드는 구조화된 메타데이터로 옮깁니다.
순수한 노이즈는 완전히 버립니다.

핵심 아이디어는 단순합니다. 더 많이 관찰하고, 더 적게 인덱싱하라.

훅 스트림이 Alloy를 우회하는 이유

훅 스트림은 이미 Loki에 맞게 형태가 잡혀 있습니다.

send_event.py가 이벤트를 밀어넣을 때쯤이면, 어떤 필드가 레이블 처리를 받아야 하고 어떤 필드가 구조화된 JSON 본문에 속해야 하는지 이미 결정되어 있습니다. 이 스트림은 Alloy를 다시 거치지 않고 곧바로 Grafana Cloud의 OTLP 게이트웨이로 향합니다.

그래서 시스템은 명확한 역할 분담을 갖게 됩니다.

Alloy는 가공되지 않은 네이티브 OTEL 스트림을 길들입니다.
훅 보강은 시맨틱 이벤트를 쿼리 가능하게 만듭니다.

이는 모든 것을 하나의 경로로 억지로 밀어넣으려는 것보다 아키텍처를 더 단순하게 유지합니다.

대시보드가 실제로 보여주는 것

아래 스크린샷은 우리 에이전트 워크플로 뒤에 있는 관찰가능성 대시보드 중 하나에서 가져온 것입니다. 벤치마크가 아니며, 수치는 특정 시점의 스냅샷일 뿐입니다. 중요한 것은 데이터의 형태입니다. 활동 피드, 도구 호출, 실패, 프롬프트, 그리고 에이전트별, 내장 도구별, MCP 사용별, 셸 명령별, 스킬별 분류입니다.

유용한 점은 이 대시보드가 나머지 에이전트 텔레메트리와 동일한 Grafana 스택 위에 있다는 것입니다. 우리는 출처 에이전트와 도구 계열로 필터링할 수 있고, 시스템마다 다른 관찰가능성 이야기를 새로 만들어낼 필요 없이 런타임 전반을 살펴볼 수 있습니다.

우리 에이전트 워크플로 뒤에 있는 실시간 대시보드 중 하나입니다. 이 스크린샷은 다른 에이전트 런타임과 시스템의 텔레메트리도 함께 수신하는 공유 Grafana 스택의 한 단면일 뿐입니다. 전체 해상도 버전을 보려면 이미지를 클릭하세요.

트레이스가 처음 보이는 것보다 더 중요한 이유

로그는 어떤 범주의 작업이 일어났는지 알려줍니다. 트레이스는 그 작업이 시간에 따라 어떻게 펼쳐졌는지 알려줍니다.

이 구분은 에이전트 시스템에서 중요한데, “느리다”는 표현이 실질적인 도움이 되기에는 너무 막연하기 때문입니다.

트레이스는 고통의 원인이 다음 중 무엇이었는지 알려줄 수 있습니다.

모델 지연 시간
도구 실행 시간
반복된 재시도
유독 비용이 큰 하나의 MCP 상호작용
개별적으로는 무해해 보였던 작은 작업들의 긴 꼬리

실제로 우리는 훅 스트림과 Tempo 트레이스를 함께 사용합니다.

훅 로그는 답합니다. 어떤 종류의 일이 일어났는가?
트레이스는 답합니다. 시간이 어디로 갔는가?

이 조합이 바로 관찰가능성을 대시보드에서 설명으로 바꿔주는 것입니다.

Codex가 들어맞는 지점

Codex는 동일한 스택의 일부이지만 Claude Code와 똑같지는 않습니다.

Codex를 위해 우리는 두 가지를 연결합니다.

Codex의 네이티브 OTEL을 Alloy로
턴 완료를 우리가 훅 이벤트에 사용하는 것과 동일한 Loki 스키마로 매핑하는 알림(notify) 웹훅을 codex_notify.py로

이는 동일한 로그 스트림 안에서 agent_tool="codex-cli" 같은 통합 필터를 가능하게 해줍니다.

한계도 솔직히 짚어보면: Codex의 알림 페이로드는 동일한 종류의 통합 인터페이스가 아니기 때문에 현재 Claude Code의 훅 페이로드보다 얇습니다. 오늘날 우리 구성에서 Codex의 턴 완료는 공유 스키마로 정규화될 수 있지만, 도구별로 풍부한 추출은 알림 브리지보다 네이티브 OTEL 스트림에서 여전히 더 낫습니다.

이것이 이 글을 쓰지 말아야 할 이유는 아닙니다. 오히려 이 글의 요점입니다. 진짜 관찰가능성 시스템은 불완전한 신호들로 조립됩니다.

MCP를 통한 Grafana가 판을 바꾼다

더 큰 변화는 Grafana가 더 이상 사람이 브라우저에서 방문하는 장소만이 아니라는 점입니다.

이 저장소에서 우리는 Grafana를 MCP를 통해서도 노출합니다. 즉 에이전트가 사람이 먼저 대시보드를 수동으로 살펴보기를 기다리는 대신, Loki, Prometheus, Tempo를 직접 쿼리할 수 있다는 뜻입니다.

이는 관찰가능성을 워크플로에 대한 능동적인 입력으로 바꿔놓습니다.

에이전트는 다음과 같이 물을 수 있습니다.

지난 한 시간 동안 어떤 도구 계열이 가장 많이 실패했는가?
어떤 MCP 서버가 세션을 지배했는가?
최근 변경이 도구 실패를 줄였는가, 아니면 그저 같은 실수를 더 셸 위주의 경로로 옮겼을 뿐인가?
어떤 트레이스가 가장 높은 지연 시간이나 반복된 재시도를 보이는가?

이것을 갖추면 자기 개선 루프에 매우 가까워집니다.

대시보드에서 피드백 루프로

이 부분이 우리가 가장 흥미롭게 여기는 지점입니다.

관찰가능성 스택이 에이전트 레이어에서 쿼리 가능해지는 순간, 텔레메트리는 수동적인 보고 수단이기를 멈추고 제어 신호가 됩니다.

루프는 이렇게 생겼습니다.

에이전트 활동이 트레이스, 메트릭, 보강된 훅 로그를 내보냅니다.
Grafana가 그 증거를 Loki, Tempo, 그리고 메트릭이 존재하는 Prometheus에 저장합니다.
에이전트가 Grafana MCP를 통해 그 증거를 쿼리합니다.
시스템이 나쁜 도구 조합, 취약한 스킬, 부실한 라우팅, 혹은 피할 수 있는 실수를 계속 만들어내는 셸 위주 워크플로를 식별합니다.
에이전트나 운영자가 프롬프트, 에이전트 설정, 스킬 설명, 라우팅 규칙, 혹은 도구 접근 권한을 조정합니다.
다음 세션은 새로운 텔레메트리 형태를 만들어내고, 순환이 반복됩니다.

이것이 “흥미로운 대시보드”에서 “측정 가능한 개선 시스템”으로 나아가는 방법입니다.

목표는 하나의 도구 범주를 극대화하는 것이 아닙니다. 실제로 수행되는 작업에 맞는 CLI, 내장 도구, MCP 호출, 스킬의 올바른 조합에 도달하는 것입니다.

이것으로 답할 수 있게 되는 것들

두 런타임이 동일한 Grafana 스택에 도달하면, 우리는 운영상의 질문에 훨씬 빠르게 답할 수 있습니다.

실패가 하나의 도구 계열에 집중되어 있는가?
더 상위 수준의 도구가 존재해야 할 자리에서 셸 위주 워크플로가 피할 수 있는 실수를 만들어내고 있는가?
어떤 MCP 서버가 작업 부하를 짊어지고 있는가?
유의미한 진전을 만들어내지 못하는 에이전트 활동에 비용을 지불하고 있는가?
세션이 모델, 도구, 혹은 오케스트레이션 레이어 때문에 상태가 나쁜가?

이는 특히 다중 에이전트 워크플로에서 유용한데, 여기서는 “에이전트가 바빴다”는 말이 거의 아무것도 알려주지 않기 때문입니다.

특정 전문 에이전트가 계속 디스패치되면서 높은 실패율을 만들어낸다면, 그것은 라우팅이나 프롬프트 설계 문제입니다.

하나의 MCP 서버가 모든 호출을 지배한다면, 이는 좋은 아키텍처일 수도 있고 나머지 전부가 쓸모없는 짐이라는 신호일 수도 있습니다.

비용은 높게 유지되는데 도구 실패가 급증한다면, 이는 품질 문제가 아니라 운영 문제입니다.

더 상위 수준의 도구가 존재해야 할 자리에서 셸 작업이 예측 가능하고 피할 수 있는 방식으로 계속 실패한다면, 이는 제품 신호입니다.

하나의 스킬이 끊임없이 활성화되지만 결과를 개선하지 못한다면, 이는 프롬프트나 라우팅 신호입니다.

진짜 교훈

여기서 더 깊은 교훈은 에이전트 관찰가능성에 런타임 텔레메트리와 워크플로 텔레메트리가 모두 필요하다는 것입니다.

런타임 텔레메트리는 시스템이 무엇을 했는지 알려줍니다.

워크플로 텔레메트리는 에이전트가 스스로 무엇을 하고 있다고 생각했는지 알려줍니다.

우리에게는 둘 다 필요합니다.

트레이스와 카운터만 유지한다면 시맨틱 레이어를 놓치게 됩니다. 훅 이벤트만 유지한다면 지연 시간, 스팬, 그리고 더 넓은 런타임 그림을 놓치게 됩니다.

그리고 둘 다 유지하면서도 이를 에이전트 레이어로 다시 피드백하지 않는다면, 여러분은 모니터링을 갖춘 것이지 적응을 갖춘 것이 아닙니다.

이 조합이야말로 시스템을 운영할 만큼 설명 가능하게 만들고, 개선할 만큼 조정 가능하게 만드는 것입니다.

아직 완벽하지 않은 것들

여전히 거친 부분들이 남아 있습니다.

모든 훅 이벤트가 우리가 원하는 소요 시간과 토큰 데이터를 포함하지는 않습니다.
최고의 타이밍 뷰 중 일부는 여전히 훅 로그가 아니라 Tempo 트레이스에서 나옵니다.
오늘날 Codex는 보강된 이벤트 스트림에서 Claude Code보다 시맨틱 측면이 덜 풍부합니다.
대시보드 스크린샷은 다듬어진 마케팅 자료가 아니라 실시간 운영 화면입니다.

마지막 항목은 의도적입니다. 우리는 에이전트 시스템이 마법처럼 스스로 설명된다고 가장하기보다는 진짜 계기판을 보여주는 쪽을 택합니다.

이것이 Maguyva에 중요한 이유

Maguyva는 에이전트에게 더 나은 코드 인텔리전스를 제공하는 것에 관한 것입니다. 하지만 에이전트가 실제로 유용한 작업을 하기 시작하면, 새로운 요구 사항이 즉시 나타납니다. 에이전트가 어떻게 행동하고 있는지 볼 수 있어야 한다는 것이죠.

검색 품질, 라우팅 품질, 도구 선택, 컨텍스트 효율성 모두가 관찰 가능한 문제가 됩니다.

이것이 우리가 이 글을 쓸 가치가 있다고 생각하는 이유입니다. 미래의 에이전트 스택은 단순히 프롬프트와 도구만이 아닙니다. 프롬프트, 도구, 그리고 전체 시스템이 제대로 작동하는지 알려주는 계측 레이어까지 포함합니다.

진지한 에이전트 워크플로를 구축하고 있다면, 관찰가능성은 선택적인 인프라가 아닙니다. 제품의 일부입니다.

루프 마이닝: 변경 사항이 조직의 기억이 되는 과정

Tue, 03 Feb 2026 00:00:00 GMT

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

모든 엔지니어링 팀은 같은 문제를 마주합니다. 변경은 끊임없이 일어나지만, 그 변경 뒤에 있는 이유는 사라집니다. 6개월 뒤 누군가 “왜 우리가 파이프라인 단계에 DuckDB를 채택했지?“라고 물으면, 그 답은 그 결정을 내린 사람의 머릿속에만 존재합니다. 그 사람이 아직 있다면 말이죠.

우리는 이 고리를 닫는 마이닝 워크플로를 만들었습니다. 변경 사항은 git 커밋을 거쳐 흐르고, 우리의 마이닝 파이프라인에서 처리되며, 구조화된 체인지로그 항목과 아키텍처 결정 기록이 되고, 그런 다음 CLI 쿼리를 통해 우리 AI 에이전트에게 다시 피드백됩니다. 결과는 사람과 AI 모두가 접근할 수 있는 조직의 기억입니다.

문제: 결정은 증발한다

전형적인 시나리오를 생각해봅시다. 어떤 개발자가 커밋합니다.

feat(canonical): add DuckDB runtime for pipeline stages

이 커밋은 중요한 아키텍처적 선택을 대표합니다. 팀은 옵션을 평가하고, 트레이드오프를 고려한 뒤, 특정한 이유로 DuckDB에 정착했습니다. 하지만 그 모든 맥락은 다음과 같은 곳에 존재합니다.

슬랙 스레드(아마 삭제되었을)
누군가의 기억(분명 희미해지고 있는)
코드 안의 주석(운이 좋다면 어쩌면)

3개월 뒤, 새로 합류한 팀원이 묻습니다. “이 새 단계에는 DuckDB를 써야 하나요, SQLite를 써야 하나요?” 조직의 기억이 없으면, 그들은 바퀴를 재발명하거나 일관성 없는 선택을 하게 됩니다.

루프: 커밋에서 컨텍스트로

우리의 마이닝 워크플로는 git 히스토리를 쿼리 가능한 지식으로 변환합니다.

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

핵심 통찰은 이렇습니다. 체인지로그와 아키텍처 결정 모두 동일한 git 히스토리에서 흘러나와, 통합된 파이프라인을 거쳐 처리됩니다. 이는 아무것도 빠져나가지 않도록 보장합니다.

마이닝이 작동하는 방식

1단계: 인덱스 동기화

uv run orkestra mine sync

이 명령은 git 히스토리를 스캔하고 모든 커밋의 인덱스를 만듭니다. 각 커밋에서 구조화된 신호를 추출합니다.

컨벤셔널 커밋 타입 (feat, fix, chore, docs)
스코프(어떤 패키지나 영역인지)
브레이킹 체인지 마커
수정된 파일과 복잡도 지표

2단계: 커버리지 상태 확인

uv run orkestra mine status

현재 우리의 상태는 다음과 같습니다.

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15,637개 커밋이 처리되었습니다. 476개는 아키텍처 결정이 되었습니다. 6,799개는 체인지로그 항목이 되었습니다. 모든 커밋이 분류되었습니다.

3단계: 검토 후보 가져오기

uv run orkestra mine candidates --limit 50 --full

이는 아직 처리되지 않은 커밋을 분류에 필요한 전체 맥락과 함께 표면화합니다.

{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

이 신호들은 분류를 안내하는 데 도움이 됩니다. is_releasable_type: true는 이것이 체인지로그에 실려야 함을 시사합니다. 큰 삽입 라인 수와 인프라 파일들은 이것이 아키텍처 결정이기도 할 수 있음을 시사합니다.

4단계: 커밋 분류

여기서 두 갈래로 나뉩니다. 체인지로그 항목과 아키텍처 결정입니다.

체인지로그 항목의 경우:

uv run orkestra mine classify abc123 --changelog added

이는 커밋 abc123가 체인지로그의 “Added” 카테고리에 실려야 함을 기록합니다.

아키텍처 결정의 경우:

먼저 실제 결정 ID를 받습니다.

uv run orkestra registry decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

그런 다음 그 결정 ID로 분류합니다.

uv run orkestra mine classify abc123 --decision DEC-PL-143

이는 커밋을 생성되거나 업데이트될 결정 기록에 연결합니다.

배치 처리의 경우 (우리가 실제로 하는 방식):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

JSONL 포맷은 한 번의 패스로 두 도메인을 모두 지원합니다.

{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

5단계: 출력 렌더링

uv run orkestra registry changelog render --package <pkg>

이는 원장(ledger)으로부터 패키지별 CHANGELOG.md 파일을 생성합니다. 체인지로그는 파생 산출물입니다. 삭제해도 원본 원장에서 완벽하게 다시 생성됩니다.

결정 기록의 구조

추출된 결정은 풍부한 메타데이터를 가진 YAML 파일이 됩니다.

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

모든 결정은 자신의 출처 커밋으로 다시 연결됩니다. 모든 결정은 자신이 영향을 미치는 파일을 명시합니다. 결정들 사이의 관계는 명시적입니다.

CLI 통합: 조직의 기억 쿼리하기

여기서 고리가 닫힙니다. 에이전트는 CLI를 통해 결정을 쿼리할 수 있습니다.

# Search by topic
uv run orkestra registry decisions search --query "retry"

재시도 로직, 오류 처리, 복구 패턴에 관한 결정을 반환합니다.

# Get full details on a specific decision
uv run orkestra registry decisions info DEC-PL-142

맥락, 근거, 영향을 포함한 완전한 결정 기록을 반환합니다.

# List recent decisions for context
uv run orkestra registry decisions list --limit 15

최근에 어떤 아키텍처적 선택이 이루어졌는지 보여줍니다.

에이전트는 이것을 어떻게 사용하는가

우리 오케스트레이터의 기본 지침에는 다음이 포함됩니다.

**Essential CLI commands:**
- `orkestra registry decisions search "X"` — Find architectural decisions

DuckDB와 관련된 무언가를 구현하라는 요청을 받으면, 에이전트는 먼저 다음을 확인할 수 있습니다.

uv run orkestra registry decisions search --query "DuckDB"

그리고 DEC-PL-142를 발견하여 다음을 배웁니다.

왜 우리가 DuckDB를 선택했는지 (context)
올바르게 사용하는 방법 (agent_guidance)
어떤 파일을 봐야 하는지 (files)
어떤 관련 결정이 존재하는지 (related)

에이전트는 바퀴를 재발명하지 않습니다. 확립된 패턴 위에 쌓아 올립니다.

세 가지 질문 테스트

모든 커밋이 결정 기록으로 남을 자격이 있는 것은 아닙니다. 우리는 걸러내기 위해 세 가지 질문 테스트를 사용합니다.

이것을 결정하기 어려웠는가? 상당한 분석, 트레이드오프 평가, 혹은 논의가 필요했는가?
바꾸는 데 비용이 많이 드는가? 이 결정을 되돌리려면 상당한 재작업이 필요한가?
시스템 전반에 영향을 미치는가? 여러 패키지에 영향을 주거나 다른 사람들이 따를 패턴을 확립하는가?

커밋이 이 질문 중 최소 하나에 “예”라고 답한다면, 이는 결정 추출의 후보가 됩니다. 우리의 일반적인 비율은 커밋 100개당 1~~4개의 결정(약 1~~4%)입니다.

체인지로그 항목의 경우 기준이 더 낮습니다. 사용자에게 보이는 모든 변경(기능, 수정, 개선)은 기록됩니다. 내부적인 잡무, 문서 업데이트, 리팩터링은 보통 건너뜁니다. 우리의 일반적인 비율은 커밋 100개당 30~50개의 체인지로그 항목입니다.

데이터 저장: 추가 전용 원장

마이닝 시스템은 충돌 없는 다중 에이전트 운영을 위해 추가 전용(append-only) JSONL 원장을 사용합니다.

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

.gitattributes 안의 merge=union을 사용하는 JSONL 포맷 덕분에, 여러 에이전트가 병합 충돌 없이 동시에 커밋을 분류할 수 있습니다. 각 줄은 독립적입니다.

검증 게이트

모든 마이닝 세션 전에 우리는 검증을 실행합니다.

uv run orkestra mine validate --quick

이는 다음을 확인합니다.

SHA 형식의 유효성
결정 ID 형식 준수
동일한 SHA에 대한 중복 항목 없음
참조된 결정이 실제로 존재함

분류 이후, 변경을 커밋하기 전에 다시 검증합니다.

이것이 중요한 이유

우리가 만든 피드백 루프는 여러 문제를 해결합니다.

새 팀원에게: “왜 우리가 X를 했지?“라고 묻는 대신, 결정 레지스트리를 검색할 수 있습니다. 맥락이 보존되어 있습니다.

AI 에이전트에게: 이들은 진공 상태에서 작동하지 않습니다. 권고를 하기 전에 조직의 지식을 쿼리할 수 있습니다. 새로운 파이프라인 단계를 추가해달라는 요청을 받으면, DuckDB 패턴을 발견하고 그것을 따를 수 있습니다.

아키텍처적 일관성에: 결정은 명시적이고 검색 가능합니다. 누군가 기존 결정과 모순되는 접근법을 제안하면, 시스템이 그 충돌을 드러낼 수 있습니다.

체인지로그 생성에: 릴리스 노트는 마지막 순간의 허둥지둥이 아닙니다. 개발 과정에서 이루어지는 지속적인 분류의 부산물입니다.

온보딩에: 새 에이전트는 코드베이스의 전체 맥락을 물려받습니다. 코드만 보는 것이 아니라, 그 코드를 만든 결정도 봅니다.

현재 상태

오늘 기준으로:

파이프라인을 거쳐 처리된 커밋 15,637개
추출되어 문서화된 아키텍처 결정 476개
기록된 체인지로그 항목 6,799개
두 도메인 모두에서 100% 커버리지

우리가 시작한 이래 모든 커밋이 분류되었습니다. 조직의 기억은 완전하고 쿼리 가능합니다.

시작하기

비슷한 것을 구현하고 싶다면:

컨벤셔널 커밋으로 시작하세요. 마이닝 파이프라인은 커밋에 구조화된 접두사(feat:, fix:, chore:)가 있을 때 가장 잘 작동합니다.
도메인을 정의하세요. 우리는 pipeline, agent-design, observability, data-modeling 같은 도메인을 사용합니다. 이들은 결정을 영역별로 정리합니다.
분류하는 습관을 만드세요. 마이닝은 팀이 정기적으로 커밋을 분류할 때 작동합니다. LLM의 도움을 받는 배치 처리는 규모를 키우는 데 도움이 됩니다.
결정을 쿼리 가능하게 만드세요. 에이전트가 CLI를 통해 결정을 검색할 수 있을 때 가치가 복리로 쌓입니다. 기계가 소비하기 좋게 출력을 구조화하세요.
고리를 닫으세요. 결정은 앞으로의 작업에 영향을 미쳐야 합니다. 에이전트 지침과 코드 리뷰 체크리스트에 결정 참조를 포함시키세요.

목표는 완벽한 문서화가 아닙니다. 오늘도, 6개월 뒤에도 사람과 AI 모두가 변경 뒤의 이유에 접근할 수 있도록 하는 것입니다. 변경이 조직의 기억이 되면, 팀은 그것을 재발명하는 대신 확립된 패턴 위에 쌓아 올립니다.

마이닝 워크플로는 우리 오케스트레이션 엔진의 일부이며, 구체적으로는 우리 오케스트레이션 패키지의 컨텍스트 엔진 모듈에 속합니다.

스킬 마이닝: 3,500개의 후보에서 466개의 역량으로

Tue, 27 Jan 2026 00:00:00 GMT

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

3,500개 스킬 문제

에이전트 오케스트레이션 시스템을 만들기 시작했을 때, 우리는 흥미로운 과제에 부딪혔습니다. AI 생태계 전반에는 수천 개의 잠재적인 스킬이 흩어져 있습니다. GitHub 저장소, 벤더 문서, 커뮤니티 프로젝트, 내부 패턴까지, 스킬은 어디에나 존재합니다. 하지만 어떤 것이 중요할까요? 어떤 것이 실제로 작동할까요? 그리고 에이전트가 실제로 쓸 수 있는 일관성 있는 스킬 라이브러리를 어떻게 유지할까요?

우리의 답은 체계적인 마이닝 및 수집 루프입니다.

오늘의 수치

Anthropic이 2025년 10월 16일 Agent Skills를 출시한 지 세 달이 조금 지난 시점, 이 글이 게시된 2026년 1월 27일 기준 우리의 상황은 다음과 같습니다.

지표	수치
확인된 후보	3,500개 이상
채택된 스킬	466개
벤더 스킬	373개
내부 스킬	93개
활성 벤더	25개 이상
스킬당 평균 토큰 수	2,834
참조된 도구	89개
고유 태그	635개

우리는 3,500개 이상의 스킬 후보를 검토했습니다. 그리고 466개를 채택했습니다. 채택률 13%입니다. 그리고 그 선별성은 의도적입니다.

지식 계층 체계

모든 스킬이 동등하게 만들어지지는 않습니다. 우리는 이를 다섯 개의 지식 계층(K0-K4)으로 조직하며, 각각은 서로 다른 적용 범위를 나타냅니다.

K0: Foundations (보편적)

모든 에이전트가 가져야 하는 스킬. “좋은 사고자” 역량을 나타내며 어디서든 작동합니다.

foundations/
├── test-first-discipline       # TDD: Red-Green-Refactor
├── evidence-based-completion   # Verify before claiming done
├── systematic-debugging        # Root cause methodology
├── structured-planning         # Break work into tasks
└── context-budget-awareness    # Manage token consumption

K0 스킬은 어떤 프로젝트, 어떤 도메인, 어떤 스택으로도 이식 가능합니다. 보편적인 인지 패턴을 담고 있습니다.

K1: Identities (전문 분야)

하나의 분야 안에서 여러 프로젝트에 걸쳐 적용되는 “좋은 엔지니어” 혹은 “좋은 연구자” 스킬.

identities/
├── research-workflows          # Multi-source research
├── web-extraction-playbook     # Content extraction
├── code-review                 # PR review patterns
└── cli-interface-standards     # CLI design patterns

K2: Domains (주제 전문성)

한 분야 안에서 이식 가능한 “좋은 데이터베이스 전문가” 혹은 “좋은 보안 엔지니어” 스킬.

domains/
├── schema-migration-workflow   # Safe migration patterns
├── rpc-validation-checklist    # RPC health checks
├── auth-validation-checklist   # JWT/OAuth patterns
└── secrets-audit-checklist     # Credential scanning

K3: Stacks (기술)

특정 기술 스택을 위한 “좋은 Supabase 사용자” 혹은 “좋은 Cloudflare 개발자” 스킬.

stacks/
├── maguyva-quickstart          # Our semantic search patterns
├── cloudflare-deployment       # Workers/Pages deployment
└── mcp-tool-best-practices     # MCP tool selection

K4: Project (조직)

우리 조직과 워크플로에 특화된 스킬.

project/
├── agent-creation-workflow     # How we build agents
├── skill-authoring-workflow    # How we write skills
├── mining-session-workflow     # This very process
└── vendor-skill-evaluation     # Evaluation rubrics

마이닝 루프

1단계: 발견

스킬은 어디에서나 옵니다.

벤더 저장소: AWS, Anthropic, Cloudflare, Supabase, 그리고 커뮤니티 기여자들이 스킬 모음을 공개합니다. 우리는 25개 이상의 벤더 루트를 추적합니다.

커뮤니티 프로젝트: GitHub은 Claude Code 템플릿, 에이전트 패턴, 워크플로 정의로 가득합니다.

내부 패턴: 우리 팀이 문제를 해결하면서 패턴이 나타납니다. 이들은 스킬로 공식화됩니다.

문서 마이닝: 기술 문서에는 종종 암묵적인 스킬 — 절차, 체크리스트, 결정 트리 — 이 담겨 있습니다.

발견은 계속됩니다. 우리는 공식 평가 전에 후보를 추적하기 위해 스킬 백로그를 사용합니다.

2단계: 평가

모든 후보는 동일한 채점 기준을 거칩니다.

adoption_criteria:
  - fills_real_gap: true      # We lack this capability
  - well_structured: true     # Progressive disclosure
  - actively_maintained: true # Commits in last 6 months
  - portable: true            # Not hyper-specific
  - tested: true              # Evidence of usage

다섯 가지 제품 기준을 모두 통과해야 합니다. 이것이 후보의 87%가 거절되는 이유입니다.

그런 다음 모든 후보는 별도의 신뢰 검토를 거칩니다. 우리는 공식 벤더 저장소, 잘 알려진 커뮤니티 관리자, 그리고 무작위 GitHub 저장소를 동등한 신뢰의 원천으로 취급하지 않습니다.

trust_review:
  vendor_credibility:
    - ownership_verified       # Official vendor, known maintainer, or internal source
    - maintenance_signal       # Recent commits, issue response, release history
    - adoption_signal          # Evidence of real use, stars alone are not enough
    - provenance_clear         # We can trace where the skill came from
  prompt_injection_scan:
    - hidden_instruction_check # Buried "ignore previous instructions" patterns
    - exfiltration_check       # Prompts that try to leak files, secrets, or context
    - authority_check          # Claims of priority over system or developer rules
  script_audit:
    - inspect_scripts          # Read shell/python/js helpers before adoption
    - network_and_exec_review  # curl|bash, remote downloads, subprocess execution
    - file_and_secret_review   # Env vars, credential access, broad file writes
    - destructive_action_check # rm, reset, overwrite, or unsafe automation

신뢰할 수 있는 벤더는 더 가벼운 출처 검토를 받지만, 그렇다고 무사통과는 아닙니다. 신뢰할 수 없거나 알려지지 않은 출처는 더 깊은 수동 감사를 받으며, 우리는 번들 스크립트를 읽고, 범위를 파악하고, 안전하다고 분류하기 전까지는 실행하지 않습니다.

갭 분석: 채택하기 전에 우리는 레지스트리를 검색합니다.

uv run orkestra skills search "<capability>"

이미 갖고 있다면 필요 없습니다. 비슷한 것을 갖고 있다면 채택하는 대신 병합할 수도 있습니다.

깊이와 표준 점수화: 우리는 또한 후보가 에이전트-스킬 모델을 얼마나 완전히 활용하는지 점수를 매깁니다. 단독 SKILL.md도 여전히 유용할 수 있지만, agentskills.io가 권장하는 방식으로 지침과 참조, 스크립트, 자산을 분리하는 더 깊은 스킬이 더 가치 있습니다.

skill_depth:
  - level_1: SKILL.md only                     # Single instruction file
  - level_2: SKILL.md + strong description     # Clear triggers and scope
  - level_3: adds references/                  # Load docs only when needed
  - level_4: adds atomic scripts/              # Small, reviewable helpers
  - level_5: adds assets/examples/templates    # Full progressive disclosure
depth_signals:
  - standards_adherence        # Structure aligns with agentskills.io conventions
  - reference_quality          # Curated references, not giant context dumps
  - script_atomicity           # Focused helpers, not opaque monoliths
  - tool_boundary_clarity      # Clear limits on what the skill can execute
  - community_signal           # Stars/forks/users help, but only as a weak boost

GitHub 스타는 신뢰도 점수를 조금 끌어올릴 수는 있지만, 얕거나 안전하지 않은 스킬을 구제하지는 못합니다. 하나의 모호한 SKILL.md와 불투명한 스크립트를 가진 스타 많은 저장소는, 정확한 설명과 잘 정리된 references/, 그리고 전체 스킬 역량을 실제로 활용하는 원자적 헬퍼를 가진 더 작은 저장소보다 낮은 점수를 받습니다.

구조적 분석: 우리는 스킬 품질을 확인합니다.

wc -l vendor/<repo>/<skill>/SKILL.md  # Size check
ls vendor/<repo>/<skill>/scripts/     # Supporting files
ls vendor/<repo>/<skill>/references/  # Bundled docs

후보가 스크립트를 포함한다면, 그 검토는 더 엄격해집니다. 좋은 스킬은 그저 유용한 것이 아니라, 에이전트에게 넘겨주기에 읽기 쉽고, 범위가 명확하고, 안전해야 합니다. 이 안전성 필터 하나만으로도 그 외에는 흥미로운 상당수의 후보가 탈락합니다.

3단계: 수집

스킬이 평가를 통과하면 레지스트리에 들어갑니다. 하지만 스킬이 그대로 채택되는 일은 없습니다. 우리 시스템에 맞게 수정됩니다.

채택 시 수정 사항:

메타데이터 정규화: 모든 스킬은 우리의 프런트매터 스키마를 갖게 됩니다
K-계층 배정: 스킬은 적절한 지식 계층에 배치됩니다
태그 보강: 발견을 위한 태그가 추가됩니다
도구 선언: 허용된 도구가 명시적으로 선언됩니다
섹션 정렬: 내용이 우리 템플릿에 맞게 재구성됩니다

수집 후 일반적인 스킬 YAML입니다.

metadata:
  identifier: vendor-skill-evaluation
  name: vendor-skill-evaluation
  description: Systematic evaluation of vendor skills for adoption.
  type: workflow
  layer: K4
  semantic_folder: project
  source: core
  last_updated: '2026-01-17'

frontmatter:
  tags:
    - agents
    - meta
    - skill-adoption
    - vendor
  allowed_tools:
    - Bash
    - Read
    - Write
    - Edit
    - Grep
    - Glob
    - Task

4단계: 스코프 배정

스킬은 스코프에 배정됩니다. 어떤 에이전트가 어떤 스킬을 로드할지 결정하는 카테고리입니다.

scopes:
  database:
    primary_skills:
      - domains/schema-migration-workflow
      - domains/rpc-validation-checklist
      - vendor/supabase/supabase-database
      - vendor/supabase/supabase-auth

  research:
    primary_skills:
      - identities/research-workflows
      - identities/web-extraction-playbook
      - identities/dataset-discovery-quickstart

에이전트는 자신의 스코프를 선언하고, 스킬은 자동으로 배정됩니다.

# Agent definition
scopes: [database, research]
# Gets: all database skills + all research skills + universal skills

5단계: 실체화

스킬은 프로덕션에서 YAML로 존재하지 않습니다. Claude Code가 로드할 수 있는 SKILL.md 파일로 렌더링됩니다.

uv run orkestra sync

이 명령은 다음을 수행합니다.

모든 스킬 YAML 정의를 읽습니다
Jinja 템플릿을 통해 이들을 렌더링합니다
.claude/skills/에 SKILL.md 파일을 씁니다
K-계층별로 정리합니다(foundations/, identities/, domains/, stacks/, project/)

최종 출력 구조입니다.

.claude/skills/
├── foundations/     # K0: Universal
├── identities/      # K1: Discipline
├── domains/         # K2: Subject
├── stacks/          # K3: Technology
├── project/         # K4: Organization
└── vendor/          # External skills

휴면 스코프 패턴

우리의 가장 강력한 패턴 중 하나는 “채택되었지만 로드되지 않은” 스킬입니다. 우리는 이를 휴면 스코프라고 부릅니다.

k-dense-scientific 저장소의 과학 컴퓨팅 스킬을 생각해봅시다. 우리는 생물정보학, 화학, 양자 컴퓨팅, 임상 정보학을 다루는 120개 이상의 스킬을 채택했습니다. 하지만 우리 에이전트 대부분은 분자 도킹이나 유전자 발현 분석이 필요 없습니다.

120개의 스킬 모두를 모든 에이전트에 로드하는(컨텍스트 윈도우를 부풀리는) 대신, 우리는:

특정 스코프(예: bioinformatics)로 스킬을 채택합니다
등록되어 있지만 로드되지 않은 상태로 휴면 상태를 유지합니다
에이전트가 그 스코프를 선언할 때만 활성화합니다

# In scopes.yaml - dormant scope
bioinformatics:
  description: "Bioinformatics and genomics"
  primary_skills: []  # Empty - skills exist but aren't loaded

# When an agent needs bioinformatics:
# Agent YAML
scopes: [research, bioinformatics]  # Now loads bioinformatics skills

이 패턴 덕분에 일반적인 에이전트가 40~60개의 관련 스킬만 로드하면서도 레지스트리에는 466개의 스킬을 둘 수 있습니다.

스킬 유형

스킬은 세 가지 인지 패턴으로 나뉩니다.

워크플로

순서가 있는 절차적 단계: “1. X를 한다, 2. 그다음 Y를 한다, 3. 마지막으로 Z를 한다”

type: workflow
# Examples: schema-migration-workflow, mining-session-workflow

규율

행동 가드레일: “항상 X를 하라”, “절대 Y를 하지 마라”, “Z를 선호하라”

type: discipline
# Examples: test-first-discipline, evidence-based-completion

체크리스트

검증 기준: “X를 확인하라”, “Y를 검증하라”, “Z를 점검하라”

type: checklist
# Examples: auth-validation-checklist, secrets-audit-checklist

품질 게이트

모든 스킬은 출시 전에 검증을 통과해야 합니다.

validation:
  file_exists: true           # Skill file at declared path
  frontmatter_valid: true     # Frontmatter parses correctly
  sections_complete: true     # Expected sections present
  tools_registered: true      # Declared tools exist in registry

설명은 Claude Code가 언제 제안해야 할지 알 수 있도록 트리거 문구(“~할 때 사용”, “~~가 필요할 때”)와 함께 50~~400자 사이여야 합니다.

우리는 지속적으로 검증합니다.

uv run orkestra validate --show-warnings

벤더 생태계

우리의 373개 벤더 스킬은 다음에서 옵니다.

제공자	스킬 수	도메인
AWS Agent	19	클라우드 서비스
Anthropic	12	문서 생성
Cloudflare	8	엣지 컴퓨팅
Supabase	5	데이터베이스
k-dense	100개 이상	과학 컴퓨팅
silvainfm	4	데이터 사이언스
Java Developer Kit	45개 이상	Spring/Java
Vercel	1	브라우저 자동화

각 벤더 루트는 metadata.yaml에 선언됩니다.

vendor_roots:
  - path: vendor/aws-agent-skills
    provider: aws
  - path: vendor/k-dense-scientific/scientific-skills
    provider: k-dense
  - path: vendor/supabase-skills
    provider: supabase

orkestra sync가 실행되면, 벤더 스킬은 제공자 네임스페이스와 함께 .claude/skills/vendor/에 심링크됩니다.

우리가 배운 것

선별성은 보상받습니다. 유용해 보이는 모든 것을 채택하고 싶은 유혹이 있습니다. 하지만 스킬 하나하나는 토큰 비용이 듭니다. 스킬당 평균 2,834토큰이면, 비대함은 금방 타격을 줍니다. 우리의 13% 채택률은 에이전트를 가볍게 유지합니다.

구조는 발견을 가능하게 합니다. K-계층 체계는 단순한 정리가 아니라 이식성에 관한 것입니다. K0 스킬은 어디서든 재사용할 수 있습니다. K4 스킬은 의도적으로 프로젝트에 특화되어 있습니다. 이 명확성은 사람과 에이전트 모두가 필요한 것을 찾는 데 도움이 됩니다.

휴면 스코프는 규모를 키웁니다. 모든 것을 로드하지 않고도 수백 개의 스킬을 채택할 수 있습니다. 스코프는 개별 에이전트의 컨텍스트 윈도우를 관리 가능하게 유지하면서도 포괄적인 레지스트리를 구축할 수 있게 해줍니다.

채택 시 수정은 필수적입니다. 가공되지 않은 벤더 스킬은 여러분의 시스템에 좀처럼 딱 맞지 않습니다. 메타데이터 추가, 계층 배정, 태그 보강이라는 수집 과정이 외부 스킬을 내부적으로 작동하게 만듭니다.

마이닝은 계속됩니다. 3,500이라는 숫자는 계속 늘어납니다. 새로운 벤더 저장소가 나타납니다. 커뮤니티 패턴이 떠오릅니다. 내부 워크플로가 굳어집니다. 루프는 절대 멈추지 않습니다.

다음 단계

우리는 여러 개선 사항을 작업 중입니다.

자동화된 갭 탐지: 흔한 에이전트 실패가 아직 채택되지 않은 스킬로 해결될 수 있을 때 알림
스킬 폐기 워크플로: 대체되었거나 사용되지 않는 스킬을 은퇴시키는 공식 절차
스킬 간 의존성: 스킬의 전제 조건을 명시적으로 선언
사용량 분석: 에이전트가 실제로 호출하는 스킬과 그저 로드만 하는 스킬을 추적

스킬 마이닝 루프는 인프라입니다. 화려하지 않습니다. 하지만 이것이 41개의 에이전트가 컨텍스트 한계 안에 머물면서도 466개의 역량과 함께 일관되게 작동하게 만드는 것입니다.

그것이 3,500이 466이 되는 이야기입니다. 3,000개를 무시해서가 아니라, 체계적으로 평가하고 작동하는 것만 채택함으로써입니다.

스킬 시스템이 실제로 작동하는 모습을 보고 싶으신가요? 현재 우리 레지스트리를 살펴보려면 uv run orkestra skills list를 확인하세요.

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

Tue, 20 Jan 2026 00:00:00 GMT

이 글의 수치는 게시 시점(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

{
  "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 도구의 전체 목록

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

{
  "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"

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

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

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

$ orkestra decisions info DEC-SR-049

{
  "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

{
  "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가 이깁니다.

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

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

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

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

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

그라운드 트루스: AI 에이전트를 현실에 고정하기

Tue, 13 Jan 2026 00:00:00 GMT

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

AI 에이전트는 놀라울 만큼 유능합니다. 추론하고, 종합하고, 생성할 수 있습니다. 하지만 이들에게는 근본적인 약점이 있습니다. 무언가를 지어낸다는 것입니다. 악의적으로가 아니라 자신 있게 말이죠. 에이전트는 존재하지 않는 API 파라미터를 지어내거나, 한 번도 정의된 적 없는 설정을 참조하거나, 학습 데이터에서 온 패턴을 여러분의 실제 아키텍처와 모순되게 적용할 수 있습니다.

표준적인 완화책은 “에이전트에게 더 많은 컨텍스트를 주라”는 것입니다. 하지만 컨텍스트는 서로 모순될 수 있습니다. 문서는 구현에서 벗어나 표류합니다. 주석은 거짓말을 합니다. 의도를 이해하지 못한 채 읽으면 코드조차 사람을 오도할 수 있습니다.

우리에게는 더 명시적인 무언가가 필요했습니다. 무시되거나 오해될 수 없는 무언가. 에이전트를 검증 가능한 현실에 고정할 수 있는 무언가.

우리는 이것을 기준 사실이라고 부릅니다.

기준 사실이란 무엇인가?

기준 사실은 에이전트가 반드시 존중해야 하는, 명시적이고 버전 관리되는 사실 진술입니다. 문서가 아닙니다. 주석도 아닙니다. 시스템 안의 1급 개체이며 다음을 갖습니다.

고유 식별자 (GT-MAG-015 또는 GT-MAG-036 같은 형태)
라이프사이클 상태 (current, tentative, deprecated)
범위 (플랫폼 전체, 패키지별, 혹은 도메인 한정)
근거 (진술을 뒷받침하는 파일 경로, URL, 참조)
에이전트 가이던스 (명시적인 권장/금지 지침)

우리 Maguyva 코드 인텔리전스 플랫폼의 예시입니다.

- id: GT-MAG-015
  status: current
  scope: package
  statement: |
    Fuzzy symbol matching is opt-in via `find_similar=true`.
    Default behavior returns empty results for non-existent symbols;
    `exact_match=true` enforces strict matching and disables all fuzzy fallbacks.
  rationale: |
    Deterministic defaults prevent agents from receiving misleading results.
    Typos should fail explicitly rather than silently returning unrelated symbols.
  evidence:
    - "packages/maguyva/server/src/maguyva/services/code_analysis_service.py"
    - "packages/maguyva/server/docs/quick_reference/parameters.md"
  last_verified: "2026-01-25"
  tags:
    - product
    - ai_first
    - principle

이것은 산문이 아닙니다. 계약입니다. 에이전트가 이 기준 사실을 마주치면 다음을 알게 됩니다.

기본 동작은 결정론적입니다(모호한 추측이 아니라 빈 결과).
정의된 동작을 가진 특정 파라미터(find_similar, exact_match)가 존재합니다.
검증 가능한 특정 파일에 근거가 존재합니다.
이 진술은 특정 날짜에 검증되었습니다.

기준 사실 레지스트리의 해부

기준 사실은 ai_assets/reference/ground_truths.yaml 아래의 YAML 레지스트리에 존재합니다. 각 패키지나 도메인은 자체 레지스트리를 가질 수 있습니다. 구조는 다음과 같습니다.

metadata:
  title: "Maguyva Ground Truths"
  summary: "Foundational constraints and principles that guide Maguyva."
  last_updated: "2026-01-26"
  owner: "maguyva"
  render:
    include_statuses: [current, tentative]
    show_deprecated: true
    groups:
      - title: "Product Principles"
        tags: [product, principle, brand]
      - title: "Architecture & Boundaries"
        tags: [architecture, boundaries, cqrs]

statements:
  - id: GT-MAG-001
    status: current
    scope: package
    statement: "Maguyva is read-only with respect to user repositories..."
    ...

레지스트리에는 컬렉션 자체에 대한 메타데이터, 문서 생성을 위한 렌더 설정, 그리고 진술 자체가 포함됩니다. 각 진술은 Pydantic 모델로 검증되는 엄격한 스키마를 따릅니다.

class GroundTruthStatement(BaseModel):
    id: str
    status: GTStatus  # current, tentative, deprecated
    source: GTSource | None  # claude-code, orkestra, discipline
    scope: GTScope  # platform, package, domain
    statement: str
    rationale: str | None
    evidence: list[str]
    last_verified: str | None
    tags: list[str]
    agent_guidance: AgentGuidance | None

에이전트가 기준 사실에 접근하는 방법

기준 사실은 여러 경로로 노출됩니다.

1. 렌더링된 문서

orkestra sync 명령은 YAML 레지스트리를 읽을 수 있는 마크다운으로 변환합니다.

uv run orkestra sync

이는 에이전트 컨텍스트에 포함되는 GROUND_TRUTHS.md 파일을 생성합니다. 렌더링된 결과는 진술을 상태와 카테고리별로 그룹화합니다.

## Current
### Product Principles
- Maguyva is read-only with respect to user repositories... (GT-MAG-001)
- Design tool responses for AI agents first... (GT-MAG-009)

### Architecture & Boundaries
- Pipeline and Maguyva boundaries are intentional... (GT-MAG-006)

2. CLI 검색

셸 접근 권한이 있는 에이전트는 그라운드 트루스를 프로그래밍 방식으로 검색할 수 있습니다.

uv run orkestra registry truths search "embedding"
uv run orkestra registry truths search --tag security
uv run orkestra registry truths list --status current

검색 함수는 여러 필드에 걸쳐 가중치를 둔 관련성으로 일치 항목을 채점합니다.

def truth_fields(gt: GroundTruthStatement) -> list[FieldSpec]:
    return [
        FieldSpec(name="id", weight=6, values=[gt.id]),
        FieldSpec(name="statement", weight=5, values=[gt.statement]),
        FieldSpec(name="rationale", weight=4, values=[gt.rationale] if gt.rationale else []),
        FieldSpec(name="tags", weight=3, values=gt.tags or []),
        FieldSpec(name="evidence", weight=2, values=gt.evidence or []),
    ]

3. 컨텍스트 구성

에이전트가 YAML 정의로부터 렌더링될 때, 그 컨텍스트는 그라운드 트루스 레지스트리를 참조할 수 있습니다.

context_composition:
  domain_knowledge:
    - packages/maguyva/ai_assets/reference/ground_truths.yaml

이는 에이전트가 작업을 시작하기 전에 관련 그라운드 트루스가 로드되도록 보장합니다.

그라운드 트루스의 범주

우리 레지스트리 전반을 살펴보면, 그라운드 트루스는 몇 가지 패턴으로 뭉칩니다.

제품 원칙

제품이 무엇이고 무엇이 아닌지에 대한 제약:

“Maguyva는 사용자 저장소에 대해 읽기 전용이다. 재생성 불가능한 유일한 자산은 유료 임베딩 캐시다.” (GT-MAG-001)

아키텍처 경계

책임이 어디에 있고 왜 그런지:

“파이프라인과 Maguyva의 경계는 의도적이다. 파이프라인은 재사용 가능하고, Maguyva는 코드 특화 로직을 갖고 있으며, CQRS가 파이프라인 단계의 쓰기와 서버의 읽기를 분리한다.” (GT-MAG-006)

환각 방지 규칙

도구 계약을 추론에 맡기지 않고 결정론적으로 유지하는 명시적 지침:

“퍼지 심볼 매칭은 find_similar=true를 통한 옵트인이다. 기본 동작은 존재하지 않는 심볼에 대해 빈 결과를 반환한다. exact_match=true는 엄격한 매칭을 강제하고 모든 퍼지 폴백을 비활성화한다.” (GT-MAG-015)

품질 게이트

유지해야 하는 기준:

“공유 인프라(post_filters.py, 관계 추출기, 공유 핸들러)에 대한 변경은 커밋 전에 전체 매니페스트 생성을 통해 지원되는 모든 언어에 대해 반드시 검증되어야 한다. 단일 언어 검증만으로는 공유 코드에 충분하지 않다.” (GT-MAG-036)

코드 패턴

구현 요구 사항:

“비동기 컨텍스트에서 CPU 바운드 작업에는 asyncio.to_thread()를 사용하라. 더 이상 사용되지 않는 loop.run_in_executor() 패턴은 새 코드에 사용해서는 안 된다.” (GT-MAG-018)

그라운드 트루스의 라이프사이클

그라운드 트루스는 고정된 것이 아닙니다. 정해진 라이프사이클을 거쳐 진화합니다.

Tentative(잠정)

평가 중인 제안된 진실. 진술은 기록되지만 변경될 수 있습니다.

- id: GT-MAG-044
  status: tentative
  statement: |
    get_file with include_metadata=false may still return metadata in the
    response because middleware may re-inject it for AI agent disambiguation.

Current(현재)

검증된, 에이전트가 반드시 존중해야 하는 진실. 근거가 검증되었습니다.

- id: GT-MAG-017
  status: current
  last_verified: "2026-01-26"
  evidence:
    - "packages/maguyva/server/src/maguyva/services/supabase.py"

Deprecated(폐기됨)

더 이상 적용되지 않는 진실. 무엇으로 대체되었는지에 대한 포인터와 함께 역사적 참고용으로 보존됩니다.

- id: GT-MAG-099
  status: deprecated
  superseded_by: GT-MAG-015
  notes: "Replaced when we moved to explicit matching behavior"

왜 그냥 문서로는 안 되는가?

문서는 다른 목적을 수행합니다. 설명합니다. 가르칩니다. 모호할 수 있고, “대체로”나 “보통” 같은 수식어를 쓸 수 있습니다.

그라운드 트루스는 모호할 수 없습니다. 이것은 단언입니다. 적용되거나 적용되지 않거나 둘 중 하나입니다.

차이를 살펴봅시다.

문서: “심볼을 찾지 못하면 API는 대체로 빈 결과를 반환하지만, 일부 설정에서는 퍼지 매칭이 활성화되어 있을 수 있다.”

그라운드 트루스: “기본 동작은 존재하지 않는 심볼에 대해 빈 결과를 반환한다. exact_match=true는 엄격한 매칭을 강제하고 모든 퍼지 폴백을 비활성화한다.”

첫 번째는 시스템을 배우는 사람에게 도움이 됩니다. 두 번째는 결정을 내리는 에이전트가 실제로 행동에 옮길 수 있는 것입니다.

에이전트 가이던스: 해야 할 것과 피해야 할 것

일부 그라운드 트루스는 명시적인 에이전트 가이던스를 포함합니다.

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code,
    never via validator filters.
  agent_guidance:
    do:
      - "Fix extraction bugs in YAML config, handlers, or tree-sitter queries"
      - "Add test cases at the layer where the fix lives"
    avoid:
      - "Adding validator filters to mask production bugs"
      - "Creating test-only workarounds for extraction issues"

이는 모호함을 없앱니다. 이를 읽는 에이전트는 무엇이 사실인지뿐 아니라 그 사실이 어떤 행동을 암시하는지도 알게 됩니다.

검증과 유지보수

그라운드 트루스는 유지보수가 필요합니다. 우리는 다음을 추적합니다.

last_verified: 누군가 이 진술이 여전히 유효함을 확인한 시점
evidence: 진술을 뒷받침하는 파일(존재 여부를 확인할 수 있음)
source: 이 진실이 어디서 비롯되었는지(CLI 조사, 아키텍처 검토, 인시던트 이후 학습)

검증 날짜가 오래되었거나 근거 링크가 깨진 그라운드 트루스는 조사가 필요하다는 신호입니다. 진실이 여전히 유효해서 재검증이 필요하거나, 아니면 현실이 바뀌어서 진실을 업데이트해야 하거나 둘 중 하나입니다.

프로덕션의 실제 사례

보안 경계

- id: GT-MAG-014
  statement: |
    Maguyva queries are search patterns, not executable code.
    SQL injection prevention is handled by PostgREST parameterization;
    application-layer SQL keyword blocking must never be added.
  rationale: |
    Blocking SQL keywords breaks legitimate code search. Users search FOR
    code containing patterns like 'DROP TABLE', they don't execute them.

이 그라운드 트루스는 제품을 망가뜨릴 수 있는 잘못된 방향의 “보안 개선” 부류를 방지합니다.

추출 시점 정확도

- id: GT-MAG-022
  statement: |
    Accuracy fixes must happen at extraction time via production code
    (YAML config, handlers, queries), never via validator filters.
  rationale: |
    Validator filters only run during tests. They can hide extractor bugs
    while production responses remain wrong.

이는 고통스러운 경험에서 나왔습니다. 에이전트들은 테스트 하니스만 더 초록색으로 보이게 만드는 검증기 전용 필터를 추가하는 방식으로 실패하는 언어 팩을 땜질했지만, 실제 라이브 Maguyva 추출기는 여전히 잘못된 엣지를 내보내고 있었습니다. 이 규칙은 수정 사항을 YAML 설정, 쿼리, 혹은 핸들러라는 진짜 경로로 되돌려 강제합니다.

다중 계층 필터링

- id: GT-MAG-023
  statement: |
    Language engine uses three-tier filtering: external_method_patterns
    (builtins/stdlib), allowlists (legitimate idioms), and expected_call_targets
    (validation-time deduplication). Each tier serves a distinct purpose.
  rationale: |
    Conflating filter purposes leads to either over-filtering (missing real
    relationships) or under-filtering (noise).

이는 에이전트가 잘못된 위치에 필터를 추가하는 것을 막습니다. 이는 정확도 리그레션을 유발했던 흔한 실수입니다.

오케스트레이션 시스템과의 통합

그라운드 트루스는 더 넓은 컨텍스트 시스템의 한 계층입니다.

아키텍처 결정(ADR) - 접근법 A를 B 대신 선택한 이유를 기록합니다
그라운드 트루스 - 지금 명확하게 사실인 것을 진술합니다
도메인 패턴 - 무언가를 올바르게 하는 방법을 설명합니다
안티패턴 - 무엇을 피해야 하고 왜 그런지 설명합니다

이 시스템에서 일하는 에이전트는 이 네 가지 모두에 접근할 수 있습니다. 그라운드 트루스는 사실적 고정점을 제공하고, 결정은 역사를 설명하며, 패턴은 구현을 안내하고, 안티패턴은 함정을 경고합니다.

영향 측정

그라운드 트루스를 도입한 이후 우리는 다음을 관찰했습니다.

“환각으로 만든 수정을 다시 고치는” 순환의 감소
사실이 명확할 때 더 확신에 찬 에이전트의 의사결정
기대치가 명시적이기 때문에 더 나아진 PR 리뷰
새 에이전트(그리고 사람)의 온보딩 시간 단축

그라운드 트루스를 유지보수하는 데 들이는 투자는 디버깅 감소와 더 명확한 시스템 경계로 보상받습니다.

시작하기

여러분의 시스템에 그라운드 트루스를 추가하려면:

패키지의 ai_assets/reference/ 디렉터리에 ground_truths.yaml을 만듭니다
메타데이터와 렌더 설정을 정의합니다
스키마를 따르는 진술을 추가합니다
문서를 생성하기 위해 uv run orkestra sync를 실행합니다
레지스트리를 에이전트 컨텍스트 구성에 포함시킵니다

가장 많은 혼란을 일으키는 사실이나 가장 자주 위반되는 제약부터 시작하세요. 그것들이 여러분에게 가장 가치 있는 그라운드 트루스입니다.

결론

AI 에이전트는 환각을 일으킬 것입니다. 그것이 그들의 본성입니다. 하지만 우리는 환각이 제약되고, 특정 사실은 타협 불가능하며, 에이전트가 자신의 가정을 검증된 현실과 대조해 확인할 수 있는 환경을 만들 수 있습니다.

그라운드 트루스는 완전한 해결책이 아닙니다. 유지보수가 필요합니다. 낡을 수 있습니다. 개발 프로세스에 오버헤드를 더합니다.

하지만 이것은 가치 있는 무언가를 제공합니다. 사람과 에이전트 모두가 신뢰할 수 있는 공유된 사실의 어휘 말입니다. 에이전트가 소프트웨어 개발에 점점 더 많이 참여하는 세상에서, 그 공유된 기반은 필수적이 됩니다.

대안은 에이전트가 확신에 찬 실수를 저지르고 사람이 이를 고쳐주는 끝없는 순환입니다. 그라운드 트루스는 수정을 명시적이고 지속적으로 만들어 그 순환을 끊습니다.

여러분의 에이전트는 무엇이 사실인지 알 자격이 있습니다. 알려주세요.

Orkestra: 대규모로 AI 에이전트 오케스트레이션하기

Tue, 06 Jan 2026 00:00:00 GMT

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

Claude Code로 구축을 시작했을 때, 우리는 AI 코딩 어시스턴트를 사용하는 모든 팀이 결국 마주치는 문제에 부딪혔습니다. 하나의 에이전트가 모든 것을 잘할 수는 없다는 것입니다.

에이전트에게 데이터베이스 전문가가 되라고 프롬프트할 수 있습니다. 혹은 보안 감사자가. 혹은 프런트엔드 엔지니어가. 하지만 이 셋을 동시에 되라고 요청하는 순간, 품질이 떨어집니다. 컨텍스트가 희석됩니다. 지침이 충돌합니다. 에이전트는 모든 것에서 평범한 제너럴리스트가 됩니다.

그래서 우리는 Orkestra를 만들었습니다.

Orkestra란 무엇인가?

Orkestra는 Claude Code와 유사한 AI 코딩 도구를 위한 에이전트 오케스트레이션 시스템입니다. 저마다 다른 전문성을 가진 여러 전문 에이전트를, 작업을 알맞은 전문가에게 라우팅하는 단일 오케스트레이터 아래에서 조율합니다.

AI 에이전트를 위한 인력 파견 업체라고 생각하면 됩니다. 오케스트레이터는 작업을 받고, 어떤 전문가가 그것을 처리해야 하는지 파악하며, 알맞은 컨텍스트와 함께 위임합니다. 작업이 끝나면 결과는 종합을 위해 오케스트레이터로 다시 흘러들어옵니다.

수치가 이를 말해줍니다.

구성 요소	개수
전문 에이전트	46
재사용 가능한 스킬	466
아이덴티티 원형	27
마인드셋	11
커뮤니케이션 스타일	10
지식 도메인	21

캐릭터 시스템: 에이전트를 위한 D&D

Orkestra 뒤에 있는 핵심 통찰은 에이전트의 행동이 세 가지 조합 가능한 요소로부터 나온다는 것입니다.

**아이덴티티(Identity)**는 에이전트가 무엇인지를 정의합니다. 아키텍트는 시스템 구조를 설계합니다. 디버거는 실패를 근본 원인까지 추적합니다. 가디언은 컴플라이언스와 보안 경계를 강제합니다. 우리는 섞어 쓸 수 있는 27개의 아이덴티티 원형을 갖고 있습니다.

**마인드셋(Mindset)**은 에이전트가 어떻게 생각하는지를 정의합니다. 분석적 마인드셋은 주장을 근거에 기반해 세우고 불확실성을 수치화합니다. 회의적 마인드셋은 가정에 의문을 제기하고 반증 근거를 찾습니다. 탐색적 마인드셋은 모호함을 받아들이고 여러 접근법을 시도합니다.

**스타일(Style)**은 에이전트가 어떻게 소통하는지를 정의합니다. 기술적 스타일은 정확한 값을 포함하고 구체적인 파일을 참조합니다. 간결한 스타일은 군더더기를 쳐내고 답부터 제시합니다. 외교적 스타일은 솔직함과 요령 사이의 균형을 잡습니다.

에이전트는 이 요소들을 조합합니다.

# architecture-advisor.yaml
identity:
  - knowledge-architect
  - architect
  - strategist
mindset: analytical
style: concise

이 조합은 시스템을 설계하고, 도메인 전반의 지식을 연결하며, 전략적 방향을 설정하고, 근거와 데이터로 사고하며, 군더더기 없이 소통하는 에이전트를 만들어냅니다.

힘은 조합 폭발에 있습니다. 27개의 아이덴티티 곱하기 11개의 마인드셋 곱하기 10개의 스타일은 거의 3,000가지의 가능한 에이전트 성격을 만들어냅니다. 하지만 여러분은 자신의 작업에 중요한 조합만 정의하면 됩니다.

스킬: 재사용 가능한 역량 모듈

스킬은 에이전트가 호출할 수 있는 지식과 워크플로입니다. 범위에 따른 계층 체계를 따릅니다.

계층	이름	범위	예시
K0	Foundations(기초)	보편적인 방법론	테스트 우선 원칙, 근거 기반 완료
K1	Identities(아이덴티티)	역할 기반 워크플로	CLI 인터페이스 표준, 성능 플레이북
K2	Domains(도메인)	도메인별 지식	데이터베이스 마이그레이션 패턴, 인증 검증
K3	Stacks(스택)	기술별	Cloudflare 배포, Supabase 운영
K4	Project(프로젝트)	이 코드베이스 전용	프로젝트별 워크플로와 관례

스킬은 지연 로딩됩니다. 에이전트는 시작 시 스킬의 이름과 설명만 보고, 전체 스킬 내용은 트리거되었을 때만 로드됩니다. 이는 수백 개의 스킬을 발견 가능하게 하면서도 컨텍스트를 가볍게 유지합니다.

각 스킬은 다음을 포함합니다.

명확한 트리거 조건 (“데이터베이스 스키마를 마이그레이션할 때 사용”)
단계별 가이던스
워크플로에 허용된 도구
성공 기준과 실패 복구 경로

우리 레지스트리의 466개 스킬은 git 워크트리 격리부터 웹 조사 워크플로, 배포 상태 검증까지 모든 것을 다룹니다.

오케스트레이션이 중요한 이유

단일 에이전트 아키텍처는 금방 벽에 부딪힙니다.

컨텍스트 희석. 20만 토큰 컨텍스트 윈도우는 데이터베이스 스키마, API 문서, 테스트 픽스처, 도메인 지식을 로드하기 전까지는 커 보입니다. 전문 에이전트는 목표가 명확한 컨텍스트로 작업할 수 있습니다.

지침 충돌. 에이전트에게 “철저하되 빠르게”와 “모든 것을 검증하되 과도하게 설계하지 마라”를 동시에 말하면 긴장이 생깁니다. 전문 에이전트는 명확한 범위를 가짐으로써 이를 해결합니다.

전문성의 깊이. 제너럴리스트 에이전트는 모든 것을 조금씩 압니다. 알맞은 아이덴티티와 스킬로 구성된 전문 에이전트는 자신의 도메인을 깊이 압니다.

Orkestra는 단일 계층(flat) 오케스트레이션을 구현합니다. 하나의 오케스트레이터가 여러 전문 에이전트를 조율합니다. 전문 에이전트는 하위 전문 에이전트를 생성할 수 없습니다. 이는 복잡성 폭발을 막으면서도 병렬 작업을 가능하게 합니다.

오케스트레이터는 220만 토큰의 실질적인 용량에 접근할 수 있습니다. 자신의 20만 토큰 윈도우에 더해, 각각 20만 토큰을 가진 10개의 동시 서브에이전트입니다. 단일 에이전트라면 소진해버릴 작업도 이 플릿 전반에 걸쳐 여유롭게 실행됩니다.

렌더링 파이프라인

에이전트 정의는 YAML에 존재합니다. Claude Code는 마크다운을 읽습니다. Orkestra는 결정론적 렌더링 파이프라인으로 이 간극을 잇습니다.

YAML Registries → Jinja Templates → .claude/agents/*.md

운영자는 YAML 소스를 편집합니다. orkestra sync를 실행합니다. 렌더링된 마크다운이 .claude/agents/에 나타납니다. Claude Code가 변경 사항을 인식합니다.

이 분리는 서로 다른 대상을 위한 것입니다.

YAML 소스는 라이프사이클 메타데이터, 태그, 검증 규칙, 도구를 위한 폐기 안내를 포함합니다
렌더링된 마크다운은 모델이 필요로 하는 것만 포함합니다. 설명, 도구, 스킬, 행동 가이던스입니다.

파이프라인은 아이덴티티, 마인드셋, 스타일, 스킬을 하나의 일관된 프롬프트로 합성합니다. 설계자-분석형-간결형 에이전트는 몇몇 기저 스킬을 공유하더라도 디버거-회의적-기술형 에이전트와는 매우 다른 시스템 프롬프트를 받습니다.

도메인 지식: 4개 파일 패턴

모든 지식 도메인은 일관된 구조를 따릅니다.

domain-name/
  decisions.md      # Key choices, rationale, consequences
  patterns.md       # Step-by-step guidance and examples
  anti-patterns.md  # Failure modes and remediation
  evolution.md      # Dated log of changes

이 구조는 에이전트의 컨텍스트 로딩을 위한 것입니다. 인증 작업을 하는 에이전트는 가이던스를 위해 authentication/patterns.md를, 알려진 함정을 피하기 위해 authentication/anti-patterns.md를 로드합니다. 파일들은 효율적인 컨텍스트 로딩에 맞는 크기입니다. 유용할 만큼 초점이 맞춰져 있으면서도, 권위를 가질 만큼 포괄적입니다.

우리는 애널리틱스, 인증, 데이터 사이언스, 인프라, 머신러닝, 성능, 보안 등을 포함한 21개의 최상위 도메인을 유지합니다. 각 도메인은 더 세밀한 단위를 위한 하위 도메인을 가질 수 있습니다.

가치: 운영체제

모든 에이전트는 자신이 어떻게 작동하는지를 정의하는 기본 가치 계층을 공유합니다.

단순함이 먼저. 작동하는 가장 단순한 해법을 사용하세요. 정당화될 때만 복잡성을 더하세요.

근본 원인을 고치세요. 실패를 임시방편으로 땜질하지 마세요. 파이프라인이 실패하면 파이프라인을 디버깅하세요. 테스트가 실패하면 코드나 테스트를 고치세요.

근거 기반. 주장을 (벤치마크가 있는) “검증됨”이나 (가정이 있는) “추정됨”으로 표시하세요. 패턴이 발견되었다고 해서 문제가 확인된 것은 아닙니다.

컨텍스트 경제학. MCP 도구는 컨텍스트의 0.1%를 소모합니다. 파일 읽기는 각각 2%를 소모합니다. 코드를 탐색하기 전에 도메인 전문성을 적용하세요.

이 가치들은 렌더링 파이프라인을 거쳐 모든 전문 에이전트에게 전파됩니다. 에이전트는 조합을 통해서도 이를 우회할 수 없습니다.

CLI: 제어 평면

Orkestra는 에이전트 생태계를 관리하기 위한 CLI와 함께 제공됩니다.

# Discovery
orkestra agents search "database"
orkestra agents info database-architect

# Validation
orkestra validate --show-warnings

# Rendering
orkestra sync --dry-run
orkestra sync

# Skills
orkestra skills list
orkestra skills info schema-migration-workflow

# Decisions
orkestra decisions search "authentication"

CLI는 어떤 에이전트가 존재하는지, 그들이 어떤 스킬을 갖고 있는지, 시스템이 건강한지에 대한 단일 진실 공급원(source of truth)입니다. 문제를 조기에 잡기 위해 동기화 전에 검증을 실행합니다.

오픈소스에 대한 고려

우리는 우리 자신의 문제를 해결하기 위해 Orkestra를 만들었습니다. 복잡한 코드베이스를 위해 대규모로 AI 에이전트를 조율하는 문제 말입니다. 우리가 발견한 패턴들은 우리 도메인에만 국한되지 않습니다.

캐릭터 조합 시스템(아이덴티티 + 마인드셋 + 스타일)은 에이전트 성격을 정의하는 어떤 팀에게도 적용됩니다.

스킬 계층 시스템(K0-K4)은 재사용 가능한 역량을 범위별로 정리하는 사고 모델을 제공합니다.

렌더링 파이프라인 패턴(YAML 소스 + 템플릿 + 생성된 산출물)은 도구와 모델 소비 사이의 관심사를 분리합니다.

단일 계층 오케스트레이션 모델(하나의 조율자, 다수의 전문가)은 병렬성을 가능하게 하면서도 복잡성을 피합니다.

Orkestra가 오픈소스가 될지는 Claude Code로 구축하는 다른 사람들에게 이 패턴들이 가치가 있는지에 달려 있습니다. 우리가 설명한 벽에 부딪히고 있다면, 이 아키텍처가 도움이 될지도 모릅니다.

우리가 배운 것

Orkestra를 만들면서 우리는 오케스트레이션이 에이전트를 더 똑똑하게 만드는 것이 아니라는 것을 배웠습니다. 이는 에이전트를 더 집중하게 만드는 것에 관한 일입니다.

완벽한 지침을 가진 단일 에이전트도 결국 컨텍스트가 바닥납니다. 모든 스킬을 가진 단일 에이전트도 어느 것을 적용해야 할지 혼란스러워합니다. 모든 것이 되려는 단일 에이전트는 모든 곳에서 평범한 결과를 냅니다.

각자의 도메인에서 뛰어난 40여 명의 전문가를, 언제 위임해야 할지 아는 오케스트레이터가 조율하는 것. 그것이 우리가 결과물을 내는 방식입니다.

수치는 아키텍처보다 덜 중요합니다. 여러분에게는 다섯 개의 에이전트가 필요할 수도, 쉰 개가 필요할 수도 있습니다. 원칙은 그대로입니다. 능력보다 조합, 일반화보다 전문화, 개인의 영웅적 활약보다 조율입니다.

Orkestra는 우리의 코드 인텔리전스 플랫폼인 Maguyva 뒤에 있는 에이전트 생태계를 구동합니다. 더 알고 싶으신가요? 팀에 문의하세요.