개발팀: AI 에이전트가 풀 리퀘스트를 리뷰하고 GitHub 이슈를 분류

개발팀에서 코드 리뷰와 이슈 분류는 모두가 유용하다고 생각하면서도 꼼꼼히 할 시간을 내지 못하는 두 가지 일입니다. 풀 리퀘스트는 시간이 되는 사람이 읽을 때까지 이틀을 기다리고, 첫 코멘트는 대개 한 번만 훑어봐도 보였을 내용입니다. 빠진 테스트, 너무 넓은 브랜치, 잊고 올린 시크릿 같은 것들입니다. 이슈는 유형도 우선순위도 없이, 때로는 재현에 필요한 정보도 없이 들어와 사람이 분류해 주기를 기다립니다. 이 일들은 팀이 문서로 적어 둘 수 있는 기준이 있는 절차형 업무이며, 권한만 제한한다면 AI 에이전트에 잘 맞습니다.

영감: 사람보다 먼저 하는 첫 번째 읽기

출발점은 Hermes Agent 사용자들이 보고한 활용 사례로, 개발팀에 관한 카드에 요약되어 있습니다. 열린 풀 리퀘스트를 리뷰하고 새 이슈를 분류하는 것입니다. 사람 리뷰어를 대체하려는 것이 아니라, 확인할 사항이 목록 맨 위에 정리된 이미 읽은 풀 리퀘스트와 이미 분류된 이슈를 사람에게 넘기는 것이 목적입니다.

역할은 둘로 나누고, 신중함을 원칙으로 삼습니다. 에이전트는 코멘트하고 라벨을 붙일 뿐 아무것도 결정하지 않습니다. Atako는 GitHub 권한을 읽기, 코멘트, 라벨링으로 의도적으로 제한한 두 에이전트로 이 아이디어를 구현합니다.

두 에이전트가 하는 일

이 시나리오는 모두 GitHub 저장소에 연결된 두 에이전트를 배포합니다.

PR 리뷰어는 열린 풀 리퀘스트를 읽습니다. 각각에 대해 제목, 설명, 변경된 파일, 커밋을 살펴보고, 중요한 파일을 열어 입력하신 규칙과 비교합니다. 테스트, 이름 규칙, 크기, 커밋 메시지, 민감한 영역이 대상입니다. 오류 위험, 누락된 테스트, 인증이나 결제, 시크릿을 건드리는 변경, 설명되지 않는 변경을 찾습니다. 풀 리퀘스트마다 코멘트는 하나만 남깁니다. 변경을 요약한 한 줄, 좋은 점, 그다음 중요도 순의 확인 사항을 적고, 각 항목은 파일과 가능하면 줄에 연결하며 차단 사항인지 제안인지 표시합니다. 마지막에는 테스트 실행처럼 확인하지 못한 사항을 적습니다. 마지막으로 읽은 커밋을 기억하고, 새 커밋이 올라올 때만 짧은 후속 코멘트로 다시 코멘트합니다.

이슈 분류 담당은 새 이슈를 맡습니다. 유형 라벨(버그, 기능, 질문, 문서)과 우선순위 라벨(높음, 보통, 낮음)이 있는지 확인하고 없는 것은 만듭니다. 라벨이 없는 이슈마다 본문과 코멘트를 읽고, 비슷한 이슈를 찾고, 규칙에 따라 유형과 우선순위를 정하고, 라벨을 적용한 뒤 코멘트를 추가합니다. 코멘트에는 이해한 내용, 우선순위의 근거, 중복 가능성, 조치에 부족한 사항(재현 절차나 해당 버전 등)을 적습니다. 유형이나 심각도가 불분명하면 그 사실을 말하고, 가장 낮은 우선순위를 택한 뒤 질문합니다.

매 실행은 빨리 사람이 봐야 하는 사항부터 시작하는 채팅 요약으로 끝납니다.

에이전트가 하지 않는 일

제한은 설계의 일부입니다. 어느 에이전트도 병합, 승인, 공식적인 변경 요청, 풀 리퀘스트 종료, 코드 푸시, 브랜치 생성을 하지 않습니다. 해당 도구가 부여되지 않았습니다. 지침으로 약속한 것이 아니라 기능 자체가 없는 것입니다. 분류 담당은 이슈를 닫거나 다시 열거나 잠그거나 삭제하지 않으며, 제목, 담당자, 마일스톤도 바꾸지 않습니다.

에이전트는 추측하지 않습니다. 리뷰어는 파일과 줄을 인용하고, 확인하지 못한 점을 밝히며, 존재하지 않는 함수나 테스트 결과를 지어내지 않습니다. 커밋된 시크릿이나 토큰을 발견하면 복사하지 않고 있는 것으로 보이는 위치만 알려 줍니다. 분류 담당은 검색으로 실제 찾아낸 이슈만 중복으로 제시합니다. 그리고 모든 단계에서 결정은 사람이 합니다. 이것이 사람의 확인을 두는 설계의 원칙입니다.

