Anthropic이 Claude Code를 쓰면서 겪던 실패 유형에 이름을 붙여줬네요: '에이전트 기술 부채(agentic technical debt)'

Claude Code(아니면 Cursor나 Cline)로 뭐 좀 제대로 된 거 만들어본 놈들은 다 알 거다. 첫 세션은 진짜 마법 같다. 코드가 술술 뽑히거든. 근데 세션 3쯤 가면 이놈이 갑자기 내가 정한 거랑은 다른 아키텍처를 들고나온다. 세션 7쯤 되면 똑같은 기능이 구현된 파일이 두 개씩 생기고, 뭐가 진짜인지 아무도 모르는 상황이 벌어짐.

한동안은 내 탓인가 싶기도 했고, 모델 탓인가 싶기도 했다. 그러다 앤스로픽 창업자 플레이북에서 '에이전트 기술 부채(agentic technical debt)'라는 용어를 봤는데, 거기서 말하는 차이점이 딱 꽂히더라. 일반적인 기술 부채는 가만히라도 있지, 스프린트 한 번 빡세게 돌리면 해결이라도 되잖아. 근데 에이전트 부채는 복리로 불어난다. 에이전트가 제일 먼저 읽어야 할 곳에 네 설계랑 결정 사항들을 안 적어두면, 세션마다 기초적인 선택들을 처음부터 다시 하느라 아키텍처가 계속 산으로 간다. 세션 좀 쌓이면 코드베이스에 일관된 논리 구조가 아예 사라짐. 각 부분은 잘 돌아가는데, 애초에 서로 합쳐질 생각을 안 하고 만들어진 꼴이지.

처음엔 내가 이걸 잘 못 다루나 싶었다. 근데 아니더라. 에이전트는 네 아키텍처를 지 맘대로 갈아엎을 만큼 똑똑한데, 네가 정한 걸 지켜야 할 의무는 없거든. 레포 읽고, 기능 짜고, 테스트 돌리는 걸 다 지 혼자 알아서 하니까. 풀 스피드로 달리니까 삽질도 풀 스피드로 하는 거다. 세션 3쯤 되면 프랑켄슈타인 코드 완성인데, 속도는 역대급으로 빠르지. 프롬프트도 더 정교하게 짜보고, 메모리 기능도 붙여봤다. 결국 효과 본 건, 내가 정한 아키텍처를 세션마다 에이전트가 강제로 지키게 만드는 방법뿐이었다.

누가 뭐라 하기 전에 미리 말하는데, 요즘 메모리 툴(메모리 MCP, 세션 메모리 같은 거) 있는 거 안다. 도움은 된다. 근데 걔들은 '회상'을 돕는 거지 '방향'을 잡아주는 게 아니다. 에이전트가 지난 세션 내용을 다 기억해도 계획에서 벗어날 놈은 벗어난다. 결정을 기억하는 거랑 그 결정을 지키게 하는 건 완전히 다른 문제인데, 아직은 전자만 해결된 상태거든.

수개월 동안 삽질하고 고치면서 내가 효과 본, 좀 지루하지만 확실한 방법은 이거다.

• 코딩하기 전에 문서부터 써라. 첫 세션 시작 전에 비즈니스 모델, 범위(in/out of scope)가 명확한 PRD, 쉬운 말로 쓴 DB 스키마, 시스템 아키텍처, 그리고 에이전트가 세션마다 읽을 CLAUDE.md를 작성해라. 특히 '범위 외(out-of-scope)' 목록이 생각보다 엄청 중요하다. 에이전트가 다음 주에 "도움 좀 주려고" 멋대로 코드 뜯어고치는 걸 막아주는 방어선이거든.

• 세션을 3단계로 나눠서 돌려라. 0단계에선 에이전트가 문서를 읽는다. 1단계에선 범위를 검증하고 이미 결정된 사항이랑 충돌하는 게 있는지 체크한다. 2단계에선 정해진 범위 내에서 구현하고, 나는 브랜치 커밋을 보면서 마지막에 검토한다. 이 순서 안 지키면 또 딴길로 샌다.

• 진짜 결정 사항은 무조건 ADR(Architecture Decision Record)로 남겨라. 맥락, 결정 내용, 근거, 기각된 대안까지 적어두면 된다. 다음 세션에 에이전트가 이미 내린 결정을 가지고 또 싸우는 대신, ADR을 읽게 해라. 이게 제일 효과 좋았다.

• 가능한 한 규칙을 결정론적으로 만들어라. 문서에 "모든 입력값을 검증해라"라고 적는 것보다, 실패하는 테스트 코드를 하나 박아두는 게 낫다. 에이전트는 말로 설득이 안 되지만 테스트 실패는 못 넘어가거든. 린팅, 타입 체크, 빨간 불 들어오는 테스트, 프리커밋 훅 같은 건 제안이 아니라 강제니까 다시 논쟁할 필요가 없다. 문서는 방향을 제시하고, 이런 장치들은 컨텍스트가 꼬일 때 에이전트가 딴짓 못 하게 막는 벽이 된다.