Harmonist: 186개의 전문 AI 에이전트와 기계적 프로토콜 강제 실행을 갖춘 멀티에이전트 오케스트레이션 프레임워크

9bow · 5월 11, 2026, 12:30오전

Harmonist 소개

AI 코딩 어시스턴트를 팀 단위의 에이전트 시스템으로 확장하려는 시도에서 가장 큰 장벽은 신뢰성입니다. 에이전트에게 "코드 변경 전 QA 검토자를 반드시 실행해라", "인증 코드를 수정할 때는 보안 리뷰를 통과해야 한다", "외부 API 호출에는 항상 멱등성(Idempotency) 키를 사용해라"와 같은 규칙을 프롬프트로 전달할 수 있지만, LLM이 이를 항상 준수한다는 보장이 없습니다. 모델은 규칙에 동의하고도 다음 턴에서 조용히 건너뛸 수 있으며, 나쁜 날에는 그 버그가 그대로 배포됩니다.

Harmonist는 이 문제에 근본적으로 다른 접근법을 취합니다. GammaLab Technologies가 오픈소스로 공개한 이 프레임워크는 프로토콜 준수를 프롬프트 요청이 아닌 **기계적 게이트(Mechanical Gate)**로 구현합니다. 코드 변경이 발생하는 모든 턴은 IDE 레벨 훅(Hook)을 통과해야 하며, 필수 리뷰어가 실행되었는지, 메모리가 업데이트되었는지, 배포 파일의 공급망(Supply chain) 무결성이 유지되는지를 확인합니다. 검사가 실패하면 해당 턴은 완료되지 않습니다. 모델이 아무리 자신 있게 "완료됐다"고 주장해도, 상태 머신(State machine)은 거부합니다.

                     ┌────────────────────────────┐
                     │        AGENTS.md           │
                     │      Orchestrator          │
                     │                            │
                     │  Protocol · Hook Phases    │
                     │  Invariants · Memory       │
                     └─────────────┬──────────────┘
                                   │  reads
                                   ▼
                     ┌────────────────────────────┐
                     │   agents/index.json        │   ← generated
                     │                            │
                     │   by category · by tag     │   ← routing table
                     │   186 entries              │
                     └─────────────┬──────────────┘
                                   │  routes to
            ┌──────────────────────┼──────────────────────┐
            ▼                      ▼                      ▼
     ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
     │ orchestration│      │   review     │      │   persona    │
     │ (scout,      │      │ (strict,     │      │ (engineering,│
     │  repo-map)   │      │  readonly)   │      │  design, …)  │
     └──────────────┘      └──────────────┘      └──────────────┘
                                   │                      │
            ┌──────────────────────┴──────────────────────┐
            ▼                                             ▼
     ┌──────────────┐                             ┌──────────────┐
     │ Review gates │                             │   .cursor/   │
     │              │                             │   memory/    │
     │ qa · sec     │                             │              │
     │ sre · perf   │                             │ session      │
     │ regression   │                             │ decisions    │
     └──────────────┘                             │ patterns     │
                                                  └──────────────┘

Harmonist는 Cursor, Claude Code, GitHub Copilot, Windsurf, Aider 등 주요 AI 코딩 어시스턴트에 드롭인(Drop-in) 방식으로 통합됩니다. 외부 런타임, 데이터베이스, 벤더 종속이 없습니다. 마크다운, 표준 라이브러리 Python, bash 스크립트만으로 구성되어 코드 옆에 위치하며, 하나의 역할을 올바르게 수행합니다. MIT 라이선스로 공개되어 있습니다.

Harmonist의 7가지 핵심 속성

Harmonist가 다른 오픈소스 에이전트 프레임워크와 구별되는 7가지 구체적인 속성이 있습니다.

1. IDE 훅을 통한 기계적 프로토콜 강제 실행: .cursor/hooks/의 스톱 훅(Stop hook)은 세션 내 서브에이전트 디스패치(Subagent dispatch) 마커를 파싱하고, QA 검증자가 실행되었는지, 필수 리뷰어가 빠지지 않았는지, session-handoff.md가 업데이트되었는지 확인합니다. 조건이 충족되지 않으면 followup_message를 반환하여 턴 완료를 거부합니다. loop_limit: 3으로 재시도를 최대 3회로 제한하며, 소진 시 인시던트(Incident)가 기록되어 다음 세션에 노출됩니다.

2. 에이전트 정의 공급망 검증: 모든 배포 파일은 MANIFEST.sha256에 해시가 기록됩니다. upgrade.py는 각 소스를 프로젝트에 복사하기 전 SHA를 검증하며, 변조된 파일은 거부됩니다. 예를 들어 "모든 요청에 승인을 반환"하도록 수정된 security-reviewer.md는 절대 프로젝트에 진입할 수 없습니다.

