요약: 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는 README와 다르다. README가 사람에게 프로젝트를 설명하는 문서라면, AGENTS.md는 에이전트가 작업할 때 따라야 할 실행 규칙이다. 길게 쓰는 것보다 판단에 필요한 정보를 정확히 쓰는 것이 중요하다.
최소 항목은 다음과 같다.
나쁜 예시는 “코드를 깨끗하게 작성해줘”다. 좋은 예시는 “API route 변경 시 pnpm test:api와 pnpm typecheck를 실행하고, Prisma migration은 생성하지 말고 필요하면 사람에게 요청하라”다. 에이전트는 추상적인 품질 기준보다 구체적인 명령과 금지 조건을 잘 따른다.
코드 에이전트에게 한 번에 큰 일을 맡기면 실패 확률이 올라간다. “대시보드 리뉴얼”은 너무 크다. “월간 매출 카드에 전월 대비 증감률을 추가하고 기존 테스트를 갱신”은 적당하다.
좋은 작업 단위는 네 가지 조건을 가진다.
프론트엔드라면 컴포넌트 하나, 상태 로직 하나, 접근성 수정 하나로 나누는 편이 좋다. 백엔드라면 endpoint 하나, validation 하나, migration 없는 리팩터링 하나로 나누는 편이 좋다. 에이전트가 강해질수록 큰 작업을 맡기고 싶어지지만, 운영 안정성은 작은 작업에서 나온다.
에이전트가 파일을 수정하고 명령을 실행할 수 있다면 권한 관리는 필수다. 샌드박스는 “실수해도 피해가 제한되는 공간”이다. 권한 프로필은 “어떤 행동을 허용할지 정한 정책”이다. 둘 중 하나만 있어서는 부족하다.
권장 권한 단계는 다음과 같다.
특히 production 관련 명령은 자동 승인 대상에서 빼야 한다. 에이전트가 “필요해 보여서” 마이그레이션을 실행하거나 배포를 시도하는 상황은 막아야 한다. 사람 개발자도 실수하는 영역은 에이전트에게 더 엄격해야 한다.
에이전트 결과물이 장황하면 리뷰어가 지친다. 반대로 너무 짧으면 검증이 어렵다. 팀에서 고정된 결과 형식을 요구하는 것이 좋다.
권장 형식은 다음과 같다.
예를 들어 “pnpm test:api 통과, pnpm typecheck 통과, 결제 실패 케이스는 mock 데이터 부족으로 수동 확인 필요”처럼 남기면 리뷰어가 빠르게 판단할 수 있다. “모든 것이 잘 작동합니다”는 쓸모가 없다.
에이전트가 실패했을 때 그냥 다시 시키면 같은 문제가 반복된다. 실패 원인을 분류해 AGENTS.md나 작업 템플릿에 반영해야 한다.
자주 나오는 실패 유형은 다음과 같다.
any를 남발함.각 실패는 규칙으로 바꿀 수 있다. “타입 오류 해결을 위해 any를 추가하지 말고, 불가피하면 이유를 보고하라”, “새 유틸을 만들기 전 기존 src/lib 검색을 먼저 하라”처럼 구체화한다. 에이전트 운영은 한 번 설정하고 끝나는 일이 아니라, 실패를 규칙으로 축적하는 과정이다.
처음부터 모든 개발자가 에이전트를 자유롭게 쓰게 하지 말고, 낮은 위험 작업부터 시작하는 편이 좋다.
1단계는 읽기 전용 분석이다. “이 버그의 원인 후보를 찾아줘”, “이 컴포넌트가 어디서 쓰이는지 정리해줘”처럼 코드 변경 없이 쓰게 한다.
2단계는 테스트 보강이다. 기존 기능을 바꾸지 않고 regression test를 추가한다. 실패해도 영향이 작고, 에이전트의 코드 이해도를 확인하기 좋다.
3단계는 작은 버그 수정이다. 변경 파일 3개 이하, 테스트 가능, 롤백 쉬운 작업만 맡긴다.
4단계는 PR 생성 자동화다. 이때도 자동 merge는 하지 않는다. CI와 사람 리뷰를 반드시 거친다.
AGENTS.md에 프로젝트 구조, 테스트 명령, 금지 명령이 적혀 있는가?AI 코드 에이전트는 잘 쓰면 작은 개발팀의 처리량을 크게 늘린다. 하지만 규칙 없이 쓰면 리뷰 비용과 사고 위험이 같이 늘어난다. AGENTS.md, 샌드박스, 권한 프로필, 검증 로그를 먼저 갖추면 에이전트는 “가끔 신기한 도구”가 아니라 반복 가능한 개발 프로세스가 된다.