How to reduce technical debt ?

첫째, 쪽지시험

시험은 채점이 아니라 인터뷰다. 에이전트는 개방형 질문을 하나 던진다. “왜 대안 X가 아니라 이 방식인가?” “이 부분이 없으면 무엇이 잘못되는가?” 내 답을 듣고, 갭이 드러난 지점을 골라 꼬리 질문을 던진다. 다음 질문은 미리 정해져 있지 않다. 내 직전 답이 결정한다. 같은 갭이 두 번의 후속 질문에도 안 풀리면 그때야 해설이 나온다.

빠뜨린 것을 즉시 알려주지도 않는다. “단계가 더 있는데, 뭐가 빠졌을까?“라고 회상을 요구한다. 불편하다. 불편한 것이 정상이다. 빚을 갚는 일이 편했던 적은 없다.

둘째, 리터릿 코드 디프

Knuth는 1984년에 리터릿 프로그래밍(literate programming)을 제안하며 이렇게 말했다. 프로그램 작성의 주 임무를 컴퓨터에게 지시하는 것이 아니라, 컴퓨터가 무엇을 하길 원하는지 인간에게 설명하는 것으로 바꾸자.7 이 관점을 디프(diff)에 적용한 것이 리터릿 코드 디프다.

일반적인 코드 리뷰 화면은 변경된 파일의 나열이다. 파일 순서는 알파벳순이고, 변경의 논리적 순서와 무관하다. 리뷰어는 조각난 변경들을 머릿속에서 재조립해야 한다. 에이전트가 만든 큰 변경 앞에서 이 재조립은 자주 포기된다. 그리고 승인 버튼이 눌린다.

리터릿 코드 디프는 순서를 뒤집는다. 변경을 개념의 순서대로 배열하고, 각 단계에 설명을 붙인다. “먼저 저장소 인터페이스를 바꿨다. 왜냐하면. 그 다음 호출부를 고쳤다. 왜냐하면.” 읽는 사람은 변경을 하나의 이야기로 따라간다. 나는 이 문서를 릴리즈 노트처럼 유지보수하는 것도 좋다고 본다. PR마다 리터릿 디프 문서를 하나씩 만들고, README에 인덱스를 두어 접근성을 유지하는 식이다. 코드베이스의 역사가 “누가 언제 무엇을 바꿨다"가 아니라 “왜 이렇게 되었다"로 남는다.

셋째, 서술형 문서

AI가 뽑아내는 문서는 대부분 열거식이다. 불릿 포인트가 정렬된 문서는 한눈에 들어온다. 그것이 장점이자 함정이다. 한눈에 들어오기 때문에 읽었다고 착각하기 쉽고, 논리가 빠진 자리도 눈에 띄지 않는다. 그리고 빨리 잊힌다.

아마존은 이것을 회사 차원에서 실험했다. 베조스는 2004년 임원 회의에서 파워포인트를 금지하고 서술형 메모를 도입했다. 이유가 정확하다. 좋은 서술형 메모가 어려운 것은, 서술 구조가 무엇이 더 중요하고 어떻게 연결되는지에 대한 더 나은 사고를 강제하기 때문이다.8 읽는 쪽도 마찬가지다. 서술형은 열거식보다 읽는 데 시간이 걸린다. 대신 이야기로 읽기 때문에 논리가 끊긴 자리가 드러나고, 읽은 내용이 오래 남는다.

ADR(Architecture Decision Record)로 비교해 보자. 열거식 ADR은 이렇게 생겼다.

결정: 세션 저장소를 Redis로 이전

• 현황: DB 세션 테이블 병목
• 대안: Memcached, DynamoDB, Redis
• 선택: Redis
• 근거: TTL 지원, 운영 경험 보유 Markdown 깔끔하다. 그리고 아무것도 검증할 수 없다. 병목이 얼마나 심했는지, Memcached는 왜 탈락했는지, “운영 경험 보유"가 결정을 정당화할 만큼 중요한 조건이었는지 이 문서는 말하지 않는다. 같은 결정을 서술형으로 쓰면 이렇게 된다.

"지난 분기 트래픽이 두 배로 늘면서 세션 테이블의 락 경합이 응답 지연의 주범이 되었다. 피크 시간대 p99 지연의 60%가 세션 조회에서 나왔다. 캐시 계층 도입이 필요했는데, Memcached는 재시작 시 세션이 전부 날아가 로그인 폭주를 일으킬 수 있어 제외했다. DynamoDB는 지연 요건은 맞췄지만 TTL 정밀도가 분 단위라 세션 만료 정책과 맞지 않았다. Redis는 두 요건을 모두 만족했고, 팀에 운영 경험이 있어 장애 대응 리스크도 낮다. 다만 단일 노드 구성이므로 Redis 장애 시 전체 로그인이 불가능해진다. 이것이 이 설계의 실패 조건이다."

읽는 데 세 배쯤 걸린다. 대신 이 글을 읽은 사람은 질문할 수 있다. “p99의 60%라는 수치는 어디서 나왔나?” “Memcached에 영속화 옵션이 있지 않나?” 열거식 문서 앞에서는 나오지 않던 질문들이다. 논리가 문장으로 이어져 있어야 논리의 구멍도 보인다. 인지부채를 갚는 문서는 빨리 읽히는 문서가 아니라 따져 읽을 수 있는 문서다.