용어집

핵심 엔티티

에이전트: 신원, 역할, 스킬, 어댑터를 갖춘 AI 워커입니다. 정확히 하나의 워크스페이스에 속합니다. 시스템의 주된 행위자입니다.

어댑터: 에이전트 턴을 실행하는 러너입니다. 두 가지가 기본 제공됩니다. Control Center(내장) — 모델 공급자와 대화하는 인프로세스 하네스 — 와 claude -p를 통한 Claude Code입니다. Cursor, Codex, Anthropic, OpenAI 및 나머지는 별도의 CLI가 아니라 내장 어댑터 위의 공급자입니다. 어댑터와 모델 관리를 참고하십시오.

워크스페이스: 최상위 격리 테넌트입니다. 에이전트, 저장소, 스페이스, 티켓, 메모리, 파이프라인을 묶습니다. 격리는 관례가 아니라 구조적입니다. 각 워크스페이스는 자체 SQLite 파일(<dataDir>/<workspaceId>/workspace.db)을 가지므로 워크스페이스를 넘는 읽기는 컴파일되지 않습니다. 앱 내 모든 라우트에는 /workspaces/:workspaceId 접두사가 붙습니다. 자세한 내용은 라우트 맵을 참고하십시오.

코드 호스트: GitHub, GitLab 또는 Bitbucket Cloud를 말합니다. 코드 호스트는 각 저장소의 속성으로, 등록할 때 origin 리모트에서 읽으며, 그 저장소의 API 어댑터와 자격 증명을 선택합니다. 하나의 워크스페이스가 세 곳 모두의 저장소를 담을 수 있고, 집계 화면(받은편지함, PR 큐)은 등장한 모든 코드 호스트로 팬아웃해 결과를 병합하며, 실패를 격리하므로 접속할 수 없는 코드 호스트가 나머지를 비우는 일은 없습니다. 코드 호스트는 지원 범위가 서로 다릅니다. 기능 표는 코드 호스트 연결을 참고하십시오.

저장소: 하나의 워크스페이스 안에 등록된 Git 저장소입니다. 워크스페이스 범위입니다. 같은 체크아웃을 두 워크스페이스에 등록하면 서로 다른 id를 가진 두 개의 독립 행이 되며, 워크스페이스를 넘는 저장소 동일성은 id가 아니라 파일 시스템 경로로 정해집니다. 등록에는 origin 리모트가 지원되는 코드 호스트를 가리키는 git 작업 트리가 필요합니다. 각 저장소는 그 코드 호스트(github / gitlab / bitbucket)를 가지며, 이것이 사용할 API 어댑터와 자격 증명을 선택합니다.

격리 저장소: 등록된 저장소의 워크스페이스 범위 워크트리입니다. 해당 네이티브가 제공되는 곳에서는 rift를 통한 기록 중 복사, Windows에서는 git worktree를 씁니다. 스페이스마다 프로비저닝되므로 그 스페이스의 모든 대화가 하나의 체크아웃을 공유하며, 에이전트는 원본을 결코 변경하지 않습니다.

스페이스: 사람과 에이전트 참여자, 영속화된 Mode, 프로비저닝 상태, 그리고 SpaceKind(topic / agentPeer / system / pr / slack)를 갖는 워크스페이스 범위 협업 컨테이너로, 이것이 스페이스의 구획, 음소거, 배지, 가비지 컬렉션 방식을 결정합니다. 대화가 공유하는 격리 워크트리를 소유합니다(rift를 통한 기록 중 복사, Windows에서는 git worktree).

대화: 스페이스 안의 하나의 메시지 스트림으로, 자체 id, 기록, 에이전트 실행 컨텍스트를 갖습니다. 스페이스 안의 대화는 대등한 평면적 관계로, 주 스트림이나 “메인” 스트림은 없습니다. 각각은 에디터 탭으로 열리며, 스페이스의 읽지 않음 상태는 이들 전체를 집계합니다.

