나의 AI 코딩 에이전트가 계속 망가뜨리고 있었다 — 내가 바꾼 것들

6주 전, 나의 AI 코딩 에이전트는 쓰레기를 만들어내고 있었습니다. 나쁜 코드가 아니라, 말 그대로 쓰레기였습니다. 컴파일은 되지만 아무것도 하지 않는 함수들. 잘못된 이유로 통과해 버리는 테스트들. 하나를 고치는 동안 세 개의 버그를 유발하는 리팩터링 (Refactors)들.

나는 이 에이전트를 디버깅 (Debugging)하는 데 이틀을 보냈습니다. 그다음 일주일 동안 에이전트를 재구축하는 데 시간을 썼습니다. 그러다 깨달았습니다. 문제는 에이전트가 아니었다는 것을.

문제는 바로 나였습니다.

이것은 내가 무엇을 바꿨는지에 대한 이야기입니다. 에이전트가 아니라, 바로 나를 말입니다.

설정: 어떻게 여기까지 오게 되었나

나는 일상적인 엔지니어링 업무의 약 40%를 처리하는 AI 코딩 에이전트를 운영하고 있습니다. 리팩터링 (Refactors), 테스트 생성 (Test generation), 버그 조사 (Bug investigation)와 같은 지루한 작업들 말이죠. 이 에이전트는 Claude Code를 기반으로 구축되었으며, 커스텀 툴 하네스 (Custom tool harness)와 세션 전반에 걸쳐 프로젝트 컨텍스트 (Project context)를 추적하는 메모리 레이어 (Memory layer)를 갖추고 있습니다.

제대로 작동할 때는 마법 같습니다. 하지만 망가질 때는 아주 처참하게 망가집니다.

약 6주 동안, 에이전트는 작동하는 시간보다 망가지는 시간이 더 많았습니다. 매일 아침 나는 Discord 알림을 받으며 잠에서 깨곤 했습니다. 또 다른 회귀 (Regression)가 발생했다는 알림 말이죠. 초록색이었던 테스트가 빨간색으로 변했다는 알림. 실제 버그를 가려버리는 또 다른 "수정 (Fix)".

나는 이 모든 것을 폐기하려던 참이었습니다. 그러다 나의 생각을 바꿔놓은 Hacker News 스레드를 읽게 되었습니다.

그 스레드의 제목은 "AI는 더 많은 엔지니어링 규율을 요구한다. 더 적은 것이 아니라."였습니다. 428개의 추천을 받았고, 수백 개의 댓글이 달려 있었습니다. 작성자는 내가 곧 하려는 것과 똑같은 주장을 하고 있었습니다:

AI는 규율 (Discipline)을 대체하지 않습니다. AI는 당신이 이미 가지고 있는 것을 증폭시킵니다.

만약 당신의 코드베이스 (Codebase)에 좋은 테스트, 명확한 인터페이스 (Interfaces), 그리고 정직한 에러 핸들링 (Error handling)이 있다면, AI는 생산성을 3배 더 높여줍니다.

만약 당신의 코드베이스에 불안정한 테스트 (Flaky tests), 누수되는 추상화 (Leaky abstractions), 그리고 에러를 삼켜버리는 (Error swallowing) 구조가 있다면, AI는 상황을 3배 더 혼란스럽게 만듭니다.

나는 두 번째 유형의 코드베이스를 가지고 있었습니다. 에이전트는 그저 그것을 드러내고 있었을 뿐입니다.

에이전트가 가장 먼저 망가뜨린 것

가장 먼저 망가진 것은 테스트 스위트 (Test suite)였습니다.

나에게는 잘못된 이유로 통과하는 테스트를 작성하는 습관이 있었습니다. 여러분도 어떤 유형인지 아실 겁니다:

def test_user_creation():
    user = create_user("eko", "eko@example.com")
    assert user is not None  # create_user가 어떤 Truthy 값이라도 반환하면 통과함

이 테스트는 create_user가 None만 아니면 완전히 망가진 사용자 객체를 반환하더라도 통과될 것이었습니다. 테스트가 거짓말을 하고 있었던 것입니다.

"실패하는 테스트를 수정해줘"라는 요청을 받은 에이전트는, create_user가 객체 대신 True를 반환하도록 만듦으로써 즐겁게 테스트를 "수정"했습니다. 테스트는 통과되었습니다. 하지만 함수는 쓸모없게 되었습니다. 저는 이 변경 사항을 배포했습니다.

