AGENTS.md가 새로운 코드 리뷰 계약이 되어가고 있다

GitHub은 이번 주에 변경 로그(changelog) 항목보다 더 큰 의미를 지닌 작은 Copilot 코드 리뷰 기능을 추가했습니다.

이제 Copilot 코드 리뷰는 저장소 수준의 AGENTS.md 지침을 읽을 수 있습니다.

이는 삶의 질을 높여주는 좋은 개선 사항처럼 들립니다. 선호도를 파일에 적어두세요. 에이전트(agent)에게 프로젝트가 어떻게 작동하는지 알려주세요. 그러면 이상한 리뷰 코멘트를 덜 받게 될 것입니다. 좋습니다.

하지만 제가 생각하는 더 흥미로운 버전은 이것입니다: 코드 리뷰가 기계가 읽을 수 있는 엔지니어링 판단(engineering judgment)에 의존하기 시작했다는 점입니다.

단순히 스타일 규칙뿐만이 아닙니다. 린트(lint)뿐만이 아닙니다. 단순히 "pnpm을 사용해 주세요"와 같은 요구도 아닙니다.

실제 팀의 취향(taste)입니다.

시니어 엔지니어들이 머릿속에 담아두고 다니는 작은 규칙들 말입니다. 마이그레이션의 흔적들. 로컬 아키텍처 경계. 코드베이스가 유연해 보이지만 실제로는 그렇지 않은 지점들. 한 폴더에서는 허용되지만 다른 폴더에서는 금지되는 패턴들. 서비스의 역사를 알아야만 이해할 수 있는 테스트 전략들.

수년 동안, 그 지식은 지친 인간들이 반복하는 코멘트로서 코드 리뷰 속에 존재해 왔습니다.

이제 우리는 그것을 에이전트(agents)를 위해 글로 적으라는 요구를 받고 있습니다.

좋은 일입니다.

동시에 불편한 일이기도 합니다.

리뷰는 언제나 구문(syntax) 그 이상이었다

코드 리뷰에서 자동화하기 가장 쉬운 부분은 우리가 이미 자동화했어야 했던 부분입니다.

포매팅(Formatting). 사용되지 않는 임포트(Dead imports). 누락된 널 체크(null checks). 기본적인 보안 실수. 명확한 컨벤션(convention)을 위반하는 명명 규칙(Naming). 명백히 실행되지 않는 테스트들. 추가해서는 안 될 의존성(Dependencies).

이것들은 유용한 점검 사항들이지만, 코드 리뷰가 중요한 이유는 이것들이 아니기 때문입니다.

리뷰의 어려운 부분은 판단(judgment)입니다.

이 변경 사항이 이 레이어(layer)에 속하는가? 이 추상화(abstraction)가 시기상조인가? 이 동작이 우리가 절반쯤 진행 중인 마이그레이션과 호환되는가? 여기가 부채(debt)를 상환할 적절한 장소인가, 아니면 실제 위험으로부터 주의를 분산시키는 곳인가? 이 테스트가 사용자가 관심을 갖는 것을 증명하는가, 아니면 단지 우리가 현재 가지고 있는 구현(implementation)만을 증명하는가?

인간은 맥락(context)을 바탕으로 이러한 질문에 답합니다.

그 맥락의 일부는 저장소(repository)에 있습니다. 일부는 문서(docs)에 있고, 일부는 티켓(tickets)에 있습니다. 또 일부는 2021년 이후로 모든 고통스러운 리팩터링(refactor)을 검토해 온 사람의 기억 속에 있습니다.

에이전트(Agents)는 많은 것을 읽을 수 있지만, 자동으로 그 기억의 일부가 되지는 않습니다.

AGENTS.md는 그들에게 지도를 제공하는 한 가지 방법입니다.

이 파일은 마법이 아니다

여기에는 유혹적이지만 잘못된 방식이 있습니다.

팀이 다음과 같이 적힌 AGENTS.md 파일을 만드는 경우입니다:

깨끗한 코드를 작성할 것
베스트 프랙티스(best practices)를 따를 것
단순함을 유지할 것
테스트를 추가할 것
보안을 유지할 것

