AI 코드 에이전트 운영 체크리스트: AGENTS.md, 샌드박스, 권한 프로필로 리뷰 비용 줄이기

요약: AI 코드 에이전트를 팀에 도입할 때 가장 흔한 실패는 모델 선택에서 생기지 않는다. 작업 지시가 불명확하고, 테스트 명령이 없고, 권한이 과하며, 결과 검증 방식이 없을 때 실패한다. Codex, Claude Code, Antigravity처럼 도구는 달라도 운영 원칙은 비슷하다. 에이전트를 “똑똑한 주니어 개발자”가 아니라 “권한 제한이 필요한 자동 작업자”로 다뤄야 한다.

검색 의도: AI 코드 에이전트 운영, AGENTS.md, Claude Code Codex 체크리스트, 코드 에이전트 보안

코드 에이전트 도입의 진짜 병목

AI 코드 에이전트는 이제 단순 autocomplete를 넘어섰다. 파일을 읽고, 수정하고, 테스트를 실행하고, PR을 만들고, 모바일이나 웹에서 원격 제어되는 흐름까지 나오고 있다. OpenAI Codex는 AGENTS.md 기반 지시, 샌드박스 실행, permission profile, 원격 제어를 강화하고 있다. Anthropic Claude Code 쪽도 remote control, auto mode, worktree, routine 같은 운영 기능을 발전시키고 있다. Google Antigravity 역시 agent-first 개발 환경을 강조한다.

그런데 팀 생산성이 자동으로 올라가지는 않는다. 에이전트에게 “버그 고쳐줘”라고 맡기면 운이 좋을 때는 빨리 끝나지만, 운이 나쁠 때는 엉뚱한 파일을 바꾸고 테스트 없이 그럴듯한 설명을 남긴다. 사람이 리뷰하는 비용이 더 커지는 경우도 많다.

핵심은 에이전트에게 작업 환경과 기준을 제공하는 것이다. 사람 개발자에게 온보딩 문서와 테스트 방법을 주듯이, 에이전트에게도 프로젝트 규칙을 줘야 한다. 이 역할을 하는 대표적인 파일이 AGENTS.md다.

AGENTS.md에 꼭 들어가야 할 내용

AGENTS.md는 README와 다르다. README가 사람에게 프로젝트를 설명하는 문서라면, AGENTS.md는 에이전트가 작업할 때 따라야 할 실행 규칙이다. 길게 쓰는 것보다 판단에 필요한 정보를 정확히 쓰는 것이 중요하다.

최소 항목은 다음과 같다.

• 프로젝트 구조: 주요 폴더와 역할.
• 설치 명령: 처음 환경을 만들 때 필요한 명령.
• 테스트 명령: 변경 범위별로 어떤 테스트를 돌릴지.
• 린트와 타입체크 명령: PR 전 필수 검증.
• 금지 명령: 삭제, 배포, DB 변경, secret 조회 등.
• 코드 스타일: 네이밍, 파일 위치, 에러 처리 방식.
• PR 규칙: 변경 요약, 테스트 로그, 위험도 표시.
• 질문 기준: 불확실할 때 멈추고 물어야 하는 조건.

나쁜 예시는 “코드를 깨끗하게 작성해줘”다. 좋은 예시는 “API route 변경 시 pnpm test:api와 pnpm typecheck를 실행하고, Prisma migration은 생성하지 말고 필요하면 사람에게 요청하라”다. 에이전트는 추상적인 품질 기준보다 구체적인 명령과 금지 조건을 잘 따른다.

작업 단위를 작게 나누는 법

코드 에이전트에게 한 번에 큰 일을 맡기면 실패 확률이 올라간다. “대시보드 리뉴얼”은 너무 크다. “월간 매출 카드에 전월 대비 증감률을 추가하고 기존 테스트를 갱신”은 적당하다.

좋은 작업 단위는 네 가지 조건을 가진다.

1. 변경 범위가 예측 가능하다.
2. 성공 여부를 테스트나 스크린샷으로 확인할 수 있다.
3. 되돌리기 쉽다.
4. 사람이 리뷰할 diff가 너무 크지 않다.

프론트엔드라면 컴포넌트 하나, 상태 로직 하나, 접근성 수정 하나로 나누는 편이 좋다. 백엔드라면 endpoint 하나, validation 하나, migration 없는 리팩터링 하나로 나누는 편이 좋다. 에이전트가 강해질수록 큰 작업을 맡기고 싶어지지만, 운영 안정성은 작은 작업에서 나온다.

샌드박스와 권한 프로필

에이전트가 파일을 수정하고 명령을 실행할 수 있다면 권한 관리는 필수다. 샌드박스는 “실수해도 피해가 제한되는 공간”이다. 권한 프로필은 “어떤 행동을 허용할지 정한 정책”이다. 둘 중 하나만 있어서는 부족하다.

