AI 에이전트에게 절대 맡겨서는 안 되는 것과 제가 프로젝트에서 사용 중인 AGENTS.md 규칙

※ 이 기사의 일본어에는 약간 부자연스러운 부분이 있을 수 있습니다. AI의 언어 지원을 활용하여 작성되었습니다.

• 서론
• 권한 매트릭스 (Permission Matrix): 언제 에이전트에게 맡기고, 언제 인간이 리뷰할 것인가
• 리스크 레벨별 실례
• AI 에이전트에게 절대 맡겨서는 안 되는 6가지
• AGENTS.md: AI와의 계약서
• Two-Agent Loop: 한 명이 쓰고, 다른 한 명이 리뷰한다
• Final Report: 에이전트에게 책임을 지운다
• 요약
• 마치며

이 기사는 AI 에이전트를 개발에 활용하고 있는 분, 또는 도입을 검토 중인 엔지니어와 팀 리더를 대상으로 합니다.

저자에 대하여: 저는 현재 일본 시장을 대상으로 시스템 개발을 수행하는 TOMOSIA VIETNAM에서 엔지니어로 근무하고 있습니다. 이 기사에서는 실제 프로젝트에서 경험한 실패와 그로부터 배운 'AI 에이전트와 올바르게 협업하는 방법'을 공유합니다.

이 기사의 목적:

• AI 에이전트에게 어떤 태스크를 맡기고, 어떤 태스크를 인간이 관리해야 하는지 명확히 한다
• AGENTS.md 및 blocked_commands.md의 구체적인 템플릿을 제공한다
• 에이전트를 안전하고 효과적으로 운용하기 위한 프랙티스 (Practices)를 소개한다

상정 독자:

• AI 에이전트를 사용한 개발에 관심이 있는 엔지니어
• 이미 사용 중이지만 '가끔 이상한 행동을 한다'고 느끼는 분
• 팀에서 AI 에이전트 운용 규칙을 정하고 싶은 리더

당신은 AI 에이전트에게 코드를 작성하게 하고 있습니까?

훌륭합니다!

하지만 저는 에이전트가 지시대로 정확하게 움직인 탓에, 1시간을 허비한 적이 있습니다.

실화입니다: 저는 에이전트에게 "리포지토리 (Repository)를 정리하고, 사용하지 않는 파일을 삭제해줘"라고 지시했습니다. 그러자 에이전트는 '사용하지 않는다'를 광의로 해석하여, 배포 스크립트 (Deploy Script)가 아직 참조하고 있는 설정 디렉토리까지 삭제해 버렸습니다. 해당 설정 파일은 .gitignore에 지정되어 있었기 때문에 Git의 관리 하에 있지 않았습니다.

결과: 삭제된 파일을 복구하는 데 1시간이 걸렸습니다.

에이전트는 잘못이 없습니다. 단지 아무도 '어디서 멈춰야 하는지'를 알려주지 않았을 뿐입니다.

교훈: 어떤 태스크를 AI에게 맡겨야 할지 파악하는 것. 이것이 AI 에이전트와 일할 때 가장 중요한 기술입니다.

이하, 저의 실천 경험을 자세히 공유합니다.

태스크 종류	에이전트 자율도	인간의 리뷰	이유 / 리스크
작은 함수의 리팩토링 (Refactoring)	높음	불필요 또는 경미	쉽게 되돌리기 (Revert) 가능. 리스크 낮음.
유닛 테스트 (Unit Test) 추가	높음	통상 불필요	CI가 즉시 감지함.
프론트엔드 버그 수정 (UI)	중~높음	육안 확인 필요	로직 버그는 보이지만, UI의 미묘한 깨짐은 인간의 눈이 필요함.
API 동작 변경	중간	필요	클라이언트에 영향. 계약 (Contract) 리뷰 필수.
의존성 (Dependency) 추가	중간	필요	보안 취약점이나 라이선스 문제 가능성.
데이터베이스 마이그레이션 (Database Migration)	낮음	필수	잘못된 마이그레이션은 데이터 손실이나 스키마 파손을 일으킴.
인증·보안 로직 (Authentication/Security Logic)	낮음	필수	버그는 유닛 테스트에서 발견되지 않고, 인시던트 (Incident) 보고를 통해 발각됨 (수개월 뒤가 될 수도 있음).
인프라 / 클라우드 (Infrastructure / Cloud (IAM, k8s, terraform))	매우 낮음	필수	권한 실수는 조용히 시스템을 파괴함. 추적이 매우 어려움.
운영 환경으로의 배포 (Deployment to Production)	없음 (수동만)	필수 + 수동 확인	에이전트는 진행 중인 인시던트나 유지보수 스케줄을 알지 못함.

심플한 규칙: 되돌릴 수 없는 작업에는 반드시 인간의 체크포인트 (Checkpoint)를 둘 것.

레벨	작업 예시	에이전트가 실수했을 때의 영향	되돌릴 수 있는가?
고자율	변수명 리팩터링 (Refactoring)	빌드 에러, CI가 즉시 감지, 5분 내 수정 가능	✅ 쉬움
중	API 응답 형식 변경	API 호출 측에서 에러가 발생하지만, 운영 환경 배포 전이라면 문제없음	⚠️ 커밋 Revert 가능
저	데이터베이스 컬럼 삭제	데이터 손실. 백업으로부터 복구하는 데 수 시간~수 일 소요	❌ 매우 어려움
자율성 없음	새벽 3시 운영 환경 배포	아무도 알아차리지 못함, 고객에게 영향, 온콜 (On-call) 담당자 부재	❌ 매우 어려움