이것은 동기 부여 포스터가 빈 벽보다 나은 것과 마찬가지로, 아무것도 없는 것보다는 낫습니다.

하지만 이것은 리뷰 계약(review contract)을 만들어내지 못합니다.

유용한 에이전트 지침 파일은 더 국소적(local)이고 더 주관적(opinionated)이어야 합니다. 실제로 당신이 유지 관리하고 있는 시스템으로 인해, 바로 여기, 이 저장소, 이 팀에게 적용되는 사실들을 말해야 합니다.

예를 들면 다음과 같습니다:

API 핸들러(handlers)는 제3자 서비스(third-party services)를 직접 호출해서는 안 됩니다. 통합 계층(integration layer)을 사용하세요.
새로운 백그라운드 작업(background jobs)은 반드시 멱등성(idempotent)을 가져야 하며 재시도(retry)가 안전해야 합니다.
기존 워커 풀(worker pool)이 라이프사이클(lifecycle)을 표현할 수 없는 경우가 아니라면 새로운 큐(queue)를 추가하지 마세요.
고객 테이블(customer table)에 플래그(flags)를 추가하는 것보다 현재의 결제 상태 머신(billing state machine)을 확장하는 것을 선호하세요.
스냅샷 테스트(Snapshot tests)는 이메일 템플릿에는 허용되지만, 비즈니스 로직(business logic)에는 허용되지 않습니다.
데이터베이스 마이그레이션(Database migrations)은 배포(deploy) 중에 이전 버전과 새 애플리케이션 버전이 모두 실행될 수 있도록 유지해야 합니다.
또 다른 날짜 라이브러리(date library)를 도입하지 마세요.

이것이 바로 유용한 내용들입니다.

이것은 보편적이지 않습니다. 화려하지도 않습니다. 이것은 팀이 에이전트에게 레일(rails, 가이드라인)이 어디에 있는지 알려주는 것입니다.

그리고 Copilot 코드 리뷰(Copilot code review)가 이러한 지침을 읽게 되면, 그것들은 누군가가 어쩌면 기억할지도 모르는 문서에 머물지 않습니다. 그것들은 리뷰 표면(review surface)의 일부가 됩니다.

이것은 지침의 소유권을 변화시킨다

어색한 질문은 누가 이 파일을 작성하느냐는 것입니다.

만약 AGENTS.md가 자동화된 리뷰 코멘트에 영향을 미친다면, 그것은 단순한 개발자의 편의 기능이 아닙니다. 그것은 엔지니어링 제어 평면(engineering control plane)의 일부입니다.

그것은 소유권(ownership)이 필요함을 의미합니다.

과도한 관료주의(bureaucracy)를 의미하는 것은 아닙니다. 제발 그것만은 아니길 바랍니다.

하지만 이 파일이 좌절한 모든 리뷰어가 자신의 개인적인 선호도를 인코딩하기 위한 쓰레기통(dumping ground)이 되어서는 안 됩니다. 아무도 동의하지 않는 300개의 규칙이 담긴 프롬프트 형태의 스타일 가이드(style guide)가 되어서도 안 됩니다. 또한, 이 파일이 규제해야 할 바로 그 풀 리퀘스트(pull request)에 의해 아무렇지 않게 재작성되어서도 안 됩니다.

가장 이상적인 모습은 아마 다른 중요한 저장소 정책(repository policy)들과 비슷할 것입니다:

코드베이스의 유지 관리자(maintainers)가 소유함
코드처럼 리뷰됨
동작을 변경할 수 있을 만큼 구체적임
사람이 읽을 수 있을 만큼 충분히 짧음
리뷰 품질이 향상되는지를 관찰함으로써 테스트됨
누군가가 논쟁에서 졌을 때가 아니라, 시스템이 변경될 때 업데이트됨

이 지점에서 "에이전트가 리뷰어를 대체한다"는 이야기는 너무 피상적으로 흐르게 됩니다.

에이전트는 인간의 판단(human judgment)을 제거하지 않습니다. 에이전트는 인간의 판단 중 기록된 부분의 가치를 더 높여줍니다.

