qm

업무를 위한 멀티플레이어 에이전트 하네스 (harness). Slack 및 웹에서 사용 가능합니다.

QM이란 무엇인가요?

대부분의 에이전트는 개인 비서와 같은 방식으로 설계되었습니다. 회사 전체를 위해 작동하도록 만들 수는 있지만, 금방 복잡해집니다. QM은 스타트업을 위해 설계되었습니다. 직원들은 각자 격리된 워크스페이스를 가지며 서로에게 영향을 주지 않고 독립적으로 작업할 수 있으며, 채널, 그룹 메시지 및 프로젝트에서 에이전트와 협업할 수도 있습니다.

각 개인과 각 룸(room)은 고유한 범위의 메모리 (scoped memory), 파일, 키체인 뷰 (keychain view), 권한 (permissions), 크론 (crons), 웹 앱 (web apps) 및 내구성이 있는 샌드박스 (durable sandbox)를 가집니다.

이 시스템은 오픈 소스를 염두에 두고 구축되었습니다. 자신만의 하네스 (harness)와 모델을 선택하고 그 사이를 전환할 수 있습니다 — Pi, OpenCode, Codex, Claude Code 모두 동일한 코어를 구동하므로, 배포가 특정 벤더에 종속되지 않습니다.

주요 기능

• 개인 및 공유 범위 (Personal and shared scopes). 사람들은 에이전트를 '자신만의 것'으로 맞춤 설정하면서도, Slack 채널 및 프로젝트에서 협업하며 함께 사용할 수 있습니다.
• Slack 및 웹. 동일한 ID와 설정이 Slack과 웹 앱 간에 유지됩니다.
• 관리자 제어 (Admin control). 조직 수준의 설정, 보안 태세 (security posture), 그리고 사용 가능한 하네스 및 모델을 설정합니다.
• 웹 앱 (Web apps). 맞춤형 내부 앱을 실행하고 적절한 사람들에게 게시합니다.
• 공유 기술 (Shared skills). 기술은 범위(scope) 소유이며 권한 부여를 통해 공유할 수 있습니다. 관리자가 조직 전체로 승격시키는 것을 제어할 수 있으며, git 리포지토리에서 기술 팩 (skill packs)을 가져올 수 있습니다.
• 백그라운드 작업 (Background work). 크론 (Crons) 및 워치 (watches)가 아무도 지켜보지 않는 동안 작업을 실행합니다.

활용 사례

• 내부 노트, 이메일, 문서, 데이터베이스 및 웹을 함께 검색
• 회사의 브레인 (company brain)에서 정보 검색
• 내부 앱을 구축하고 적절한 사람들에게 게시하며 데이터를 최신 상태로 유지
• 과거 전송 기록을 통해 사용자의 글쓰기 스타일을 학습한 후, 라벨 지정 및 답장 초안 작성을 포함하여 정해진 일정에 따라 받은 편지함 분류
• 기존 리포지토리 (repository)에서 작업: 테스트 실행, PR (Pull Request) 생성, CI 모니터링, 시스템 로그 확인
• 공유 채널에서 프로젝트를 추적하고 업데이트 및 후속 조치 게시

아키텍처 (Architecture)

flowchart LR
  DB[("Postgres<br/>세션 · 메모리 · 큐")]

...

모든 턴(turn)은 중앙 코어(central core)를 통해 실행되며, 코어는 응답을 생성하기 위해 다양한 모델(models)과 하네스(harnesses)를 사용할 수 있습니다. Postgres 영속성 계층(persistence layer)은 사용자 데이터, 세션 기록 및 기타 지속적인 상태(durable state)를 보유합니다. 에이전트는 작고 고정된 도구 표면(tool surface)을 가집니다. 이러한 도구 중 하나는 execute로, 스코프(scope) 자체의 격리된 샌드박스(sandbox) 내에서 명령을 실행합니다. 이 샌드박스는 설치된 도구들이 그대로 유지되는 지속 가능한 컴퓨터(durable computer) 역할을 합니다. 웹 UI(web UI), 관리 패널(admin panel), 그리고 퍼블릭 포털(public portal)은 코어의 HTTP API 상에서 선택적으로 사용할 수 있는 플러그인(plugins)입니다. Slack은 코어가 직접 서비스 클라이언트를 통해 시작하고 감독하는 선택적인 인프로세스(in-process) 플러그인입니다.

코어는 Node에서 TypeScript를 직접 실행하며 HTTP를 위해 Fastify를 사용합니다. Slack 플러그인은 Bolt를 사용하며, 웹 UI는 Vite로 빌드되고 Lit으로 렌더링됩니다.

