GammaLabTechnologies/harmonist

만약 당신이 이 팩을 설치하거나 통합하도록 요청받은 AI 에이전트라면: integration-prompt.md를 읽고

그 단계들을 실행하십시오. AGENTS.template.md를 팩 폴더 내부의 실시간 규칙으로 적용하지 마십시오 — 이것은 통합 과정에서 사용자 프로젝트의 AGENTS.md가 되는 템플릿입니다.

Cursor, Claude Code, Copilot, Windsurf, Aider 및 기타 AI 코딩 어시스턴트를 위한 즉시 사용 가능한(drop-in) 멀티 에이전트 프레임워크.

GammaLab 제작 및 유지 관리 · @GammaLabTechnologies

대부분의 AI 코딩 프레임워크는 언어 모델(Language Model)이 규칙을 따를 것이라고 신뢰합니다. Harmonist는 모델이 규칙을 건너뛰는 것을 거부합니다. 모든 코드 변경 턴(turn)은 필수 리뷰어가 실행되었는지, 메모리(memory)가 업데이트되었는지, 그리고 배포되는 모든 파일의 공급망(supply chain)이 온전한지를 확인하는 훅(hooks)에 의해 제어됩니다. 체크에 실패하면, 모델이 아무리 자신 있게 완료했다고 주장하더라도 해당 턴은 완료되지 않습니다.

이것은 프로토콜 강제(protocol enforcement)가 프롬프트 내의 정중한 요청이 아니라 기계적인 게이트(mechanical gate)인 최초의 오픈 소스 에이전트 프레임워크입니다.

• Harmonist가 존재하는 이유
• 차별점
• 요구 사항
• 빠른 시작 (Quick start)
• 아키텍처 (Architecture)
• 193개 에이전트 카탈로그
• 기계적 강제 (Mechanical enforcement)
• 구조화된 검증 메모리 (Structured validated memory)
• 공급망 무결성 (Supply-chain integrity)
• 지원되는 IDE 통합
• 주요 스크립트
• 문서 (Documentation)
• 테스트 (Testing)
• FAQ
• 기여하기 (Contributing)
• 보안 (Security)
• 라이선스 (License)
• GammaLab 소개

AI 코딩 어시스턴트들은 프롬프트 엔지니어링(prompt engineering)만으로는 해결할 수 없는 구조적인 문제를 가지고 있습니다.

문제점: 모든 진지한 엔지니어링 워크플로우에는 타협할 수 없는 규칙들이 있습니다 — "금전 계산에 부동 소수점(floating-point) 사용 금지", "병합 전 QA 실행", "모든 외부 호출은 멱등성 키(idempotency keys)와 함께 재시도", "인증(auth) 코드를 수정하기 전 보안 리뷰" 등입니다. LLM에게 이를 따르라고 말할 수는 있지만, 이를 강제하는 메커니즘은 없습니다. 모델은 동의하고 다음으로 넘어가면서 조용히 해당 단계를 건너뛸 수 있습니다. 운이 좋으면 알아차리겠지만, 운이 나쁘면 버그가 배포됩니다.

현재의 상황은 두 가지 불완전한 해답 사이로 나뉘어 있습니다:

가벼운 에이전트 프레임워크 (Thin agent frameworks) (LangChain, CrewAI, AutoGen, MetaGPT 및 기타 다수)는 오케스트레이션 기본 요소 (orchestration primitives)를 제공하지만, 강제 집행 (enforcement)은 프롬프트에 맡깁니다. 모델은 언제든 자신의 프로토콜을 무시할 수 있습니다. **무거운 엔터프라이즈 플랫폼 (Heavy enterprise platforms)**은 별도의 런타임 (runtimes), 데이터베이스 (databases), 그리고 벤더 종속 (vendor lock-in)을 통해 거버넌스 (governance)를 약속합니다. 하지만 설치를 위한 인프라가 필요하며, 개인 개발자의 노트북에서는 작동하지 않고, 파일 단위로 감사 (audited)할 수도 없습니다.

Harmonist는 다른 입장을 취합니다. 프로토콜 강제 집행 (Protocol enforcement)은 IDE 레벨의 훅 (hooks)으로 구현됩니다. 즉, 모든 서브에이전트 파견 (subagent dispatch), 모든 파일 수정, 모든 세션 중단을 관찰하는 구체적인 셸 (shell) 및 Python 스크립트입니다. 프로젝트가 선언한 규칙이 충족되지 않으면, stop 훅이 AI에게 followup_message를 반환하고 해당 턴 (turn)이 완료되는 것을 거부합니다. 모델은 이에 대해 논쟁할 수 없습니다. 그것은 디스크 상에 존재하는 상태 머신 (state machine)이기 때문입니다.