스레드: anchorMessageId가 설정된 대화입니다. 같은 스페이스의 형제 대화 메시지 하나에 고정되며, 그 앵커 메시지로 시드된 새 에이전트 컨텍스트를 갖습니다. 깊이는 한 단계뿐으로, 스레드가 스레드에 고정되는 일은 없습니다.

티켓: 작업 단위 애그리게이트입니다. 공급자 중립적이며 기본은 local이고, Linear, GitHub Issues, Jira Cloud, ClickUp을 위한 동기화 어댑터를 갖지만 앱 안에서 동기화 연결을 만드는 화면은 없습니다. 계층, 링크, 위임을 지원합니다. 에이전트에 할당하면 소유권만 기록하고 아무것도 디스패치하지 않으며, 팀에 할당하는 것이 예외입니다(TeamRoutingService가 리더를 디스패치합니다).

파이프라인: 단계(에이전트 디스패치, 스크립트, 조건)를 연결하는 DAG 기반 워크플로입니다. 템플릿으로 정의하고 실행으로 실행합니다.

값 객체

AgentRole: 열거형 역할(CEO, coder, reviewer, QA, designer, security, devops, PM, general)입니다. 페르소나, 메모리 접근, 계층을 결정합니다.

AgentSkills: 디스패치 시점에 관련 컨텍스트를 프롬프트에 주입하는, 대소문자를 구분하지 않는 스킬 식별자 집합입니다.

스킬 소스: 스킬 카탈로그로 워크스페이스마다 등록하는 GitHub 저장소입니다. 구조적으로 신뢰하지 않습니다. 저장소의 메타데이터는 표시 전용이며, 모든 설치가 내용이 디스크나 프롬프트에 도달하기 전에 실패 시 차단(fail-closed) 스캔 게이트를 통과합니다. 스킬 설치 및 관리를 참고하십시오.

skills-lock.json: 설치된 스킬의 워크스페이스별 매니페스트입니다. 각 스킬마다 소스 저장소, 저장소 내 경로, 고정된 커밋, 롤업된 콘텐츠 해시를 담습니다. 설치, 업데이트, 제거가 이 파일을 최신으로 유지하며, verify_skills가 디스크와 대조합니다.

에이전트 실행 게이트웨이: 에이전트의 샌드박스 안에서 작업 정책을 적용하는 cc_server의 루프백 엔드포인트입니다. 에이전트가 하는 모든 GitHub 푸시는 이곳으로 보내져 리모트에 푸시 규칙으로 확인된 뒤, 에이전트가 결코 갖지 않는 쓰기 토큰으로 전달됩니다. Claude Code의 Bash 명령은 같은 엔드포인트의 훅을 통해 확인됩니다. 샌드박스와 보안을 참고하세요.

Mode: chat, plan, review, orchestrate 중 하나입니다. 스페이스별로 저장되므로 한 에이전트가 스페이스마다 다른 모드일 수 있고, 스페이스 안의 모든 대화가 이를 공유합니다. 시스템 프롬프트, 샌드박스 쓰기 규칙, MCP 도구 허용 목록을 게이팅합니다. 컴포저는 chat, plan, orchestrate만 제공하며 chat에는 “Agent” 레이블이 붙습니다.

SandboxBackend: microvm(커널 경계를 가진 유일한 백엔드인 격리 VM으로, 대화형 터미널에 적용됩니다), native(macOS의 Seatbelt, Linux와 WSL2의 bubblewrap) 또는 none입니다. 부팅 시 한 번 탐지합니다. native는 사용 가능할 때 에이전트 디스패치에 적용되어 Claude Code CLI와 하네스의 bash 도구를 감쌉니다. Windows에는 네이티브 백엔드가 없고 Linux에는 bwrap과 socat이 필요하므로 그곳의 실행은 감싸지지 않습니다. --sandbox off는 의도적으로 제외합니다.

