코드는 늘어나는데, 이해는 줄어든다
AI 코딩 도구를 쓰면서 이상한 감각을 느낀 적 있을 것이다. PR은 빠르게 올라가고, 테스트는 통과하고, 코드도 깔끔하다. 그런데 왜인지 시스템이 어떻게 돌아가는지 전보다 덜 아는 것 같은 기분. 이게 착각이 아니다.
dev.to에 올라온 글 "The Most Dangerous Code in Your Repo Is the Behavior Nobody Can Prove"는 이 감각을 정확히 짚는다. 저자가 던지는 질문은 단순하다. "이 동작이 왜 이렇게 구현됐는지, 레포지토리 자체가 증명할 수 있는가?" 개발자가 알고 있다거나, 팀에 4년 된 시니어가 기억한다거나—그런 답은 해당되지 않는다. 레포지토리가 스스로 설명할 수 없다면, 그 행동은 사실상 증명되지 않은 것이다.
코드 히스토리 ≠ 행동 히스토리
Git은 "이 함수가 화요일에 바뀌었다"는 사실은 알려준다. 하지만 "이 함수가 결제 프로바이더의 24시간 재시도 정책 때문에 중복 웹훅을 처리하며, 이 로직을 바꾸려면 idempotency 테스트도 같이 수정해야 한다"는 사실은 알려주지 못한다. 후자야말로 팀이 실제로 필요한 정보인데, 대부분의 코드베이스에서 그건 누군가의 머릿속이나 2022년 슬랙 스레드, 혹은 아무 데도 없는 곳에 존재한다.
코드는 여전히 실행되고, 테스트는 통과하고, 팀은 계속 배포한다. 하지만 레포지토리는 이미 그 이유를 잃어버렸다. AI가 이 문제를 만든 건 아니다—조건 하나가 왜 저렇게 생겼는지 아무도 모르는 코드는 AI 이전에도 모든 팀에 있었다. 다만 AI는 이 문제를 확실히 가속한다. 에이전트가 if (user.country === "US" && order.total > 0) 같은 조건을 "단순화"할 때, 리뷰어는 깔끔한 diff를 보고, 테스트는 통과하고, PR은 머지된다. 2주 후에야 주문이 수동 검토에 들어가지 않는 이유를 누군가 묻기 시작한다.
통과한 테스트는 이해의 증거가 아니다
테스트를 사랑하지만, 테스트는 누군가가 assert하기로 기억한 것만 증명한다. 함수가 200을 반환한다는 건 증명할 수 있다. 하지만 그 함수가 재시도 가능한지, 재시도가 idempotent해야 하는지, 타임아웃이 모바일 클라이언트 의존성 때문에 존재하는지—그런 건 증명하지 못한다. 초록 테스트 스위트는 종종 "우리가 작성한 체크가 아직 통과한다"는 뜻이지, "사용자가 의존하는 동작이 보호되고 있다"는 뜻이 아니다.
이걸 신호로 읽어야 한다. 결제 로직을 건드리는 PR에서 결제 테스트가 하나도 바뀌지 않았다면, 그건 PR이 나쁘다는 게 아니라 신호다. 기능 하나에 구현이 다섯 개, 네이밍이 세 가지, 문서가 없고, 테스트가 해피 패스만 커버한다면—다음 변경은 겉보기보다 훨씬 위험하다. 레포지토리가 조용히 말하고 있는 것이다: "나는 작동하지만, 왜 작동하는지 설명할 수 없다."
코드가 싸질수록, 이해가 비싸진다
"Has AI Changed the Joy of Building?"이라는 글에서 한 개발자는 솔직한 성찰을 남긴다. AI가 문제를 더 빠르게 푸는 데 도움을 주지만, 스스로 성장하게 만드는 부분—막히고, 문서를 읽고, 실수하고, 결국 스스로 풀어내는 과정—을 빼앗아간다고. 가장 자랑스러운 프로젝트는 가장 빨리 끝낸 것이 아니라, 가장 많이 막혔던 것이라는 고백이다.
이 두 관점은 같은 구조적 문제를 가리킨다. AI는 코드 생성 속도를 높이는 동시에, 그 코드가 왜 그렇게 동작하는지 팀이 이해할 기회를 줄인다. 빠른 프로토타이핑이 목표라면 AI는 완벽한 도구다. 하지만 프로토타입을 프로덕션으로 고도화할 때, 그 시스템을 6개월 후에 유지보수할 때—그때 필요한 건 빠르게 생성된 코드가 아니라, 그 코드의 행동을 설명할 수 있는 증거다. 코드가 싸질수록 이해는 비싸진다는 역설이 여기서 나온다.
개발자가 설계해야 할 것
그렇다면 무엇을 바꿔야 할까. 문서를 더 잘 쓰자는 답은 절반만 맞다. README에 "webhooks are idempotent"라고 쓰는 것보다, 중복 전달이 안전하다는 걸 테스트로 증명하는 게 낫다. 테스트보다는 왜 그 방식으로 구현했는지 설명하는 의사결정 기록이 낫다. 그리고 그 모든 주장을 실제 파일, 테스트, 라우트, 최근 diff와 연결할 수 있는 구조가 가장 낫다.
코드 리뷰 질문도 달라져야 한다. 전통적인 리뷰는 코드가 올바른지, 읽기 좋은지, 안전한지, 테스트됐는지를 묻는다. 여기에 하나를 더해야 한다. "이 변경이 보존한다고 주장하는 동작은 무엇이고, 그 증거는 어디 있는가?" 결제 웹훅을 건드리는 PR이라면—중복 전달에 영향을 주는가, 재시도 동작은 어떻게 되는가, 환불 로직은 안전한가—그리고 각 답에 대한 증거가 있는가, 아니면 그냥 자신감만 있는가.
원문 저자는 레포지토리가 핵심 동작 영역별로 증거 수준을 보여주는 "understanding score" 개념을 제안한다. 인증은 강함, 결제 웹훅은 부분적, 어드민 권한은 불명확—이런 식으로. 완벽한 점수를 목표로 하는 게 아니라, 자신감이 가짜인 부분에 주의를 집중시키기 위해서다. 가짜 자신감은 비싸다.
병목은 증거다
AI 도구는 계속 좋아진다. 코드를 더 많이 생성하고, PR을 더 많이 올리고, 테스트를 더 많이 만든다. 문제는 그게 아니다. 더 빠른 코드 생성이 더 나은 시스템 이해로 자동 연결되지 않는다는 것이다. 팀은 더 많은 코드를 배포하면서 자신이 보존하고 있는 동작을 점점 덜 이해할 수 있다.
진짜 병목은 문법도, 보일러플레이트도, 리뷰 속도도 아니다. 병목은 증거다. 이 동작이 무엇인지, 왜 존재하는지, 이 변경이 그것을 깨뜨리지 않는다는 걸 증명할 수 있는가. 그 질문에 답하는 구조를 설계하지 않으면—레포지토리는 기억과 구전과 자신감 위에서 돌아간다. 그리고 자신감은 증거가 아니다.