AI 코딩 에이전트 도입 논의가 대부분 '신뢰할 수 있냐', '자동화 수위를 어디까지 열 거냐' 같은 추상적 설계 질문에서 맴돈다. 현장에서 내일 당장 실행해야 하는 팀 입장에서 그 질문들은 중요하지만 충분하지 않다. 에이전트가 실제로 코드를 생성하는 순간, 세 가지 실무 문제가 동시에 터진다. 컨텍스트 문서가 이미 망가져 있고, 생성된 코드의 책임 소재가 흐릿해지고, 토큰 비용이 PR 단위로 눈에 보이지 않는다. 이 세 가지를 순서대로 짚는다.
1. CLAUDE.md가 틀려 있다면, 에이전트는 자신 있게 깨진 코드를 짠다
dev.to의 엔지니어 Hash가 공유한 사례는 팀 대부분이 외면하는 불편한 현실을 드러낸다. 그가 실제 코드베이스를 감사한 결과, 에이전트 문서(CLAUDE.md, Skills, Agents)가 자신 있게 틀려 있었다. CSS 모듈 패턴은 빌드 설정과 맞지 않는 클래스명을 생성하고, 테스트 템플릿의 목(mock)은 두 번째 테스트부터 조용히 죽어 있었다. 문서가 완결돼 보일수록, 에이전트는 더 확신을 갖고 깨진 코드를 양산한다. 그리고 그 한 번의 실수가 수천 토큰짜리 디버그 루프로 돌아온다.
해결책은 생각보다 단순하지만 실천되는 경우가 드물다. '하나의 사실, 하나의 파일' 원칙이다. CLAUDE.md는 모든 편집에 적용되는 규칙 3줄 이내와 링크만 담는다. 깊은 패턴은 Skills 파일에 살고, Agents는 워크플로우와 완료 기준만 정의하며, 절대 생략할 수 없는 규칙은 Hook으로 코드에 박아 넣는다. 문서의 모든 예제는 실제 코드베이스와 grep으로 대조 검증해야 하고, 서브에이전트에게 문서만 줬을 때 올바른 코드를 짜는지 '검색 테스트'를 돌려야 한다. 문서를 위키가 아닌 로딩 시멘틱이 있는 시스템으로 다루는 순간, 에이전트의 컨텍스트 품질이 바뀐다.
2. AI가 썼어도, 그 코드의 소유권은 오히려 더 무거워졌다
에이전트가 PR 대부분을 작성하는 경험이 쌓이면, 슬그머니 퍼지는 생각이 있다. '에이전트가 썼으니까 내 책임이 조금 줄지 않았나.' dev.to 필자 Dip의 글은 이 심리가 정확히 반대 방향이라고 지적한다. 에이전트는 파일 단위로 유효한 SQL을 짜지만, 우리 제품의 모든 테이블이 멀티테넌트라는 사실은 모른다. 지난해 팀이 특정 라이브러리를 쓰지 않기로 한 결정은 Slack 스레드에 묻혀 있다. 에이전트는 코드가 그 자체로 올바른지는 판단할 수 있어도, 이 시스템에서 올바른지는 판단할 수 없다.
'두 번째 에이전트가 리뷰하면 괜찮지 않나'는 발상도 함정이다. 두 모델이 동의한다고 책임 소재가 생기지는 않는다. 새벽 2시에 프로덕션이 터졌을 때 포스트모템에는 'AI가 했습니다' 칸이 없다. 코드가 더 빠르게 흐를수록, 그 코드에 이름을 올리는 사람의 판단 부담은 줄지 않고 오히려 늘어난다. 에이전트 도입 이후 개발자의 핵심 역할은 '이 코드가 우리 시스템의 맥락에서 올바른가'를 판단하는 것으로 이동한다. 이 역할을 명시적으로 정의하지 않은 팀은, 에이전트가 빠르게 만들어낸 코드 위에 책임의 공백을 함께 만들게 된다.
3. 토큰 비용은 소스코드에 살고, PR 단계에서 잡아야 한다
에이전트를 실제 운영에 붙이면 비용 문제는 반드시 터진다. dev.to 필자 wartzarbee의 사례가 단적이다. 에이전트를 타이머에 걸어 놓았더니 하룻밤 사이 1억 3600만 토큰을 태웠다. 극단적인 사례지만, 일상적 형태는 조용하다. 시스템 프롬프트가 200토큰 늘고, 컨텍스트 윈도우 트리밍이 멈추고, 새 툴 설명이 800단어짜리로 달린다. 코드 리뷰에서 diff는 깔끔해 보인다. 토큰은 보이지 않는다.
해결책은 .github/workflows/cost-guardrail.yml 파일 하나다. GitHub Action으로 PR 기준 브랜치 대비 토큰 증가율을 계산하고, 임계값(예: 20%)을 넘으면 빌드를 차단하며, 어느 파일이 원인인지 PR 코멘트로 명시한다. 'system_prompt.txt가 534토큰 늘었습니다'는 리뷰어가 그 자리에서 행동할 수 있는 정보다. 청구서에서 발견하는 것과 차원이 다르다. 처음에는 threshold-pct: 0으로 리포트 모드만 켜두고 일주일간 실제 PR의 토큰 패턴을 관찰한 뒤 임계값을 설정하는 것이 현실적인 도입 순서다.
세 가지를 순서대로 설계하는 이유
컨텍스트 문서 검증 → 코드 소유권 재정의 → 비용 게이트는 단순한 체크리스트가 아니라 의존 관계가 있다. 문서가 틀려 있으면 에이전트가 생성하는 코드 자체가 오염되고, 그 코드에 이름을 올리는 사람이 책임 구조를 인식하지 못하면 리뷰가 형식화되며, 비용을 PR 단계에서 가시화하지 않으면 프롬프트 최적화 동기 자체가 생기지 않는다. 세 가지를 동시에 설계하지 않으면 어느 하나가 빠진 자리에서 반드시 문제가 생긴다.
AI 코딩 에이전트는 도입 결정 이후가 더 어렵다. 에이전트가 팀 워크플로우 안에서 예측 가능하게 작동하게 만드는 것, 그 구조를 설계하는 것이 지금 테크 리드에게 실제로 주어진 과제다. 도구의 가능성에 낙관적이되, 팀이 치러야 할 도입 비용에는 냉정해야 한다.