리그: 에이전트가 실시간으로 조작하는 일회용 머신입니다. 격리된 브라우저나 Linux 데스크톱, 호스트가 관리하는 Android 에뮬레이터나 iOS 시뮬레이터, 또는 격리된 터미널입니다. 자체 전체 해상도 레인으로 라이브 관찰되며 테이크오버는 서버 측에서 강제됩니다. 대화 범위이므로 사람 탭과 에이전트의 browser_use / computer_use / mobile_use / ios_use 호출이 하나의 기본 머신을 대상으로 합니다. 리그와 인클로저를 참고하십시오.

인클로저: VM 기반 리그가 갖는 더 강력한 경계입니다. 커널 경계, 일회용 오버레이 디스크, 기본 거부 네트워크 게이트, 자격 증명 브로커입니다. Android와 iOS 리그는 일회용이지만 호스트가 관리하는 네트워킹을 사용하므로 이 경계를 주장하지 않습니다. 어떤 리그를 조작하든 enclosureControl 가드레일 클래스를 사용합니다.

RunCost: 단일 에이전트 실행의 토큰/비용 집계(입력 토큰, 출력 토큰, 센트 단위 예상 비용)입니다.

WakeReason: 에이전트가 디스패치된 이유입니다. 여섯 가지 값: 사용자 메시지, 티켓 할당, 실패 후 복구 재디스패치, 하위 티켓 완료, 예약된 팔로업 하트비트, 파이프라인 단계.

포트

SandboxPort: 샌드박스 수명주기(탐지, 실행, 이벤트, exec, 파기)를 관리합니다.

CredentialBrokerPort: 샌드박스 실행을 위한 범위 지정 자격 증명을 발급하고 — 에이전트 환경에는 읽기 전용, 쓰기는 서버 측 푸시 경로 전용 — 해제 시 폐기합니다.

GitRepoInspectorPort: 로컬 Git 저장소 경로에서 메타데이터(owner, repo, branch)를 추출합니다.

EmbeddingPort: 시맨틱 검색을 위한 단위 노름 텍스트 임베딩 벡터를 생성합니다.

NotificationPort: 카테고리/라우트 게이팅을 존중하여 네이티브 데스크톱 알림을 표시합니다.

TicketProviderPort: 티켓팅 백엔드로의 공급자 중립 경계(create, get, list, update, transition, assign)입니다.

PipelineEnginePort: 템플릿에서 파이프라인 실행을 시작하여 호출자를 구체 엔진과 분리합니다.

도메인 서비스

AgentDispatchService: 에이전트 실행을 시작합니다. 격리 저장소를 프로비저닝하고, 프롬프트를 만들고, 실행 로그를 생성하고, 라이브 이벤트 스트림을 반환합니다.

TicketWorkflowService: 낙관적 동시성 변경 초크포인트와 워크스페이스 격리 강제를 갖춘 순수 도메인 티켓 수명주기 엔진입니다. 여기서 강제하는 전이 그래프는 에이전트와 자동화만 구속하며, 사용자가 UI에서 하는 변경은 force: true를 전달해 이를 우회합니다. 에이전트 담당자를 위한 티켓 디스패처는 없습니다. AgentDispatchService가 디스패치를 소유하며, 티켓을 에이전트에 할당해도 실행은 시작되지 않습니다. 티켓을 팀에 할당하는 것이 예외입니다(TeamRoutingService가 리더를 디스패치합니다).

PipelineEngine: 실행 실행을 오케스트레이션합니다. 실행을 시작하고, 단계를 예약하고, 상태를 영속화하고, 라우터/조인/continue-on-fail을 처리하고, 재시작 후 진행 중인 실행을 재개합니다.

PipelineTriggerDispatcher: 도메인 이벤트를 구독하고 활성화된 트리거에 대해 일치하는 파이프라인 실행을 자동 시작합니다.

MemoryAccessPolicy: 도메인에 대한 에이전트 역할 메모리 권한을 해석하고 강제합니다.

HarnessCostCalculator: models.dev 카탈로그에서 내장 하네스의 토큰 사용량을 RunCost로 가격 산정합니다. 디스패치가 그 집계를 실행 로그에 영속화합니다.