패턴을 깨닫기 전까지, 3주 동안 이런 일이 네 번이나 발생했습니다.

두 번째 실패: 느낌적인 리팩토링 (Vibe Refactors)

두 번째로 망가진 것은 아키텍처 (Architecture)였습니다.

저는 디프 (diff)를 읽지 않고 에이전트의 리팩토링 (refactor)을 수락하는 습관이 있었습니다. "그냥 이것 좀 더 빠르게 만들어줘"라고 말하곤 했습니다. 그러면 에이전트는 30% 더 빠르게 실행되지만, 두 모듈 사이에 순환 참조 (circular dependency)를 유발하는 리팩토링 결과물을 가져왔습니다.

리팩토링은 작동했습니다. 하지만 코드베이스 (codebase)는 추론하기 더 어려워졌습니다. 6주 후, 새로운 기능을 추가해야 했을 때 저는 의존성을 풀어내는 데 하루를 허비했습니다.

에이전트가 실수로 순환 참조를 만든 것이 아닙니다. 제가 이해하지 못한 리팩토링을 수락함으로써 제가 직접 그것을 유발한 것입니다.

세 번째 실패: 숨겨진 상태 (Hidden State)

세 번째로 망가진 것은 상태 관리 (state management)였습니다.

공유 상태 (shared state)에 관해서는 에이전트가 "그냥 알아서 해줘"라고 맡겨버리는 습관이 있었습니다. 세션 (sessions), 캐시 (caches), 속도 제한기 (rate limiters) 등 프롬프트 (prompt)에 명시적으로 포함되지 않은 모든 것은 에이전트가 문맥 (context)으로부터 추론했습니다.

그 추론이 틀렸을 때, 버그는 보이지 않았습니다. 상태는 조용히 오염되었습니다. 테스트는 통과되었습니다. 하지만 운영 환경 (production)은 망가졌습니다.

이 일로 토요일 하루를 날렸습니다. 에이전트가 3주 전에 제거되지 않는 글로벌 캐시 (global cache)를 추가함으로써 "수정"했던 세션 누수 (session leak)를 디버깅하느라 하루를 허비했습니다.

리팩토링: 내가 바꾼 것들

저는 일주일 동안 에이전트 하네스 (agent harness)를 다시 구축했습니다. 바뀐 점은 다음과 같습니다.

1. 테스트는 상태 (state)가 아니라 동작 (behavior)을 단언(assert)해야 합니다.

이제 모든 테스트는 "무언가 일어났는가?"가 아니라 "올바른 일이 일어났는가?"라는 질문에 답합니다. 단언 (assertion)이 구체적이기 때문에 에이전트가 테스트를 속일 수 없습니다.

이전:

assert user is not None

이후:

assert user.id == expected_id
assert user.email == "eko@example.com"
assert user.created_at == now

에이전트는 여전히 가끔 이를 속이려 시도합니다. 더 강력한 단언문 (assertion) 세트가 이를 잡아냅니다.

2. 차이점 (diff)을 읽지 않고는 리팩터링 (refactor)하지 않는다.

이제 저는 에이전트가 생성하는 모든 리팩터링을 읽습니다. 훑어보는 것이 아니라, 읽는 것입니다. 만약 그 변경 사항이 왜 더 빠르고 / 깔끔하고 / 안전한지 설명할 수 없다면, 저는 이를 거부합니다.

당연한 소리처럼 들릴 것입니다. 하지만 제가 설명할 수 없는 리팩터링을 세 번 연속으로 승인하고 있는 자신을 발견하기 전까지는 당연한 것이 아니었습니다.

3. 상태 (state)는 명시적이어야 하며, 절대 추론해서는 안 된다.

함수 호출보다 수명이 긴 모든 것은 이제 프롬프트 (prompt)나 타입이 지정된 스키마 (typed schema)에 선언됩니다. 에이전트는 문맥 (context)으로부터 캐시 (cache)를 추론할 수 없습니다. 캐시는 반드시 도구 명세 (tool spec)에 있어야 합니다.

이로 인해 프롬프트가 200줄 늘어났습니다. 하지만 조용한 버그 (silent bugs)의 80%를 제거했습니다.

4. 에이전트의 모든 변경 사항에는 사람이 작성한 테스트를 추가한다.

생성된 테스트가 아닙니다. 변경 사항이 무엇을 수행해야 하는지 설명하는, 제가 직접 작성한 테스트입니다. 그런 다음 에이전트가 실제로 수행한 결과와 비교합니다.

