에이전트를 통해 코드 리뷰를 수행하는 방법

쇼핑 목록 페이지를 상상해 보세요. 페이지가 열리고, 항목이 추가되고, 버튼이 정상적으로 표시됩니다. 하지만 완성된 화면만으로는 코드가 잘 작성되었다는 것을 보장할 수 없습니다. 개발자들은 놓친 오류를 찾고 구현 방식을 논의하기 위해 코드를 따로 검토합니다. 이런 작업은 에이전트에게 맡길 수 있고, 에이전트는 이를 아주 잘 해냅니다. 다만 작업을 제대로 설명해 줘야 합니다.

1. 팀에서 코드를 검토하는 방법

소규모 팀에서 개발자가 작업을 받았습니다. 항목을 추가하고 하나씩 삭제할 수 있는 쇼핑 목록을 만드는 것입니다. 개발자는 코드를 작성하고 빵과 우유를 추가해 본 뒤 빵을 삭제했습니다. 모두 잘 작동했습니다. 작업을 넘기기 전에 개발자는 자신의 변경사항을 다시 읽었습니다. 깜빡 남겨 둔 코드 조각을 지우고 알아보기 어려운 이름을 고쳤습니다. 이것이 자가 검토입니다.

그 다음 개발자가 동료에게 코드를 봐달라고 요청했습니다. 동료는 프로그래밍 언어를 알고 있어서, 추가 기능이 어떻게 만들어졌는지, 프로그램이 삭제할 항목을 어떻게 고르는지, 나머지 목록은 어떻게 되는지 코드를 읽으며 살펴봅니다. 이러한 검토를 코드 리뷰(code review)라고 하며, 검토자를 리뷰어라고 합니다.

동료가 한 가지를 발견합니다. 프로그램이 삭제할 항목을 이름으로 고른다는 점입니다. 목록에 "우유" 항목이 두 개 있으면 하나를 지우려고 눌렀을 때 둘 다 삭제될 수 있습니다. 작성자는 빵과 우유로 확인했습니다. 이런 경우는 그저 마주치지 않았을 뿐입니다.

리뷰어가 해당 코드 섹션 옆에 댓글을 남깁니다. "지금은 같은 이름의 항목이 모두 삭제됩니다. 같은 항목을 여러 개 허용하나요? 그렇다면 선택한 항목만 삭제해야 합니다." 작성자가 요구사항을 확인해 줍니다. 같은 항목은 서로 다른 사람을 위해 추가했을 수 있으니 허용됩니다. 논의 후 작성자는 항목을 고르는 방식을 바꿉니다. 동료는 수정된 코드를 다시 보고 지적사항이 반영되었는지 확인합니다.

다이어그램은 지적사항이 나온 경우의 리뷰 과정을 보여 줍니다. 코드는 작성자에게서 동료에게 넘어갔다가 수정을 위해 다시 돌아옵니다. 다시 봐도 의문이 남으면 논의와 수정을 반복합니다. 중요한 지적사항이 없으면 동료가 변경을 승인합니다.

평범한 작업 주기는 이렇습니다. 작성하고, 보여 주고, 지적을 받고, 논의하고, 고칩니다. 지적사항이 여러 개일 때도 있고 하나도 없을 때도 있습니다. 작성자가 자신의 결정을 설명하고 동료가 문제 제기를 거두는 경우도 있습니다. 리뷰라고 해서 모든 댓글에 동의해야 하는 것은 아닙니다.

이런 검토에서는 코드가 이해하기 쉬운지도 논의합니다. 다음 개발자가 코드를 파악할 수 있는지, 규칙 하나를 바꾸려고 여러 곳을 고쳐야 하지는 않는지 살펴봅니다. 그 과정에서 동료는 프로그램의 새 부분이 어떻게 만들어졌는지도 알게 됩니다. 프로젝트에 대한 지식이 작성자에게만 머물지 않고 점차 여러 사람에게 퍼집니다.

리뷰와 테스트를 헷갈리기 쉽습니다. 항목 두 개를 추가하고 버튼을 누르는 것은 실행 중인 프로그램의 동작을 확인하는 일입니다. 삭제 코드를 읽으며 어떤 항목이 선택될지 따져 보는 것이 리뷰입니다. 리뷰 중에 프로그램을 실행하여 추측을 확인할 수 있습니다. 이 두 가지 방법은 서로를 보완합니다.

2. 에이전트에게 리뷰를 맡기는 방법

