에이전트와 일하는 방법에 대한 대부분의 가이드는 에이전트의 이해도를 최적화하는 데 맞춰져 있다: context 파일, MCP 서버, 문서화된 스킬, 에이전트가 코드베이스를 추론할 수 있도록 올바른 정보를 주입하는 일 등이다. 정작 에이전트가 바꾸고 있는 시스템을 사람이 여전히 이해하고 있는지를 보장하는 방법에 대한 논의는 훨씬 적다.

Addy Osmani는 이해 부채 — AI 생성 코드의 숨은 비용에 대해 훌륭한 글을 썼다. AI는 사람이 코드를 평가할 수 있는 속도보다 훨씬 빠르게 코드를 생성하고, 그 간극이 팀의 코드베이스에 대한 이해를 속속들이 갉아먹는다.

우리는 에이전트의 이해도는 최적화하면서 사람의 이해도는 점점 잃고 있다. 바로 이 간극 때문에 나는 어떻게 일해 왔는지, 그리고 코드베이스를 건강하게 유지하는 이해를 잃지 않으면서 빠르게 움직이기 위해 무엇이 먼저 갖춰져야 하는지를 깊이 고민하게 됐다.

코드 리뷰가 하던 일

리뷰는 단순한 품질 보증 절차가 아니다. 팀 전체에 이해가 퍼지는 방식이다. 누군가 당신의 코드를 승인할 만큼 꼼꼼히 읽을 때, 그는 무엇이 왜 바뀌었는지에 대한 멘탈 모델을 구축한다. 그것이 팀이 자신의 코드베이스에 대해 집단적으로 방향을 유지하는 메커니즘이다.

에이전트는 코드를 더 나쁘게 만들어서가 아니라, 리뷰 프로세스가 감당하도록 설계된 속도보다 더 빠르게 코드를 생성함으로써 이 메커니즘에 부담을 준다. 때로는 빠르게 움직이며 에이전트를 신뢰하는 것이 옳은 판단이다. 특히 테스트 커버리지가 탄탄하고 잘 이해하고 있는 코드베이스 영역에서는 더욱 그렇다. 하지만 일이 잘못되면 그 여파는 누적된다. 제대로 이해되지 않은 변경 하나하나가 다음 리뷰를 덜 의미 있게 만든다. 이미 어긋나기 시작한 멘탈 모델을 바탕으로 새로운 코드를 추론해야 하기 때문이다.

직접 시도하며 배운 것

이 문제에 부딪혔을 때 나의 첫 본능은 프로세스였다. 에이전트가 만든 대규모 변경 묶음을 더 작고 순서가 있는 MR들로 나누는 것. 각각이 이야기의 일관된 한 부분을 담당하고, 각각이 독립적으로 배포 가능하도록 만드는 것이다. 마치 빨리 감기를 한 뒤 슬로우 모션으로 다시 보는 것처럼. 일리는 있다. 커밋을 하나씩 리뷰할 수 있도록 재구성한 큰 MR이 별 마찰 없이 머지된 적도 있다. 변경을 읽기 쉽게 만들고 일관된 이야기를 전달하는 것은 언제나 옳은 본능이다.

하지만 나는 레거시 코드베이스에 쌓인 다섯 개의 MR을 드래프트 상태로 그대로 두고 있기도 하다. 변경이 무엇을 하는지는 이해하지만, 기존 테스트 커버리지가 깨질 수 있는 사이드 이펙트나 기능적 동작을 잡아낼 거라고는 믿지 못한다. 그런 확신 없이는 그 모든 것의 기저에 수동 검증을 기대한다는 암묵적인 전제가 깔리고, 이는 당신이 처리하지 않은 리스크를 리뷰어에게 떠넘기는 셈이다.

프로세스는 변경을 더 읽기 쉽게 만들 수 있다. 하지만 존재하지 않는 안전망을 대신할 수는 없다.

지금의 이해는 어떤 모습인가

이제는 한 줄 한 줄 뜯어보는 방식이 아니다. 더 이상 현실적이지 않고, 그렇다고 우기는 건 일부 리뷰를 요식행위로 만드는 일일 뿐이다. 그렇다고 아무것도 하지 않는 것도 아니다. 나는 이해가 세 가지 차원에서 이뤄진다고 본다.

첫 번째는 행위적 차원이다: 예상대로 동작하는가? 여기서 테스트 커버리지는 팀이 할 수 있는 가장 중요한 투자가 된다. 사용자가 실제로 거치는 경로 전반에 걸쳐 실제 동작을 커버하는 진짜 커버리지, 그리고 컴파일 타임에 타입 에러를 잡아내는 타입 안정성과 함께 말이다. 컴파일러와 테스트 스위트가 제 역할을 한다면 리뷰어는 모든 라인을 일일이 추적할 필요가 없다. 커버리지가 얕거나 팀이 수동 테스트에 의존해 온 곳이야말로 에이전트의 속도가 더 이상 속도가 아니라 방치로 바뀌는 지점이다.

