AI 코딩 에이전트는 왜 자꾸 크게 만들까 — 과설계의 원인을 따라가 지침 파일에 브레이크를 걸기까지#
2026-11-22

값 하나 저장하는데 버전 테이블이 생겼다#
필자는 개발할 때 Claude Code와 Codex를 함께 씁니다. 두 도구를 함께 쓰는 방식은 메인 에이전트는 질문과 답만 본다에서 정리한 적이 있습니다. 그런데 요즘 들어 두 도구가 예전보다 훨씬 많은 것을 한꺼번에 구현하려 한다는 느낌을 자주 받았습니다.
예를 들면 이런 식입니다. 어떤 테이블에 값을 추가하고 수정할 수만 있으면 되는 기능을 맡겼습니다. 돌아온 결과물에는 버전 관리용 테이블이 하나 더 있었고, 두 테이블의 일관성을 지키려고 여러 데이터베이스 작업을 하나로 묶어, 전부 반영되거나 전부 취소되게 만드는 단위입니다. 예를 들어 값을 바꾸는 작업과 그 이력을 남기는 작업을 묶으면, 한쪽만 반영되는 일을 막을 수 있습니다. 데이터베이스 안에 저장해 두고 이름으로 불러 쓰는 SQL 묶음입니다. 여러 테이블을 한 번에 바꾸는 처리를 데이터베이스 쪽에 맡길 때 쓰지만, 로직이 애플리케이션 코드와 데이터베이스 두 곳으로 나뉘어 고칠 곳이 늘어납니다.
복잡하고 완벽한 구현이 늘 정답은 아닙니다. 상황에 따라 다릅니다. 스타트업이 막 시작하는 애플리케이션이라면 빠르게 만들고 자주 바꿀 수 있는 것이 중요합니다. 이미 많은 고객을 보유한 애플리케이션을 고칠 때는 안정성이 먼저입니다. 그런데 에이전트는 상황을 가리지 않고 후자를 정답으로 보고 가는 것 같았습니다.
필자만의 느낌은 아니었습니다. Anthropic은 공식 프롬프팅 가이드의 “Overeagerness”(지나친 의욕) 절에서, Claude Opus 4.5와 4.6이 “추가 파일을 만들고, 불필요한 추상화를 더하고, 요청하지 않은 유연성을 넣는 식으로 과설계하는 경향이 있다"고 적어 두었습니다. 이 경향을 줄이는 예시 프롬프트도 함께 실어 두었습니다. 모델을 만든 회사가 직접 인정하는 경향이라면, 쓰는 쪽에서 막을 장치를 마련하는 수밖에 없습니다.
에이전트가 크게 만드는 다섯 가지 이유#
막을 장치를 고르기 전에 왜 이런 일이 생기는지부터 따져 봤습니다. 아래 다섯 가지 중 첫째와, 셋째의 학습 데이터 이야기는 모델이 만들어지는 방식에 대한 필자의 추론입니다. 나머지는 사용하면서 관찰한 것입니다.
첫째, 부족하면 벌을 받고 과하면 벌을 거의 받지 않습니다. 코딩 에이전트는 테스트 통과나 리뷰 평가 같은 기준으로 정답을 직접 가르치는 대신, 모델이 낸 결과에 점수(보상)를 매기고 점수가 높은 쪽으로 행동을 조정해 가는 학습 방식입니다. 코딩 에이전트라면 테스트를 통과했는지, 리뷰에서 좋은 평가를 받았는지 같은 것이 점수가 될 수 있습니다.
둘째, 사람에게 있던 브레이크가 없습니다. 사람 개발자는 코드를 더 쓰면 시간이 들고 지치며, 나중에 그 코드를 유지보수하는 것도 본인입니다. 그래서 귀찮아서라도 “지금 필요 없는 건 만들지 않는다"는 원칙을 지켰습니다. 에이전트는 지치지 않고, 지금 쓰는 코드를 나중에 유지보수할 부담을 판단에 넣지도 않습니다. 다음 세션의 에이전트도 필요하면 그 코드를 찾아 읽지만, 그 비용은 쓰는 시점이 아니라 나중에 치러집니다. 늘어난 코드의 비용은 이후 그 코드를 다시 읽고 고쳐야 하는 사람과, 관련 작업을 할 때마다 그 코드까지 읽어야 하는 에이전트에게 돌아옵니다. 테이블 하나를 고칠 때마다 버전 테이블과 프로시저까지 함께 읽고 고쳐야 하니, 토큰 비용도 그만큼 계속 늘어납니다.
셋째, 제품이 어느 단계인지 알 길이 없습니다. “값을 저장하고 수정"이라는 요청만 보고는 사용자가 0명인지 10만 명인지 알 수 없습니다. 게다가 학습 데이터의 “모범 사례"는 대부분 성숙한 대형 시스템을 기준으로 쓰였습니다. 비어 있는 맥락은 자연스럽게 운영 서비스 수준으로 채워집니다.
넷째, 모호한 요청을 가장 완전한 해석으로 채웁니다. 에이전트는 “수정하면 이전 값이 사라지는데 괜찮을까?“라는 질문을 스스로 떠올립니다. 여기까지는 좋은 습관입니다. 문제는 그 질문을 사용자에게 묻지 않고 답까지 구현해 버린다는 점입니다. 최근 모델은 사람의 확인 없이 오래 일하도록 다듬어지고 있어서, 이 경향은 앞으로 더 강해질 수 있습니다.
다섯째, 리뷰 루프는 복잡도를 한 방향으로만 키웁니다. 계획 모드나 리뷰 에이전트, 다른 모델의 교차 검토를 거치면 “ 두 개 이상의 요청이 같은 데이터를 거의 동시에 다룰 때, 처리 순서에 따라 결과가 달라지는 문제입니다. 두 사람이 같은 값을 동시에 고치면 한쪽의 수정이 조용히 덮어써지는 경우가 대표적입니다.
사람이 거르는 방법은 고르지 않았다#
원인을 놓고 보니 손쉬운 대책이 두 가지 떠올랐습니다. 구현 전에 “새로 만들 테이블과 파일 목록"을 먼저 받아서 거르는 방법, 그리고 요청할 때 “이력 관리는 필요 없음"처럼 하지 않을 것을 함께 적는 방법입니다.
둘 다 효과는 있겠지만, 필자는 고르지 않았습니다. 결국 사람이 할 일이 늘어나는 방향이기 때문입니다. 불필요한 부분을 결과물에서 지우라고 하는 것은 지금도 할 수 있습니다. 필자가 원한 것은 애초에 그 방향으로 가지 않게 하는 것이었습니다. 요청할 때마다 사람이 무언가를 덧붙이지 않아도 에이전트가 먼저 알고 있어야 하는 정보라면, 매번 읽히는 지침 파일에 두는 것이 사실상 유일한 길입니다.
지침을 열어 보니 브레이크가 아니라 액셀이 있었다#
그래서 지금 쓰고 있는 지침 파일부터 열어 봤습니다. 회사에서 과설계 위험이 크다고 느낀 저장소는 백엔드, 프론트엔드, 업무 자동화 에이전트 세 곳이었습니다. 세 저장소와 이들을 묶는 작업 허브, 그리고 Claude Code와 Codex의 사용자 전역 지침까지 일곱 곳을 살폈습니다. 회사 작업 허브 구조는 고칠 줄 몰라서가 아니라 불편한 줄 몰라서에서 설명한 적이 있습니다.
결과는 예상보다 나빴습니다. 과설계를 막는 일반 원칙은 일곱 곳 어디에도 없었습니다. “이 프롬프트 파일은 기능이나 형식을 바꾼 뒤에도 예전 방식으로 쓰던 코드나 데이터가 계속 동작하게 하는 것입니다. 외부 사용자가 많을수록 중요하지만, 그만큼 옛 방식과 새 방식을 함께 유지하는 코드가 늘어납니다.
더 눈에 띈 것은 오히려 복잡도를 끌어올리는 요소들이었습니다.
- 문서의 어조. 세 저장소의 지침은 “
문제가 생기거나 판단이 애매할 때 ‘허용’이 아니라 ‘차단’ 쪽으로 동작하게 만드는 설계 원칙입니다. 권한 검사처럼 잘못 열리면 위험한 곳에 쓰는 보수적인 방식입니다.
”, “단일 진실 공급원”, “불변 조건”, “가드” 같은 단어와 설계 결정 문서 번호로 가득했습니다. 에이전트는 맥락의 어조를 따라갑니다. 이런 문서를 읽고 나면 화면 문구 하나를 고칠 때도 고위험 시스템을 다루듯 움직입니다. - 항상 읽히는 고위험 패턴. 업무 자동화 에이전트 저장소의 지침에는 “고객의 돈이 움직이는 설정을 바꿀 때는 같은 트랜잭션에서 이력 테이블에도 기록한다"는 규칙이 있었습니다. 그 영역에서는 맞는 결정입니다. 문제는 “이력이 없는 변경이 곧 우회 경로를 탐지하는 신호"라는 설득력 있는 근거가 함께 적혀 있고, 이 규칙을 그 영역에만 쓰라는 문장이 없다는 점이었습니다. 필자가 처음 겪은 버전 테이블 사례와 같은 모양의 패턴이, 모든 세션이 읽는 파일 한가운데 있었던 셈입니다.
- 새로 만들지 말지의 기준이 없는 레이어 규칙. 백엔드는 라우터, 서비스, Repository(데이터 접근 계층), 엔티티 순서의
코드를 역할별 층으로 나누고, 위층이 바로 아래층만 부르게 하는 설계 방식입니다. 요청을 받는 층, 업무 규칙을 처리하는 층, 데이터베이스를 다루는 층을 나누는 식입니다. 역할이 분명해지는 대신, 기능 하나를 더할 때 여러 층의 파일을 함께 만들게 됩니다.
를 지키라고 정해 두었습니다. 일관성을 위해 유지할 가치가 있는 규칙입니다. 하지만 기존 서비스에 메서드를 하나 더할지, 새 서비스를 만들지에 대한 기준이 없으니 단순한 기능도 파일 네 개로 시작하게 됩니다.
조사하다가 알게 된 사실이 하나 더 있습니다. 팀에서는 얼마 전 내부 운영 화면의 과설계를 감사하고 걷어 내는 작업을 이미 한 번 했습니다. 문제를 겪고 고치기까지 했는데, 그 교훈이 다음 작업의 에이전트가 읽는 지침에는 들어가지 않았던 것입니다.
“단순하게"가 아니라 전제를 사실로 막는다#
무엇을 막아야 하는지부터 정리했습니다. 필자가 겪었거나 지침을 보며 떠올린 과설계 유형은 대략 다섯 묶음입니다.
- 데이터 모델: 이력·버전 테이블,
행을 실제로 지우지 않고 ‘삭제됨’ 표시(예: 삭제 시각 컬럼)만 남기는 방식입니다. 실수로 지운 데이터를 되살릴 수 있지만, 그 뒤로는 모든 조회에 ‘삭제되지 않은 것만’ 조건을 붙여야 합니다.
, 프로시저로 묶은 다중 테이블 트랜잭션, 동시 수정을 막는 잠금, 미리 만드는 인덱스 - 코드 구조: 구현체가 하나뿐인 인터페이스,
객체를 만드는 방법이나 처리 방식을 나중에 갈아 끼울 수 있게 한 단계 감싸 두는 설계 기법입니다. 바꿔 끼울 구현이 여러 개일 때는 유용하지만, 구현이 하나뿐이면 감싸는 코드만 늘어납니다.
, 한 번만 쓰는 범용 유틸, 하드코딩해도 될 값의 설정화 - 방어 코드: 내부 호출마다 붙는 입력 검증, 재시도와
실패한 요청을 다시 시도할 때마다 기다리는 시간을 1초, 2초, 4초처럼 두 배씩 늘려 가는 방식입니다. 잠깐 불안정한 외부 서비스를 상대할 때 쓰는 기법인데, 실패할 일이 거의 없는 내부 호출에까지 붙이면 코드만 복잡해집니다.
, 실패를 숨기는 폴백, 옛 이름을 살려 두는 하위 호환 장치 - 운영: 캐시 레이어, 큐와 백그라운드 워커, 요청하지 않은 로깅과 메트릭
- 범위 확장: “수정"을 요청했는데 따라오는 삭제·일괄 수정·검색, 고치러 간 김에 하는 주변 리팩터링
Anthropic이 공식 가이드에 실어 둔 예시 프롬프트도 비슷한 목록입니다. “요청했거나 명백히 필요한 것만 바꾼다”, “가상의 미래 요구를 위해 설계하지 않는다”, “적절한 복잡도는 현재 작업에 필요한 최소한이다” 같은 문장이 들어 있습니다. 좋은 출발점입니다. 다만 그대로 가져다 쓰기에는 두 가지가 걸렸습니다.
첫째, “명백히 필요한 것"을 판단하는 주체가 여전히 에이전트라는 점입니다. 단계 정보가 없으면 에이전트는 운영 서비스 기준으로 필요성을 판단하고, 그 기준에서는 버전 테이블도 “명백히 필요한 것"이 될 수 있습니다. 에이전트는 자기 설계가 이미 적절하다고 여길 것이므로, “단순하게"라는 말만으로는 판단이 바뀌기 어렵다고 필자는 봤습니다.
둘째, 회사 서비스에서 모든 곳을 최소한으로 가면 위험하다는 점입니다. 돈이 움직이는 설정 변경이나 권한 판정까지 가볍게 다뤄서는 안 됩니다.
그래서 지침을 쓰는 방식을 바꿨습니다. 에이전트가 과설계의 명분으로 삼는 전제를 사실로 막는 것입니다. “두 명이 동시에 고치면?“이라는 명분은 “동시 편집은 사실상 없다"는 한 줄이 있으면 힘을 잃습니다.
이 방향으로 지침에 넣을 내용을 다섯 가지로 정리했습니다.
- 사실로 전제를 막습니다. 실사용자 규모, 동시 편집 가능성, 외부 API 소비자 유무, 데이터 규모처럼 에이전트가 명분으로 쓰는 전제를 저장소마다 적습니다. 예를 들어 개발 중인 서비스라면 “스키마와 API는 자유롭게 바꾼다"로 충분합니다. 라이브지만 사용자가 적은 크롬 확장이라면 “저장 형식을 바꿀 때만 기존 값을 읽을 수 있게 한다” 정도가 맞습니다. 확장 업데이트는 사용자에게 자동으로 배포되기 때문입니다.
- 금지 목록에 예외 조건을 답니다. “이력 테이블은 요청에 ‘이력’이나 ‘되돌리기’가 있을 때만"처럼 언제 허용되는지를 함께 적습니다.
- 출구를 줍니다. 필요해 보이면 구현하지 말고 응답 끝에 “추가 고려” 한 줄로 남기게 합니다. 응답은 어차피 사람이 읽으니 할 일이 늘지 않습니다. 이 출구가 없으면 에이전트는 걱정을 해소하려고 결국 구현해 버립니다.
- 줄이면 안 되는 영역을 적습니다. 인증·권한 판정, 비밀키, 돈이 움직이는 쓰기, 되돌릴 수 없는 사용자 데이터 손실은 단계와 상관없이 엄격하게 갑니다. 이 경계가 없으면 단순화 지침이 보안 구멍으로 번질 수 있습니다.
- 팀이 정한 검증 절차는 단순화 대상이 아니라고 적습니다. 회사 저장소에는 동료가 일부러 정해 둔 높은 테스트 커버리지 기준과, 커밋마다 작업 기록을 남기는 규칙이 있습니다. 이번 작업에서 이 규칙들은 건드리지 않았습니다. 바꾸려면 팀 합의가 필요한 일이기도 하지만, 더 큰 이유가 있습니다. “단순하게"라는 원칙이 테스트나 기록을 생략하는 근거로 쓰이면 안 되기 때문입니다. 이 원칙은 제품 코드의 범위에만 적용한다고 못 박아 두었습니다.
회사 서비스에는 여기에 비례 원칙을 더했습니다. 고객이 있는 운영 서비스이니 모든 곳을 가볍게 갈 수는 없습니다. 그래서 엄격하게 갈 구역을 명시하고 그 밖은 가볍게 가기로 했습니다. 엄격 구역은 돈이 움직이는 설정 변경, 권한 판정, 운영 데이터베이스 쓰기, 자격 증명입니다. 가벼운 구역은 화면 표시와 문구, 읽기 전용 조회 화면, 리포트 서식, 내부 도구입니다. 엄격 구역은 저장소마다 조금씩 달라서 각 저장소 지침에 따로 적습니다. 앞에서 문제로 짚은 이력 동시 기록 패턴에는 “이 패턴은 그 영역에만 쓰고 다른 테이블에 복제하지 않는다"는 문장을 덧붙이기로 했습니다.
전역 지침에 실제로 넣은 문안은 다음과 같습니다.
## 구현 범위와 복잡도
- 기본값은 요청을 충족하는 가장 단순한 구현이다. 복잡도는 위험에 비례해서만 더한다.
- 요청에 없으면 추가하지 않는다: 이력·버전·감사 테이블, soft delete, 프로시저·RPC로 묶는 다중 테이블 트랜잭션, 낙관적 잠금·동시성 제어, 캐시·큐·재시도·폴백, 구현체가 하나뿐인 인터페이스·팩토리, 하위 호환 shim, 요청하지 않은 인접 기능·UI 상태·주변 리팩터링.
- 필요해 보이면 구현하지 말고 응답 끝에 "추가 고려" 한 줄로 남긴다.
- 저장소의 레이어 구조 등 기존 패턴은 따르되, 새 Service·Repository·모듈은 기존 것에 넣을 수 없을 때만 만든다.
- 특정 도메인에 정해진 엄격 패턴(예: 쓰기와 이력 테이블 동시 기록)은 그 도메인 밖으로 넓히지 않는다.
- 리뷰·검토 지적은 현재 단계와 위험에 맞는 것만 반영한다.
- 단계와 무관하게 줄이지 않는다: 인증·권한·scope 판정, 비밀키, 돈이 움직이는 쓰기, 되돌릴 수 없는 사용자 데이터 손실.
- 저장소가 정한 검증·문서 절차(테스트·coverage 게이트, handoff, 문서 갱신 규칙)는 단순화 대상이 아니다. 이 원칙은 제품 코드의 범위에만 적용한다.
- 저장소 지침이 범위·단계·엄격 구역을 더 구체적으로 정하면 그쪽을 따른다.마지막 줄은 저장소마다 사정이 다르다는 점을 위한 것입니다. 예를 들어 회사 프론트엔드는 로딩·빈 상태·오류 화면을 기본으로 갖추도록 팀 규칙으로 정해 두었습니다. 그런 저장소에서는 전역 목록의 “요청하지 않은 UI 상태"보다 팀 규칙이 우선합니다.
어디에 둬야 읽히는가#
지침은 에이전트가 실제로 읽어야 효과가 있습니다. 내용을 쓰는 것만큼, 어느 파일에 둬야 어느 도구가 읽는지 확인하는 일이 중요했습니다. 공식 문서로 확인한 내용은 다음과 같습니다(2026년 11월 기준).
Claude Code는 ~/.claude/CLAUDE.md(사용자 전역)와, 작업 폴더부터 그 위쪽 폴더들의 CLAUDE.md를 읽어 모두 이어 붙입니다. 하위 폴더의 CLAUDE.md는 그 폴더의 파일을 다룰 때 읽습니다. 최근 버전은 AGENTS.md도 직접 읽지만, 그 위치나 상위에 CLAUDE.md가 없을 때만 그렇습니다. 두 파일이 함께 있으면 공식 문서는 CLAUDE.md에 @AGENTS.md 한 줄을 넣어 가져오라고 권합니다.
Codex는 1KiB(키비바이트)는 1,024바이트이므로 32KiB는 약 3만 2천 바이트입니다. 한글은 한 글자가 보통 3바이트라 1만 자 남짓이고, 영어로는 3만 자 정도입니다. 한도에 이르면 그 뒤의 지침 파일은 더해지지 않습니다.~/.codex/AGENTS.md(사용자 전역)를 읽습니다. 그리고 저장소 루트부터 작업 폴더까지 폴더마다 AGENTS.md를 하나씩 읽어 이어 붙입니다. 빈 파일은 건너뜁니다. CLAUDE.md는 설정 파일의 대체 파일명 목록에 직접 넣지 않으면 읽지 않습니다. 이어 붙인 지침은 기본값으로
이 사실을 놓고 보니 놓친 지점이 보였습니다. 회사 저장소 두 곳의 CLAUDE.md에는 “규칙은 AGENTS.md를 보라"는 문장만 있고 @AGENTS.md 가져오기가 없었습니다. 그래서 정작 규칙이 담긴 AGENTS.md가 Claude Code의 맥락에 들어가는지는 에이전트가 그 파일을 직접 열어 보느냐에 달려 있었습니다. 작업 허브의 지침도 허브에서 시작한 세션만 읽습니다. 저장소의 작업 폴더에서 바로 시작한 세션에는 적용되지 않습니다.
그래서 지침을 세 층으로 나눠 두기로 했습니다.
- 전역: 공통 원칙을 Claude Code와 Codex의 전역 파일에 같은 내용으로 넣었습니다. 어느 폴더에서 시작한 세션이든 읽힙니다. 두 파일은 내용이 같으니, 한쪽을 고치면 다른 쪽도 고친다는 메모를 함께 남겼습니다.
- 작업 허브: 회사 서비스의 엄격 구역과 가벼운 구역을 적었습니다. 허브에서 일을 맡기는
메인 에이전트가 작업 일부를 떼어 맡기는 별도의 에이전트입니다. 자기만의 맥락에서 일하고 결과만 돌려주며, 어떤 지시와 도구로 일할지를 정의 파일에 적어 둡니다.
정의에는 저장소의AGENTS.md를 처음에 읽도록 명시했습니다. - 저장소: 세 저장소의
AGENTS.md에 원칙과 저장소별 엄격 구역을 넣습니다. 이 파일은 필자의 도구뿐 아니라 팀원이 쓰는 Claude Code, Codex, Cursor도 읽습니다. 그래서 다른 팀 규칙 변경과 똑같이 저장소마다코드 변경을 저장소에 바로 넣지 않고, 변경 내용을 올려 다른 사람이 검토한 뒤 합치도록 요청하는 절차입니다. 팀 저장소의 규칙 문서도 코드와 같은 검토를 거쳐 바뀝니다.
로 반영하고 있습니다.
아직 모르는 것, 그리고 사람의 몫#
이 글을 쓰는 시점에는 지침을 막 적용했을 뿐이라 효과는 아직 모릅니다. 한동안 실제 구현 작업을 해 보면서 네 가지를 볼 생각입니다.
- 가벼운 구역에서 요청하지 않은 이력 테이블, 캐시, 재시도, 하위 호환 장치가 줄었는가. 그 대신 “추가 고려” 한 줄로 빠지는가.
- 엄격 구역의 장치가 약해지지 않았는가. 돈이 움직이는 설정 변경의 이력 기록 같은 것이 그대로 유지되는가.
- 단순화 원칙을 핑계로 테스트나 작업 기록을 생략하는 일이 생기지 않는가.
- 오히려 구현 품질이 떨어져 구현과 검토를 오가는 횟수가 늘지 않았는가. 꼭 필요한 처리까지 빠져서 다시 시키는 일이 잦아진다면, 원칙이 지나치게 작동하고 있다는 신호입니다.
문제가 생기면 저장소 변경은 되돌리는 PR로, 전역 지침은 백업해 둔 파일로 되돌릴 수 있습니다.
이번에 원인을 따라가며 정리된 생각은 이렇습니다. 에이전트의 기본값은 “고객이 많은 운영 서비스"입니다. 에이전트가 나빠서가 아니라, 상황을 모를 때 그쪽이 가장 덜 틀리는 선택이기 때문입니다. 그 기본값을 바꿀 수 있는 정보, 곧 지금 이 제품이 어느 단계에 있고 어디가 정말 위험한지는 사람만 알고 있습니다. 예전에는 사람의 게으름이 과설계를 막는 브레이크였다면, 이제는 그 정보를 지침 파일에 적어 두는 일이 브레이크가 됩니다. 이것이 하네스 엔지니어링에서 말하는 하네스의 한 조각이기도 합니다.
물론 지침 파일은 결국 모델이 읽고 따르기를 기대하는 장치입니다. 규칙을 기억에서 코드로에서 다뤘듯이, 문서에 적은 규칙은 강제가 아닙니다. 이번 지침이 어느 정도 지켜지는지, 지켜지지 않는 부분은 어떻게 보완해야 하는지는 몇 주 써 본 뒤 후속 글로 정리하겠습니다.