이제 Claude Code가 여러분의 설명대로 쇼핑 목록을 만들었다고 상상해 보세요. 페이지에서 무슨 일이 일어나야 하는지는 설명할 수 있지만, 프로그램 로직을 읽을 수는 없습니다. 리뷰의 기술적인 부분도 에이전트에게 맡길 수 있습니다. 에이전트가 파일을 읽고 지적사항을 쉬운 말로 설명해 줍니다.

팀 이야기에서 본 역할은 그대로입니다. 코드 작성자가 있고, 별도의 일을 맡은 검토자가 있습니다. Claude Code에서는 이를 위해 서브에이전트(subagent)를 사용할 수 있습니다. 주 에이전트가 특정 작업을 맡기는 도우미입니다. 여기서는 코드를 읽고 지적사항을 돌려줍니다.

작성자에게 자신의 작업을 다시 검토해 달라고 하는 것도 도움이 됩니다. 별도의 리뷰어는 다른 시각을 더해 줍니다. 리뷰어는 결과를 평가하는 일을 맡으니까요. 어떤 해결 방식이 허용되는지 알 수 있도록 리뷰어에게 요구사항을 전달하세요. 예를 들어 같은 이름의 항목을 금지하면 삭제 문제는 겉보기에는 사라지지만, 페이지의 의도된 동작이 바뀌어 버립니다.

Claude Code의 리뷰 관련 권장사항에서는 별도의 검토자를 두고 기준을 명시하라고 권합니다. 같은 곳에서 올바른 동작과 요구사항에 영향을 주는 지적사항에 집중하라고도 조언합니다. 이를 프로젝트의 작은 부분에 적용해 봅시다.

리뷰를 진행하는 데 여러분이 할 일은 많지 않습니다. 원하는 동작을 설명하고, 확인된 문제 중 무엇을 고칠지 고르면 됩니다. 프로그램 로직을 읽고, 원인을 찾고, 기술적인 반론을 따져 보는 일은 에이전트에게 맡길 수 있습니다.

다이어그램에는 세 가지 역할이 있습니다. 여러분은 요구사항을 정하고 고칠 것을 고릅니다. 주 에이전트는 작업을 조율하고 코드를 수정합니다. 검토자들은 코드와 지적사항을 살펴봅니다. 주 에이전트는 검토자들에게 필요한 자료를 넘기고 결과를 여러분에게 전해 줍니다. 확인된 문제가 없으면 수정 단계는 건너뜁니다. 아래에서 이 순서를 세 개의 요청으로 진행해 보겠습니다.

결과적으로 여러분은 문제에 대한 알기 쉬운 설명, 그 문제의 재검토 결과, 수정 보고서를 얻게 됩니다. 지적사항이 틀린 것으로 밝혀져도 얻는 것이 있습니다. 불필요한 수정을 피한 셈이니까요.

이런 검토를 맡길 고정 도우미를 설정하고 싶다면 서브에이전트를 만들고 실행하는 방법에 관한 글이 도움이 됩니다. 더 자세한 작업 지시를 준비하는 방법은 브리프와 결과 형식에 관한 글에서 다룹니다.

요청 1. 작성된 코드 검토하기

프로젝트 폴더에서 Claude Code를 실행하세요. 다음 세 요청은 주 세션에 보냅니다. 도우미에게 일을 넘기는 것은 주 에이전트가 알아서 합니다. 여기서부터는 연습용 쇼핑 목록을 예로 듭니다. 여러분의 프로젝트에서는 동작 설명을 바꿔 쓰세요.

별도의 서브에이전트에게 현재 프로젝트의 쇼핑 목록 코드 리뷰를 맡겨 주세요.
항목 추가와 삭제를 확인해 주세요.
요구사항: 같은 이름은 허용됩니다. 선택한 항목만 삭제됩니다.
빈 항목은 추가할 수 없습니다.

현재 코드와 관련된 프로젝트 부분을 읽어 주세요.
이 요구사항을 어기는 오류를 찾아 주세요.
코드는 바꾸지 마세요. 새 기능도 추가하지 마세요.
지적사항마다 쉬운 말로 설명해 주세요.
무엇이 잘못될 수 있는지, 어떤 동작에서 그런지, 왜 그렇게 판단했는지.
다른 에이전트가 이어서 확인할 수 있도록 코드 위치를 적어 주세요.
문제가 없으면 없다고 써 주세요. 무엇을 확인했고
무엇을 아직 모르는지 나열해 주세요. 보고서는 REVIEW_REPORT.md에 저장해 주세요.
저는 프로그래밍 언어를 모릅니다. 코드를 읽지 않아도 이해할 수 있게 결론을 설명해 주세요.

