AI 에이전트에게 레포를 맡길 때 먼저 세워야 할 네 개의 경계
AI 에이전트에게 “이 기능 전부 만들어 줘”라고 말하는 일은 점점 자연스러워지고 있습니다. 문제는 에이전트가 코드를 쓸 수 있느냐가 아닙니다. 어디까지 맡겼는지, 무엇을 근거로 판단했는지, 언제 멈춰야 하는지가 불분명한 상태로 작업을 시작하는 것이 문제입니다.
좋은 에이전트 사용법은 더 큰 프롬프트에서 시작하지 않습니다. 작업의 경계를 먼저 정하고, 에이전트가 만든 결과를 사람이 검증할 수 있는 루프를 만드는 것에서 시작합니다.
워크플로와 에이전트는 다릅니다
Anthropic은 미리 정해진 코드 경로를 따라가는 workflow와, 모델이 도구 사용과 다음 행동을 스스로 결정하는 agent를 구분합니다. 둘 다 유용하지만 위험의 모양이 다릅니다. 고정된 workflow는 예상 가능한 대신 유연성이 낮고, agent는 유연한 대신 더 많은 판단을 맡깁니다.
여기서 흔한 실수는 에이전트에게 workflow의 계약 없이 agent의 자율성만 주는 것입니다. “알아서 해”는 목표가 아닙니다. 저장소에서 허용되는 행동과 완료의 증거가 함께 있어야 합니다.
첫 번째 경계 — 범위
작업을 기능 이름으로만 주지 말고 종료 조건으로 쪼개세요.
나쁜 요청:
로그인 기능을 완성해 줘.
나은 요청:
이번 작업은 이메일 로그인 폼의 유효성 검사만 다룬다.
변경 허용 경로는 src/auth와 테스트 파일이다.
성공 조건은 빈 이메일·잘못된 형식·정상 입력에 대한 테스트 3개가 통과하는 것이다.
DB 스키마, 배포 설정, 의존성 업그레이드는 범위 밖이다.
범위가 작으면 에이전트가 똑똑해질 필요도 줄어듭니다. 실패해도 되돌릴 파일이 적고, 사람이 diff를 읽는 비용도 작습니다.
두 번째 경계 — 컨텍스트
에이전트는 저장소의 모든 파일을 이해하고 있는 팀원이 아닙니다. 필요한 규칙과 예시를 명시적으로 제공해야 합니다. Cursor는 프로젝트 규칙을 .cursor/rules에 저장할 수 있고, 간단한 프로젝트 지침에는 AGENTS.md를 사용할 수 있다고 설명합니다. CLI도 프로젝트의 AGENTS.md와 규칙 파일을 읽습니다.
다만 규칙 파일을 길게 만든다고 컨텍스트 문제가 해결되지는 않습니다. 저는 다음 네 가지를 먼저 적는 편입니다.
# AGENTS.md
## Goal
- Make the smallest change that satisfies the user request.
## Before editing
- Read the relevant module and its tests.
- State the files you plan to change.
## Verification
- Run the narrowest relevant test first.
- Report failures; do not hide or bypass them.
## Boundaries
- Do not change secrets, production data, or deployment settings.
- Do not add dependencies without explaining why.
- Stop and ask when the requested behavior conflicts with the existing architecture.
짧은 규칙은 모든 상황을 예측하려는 문서가 아닙니다. 에이전트가 매번 놓치기 쉬운 결정만 고정하는 체크리스트에 가깝습니다.
세 번째 경계 — 권한
규칙은 에이전트에게 “하지 말라”고 말하는 장치이지, 운영체제 수준의 접근 제어가 아닙니다. Cursor 문서도 규칙이 유일한 보안 통제가 되어서는 안 된다고 명시합니다.
실무에서는 다음을 분리해야 합니다.
- 코드 수정 권한과 운영 환경 접근 권한
- 초안 생성 권한과 실제 발행 권한
- 테스트용 자격 증명과 프로덕션 시크릿
- 읽기 전용 조사와 외부 시스템에 쓰는 작업
이 경계가 있으면 에이전트가 초안을 만들고 API를 호출할 수 있어도, 데이터베이스에 직접 접속하거나 게시 상태를 바꾸지는 못하게 할 수 있습니다. 자율성을 없애는 것이 아니라 사고 반경을 줄이는 방식입니다.
네 번째 경계 — 검증
“에이전트가 완료했다고 말했다”는 검증이 아닙니다. 완료를 관찰 가능한 증거로 바꿔야 합니다.
목표 정의
↓
관련 파일 읽기
↓
작은 변경
↓
테스트·린트 실행
↓
diff와 부작용 검토
↓
완료 보고 또는 중단
여기서 중요한 것은 테스트를 마지막 장식으로 두지 않는 것입니다. 테스트가 없으면 에이전트에게 테스트를 먼저 추가하게 하거나, 최소한 수동 검증 절차를 완료 조건에 넣어야 합니다. 실패한 테스트를 “환경 문제”라고 뭉개지 말고, 무엇이 실패했고 다음 사람이 어떤 판단을 해야 하는지 남겨야 합니다.
Cursor에서 실제로 쓰는 한 사이클
저장소 작업은 다음 순서가 안정적입니다.
- Plan: 에이전트에게 먼저 변경 파일과 완료 조건만 제안하게 합니다.
- Read: 관련 구현과 테스트를 읽게 합니다. 이때 새 파일을 바로 만들지 않습니다.
- Edit: 한 번에 하나의 작은 슬라이스를 수정합니다.
- Verify: 좁은 테스트부터 실행하고, 통과하면 전체 검사로 넓힙니다.
- Review: diff를 사람이 읽고, 요청하지 않은 변경을 제거합니다.
- Stop: 조건을 만족하면 더 개선하려고 범위를 넓히지 않습니다.
특히 마지막 단계가 어렵습니다. 에이전트는 “조금 더 개선할 수 있는” 이유를 잘 찾습니다. 하지만 운영 가능한 자동화에서 좋은 결과는 가장 많은 파일을 바꾼 결과가 아니라, 필요한 결과를 가장 작은 변경으로 만든 결과입니다.
시니어 엔지니어의 관점
AI 에이전트를 잘 쓰는 팀은 에이전트를 믿어서 검토를 생략하는 팀이 아닙니다. 에이전트가 빠르게 만든 변경을 사람이 저렴하게 검증할 수 있도록 시스템을 설계한 팀입니다.
그래서 저는 자율성보다 복구 가능성을 먼저 봅니다. 변경이 작고, diff가 읽히고, 테스트가 있으며, 시크릿과 발행 권한이 분리되어 있다면 에이전트가 한 번 틀려도 다음 시도에서 회복할 수 있습니다. 반대로 거대한 프롬프트 하나로 코드·DB·배포를 모두 건드리면, 성공했을 때조차 무엇이 실제로 바뀌었는지 설명하기 어렵습니다.
FAQ
Q. AGENTS.md 하나면 충분한가요?
A. 작은 저장소나 입문 단계에는 충분할 수 있습니다. 영역별 규칙이 많아지면 .cursor/rules로 나누되, 보안 통제의 대체물로 사용하면 안 됩니다.
Q. 모든 작업을 먼저 계획하게 해야 하나요?
A. 한 줄짜리 수정에는 과합니다. 여러 파일, 데이터 변경, 외부 API가 관련될 때 계획과 완료 조건의 가치가 커집니다.
Q. 에이전트에게 테스트 실행 권한을 줘도 되나요?
A. 저장소와 실행 환경에 맞춰 판단해야 합니다. 테스트 실행과 배포·프로덕션 데이터 변경은 같은 권한으로 취급하지 않는 것이 안전합니다.
Q. 가장 먼저 적용할 한 가지는 무엇인가요?
A. 다음 작업의 성공 조건과 변경 허용 범위를 한 문장씩 적어 보세요. 좋은 경계는 좋은 모델보다 먼저 효과가 나타납니다.
마무리
에이전트는 코드를 대신 타이핑하는 도구에서, 계획하고 실행하고 관찰하는 작업 파트너로 바뀌고 있습니다. 그만큼 중요한 것은 “얼마나 많이 맡길 수 있는가”가 아니라 “맡긴 일을 어디서 멈추고 어떻게 확인할 것인가”입니다.
다음 Cursor 작업에서 AGENTS.md에 목표·범위·검증·중단 조건 네 줄만 먼저 적어 보세요. 에이전트의 능력을 시험하는 가장 현실적인 방법은 더 큰 일을 시키는 것이 아니라, 작은 일을 다시 재현 가능하게 만드는 것입니다.