BudgetEnforcementService: 에이전트별 월 지출과 디스패치 전 차단(checkInvocationBlock)을 계산합니다. 그 차단은 복구 리컨사일러(OrphanRunReaper, StrandedTicketReconciler)만 참조하며, 일반 사용자나 에이전트의 디스패치는 결코 참조하지 않습니다.

BudgetGovernanceService: 각 실행 후 에이전트별 월 지출을 평가합니다. 소프트 임계값은 경고 인시던트를 기록하고, 소진은 하드 인시던트를 기록하며 에이전트 수명주기를 paused로 전환합니다.

이벤트

DomainEventBus: 기능 간 통신을 위한 인프로세스 브로드캐스트 발행/구독 버스입니다. 이벤트는 타입이 있으며 구독자는 on<T>() 스트림을 소비합니다.

DomainEvent: 기본 인터페이스입니다. 모든 이벤트는 occurredAt을 갖습니다. 주요 범주: workspace/agent, PR/review, messaging, ticketing, pipeline, meetings/calendar, identity, rigs, observability.

회의와 캘린더

회의: 로컬에서 녹음하고 전사한 회의 세션입니다. 마이크와 시스템 오디오를 캡처하고, 선택 가능한 ASR 모델(기본값은 Parakeet TDT v3이며 Parakeet TDT v2, Whisper large-v3-turbo, Whisper base.en이 대안)로 기기 내에서 전사하고, 화자를 분리한 뒤 노트, 실행 항목, 결정 사항으로 요약합니다. 선택한 ASR 모델은 부팅 시 강제 설치되며 녹음 기능은 한 번 재시작한 뒤 활성화됩니다. 워크스페이스 범위이며 기기에 남습니다.

MeetingSegment: 화자 태그(me/them)와 화자 분리 레이블, 밀리초 오프셋을 갖춘 전사된 오디오 구간 하나입니다.

MeetingActionItem / MeetingDecision: 요약 파이프라인이 추출해 개별 행으로 저장하는 구조화된 출력입니다. 실행 항목은 티켓에 연결할 수 있습니다.

CalendarEvent: 워크스페이스와 연결된 계정 범위의 동기화된 Google Calendar 항목입니다. 회의와 다릅니다. 이벤트는 예정된 약속이고, 회의는 녹음된 세션입니다. MeetingCalendarLink로 일대일로 연결됩니다.

CalendarAccount: 워크스페이스와 이메일마다 하나씩 연결된 Google 계정입니다. OAuth 리프레시 토큰은 <dataDir>/secrets.json에 google_* 키로 서버 측에 저장되며 클라이언트에는 결코 도달하지 않습니다. 기기 코드 흐름은 서버에서 완료됩니다. authExpiredAt 플래그가 재연결 배너를 구동합니다.

아키텍처 용어

클린 아키텍처: 의존성 규칙: Presentation → Application/Providers → Domain ← Infrastructure. Domain에는 인프라 임포트가 전혀 없습니다.

포트와 어댑터: 도메인이 추상 인터페이스(포트)를 정의하고, 인프라가 구체 구현(어댑터)을 제공합니다. 컴포지션 루트가 이들을 바인딩합니다.

공유 커널: 3개 이상의 기능이 공유하는 core/domain/ 엔티티, 값 객체, 포트, 서비스입니다.

피처 우선: 코드를 기술 계층이 아니라 비즈니스 도메인(agents, pipelines, messaging)별로 구성합니다.

멀티플레이어, 신원, 속도

주체: 사람과 에이전트를 단일 행위자 추상으로 통합하는 봉인된 값입니다. UserPrincipal(userId) 또는 AgentPrincipal(agentId)입니다. 모든 메시지, 티켓, 리뷰, 플랜, 실행 로그는 주체를 통해 귀속됩니다.

사용자: 인간 신원으로, global.db에 저장되므로 워크스페이스를 넘어 전역입니다. 워크스페이스를 만든 주체가 그 소유자가 되어, 같은 연산에서 Workspace.ownerUserId에 소유자 역할 멤버십 행과 함께 기록됩니다. 나머지는 초대나 SSO로 합류합니다.

