풀 리퀘스트 병목 현상 해결하기

조직은 역사적으로 리뷰되지 않은 많은 풀 리퀘스트로 어려움을 겪어왔으며, 이는 개발 워크플로우에서 AI가 널리 채택되기 훨씬 전부터 존재한 과제입니다. 이 문제는 최근 AI 에이전트가 생성하는 새로운 제약과 증가된 PR 물량으로 인해 극적으로 확대되었습니다.

Matt Pocock은 AI가 생성한 기여의 유입을 수용하기 위해 리뷰 프로세스를 가속화하더라도 코드 품질을 유지하거나 심지어 향상시키는 것이 목표라고 말했습니다. 이를 위해서는 인간 개발자와 AI 시스템 간의 상호작용을 관리하는 전략적 접근이 필요합니다.

에이전트는 인간의 행동이 아니라 결정론적 코드를 통해 버그 수정이나 데이터베이스 쿼리 같은 작업을 시작하는데, 이 과정은 보호 장치 없이 사용될 경우 저품질 풀 리퀘스트의 "슬롭 대포"를 만들어낼 위험이 있습니다. 이 접근 방식은 작업의 초기 단계를 자동화하여 개발 노력을 확장할 수 있게 합니다.

그러나 적절한 보호 장치를 구현하지 않고 이러한 자동화 메커니즘에 과도하게 의존하면 관리할 수 없는 양의 저품질 풀 리퀘스트가 발생할 수 있습니다. Matt Pocock은 통제 없이 팩토리를 통해 코드를 지속적으로 가속화하면 리뷰가 불가능한 수준 이하의 PR이 "슬롭 대포"처럼 쏟아질 것이라고 경고했습니다.

AI가 생성한 코드의 유입을 관리하고 품질을 유지하려면 자동화된 검사, 자동화된 리뷰, 인간 리뷰의 세 가지 뚜렷한 통제 계층 시스템이 필요합니다. 1950년대부터 개발의 필수 요소였던 자동화된 검사는 결정론적 테스트, 린팅, 타입 검사 및 코드 품질 지표를 포함합니다.

두 번째 계층은 자동화된 리뷰로, AI 에이전트가 기본 테스트로 포착할 수 없는 코드 구조와 뉘앙스를 평가하여 더 정교한 필터 역할을 합니다. 마지막 계층은 인간 리뷰로, 최고 기준을 보장하기 위해 비판적 판단을 적용하며, 궁극적인 목표는 초기 코드 품질을 극대화하여 인간 개입을 최소화하는 것입니다.

자동화된 검사는 인간의 노력이 아니라 CPU 주기를 소비하기 때문에 저렴하지만 기만적일 수 있습니다. 지적된 바와 같이, 특히 항진명제적 테스트가 실패를 숨길 때 녹색 CI 상태가 코드가 프로덕션에 준비되었음을 보장하지는 않습니다. 여기에는 코드 일관성을 보장하고 기본 오류를 포착하는 ESLint 및 Prettier 같은 도구가 포함됩니다.

유용성에도 불구하고 자동화된 검사는 완벽하지 않습니다. "녹색 CI" 상태가 코드가 프로덕션에 준비되었음을 자동으로 보장하지는 않습니다. Matt Pocock은 이러한 검사가 더 깊은 문제를 감지하지 못하고 "거짓말"할 수 있다고 설명했습니다.

AI 생성 코드의 흔한 문제는 항진명제적 테스트의 생성으로, 테스트가 구현 세부 사항이 자기 자신과 같다고 주장하여 실질적으로 유용한 것을 테스트하지 않습니다. 자동화 및 인간 리뷰를 포함한 소프트웨어 팩토리의 다른 계층은 이러한 자동화된 테스트의 무결성과 효과를 검증하는 "거짓말 탐지기" 역할을 합니다.

테스트가 기능적 결과가 아니라 UI 요소 순서나 내부 상수에 의존할 때 구조적 변경으로 인해 실패하며, 이는 'useAudioBoost' 같은 스텁 뒤에 프로덕션 오류를 숨기는 AI 생성 코드에서 반복되는 문제입니다. 예를 들어, 테스트는 화면 렌더링을 시뮬레이션하는 대신 소스 코드 파일을 직접 읽어 UI 요소의 순서를 확인할 수 있어 취약합니다.

실제 비즈니스 로직의 변경이 아니라 상수 이름 변경으로 인해 깨지는 테스트도 이러한 취약성의 또 다른 예입니다. 이러한 문제는 개발자의 시간을 낭비하고 실제 버그를 가릴 수 있습니다.

AI 에이전트는 종종 동작을 검증하기 위해 기능적 코드를 실행하기보다 코드 구조에 너무 얽매인 테스트를 생성합니다. Matt Pocock은 'useAudioBoost'와 같은 스텁이 복잡한 오류 모드를 우연히 숨길 수 있으며, 이는 기존 테스트 스위트가 포착할 수 없는 프로덕션 실패로 나타날 수 있다고 강조했습니다.

