에이전트 모델

에이전트란 무엇인가?

에이전트는 페르소나, 스킬 집합, 실행할 어댑터를 가진 이름 있는 주체입니다. 에이전트는 사람과 같은 의미의 주체입니다. 메시지를 작성하고, 티켓을 소유하고, 리뷰를 남기고, 같은 로스터에 나타납니다. 실제로 일을 하는 것이 바로 에이전트입니다.

각 에이전트는 정확히 하나의 워크스페이스에 속합니다. 이는 강력한 불변식입니다. agent.workspaceId는 null일 수 없고, 에이전트의 행이 기록될 데이터베이스 파일은 그 에이전트의 워크스페이스가 결정하며, 워크스페이스가 없는 에이전트를 만드는 것은 거부됩니다.

에이전트는 디렉터리이기도 합니다. 에이전트의 정의는 워크스페이스 데이터 디렉터리 아래 agents/<slug>/AGENTS.md에 있으며, 보유한 스킬은 agents/<slug>/.agents/skills로 심볼릭 링크됩니다. 데이터베이스 행과 파일은 함께 기록됩니다. 시딩은 멱등입니다. 에이전트 행이 이미 존재하더라도 디스크상의 파일과 스킬 링크는 다시 기록됩니다. 프로덕션에서 이 호출을 하는 곳은 서버를 시작할 때마다가 아니라 워크스페이스를 생성할 때입니다.

에이전트가 지니는 것

속성	하는 일
`name`	짧은 슬러그 형태의 식별자(`architect`, `qa`). `@mentions`가 해석되는 대상이기도 합니다
`title`	사람이 읽을 수 있는 직함
`persona`	자유 형식의 성격 및 행동 지침이며, 프롬프트 섹션으로 주입됩니다
`systemPrompt`	선택적 추가 지침이며, “Agent instructions” 섹션으로 주입됩니다. 조립된 프롬프트의 나머지 부분을 대체하지는 않습니다
`skills`	대소문자를 구분하지 않는 스킬 이름 집합이며, 디스크의 스킬 링크로 반영됩니다
`adapterId`	에이전트가 디스패치되는 러너. null이면 내장 루프로 폴백합니다
`modelId`	해당 어댑터 내에서 사용할 모델
`effort`	선택한 모델 자체의 어휘에서 가져온 추론 수준
`contextSize`	컨텍스트 창 재정의
`silenceTimeoutMinutes`	무응답 감시(silence watchdog)에 대한 에이전트별 재정의 (1–240)
`reportsTo`	상위 에이전트 id. 조직도가 그리는 보고 체인입니다

이 모든 항목은 설정 → 워크스페이스 → 에이전트에서 편집합니다. 새 에이전트는 이름 없는 에이전트를 만들며, 이후에 내용을 채우면 됩니다.

스킬

스킬은 에이전트 엔터티에 있는 대소문자 비구분 이름입니다. 스킬과 관련해서는 두 가지 별개의 일이 일어납니다:

이 이름들은 조립된 프롬프트에 “Skills” 제목으로 나열됩니다. 엔터티의 집합 자체가 하는 일은 이것뿐입니다. 이를 키로 삼는 스킬별 프롬프트 라이브러리는 없습니다.
이름이 지정된 각 스킬의 디렉터리(워크스페이스의 skills/<slug>/SKILL.md)는 에이전트 자체 폴더로 링크됩니다. 내장 하네스에서는 링크된 스킬의 프런트매터가 시스템 프롬프트에 자동으로 로드되고, 에이전트는 필요할 때 본문을 읽습니다. 대화에서 /skill:<name>을 입력하면 해당 본문이 그 턴의 지시로 로드됩니다.

외부에서 가져온 스킬은 가져오기와 쓰기 사이에 닫힌 상태로 실패하는(fail-closed) 공급망 스캔을 통과합니다. 판정 없이는 어떤 스킬 콘텐츠도 디스크나 프롬프트에 도달하지 않습니다. ’외부’란 직접 스킬 소스로 등록한 GitHub 리포지토리입니다. 큐레이션된 스토어가 없으므로 리포지토리 자체의 메타데이터(설명, 스타 수, 스킬 이름)는 신뢰할 수 없는 표시 데이터이며, 스캔 판정만이 유일한 안전 신호입니다. 설치는 스킬의 디렉터리 전체를 가져와 skills-lock.json에 가져온 커밋으로 고정하고, 이후 업데이트는 무엇이든 교체하기 전에 같은 게이트를 다시 통과합니다. 사용법은 스킬 설치 및 관리에 있습니다.