WorkspaceMember / WorkspaceRole: 사용자를 역할(owner / admin / member / viewer / guest)로 워크스페이스에 묶는 멤버십 행입니다. 페어링 키가 아니라 멤버십이 접근 경계입니다. 저장소별 권한 부여는 멤버십이 코드 호스트보다 큰 권한을 갖지 못하게 합니다.

ParticipantPresence: 주체를 위한 일시적 인식(상태, 위치, 커서, 입력 중, 에이전트의 라이브 상태와 실행 비용)입니다. 결코 영속화되지 않고, 서버 허브를 거치며, 팬아웃 전에 저장소 권한으로 필터링됩니다.

팔로우 모드: 아바타를 클릭하면 직접 행동할 때까지 그 뷰포트를 함께 따라가다가 떨어집니다. 사람과 에이전트 모두에게 동작합니다(“에이전트가 일하는 모습 보기”).

자율성 다이얼: 스페이스별·에이전트별 제어로, propose-only / act-with-approval / act-freely를 액션 가드레일 저장소 위의 이름 있는 프로필로 구현합니다.

ActionClass: 13개의 효과 클래스로 이루어진 닫힌 집합(fileDelete, gitPush, prCreate, networkEgress, processSpawn, enclosureControl, …)입니다. 모든 변경 도구가 자신의 클래스를 선언하며, 가드레일 엔진이 범위마다 allow / prompt / deny를 해석합니다(space > agent > workspace > mode preset > built-in default).

WriteLedger / 멱등성 키: 모든 변경은 클라이언트가 생성한 멱등성 키(UUIDv7, 논리적 작업마다)를 가집니다. 워크스페이스 범위 원장이 핸들러 실행 전에 중복을 제거하며, 재생은 바이트 단위로 동일한 원래 결과를 반환합니다. 재연결과 다중 클라이언트를 구조적으로 안전하게 만듭니다.

받은편지함: 엄격한 규칙을 가진 범주 횡단 큐입니다. 무언가(에이전트, 병합, 동기화)를 막고 있거나 운영자가 명시적으로 요청한 항목만 나타납니다.

Plan Studio: 대화형 계획 화면입니다. 단계별 비용, 시간, 위험과 부분 승인을 갖춘 편집 가능한 타입 지정 DAG 플랜입니다.

리뷰 컴퓨트: 서버 측 PR 리뷰 컴퓨트(그래프에서 도출한 코호트, 타입 지정 다이어그램, 시각적 diff, API 계약 diff, 다축 게이트)로, review_studio.*로 제공되고 리뷰 탭에 반영됩니다.

리뷰 스페이스: PR의 단일 배후 스페이스(모드 review, 종류 pr)로, 멱등하게 생성되고 ReviewSpaceAssociation으로 PR에 연결됩니다. 모든 리뷰어가 여기에 발견 사항을 제출하며, 그 덕분에 비교가 가능해집니다. 격리 워크트리에는 PR이 헤드 상태로 체크아웃되어 있습니다.

리뷰 노드: AI 리뷰 발견 사항의 구조화된 단위입니다. 종류(bug, suggestion, recommendation, question, ticket), 우선순위 P0–P3, 카테고리/심각도/노력 트리아지 3요소, 파일·줄 앵커, 선택적 수정 제안, 신뢰도 점수로 이루어집니다. add_review_node로 제출하며, 판정은 산문이 아니라 노드에서 계산됩니다.

Consensus-ready: 동료 리뷰어가 발견 사항을 확인해야만 도달하는 리뷰 노드 상태입니다. 에이전트는 자신의 발견 사항을 확인할 수 없습니다. 리뷰 탭의 GitHub에 게시 버튼은 남아 있는 열린 발견 사항을 모두 전송하며(selection: all_open), MCP 도구 publish_review_to_github는 여전히 동료가 확인한 발견 사항만 기본으로 삼습니다.

리뷰 수준: 어떤 리뷰어가 전개되는지(엔지니어만, +qa+architect, +security+perf)와 임계값 미만의 발견 사항이 어디에 표시되는지를 조절하는 워크스페이스 정책(light, balanced, thorough)입니다. 발견 사항을 결코 삭제하지 않습니다.