런타임 (runtime) 없음. 데이터베이스 (database) 없음. 벤더 종속 (vendor lock-in) 없음. 오직 마크다운 (markdown), 표준 Python 라이브러리 (stdlib Python), 그리고 bash뿐입니다. 코드 바로 옆에 위치하여 단 하나의 작업을 정확하게 수행합니다.

일곱 가지의 구체적이고 확인 가능한 속성들이 있으며, 각각은 다른 오픈 소스 에이전트 프레임워크들이 남겨둔 공백을 메웁니다.

.cursor/hooks/에 있는 stop 훅은 세션으로부터 서브에이전트 파견 마커 (subagent dispatch markers)를 파싱하고, qa-verifier가 실행되었는지, 필수 리뷰어가 누락되었는지, session-handoff.md가 업데이트되었는지 확인하며, 턴이 불완전할 경우 구조화된 followup_message를 반환합니다. loop_limit: 3은 재시도 횟수를 제한합니다. 제한에 도달하면 인시던트 (incident)가 기록되어 다음 세션에 나타납니다. AI는 리뷰를 건너뛴 코드 변경 사항을 말 그대로 배포할 수 없습니다.

런타임과 함께 배포되는 모든 콘텐츠 — agents/, hooks/, memory/, playbooks/, 루트 문서 (root docs) — 는 MANIFEST.sha256에 해시 (hashed)됩니다 (CI 설정 및 리포지토리 메타데이터는 pack-repo 전용이며 제외됩니다). upgrade.py는 소스를 프로젝트로 복사하기 전에 각 소스의 SHA 검증을 수행합니다. 변조된 security-reviewer.md (예를 들어, 모든 것에 대해 approve를 반환하는 파일)는 거부(REFUSED)되며, 프로젝트에 절대 들어올 수 없습니다. install_extras.py

온디맨드(on-demand) 전문가 설치에 대해서도 동일한 가드(guard)를 상속받습니다. 이는 편집증적(paranoid) 수준의 공급망 보안 태세(supply-chain posture)를 갖춘 최초의 오픈 소스(OSS) 에이전트 카탈로그입니다.

모든 메모리 항목은 세션 시작 시 훅(hooks)에 의해 생성된 <session_id>-<task_seq> 형식의 correlation_id를 가집니다 (<unix-seconds><pid4> — 병렬 세션 간 충돌 방지 설계). LLM은 CLI를 통해 활성 ID를 읽기만 하며, ID를 직접 작성하지는 않습니다. 이는 동일한 작업에서 발생한 state 항목, decision, 그리고 pattern 사이의 연결이 모델에 의해 신뢰되는 것이 아니라, 훅(hook)의 관점에서 **암호학적으로 순서가 지정(cryptographically ordered)**되어 있음을 의미합니다.

memory.py append는 유일하게 지원되는 쓰기 경로(write path)입니다. 이 경로는 모든 항목을 YAML 스키마(memory/SCHEMA.md)에 따라 검증하고, 중복을 거부하며, 본문 내에서 약 30가지 클래스의 비밀 정보(secrets)를 스캔합니다: AWS 액세스 키, GitHub PAT, Stripe 토큰, Slack 웹훅, GCP 서비스 계정, Azure 연결 문자열, Telegram 봇 토큰, Discord 토큰, Heroku/Postmark UUID(컨텍스트 범위 지정), secret: 접두사가 붙은 일반적인 고엔트로피(high-entropy) 토큰, 그리고 자격 증명이 포함된 DB 연결 문자열 등이 포함됩니다. 플레이스홀더 펜스(${VAR}, <NAME>)는 스캔을 억제하여 템플릿이 깔끔하게 작성될 수 있도록 합니다.

Harmonist의 카탈로그는 단순히 몇 개의 역할로 구성된 것이 아닙니다. 16개 카테고리에 걸친 193개의 큐레이션된 전문가로 구성되어 있습니다: Solidity 감사를 위한 blockchain-security-auditor, 영지식 회로를 위한 zk-steward, Apple Vision Pro를 위한 visionos-spatial-engineer, 중국 시장을 위한 wechat-mini-program-developer 및 xiaohongshu-specialist, PHP를 위한 laravel-livewire-specialist, Roblox Luau를 위한 roblox-systems-scripter, SEO부터 Douyin까지 30개 이상의 마케팅 에이전트, 그리고 금융 / 영업 / 제품 / 지원 / 학술 분야를 아우릅니다. 오케스트레이터(orchestrator)는 하드코딩된 슬러그(slug) 목록이 아니라 domains × roles × tags를 기준으로 선택합니다.