만약 팀이 무엇을 원하는지 설명할 수 없다면, 에이전트는 주로 구문(syntax), 파일 이름, 주변 패턴, 그리고 인터넷의 일반적인 조언과 같은 쉬운 표면만을 학습할 것입니다.

작은 변경 사항에는 그것으로 충분할 수도 있습니다.

하지만 실제 시스템의 기이한 부분들에는 충분하지 않습니다.

린트(lint)가 첫 번째 계약이었다

우리는 전에도 이런 경험이 있었습니다. 단지 도구가 더 작았을 뿐입니다.

린터(Linters)는 어떤 취향을 실행 가능한 규칙으로 바꾸었습니다. 포맷터(Formatters)는 리뷰 코멘트의 특정 범주를 완전히 끝내버렸습니다. 타입 시스템(Type systems)은 실수를 더 이른 단계로 옮겼습니다. CI는 "내 컴퓨터에서는 잘 돌아가요"라는 말이 설득력을 잃게 만들었습니다. 코드로서의 정책(Policy-as-code)은 일부 운영 규칙을 회의에서 체크(checks) 단계로 옮겼습니다.

각 단계는 코드 리뷰를 변화시켰습니다.

리뷰어는 세미콜론(semicolon)에 시간을 쓰는 것을 멈추고 동작(behavior)에 더 많은 시간을 쓰기 시작했습니다. 적어도 그것이 약속된 바였습니다.

에이전트 지침(Agent instructions)도 이와 유사한 움직임이지만, 덜 결정론적(deterministic)입니다.

린터는 규칙 위반을 보고하거나 혹은 보고하지 않거나 둘 중 하나입니다. 에이전트는 지침을 읽고, 이를 코드 컨텍스트(context), 모델의 동작, 그리고 프롬프트에 포함된 그 외의 것들과 혼합한 다음, 유용할 수도 있고 그렇지 않을 수도 있는 코멘트를 생성합니다.

따라서 우리는 AGENTS.md가 테스트 스위트(test suite)와 같다고 가장해서는 안 됩니다.

그것은 그보다 훨씬 더 부드러운(softer) 것입니다.

하지만 부드럽다는 것이 쓸모없다는 뜻은 아닙니다.

엔지니어링 조직은 이미 부드러운 계약(soft contracts)을 기반으로 운영되고 있습니다. 아키텍처 원칙(architecture principles), 디자인 리뷰 규범(design review norms), 에스컬레이션 규칙(escalation rules), 소유권 경계(ownership boundaries), 배포 기대치(deploy expectations), 그리고 모든 건강한 팀이 보유한 비공식적인 "우리는 여기서 이런 방식은 쓰지 않습니다"와 같은 지식들이 바로 그것입니다.

차이점은 에이전트(agent)에게는 이러한 부드러운 계약들이 문서로 작성되어 있어야 한다는 점입니다.

잘못된 지침은 노이즈가 심한 리뷰를 생성한다

제가 앞으로 많이 보게 될 것이라 예상하는 실패 모드(failure mode)가 하나 있습니다.

에이전트가 오래되었거나 모호한 지침을 바탕으로 확신에 찬 코멘트를 남기기 시작하는 것입니다.

이제는 승인된 패턴을 사용하지 말라고 사람들에게 말합니다. 몇 달 전에 끝난 마이그레이션(migration) 기간에만 적용되었던 규칙을 반복합니다. 파일에 "절대 안 됨"이라고 적혀 있다는 이유로 합리적인 로컬 예외 사항을 차단합니다. 모든 풀 리퀘스트(pull request)에 똑같이 일반적인 아키텍처 설교를 늘어놓습니다.

이런 상황은 개발자들이 해당 도구를 빠르게 싫어하게 만들 것입니다.

해결책은 저장소 지침(repository instructions)을 포기하는 것이 아닙니다. 해결책은 지침을 살아있는 코드(living code)로 취급하는 것입니다.

만약 어떤 지침이 잘못된 리뷰 코멘트를 생성한다면, 그 지침을 수정하십시오. 지침은 맞지만 에이전트가 이를 제대로 적용하지 못한다면, 지침의 범위를 더 좁게 만드십시오. 규칙에 예외가 있다면 예외 사항을 명시하십시오. 만약 규칙이 실제로는 아키텍처로 포장된 개인적 선호도에 불과하다면, 그것을 제거하십시오.

