PR은 멀쩡해 보이는데도 어딘가 잘못된 느낌이 들 때
AI를 붙여 몇 주만 개발해 봤어도, 아마 이 감각을 이미 알고 있을 겁니다.
PR을 엽니다. 코드는 충분히 깔끔합니다. 이름도 무난합니다. 테스트도 있습니다. 겉으로 보기엔 분명히 망가진 곳이 없습니다. 그런데도 어딘가가 걸립니다.
경계가 조금 흐릿한 걸지도 모릅니다. contract가 명시되지 않고 암묵적으로만 존재하는 걸지도 모릅니다. 정상 흐름은 덮였지만, 진짜 비즈니스 규칙은 아직 누군가의 머릿속에만 남아 있는 걸지도 모릅니다. 치명적인 한 줄을 집어내지는 못해도, 위험은 분명히 느껴집니다.
이게 새로운 리뷰 문제입니다.
대부분의 팀은 아직도 AI 보조 코딩을 오래된 작업 흐름 위에서 돌립니다. 프롬프트를 쓰고, diff를 만들고, PR을 열고, 시니어 엔지니어에게 코드를 충분히 꼼꼼하게 들여다봐서 깨진 invariants, 빠진 edge case, 아키텍처 이탈, 숨어 있는 위험을 잡아내 달라고 합니다.
인간이 구현 대부분을 직접 쓰던 때에는 그 방식이 말이 됐습니다. 하지만 이제 모델이 한 번에 구현, 첫 테스트 스위트, 스키마, 심지어 contract scaffolding까지 만들어내는데, 그 방식은 훨씬 덜 말이 됩니다.
그 지점부터는 시니어의 시간을 한 줄씩 코드 리뷰하는 데 쓰는 것이 더 이상 가장 레버리지가 큰 선택이 아닙니다.
진짜 질문은 더 이상 “이 함수가 그럴듯해 보이는가?”가 아닙니다.
진짜 질문은 “함수가 생기기 전에 우리가 올바른 동작, 경계, invariant를 정의했는가?”입니다.
이게 AI가 만들어내는 작업 흐름의 역전입니다. 코드 리뷰가 사라지는 것은 아닙니다. 하지만 무게중심은 앞단으로 이동합니다. AI 시대에 코드 리뷰는 명세 검토가 됩니다.
왜 이 변화는 체감이 이렇게 다른가
오랫동안 대부분의 엔지니어링 팀은 명세를 보조 자료 정도로 취급해 왔습니다.
코드가 진짜였습니다. doc comment는 힌트였고, ADR은 읽을 시간이 있을 때만 보는 맥락 자료였습니다. 스키마는 “그냥 검증”이었고, Gherkin 파일은 누군가 최신 상태를 유지해 주기만 하면 좋은 정도였습니다.
그 위계가 무너지고 있습니다.
LLM이 명세를 구현 산출물로 빠르고 반복해서 바꿔낼 수 있다면, 명세는 더 이상 부차적인 것이 아닙니다. 시스템의 나머지 부분이 거기서 파생되는 원천 산출물이 됩니다.
그러면 실수를 가장 싸게 잡아낼 수 있는 지점도 달라집니다.
명세가 모호하면, 모델은 틀린 것을 아주 아름답게 구조화된 구현으로 만들어낼 수 있습니다. 깨끗한 코드와 그럴듯한 테스트, 그리고 근거 없는 자신감까지 함께 줄 수 있습니다. 강한 코드 리뷰조차 진짜 문제를 놓칠 수 있습니다. 문제가 문법에 있는 게 아니기 때문입니다. 문제는 의도 안에 있습니다.
지금 이 순간이 까다롭고도 중요한 이유가 여기에 있습니다. AI는 그럴듯한 출력을 만들기 쉽게 해줍니다. 동시에, 무엇을 요청했는지 허술하게 다루는 일을 훨씬 더 위험하게 만듭니다.
명세가 정확하고, 경계가 분명하고, 테스트 가능하면 모든 것이 쉬워집니다. 구현도 쉬워지고, 검증도 쉬워지고, 리뷰도 쉬워지고, CI도 더 강해집니다.
그래서 최고의 인간 리뷰 노력은 각 분기를 손으로 일일이 감사하는 데서 벗어나, 애초에 그 분기의 동작을 정의하는 산출물을 더 단단하게 만드는 쪽으로 옮겨가고 있습니다.
명세는 거대한 요구사항 문서가 아니다
사람들은 “명세”라는 말을 들으면, 쓰기도 싫고 여섯 주 뒤에는 아무도 믿지 않는 비대한 문서를 떠올리곤 합니다.
하지만 여기서 중요한 것은 그런 것이 아닙니다.
실용적인 AI 보조 작업 흐름에서 명세란, 생성과 enforcement에 쓸 수 있을 만큼 의도된 동작을 촘촘하게 정의하는 어떤 산출물이든 될 수 있습니다.
그건 예를 들면 이런 것들입니다.
- boundary rule을 설명하는 Markdown ADR
- 외부 입력 형태를 정의하는 Zod 스키마
- 날카로운 doc comment가 붙은 함수 시그니처
- 관측 가능한 동작을 포착하는 Gherkin 시나리오
- 사전조건과 사후조건을 담은 contract 블록
- reducer 모델 또는 상태 전이 표
이 중 어느 것도 거창할 필요는 없습니다. 도구가 거기서 실제로 유용한 일을 해낼 만큼만 분명하면 됩니다.
중요한 기준선은 그것입니다. 유용한 명세는 사람이 읽을 수 있기만 해서는 안 됩니다. codebase를 둘러싼 시스템이 실제로 활용할 수 있어야 합니다.
좋은 리뷰의 모습은 이렇게 바뀌기 시작한다
예전 모델에서 시니어 엔지니어는 이런 질문에 에너지를 썼습니다.
- 구현이 깔끔한가?
- 작성자가 edge case를 놓쳤나?
- 이 테스트는 충분히 강한가?
- 이 import는 경계를 위반하나?
이 질문들은 여전히 중요합니다. 다만 더 이상 가장 먼저 던져야 할, 레버리지가 가장 큰 질문은 아닙니다.
명세 우선 작업 흐름에서 더 가치 있는 질문은 이런 것들입니다.
- contract 자체가 정말 맞는가?
- 스키마가 진짜 경계를 정의하고 있는가?
- 비즈니스 규칙이 빠짐없이 들어가 있는가?
- ADR이 enforcement를 걸 수 있을 만큼 정밀한가?
- 나열된 속성들이 실제 의미를 표현하고 있는가?
이쪽이 더 좋은 리뷰 질문인 이유는, 좋은 답 하나가 여러 산출물을 한 번에 개선하기 때문입니다.
모호한 ADR 하나를 더 단단하게 만들면, 아키텍처 규칙과 구현 지침, 그리고 CI enforcement를 한 번에 개선하게 됩니다.
약한 스키마를 바로잡으면, 런타임 검증과 타입 추론, 그리고 코드 생성 품질을 한 번에 끌어올리게 됩니다.
contract를 날카롭게 다듬으면, 구현과 테스트, 그리고 mutation testing에 대한 저항성을 한 번에 끌어올리게 됩니다.
레버리지 차이는 여기서 납니다. 더는 산출물을 하나씩 검사하는 것이 아니라, 그 산출물을 빚어내는 대상을 리뷰하게 됩니다.
전통적인 코드 리뷰가 흔들리기 시작하는 이유
전통적인 코드 리뷰는 인간이 주 저자라고 가정합니다. 그리고 리뷰어는 완성된 코드에서 인간의 사고 과정을 역으로 읽어 그 품질을 점검한다고 가정합니다.
AI가 들어오면 그 가정은 매주 더 약해집니다.
모델은 몇 초 만에 그럴듯한 50줄을 만들어냅니다. 곧바로 또 다른 50줄도 만들어냅니다. 그다음 50줄도 마찬가지입니다. 그 흐름 속에 숨어든 의미 이탈을 리뷰어가 손으로 직접 잡아내는 데 전체 프로세스가 기대고 있다면, 리뷰 표면적은 인간의 집중력보다 훨씬 빠르게 커집니다.
그러면 나쁜 균형이 생깁니다.
- 코드 생성은 더 빨라지고
- diff는 더 커지거나 더 자주 생기고
- 리뷰어 피로는 올라가고
- 동작 의미에 대한 확신은 떨어지고
- 팀은 감과 직감, 그리고 “괜찮아 보입니다”로 버티기 시작합니다
그건 확장 전략이 아닙니다. 보기 좋게 포맷된 누적 위험일 뿐입니다.
더 나은 선택은 애초에 주관적 리뷰의 양을 줄이는 것입니다. 더 많은 의미를 deterministic하고 리뷰 가능한 명세에 밀어 넣으십시오. 그리고 그 의미에 코드가 여전히 맞는지 시스템이 검사하게 하십시오.
이걸 현실로 만드는 것은 CI다
이 작업 흐름의 역전은 명세가 enforcement와 연결될 때만 작동합니다.
그렇지 않으면 문서에 이름만 다시 붙여 놓고 사람들이 더 존중해 주길 바라는 것에 불과합니다.
핵심은 명세를 실제로 작동하는 대상으로 만드는 데 있습니다.
그 말은 곧 이런 뜻입니다.
- 아키텍처 결정이 의존성 규칙으로 컴파일되고
- 스키마가 runtime-safe하고 type-safe한 경계를 정의하고
- contracts가 실행 가능한 검사를 생성하고
- 속성 목록이 테스트 생성을 이끌고
- 핵심 의미가 merge gate가 되어야 합니다
바로 그래서 살아 있는 명세가 마침내 보통의 팀에게도 현실적인 선택지가 됩니다. 역사적으로 문서가 썩어버린 이유는, 텍스트와 코드를 손으로 계속 동기화할 시간이 아무에게도 없었기 때문입니다.
AI는 이런 산출물을 쓰고 갱신하는 경제성을 바꿉니다. CI는 그것을 enforcement하는 경제성을 바꿉니다.
둘 다 필요합니다. enforcement 없는 AI는 반듯하게 포장된 drift를 줍니다. 좋은 명세 없는 enforcement는 딱딱한 혼란을 줍니다.
Hard Guard와 Soft Review
이 지점은 Autotomy 철학이 점점 더 옳다고 느껴지는 부분이기도 합니다.
아이디어는 단순합니다. 협상 불가능한 규칙은 hard guard에 넣고, 인간 리뷰는 정말 판단이 필요한 부분에 집중시키는 것입니다.
그 말은 타입, 스키마, contracts, 의존성 규칙, deterministic checks가 이미 알려진 실패 양상을 처리한다는 뜻입니다. 이것들은 매번 실행됩니다. 지치지도 않습니다. 보기 좋게 정리된 diff에 주의를 빼앗기지도 않습니다. 코드가 스태프 엔지니어에게서 나왔는지, 언어 모델에게서 나왔는지도 신경 쓰지 않습니다.
그러면 리뷰 층은 더 작아지고 더 좋아집니다.
시스템이 자동으로 거절할 수 있었던 일에 시니어의 시간을 쓰는 대신, 절충점과 의미, interface, 아키텍처에 시간을 쓰게 됩니다. 경계가 맞는지, contract가 정직한지, 교체된 구현이 정말 interface를 만족하는지, 시스템이 바꾸기 쉬워지고 있는지 아니면 더 어려워지고 있는지를 묻게 됩니다.
이 마지막 부분이 특히 중요합니다.
명세 우선 작업이 주는 가장 건강한 부작용 중 하나는 더 깔끔한 절단면으로 밀어준다는 점입니다. 어떤 module이 contract를 만족하고 checks를 통과하기만 하면 교체할 수 있다면, 각 구현을 성역처럼 대하지 않게 됩니다. 고통스럽게 보존하는 대신 안전하게 교체하도록 설계하게 됩니다.
그건 미묘한 변화지만, 팀이 성장을 다루는 방식을 바꿉니다. codebase가 더 이상 안쪽에서 조심조심 땜질만 해야 하는 대상으로 느껴지지 않습니다. 명시적인 이음새가 있는 시스템처럼 느껴지기 시작합니다.
이건 사실 시니어 엔지니어에게 좋은 소식이다
이 변화가 시니어 엔지니어의 판단을 덜 가치 있게 만드는 것은 아닙니다. 오히려 더 집중되고 더 중요하게 만듭니다.
시니어 엔지니어의 가장 큰 가치는 더 이상 인간 문법 diff 엔진 노릇에 있지 않습니다. 모호함을 해소하고, invariants를 고르고, interface를 다듬고, 절충점을 명시하는 곳에 있습니다.
그 말은 더 많은 시간을 여기에 쓰게 된다는 뜻입니다.
- 정밀한 ADR 쓰기
- contracts와 스키마 정의하기
- 스타일이 아니라 의미 변화를 리뷰하기
- 어떤 속성에 enforcement를 걸어야 하는지 결정하기
- 아키텍처를 merge 가능한 규칙으로 바꾸기
훨씬 더 나은 곳에 비싼 시간을 쓰는 셈입니다.
기계는 구현 세부사항을 메워 넣는 데 아주 강합니다. 하지만 시스템이 스트레스를 받고, 바뀌고, 확장될 때에도 무엇이 반드시 참이어야 하는지를 결정하는 일에서는 여전히 시니어 엔지니어가 훨씬 낫습니다.
프로세스를 거창하게 갈아엎을 필요는 없다
이 얘기는 실제보다 훨씬 더 거창하게 들릴 수 있습니다.
형식 기법 프로젝트를 띄울 필요도 없습니다. 배포를 멈출 필요도 없습니다. 팀을 프로세스에 파묻을 필요도 없습니다.
아주 좁은 변화 하나부터 시작하면 됩니다. 명세 한 종류를 정식 리뷰 대상 산출물로 취급하십시오.
실제로는 이런 순서면 충분합니다.
- 중요한 경계에는 정밀한 doc comment와 스키마를 요구한다
- ADR 변경은 시니어 리뷰 항목으로 다룬다
- 그 산출물에서 테스트와 contracts를 생성한다
- 아키텍처 이탈과 contract drift를 CI에서 enforcement한다
- 스타일만 지적하는 리뷰 코멘트의 우선순위를 낮추고 의미 리뷰를 올린다
그 정도면 문화를 바꾸기에 충분합니다.
더 나은 명세가 후속 리뷰 소모를 줄인다는 걸 팀이 체감하면, 이 방식은 스스로 강화되기 시작합니다. 리뷰는 더 날카로워지고, diff는 덜 무서워지고, 신뢰는 높아집니다.
진짜 전략적 변화
AI와 함께 이기는 팀은 단지 코드를 더 빨리 생성하는 팀이 아닐 것입니다.
그 팀은 인간의 집중력을 작업 흐름에서 가장 좁고, 가장 레버리지가 큰 지점으로 옮기는 팀일 것입니다.
그 지점이 바로 명세입니다.
명세가 주된 산출물이 되면, 코드는 더 이상 한 줄씩 검토할 유일한 대상이 아닙니다. 더 규율 있는 시스템이 만들어내는 하나의 출력이 됩니다.
구현은 여전히 중요합니다. 아주 많이요. 하지만 점점 더 중요한 리뷰 결정은 구현이 생기기 전에 내려집니다.
그래서 AI 시대에 코드 리뷰는 명세 검토가 됩니다.