기억에 남을 정도로 고통스러운 버그를 마주할 때마다, 저는 똑같은 질문을 던지기 시작했습니다. 어떻게 하면 나의 AI 코딩 어시스턴트가 몇 달 후에도, 혹은 한 번도 본 적 없는 저장소(repo)에서도 해당 버그를 다시 발생시키지 않도록 보장할 수 있을까? 메모 파일에 적어두는 것만으로는 충분하지 않습니다. 메모는 대충 훑어보게 되고, 맥락은 요약되며, 세부 사항은 유실되기 때문입니다. 그래서 저는 특정하고 이미 알려진 잘못된 패턴이 코드에 반영되기 전에 이를 즉시 차단하는 작은 훅(hooks) 세트를 구축했습니다.

아이디어: 어렵게 얻은 교훈은 기억되는 것이 아니라 강제되어야 한다

기억을 위한 메모는 제안에 불과합니다. 하지만 모든 파일 쓰기 작업 시 실행되어 0이 아닌 종료 코드(nonzero exit code)로 쓰기를 차단하는 훅은 규칙입니다. 저는 실제로 시간 낭비를 초래했을 때만 어떤 사항을 엄격한 규칙으로 격상시킵니다. 이것은 베스트 프랙티스(best practices)의 희망 목록이 아니라, 특정 사건들의 짧은 목록입니다.

현재 그 목록은 다음과 같은 것들을 차단합니다:

• 한 번 개발 서버의 컴파일 그래프(compile graph)에 약 9,000개의 모듈을 끌어들여 전체 VM을 멈추게 했던 특정 의존성 임포트(dependency-import) 패턴 (정확히 그 "편리한" 임포트 경로는 차단되지만, 동일한 패키지를 일반적인 방식으로 임포트하는 것은 괜찮습니다).
• 컨테이너 상태가 루트 소유(root-owned) 디렉토리로서 저장소의 작업 트리(working tree)에 바인드 마운트(bind-mounted)되는 현상 — 이는 파일 와처(file watchers)와 포매터(formatters)를 조용히 망가뜨리며, 발생 시 관련 없는 툴링 버그처럼 보입니다.
• 어떤 파일에든 개인 키(private key) 자료를 쓰는 것.
• credentials: true와 결합된 와일드카드(Wildcard) 또는 반사된(reflected) CORS 오리진(origins).
• localStorage/sessionStorage에 인증 토큰(Auth tokens)을 쓰는 것.
• 공정하거나 예측 불가능해야 하는 코드 근처에서 시스템 시계로부터 유도된 RNG 시드(seed).

이 각각의 사례는 "어떻게 이런 일이 일어날 수 있지?

차단 훅(blocking hook)은 잘못된 패턴이 안착하는 것을 방지합니다. 별도의 훅은 더 미묘한 실패, 즉 실제로 증명되지 않았음에도 무언가를 "완료(done)"되었다고 선언하는 문제를 방지합니다. git 저장소에 커밋되지 않은 소스 변경 사항이 있다면, 이 훅은 세션당 한 번씩(끈질기게 괴롭히지 않는 수준으로) 저에게 알려줍니다. 즉, 완료되었다고 말하기 전에 실제로 타입 체크(typecheck)를 수행하고, 테스트를 실행하며, 변경 사항이 엔드 투 엔드(end to end)로 작동함을 증명하라고 상기시켜 줍니다. 모델(또는 지친 인간)은 코드가 그럴싸해 보인다는 이유만으로 기쁘게 "이것은 작동합니다"라고 말할 것입니다. 증명(Proof)은 그럴듯함(plausibility)과는 다른 기준입니다.

매번 규칙을 재도출하는 하나의 일반론자 대신 전문가 활용하기

또 다른 요소는 다음과 같습니다. 모든 도메인의 규칙을 동시에 머릿속에 담으려고 노력하는 하나의 어시스턴트 대신, 저는 검토 책임을 관련이 있을 때만 호출되는 좁은 범위의 전문가 리뷰어(specialist reviewers)로 분리했습니다. 예를 들어, 돈을 다루는 불변성(invariants)만을 체크하는 리뷰어(모든 변이(mutation)가 단일 감사 경로를 거치는지, 부동 소수점(floats)으로 계산되어서는 안 되는 것이 있는지 확인), 스마트 컨트랙트(smart contracts)만을 리뷰하는 리뷰어, 특정 웹 프레임워크의 성능 함정(footguns)만을 체크하는 리뷰어, 그리고 강화된 표준에 따라 인증/세션(auth/session) 패턴만을 확인하는 리뷰어 등이 있습니다. 각 리뷰어는 의도적으로 범위를 좁게 설정되었습니다. "모든 것"을 확인하라는 요청을 받은 일반론자는 아무것도 깊이 있게 확인하지 못하는 경향이 있지만, 한 가지를 확인하라는 요청을 받은 전문가는 실제로 그것을 잡아내는 경향이 있습니다.

과거의 나에게 해주고 싶은 말

• 만약 어떤 일이 실제로 디버깅 시간을 낭비하게 만들었다면, 단순히 기록만 하지 마세요. 그것이 다시는 발생하지 않도록 기계적으로 차단할 수 있는 무언가로 바꿀 수 있는지 확인하세요.
• 차단 목록(blocklist)을 짧고 구체적으로 유지하세요. "나를 아프게 했던 바로 그 행동을 하지 마라"라는 규칙은 강제할 수 있지만, "좋은 코드를 작성하라"라는 규칙은 강제할 수 없습니다.
• "잘못된 패턴 방지"와 "주장된 완료 사항 검증"을 분리하세요. 이들은 서로 다른 실패 모드이며 서로 다른 가드레일(guardrails)이 필요합니다.
• 모든 도메인의 규칙을 한꺼번에 담으려는 하나의 리뷰어보다, 좁고 전문화된 리뷰어들이 더 낫습니다.