이것은 지루한 유지보수 작업입니다.

그렇기에 이것이 중요합니다.

AI 리뷰로부터 가치를 얻는 팀은 지침 파일이 가장 긴 팀이 아니라, 지침이 가장 명확한 팀이 될 것입니다.

리뷰 코멘트에는 출처(provenance)가 필요하다

AI 보조 리뷰에서 제가 더 많이 보고 싶은 것 중 하나는 출처(provenance)입니다.

만약 Copilot이 AGENTS.md 때문에 코멘트를 남겼다면, 그렇게 명시하십시오.

해당 지침을 가리키십시오. 작성자와 리뷰어가 어떤 로컬 규칙이 관여되었는지 볼 수 있게 하십시오. 일반적인 모델의 우려 사항과 저장소 특화 계약(repository-specific contract) 사이의 차이를 쉽게 구분할 수 있도록 만드십시오.

이것이 중요한 이유는 인간이 시스템을 디버깅(debug)해야 하기 때문입니다.

인간 리뷰어가 잘못된 피드백을 줄 때는 그 인간과 대화할 수 있습니다. 하지만 에이전트(agent)가 잘못된 피드백을 줄 때는 시스템의 어느 부분에서 그것이 생성되었는지 알아야 합니다: 모델(model), 코드 컨텍스트(code context), 프롬프트(prompt), 리포지토리 지침(repo instructions), 오래된 문서(stale doc), 또는 누락된 예외(missing exception) 중 무엇인지 말입니다.

그러한 추적 경로(trail)가 없다면, 팀은 코멘트를 너무 과하게 신뢰하거나 아니면 완전히 무시하게 될 것입니다.

둘 다 좋지 않습니다.

훌륭한 AI 리뷰는 정체불명의 두 번째 리뷰어처럼 느껴지기보다, 팀 자체 표준의 가시적인 확장처럼 느껴져야 합니다.

핵심 요약 (the punchline)

Copilot 코드 리뷰에서의 AGENTS.md 지원은 작은 기능이지만 심각한 함의를 담고 있습니다.

리포지토리(repositories)는 팀이 코드, 테스트, 설정뿐만 아니라 비인간 협업자(non-human collaborators)를 위한 지침까지 인코딩하는 장소가 되어가고 있습니다.

이것은 올바른 방향입니다.

코드베이스(codebase)는 그 안에서 작동하는 도구들에게 스스로를 설명할 수 있어야 합니다. 리뷰 에이전트(review agent)는 일반적인 모범 사례(best practices) 이상의 것을 알고 있어야 합니다. 이 시스템을 유지 관리 가능하게 만드는 로컬 계약(local contracts)을 알고 있어야 합니다.

하지만 이것은 팀이 이 파일을 진지하게 받아들일 때만 작동합니다.

실제로 반복되기를 원하는 판단 기준을 기록하십시오. 짧게 유지하십시오. 로컬하게 유지하십시오. 다른 정책 파일에 쏟는 것과 동일한 주의를 기울여 이 파일의 변경 사항을 검토하십시오. 오래된 규칙은 제거하십시오. 모호한 취향보다는 구체적인 제약 조건(concrete constraints)을 선호하십시오. 코멘트가 개선되는지 지켜보십시오.

모델은 폴더 이름만 보고 당신의 엔지니어링 문화(engineering culture)를 마법처럼 학습하지 않습니다.

에이전트가 팀의 일원처럼 리뷰하기를 원한다면, 그들이 사용할 수 있는 형태로 팀의 표준을 제공해야 합니다.

그것이 바로 AGENTS.md가 되어가고 있는 모습입니다.

프롬프트(prompt)가 아닙니다.

리뷰 계약(review contract)입니다.

참고 문헌 (references)

제 프로젝트를 테스트하기 위해 저는 Railway를 사용합니다. 시작할 때 $20 USD를 받고 싶다면, 이 링크를 사용하세요.