저장소 범위 스킬

저장소는 관례적인 위치(.agents/skills/, .claude/skills/, .opencode/skills/) 중 어디에든 자체 스킬을 포함할 수 있습니다. 스페이스는 연결된 모든 저장소를 repos/<name>/ 아래에 나란히 체크아웃하지만, 에이전트는 한 번에 하나의 저장소에서만 작업합니다. 따라서 해당 저장소의 스킬만 지니며, 저장소가 바뀌면 스킬 집합도 바뀝니다.

어느 저장소가 활성인지는 에이전트가 건드린 파일에서 추론합니다. repos/<name>/ 아래에 파일을 쓰면 그 저장소가 활성 저장소가 되지만, 저장소를 가로질러 읽기만 하는 것은 그렇지 않으므로, 심볼을 따라 형제 서비스로 들어가도 작업 도중에 스킬 집합이 바뀌는 일은 없습니다. 단일 저장소 스페이스에서는 첫 턴 전에 답이 정해져 있습니다.

이 범위 지정은 컨텍스트 예산에 관한 결정입니다. 스킬 인덱스는 매 턴 프롬프트에 들어가지만 본문은 그렇지 않으므로, 모든 저장소의 스킬을 한꺼번에 나열하면 토큰이 계속 소모됩니다. 또한 한 서비스의 testing 스킬은 작업이 다른 곳에 있을 때 오히려 잘못된 방향으로 이끕니다. 에이전트의 인덱스는 저장소 하나만 담지만 컴포저는 그렇게 범위가 정해지지 않는 이유도 같습니다. 스킬 이름을 직접 지정하는 것은 명시적인 행동 하나이므로, /skill:<repo>:<name>은 스페이스의 어느 저장소에든 닿습니다.

저장소 스킬은 내장 하네스뿐 아니라 모든 어댑터에 로드됩니다. 활성 저장소의 스킬은 에이전트의 작업 디렉터리에 구체화되는데, 이는 Claude Code가 이미 스캔하는 경로입니다. 같은 인덱스가 내장 하네스가 읽는 AGENTS.md에 조합됩니다. 저장소의 스킬은 그 전에 설치된 스킬과 동일한 닫힌 상태로 실패하는 스캔을 통과합니다. 체크아웃된 저장소는 복제된 콘텐츠이며, 그 프런트매터는 프롬프트에 도달합니다.

권한

에이전트는 자체 권한 플래그를 갖지 않습니다. 커밋 생성, 푸시, 풀 리퀘스트 열기, 트래커에 쓰기, 네트워크 접근이 가능한지는 작업 가드레일이 결정합니다. 워크스페이스, 에이전트, 스페이스 범위에서 허용, 먼저 묻기, 거부 중 하나이며, 어떤 어댑터가 실행하든 같은 규칙이 적용됩니다.

실행이 넘겨받는 것은 이 규칙에 따라 달라지지 않습니다. GitHub 워크트리에서의 실행은 항상 읽기 전용 GitHub 토큰을 받고, 푸시는 일어나는 시점에 확인됩니다. 에이전트의 git 구성은 모든 GitHub 푸시를 Control Center를 거쳐 보내며, Control Center는 전달하기 전에 리모트에 푸시 규칙을 적용합니다.

이것이 어떻게 동작하는지, 그리고 파일 시스템 수준에서 무엇이 강제되고 강제되지 않는지는 샌드박스와 보안을 참고하세요.

어댑터가 무엇을 강제할 수 있는지 결정합니다

에이전트에서 가장 영향이 큰 단일 필드는 어댑터입니다. 어댑터의 전송 방식이 Control Center 정책 중 얼마나 실제로 강제될 수 있는지를 결정하기 때문입니다.

전송 방식	어댑터	Control Center가 강제하는 것
내장 하네스	Control Center (built-in)	모든 것. 도구 표면이 모드로부터 _구성_되므로, 허용되지 않은 도구는 단순히 거부되는 것이 아니라 보이지 않습니다. 모든 호출이 승인 게이트와 액션 가드레일을 통과합니다. 완료 계약은 결과물 없이 끝나는 실행을 재촉한 뒤 실패시킬 수 있습니다
Claude CLI	Claude Code	제공받는 `mcp__*` 도구와, 훅이 실행 전에 작업 정책으로 보내는 `Bash` 명령. Claude 자체의 읽기, 쓰기, 편집 도구는 자체 프로세스 안에서 실행되며 보이지 않습니다. 또한 비대화형 `claude -p`가 자체 프롬프트에서 영원히 멈추게 되므로 `--dangerously-skip-permissions`와 함께 실행됩니다