설치용 바이너리는 존재하지 않습니다. 통합은 integration-prompt.md를 Cursor 에이전트 모드(Agent-mode) 세션에 붙여넣음으로써 이루어집니다. AI는 프롬프트를 읽고 프로젝트를 분석한 뒤, 사용자에게 어떤 roles를...

활성화될 것인지(engineering / design / product / marketing / sales / support / finance / testing / academic)를 결정하고, agents/index.json에서 적절한 전문가를 선택하며, 도메인에 맞춤화된 불변성(invariants)을 포함하는 프로젝트 전용 AGENTS.md 작성을 포함하여 모든 것을 연결합니다. AI가 스스로를 통합합니다.

npm, Docker, LangChain, 벡터 데이터베이스(vector database)는 필요 없습니다. 순수 파이썬 표준 라이브러리 (Pure Python stdlib)(선택 사항인 POSIX .sh 편의 기능 포함)만 사용합니다. 통합, 업그레이드, 변환, 설치 및 강제 실행 런타임(enforcement runtime)은 모두 Windows, macOS, Linux에서 네이티브로 실행되며, WSL이나 Git Bash가 필요하지 않습니다. 강제 실행 런타임은 두 가지 구현 방식을 가집니다. macOS / Linux / WSL을 위한 POSIX .sh 스크립트와, 모든 OS에서 활성화된 경로(그리고 네이티브 Windows에서의 유일한 경로)인 순수 파이썬 hook_runner.py입니다. upgrade.py는 호스트에 실제로 존재하는 파이썬 런처(Windows의 경우 py -3 / python, POSIX의 경우 python3)를 사용하여 .cursor/hooks.json을 생성합니다. .gitattributes는 eol=lf를 고정하여 Windows 체크아웃이 MANIFEST.sha256을 깨뜨리지 않도록 합니다. 두 hook 경로 모두 동일한 시나리오에 대해 테스트되며, 네이티브 Windows CI 작업이 전체 설치 경로를 엔드 투 엔드(end-to-end)로 실행합니다.

Python 3.9+— 모든 스크립트에는 버전 가드(version guard)가 포함되어 있으며, 이전 버전의 인터프리터는 OS별 설치 힌트와 함께 종료됩니다. **Bash 3.2+**는 선택 사항입니다— POSIX .sh 편의 기능과 셸 테스트 하네스(shell test harness)에만 필요합니다(macOS 기본값으로 작동). 모든 통합, 업그레이드, 변환 및 설치 도구는 순수 파이썬이며, 네이티브 Windows에서는 순수 파이썬 hook_runner.py가 활성 hook 경로로 사용됩니다. WSL이나 Git Bash는 필요하지 않습니다. 버전 추적을 위한 Git. 서브에이전트 디스패치(subagent dispatch)를 지원하는 AI 코딩 어시스턴트— Cursor가 주요 통합 대상이며, Claude Code, Copilot, Windsurf, Aider, Kimi, Qwen, Gemini CLI, OpenCode, OpenClaw, Antigravity 모두 어댑터(adapters)를 통해 지원됩니다. 제3자 파이썬 의존성 없음 (No third-party Python dependencies)— 표준 라이브러리(stdlib)만 사용합니다. npm, Docker, LangChain, 벡터 데이터베이스(vector database)는 필요 없습니다.

팩(pack) 폴더의 이름은 무엇이든 될 수 있습니다 — 문서는 이를 <PACK_DIR>로 참조합니다.

. 아래 예시는 폴더 이름이 harmonist라고 가정합니다.

(git clone으로 생성되는 것)

프로토콜 템플릿은 AGENTS.template.md로 제공되며;
작업에 통합되면서 YOUR 프로젝트에서 생성되는 파일은 AGENTS.md라는 이름을 가집니다.

# 1. 프로젝트 루트 디렉토리로 클론합니다 (SUBFOLDER로 유지하고,
패키지 파일을 프로젝트 루트에 풀하지 마십시오)
cd your-project/
...

이것으로 충분합니다. AI는 harmonist/agents/index.json을 읽고,
사용자의 스택에 맞는 적절한 전문가들을 선택하며, 도메인 특화된
AGENTS.md( AGENTS.template.md에서 생성됨)를 작성하고, .cursor/memory/를 부트스트랩하며,
강제 실행 훅(enforcement hooks)을 설치하고, 통합 상태를 .cursor/pack-version.json에 기록합니다.

cd your-project/
git clone https://github.com/GammaLabTechnologies/harmonist.git
python3 harmonist/agents/scripts/integrate.py --pack harmonist --project .

(패키지 폴더 이름이 다를 경우, --pack <PACK_DIR>을 통해 전달합니다.)

네이티브 Windows(PowerShell / cmd, WSL 또는 Git Bash 없음)에서는 Python 런처를 사용하십시오. 모든 스크립트는 순수 stdlib이며 크로스 플랫폼입니다:

