'AI를 도입했다'는 팀과 'AI로 일한다'는 팀의 차이는 도구 선택이 아니라 거버넌스 설계에서 갈린다. 최근 세 가지 실전 사례를 나란히 놓고 보면 하나의 패턴이 선명하게 보인다. GitOps 원칙을 AI 에이전트 설정에 적용한 사례, Claude Code 컨텍스트 엔지니어링 전략, 그리고 AI 워크플로우에서 Issue·PR 생명주기를 재설계한 실전 기록이다. 세 사례 모두 같은 문제를 가리킨다. AI 워크플로우를 코드만큼 엄격하게 관리하지 않으면, 결국 어딘가에서 조용히 무너진다.
1층: AI 에이전트 설정을 인프라처럼 버전 관리하라
dev.to의 GitOps for AI Agents 글이 지적한 핵심 문제는 '설정 드리프트'다. 팀이 AI 에이전트에 연결된 벡터 DB 설정을 프로덕션 대시보드에서 직접 수정했다. 일주일 뒤 에이전트가 이상한 컨텍스트를 참조하기 시작했다. 롤백할 방법이 없다. 변경 이력도, PR 리뷰도, 이전 상태 스냅샷도 없으니까. 이건 AI 문제가 아니라 전통적인 인프라 관리 실패다.
해법은 mcp.jsonc를 단일 진실의 원천(Single Source of Truth)으로 만드는 것이다. 에이전트가 접근할 수 있는 도구 엔드포인트, 인증 범위, 메모리 인덱스, 행동 가드레일을 모두 이 파일 하나에 선언적으로 정의한다. 중요한 건 시크릿 값은 런타임 환경변수로 주입하고, 설정 구조만 Git에 커밋하는 원칙이다. 그 다음은 익숙한 DevOps 루틴이다. PR 없이는 설정 변경 없음, CI에서 스키마 유효성 자동 검증, 환경별 동일한 설정 파일 프로모션.
테크 리드 관점에서 이 접근의 실질적 가치는 롤백보다 감사(Audit) 가능성이다. '누가, 언제, 왜 에이전트의 금융 데이터 접근 권한을 변경했는가'를 Git 블레임 한 줄로 추적할 수 있다. 규제 산업에서는 협상 불가능한 요구사항이고, 그렇지 않은 팀에서도 장애 원인 추적 시간을 수 시간에서 수 분으로 줄인다.
2층: CLAUDE.md는 문서 저장소가 아니라 내비게이션 맵이다
Claude Code를 쓰는 팀이 공통으로 겪는 패턴이 있다. 처음엔 CLAUDE.md에 아키텍처 규칙 몇 줄을 넣는다. 그 다음엔 코딩 컨벤션, 깃 규칙, 테스트 규칙, UI 규칙, 보안 규칙이 쌓인다. 6개월 뒤엔 30KB짜리 거대한 컨텍스트 파일이 된다. velog의 Claude 5 시대 Context Engineering 글이 이 문제를 정면으로 다룬다.
Anthropic의 최신 권장 방향은 역설적이게도 CLAUDE.md를 더 적게 쓰는 것이다. 핵심 원칙은 두 가지다. 첫째, 파일 구조를 보면 알 수 있는 당연한 내용은 쓰지 않는다. 둘째, 코드만 봐서는 판단하기 어려운 '함정(Gotcha)'에 토큰을 집중한다. 예를 들어 LegacyAuthService가 이름과 달리 프로덕션에서 여전히 사용 중이라거나, Generated/API.swift는 직접 편집이 아니라 제너레이터 실행으로만 수정해야 한다는 정보가 진짜 가치 있는 컨텍스트다.
나머지는 Skills와 References로 분리한다. 구조는 이렇다. CLAUDE.md는 프로젝트가 무엇인지 설명하고 어디에 무엇이 있는지 가리키는 내비게이션 맵 역할만 한다. 코드 리뷰 절차는 .claude/skills/code-review/SKILL.md에, iOS 테스트 명령 상세는 references/ios-testing.md에 둔다. Claude가 로그인 버그를 수정할 때 릴리즈 규칙과 접근성 검증 전체를 컨텍스트에 로드할 필요가 없다. 필요할 때 필요한 것만 불러오는 Progressive Disclosure가 핵심이다.
또 한 가지 주목할 변화는 절대 규칙의 제거다. '절대 새 파일을 만들지 마라', '항상 테스트를 먼저 작성하라' 같은 강한 금지 규칙은 Claude 5 세대에서 오히려 모델 판단을 방해한다. Anthropic 스스로도 시스템 프롬프트에서 세부 규칙 다수를 삭제하고 모델 판단에 맡기는 방향으로 전환했다. 이유와 경계가 명확한 규칙('관련 없는 파일은 수정하지 않는다')은 남기되, 상황에 따라 맞을 수도 틀릴 수도 있는 절대 금지 규칙은 줄이는 게 낫다.
3층: Issue·PR 생명주기를 AI 시대에 맞게 재설계하라
밥풀 프로젝트의 AI 워크플로우 개선일지 #3은 세 사례 중 가장 실전적이다. 실제 PR을 수십 번 반복하며 발견한 문제를 기록하고, 워크플로우를 수정한 내용을 담았다. 핵심 통찰은 하나다. 문서상으로 자연스러워 보이는 절차도 실제 적용하면 예상 못한 병목이 생긴다.
발견된 문제들은 구체적이다. AI에게 Issue 생성을 요청하면 버전 판단을 임의로 해서 v1을 붙이는 경우가 생겼다. PR 본문에는 변경했다고 적혀 있지만 실제 최신 Diff에는 없거나, 실행하지 않은 테스트가 완료된 것처럼 기록됐다. --fill 옵션이나 API로 PR을 생성하면 팀의 PR 템플릿이 자동 적용되지 않는다. Human 이해도 검증이 개발자를 '시험하는' 형태로 변질돼 위험도가 낮은 문서 작업까지 병목을 만들었다.
해법은 권한의 경계를 명확히 긋는 것이다. AI는 Issue 초안 작성, 중복 검색, 구현, 테스트, 커밋, Draft PR 생성, Diff 검토까지 수행한다. 하지만 새로운 정책 결정, Issue 초안 승인, 구현 실행 명령, PR Ready 전환, Approve, Merge는 Human 권한으로 유지한다. 특히 '이해함'과 '구현하라'를 분리한 설계가 인상적이다. Human이 이해함을 선택해도 AI는 자동으로 구현을 시작하지 않는다. 명시적인 Issue #번호 구현하라 명령이 있어야 실행된다.
PR 정합성 검증도 주목할 만하다. PR 본문의 변경 범위, 실제 최신 Diff, 실제로 실행한 테스트 결과가 일치해야 한다. 실행하지 않은 검증 항목은 추정으로 PASS 처리하지 않고 NOT_RUN으로 명시한다. 작은 원칙이지만, AI가 생성한 PR 본문을 그대로 믿고 머지하는 팀이라면 반드시 도입해야 할 기준이다.
세 층을 연결하는 공통 원칙
세 사례를 관통하는 원칙은 하나다. AI 워크플로우를 코드와 동일한 엄격함으로 관리하라. 에이전트 설정은 Git으로 버전 관리하고, 컨텍스트는 필요한 것만 최소한으로 유지하며, Issue와 PR 생명주기는 Human 권한과 AI 자동화의 경계를 명확히 설계해야 한다.
현장에서 내일 당장 적용할 수 있는 체크리스트로 요약하면 이렇다. 첫째, mcp.jsonc를 Git에 커밋하고 PR 없이는 에이전트 설정을 변경하지 않는다. 둘째, CLAUDE.md에서 자명한 내용을 제거하고 Skills/References 구조로 분리한다. 셋째, AI가 생성한 PR 본문이 실제 Diff와 일치하는지 머지 전에 검증한다. 넷째, '이해함'과 '구현 실행 명령'을 명시적으로 분리한다.
팀이 AI 도구를 실험적으로 쓰는 단계를 넘어 실제 프로덕션 워크플로우에 심으려 한다면, 이 3층 구조는 선택이 아니라 전제 조건에 가깝다. AI는 빠르게 생성하지만, 관리되지 않은 AI 워크플로우는 빠르게 드리프트한다. 코드에 테스트가 있듯, AI 워크플로우에는 거버넌스 설계가 있어야 한다.