John Ousterhout은 저서 'A Philosophy of Software Design'에서 깊은 모듈을 복잡한 로직을 단순한 인터페이스 뒤에 숨겨 구조에 민감한 테스트 실패를 최소화하는 구성 요소로 정의합니다. 깊은 모듈은 복잡한 내부 동작을 단순하고 깔끔한 인터페이스 뒤에 숨기는 것을 특징으로 합니다.

변경 가능한 내부 구현이 아니라 이러한 안정적인 인터페이스에 대해 테스트함으로써 구조에 민감한 실패의 가능성이 크게 줄어듭니다. 이 접근 방식은 테스트를 더 견고하게 만들고 내부 리팩토링이 발생할 때 깨질 가능성을 줄입니다.

코드베이스 설계 기술은 개발자가 중복을 줄이고 프로젝트 전반의 테스트 용이성을 향상시킬 기회를 식별할 수 있게 합니다. 모듈이 깊을 때 더 많은 구현 세부 사항이 숨겨져 구조에 민감한 테스트가 자연스럽게 줄어들어 테스트 표면이 단순해집니다.

지역성, 레버리지, 심(seams)은 엔지니어링 팀에게 정확하고 공유된 어휘를 제공하여 모호한 업계 전문 용어를 프로젝트별 아키텍처 원칙으로 대체합니다. 이는 지역성, 레버리지, 심과 같은 설계 개념에 대한 특정 용어를 정의하는 것을 포함하며, 이는 모호성을 피하고 모든 사람이 같은 이해를 갖도록 보장합니다.

지역성은 관련 코드 변경이 함께 이루어져 코드베이스 전반에 불필요한 파급을 방지하는 것을 의미하며, 레버리지는 호출자가 깊고 단순한 모듈 인터페이스와 상호작용함으로써 얻는 가치를 설명합니다. 프로젝트별 아키텍처 원칙을 엄격히 정의함으로써 팀은 도메인 주도 설계(DDD)와 같은 광범위한 용어와 관련된 모호함을 피하고 코드가 어떻게 구조화되고 유지되어야 하는지에 대한 더 명확한 이해를 촉진할 수 있습니다.

"구현이 과부하 상태"라는 정신 모델은 현재 AI 에이전트 워크플로우의 중요한 문제를 강조합니다. 에이전트의 컨텍스트 창은 코드 탐색, 파일 업데이트, 검증/디버깅을 동시에 관리해야 하며, 이는 까다로운 작업 집합입니다.

에이전트가 이미 이러한 복잡한 구현 책임을 처리하고 있는 동안 엄격한 코딩 표준을 부과하면 과부하가 더 심해집니다. 이는 에이전트가 제한된 컨텍스트 내에서 여러 까다로운 지시를 균형 있게 처리하려고 애쓰면서 전체 코드 성능과 품질의 저하로 이어집니다.

코드 품질과 에이전트 효율성을 향상시키려면 구현과 리뷰 프로세스를 분리하여 각 작업에 별도의 에이전트를 할당하는 것이 중요합니다. 한 에이전트는 코드가 작동하도록 만드는 데만 집중하고, 다른 리뷰 에이전트는 코드가 코딩 표준과 모범 사례를 준수하는지 확인합니다.

Matt Pocock은 이를 좋은 코드를 작성하는 두 부분의 과정으로 설명합니다. 먼저 기능적으로 작동하게 구현한 다음, 코딩 표준을 부과하여 좋게 만들기 위해 코드 리뷰를 수행합니다. 리뷰 에이전트는 자체 컨텍스트 창과 예산으로 운영됩니다.

이러한 분리는 리뷰 에이전트가 구현자보다 부담이 적어 과부하되지 않고 여러 코딩 표준을 효과적으로 관리할 수 있게 합니다. 이는 기능이 작동하게 하는 것과 그 품질을 개선하는 것 사이의 명확한 구분을 강조하는 '레드-그린-리팩터' 방법론을 반영합니다.

흔한 함정은 리뷰 에이전트가 풀 리퀘스트에 단순히 논평만 하게 하여, 인간 리뷰어가 제안된 수정을 구현해야 하는 추가 작업을 발생시키는 것입니다. 대신 최적의 접근 방식은 자동화된 리뷰어가 직접 수정 사항을 커밋하여 인간의 검토를 위해 완성된 결과물을 제시하는 것입니다.

Matt Pocock은 리뷰어가 단순한 제안이 아니라 적극적인 변경을 수행해야 한다고 주장했습니다. 인간 리뷰어는 결과적으로 더 깔끔하고 정제된 코드를 받게 됩니다. 논평은 에이전트가 독립적으로 해결할 수 없는 복잡한 질문이나 문제에만 한정하여 인간 리뷰 프로세스를 간소화해야 합니다.

이는 인간 리뷰어가 불필요한 세부 사항을 뒤지지 않고 변경 사항의 본질을 빠르게 파악할 수 있도록 하는 것을 목표로 합니다.

양방향 문 PR은 쉽게 되돌릴 수 있는 변경을 의미하며, 위험이 낮기 때문에 덜 집중적인 리뷰 프로세스가 필요합니다.

