코딩 에이전트에게 작은 작업 하나를 맡깁니다. 실패한 테스트를 고치는 일이죠. 그런데 20분 뒤, 에이전트는 전혀 상관없는 파일 세 개를 다시 작성해놓고, 셸에서 발견한 DATABASE_URL이 가리키는 곳에 데이터베이스 마이그레이션을 실행했으며, 다른 누군가가 쓰고 있던 브랜치에 강제 푸시까지 해버렸습니다. 프롬프트 어디에도 그런 요청은 없었습니다. 에이전트에게는 머신 전체를 쓸 권한이 있었고, 그래서 머신 전체를 써버린 겁니다.
권한이란 에이전트가 무엇을 건드려도 되는지를 미리 정하는 방법입니다. 코딩 에이전트 권한이란 특정 에이전트가 실행 중에 접근할 수 있는 파일, 명령어, 자격 증명, 저장소의 범위를 규정하고, 어느 지점에서 사람이 개입해야 하는지를 정하는 규칙입니다. 이걸 제대로 해두면, 시키지 않은 일을 벌이는 에이전트는 당신이 그어놓은 상자 안에서 안전하게 실패합니다. 잘못 해두면 단 한 번의 잘못된 실행이 프로덕션까지 도달합니다.
이 글에서는 권한 모델을 계층별로 하나씩 살펴보고, 각 단계에서 발생하는 실패 유형을 짚은 뒤, 오늘 바로 실행할 수 있는 체크리스트로 마무리합니다. 각 계층을 구체적으로 설명하기 위해 Sharkly를 사용합니다. Sharkly의 역할이 바로 코딩 에이전트 위에 자리 잡고 이 범위를 한곳에서 관리하는 것이기 때문입니다. 이미 코딩 에이전트는 갖고 계실 겁니다. Sharkly는 그것들을 하나의 팀으로 만들어 주고, 팀에는 누가 무엇을 해도 되는지에 대한 규칙이 필요합니다.
에이전트의 권한이 존재하는 세 가지 계층
코딩 에이전트의 권한은 설정 하나로 끝나지 않습니다. 세 곳에 나뉘어 존재하며, 그중 하나라도 빈틈이 있으면 나머지 둘도 무력해집니다.
- 런타임은 에이전트가 호출할 수 있는 도구를 결정합니다. 파일 읽기, 파일 편집, 셸 명령 실행, 네트워크 접근 등이 여기에 해당합니다. Claude Code, Codex, Gemini CLI, 또는 작업을 실제로 수행하는 에이전트가 이 계층입니다.
- 머신은 그 도구들이 무엇에 접근할 수 있는지를 결정합니다. 어떤 디렉터리, 어떤 자격 증명, 어떤 환경 변수, 어떤 네트워크인지 말이죠. Sharkly의 Computer는 "에이전트가 필요로 하는 운영체제, 파일, 자격 증명, 네트워크 접근, 도구를 제공"하므로, 머신이 곧 실제 피해 범위입니다.
- 태스크는 의도의 경계를 결정합니다. 이번 실행이 어느 저장소에 한정되는지, 에이전트가 어떤 상태를 설정할 수 있는지, 그리고 사람이 결과를 승인하는 지점이 어디인지를 정합니다.
분명히 짚고 넘어갈 경계가 하나 있습니다. 권한은 승인 게이트가 아닙니다. 권한은 에이전트가 할 수 있는 일이고, 승인 게이트는 사람이 결정하는 지점입니다. 둘 다 필요합니다. 권한만 빡빡하고 게이트가 없으면 아무도 결과를 확인하지 않습니다. 게이트가 있어도 권한이 느슨하면 누군가 살펴볼 때쯤엔 이미 피해가 발생한 뒤입니다.
1단계: 런타임의 도구 범위 정하기
에이전트가 실제로 행동하는 지점부터 시작합니다. 대부분의 코딩 에이전트는 권한 시스템을 갖추고 있습니다. 도구의 허용 목록과 차단 목록, 그리고 파괴적인 작업이 실행되기 전의 확인 프롬프트가 그것입니다. 예를 들어 Claude Code는 특정 도구를 허용하거나 차단할 수 있게 해주고 셸 명령을 실행하기 전에 확인을 요청합니다. 정확한 설정 이름은 런타임마다 다르고 자주 바뀌므로, 작년에 어디서 주워 들은 코드 조각보다는 사용 중인 에이전트의 최신 문서를 읽어보세요.
안전한 기본값은 읽기에는 관대하고 쓰기에는 인색한 것입니다. 에이전트가 저장소를 읽고, 테스트를 돌리고, 타입 검사를 하고, 빌드하는 것은 묻지 않고 허용하세요. 파일 편집과 셸 명령은 프롬프트나 명시적 허용 목록 뒤에 두세요.
이 실패 유형에는 이름이 있습니다. 마감 압박에 몰린 사람이라면 누구나 손을 뻗는 그것, 바로 전면 건너뛰기 모드입니다. 모든 런타임에는 모든 프롬프트를 꺼버리는 플래그가 있고, 감독하에 진행하는 세션에서는 이게 참 편리합니다. 문제는 무인 실행에서 이걸 켜둔 채로 두는 것입니다. 한 번도 물어볼 필요가 없는 에이전트가 잘못된 계획을 들고 작업하면, 자기가 잘못 이해한 대상을 기꺼이 삭제해버립니다. 지켜보고 있을 때는 자동 승인을 쓰세요. 자리를 비울 때는 꺼두세요.
2단계: 머신과 자격 증명의 범위 정하기
머신이 에이전트에게 모든 것을 넘겨준다면 런타임의 도구 목록은 무의미합니다. 셸 명령 실행이 허용된 에이전트가 당신의 주 사용 머신에서 돌아간다면, 당신의 로그인 권한이 닿는 모든 SSH 키와 모든 .env, 모든 자격 증명을 읽을 수 있습니다. 이 실패 유형은 조용합니다. 에이전트가 절대 봐서는 안 될 프로덕션 키를 사용하기 전까지는 아무것도 이상해 보이지 않습니다.
피해 범위를 줄이는 방법은 두 가지입니다. 첫째, 진짜 비밀이 보관된 노트북이 아니라 범위가 제한된 곳에서 에이전트를 실행하세요. Sharkly는 수명이 짧고 일회용인 일회성 설치 토큰으로 Computer를 등록하며, 문서에도 분명히 나와 있습니다. 그 토큰을 재사용 가능한 이미지나 스크립트, Task, 댓글에 넣지 말라고요. Computer가 컨테이너든, 서버든, 여분의 머신이든, 에이전트의 접근 범위는 당신의 환경이 아니라 그 환경의 접근 범위입니다. 오프라인일 때도 에이전트가 작업하길 원한다면, 열려 있는 노트북 대신 원격 Computer에서 실행하세요.
둘째, 한 번의 실행에 필요한 것만 넘겨주세요. Sharkly 실행의 환경은 명시적 설정으로 구성됩니다. 연결된 저장소, 환경 변수, 시크릿 바인딩, 작업 디렉터리가 그것입니다. Space 기본값보다 좁은 코드 범위가 필요할 때는 Agent에 저장소를 연결하세요. 그래야 프런트엔드 Agent가 결제 서비스를 체크아웃하는 일이 없습니다. 각 실행은 자체 격리된 워크트리에서 이루어지게 하세요. 잘못된 편집이 하나의 체크아웃에 머무르느냐, 두 에이전트가 같은 워킹 트리를 망가뜨리느냐의 차이가 바로 여기서 갈립니다. 모든 필드에 적용되는 원칙이 있습니다. 제품이 요구하는 설정만 입력하고, 비밀번호나 토큰을 관계없는 필드나 시작 명령에 절대 붙여넣지 마세요.
3단계: 태스크 범위 정하기, 그리고 머지는 사람에게 남겨두기
마지막 계층은 의도입니다. 올바르게 샌드박스 처리되고 자격 증명 범위도 제한된 에이전트라도 잘못된 작업을 할 수 있습니다. 자기 태스크를 완료 처리하거나, 미완성 변경을 공용 브랜치에 푸시하거나, PR이 머지할 준비가 됐다고 판단하는 식으로요.
바로 여기가 인간-에이전트 계약이 필요한 지점입니다. 에이전트는 조사하고, 실행하고, 테스트하고, 보고합니다. 사람은 방향을 정하고, 권한을 부여하고, 결과를 승인합니다. 팀의 판단이 필요한 지점에서 자동화는 멈춥니다. 에이전트는 드래프트 PR을 열고 테스트 출력을 첨부하는 것까지는 허용되어야 하지만, 그 PR을 승인하거나 보호된 브랜치에 머지해서는 안 됩니다. 호스트의 브랜치 보호와 태스크에 대한 사람의 리뷰, 이 두 개의 잠금장치가 그 경계를 지켜줍니다.
Sharkly에서는 태스크 자체가 이 제한을 담고 있습니다. Task 타입 Workflow는 Agent가 선택할 수 있는 상태를 제한하므로, Agent가 사람이 소유한 "Done"이나 "Released" 상태로 작업을 몰래 옮길 수 없습니다. Agent가 결정을 필요로 할 때는 태스크를 사람의 리뷰나 답변을 기다리는 상태로 남겨두고, 그것이 Inbox에 나타나 담당자가 승인하거나, 변경을 요청하거나, 재할당할 수 있게 합니다. 실행, 블로커, 결과, 리뷰가 모두 하나의 Task로 돌아오고, 다섯 개의 터미널에 흩어지지 않습니다.
이 지점에서 직접 구축한 방식의 확장성도 한계에 부딪힙니다. 에이전트 하나, 저장소 하나, 꼼꼼한 엔지니어 한 명이라면 권한 모델 전체를 머릿속에 담아둘 수 있습니다. 여기에 두 번째, 세 번째 에이전트가 더해지고 저장소가 늘고 팀원이 합류하면, "여기서 각 에이전트가 무엇을 할 수 있는가"라는 질문에 아무도 기억만으로 답할 수 없게 됩니다. 태스크 보드는 이런 규칙들을 공유되고 검토 가능한 설정으로 바꿔줍니다. 누가 작업을 할당했고, 실행 범위가 어땠고, 어떤 증거가 돌아왔고, 누가 승인했는지가 드러나죠. 이것이 코딩 에이전트 위의 관리 계층입니다. 워크트리, 범위가 제한된 자격 증명, 브랜치 보호로 직접 구축할 수도 있고, 기존 코딩 에이전트를 Sharkly로 실행해서 권한, 태스크, 리뷰를 한곳에서 관리할 수도 있습니다.
오늘 바로 실행할 수 있는 권한 체크리스트
실제 저장소를 건드리게 하는 모든 에이전트에 대해 이 목록을 점검하세요.
- 런타임: 읽기와 테스트는 프롬프트 없이 허용, 편집과 셸 명령은 게이트로 차단, 무인 실행에서는 전면 건너뛰기 모드 꺼둠.
- 머신: 에이전트는 주 사용 머신이 아닌 범위가 제한된 Computer에서 실행, 설치 및 접근 토큰은 일회용이며 절대 커밋하지 않음.
- 자격 증명: 이번 실행에 필요한 환경 변수와 시크릿 바인딩만 사용, 관계없는 필드에 아무것도 붙여넣지 않음.
- 저장소 범위: 에이전트는 Space의 모든 저장소가 아니라 작업에 필요한 저장소에만 연결됨.
- 격리: 각 실행이 자체 워크트리를 가지므로 잘못된 변경이 공유 체크아웃을 망가뜨릴 수 없음.
- 태스크 범위: 에이전트는 작업 중 상태는 설정할 수 있지만 사람이 소유한 승인 또는 릴리스 상태로 태스크를 옮길 수 없음.
- 머지: 브랜치 보호와 태스크 수준 증거를 동반한 사람의 리뷰가 에이전트의 PR과 main 사이를 지킴.
이 중 하나라도 느슨하다면, 그것이 왜 중요했는지 깨닫게 해주는 사고가 난 다음이 아니라, 다음 실행 전에 조이세요.
자주 묻는 질문
코딩 에이전트 권한과 승인 게이트의 차이는 무엇인가요? 권한은 에이전트가 기술적으로 무엇을 할 수 있는지를 정의합니다. 어떤 파일, 명령, 자격 증명에 접근할 수 있는지 말이죠. 승인 게이트는 사람이 에이전트가 한 일을 받아들일지 결정하는 지점입니다. 둘 다 필요합니다. 권한이 빡빡해도 사람이 최종 확인해야 할 작업은 남아 있고, 에이전트가 이미 해를 끼칠 권한을 갖고 있었다면 승인 게이트는 도움이 되지 않기 때문입니다.
코딩 에이전트가 자기 PR을 직접 머지하도록 허용해도 되나요? 아니요, 기본적으로는 안 됩니다. 에이전트가 드래프트 PR을 열고 검증 출력을 첨부하게 한 뒤, 머지는 사람이나 필수 리뷰에 맡기세요. 근거는 인간-에이전트 계약입니다. 에이전트는 실행하고 보고하고, 사람은 승인하고 릴리스합니다. 이는 에이전트가 작업의 대부분을 수행하는 휴먼 인 더 루프 워크플로에서도 마찬가지입니다.
모든 권한 프롬프트를 꺼둔 채 에이전트를 실행해도 안전한가요? 지켜보고 있을 때만 안전합니다. 자동 승인 모드는 잘못된 단계를 멈출 수 있는 감독 세션에서는 유용합니다. 무인 실행이나 야간 실행에서는 프롬프트나 허용 목록을 켜두고, 실수가 통제 안에 머물도록 에이전트를 범위가 제한된 머신에서 실행하세요.
