에이전트와 함께 일하는 방법에 대한 대부분의 가이드는 에이전트의 이해도를 높이는 데 최적화되어 있습니다. 컨텍스트 파일, MCP 서버, 문서화된 스킬 등 에이전트가 코드베이스를 추론할 수 있도록 올바른 정보를 주입하는 데 초점이 맞춰져 있습니다. 정작 에이전트가 바꾸고 있는 시스템을 인간이 여전히 이해하고 있는지를 보장하는 이야기는 훨씬 적습니다.

Addy Osmani는 이해 부채(comprehension debt)에 대한 훌륭한 글을 썼습니다. AI가 생성한 코드의 숨은 비용에 대한 글입니다. AI는 인간이 평가할 수 있는 속도보다 훨씬 빠르게 코드를 생성하고, 그 간극은 팀이 자신의 코드베이스에 대해 가진 이해를 속속 비워 냅니다.

우리는 에이전트의 이해도는 최적화하면서 인간의 이해도는 침식되도록 두고 있습니다. 바로 그 간극 때문에 저는 제가 일해 온 방식을, 그리고 이해를 잃지 않고 빠르게 움직이기 위해 무엇이 먼저 갖춰져야 하는지를 곰곰이 생각하게 되었습니다. 코드베이스를 건강하게 유지하는 그 이해 말입니다.

코드 리뷰가 하던 일

리뷰는 단순한 품질 보증이 아닙니다. 팀 안에서 이해가 퍼지는 통로입니다. 누군가 여러분의 코드를 승인할 만큼 꼼꼼히 읽을 때, 그는 무엇이 왜 바뀌었는지에 대한 멘탈 모델을 구축하게 됩니다. 팀이 코드베이스에 대해 집단적으로 방향을 잃지 않는 메커니즘이 바로 그것입니다.

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

직접 시도하며 배운 것

이 문제에 부딪혔을 때 제 첫 번째 본능은 프로세스였습니다. 거대한 에이전트 변경 묶음을 더 작고 순서가 있는 MR들로 나누는 것입니다. 각각이 이야기의 일관된 한 부분을 담당하고, 각각이 개별적으로 배포 가능하도록 말입니다. 빨리 감기로 달린 뒤 슬로모션 리플레이를 보는 것과 같습니다. 분명 일리는 있습니다. 커밋을 하나씩 리뷰할 수 있도록 재구성한 큰 MR 하나는 마찰 없이 머지되었습니다. 변경 사항을 읽기 쉽게 만들고 일관된 이야기를 들려주는 것은 언제나 올바른 본능입니다.

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

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

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

한 줄 한 줄 뜯어보는 방식이 아닙니다. 이제는 더 이상 현실적이지 않으며, 그렇지 않은 척하는 것은 일부 리뷰를 요식행위로 만들 뿐입니다. 그렇다고 아무것도 하지 않는 것도 아닙니다. 저는 세 가지 층위에서 작동한다고 생각합니다.

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

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

세 번째는 표준 층위입니다. 코드가 팀이 합의한 컨벤션을 따르고 있는가? 린팅이 이 중 상당 부분을 자동으로 처리하며, 린터로 밀어 넣을 수 있는 것은 무엇이든 인간 리뷰어가 신경 써야 할 일이 하나 줄어드는 셈입니다. 린팅으로 잡을 수 없는 것들에 대해서는 이전에 에이전트 스킬에 대해 쓴 적이 있습니다. 여러분의 표준이 코드를 작성하는 에이전트를 가이드할 만큼 잘 문서화되어 있다면, 코드를 리뷰하는 에이전트를 가이드할 만큼도 잘 문서화되어 있는 것입니다.

과정을 보여주세요

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

이는 인간 리뷰어가 필요한 아키텍처적 결정을 표시하고, 무엇이 왜 바뀌었는지를 설명해야 함을 의미합니다. 코드 자체를 읽기 전에도 변경의 이야기가 리뷰에서 명확히 드러나도록 커밋 구조를 신중하게 고민해야 함을 의미합니다. 에이전트가 만들어 낸 것을 여러분이 이해했음을 보여주는 설명을 써야 함을 의미합니다. 명확하게 설명할 수 없다면, 여러분이 수동적 위임으로 넘어가 버렸을 위험이 있기 때문입니다.

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

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

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

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

하지만 저자 의식에 대한 노력 없는 탄탄한 테스트 스위트만으로는 리뷰어가 그저 아무것도 깨지지 않았음을 확인하는 데 그치게 됩니다. 그것은 무엇이 바뀌었는지, 왜 바뀌었는지, 에이전트가 결정한 것 중 여러분이 의식적으로 유지한 것이 무엇인지를 이해하는 것과는 다릅니다. 에이전트는 여러분에게 속도를 제공합니다. 그 속도를 진짜로 만드는 것은 단순히 동작한다는 사실이 아니라, 무엇을 왜 만들었는지 설명할 수 있는 능력입니다.