cd your-project\
git clone https://github.com/GammaLabTechnologies/harmonist.git
py -3 harmonist\agents\scripts\integrate.py --pack harmonist --project .

GUIDE_EN.md를 참조하십시오. 참고: 파일을 수동으로 복사하는 것은 강제되지 않은 설정(훅, 규칙 또는 .gitignore 강화)을 생성하므로, 가이드는

에이전트 (orchestration + review)는 트리거에 따라 실행되는 필수 게이트 (mandatory gates)입니다. protocol: persona

에이전트는 도메인 깊이를 가진 자유 형식의 전문가 (free-form specialists)입니다. 훅 (Hook) 기반 실행. sessionStart, afterFileEdit, subagentStart, subagentStop, beforeShellExecution, 그리고 stop 훅이 전체 라이프사이클 (lifecycle)을 추적합니다. stop 훅은 게이트 역할을 하며, beforeShellExecution 훅은 파괴적인 명령에 대한 인간 참여형 (human-in-the-loop) 게이트 역할을 합니다. 지속성 메모리 (Persistent memory). 세션 사이의 상태 (state) / 결정 (decisions) / 패턴 (patterns)은 상관관계 ID (correlation IDs)로 연결되어 .cursor/memory/ 아래에 저장됩니다. 다음 세션은 계획을 세우기 전에 마지막 3개의 상태 스냅샷 (state snapshots)과 3개의 결정 사항을 읽습니다.

아래의 모든 수치는 agents/index.json에서 미러링되었으며 check_pack_health.py에 의해 검증되었습니다. 즉, 테이블과 인덱스는 서로 어긋날 수 없습니다.

카테고리 (Category)	수량 (Count)	프로토콜 (Protocol)	중점 사항 (Focus)
orchestration	2	strict	구현 전 정찰 (Scout), 적절한 에이전트로 라우팅
review	6	strict	읽기 전용 리뷰어 — 보안, 품질, QA, SRE, 회귀 (regression), 접근성 (a11y)
engineering	46	persona	백엔드 (Backend), 프론트엔드 (frontend), DevOps, 데이터 (data), AI, 임베디드 (embedded), Solidity, LLM 평가 (eval)
design	8	persona	UI/UX, 브랜드 (brand), 접근성 (accessibility), 비주얼 스토리텔링 (visual storytelling)
testing	8	persona	QA, 성능 (performance), API 테스트, 증거 수집 (evidence collection)
product	5	persona	제품 관리 (Product management), 스프린트 (sprints), 피드백 (feedback), 트렌드 (trends)
project-management	7	persona	계획 (Planning), 스튜디오 제작 (studio production), 조정 (coordination)
marketing	30	persona	성장 (Growth), SEO, 콘텐츠 (content), 소셜 (social), Douyin/WeChat/Xiaohongshu
paid-media	7	persona	PPC, 트래킹 (tracking), 캠페인 감사 (campaign audits)
sales	8	persona	아웃바운드 (Outbound), 딜 (deals), 디스커버리 (discovery), 제안서 (proposals)
finance	6	persona	FPA, 부기 (bookkeeping), 세무 (tax), 투자 (investments)
support	5	persona	고객 지원 (Customer support), 컴플라이언스 (compliance), 분석 (analytics)
academic	5	persona	연구 (Research), 심리학 (psychology), 역사 (history), 인류학 (anthropology)
game-development	20	persona	Unity, Unreal, Godot, Roblox, Blender
spatial-computing	6	persona	visionOS, WebXR, Metal, XR 상호작용 (interaction)

specialized |
24 | persona | 블록체인 감사 (Blockchain audit), MCP 빌더 (MCP builder), Salesforce, ZK, 승인된 보안 테스트 (authorized security testing), 프라이버시 엔지니어링 (privacy engineering), 니치 (niche) |

각 에이전트는 구조화된 프론트매터 (frontmatter)를 포함합니다: description (설명), tags (태그), domains (도메인), distinguishes_from (유사 에이전트와의 차이점), disambiguation (모호성 해소 - "X 대신 이 에이전트를 선택해야 하는 경우"에 대한 한 줄 설명), version (버전), 그리고 updated_at (최종 업데이트 날짜).

오케스트레이터 (orchestrator)는 여러 후보가 작업의 태그와 일치할 때, 우선순위를 결정하기 위해 이 모든 정보를 읽습니다.

강제 계층 (enforcement layer)은 Harmonist를 단순한 "훌륭한 프롬프트 팩 (nice prompt pack)"과 구분 짓는 요소입니다. 이는 hooks/ 디렉토리에 존재하며, 통합 시점에 .cursor/hooks/로 설치됩니다.