행동하지 않을 때를 아는 자율 GitHub 봇 만들기

이 봇은 무엇을 하는가

이 레시피는 네 가지 작업을 수행하는 자율 GitHub Actions 봇을 구축합니다. 이슈 분류(triage), 풀 리퀘스트 리뷰, AI 슬롭(slop) 탐지, 그리고 버그 수정 PR 생성입니다. 실행 환경은 OpenCode에 Muse Spark를 모델로 얹은 구성인데, Model API가 기존 에이전트 CLI와 그대로 호환되기 때문에 가능한 조합입니다. 모든 것은 남의 인프라가 아니라 여러분 저장소의 Actions 안에서 돌아갑니다.

설계 요구사항으로서의 ‘절제’

이 레시피가 단순히 “LLM을 웹훅에 연결해 봤다” 수준의 프로젝트와 구분되는 지점은, 상당 부분이 행동하지 않는 것에 관한 설계라는 데 있습니다. 리뷰 에이전트는 명시적인 “NOT slop” 목록을 갖고 있습니다. 절대 지적하면 안 되는 정당한 패턴들을 정의해 두어, 멀쩡한 코드에 늑대가 나타났다고 외치는 일을 막는 것입니다. 이슈 분류 에이전트는 절대 이슈를 닫지 않습니다. 그 결정은 항상 사람의 몫으로 남습니다. 버그 수정 에이전트는 버그를 먼저 재현하지 못하면 PR을 열지 않습니다. Meta의 표현은 직설적입니다. 과잉 반응(over-triggering)은 사소한 흠이 아니라 명백한 실패 모드로 취급합니다.

인용 규율도 있습니다. Q&A 기능은 오직 저장소 파일에 근거해서만 답해야 하고, 모든 주장에 파일·섹션 단위 출처를 붙여야 하며, 저장소에 답이 없으면 지어내지 않고 거부해야 합니다. 공개 스레드에서 프로젝트의 이름으로 발언하는 봇이라면, “근거가 있거나, 아니면 침묵하거나”만이 유일하게 방어 가능한 정책입니다.

AGENTS.md: 함대 전체를 다스리는 파일 하나

레시피의 모든 에이전트는 공통 AGENTS.md 파일을 자동으로 불러옵니다. 이 파일에는 저장소 컨텍스트가 담겨 있어 에이전트가 컨벤션을 추측하지 않아도 되고, 모든 에이전트가 상속하는 보안 규칙도 함께 들어 있습니다. Meta는 이 파일을 자기 프로젝트에 맞게 고쳐야 할 가장 중요한 단 하나의 파일이라고 강조합니다. 배포판에 포함된 버전은 Python/pytest/uv 스택 기준의 예시일 뿐이므로 여러분의 스택에 맞게 다시 쓰되, SECURITY 섹션만은 한 글자도 바꾸지 말고 그대로 유지해야 합니다.

단계적으로 배포하고, 쓰기 권한은 ’획득’하게 하라

배포 가이드는 4단계 신뢰 사다리로 구성되어 있습니다. 1단계는 PR 리뷰와 이슈 분류를 읽기 전용으로 돌리는 것입니다. 실제 트래픽으로 품질을 검증하되 피해 반경은 0으로 유지합니다. 2단계는 명시적인 /oc 명령입니다. 메인테이너가 의도적으로 에이전트를 호출할 때만 작업이 실행됩니다. 3단계는 라벨로 게이트를 건 자동 버그 수정, 4단계는 브랜치 보호, CODEOWNERS, CI 게이트를 통한 하드닝입니다. 쓰기 권한은 실적으로 획득하는 것이지, 첫날부터 부여되는 것이 아닙니다. Muse Code 자체의 감사 가능성(auditability) 스토리와 같은 철학입니다. 자율성은 검증 능력이 커지는 속도만큼만 확장됩니다.

Meta는 이것을 어떻게 검증했나

따라 할 가치가 있는 디테일이 하나 있습니다. 이 레시피는 실제 에이전트를 헤드리스로 구동하되, 스크립트로 짜 둔 이슈·PR 시나리오를 상대하게 하는 방식으로 검증되었습니다. PATH에 가짜 gh를 올려 Action의 프롬프트를 재구성했기 때문에 실제 저장소에는 아무것도 닿지 않았고, 그 상태에서 에이전트가 만들어낸 결과물을 읽어 평가했습니다. 여러분의 봇도 신뢰할 수 없는 자동화를 테스트하듯 다뤄야 합니다. 프로덕션을 만나기 전에, 유리병 안에서 먼저 시험하십시오. 실행 가능한 레시피는 쿡북의 use cases 항목에 있습니다.