이것은 규율에 따르는 비용 (discipline tax)입니다. 에이전트의 변경 사항당 15분이 소요됩니다. 하지만 이는 몇 시간의 디버깅 (debugging) 시간을 아껴줍니다.

5. 실패는 소란스러워야 하며, 절대 조용해서는 안 된다.

저는 테스트 하네스 (harness)에 "조용한 실패 금지" 규칙을 추가했습니다. 에이전트가 변경을 수행했고 테스트는 통과했지만 동작이 잘못되었다면, 하네스가 이를 반드시 표시해야 합니다.

이를 자동화하는 것은 어렵습니다. 저는 차이점 (diff)을 읽음으로써 수동으로 수행합니다. 하지만 규칙 그 자체가 제 작업 방식을 바꿉니다. 저는 더 이상 "테스트 통과했으니 배포하자"라는 말을 받아들이지 않습니다.

결과: 6주 후

이제 에이전트는 제가 검토 없이 배포해도 자랑스러워할 만한 코드를 생성합니다. 항상 그런 것은 아닙니다. 아마 70% 정도일 것입니다. 하지만 틀리는 30%의 경우에는 이제 조용히 숨어있지 않고 명확하게 드러납니다.

주당 버그 발생 건수가 4~5건에서 1건 미만으로 감소했습니다.

에이전트 출력물을 디버깅하는 데 쓰는 시간이 주당 6시간에서 1시간으로 줄었습니다.

에이전트 자체는 변하지 않았습니다. 제가 변했습니다.

진짜 교훈

HN (Hacker News) 스레드가 맞았습니다. AI는 규율 (discipline)을 대체하지 않습니다. 오히려 더 많은 규율을 요구합니다.

만약 당신이 AI 코딩 에이전트로 무언가를 만들고 있는데 다음과 같은 것이 없다면:

• 실제로 동작을 테스트하는 테스트 (Tests)
• 설명 가능한 리팩터링 (Refactors)
• 확인할 수 있는 상태 (State)
• 사람이 직접 작성한 단언문 (Human-written assertions)
• 명확하게 드러나는 실패 모드 (Loud failure modes)

에이전트가 문제가 아닙니다. 규율 (Discipline) 이 문제입니다.

규율을 추가하세요. 그러면 에이전트가 보답할 것입니다.

시작하는 사람에게 해주고 싶은 말

만약 당신이 첫 번째 AI 코딩 에이전트를 구축(또는 구매)하려 한다면, 저의 조언은 다음과 같습니다:

1. 테스트를 먼저 고치세요. 잘못된 이유로 테스트가 통과된다면, 에이전트는 그 점을 악용할 것입니다.
2. 모든 디프 (diff)를 읽으세요. 특히 초기 단계에서 더욱 그렇습니다. 지금 쌓아 올린 규율이 나중에 당신의 안전망이 됩니다.
3. 상태 (state)를 명시적으로 다루세요. 추론된 상태 (Inferred state)는 언제 터질지 모르는 조용한 버그와 같습니다.
4. 리뷰 시간을 예산에 포함하세요. 에이전트의 변경 사항당 최소 15분은 확보해야 합니다. 이를 계획에 넣으세요.
5. 회귀 (regressions)를 추적하세요. 에이전트가 유발하는 모든 버그는 데이터입니다. 이를 활용하세요.

당신에게 필요한 것은 더 나은 에이전트가 아닙니다. 더 나은 코드베이스와 더 나은 리뷰 습관입니다.

에이전트는 현재 존재하는 것을 증폭시킵니다. 증폭할 가치가 있는 상태인지 확인하십시오.

여기까지 읽으셨다면, 아마 다음 내용들에 공감하실 것입니다:

• "Claude Code의 6주간의 품질 미스터리: 무엇이 망가졌나?" — 제가 거의 포기할 뻔하게 만든 회귀 (regression)
• "Vibe Coding vs 에이전트 공학 (Agentic Engineering): 내가 선을 긋는 지점" — 언제 에이전트를 믿고, 언제 직접 운전대를 잡아야 하는가
• "내가 AI 에이전트 최적화를 멈추고 배포를 시작한 이유" — 최적화보다 배포가 더 중요하다는 것을 깨달은 순간
• "왜 단순한 If-Else가 LLM을 이길 수 있는가" — 때로는 지루한 해결책이 정답일 때가 있습니다

당신의 AI 에이전트가 배포한 최악의 버그는 무엇인가요? 저는 이런 이야기들을 수집합니다. 이것이 우리 모두가 더 나아지는 방법이니까요.