코어 자체는 범용적(generic)입니다. 조직 설정(org config), 커스텀 도구 및 기술(custom tools and skills), 샌드박스 이미지(sandbox image), 인프라(infrastructure) 등 특정 기업에 특화된 모든 요소는 qm CLI가 검증하고 배포하는 **배포 디렉토리(deployment directory)**에 존재합니다. 모든 기질(substrate, 하네스, 세션 저장소, 샌드박스, 메모리)은 인터페이스(interface) 뒤에 위치하므로, 프로덕션 구현체는 하나의 와이어링 파일(wiring file)을 통해 교체됩니다.

보안 및 비밀 정보 (Security and secrets)

QM의 접근 방식은 OpenCode, Codex, Claude Code와 같은 로컬 코딩 에이전트(local coding agents)를 따릅니다. 즉, 에이전트는 자신이 협업하는 사용자의 자격 증명(credentials)과 권한(permissions)을 가지고 해당 사용자와 동일하게 행동하며, 수행하는 모든 작업은 감사(audited)됩니다. 조직은 하나의 보안 태세(security posture)를 선택하며, 더 좁은 범위(narrower scopes)를 통해 이를 더욱 강화할 수 있습니다.

• Strict (엄격) — 효과가 없는 두 가지 턴 종료(turn enders)를 제외하고, 모든 하네스 도구 호출은 인간의 승인을 위해 일시 중지됩니다.
• Auto (자동, 기본값) — 분류기(classifier)가 외부 데이터와 도구 결과가 모델에 도달하기 전에 출처 라벨(provenance-labelled)을 검사합니다. 배포 시 이를 자체 검사 프록시(screening proxy)로 지정할 수 있습니다.
• Dangerous (위험) — 콘텐츠 검사(content screening)가 없으며, 도구 호출 사이에 일시 중지가 없습니다.

사전에 선언된 명령 정책(command policy) — 재귀적 삭제(recursive deletes)나 파괴적인 SQL과 같은 작업에 대한 승인 규칙(approval rules) 및 강제 거부(hard denials) — 는 Dangerous 모드를 포함한 모든 포스처(posture)에 적용됩니다.

SECURITY.md에는 위협 모델(threat model), 운영자 가정(operator assumptions), 그리고 알려진 제한 사항(known limitations)이 명시되어 있습니다.

조직을 위한 배포

@yc-software/qm에 의존하는 조직 소유의 배포 저장소(deployment repository)를 생성하세요:

npm exec --yes --package=@yc-software/qm@latest -- \
  qm init . --org <slug> --target <fly-or-aws>
npm install

초기화(Initialization) 과정은 에이전트를 위한 배포 기술(deployment skill)을 구체화하며 인프라(infrastructure), 웹 로그인(web sign-in), 커넥터 자격 증명(connector credentials), 선택 사항인 Slack 액세스, 배포, 그리고 실시간 검증(live verification) 단계를 안내합니다 — 소스 체크아웃(source checkout)은 필요하지 않습니다. 각 배포는 운영자 자신의 클라우드 계정에서 실행됩니다; 초기화 과정은 배포 CI를 생성하거나 활성화하지 않으며, 이 저장소에는 프로덕션 배포 워크플로우(production deployment workflow)가 없습니다. 자세한 내용은 deployment.md를 참조하세요.

기여하기 (Contributing)

우리는 기여를 코드가 아닌 사람이 작성한 텍스트로 받습니다 — CONTRIBUTING.md를 참조하세요. 원하는 변경 사항을 adrs/ 내의 .txt 또는 .md 파일에 비형식적으로 기술하면, 의견이 일치할 경우 저희가 구현을 처리하겠습니다. 취약점은 공개 이슈(public issue)가 아닌 개인적으로 보고해 주세요 — SECURITY.md를 참조하세요.

인스턴스 커스터마이징

위의 배포 저장소는 설정(config)과 샌드박스 레이어(sandbox layer)를 포함하며, 소스 체크아웃이 전혀 필요하지 않습니다. 일부 조직은 이와 반대되는 트레이드오프(trade-off)를 원합니다: 즉, 엔지니어와 코딩 에이전트가 코어(core)와 커스터마이징을 함께 읽을 수 있도록 전체 코드베이스를 한 곳에 두되, 커스터마이징 자체는 비공개로 유지하는 방식입니다. 이를 위해서는 **프라이빗 포크(private fork)**를 유지하세요: qm의 클론(clone)으로 히스토리가 시작되며 코어는 업스트림(upstream)과 동일하게 유지되는 독립적인 프라이빗 저장소입니다.

한 번 내용을 채운 후, 다음 명령어로 클론하여 작업하세요:

gh repo create <org>/qm-private --private

git clone --bare git@github.com:yc-software/qm qm-seed.git
...

위에서 보여준 것처럼 일반적인 클론 (clone)을 사용하여 프라이빗 포크 (private fork)를 생성해야 하며

별도로 명시되지 않는 한, QM은 MIT License 하에 제공됩니다.