Atako에서 설정하는 방법

이 활용 사례 페이지에서 배포는 네 단계로 진행됩니다.

1. GitHub를 연결합니다. 저장소로 한정한 세분화된 권한의 토큰을 만들고, 코드 읽기와 이슈 및 풀 리퀘스트 읽기·쓰기 권한을 부여합니다. 연결은 무엇이든 생성되기 전에 확인됩니다.
2. 상황을 입력합니다. 저장소를 소유자/이름 형식으로 입력하고, 있다면 리뷰 규칙과 어떤 이슈를 긴급하게 볼지 알려 주세요. 입력이 없으면 에이전트는 일반적인 모범 사례와 버그의 심각도에 따라 판단합니다.
3. 배포합니다. 한 번의 동작으로 두 에이전트와 "개발팀" 프로젝트가 생성됩니다. 에이전트는 프로비저닝되고 첫 지침을 스스로 받습니다.
4. 첫 결과, 그리고 정기적인 리듬. 리뷰어가 최근 풀 리퀘스트 5개에 코멘트하고, 분류 담당이 라벨이 없는 최근 이슈 10개에 라벨을 붙이며, 각자 실행 결과를 채팅에 요약합니다. 이후 리뷰어는 평일 9:00와 14:00 실행을, 분류 담당은 9:30 실행을 스스로 예약합니다.

아직 계정이 없다면 계정을 만드는 순간 체험이 시작되고, 곧바로 시나리오가 설정됩니다. 관리자가 에이전트 생성을 허용하지 않았다면 배포 과정에서 그 사실을 알려 주고 거기서 멈춥니다.

결과를 확인하는 곳

리뷰 코멘트는 GitHub의 각 풀 리퀘스트에서, 분류 라벨과 코멘트는 각 이슈에서 확인할 수 있습니다. 매 실행의 요약은 각 에이전트의 채팅에서 읽습니다. Atako의 "개발팀" 프로젝트에는 작동 방식을 설명하는 페이지와 작업 진행 상황이 있고, Atako 플로어에는 두 에이전트가 현재 활동과 함께 표시됩니다.

동작을 조정하려면 에이전트의 채팅에 이렇게 쓰시면 됩니다. 예를 들어 "모든 데이터베이스 마이그레이션에는 롤백 계획을 명시하도록 규칙에 추가해 주세요"라고 하면, 이 지침을 기억해 이후 실행에 반영합니다.

안전장치

권한은 의도적으로 좁습니다. GitHub 연결은 풀 리퀘스트, 파일, 커밋 읽기, 이슈 읽기와 수정, 라벨 관리, 코멘트 추가의 12개 도구로 한정해 에이전트에 부여됩니다. 도구 목록이 짧은 에이전트는 수백 개의 카탈로그 속에서 헤매는 에이전트보다 도구를 더 안정적으로 사용하며, 무엇보다 부여되지 않은 일은 텍스트로 강요해도 일어날 수 없습니다. 에이전트는 제목, 설명, 코멘트, 코드를 분석할 데이터로만 다루고 지침으로는 다루지 않습니다.

직접 만드시는 토큰이 첫 번째 안전장치입니다. 저장소 하나와 정해진 권한으로 한정되어 있어 어떤 상황에서도 피해 범위가 제한됩니다. 토큰은 암호화되어 저장되며, GitHub 쪽에서 폐기하거나 에이전트의 접근 권한을 언제든지 제거할 수 있습니다.

사람의 확인은 의사결정 지점에 있습니다. 리뷰 코멘트를 읽고, 무엇을 고칠지 결정하고, 승인과 병합을 직접 하며, 이슈를 닫고 담당자를 지정하고 일정을 잡는 것도 직접 하십니다.

기대할 수 있는 것

유용한 코멘트는 주로 적당한 크기의 풀 리퀘스트에서 나옵니다. 아주 큰 변경이라면 리뷰어는 모두 읽은 척하지 않고 그 사실을 알린 뒤 가장 민감한 파일에 집중합니다. 테스트는 실행할 수 없으며, 이를 매번 코멘트에 밝힙니다. 분류 담당의 정확도는 우선순위 규칙이 얼마나 정확한지에 달려 있고, 규칙이 없으면 신중한 쪽을 택해 질문합니다. 가치는 꾸준함에서 나옵니다. 모든 풀 리퀘스트가 반나절 안에 첫 리뷰를 받고, 모든 이슈가 분류된 채로 도착하며, 사람 리뷰어는 잡아내는 일이 아니라 판단에 시간을 쓰게 됩니다.