3. LLM이 위조할 수 없는 메모리 상관 ID: 모든 메모리 항목은 세션 시작 시 훅이 생성하는 <session_id>-<task_seq> 형식의 correlation_id를 갖습니다. LLM은 ID를 읽을 수만 있으며, 절대 쓸 수 없습니다. 이를 통해 동일 태스크 내 상태 항목, 결정, 패턴 사이의 연결이 훅의 관점에서 암호적으로 정렬됩니다.

4. 시크릿 패턴 스캐닝을 포함한 스키마 검증 메모리: memory.py append는 유일하게 지원되는 쓰기 경로입니다. YAML 스키마(memory/SCHEMA.md)에 대해 모든 항목을 검증하고, 중복을 거부하며, AWS 액세스 키, GitHub PAT, Stripe 토큰, Slack 웹훅, GCP 서비스 어카운트 등 30개 유형의 시크릿 패턴을 스캔합니다. ${VAR}, <NAME> 형식의 플레이스홀더는 스캔을 억제하여 템플릿이 정상적으로 작동할 수 있습니다.

5. 186개의 큐레이션된 도메인 전문가: 단일 범용 "코더" 에이전트가 아닌, 16개 카테고리에 걸쳐 186개의 전문 에이전트 카탈로그를 제공합니다. blockchain-security-auditor(Solidity 감사), zk-steward(영지식 회로), visionos-spatial-engineer(Apple Vision Pro), laravel-livewire-specialist(PHP), roblox-systems-scripter(Roblox Luau), 30개 이상의 마케팅 에이전트, 금융/영업/제품/지원/학술 커버리지 등이 포함됩니다. 오케스트레이터는 하드코딩된 슬러그 목록이 아닌 도메인 × 역할 × 태그로 에이전트를 선택합니다.

6. 프롬프트로서의 통합(Integration-as-a-Prompt): 별도의 설치 바이너리가 없습니다. integration-prompt.md를 Cursor 에이전트 모드 세션에 붙여넣으면 AI가 직접 통합을 수행합니다. AI는 프로젝트를 분석하고, 활성화할 역할(엔지니어링/디자인/제품/마케팅 등)을 확인하고, agents/index.json에서 적절한 전문가를 선택하여 도메인 맞춤형 불변 규칙을 포함한 AGENTS.md를 작성합니다.

7. 런타임 의존성 없는 크로스플랫폼 동작: npm, Docker, LangChain, 벡터 데이터베이스 없이 순수 Python 표준 라이브러리와 bash만 사용합니다. macOS/Linux/WSL용 POSIX .sh 스크립트와 Windows용 순수 Python hook_runner.py 두 가지 구현체가 CI에서 430개 이상의 테스트 어설션으로 동일한 동작을 보장합니다.

Harmonist 설치 및 사용

# Cursor 에이전트 모드에 붙여넣기
cat integration-prompt.md

또는 수동으로 에이전트를 선택하여 설치:

# 필요 사항: Python 3.9+, Git, AI 코딩 어시스턴트
# Claude Code, Cursor, Copilot, Windsurf, Aider 등 지원

# 저장소 클론
git clone https://github.com/GammaLabTechnologies/harmonist.git

# 특정 도메인 에이전트만 설치
python3 install_extras.py --domain engineering --role security-reviewer

# 메모리 항목 추가 (유일하게 지원되는 쓰기 경로)
python3 memory.py append \
  --category "architecture" \
  --body "인증 모듈은 외부 API 호출 시 항상 OAuth 2.0을 사용한다"

훅이 프로토콜 위반을 감지하면 다음과 같은 메시지가 반환됩니다:

[Harmonist Stop Hook] 프로토콜 위반 감지:
- qa-verifier가 실행되지 않았습니다 (필수)
- session-handoff.md가 업데이트되지 않았습니다
이 턴은 완료될 수 없습니다. 위 항목을 해결하세요.

Harmonist 지원 플랫폼

Harmonist는 서브에이전트 디스패치를 지원하는 모든 AI 코딩 어시스턴트와 호환됩니다. 공식 통합이 제공되는 플랫폼은 다음과 같습니다.

Cursor (주 통합 대상)
Claude Code, GitHub Copilot, Windsurf, Aider
Kimi, Qwen, Gemini CLI, OpenCode, OpenClaw, Antigravity

라이선스

Harmonist는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용, 수정, 배포할 수 있습니다.

Harmonist 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~