반대로 단방향 문 PR은 데이터 손실, 비용이 많이 드는 데이터베이스 마이그레이션 또는 수천 명의 사용자에게 대량 이메일 발송과 같은 영향력이 큰 작업과 같이 되돌릴 수 없는 변경을 포함합니다. 이러한 유형의 변경은 상당한 위험을 수반하며 세심한 검토가 필요합니다.

개발자는 PR 요약에 '병합 위험'과 '영향 범위'를 문서화하여 변경의 잠재적 영향과 되돌릴 수 있는지 명확히 표시하도록 권장됩니다. 이러한 사전 평가는 리뷰 노력의 우선순위를 정하고 고위험 수정에 적절한 보호 장치가 마련되도록 보장하는 데 도움이 됩니다.

Dex Holley의 'Human Layer Skills' 저장소는 Mermaid 다이어그램과 UML 시퀀스가 개발자가 복잡한 풀 리퀘스트의 근거를 빽빽한 텍스트보다 더 빠르게 파악할 수 있게 한다는 점을 강조합니다. Matt Pocock은 Dex Holley의 Human Layer Skills 저장소의 'show me' 스킬을 이 접근 방식의 대표적인 예로 꼽습니다.

이 스킬은 대부분의 텍스트를 시각적 표현으로 대체하며, Mermaid 다이어그램과 UML 시퀀스를 활용하여 복잡한 변경을 단순화합니다. 목표는 리뷰어가 CLI 명령이든 복잡한 에이전트 워크플로우든 변경의 '이유'를 빠르게 이해할 수 있도록 하여 더 빠르고 효율적인 리뷰를 촉진하는 것입니다.

인간 리뷰를 수행할 때 초점은 코드 자체만이 아니라 그것을 생성한 근본 시스템까지 확장하여 잠재적인 반복 에이전트 실수를 해결해야 합니다. 여기에는 과거 풀 리퀘스트와 에이전트 세션을 분석하는 새로운 'retro'(회고) 스킬을 도입하는 것이 포함됩니다.

이 'retro' 스킬은 과거 리뷰 데이터를 활용하여 코딩 표준 및 검사에 대한 제안을 자동화합니다. 또한 에이전트 탐색, 토큰 효율성을 위한 도구 경제성, 비대해진 스티어링 파일 간소화 등의 측면을 다루어 인간 리뷰가 AI 코드 생성 시스템의 지속적인 개선에 기여하도록 합니다.

협업 노력은 집합적으로 에이전트가 작동하는 환경을 형성하는 공유 스킬 및 스티어링 파일을 중심으로 이루어집니다.

따라서 개발 프로세스는 결과 코드만큼이나 중요해집니다. 리뷰어는 여러 풀 리퀘스트에서 동일한 에이전트 오류를 반복적으로 수정하는 것을 피하고 동일한 논평을 두 번 작성할 필요가 없도록 근본 시스템 개선에 집중해야 합니다.

'Retro' 스킬을 통해 팀은 과거 세션과 풀 리퀘스트를 분석할 수 있으며, 인간 리뷰가 자동으로 코딩 표준과 검사를 생성하여 향후 성능을 개선하는 복리 효과를 창출합니다. 새로운 자동화된 검사와 개선된 코딩 표준 같은 구체적인 개선 사항이 이 분석에서 나옵니다.

이러한 제안을 체계적으로 통합함으로써 인간 리뷰는 복리 효과를 얻습니다. 각 수동 리뷰는 즉각적인 품질을 보장할 뿐만 아니라 에이전트 시스템 자체의 향상에 기여하여 향후 리뷰에서 더 높은 품질을 가져오고 후속 수동 노력을 줄입니다.

코딩 표준뿐만 아니라 'retro' 스킬은 에이전트 효율성의 다양한 측면을 최적화하는 데도 초점을 맞춥니다. 여기에는 에이전트가 필요한 정보를 더 쉽게 찾도록 돕는 탐색 포인터 분석이 포함되며, 종종 agents.mmd 같은 파일 내에 명시적 지침을 제공합니다.

시스템은 또한 토큰 효율성을 개선하고 계산 비용을 줄이는 방법을 식별하기 위해 도구 경제성을 검토합니다. 추가적으로 'retro'는 스티어링 파일과 스킬의 '비대화'를 모니터링하여 지나치게 복잡해져 에이전트 성능에 부정적인 영향을 미치는 것을 방지합니다.

인간 개입을 간소화하기 위해 자동화된 검사를 계층화하는 것은 수동 노력을 줄이는 핵심 전략이며, 이는 더 빠르고 덜 빈번한 감독으로의 전환을 촉진합니다. 이는 자동화된 검사와 고급 AI 기반 리뷰를 체계적으로 계층화함으로써 달성됩니다.

전체 코드 생성 시스템을 최적화함으로써 인간 개입은 덜 빈번하고 덜 부담스러워집니다. 리뷰어는 강력한 자동화 기반을 자신 있게 신뢰하여 모든 사소한 변경을 scrutinize할 필요 없이 더 높은 수준의 전략적 문제에 집중할 수 있습니다.