CI에 코딩 에이전트를 넣는 일은 생산성이라는 옷을 입은 권한 설계 문제다. 메커니즘 자체는 오후 한나절이면 끝난다. 헤드리스 모드는 2025년 9월 Claude Code 2.0부터 제공됐고, anthropics/claude-code-action@v1은 이 전체 과정을 GitHub Action 하나로 감싸준다. 점심 먹기 전에 풀 리퀘스트에 댓글을 다는 에이전트를 만들 수 있다. 그 에이전트에게 커밋을 푸시하게 할지는 전혀 다른 질문이고, 유일하게 중요한 질문이기도 하다.

이걸 안전하게 지키는 규칙은 단순하다. CI 안의 에이전트는 제안만 하고, 병합은 하지 않는다. 아래에 나오는 패턴들은 모두 이 선을 어디에 긋느냐의 변주일 뿐이다.

헤드리스 모드, 짧게

-p(또는 --print) 플래그는 Claude Code를 대화형 REPL에서 단일 배치 호출로 전환시키며, 이것이 스크립트로 다룰 수 있게 만드는 핵심이다. 데모를 무인 실행 가능한 무언가로 바꿔주는 플래그는 제약을 거는 플래그들이다.

claude -p "Fix the failing unit tests. Do not change public APIs." \
  --output-format json \
  --max-turns 8 \
  --allowedTools "Read,Edit,Bash(npm test)" \
  --model claude-haiku-4-5

각 플래그는 실제로 일을 한다. --output-format json은 result, model, usage, stop_reason을 담은 객체를 반환하므로, 파이프라인은 산문을 grep하는 대신 결과에 따라 분기할 수 있다. --max-turns는 회로 차단기다. --allowedTools는 허용 목록이고, 이 한 줄에서 가장 중요한 플래그다.

배짱의 크기 순으로 세 가지 패턴

팀들은 셋 중 하나에 정착한다. 이 셋은 동등하지 않으며, 대부분의 팀은 두 번째에서 멈춰야 한다.

  • 자문형. 에이전트는 diff를 읽고 코멘트만 남긴다. 어떤 것에도 쓰기 권한이 없다. 발견 사항 하나하나를 사람이 받아들이거나 무시하는 데 30초가 든다. 여기서 시작해야 하고, 많은 팀은 여기 계속 머물러도 된다.
  • 제안형. 에이전트는 무언가를 고치고 브랜치에 풀 리퀘스트를 연다. 코드는 에이전트가 쓰지만 병합 버튼은 사람 몫이다. 이미 신뢰하고 있는 리뷰 게이트가 원래 하도록 만들어진 일을 그대로 한다. 여기가 최적점이다.
  • 자율형. 에이전트가 배포로 이어지는 브랜치에 직접 커밋한다. 사람들이 데모하는 패턴이자 사고를 만드는 패턴이다. CI는 스택 전체에서 나쁜 행위자가 사람의 개입 없이 곧장 배포된 산출물이 되는 유일한 지점이기 때문이다.

셋 사이에서 바뀌는 건 에이전트의 능력이 아니라 실수의 파급 범위뿐이라는 점에 주목하라. 에이전트가 틀릴 확률은 세 경우 모두 똑같다. 다른 건 그다음에 무슨 일이 벌어지는가다.

아무도 대비하지 않는 실패 양상

뻔한 걱정은 에이전트가 나쁜 코드를 짤지 모른다는 것이다. 그건 이미 대비돼 있다. 테스트와 리뷰어가 나쁜 코드를 잡아내라고 있는 것이니까.

진짜 실패는 더 미묘하다. 빌드를 초록색으로 만들라는 지시를 받은 에이전트는 목표가 딱 하나뿐이고, 거기 도달하는 방법은 하나가 아니다. 실패하는 assertion을 지워도 빌드는 초록색이 된다. 테스트에 skip을 붙여도 초록색이 된다. 타입을 any로 넓혀도 타입 에러는 사라진다. 이 중 어느 것도 에이전트의 오작동이 아니다. 지시가 목표가 아니라 증상을 서술했기 때문에, 에이전트는 요청받은 그대로를 의도하지 않은 방식으로 정확히 해낸 것이다.

