누구도 이력서만 보고 새 팀원을 믿지 않는다. 신뢰는 구조에서 나온다. 명확히 규정된 책임 범위, 팀이 지켜볼 수 있는 곳에서 이루어지는 작업, 그리고 무엇이든 배포되기 전에 거치는 검토. 이 중 하나라도 빠지면 아무리 뛰어난 동료라도 부담이 된다. AI 에이전트를 팀원으로 들일 때도 마찬가지다. 문제는 결코 “모델이 충분히 똑똑한가”가 아니다. “이것이 무엇을 건드릴 수 있는지 내가 알고 있는가, 그것이 한 일을 볼 수 있는가, 사람이 승인하지 않으면 아무것도 배포되지 않는가”이다.
Sharkly는 약속이 아니라 구성으로 이 질문에 답한다. Sharkly의 에이전트는 일회성 프롬프트가 아니라 저장된 작업 구성이다. 지침, 런타임, 스킬, 리포지터리, 환경, 실행 설정이 작업 처리 방식을 결정한다. 프롬프트는 터미널을 닫으면 사라진다. 구성은 검사할 수 있고, 공유할 수 있으며, 모든 실행에서 안정적으로 유지된다.
플랫폼 개요를 먼저 보고 싶다면 Sharkly란 무엇인가부터 읽고 돌아오자.
TL;DR
Sharkly의 에이전트는 AI 실행 주체를 위한 저장되고 재사용 가능한 작업 구성이다. 운영 지침, 컴퓨터와 런타임 바인딩, 연결된 스킬, Git 리포지터리, 환경 변수, 그리고 동시성, 타임아웃, 작업 디렉터리 모드 같은 실행 설정으로 이루어진다. 신뢰는 맹신이 아니라 구조를 통해 팀원을 믿는 방식과 같다. 에이전트의 권한 범위는 구성에 명시되어 있고, 실행 상태와 트레이스는 눈으로 확인할 수 있으며, 결과는 태스크로 돌아와 사람이 검토하고 수용한다. 에이전트는 조사하고, 실행하고, 테스트하고, 보고한다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 수용한다.
에이전트란 무엇이며, 무엇이 아닌가
에이전트는 Sharkly에서 작업을 처리하도록 구성된 AI 실행 주체다. 할당된 태스크를 받고, 댓글을 작성하고, 사용 가능한 워크플로를 통해 태스크 상태를 업데이트하고, 실행 트레이스를 생성할 수 있다. 구성이 저장되기 때문에 팀은 코드 변경, 리뷰, 테스트, 문서화, 운영 트리아지를 위한 별도의 에이전트를 유지할 수 있으며, 태스크마다 같은 지침을 다시 작성할 필요가 없다.
먼저 짚어둘 두 가지 경계가 있다.
에이전트는 실행 호스트가 아니다. 에이전트의 작업은 연결된 컴퓨터에서 선택된 런타임을 통해 실행된다. 에이전트는 작업을 어떻게 처리해야 하는지 정의하고, 컴퓨터는 호스트를 제공하며, 런타임은 실제 세션을 수행하고, 태스크는 공유 기록으로 남는다. 각 역할은 하나의 임무만 맡기 때문에 컴퓨터 하나로 여러 에이전트를 지원할 수 있다.
에이전트는 스스로 모델을 선택하지 않는다. 런타임의 기본 모델을 따르며, 에이전트에는 모델 선택기나 사고 깊이 제어 기능이 없다. 다른 모델을 쓰려면 런타임이나 컴퓨터 도구 구성에서 변경하면 된다. 예를 들어 Claude Code나 Codex 자체에서 설정한다.
신뢰는 모델이 아니라 시스템의 속성이다
이 글의 핵심 논지는 이것이다. 에이전트는 작업의 범위가 정해져 있고, 가시적이며, 검토 가능할 때 신뢰할 수 있다. 모델이 인상적일 때가 아니다.
범위가 정해져 있다는 것은 에이전트의 권한이 실행 전에 문서로 명시된다는 뜻이다. 어떤 리포지터리를 건드릴 수 있는지, 어느 컴퓨터에서 실행되는지, 지침이 무엇을 허용하는지, 동시에 몇 개의 태스크를 실행할 수 있는지, 실행이 얼마나 지속될 수 있는지가 정해진다. 가시적이라는 것은 실행 상태, 트레이스 이벤트, 결과가 개인 터미널 속으로 사라지지 않고 누구나 확인할 수 있는 태스크로 돌아온다는 뜻이다. 검토 가능하다는 것은 루프의 끝에 사람이 앉아 있다는 뜻이다. 에이전트는 태스크를 사람의 답변 대기나 사람의 리뷰 대기 상태로 남길 수 있고, 그 신호는 담당자의 받은편지함에 도착한다.
이것이 실제로 작동하는 인간-에이전트 계약이다. 자동화는 팀의 판단이 필요한 지점에서 멈춘다. 워크플로 자체를 아직 고민 중이라면, 에이전트 코딩 입문 글에서 프롬프트 작성에서 작업 할당으로의 전환을 다룬다.
에이전트 구성 항목
에이전트에는 이름, 설명, 아바타, 소유자, 운영 지침, 공개 범위와 스페이스 배치, 컴퓨터 연결과 런타임 제공자, 할당된 스킬, 에이전트 전용 Git 리포지터리, 일반 및 비밀 환경 변수, 추가 런타임 인자, 태스크 작업 디렉터리 설정, 그리고 병렬 실행 태스크 최대 개수와 태스크별 타임아웃이 포함될 수 있다. 각 항목은 신뢰를 조절하는 레버다.
지침은 모든 실행에 포함된다. 모든 태스크에서 유지되어야 하는 동작, 즉 범위와 역할, 행동 전에 태스크를 검토하는 방법, 언제 사람의 입력을 요청할지, 예상되는 검사, 보고 형식 등을 여기에 담는다. 문서에서는 유용한 삼분법을 제시한다. 태스크별 요구사항은 태스크 설명이나 댓글에, 여러 에이전트가 공유할 수 있는 재사용 가능한 절차는 스킬에, 에이전트 자체의 지침에는 변하지 않는 정체성을 담는다. “편집하기 전에 태스크 설명과 최근 댓글을 읽는다. 변경은 요청된 동작으로 제한한다. 가장 관련성 높은 검사를 실행하고 실패를 숨기지 않고 보고한다”는 에이전트에 속한다. 월요일에도 참이어야 하고 3월에도 여전히 참이어야 하기 때문이다. 설명은 다른 독자를 위한 것이다. 설명은 사람에게 무엇을 할당할지 알려주고, 지침은 에이전트에게 어떻게 일할지 알려준다.
공개 범위는 Personal(현재 소유자만 사용 가능) 또는 Space(에이전트의 스페이스에 접근할 수 있는 사람이 사용 가능)다. 또한 누가 에이전트를 할당하고, 에이전트 채팅을 시작하고, 댓글이나 멘션으로 트리거할 수 있는지도 제어한다. 튜닝하는 동안에는 Personal로 시작하고, 구성을 공유할 가치가 생기면 Space로 옮긴다. 이 승격의 순간이 한 개발자의 작업 방식을 팀 인프라로 만드는 시점이다.
컴퓨터와 런타임은 결합되어 실행 대상을 이룬다. 컴퓨터가 온라인이라는 것은 로컬 서비스가 하트비트를 보내고 있다는 뜻일 뿐이며, 선택된 런타임이 태스크를 실행할 수 있다는 뜻은 아니다. 컴퓨터가 오프라인이면 새 실행은 보통 다시 연결될 때까지 기다린다. 선택된 런타임이 사라졌다면 다른 적합한 런타임을 선택한다. 전체 설정 방법은 Sharkly의 컴퓨터에서 다룬다.
스킬은 재사용 가능한 지침과 지원 파일을 묶은 것이다. 리뷰 규칙, 배포 체크리스트, 팀 프로세스 등이 여기에 해당한다. 로컬 런타임 스킬은 해당 컴퓨터에서 자동으로 사용할 수 있지만, 공유 스페이스 스킬은 명시적으로 할당해야 한다. 반복해서 강조할 만한 주의점이 있다. 서로 겹치는 스킬을 많이 연결하지 말아야 한다. 지침이 충돌하면 실행 예측 가능성이 떨어지기 때문이다. 자세한 내용은 Sharkly의 스킬을 참고하자.
리포지터리는 가장 깔끔한 범위 제한 레버다. 스페이스 기본값보다 좁은 코드 범위가 필요할 때 에이전트에 리포지터리를 연결한다. 바인딩이 없으면 Sharkly는 태스크의 스페이스에 구성된 리포지터리를 기본으로 사용한다. 문서 리포지터리에 연결된 문서 에이전트는 결제 서비스에 접근할 길이 없다.
환경과 실행 설정은 실행이 사용할 수 있는 범위를 제한한다. 일반 및 비밀 환경 변수와 추가 런타임 인자를 통해 누구도 태스크에 자격 증명을 붙여넣지 않고도 실행에 구성을 전달할 수 있다. 리포지터리 토큰, 개인 키, 설치 토큰을 태스크 설명, 댓글, 에이전트 지침, 스킬에 절대 넣지 말아야 한다. 태스크 실행 설정은 병렬 태스크, 최대 실행 시간, 작업 디렉터리 모드를 제어한다.
| 임시 모드 | 지정 모드 | |
|---|---|---|
| 실행에 주어지는 것 | 태스크마다 격리된 디렉터리. 리포지터리 기반 실행은 새 워크트리를 준비할 수 있다 | 에이전트의 디렉터리 풀에서 구성된 절대 로컬 디렉터리 하나 |
| 동시성 | 더 안전한 병렬 실행. 기본값은 컴퓨터 한도의 50% | 한 번에 디렉터리당 하나의 실행. 기본값은 디렉터리 개수와 동일 |
| 가용성 | 연결된 모든 컴퓨터 | 로컬 컴퓨터만 |
| 적합한 경우 | 대부분의 리포지터리 작업, 그리고 여러 태스크가 동일한 코드베이스를 병렬로 수정할 수 있는 경우 | 매우 큰 리포지터리, 비용이 큰 로컬 캐시, 또는 로컬 서비스에 묶인 태스크 |
동시성 값을 디렉터리 개수보다 높게 수동 설정하면 쓰기 충돌이 발생할 수 있다는 경고가 표시된다. 격리 메커니즘은 Sharkly가 병합 충돌 없이 에이전트를 병렬 실행하는 방법에서 자세히 다룬다.
대화와 태스크: 두 개의 표면, 하나의 규칙
에이전트 채팅은 추적되는 태스크가 필요하기 전에 질문하거나, 주제를 조사하거나, 계획을 구체화하기 위한 독립형 대화다. 채팅은 세 가지 모드를 지원한다. 읽기 전용 조사를 위한 Explore, Sharkly가 계획된 태스크와 하위 태스크를 생성하기 전에 검토하고 확인하는 제안을 위한 Plan, 에이전트에 구성된 CLI를 통해 직접 실행하는 Execute다. 각 세션은 이를 만든 사람에게 속한다.
태스크는 작업에 소유자, 상태, 실행 이력, 검토가 필요할 때 향하는 곳이다. 판단 기준은 이렇다. 작업에 추적되는 태스크가 필요하기 전에는 채팅으로 조사하고, 계획하고, 실행한다. 작업에 담당자, 상태, 수용 기준, 영구 기록이 필요하면 태스크를 사용한다.
맥락을 잃지 않게 해주는 경계가 하나 있다. 에이전트 채팅에서 메시지를 보내도 태스크 댓글이 생성되지 않으며, 태스크의 에이전트 채팅에 있는 메시지는 활동에 댓글로 나타나지 않는다. 팀이 결론을 봐야 한다면 태스크 설명이나 댓글로 복사해야 한다. 신뢰는 공유 기록에 달려 있고, 공유 기록은 바로 태스크다.
상태 값이 알려주는 것
여기서 가시성이란 읽을 수 있는 구체적인 상태 집합을 뜻하며, 대시보드 구호가 아니다.
태스크 실행은 queued, dispatched, waiting for local directory, running, completed, failed, canceled 단계를 거친다. 실행 상태는 태스크의 워크플로 상태와 별개다. 실행이 실패해도 태스크는 다시 시도할 수 있도록 열려 있을 수 있다. 실행 로그에는 실행이 큐에 들어간 이유, 시작 및 종료 시각, 도구 호출과 런타임 이벤트, 트리거 출처, 실패 세부 정보가 기록된다.
에이전트 가용성은 세 번째로 별개의 신호다. 온라인 상태의 에이전트도 동시성이나 디렉터리 용량이 꽉 차서 대기 중인 작업이 있을 수 있다. 백로그는 대기 구역 역할을 한다. 에이전트에 할당된 태스크는 백로그에 있는 동안 기다리고, 작업 준비가 된 상태로 옮겨야 실행이 시작된다. 에이전트를 할당한다고 해서 작업이 갑자기 시작되는 일은 없다.
첫 번째 에이전트: 믿고 따라 하는 워크스루
신뢰를 쌓는 가장 빠른 방법은 Sharkly 문서에 나오는 가장 작은 유용한 루프다. 컴퓨터 하나를 연결하고, 에이전트 하나를 만들고, 위험이 낮은 태스크 하나를 할당한다.
- 컴퓨터를 연결한다. 설정에서 컴퓨터를 열고 컴퓨터 연결을 선택한다. 최소 하나의 사용 가능한 런타임과 함께 연결됨으로 표시될 때까지 기다린다.
- 좁은 역할로 에이전트를 만든다. 이름: Code Reader. 설명: 리포지터리를 읽고 현재 구현을 설명하며, 파일을 변경하지 않고 위험을 보고한다. 공개 범위: Personal.
- 범위를 강제하는 지침을 작성한다. “행동하기 전에 전체 태스크와 관련 댓글을 읽는다. 범위를 요청 사항으로 제한한다. 첫 번째 태스크에서는 파일을 편집하지 않는다. 무엇을 검토했는지, 각 결론의 근거, 불확실하게 남은 사항을 보고한다.”
- 코드를 연결한다. Git 리포지터리를 첨부하거나 이미 이를 포함하고 있는 지정 로컬 디렉터리를 구성한다. 스킬은 나중에 해도 된다.
- 작고 텍스트만 있는 태스크를 만든다. 인증 오류 경로를 검토하고, 사용자에게 보이는 실패 사례 세 가지를 식별하고, 각각 관련 파일을 인용하고, 아무것도 변경하지 않는다.
- 백로그가 아니라 작업 준비가 된 상태를 사용해 할당하고 시작한다. 실행 상태가 queued에서 running으로 넘어가는 것을 지켜본 뒤 태스크에서 결과를 읽는다.
- 진심으로 검토한다. 에이전트가 의도한 코드를 검토했는지, 편집 금지 경계를 지켰는지, 근거를 제시했는지, 추측하는 대신 불확실성을 기록했는지 확인한다.
마지막 단계가 핵심이다. 읽기 전용 첫 태스크를 통해 에이전트는 권한을 갖기 전에 신뢰를 쌓는다. 루프가 작동하면 의도적으로 범위를 넓힌다. 전체 할당 방식은 AI 코딩 에이전트에 첫 태스크를 할당하는 방법에서 다룬다.
그리고 에이전트가 더 이상 신뢰를 얻지 못하면 권한 회수는 깔끔하다. 보관하면 할당과 멘션에서 제외되고 실행 중인 작업이 취소되지만, 이전 태스크와 댓글, 실행 이력은 그대로 남는다. 작업 기록을 잃지 않고 내보낼 수 있는 팀원이라야 기꺼이 들일 수 있는 팀원이다.
FAQ
Sharkly에서 에이전트는 정확히 무엇인가?
에이전트는 Sharkly에서 작업을 처리하도록 구성된 AI 실행 주체다. 지침, 컴퓨터와 런타임 바인딩, 스킬, 리포지터리, 환경 변수, 실행 설정으로 이루어진 저장된 구성이다. 할당된 태스크를 받고, 댓글을 작성하고, 태스크 상태를 업데이트하고, 실행 트레이스를 생성할 수 있다. 구성이 저장되므로 에이전트를 스페이스에 공유하면 한 사람의 작업 방식이 재사용 가능해진다.
Sharkly 에이전트는 어떤 모델을 사용하는가?
에이전트는 Claude Code나 Codex처럼 선택된 런타임의 기본 모델을 따르며, 특정 모델 이름을 표시하거나 보장하지 않는다. 에이전트에는 모델 선택기나 사고 깊이 제어 기능이 없다. 모델을 바꾸려면 런타임이나 컴퓨터 도구 구성을 업데이트한다.
에이전트와 대화하는 것과 태스크를 할당하는 것의 차이는 무엇인가?
에이전트 채팅은 작업에 추적 기록이 필요하기 전에 탐색하고, 계획하고, 실행하기 위한 독립형 대화다. 태스크는 담당자, 상태, 실행 이력, 검토를 갖춘 공유 작업 단위다. 채팅 메시지는 태스크 댓글이 되지 않으므로, 팀이 볼 결론은 태스크에 남겨야 한다.
에이전트가 할 수 있는 일을 어떻게 제한하는가?
범위는 구성에서 설정한다. 지침은 역할과 주의 규칙을 정의하고, 리포지터리 바인딩은 에이전트가 볼 수 있는 코드를 제한하며, 태스크 실행 설정은 병렬 태스크와 실행 시간을 제한한다. 임시 작업 디렉터리 모드는 각 태스크에 자체 디렉터리를 부여해 격리를 강화한다. 최종 수용은 여전히 사람의 몫이다.
할당한 태스크가 시작되지 않는 이유는 무엇인가?
세 가지를 확인한다. 백로그에 있는 태스크는 설계상 대기하므로 작업 준비가 된 상태로 옮긴다. 컴퓨터가 온라인이라는 것은 하트비트가 도착하고 있다는 뜻일 뿐이므로, 선택된 런타임이 사용 가능으로 표시되는지 확인한다. 그리고 온라인 에이전트도 동시성이나 지정 디렉터리가 꽉 차면 작업을 대기열에 넣을 수 있다.
