6개월 전 AI가 80%를 작성한 WordPress 플러그인을 다시 열었을 때, 날짜 포맷 로직이 세 군데에 흩어져 있었다. 유틸 함수 하나, 클래스 메서드 하나, 템플릿 인라인 하나. 모두 조금씩 달랐다. 버그 리포트가 들어왔고, 고치는 건 어렵지 않았다. 어려운 건 내가 쓴 코드의 구조를 읽는 것이었다. dev.to에 올라온 이 경험담은 AI 코딩 에이전트를 둘러싼 논쟁에서 자주 빠지는 질문을 정면으로 건드린다. 빠르게 만든 코드가 오래 살아남을 수 있는가?
이 질문은 단순히 코드 품질 문제가 아니다. 제품의 생애주기 문제다. 프로토타입을 빠르게 검증하고 고도화하는 흐름을 중요하게 생각한다면, AI가 만들어준 초안이 그 여정의 발목을 잡는 순간을 반드시 마주하게 된다. 속도 자체가 문제가 아니다. 속도가 조용히 제거해버리는 것들이 문제다.
왜 6개월 뒤에 읽을 수 없어지는가
진단은 세 문장으로 충분하다. 설계 결정의 이유는 채팅창 안에만 존재하다가 창을 닫는 순간 사라진다. diff를 읽지 않고 수락하면서 코드가 '내 것'이 되는 과정이 생략된다. 그리고 에이전트에게 구조를 세션 단위로 맡기면, 같은 일이 세 가지 방식으로 구현된다. 세 개의 날짜 함수는 이 마지막 문제의 결과물이다.
결정을 코드 옆에 착지시켜라
가장 효과가 컸던 변화는 CLAUDE.md의 용도를 바꾸는 것이었다. 에이전트 지시 파일의 절반을 미래의 나를 위한 결정 기록으로 전환했다. 중요한 건 무엇을 했는가가 아니라 왜 했는가, 그리고 어떤 선택지를 거절했고 그 이유는 무엇인가다. 거절한 옵션이 가장 중요하다. 6개월 뒤의 나는 정확히 똑같은 '좋은 아이디어'를 다시 떠올리고, 같은 함정에 빠지기 때문이다.
여기에 기능을 추가할 때마다 docs/decisions.md에 한 단락을 남기는 습관을 더했다. 완성 후 풀 스펙을 작성하려는 시도는 번번이 실패했다. 기억에서 복원한 스펙은 절반이 틀리고, 부담이 커서 계속 미루게 된다. 한 단락, 기능을 막 닫은 직후의 모멘텀을 그대로 살려서 쓰는 것—이 정도라야 실제로 지속된다. 한 가지 경고가 있다. 에이전트에게 결정 로그를 '써달라'고 하면 코드를 역공학한 그럴듯한 설명이 나온다. 그건 실제 이유가 아니다. 초안을 받더라도, 그 당시 진짜 생각했던 것으로 반드시 덮어써야 한다.
리뷰 게이트를 작게 유지하라
모든 diff를 읽으려다 실패했고, 아무것도 읽지 않는 acceptEdits 기본값으로 돌아가는 악순환은 누구나 겪는다. 극단은 지속되지 않는다. 해법은 반드시 읽어야 하는 diff의 짧은 목록을 명시하고, 나머지는 자동 수락하는 것이다. 공개 API(훅 이름, 함수 시그니처, REST 라우트), DB 스키마, 인증·권한·이스케이핑 처리, 그리고 단일 커밋 80줄 초과—이 네 가지만 사람이 본다. 내부 리팩터링이나 테스트 추가는 자동 수락한다. 기준은 되돌리는 비용이다. 훅 이름 하나가 바뀌면 그걸 사용하는 모든 코드가 조용히 깨진다. 이스케이핑 누락은 6개월 뒤 보안 취약점으로 나타난다. 선택적 집중이 리뷰 습관을 살아있게 한다.
구조와 네이밍은 직접 붙들어라
세 개의 날짜 함수 문제는 구조를 에이전트에게 세션 단위로 넘긴 결과다. 에이전트는 방치하면 팽창한다. 새 함수, 새 파일, 이미 있는 헬퍼 옆에 또 다른 헬퍼. 해법은 프레임을 직접 고정하고 에이전트가 그 안에서 움직이게 하는 것이다. 디렉터리 구조, 네이밍 규칙, 파일당 책임 범위를 CLAUDE.md와 AGENTS.md 양쪽에 동일하게 명시한다. 도구를 전환하는 순간 스타일이 바뀌기 때문이다. '500줄 초과 시 분리를 제안하라, 직접 하지 말라'는 규칙도 여기서 나온다. 에이전트가 임의로 파일을 쪼개면, 내가 찾던 코드가 이동해있다.
주석과 커밋은 '왜'만 담아라
에이전트가 추가하는 주석 대부분은 코드가 무엇을 하는지를 설명한다. 6개월 뒤에는 쓸모가 없고, 코드가 바뀌는 순간 거짓말이 된다. 진짜 가치 있는 주석은 코드 자체가 보여줄 수 없는 이유다. hash_equals를 쓴 이유, ==으로 단순화하면 안 되는 이유—이걸 두 줄로 남기면, 6개월 뒤 단순화를 시도하려던 손이 멈춘다. 커밋 메시지도 마찬가지다. 첫 줄은 what(위임해도 된다), 본문 한 줄이 why다. git blame이 그 줄에 착지했을 때, 이유가 바로 거기 있어야 한다.
테스트를 살아있는 명세로
스펙이 끝내 작성되지 않는다면, 테스트가 스펙이어야 한다. 함수명이 아니라 동작 단위로 테스트 이름을 붙이면(invalid_signatures_are_logged_and_swallowed, gives_up_after_three_failed_sends), 테스트 목록을 훑는 것만으로 플러그인이 무엇을 보장하는지 읽힌다. 내부 구현을 추적하는 테스트는 리팩터링마다 깨져서 결국 주석 처리된다. 외부 동작 계약을 검사하는 테스트만 6개월 뒤에도 살아있다.
이 모든 습관은 하나의 통찰로 수렴한다. AI 에이전트는 코드를 생성하지만, 맥락을 보존하지 않는다. 채팅은 닫히고, 세션은 리셋되고, 결정의 이유는 증발한다. 미래의 나—혹은 팀원—가 그 코드를 열었을 때 마주하는 건 결과물뿐이다. 프로세스도, 트레이드오프도, 거절된 선택지도 없다. 기록 습관은 AI 도구를 덜 쓰라는 말이 아니다. AI가 채워주지 않는 빈자리를 의도적으로 설계하라는 말이다.
한편 '마찰 없는 온보딩' 관점에서도 같은 문제가 보인다. 멀티플레이어 수족관 프로젝트 사례처럼, 로그인 없이 즉시 시작하고 나중에 계정을 연결하는 설계는 사용자 경험의 마찰을 제거한다. AI 코딩 도구도 같은 맥락이다. 진입 마찰을 없애주는 대신, 소유권(Ownership)과 추적 가능성이라는 비용이 뒤로 미뤄진다. 사용자에게는 나중에 '내 물고기'를 되찾을 경로를 만들어줘야 하듯, 개발자에게는 나중에 '내 코드'를 이해할 경로를 지금 만들어줘야 한다.
전망: 생성 이후의 설계
AI 코딩 도구는 점점 더 많은 코드를 더 빠르게 만들어줄 것이다. 그 속도가 올라갈수록, 맥락을 보존하는 구조의 가치도 함께 올라간다. CLAUDE.md를 잘 쓰는 것, 결정 로그를 남기는 것, 리뷰 게이트를 선택적으로 유지하는 것—이것들은 AI를 덜 신뢰해서가 아니라 AI와 오래 협업하기 위한 설계다. 빠르게 프로토타입을 만들고 검증하고 고도화하는 흐름에서, AI는 강력한 동반자다. 단, 그 동반자가 채워주지 못하는 빈자리를 아는 개발자만이 6개월 뒤의 코드베이스를 온전히 소유할 수 있다.