AI 코딩 에이전트 권한 설계법: 파일·터미널·네트워크를 어디까지 열어줄까

요약: Claude Code, Copilot CLI 같은 코딩 에이전트는 코드를 읽고, 파일을 수정하고, 명령을 실행하고, 개발 도구와 연결된다. 생산성은 여기서 나오지만 사고도 같은 지점에서 난다. 실무 도입의 핵심은 좋은 프롬프트보다 권한 경계, 샌드박스, 로그, 승인 규칙을 먼저 설계하는 것이다.

코딩 에이전트는 챗봇이 아니라 작업자다

공식 Claude Code 문서는 이 도구를 코드베이스를 읽고, 파일을 편집하고, 명령을 실행하며, 개발 도구와 통합되는 agentic coding tool로 설명한다. GitHub Copilot CLI도 터미널에서 작업을 수행하고 모델을 호출한다. 즉 코딩 에이전트는 질문에 답하는 챗봇이 아니라 실제 저장소 상태를 바꾸는 작업자에 가깝다.

이 차이를 무시하면 위험하다. 챗봇은 틀린 답을 하면 사람이 무시하면 된다. 코딩 에이전트는 틀린 명령을 실행하거나, 의도하지 않은 파일을 바꾸거나, secret이 포함된 로그를 읽어 요약할 수 있다. 그래서 도입 순서는 ‘어떤 모델이 똑똑한가’보다 ‘어디까지 허용할 것인가’가 먼저다.

권한 설계는 개발 속도를 늦추는 절차가 아니다. 오히려 팀이 안심하고 에이전트를 더 자주 쓰게 만드는 기반이다. 파일 범위, 명령 범위, 네트워크 범위, 외부 쓰기 권한이 명확하면 작은 작업은 과감하게 자동화할 수 있다.

파일 권한: 읽기와 쓰기를 분리한다

첫 번째 원칙은 읽기 권한과 쓰기 권한을 다르게 보는 것이다. 에이전트가 저장소 전체를 읽어야 문제를 이해할 수 있는 경우는 많다. 그러나 저장소 전체를 수정할 필요는 드물다. 작업 시작 전 변경 가능한 디렉터리와 파일 패턴을 정하고, 실행 후 diff가 그 범위를 벗어나면 실패 처리해야 한다.

예를 들어 문서 작업은 docs/, README.md, .mdx 파일만 허용한다. 테스트 수정은 해당 테스트 파일과 대상 소스 파일만 허용한다. 의존성 업데이트는 package manifest와 lockfile, 관련 타입 수정 파일로 제한한다. 결제, 인증, 권한, 배포 설정 파일은 별도 승인 없이는 수정하지 못하게 둔다.

읽기 권한에도 예외가 있다. .env, private key, production credential, 고객 데이터 dump는 에이전트가 읽지 못하게 해야 한다. .gitignore에 들어간 파일이라고 해서 자동으로 안전한 것은 아니다. 로컬 작업 환경에는 임시 로그와 secret이 섞여 있을 수 있다.

명령 권한: allowlist부터 만든다

터미널 명령은 코딩 에이전트의 가장 강력한 도구다. 테스트를 실행하고 타입체크를 돌릴 수 있어야 품질이 올라간다. 동시에 rm, 배포, migration, cloud CLI, package publish 같은 명령은 큰 사고를 만들 수 있다. 따라서 기본은 deny이고, 필요한 명령만 allowlist로 여는 편이 안전하다.

초기 allowlist는 단순하게 시작한다. npm test, npm run typecheck, npm run lint, pnpm test, git diff, git status처럼 읽기 또는 검증 중심 명령을 허용한다. 설치 명령, 데이터베이스 migration, cloud deploy, production secret 접근은 사람 승인 대상으로 둔다.

명령은 문자열만 볼 것이 아니라 실행 위치와 인자도 봐야 한다. npm test는 안전해 보여도 pretest script가 외부 서비스를 건드릴 수 있다. python script.py도 script 내용에 따라 위험도가 달라진다. CI나 전용 샌드박스에서 검증된 script만 실행하게 하는 구조가 좋다.

네트워크 권한: 외부 쓰기를 기본 차단한다

코딩 에이전트가 네트워크에 접근하면 패키지 설치, 문서 조회, API 테스트가 가능해진다. 하지만 외부 전송도 가능해진다. 민감한 코드나 로그가 요청 본문에 들어갈 수 있고, 잘못된 API endpoint에 쓰기 요청을 보낼 수도 있다. 그래서 네트워크 권한은 읽기와 쓰기를 나눠야 한다.