권장 권한 단계는 다음과 같다.

• Read-only: 코드 읽기, 질문 답변, 영향 범위 분석.
• Test-safe: 테스트, 린트, 타입체크 실행 허용.
• Edit-safe: 제한된 폴더의 코드 수정 허용.
• Network-limited: 패키지 설치와 문서 조회만 허용.
• Human-approved: 삭제, 배포, DB 변경, 외부 전송은 사람 승인 필요.

특히 production 관련 명령은 자동 승인 대상에서 빼야 한다. 에이전트가 “필요해 보여서” 마이그레이션을 실행하거나 배포를 시도하는 상황은 막아야 한다. 사람 개발자도 실수하는 영역은 에이전트에게 더 엄격해야 한다.

리뷰 비용을 줄이는 출력 형식

에이전트 결과물이 장황하면 리뷰어가 지친다. 반대로 너무 짧으면 검증이 어렵다. 팀에서 고정된 결과 형식을 요구하는 것이 좋다.

권장 형식은 다음과 같다.

• 변경 요약: 3줄 이내.
• 변경 파일: 주요 파일 목록.
• 검증: 실행한 명령과 결과.
• 미검증 항목: 실행하지 못한 테스트와 이유.
• 위험도: low, medium, high 중 하나.
• 리뷰 포인트: 사람이 특히 봐야 할 부분.

예를 들어 “pnpm test:api 통과, pnpm typecheck 통과, 결제 실패 케이스는 mock 데이터 부족으로 수동 확인 필요”처럼 남기면 리뷰어가 빠르게 판단할 수 있다. “모든 것이 잘 작동합니다”는 쓸모가 없다.

실패를 학습 데이터로 남기는 방법

에이전트가 실패했을 때 그냥 다시 시키면 같은 문제가 반복된다. 실패 원인을 분류해 AGENTS.md나 작업 템플릿에 반영해야 한다.

자주 나오는 실패 유형은 다음과 같다.

• 테스트 명령을 몰라서 검증하지 않음.
• 비슷한 파일을 잘못 수정함.
• 기존 패턴을 무시하고 새 구조를 만듦.
• 타입 에러를 우회하려고 any를 남발함.
• 임시 코드를 삭제하지 않음.
• 외부 API나 DB 접근을 과하게 시도함.

각 실패는 규칙으로 바꿀 수 있다. “타입 오류 해결을 위해 any를 추가하지 말고, 불가피하면 이유를 보고하라”, “새 유틸을 만들기 전 기존 src/lib 검색을 먼저 하라”처럼 구체화한다. 에이전트 운영은 한 번 설정하고 끝나는 일이 아니라, 실패를 규칙으로 축적하는 과정이다.

팀 도입 순서

처음부터 모든 개발자가 에이전트를 자유롭게 쓰게 하지 말고, 낮은 위험 작업부터 시작하는 편이 좋다.

1단계는 읽기 전용 분석이다. “이 버그의 원인 후보를 찾아줘”, “이 컴포넌트가 어디서 쓰이는지 정리해줘”처럼 코드 변경 없이 쓰게 한다.

2단계는 테스트 보강이다. 기존 기능을 바꾸지 않고 regression test를 추가한다. 실패해도 영향이 작고, 에이전트의 코드 이해도를 확인하기 좋다.

3단계는 작은 버그 수정이다. 변경 파일 3개 이하, 테스트 가능, 롤백 쉬운 작업만 맡긴다.

4단계는 PR 생성 자동화다. 이때도 자동 merge는 하지 않는다. CI와 사람 리뷰를 반드시 거친다.

운영 체크리스트

• AGENTS.md에 프로젝트 구조, 테스트 명령, 금지 명령이 적혀 있는가?
• 작업을 30분 이하, 변경 파일 3~5개 이하로 쪼갰는가?
• read-only, test-safe, edit-safe, human-approved 권한 단계를 나눴는가?
• DB 변경, 배포, secret 접근은 자동 승인에서 제외했는가?
• 에이전트 결과물에 변경 파일, 테스트 로그, 미검증 항목이 포함되는가?
• 리뷰어가 볼 포인트를 에이전트가 명시하도록 했는가?
• 실패 사례를 AGENTS.md나 작업 템플릿에 반영하는 루프가 있는가?
• 자동 merge 없이 PR과 CI를 거치도록 했는가?

AI 코드 에이전트는 잘 쓰면 작은 개발팀의 처리량을 크게 늘린다. 하지만 규칙 없이 쓰면 리뷰 비용과 사고 위험이 같이 늘어난다. AGENTS.md, 샌드박스, 권한 프로필, 검증 로그를 먼저 갖추면 에이전트는 “가끔 신기한 도구”가 아니라 반복 가능한 개발 프로세스가 된다.