리뷰 축: 리뷰마다 점수를 매기는 다섯 레인 중 하나입니다. correctness, security, testGap은 리뷰어 발견 사항에서 나오고, visual과 apiContract는 결정적입니다. 게이트된 축은 판정에 반영되며 판정을 더 엄격하게만 만들 수 있습니다. partial 또는 unavailable 게이트는 판정을 통과시키지 않고 붙잡습니다.

리뷰 판정: ship, hold 또는 block입니다. 신뢰도 ≥ 0.7인 P0 발견 사항은 block이고, 그 밖의 P0나 모든 P1은 hold이며, 그 외에는 ship입니다. 게이트된 축이 실패하면 block이 강제되며 발견 사항으로 뒤집을 수 없습니다.

플릿과 평가

cc_worker: 헤드리스 순수 Dart 플릿 실행기 바이너리입니다. cc_server와 페어링하고, 호스트 기능을 선언하고, 임차된 작업을 가져와 실행하고, 프로세스 이벤트를 스트리밍해 돌려줍니다. 지속 상태를 보관하지 않습니다. 하나의 권위 서버, N개의 단순한 팔다리입니다.

JobSpec: 실행 가능한 모든 것(에이전트 실행, 파이프라인 단계, 코드 인덱스, 골든 렌더, 벤치마크, 평가 배치)에 대한 타입 지정 명세입니다.

평가 스위트: 워크스페이스 범위의 평가 정의(프롬프트, 대상 에이전트와 모드, 채점자)입니다. 워크스페이스를 만들 때 다섯 개의 스타터가 시드되며, 옵저버빌리티 → 품질에서 확인할 수 있습니다.

배포와 클라이언트

씬 클라이언트 아키텍처: 어떤 클라이언트도 데이터베이스를 열지 않습니다. 헤드리스 cc_server 프로세스가 데이터를 소유하고 WebSocket RPC로 제공합니다. 모든 클라이언트(데스크톱, 웹, 휴대폰)는 그 하나의 RPC 연결 위의 렌더러입니다.

cc_server: 헤드리스 서버 바이너리(순수 Dart, Flutter 엔진 없음)입니다. Drift/SQLite 데이터베이스를 소유하고, WebSocket으로 repo-RPC를 제공하며, 백그라운드 서비스(파이프라인, MCP, 리컨사일러)를 실행합니다.

ServerConnectionMode: 데스크톱이 서버에 도달하는 방식입니다. local(이 머신에서 cc_server를 실행하며 기본값) 또는 remote(다른 곳의 서버에 접속)입니다. 웹 클라이언트는 항상 remote입니다.

RemoteRpcClient: 모든 씬 클라이언트가 서버와 대화하는 데 쓰는 전송 독립적 JSON-RPC 클라이언트로, WSS, 루프백 또는 중계 릴레이를 통해 통신합니다.

호출별 워크스페이스 스코프: 서버는 무상태입니다. 세션별 워크스페이스 바인딩이 없으므로 한 서버의 여러 클라이언트가 “현재 워크스페이스”를 공유하지 않습니다. 워크스페이스 범위의 모든 repo/call과 sub/subscribe는 인자에 workspace_id를 담아야 하며, 없거나 등록되지 않은 id는 데이터베이스를 열기 전에 거부됩니다. 접근은 그다음 세션이 아니라 워크스페이스 멤버십과 역할로 게이팅됩니다.

cc_remote: 휴대폰 씬 클라이언트입니다. 기본 거부 도구 정책으로 중계 릴레이를 통해 플릿을 원격 제어하는 Flutter 웹 PWA입니다.

cc_signaling_server: 초대 게이트된 방을 호스팅하는 무상태 WebSocket 릴레이 브로커입니다. 종단 간 봉인된 프레임만 전달하고, 앱 데이터를 보관하지 않으며, 페어링 PSK를 결코 보지 못하는 단순 중계기입니다.

용어집