도움이 되는 것은 두 가지다. 목표를 타깃이 아니라 제약으로 적어라. "테스트 파일을 건드리지 말고 구현을 고쳐서 기존 테스트를 통과시켜라"는 "빌드를 고쳐라"와는 다른 지시다. 그리고 산문을 신뢰하는 대신 구조적으로 강제하라. 산문은 요청이지만 도구 허용 목록은 규칙이다.

진짜로 힘을 받는 가드레일

  • 도구 허용 목록을 작업 범위로 좁혀라. 테스트를 고치는 에이전트는 파일을 읽고 소스를 편집하고 테스트 명령을 실행하면 된다. 네트워크 접근도, CI 설정을 건드릴 권한도, 러너 환경에 마침 놓여 있는 배포 자격 증명도 필요 없다.
  • 정답의 기준이 되는 파일을 보호하라. 테스트, 락파일, CI 워크플로, IAM 정책은 경로 차단 목록에 올려야 한다. 에이전트가 테스트를 편집할 수 없다면 테스트를 지워서 통과시킬 수도 없다.
  • 턴 수와 토큰에 상한을 둬라. 수렴하지 못하는 루프는 멈추고 그렇다고 말해야 한다. 상한 없는 에이전트가 불가능한 과제를 붙들고 있는 건 청구서와 밀린 작업 큐를 만든다.
  • 러너에게 고유한 신원을 부여하라. 마침 그 자리에 있던 광범위한 관리자 역할이 아니라, 그 하나의 작업에 필요한 권한만 가진 범위 지정 역할로 에이전트의 작업이 돌아가야 한다. 그래야 혼란에 빠진 에이전트가 애초에 가질 필요가 없던 무언가에 손을 뻗지 못한다.
  • 에이전트의 커밋을 신뢰할 수 없는 입력으로 취급하라. 다른 기여자와 동일한 필수 체크, 동일한 리뷰, 동일한 브랜치 보호. 에이전트에게 지름길은 없다. 지름길이야말로 취약점이기 때문이다.
  • 세션 전체를 기록하라. 에이전트가 만든 변경이 새벽 3시에 사고를 일으켰을 때 "무엇을 지시받았고 무엇을 했는가"라는 질문에 어깨를 으쓱하는 것 말고 답이 있어야 한다. JSON 출력과 세션 트랜스크립트가 그 감사 기록이다. 보관하라.

경제성은 정말로 좋다

공정하게 짚어야 할 부분이 있다. 숫자는 유리하다. 중간 크기 diff에 대한 자동 리뷰 한 번은 몇 센트에 1분도 안 걸려 끝난다. 리뷰어의 컨텍스트 전환 비용과 비교하면 거의 모든 풀 리퀘스트 볼륨에서 이 셈법은 성립하고, 바로 그래서 이 패턴이 퍼지고 있다.

바로 그 점이 함정이기도 하다. 매 PR마다 돌릴 만큼 저렴하다는 건 별생각 없이 돌릴 만큼 저렴하다는 뜻이고, 허용 목록에 권한 하나를 더 추가하는 한계 비용은 추가하는 순간에는 항상 0이다. 비용은 나중에, 한 번에 몰려온다. 경계는 아직 가설일 때 정해두는 편이 낫다.

요약

파이프라인 안의 에이전트는 판단력은 없지만 인내심은 무한하고 러너에게 쥐여준 자격 증명은 무엇이든 갖게 되는 기여자다. 좁은 도구만 주어 한 가지 일만 하게 하고, 무엇이 정답인지를 규정하는 파일을 보호하고, 루프에 상한을 두고, 다른 모두처럼 풀 리퀘스트를 열게 하라. 생산성 향상은 실재한다. 다만 그것은 지루한 초안 작업을 에이전트가 대신 해주는 데서 오는 것이지, 예스라고 말하는 사람을 없애는 데서 오는 게 아니다.

이어서 읽으면 좋은 글

파이프라인 쪽 이야기로는 why automated tests are essential in your CI/CD pipeline이 에이전트의 결과물이 통과해야 할 체크들을 ercan.cloud에서 다룬다. 허브는 ercanermis.com이다.