REVIEW_REPORT.md 파일은 평범한 텍스트 보고서가 됩니다. 이름은 우리가 정한 것이고 다른 이름이어도 괜찮습니다. 이 이름은 다음 요청에서 어떤 지적사항을 재검토할지 알려 주는 역할을 합니다. "코드는 바꾸지 마세요"라는 조건은 검토와 수정을 구분해 줍니다. 보고서를 쓰는 것은 허용됩니다.

이 예에서 쓸모 있는 답변은 이런 식일 수 있습니다. "같은 이름의 항목을 두 개 추가한 뒤 하나를 삭제하면 둘 다 사라집니다. 코드가 이름으로 항목을 고르기 때문에 일치하는 두 항목 모두에 영향을 줍니다." 이것은 연습용 답변 예시일 뿐, 여러분의 프로젝트를 검토한 결과가 아닙니다.

여러분은 결과를 이해할 수 있습니다. 사용자가 남겨 두려던 항목을 잃게 된다는 것이죠. 파일 이름과 코드 위치는 다음 에이전트가 원인을 찾는 데 필요합니다. 그 부분을 여러분이 직접 분석할 필요는 없습니다.

3. 의견을 재검토하는 방법

리뷰어 에이전트도 실수를 합니다. 예를 들어 "목록에 빈 항목을 추가할 수 있습니다"라고 적습니다. 그럴듯하게 들립니다. 하지만 빈 입력을 막는 검사는 이미 프로그램의 다른 부분에 있고, 리뷰어는 그 부분을 읽지 않았습니다. 이 지적사항은 존재하지 않는 문제를 설명하고 있습니다.

이렇게 확신에 차 있지만 지어낸 주장을 흔히 AI의 환각이라고 부릅니다. 리뷰에서는 특히 곤란합니다. 에이전트가 수정을 제안하면, 이미 제대로 동작하던 코드를 고치느라 시간을 쓰게 됩니다. 그래서 작성된 코드뿐 아니라 그 코드에 대한 지적사항도 다시 확인하는 것이 좋습니다.

첫 단계는 이미 밟았습니다. 작성자의 작업을 검토하게 했으니까요. 이제 다른 검토자에게 보고서와 현재 프로젝트를 함께 넘깁니다. 이 검토자의 일은 각 지적사항이 사실인지 가려내는 것입니다. 첫 번째 리뷰어와 의견이 달라도 괜찮습니다.

요청 2. 리뷰어의 보고서 검증하기

다른 서브에이전트에게 REVIEW_REPORT.md를 현재 프로젝트 코드와
이전 요청의 요구사항에 비추어 재검토하도록 맡겨 주세요.
그 요구사항을 서브에이전트에게 명시적으로 전달해 주세요.

지적사항마다 설명된 문제가 실제로 있는지 확인해 주세요.
관련된 코드 부분도 확인해 주세요. 필요한 처리가 이미 있을 수 있습니다.
첫 번째 보고서를 증거로 여기지 마세요. 결론을 내리는 데 실행 확인이
필요하면 사용할 수 있는 수단으로 실행해 주세요.
프로젝트 코드는 바꾸지 마세요.

항목마다 확인됨, 반박됨, 아직 판단할 수 없음 중 하나로 표시해 주세요.
근거는 이해하기 쉬운 말로 설명해 주세요.
코드를 읽고 내린 결론과 실제로 실행한 검사 결과를 구분해 주세요.
실행하지 않은 검사를 실행한 것처럼 쓰지 마세요.
결과를 REVIEW_CHECK.md에 저장하고 저에게 짧게 설명해 주세요.

이제 재검토 결과가 담긴 REVIEW_CHECK.md가 생깁니다. 이 연습 사례에서 두 번째 에이전트는 같은 이름 문제는 확인하고, 빈 입력에 대한 지적은 반박할 수 있습니다. "빈 문자열은 항목이 추가되기 전에 거부됩니다. 첫 번째 리뷰어가 이 검사를 놓쳤습니다."

