Claude Code에서 PR을 위한 루프 엔지니어링 스킬 구축 — 브랜치 생성, 두 개의 독립적인 리뷰, CI 처리, 머지 핸드오프. 구축

대부분의 에이전트 기반 코딩 도구(agentic coding tools)는 한 가지를 정말 잘합니다. 바로 코드를 빠르게 작성하는 것이죠. 문제를 설명하면 구현하고, 끝납니다. 솔직히 그 부분은 꽤 수준이 높아졌습니다.

하지만 아무도 이야기하지 않는 부분은 첫 번째 커밋(commit) 이후의 모든 과정입니다. 리뷰(review), CI, 머지 규율(merge discipline) 말이죠. 바로 이 지점에서 실제 코드베이스가 무너지기 시작하는데, 제가 시도해 본 도구 중 그에 대한 진지한 해답을 가진 것은 없었습니다.

그래서 저는 작업 항목을 전체 PR 파이프라인(PR pipeline)을 통해 실행하는 Claude Code 스킬인 /pr-loop를 구축했습니다. 이것이 어떻게 작동하는지, 그리고 그 과정에서 무엇이 저를 놀라게 했는지 공유하고 싶습니다.

실제로 하는 일
GitHub 이슈 번호를 주거나 작업 내용을 설명하기만 하면 됩니다. 나머지는 순서대로 진행됩니다:

1. 아무것도 건드리기 전에 프로젝트의 기여 규칙(contribution rules)을 읽습니다 (CONTRIBUTING.md, CLAUDE.md, README 등 존재하는 모든 것). 이를 통해 커밋 형식, 브랜치 명명 규칙, 테스트 명령, 머지 규칙 등을 학습합니다. 만약 문서화되어 있지 않다면, 추측하지 않고 사용자에게 질문합니다.
2. 그다음 이슈 자체가 실제로 실행 가능한지 확인합니다. 설명이 모호하거나 수락 기준(acceptance criteria)이 누락되었다면 중단하고 질문합니다. 단 세 단어로 된 이슈 제목만으로는 작업을 수행하기에 충분하지 않습니다. 이 과정 덕분에 예상치 못한 비용이 드는 잘못된 방향으로 가는 상황을 수없이 방지할 수 있었습니다.
3. 그다음 브랜치를 생성하고, 구현하고, 충돌 체크(conflict check)를 수행하며, 로컬 게이트(local gates)(테스트, 린터(linter), 빌드)를 실행합니다. 아무것도 푸시(push)하기 전에 모든 항목이 통과(green)되어야 합니다.
4. 많은 파일을 수정하거나 설계 결정이 필요한 대규모 변경의 경우, 구현에 완전히 몰두하기 전에 방향성을 확인하기 위해 초기에 드래프트 PR(draft PR)을 엽니다. 이 기능은 작아 보이지만 제가 작업을 구조화하는 방식을 바꾸어 놓았습니다.

제가 실제로 자랑스럽게 생각하는 부분: 세 개의 분리된 에이전트 컨텍스트(agent contexts)
이것이 핵심 설계 결정이었으며, 저는 이것이 옳은 결정이었다고 생각합니다.

완전히 분리된 세 가지 컨텍스트가 있습니다: 작성자(코드를 작성함), 두 명의 리뷰어(병렬로 실행되며 서로를 볼 수 없음), 그리고 선택적인 머저(merger)입니다. 코드를 작성한 컨텍스트는 절대로 그 코드를 리뷰하지 않습니다. 절대로 머지하지도 않습니다.

AI에게는 그런 것이 중요하지 않다고 생각할 수도 있습니다. 하지만 매우 중요합니다.

자신의 코드를 리뷰하는 에이전트는 작성자가 가졌던 것과 동일한 사각지대(blind spots)를 가집니다. 동일한 엣지 케이스(edge cases)를 놓칠 것이고, 동일한 트레이드오프(tradeoffs)를 정당화할 것입니다. 컨텍스트(contexts)를 분리하는 것은 단순한 규칙이 아닙니다. 이는 의미 있게 다른 결과물을 만들어냅니다.