두 번째는 아키텍처적 차원이다: 변경이 어떻게 동작하는지 큰 그림에서 이해하고, 시스템에 대한 멘탈 모델을 업데이트할 수 있는가? 이는 에이전트가 직접 도울 수 있는 부분이다. 에이전트에게 변경 묶음에서 의미 있는 결정들을 요약해 달라고 요청하라. 기계적인 변경 사항이 아니라 사람이 평가해야 할 선택들, 즉 어떤 대안을 고려했는지, 자명하지 않은 결정이 어디에 있는지, 작성자가 코드 워크스루에서 짚고 넘어갈 지점 같은 것들이다. 그것을 MR 설명의 기반으로 삼아라. 나는 이를 여러분의 워크플로에 바로 붙여 쓸 수 있는 에이전트 스킬로 패키징해 두었다. 리뷰어가 에이전트가 생성한 변경 묶음을 더 쉽게 이해할 수 있도록 돕는, 구조화된 MR 설명과 커밋 구조 추천을 생성해 주며, 이를 검토해 활용할 수 있다.

세 번째는 표준 차원이다: 코드가 팀이 합의한 컨벤션을 따르는가? 린팅이 이 중 상당 부분을 자동으로 처리하며, 린터로 밀어 넣을 수 있는 것 하나하나가 사람이 리뷰할 때 신경 써야 할 일을 덜어준다. 린팅으로 잡아낼 수 없는 부분에 대해서는 이전에 에이전트 스킬에 대해 쓴 적이 있다. 표준이 코드를 작성하는 에이전트를 가이드할 만큼 잘 문서화되어 있다면, 그 표준은 코드를 리뷰하는 에이전트를 가이드할 만큼도 충분히 문서화된 것이다.

과정을 보여라

좋은 저자로서의 태도는 언제나 중요했다. 지금은 더욱 그렇다. 리뷰어는 당신의 에이전트 세션에 함께 있지 않았고, 당신이 무엇을 하려 했는지, 어떤 트레이드오프를 고려했는지, 에이전트가 내린 결정 중 당신이 의식적으로 유지한 것이 무엇인지에 대해 아무런 배경 지식도 갖고 있지 않다. 그 맥락은 diff를 통해 전달되지 않는다. 의도적으로 전달해야 한다.

그것은 사람의 리뷰가 필요한 아키텍처적 결정을 짚어내고, 무엇이 왜 바뀌었는지를 설명한다는 뜻이다. 코드를 읽기 전에도 변경의 이야기가 리뷰에서 명확히 드러나도록 커밋 구조를 신중하게 고민한다는 뜻이다. 에이전트가 만들어낸 것을 당신이 이해했다는 것을 보여주는 설명을 작성한다는 뜻이다. 명확하게 설명할 수 없다면, 당신이 수동적인 위임으로 넘어가 버렸을 위험이 있기 때문이다.

Addy가 인용한 Anthropic 연구에 따르면, AI를 수동적 위임 수단으로 사용한 엔지니어—즉, 적극적으로 관여하지 않고 그저 코드를 생성하게 둔 엔지니어—는 AI를 사고 도구로 활용한 엔지니어보다 이해도 테스트에서 유의미하게 낮은 점수를 받았다. 에이전트는 엔지니어를 대체하지 않는다. 그것은 도구이며, 단순히 동작한다는 사실뿐 아니라 무엇을 왜 하는지 여전히 이해해야 한다. 그 이해가 바로 리뷰어가 마땅히 받아야 할 것이며, 처음부터 다시 재구성하도록 내버려 둘 것이 아니라 그 이해로 안내해야 한다.

모든 변경이 같은 리스크를 갖거나 같은 깊이의 리뷰를 요구하는 것은 아니며, 그 점을 명시하는 것 역시 좋은 저자 의식의 일부다. Ship / Show / Ask는 이를 위한 유용한 프레임으로, 변경의 성격과 팀과 이미 형성된 신뢰를 바탕으로 리뷰 수준을 조율한다.

빠르게 움직이기 위해 필요한 것

드래프트에 쌓여 있는 다섯 개의 MR은 프로세스 때문에도, 내가 코드를 이해하지 못해서도 막혀 있는 것이 아니다. 안전망이 없기 때문에 막혀 있다. 그것이 첫 번째 의무다. 출시한 뒤가 아니라 출시하기 전에 고쳐야 한다.

하지만 저자로서의 역할 없이 탄탄한 테스트 스위트만 갖춘다면 리뷰어는 그저 아무것도 깨지지 않았다는 것만 확인할 수 있을 뿐이다. 그것은 무엇이 바뀌었는지, 왜 바뀌었는지, 에이전트가 결정한 것 중 당신이 의식적으로 유지한 것이 무엇인지 이해하는 것과는 다르다. 에이전트는 속도를 제공한다. 그 속도를 진짜로 만드는 것은 단순히 동작한다는 사실이 아니라, 무엇을 왜 만들었는지 설명할 수 있는 능력이다.