이것만으로도 다음에 무엇을 할지 고르는 데 도움이 됩니다. 삭제 문제는 수정으로 넘기면 됩니다. 빈 입력은 이 지적사항 때문에 바꿀 필요가 없습니다. 에이전트가 "아직 판단할 수 없음"이라고 쓰면 어떤 정보가 부족했는지 설명해 달라고 하세요. 때로는 여러분에게 묻는 질문일 수도 있습니다. 예를 들어 같은 이름의 항목을 물건 하나로 볼지 두 개로 볼지 같은 것입니다.

재검토는 지어낸 지적사항을 걸러 내는 데 도움이 되지만, 완전히 없애 준다고 보장하지는 않습니다. 두 에이전트가 같은 실수를 되풀이할 수도 있습니다. 그래서 답변에는 근거가 필요합니다. 검토자가 프로젝트에서 무엇을 찾았는지, 실행해서 어떤 결과를 얻었는지 말입니다. "이전 에이전트와 같은 의견입니다" 한마디로는 부족합니다.

4. 수정 및 재검토

이제 무엇을 고칠지 고르세요. 그러려면 문제가 페이지의 의도된 동작에 어떤 영향을 주는지만 이해하면 됩니다. 이 예에서는 남겨야 할 항목까지 지워지는 것이 분명히 문제이니 이 항목을 고릅니다. 정렬을 추가하자는 제안은 나중으로 미뤄도 됩니다. 삭제 수정과는 어차피 관계가 없으니까요.

선택한 지적사항을 통째로 에이전트에게 넘기세요. 그래야 "첫 번째 오류를 고쳐 줘"가 무슨 뜻인지 에이전트가 짐작할 필요가 없습니다. 수정한 뒤 결과를 다시 확인해 달라고도 요청하세요. 팀 이야기의 다음 장면과 같습니다. 동료가 수정된 버전을 다시 보는 것이죠.

요청 3. 수정하고 결과 확인하기

REVIEW_CHECK.md에서 확인된 문제를 고쳐 주세요.
항목 하나를 삭제하면 같은 이름의 항목이 모두 사라지는 문제입니다.
선택한 항목만 삭제되어야 합니다. 같은 이름은 허용됩니다.
리뷰의 다른 제안은 지금 반영하지 마세요.

수정한 뒤 사용할 수 있는 수단으로 항목 추가와 삭제를 확인해 주세요.
같은 이름의 항목 두 개를 추가하고 삭제하는 경우도 포함해 주세요.
그다음 별도의 서브에이전트에게 수정된 코드의 재리뷰를 맡겨 주세요.
원인이 해결되었는지, 추가와 삭제가 망가지지 않았는지 확인하게 해 주세요.
원래 요구사항과 수정한 문제의 설명을 그 서브에이전트에게 전달해 주세요.

무엇이 바뀌었는지, 어떤 확인을 했는지, 재리뷰 결과가 어땠는지
저에게 쉬운 말로 설명해 주세요.
확인하지 못한 것이 있으면 따로 알려 주세요.
새로운 개선으로 작업 범위를 넓히지 마세요.

여러분의 프로젝트에서는 쇼핑 항목에 관한 문단을 여러분의 보고서에서 확인된 지적사항으로 바꾸세요. 나머지 순서는 그대로 두어도 됩니다. 수정, 확인, 결과에 대한 별도의 검토입니다.

좋은 결과 보고는 구체적입니다. "이제 각 항목이 따로 삭제됩니다. 같은 이름의 항목 두 개로 확인했을 때 두 번째 항목은 그대로 남았습니다. 재리뷰에서 기존 오류의 원인은 발견되지 않았습니다." 이런 보고는 실제로 그런 확인을 거친 뒤에만 쓸 수 있습니다. 에이전트가 코드를 읽기만 했다면 그렇다고 밝혀야 합니다.

여러분이 직접 페이지를 열어 평소 하던 동작을 해 볼 수도 있습니다. 여기에는 프로그래밍 언어 지식이 필요 없습니다. 이것은 눈에 보이는 결과를 한 번 더 확인하는 것이고, 수정에 대한 기술적인 리뷰는 여전히 에이전트가 맡습니다. 에이전트가 실행으로 확인할 수단이 부족했다면, 보고서에는 "모두 확실히 동작합니다"라는 약속 대신 알기 쉬운 한계가 적혀 있을 것입니다.

매번 끝없는 손질로 이어갈 필요는 없습니다. 선택한 문제가 해결되고 확인되었으며 재리뷰에서 관련 오류가 나오지 않았다면 이 작업은 끝내도 됩니다. 그게 전부입니다. 새로운 바람은 따로 논의할 일입니다.