두 리뷰어는 동일한 작업을 수행하지도 않습니다. 한 명은 보안, 정확성, 성능, 유지보수성(maintainability)과 같은 구조적 분석(structured analysis)을 수행합니다. 다른 한 명은 실제로 게이트(gates)를 실행하고 변경 사항이 PR(Pull Request)에서 주장하는 대로 작동하는지 조사합니다. 서로 다른 렌즈를 통해 서로 다른 실패 모드(failure modes)를 포착하는 것입니다.

리뷰 루프 (The review loop)
모든 발견 사항은 처리됩니다. 여기에는 사소한 지적(nits)도 포함됩니다. 리뷰어가 변수 이름을 지적하면 이름이 변경됩니다. 아무것도 조용히 누락되거나 백로그(backlog)에서 죽어버리도록 "낮은 우선순위(low priority)"로 표시되지 않습니다.

3라운드 제한이 있습니다. 리뷰와 수정이 세 라운드 진행된 후에도 발견 사항이 계속 나타나면, 루프는 일시 중지하고 사용자에게 요청합니다. 세 번의 패스(passes) 내에 무언가를 해결할 수 없다면, 그것은 아마도 인간의 판단이 필요한 판단(judgment call)일 가능성이 높기 때문입니다.

머지는 선택 사항 (Merge is opt-in)
기본 설정은 핸드오프(handoff) 단계에서 멈추는 것입니다. 두 리뷰가 모두 통과되고 CI(Continuous Integration)가 통과(green)되면, 스킬은 다음과 같이 보고하고 중단합니다: "PR 오픈됨, CI 통과, 두 리뷰 모두 통과. 머지를 기다리는 중입니다."

아직 부족한 점
솔직히 말씀드리면:
아직 멀티 레포(multi-repo)나 모노레포(monorepo)의 교차 패키지 변경 사항을 잘 처리하지 못합니다. 만약 PR이 독립적인 CI를 가진 두 개의 패키지를 건드린다면, 현재 로직은 양쪽 모두를 어떻게 적절히 기다려야 하는지 알지 못합니다.

또한 머지 충돌(merge conflicts)을 자율적으로 처리할 수 없습니다. 파이프라인 중간에 브랜치에 충돌이 발생하면, 이를 사용자에게 알리고 중단합니다. 이는 올바른 결정입니다. 사소하지 않은 충돌을 자동으로 해결하는 것은 미묘한 버그를 유발하는 지름길이기 때문입니다. 하지만 이는 때때로 사용자가 개입해야 함을 의미합니다.

그리고 리뷰어가 제가 제품 결정(product decision) 없이는 진정으로 해결할 수 없는 '변경 요청(Request Changes)'을 보냈을 때를 위한 에스컬레이션 경로(escalation path)가 아직 없습니다. 현재는 일시 중지하고 질문을 던집니다. 궁극적으로는 이러한 요청을 별도의 "제품 판단(product judgment)" 에이전트로 라우팅하고 싶지만, 아직 구축하지는 않았습니다.

스킬 파일 자체는 약 105줄 정도입니다.
프레임워크도 없고, 오케스트레이션 레이어(orchestration layer)도 없습니다.

git과 gh CLI 외에는 아무런 의존성(dependencies)이 없습니다. 그저 Claude Code가 읽고 실행할 수 있는 구조를 가진 마크다운(markdown) 파일일 뿐입니다.

Skill 상세 내용이 담긴 Medium 기사: https://medium.com/developersglobal/loop-engineering-in-practice-i-built-a-105-line-skill-that-runs-the-full-pr-pipeline-fc102b050127
제출자: /u/Naive_Maybe6984
[link] [comments]