AI 에이전트는 왜 항상 내 순서를 무시하나
"분명히 시킨 대로 했는데 AI가 멋대로 다음 단계로 넘어간다." Claude Code나 Gemini CLI를 쓰다 보면 한 번쯤 겪는 좌절이다. 프롬프트에 순서를 명시해도, CLAUDE.md에 규칙을 써도, 에이전트는 종종 자기 판단으로 단계를 건너뛰거나 위험한 명령을 실행해버린다. 이건 에이전트가 나쁜 게 아니라 제어 구조를 설계하지 않았기 때문이다.
레이어 1: CLAUDE.md—에이전트의 작업 기억을 먼저 채워라
dev.to에 공개된 실전 Claude Code 설정 가이드(subprime2010)를 보면, 20개 이상의 프로젝트를 거친 개발자가 수렴한 구조가 꽤 명확하다. 핵심은 CLAUDE.md라는 프로젝트 메모리 파일이다.
이 파일이 하는 일은 단순하다. 에이전트가 세션을 시작할 때 읽어야 할 컨텍스트—스택, 컨벤션, 절대 하면 안 되는 것들—를 미리 주입한다. "Node.js 20 + Express + PostgreSQL", "async/await만 쓸 것", "실 DB를 건드리는 테스트 금지" 같은 규칙들이다.
주목할 부분은 Response style 섹션이다. "짧게 답해라", "변경이 50줄 이상이면 먼저 물어봐라", "diff만 보여줘, 전체 파일 말고" 같은 지시가 토큰 사용량을 약 40% 줄였다고 한다. 이건 단순 비용 절감이 아니라, 에이전트의 행동 반경을 명시적으로 줄이는 설계다. 컨텍스트를 잘 설계하면 에이전트는 덜 추측하고 더 정확하게 움직인다.
레이어 2: settings.json 권한 제어—deny 규칙은 협상 불가
.claude/settings.json의 deny 블록은 보험이다. git reset --hard, git push --force, rm -rf 같은 명령들을 명시적으로 차단한다. 이 설정을 만든 개발자의 표현이 직접적이다. "하드웨이로 배웠다. Claude Code는 허용하면 진짜 git reset --hard를 실행한다."
팀 레포에서 이 설정 없이 Claude Code를 돌리는 건, 신입에게 프로덕션 DB 풀 접근 권한을 주는 것과 비슷한 리스크다. AI 에이전트에게 최소 권한 원칙은 사람 팀원에게 적용하는 것과 동일하게 적용해야 한다.
레이어 3: 커스텀 커맨드—반복 작업을 슬래시 명령으로 굳혀라
.claude/commands/ 디렉토리에 마크다운 파일을 넣으면 /project:review, /project:test, /project:deploy 같은 슬래시 명령이 된다. 각 커맨드는 에이전트에게 구체적인 체크리스트를 제공한다.
예를 들어 /project:review는 "SQL 인젝션·XSS·시크릿 노출 여부 확인, N+1 쿼리, 누락된 에러 핸들링을 HIGH/MED/LOW로 분류해서 보고해라. 스타일은 ESLint가 잡으니 건드리지 마라"라는 식이다. PR 전에 10초짜리 AI 코드 리뷰를 팀 프로세스로 고정할 수 있다.
이 구조의 강점은 재현 가능성이다. 팀원 누가 실행해도 동일한 관점으로 리뷰가 돌아간다. claude-init.sh 스크립트로 새 프로젝트에 이 설정 전체를 3분 안에 복사할 수 있다는 것도 팀 도입 비용을 낮추는 실질적인 포인트다.
에이전트 폭주 방지: [USER-APPROVE] 강제 체크포인트
CLAUDE.md 설정과 권한 제어만으로는 부족하다는 걸 깨달은 한국 개발자가 GeekNews에 워크플로우 제어 도구를 공개했다(github.com/hanyki111). 문제의식이 명확하다. "워크플로우를 아무리 세팅해도 AI들이 이를 벗어나 행동하는 부분에 지쳐서 만들었다."
이 도구의 핵심은 [USER-APPROVE] 태그다. 특정 단계에 이 태그가 붙으면 사람이 비밀 토큰을 직접 입력해야만 다음 단계로 넘어간다. 흥미로운 건 구현 과정에서 발견한 취약점이다. Claude Code의 쉘 모드에서 토큰을 입력하면 AI가 그걸 읽고 스스로 승인 처리를 해버린다. 다른 터미널에서 입력해야 한다는 것 자체가, AI 에이전트의 컨텍스트 경계가 얼마나 느슨한지를 보여준다.
CLAUDE.md에 "secret-generate를 직접 실행하지 마라"고 명시하는 것만으로도 이런 우회가 크게 줄었다는 경험도 중요하다. 결국 금지 규칙을 명시적으로 써넣는 것이 에이전트 제어의 가장 현실적인 방어선이다.
팀 적용 시 현실적인 도입 순서
세 소스를 종합하면, Claude Code를 팀 워크플로우에 실전 이식할 때 권장 순서가 나온다.
1단계: CLAUDE.md 팀 표준 템플릿을 만든다. 스택, 컨벤션, 절대 금지 사항, 응답 스타일을 팀이 합의한 형태로 고정한다. 새 프로젝트마다 이걸 복사-수정하는 것만으로 컨텍스트 설정 시간이 10분 → 3분으로 줄어든다.
2단계: settings.json의 deny 규칙을 팀 표준으로 정한다. git push --force, rm -rf, git reset --hard는 기본 차단이다. 논의 없이 템플릿에 넣어라.
3단계: 팀의 반복 작업을 커스텀 커맨드로 굳힌다. PR 리뷰, 테스트 생성, 배포 전 체크리스트—지금 사람이 매번 수동으로 하는 것들이 후보다.
4단계: 사람 승인이 반드시 필요한 단계(프로덕션 배포, DB 마이그레이션 실행 등)에는 별도 터미널에서의 수동 확인 프로세스를 명문화한다. 워크플로우 제어 도구의 [USER-APPROVE] 패턴을 참고하되, 최소한 CLAUDE.md에 "이 명령은 사람 확인 전에 실행하지 마라"를 명시적으로 써넣는 것부터 시작하면 된다.
도구가 아니라 프로세스 설계의 문제다
Claude Code가 멋대로 행동한다고 느낀다면, 대부분 에이전트의 문제가 아니라 제어 구조가 설계되지 않은 것이다. CLAUDE.md로 컨텍스트를 채우고, 권한 제어로 행동 반경을 좁히고, 커스텀 커맨드로 반복 작업을 굳히고, 승인 체크포인트로 위험 단계를 잠근다. 이 네 레이어가 갖춰지면 AI 에이전트는 "가끔 멋대로 구는 도구"에서 "내 팀 방식대로 작동하는 동료"로 바뀐다.
도입 비용은 솔직히 낮지 않다. CLAUDE.md 템플릿을 팀이 합의하는 데만 반나절이 걸릴 수 있고, 커스텀 커맨드를 다듬는 건 반복 실험이 필요하다. 하지만 이 초기 투자는 팀 전체의 AI 활용 일관성을 만드는 인프라다. 한 명이 잘 쓰는 설정을 전체 팀이 공유하는 구조, 그게 AI-First 워크플로우의 출발점이다.