Repo Drift는 AI 코딩 에이전트의 숨겨진 비용입니다 — 그리고 한 가지 해결책은 생각보다 간단합니다

AI 코딩 에이전트(AI coding agents)에 대한 많은 대화는 명백한 실패 사례들에 집중합니다: 환각을 일으키는 API (hallucinated APIs), 깨진 테스트 (broken tests), 잘못된 가정 (bad assumptions), 또는 단순히 실행되지 않는 코드 같은 것들 말이죠.

하지만 저는 더 큰 문제 중 하나가 훨씬 조용하게 발생한다고 생각합니다. 에이전트가 작업을 완료했고, 앱은 여전히 작동하며, 테스트마저 통과할 수도 있지만, 리포지토리(repo)는 이전보다 더 무질서해진 상태가 되는 것입니다.

이것이 바로 Repo Drift입니다. 또는 더 구체적으로 말하자면, Repo Entropy(리포지토리 엔트로피)입니다.

이는 비대해진 파일, 중복된 헬퍼 함수 (duplicate helpers), 겉모습만 모듈화된 구조 (cosmetic modularity), 오래된 스캐폴딩 (stale scaffolding), 한 곳의 표면적인 문제는 해결하지만 다른 곳에 불일치를 만드는 로컬 패치 (local patches), 그리고 프레임워크와 함께 작동하는 대신 프레임워크를 우회하여 작동하는 커스텀 내부 코드 (custom under-the-hood code) 등의 형태로 나타납니다.

이것은 제가 AI 보조 개발 (AI-assisted development)에서 목격하는 Drift의 가장 큰 원인 중 하나입니다.

에이전트는 자동으로 당신의 소프트웨어 전문가가 되는 것이 아닙

개발자들은 종មាន히 AI 코딩 에이전트가 리포지토리 내부에서 작업하고 있다면, 숙련된 유지보수자 (maintainer)처럼 소프트웨어 스택 (software stack)을 이해할 것이라고 가정하곤 합니다. 하지만 그것이 항상 사실인 것은 아닙니다.

에이전트는 일반적인 의미에서 프레임워크를 알고 있을 수 있습니다. 수천 개의 예시를 보았을 수도 있습니다. 그럴듯한 코드를 빠르게 생성하는 데 능숙할 수도 있습니다. 하지만 그것이 프레임워크의 현재 버전, 리포지토리의 실제 아키텍처 (architecture), 프로젝트가 선호하는 패턴 (preferred patterns), 최신 공식 가이드라인, 기존의 추상화 (existing abstractions), 어떤 파일이 표준(canonical)인지, 어떤 패턴이 권장되지 않는지 (deprecated), 또는 소프트웨어가 어떻게 확장되기를 "원하는지"를 알고 있다는 의미는 아닙니다.

마지막 포인트는 사람들이 생각하는 것보다 더 중요합니다. 모든 성숙한 스택에는 결(grain)이 있습니다. 프레임워크가 상태 (state), 라우팅 (routing), 폼 (forms), 검증 (validation), 에셋 (assets), 테스트 (tests), 설정 (configuration), 그리고 데이터 흐름 (data flow)이 시스템을 통해 이동하기를 기대하는 방식이 존재합니다.

에이전트가 그 결을 따르지 않을 때, 에이전트는 자신이 이해하지 못하는 간극을 메우기 위해 커스텀 코드를 발명하기 시작하는 경우가 많습니다. 그 커스텀 코드는 당면한 작업은 해결할 수 있겠지만, Drift를 생성합니다.

Drift는 종종 "도움이 되는" 코드로 시작됩니다

코딩 에이전트 (Coding agent)가 무모하게 행동하려고 해서 Drift를 생성하는 경우는 보통 없습니다. 에이전트는 불완전한 근거 (Grounding)를 바탕으로 도움을 주려다 보니 Drift를 생성하게 됩니다.

에이전트는 문제를 발견하면 그 주변을 임시로 수정 (Patch)합니다. 누락된 헬퍼 (Helper)를 발견하면 새로 만듭니다. 어색한 인터페이스 (Interface)를 보면 또 다른 레이어 (Layer)를 추가합니다. 실패하는 테스트를 보면 테스트를 수정합니다. 프레임워크 제약 (Framework constraint)을 발견하면, 프레임워크에 이미 해당 문제를 해결할 네이티브 경로 (Native path)가 있는지 확인하는 대신 커스텀 로직 (Custom logic)을 작성합니다.