문서 조회, package registry metadata, public API GET 요청은 상대적으로 안전하다. 반면 Slack, Discord, GitHub PR 생성, cloud resource 변경, 결제 API 호출, 이메일 발송은 외부 write로 분류한다. 외부 write는 자동 승인하지 말고 사람 확인을 거친다.

테스트 환경도 분리해야 한다. 에이전트가 실제 production API key로 통합 테스트를 돌리면 안 된다. mock, localstack, staging credential, read-only token을 사용하고, 호출량 제한을 둔다. AI 에이전트가 빠르게 반복하면 API quota도 빠르게 닳는다.

로그와 감사 추적

에이전트 작업은 나중에 재현 가능해야 한다. 어떤 프롬프트로 시작했는지, 어떤 파일을 읽고 바꿨는지, 어떤 명령을 실행했는지, 어떤 모델이 선택됐는지, 실패 후 어떤 결정을 했는지 남겨야 한다. 이 로그가 없으면 사고가 났을 때 사람의 기억에 의존하게 된다.

로그에는 민감정보를 남기지 않는 규칙도 필요하다. 에이전트가 .env 내용을 읽지 못하게 하는 것이 우선이고, 명령 출력에 secret이 섞일 때 마스킹하는 것도 필요하다. CI artifact와 PR comment는 공개 범위가 넓어질 수 있으므로 특히 조심해야 한다.

감사 로그의 목적은 책임 추궁이 아니라 학습이다. 어떤 작업에서 에이전트가 자주 잘못된 파일을 건드리는지, 어떤 명령에서 실패가 많은지, 어떤 프롬프트가 비용을 많이 쓰는지 보면 자동화 범위를 더 안전하게 넓힐 수 있다.

승인 규칙: 위험한 순간만 사람이 본다

모든 단계마다 승인을 요구하면 에이전트의 장점이 사라진다. 반대로 모든 것을 자동 승인하면 사고가 난다. 좋은 승인 규칙은 위험한 순간에만 멈춘다. 예를 들어 파일 삭제, dependency major upgrade, DB schema 변경, 외부 write, secret 접근, 배포 명령은 승인 대상이다.

반면 테스트 실행, 타입체크, 문서 수정, 작은 단위의 코드 변경은 자동으로 진행해도 된다. 핵심은 승인 기준을 작업 전에 정하는 것이다. 작업 중간에 사람이 감으로 판단하면 일관성이 떨어지고, 에이전트도 예측 가능한 경계 안에서 움직이지 못한다.

승인 요청에는 전체 명령, 변경 파일, 예상 영향, 되돌리는 방법이 있어야 한다. ‘진행해도 될까요?’만 묻는 승인은 의미가 없다. 리뷰어가 실제 위험을 판단할 수 있는 정보가 필요하다.

팀 도입 순서

처음부터 모든 개발 작업을 에이전트에 맡기지 말아야 한다. 1단계는 읽기 전용 분석이다. 에러 로그 요약, 테스트 실패 원인 후보, 리팩터링 계획처럼 파일 수정 없이 도움을 받는다. 2단계는 제한된 파일 수정이다. 테스트 추가, 문서 수정, 타입 에러 수정이 적합하다.

3단계는 CI와 연결한 자동 PR이다. 이때는 파일 범위, 명령 allowlist, 비용 한도, PR 리뷰 규칙이 준비되어 있어야 한다. 4단계는 더 큰 migration이나 반복 작업 자동화다. 이 단계에서도 자동 merge는 예외적으로만 허용한다.

도입 성공의 기준은 ‘에이전트가 몇 줄을 썼나’가 아니다. 리뷰 시간이 줄었는지, rollback이 늘지 않았는지, 테스트 실패가 줄었는지, 비용이 예측 가능한지가 기준이다.

실행 체크리스트

• 에이전트의 읽기 가능 파일과 쓰기 가능 파일을 분리해 정의한다.

• 터미널 명령은 deny-by-default로 두고 테스트·lint·typecheck부터 allowlist에 넣는다.

• 외부 write, 배포, DB migration, secret 접근은 사람 승인 대상으로 둔다.

• 프롬프트, diff, 실행 명령, 모델, 비용, 실패 원인을 작업 로그로 남긴다.

• 읽기 전용 분석 → 제한 파일 수정 → 자동 PR → 큰 migration 순서로 도입 범위를 넓힌다.