구체적으로 내장 하네스만 서브에이전트, 실행 중 조종(mid-run steering), 일시 중지와 재개(따라서 넘겨받기), 구조적 모드 강제를 지원합니다. Claude Code는 이 중 어느 것도 제공받지 못합니다.

위의 표는 Control Center가 보고 게이트할 수 있는 것에 관한 것입니다. 그 아래에서 cc_server는 존재하는 경우 Claude Code CLI를 호스트의 OS 샌드박스로 감쌉니다. macOS에서는 Seatbelt, Linux와 WSL2에서는 bubblewrap입니다. 따라서 보이지 않는 rm이나 보이지 않는 쓰기도 여전히 OS에 의해 제한됩니다. Windows에는 백엔드가 아예 없고, bwrap과 socat이 없는 Linux 또는 WSL2에서는 프로브가 none을 보고합니다. 따라서 그런 환경에서 이 실행들은 환경 정리(sanitization), 중개된 자격 증명, Control Center가 볼 수 있는 호출에 대한 가드레일, 대화 자체의 워크트리로 폴백합니다(rift가 제공되는 곳에서는 기록 중 복사, Windows에서는 git worktree).

샌드박스가 아닌 것은 _게이트_입니다. 샌드박스는 프로세스가 읽고, 쓰고, 연결할 수 있는 범위를 제한합니다. 읽기 전용 모드는 읽기 전용 바인드 마운트로서 샌드박스에 도달하지만, 샌드박스는 호출을 가로채거나 승인을 요구하거나 나중에 CLI가 무엇을 시도했는지 알려줄 수는 없습니다. 이것과 바로 위에서 언급한 네 가지 기능이 여전히 내장 하네스에는 있고 다른 어댑터에는 없는 것입니다. 샌드박스와 보안을 참고하세요.

어댑터가 없는 에이전트는 **Control Center (built-in)**으로 폴백합니다. 서버 내부의 루프이므로 설치할 CLI가 없으며, 실행 로그에 cc-harness가 기록됩니다. 시딩된 모든 에이전트는 어댑터나 모델 없이 생성되므로, 새 워크스페이스의 다섯 에이전트는 에이전트별로 어댑터와 모델을 설정할 때까지 Anthropic의 기본 모델로 그곳에서 실행됩니다. 온보딩의 “default adapter” 선택은 서버가 결코 읽지 않는 클라이언트 측 기본 설정이며, 이미 생성된 에이전트에 소급 적용되지 않습니다.

에이전트는 어디에서 오는가

워크스페이스와 함께 시딩됩니다. 첫 번째 워크스페이스뿐 아니라 모든 워크스페이스에 CEO 한 명과 그에게 보고하는 네 명의 전문 에이전트(qa, architect, engineer, librarian)가 주어지며, 워크스페이스를 만들 때 백그라운드에서 멱등하게 생성됩니다. 워크스페이스와 격리를 참고하세요.
수동으로 추가합니다: 설정 → 워크스페이스 → 에이전트. 에이전트에게 동료를 채용하라고 요청해도 행이 생성되지 않습니다. 그 화면을 사용하세요.

실시간 상태

에이전트에는 저장된 상태 열이 없습니다. 실시간 상태는 읽을 때마다 가장 최근 실행 로그에서 도출됩니다:

상태	의미
`neverRun`	실행 로그가 없습니다
`running`	현재 진행 중인 실행이 하나 이상 있습니다
`failed`	최신 실행이 오류가 났거나, 그 생존 상태(liveness)가 failed 또는 dead입니다
`blocked`	최신 실행의 생존 상태가 blocked, stalled 또는 looping입니다
`idle`	나머지 전부. 에이전트가 이전에 실행된 적이 있고 진행 중인 것이 없습니다

두 가지 추가 상태인 queued와 succeeded는 대화 실행 트리에서 개별 실행에 대해 존재합니다. 로스터는 이들을 만들어 내지 않습니다. 끝난 실행이 초록색이라는 것은 에이전트가 아니라 실행에 관한 사실이기 때문입니다.

프레즌스 로스터는 라이브 실행 이벤트로부터 서버 측에서 합성된, 더 거친 병렬 그림을 보여줍니다. 즉 생각 중, 실행 중, 승인 대기로 차단됨, 완료이며, 이것이 에이전트가 사람 옆에 나타나게 하는 것입니다. 멀티플레이어를 참고하세요.