rm -rf
, git clean -fd
, git reset --hard

• 에이전트는 "clean up"이라는 단어를 보면, 리팩터링 (Refactoring) 도중에 git clean -fd를 실행할 수도 있습니다. 커밋되지 않은 작업이 모두 삭제됩니다.

WHERE 절이 없는 DELETE, DROP TABLE, TRUNCATE, 운영 데이터에 접근하는 마이그레이션 (Migration) -

• WHERE 절의 오타 하나로 테이블 전체가 삭제될 수 있습니다. 에이전트는 확인하지 않습니다.

terraform apply, kubectl delete, aws iam * -

• 권한 변경은 특히 위험합니다. 무언가가 망가질 때까지 조용히 진행됩니다.

• 코드가 에이전트에 의해 작성되더라도, 배포 결정은 당신이 내려야 합니다.

• 에이전트는 "진행 중인 인시던트 (Incident)가 있는지" 또는 "유지보수 예정이 있는지" 알지 못합니다.

• 인증 플로우 (Authentication flow), 인가 규칙 (Authorization rule), 토큰 처리, 세션 관리

• 이런 종류의 버그는 유닛 테스트 (Unit test)로는 발견되지 않습니다. 인시던트 리포트 (Incident report)를 통해 발각되며, 때로는 몇 달 뒤에 나타나기도 합니다.

• 에이전트에게 이러한 파일의 읽기나 쓰기를 허용해서는 안 됩니다.

AGENTS.md 파일을 리포지토리 (Repository) 루트에 배치합니다. 이 파일은 에이전트에게 "프로젝트의 목적", "실행 방법", "건드려서는 안 되는 것"을 전달합니다.

# AGENTS.md
## Project
[프로젝트에 대한 간단한 설명과 기술 스택]
...
```bash
npm install # 또는 pip install -r requirements.txt
npm run dev
npm test
npm run lint

• 변경을 최소한으로 유지할 것. 관련 없는 코드를 리팩터링 (Refactoring) 하지 말 것.
• 동작을 변경한 경우, 테스트를 추가하거나 업데이트할 것.
  ...

### blocked_commands.md (실행 전 승인 필요)
```markdown
# blocked_commands.md
## 파괴적인 파일 작업
- rm -rf
...

중급 이상의 복잡성을 가진 작업에서는, 하나의 에이전트가 아니라 두 개를 사용합니다.

프롬프트 (Prompt):

당신은 시니어 엔지니어입니다. 작업: [작업 설명]
Context: [AGENTS.md로의 링크]
규칙:
...

프롬프트 (Prompt):

당신은 코드 리뷰어 (Code reviewer)입니다. 구현에 대한 애착이 없습니다.
이 diff를 리뷰해 주세요: [diff를 붙여넣기]
체크 항목:
...

리뷰어 에이전트에게는 코드에 대한 "자아"가 없습니다. 구현자가 놓친 버그나 엣지 케이스 (Edge case)를 찾아냅니다. 이것이 바로 **자동화된 코드 리뷰 (Automated code review)**입니다.

각 에이전트 작업 후에, 최종 리포트를 필수 사항으로 합니다:

• 변경 개요
• 변경한 파일
• 실행한 테스트와 결과
• 리스크 / 전제 조건
• 완료되지 않은 사항

에이전트가 명확하게 요약하지 못한다면 → 작업이 깔끔하게 정리되지 않았다는 증거입니다.

또한, 이러한 리포트들은 축적되어 자동화된 문서가 됩니다. 일주일 후에 버그가 발생했을 때, 무엇이 변경되었고 왜 변경되었는지를 정확하게 추적(Trace)할 수 있습니다.

AI 에이전트는 확실히 당신의 생산성을 향상시킵니다. 하지만, 가장 많이 활용하고 있는 사람들은 다음과 같은 "지루한 작업"을 제대로 수행하고 있는 사람들입니다:

• AGENTS.md 작성 - 권한 레벨 설계
• blocked_commands.md 구축 - Two-Agent Loop 설정

에이전트는 명확한 지시가 있을 때 가장 잘 작동합니다. 그 부분은 당신의 책임입니다.

여기까지 읽어주셔서 진심으로 감사합니다.

만약 **「시스템 개발을 의뢰하고 싶다」 「기술적인 상담을 하고 싶다」 「AI를 활용한 과제 해결 아이디어가 있다」**와 같은 고민이 있으시다면, 꼭 저희 TOMOSIA VIETNAM에 상담해 주세요.

• 💻 소프트웨어 수탁 개발 (Web · 앱 · 시스템) - 🤖 AI 솔루션 (챗봇, 이미지 처리, LLM 응용) - 📱 모바일 앱 개발 (iOS / Android) - 🔌 Fintech / IoT 개발 - 🔧 브릿지 SE (BrSE) 지원 (일본어 커뮤니케이션을 원활하게)

• ISO/IEC 27001 (정보 보안) 인증 취득 완료 – 안심하고 맡기실 수 있습니다 -

• 일본어 대응 팀 – 일본의 문화와 비즈니스 관습을 이해한 멤버가 직접 대응 -

• 「Win-Win, Happy Together」 문화 – 장기적인 파트너십을 소중히 여깁니다

🔗 공식 사이트: tomosia.com

우선 가볍게 한마디 연락해 주세요. 저희와 함께, 「베트남의 지혜」로 세계에 도전해 보지 않겠습니까?