각각의 움직임은 국소적으로는 합리적으로 보일 수 있습니다. 위험한 점은 그 축적입니다.

하나의 헬퍼가 세 개가 됩니다. 하나의 워크어라운드 (Workaround)가 하나의 패턴 (Pattern)이 됩니다. 비대해진 파일 하나가 모든 것이 추가되는 장소가 됩니다. 하나의 "임시" 스캐폴드 (Scaffold)가 아키텍처 (Architecture)의 일부가 됩니다.

이런 방식으로 레포지토리 (Repo)는 서서히 자신의 설계와 일치하지 않게 됩니다.

한 가지 간단한 해결책은 에이전트를 레포지토리의 실제 베이스라인 (Baseline)에 맞게 업데이트하는 것입니다

더 나은 프롬프트 (Prompt)가 도움이 되긴 하지만, 그것만으로는 충분하지 않습니다. 더 큰 수리 방법은 에이전트가 레포지토리의 실제 베이스라인을 바탕으로 작업하도록 강제하는 것입니다.

"Best practices를 사용하세요"와 같은 모호한 지침이 아니라,

다음과 같은 구체적인 가이드라인이 필요합니다:

• 이 레포지토리가 사용하는 프레임워크 버전 (Framework version)
• 이 버전에 대해 공식 문서 (Official docs)가 권장하는 사항
• 어떤 레포지토리 파일이 표준 (Canonical)인지
• 어떤 패턴이 승인되었는지
• 어떤 패턴이 권장되지 않는지 (Deprecated)
• 어떤 명령어가 변경 사항이 작동함을 증명하는지
• 이 작업에서 건드려서는 안 되는 파일은 무엇인지
• 무엇을 범위 확장 (Scope creep)으로 간주할 것인지
• 무엇을 완료 (Done)로 간주할 것인지

코딩 에이전트가 즉흥적으로 행동하게 두는 대신, 소프트웨어의 실제 벤치마크 가이드라인 (Benchmark guidance) 내에서 작동하도록 업데이트하는 것만으로도 많은 Drift를 피할 수 있습니다.

다시 말해, 소프트웨어에 이미 아키텍처가 있다면 에이전트가 아키텍처를 발명하게 두지 마십시오.

작업 완료 (Completion)와 레포지토리 건강도 (Repo health)는 같은 것이 아닙니다

이것은 제가 계속해서 강조하는 차이점입니다. 에이전트가 작업을 완료할 수는 있지만, 여전히 레포지토리를 더 나쁘게 만들 수 있습니다.

에이전트는 버그를 수정하면서 파일의 크기를 비대하게 만들 수 있습니다. 테스트를 통과하면서도 설계를 약화시킬 수 있습니다. 기능을 추가하면서 기존의 추상화 (Abstraction)를 중복시킬 수도 있습니다. 프롬프트 (Prompt)를 만족시키면서 프로젝트의 베이스라인 (Baseline)을 위반할 수도 있습니다.

따라서 질문은 단지 다음과 같아서는 안 됩니다:

에이전트가 작업을 완료했는가?

다음과 같은 질문도 포함되어야 합니다:

에이전트가 손을 댄 후, 레포지토리가 더 신뢰할 수 있게 되었는가, 아니면 더 엔트로피 (Entropy)가 높아졌는가?

이것이 바로 차세대 AI 보조 개발 (AI-assisted development)이 나아가야 할 방향이라고 생각합니다. 단순히 더 자율적인 에이전트, 더 긴 컨텍스트 (Context), 또는 더 나은 코드 생성 (Code generation)이 아니라, 더 나은 레포지토리 로컬 감독 (Repo-local supervision)이 필요합니다.

무엇이 변했는지, 그 변화가 작업 경계 (Task boundary) 내에 머물렀는지, 검증 (Verification)이 실제로 실행되었는지, 파일이 비대해졌는지, 그리고 작업이 완료된 후에도 레포지토리가 여전히 자체적인 진실 (Truth)과 일치하는지를 파악할 수 있는 진단 도구가 필요합니다.

왜냐하면 가장 까다로운 AI 코딩 실패는 항상 즉각적으로 무언가를 망가뜨리는 것이 아니기 때문입니다. 때때로 에이전트는 성공하지만, 그 뒤에 무질서를 남겨둡니다.