GitHub 리포지토리 자동 관리 오케스트레이터
‘에이전트에게 프롬프트하지 말고, 에이전트에게 프롬프트할 루프를 설계하라.’ Peter Steinberger의 이 한 문장은 며칠 전 830만 뷰를 기록했다. 그리고 그는 자신이 말한 그 루프의 실물을 깃허브에 공개했다. 막상 열어보니 정교한 코드가 아니라 문서 두 장이었다. 오픈소스 리포지토리 유지보수를 자동화된 에이전트 시스템으로 관리하는 방식을 담은 글이다. 이 시스템은 중앙 오케스트레이터와 독립적인 워커 스레드 간의 명확한 역할 분담으로 운영된다.
유지보수 오케스트레이터의 역할
유지보수 오케스트레이터는 리포지토리 작업 흐름의 중앙 통제점 역할을 한다. 이 오케스트레이터는 작업을 검사하고, 위임하고, 모니터링하며, 중요한 결정 요청을 전달하고, 최종 보고서를 생성한다. 실질적인 리포지토리 조사, 구현, 검토, 라이브 검증, 반영 및 릴리스 실행은 별도의 리포지토리 워커 스레드에 위임한다.
오케스트레이터가 관리하는 리포지토리 범위는 피터(Peter)가 주된 커밋 작성자인 모든 리포지토리를 포함한다. 단, openclaw 및 clawhub 조직 아래의 리포지토리와 아카이브된 리포지토리는 명시적인 재요청이 없는 한 기본적으로 제외한다. 리포지토리 소유권은 리포지토리 이름만이 아닌 기여 기록으로 판단한다.
작업 운영 모델
오케스트레이터는 github-project-triage라는 도구를 활용해 각 리포지토리의 열린 이슈, PR, CI 상태, 최신 릴리스, 패키지 메타데이터, 미출시 변경 로그를 매핑한다. 이후 모든 큐 항목을 세 가지 유형으로 분류한다.
| 분류 | 설명 | 예시 |
|---|---|---|
| 자율(Autonomous) | 명확하고 재현 가능하며, 구현 범위가 정해져 있고 검증 경로가 명확한 항목이다. 오너의 추가 개입 없이 워커가 독자적으로 처리한다. | 성능 개선, 버그 수정, 문서화, 간단한 UI/UX 조정 |
| 오너 필요(Needs owner) | 제품 선택, 보안/개인정보 결정, 필요한 자격 증명/액세스 부재, 라이브 검증 불가, 또는 파괴적이거나 돌이킬 수 없는 결정이 필요한 항목이다. | 새 기능 추가, 광범위한 동작 변경, 보안 관련 변경 |
| 오너가 무시(Ignored by owner) | 오너가 현재 작업이나 릴리스 게이트에 영향을 주지 않도록 명시적으로 지시한 항목이다. 이 항목은 닫히거나 수정되지 않고 열린 상태로 유지된다. |
자율적으로 처리할 수 있는 항목이 없거나 오너의 결정이 필요한 경우, 오케스트레이터는 워커 스레드를 관리하며 작업 진행 상황을 5분마다 모니터링한다. 워커는 :<리포지토리>:<항목> 형식으로 이름을 정하고, 할당된 리포지토리 작업만 수행한다. 워커는 하위 워커를 생성하거나 다른 대화를 관리하지 않는다.
결정 준비 큐 규칙
오케스트레이터는 미준비된 이슈나 미완성 기여자 브랜치로 오너에게 결정을 요청하지 않는다. 모든 결정 요청은 철저히 준비된 상태여야 한다.
| 항목 유형 | 준비 과정 | 오너 요청 내용 |
|---|---|---|
| 기존 PR | 검사, 재현, 필요 시 수정, 테스트/문서/변경 로그 추가, 라이브 검증, 자동 검토, CI 통과 확인 | PR 병합 가능 여부, 자율 해결 불가한 블로커 해결 지시 |
| PR 없는 이슈 | 근본 원인 및 제품 제약 조사, 최적의 후보 구현, PR 생성 및 병합 가능한 상태로 진행 | 준비된 PR 병합/삭제, 대체 옵션 선택, 정확한 접근 권한 부여 |
| 제품 결정 | 기술적으로 안전하다면 가역적인 기본값 선택, PR 설명에 결정 사항 명확히 노출 및 유용한 대안 준비 | |
| 접근/라이브 검증 블로커 | 코드, 테스트, 문서, 검토, CI 작업 완료 | 정확한 자격 증명, 계정 작업, 하드웨어 상호작용, 면제 또는 반영/삭제 결정 |
| 거부 후보 | 구체적인 연구 및 증거 준비. 코드 후보가 트레이드오프를 명확히 한다면 PR 준비 | 오너의 닫기/유지 결정에 필요한 증거 제공 |
오너의 일반적인 상호작용은 준비된 PR을 반영하거나 삭제하는 것, 정확한 액세스 단계를 제공하는 것, 또는 명확하게 문서화된 대안 중 하나를 선택하는 것이다.
오너 결정 브리핑
오너에게 결정을 요청할 때는 단순히 URL이나 상태 레이블만 제공하지 않는다. 모든 결정 요청에는 다음 정보가 포함된다.
- 완전하고 클릭 가능한 URL 및 제목
- 무엇이 변경되는지, 누가 이점을 얻는지에 대한 명확한 설명
- 지금 결정이 필요한 이유
- 재현, 라이브 테스트, 테스트, 자동 검토, CI, 병합 가능성 등 완료된 증명
- 주요 트레이드오프, 잔여 위험, 범위 우려 또는 누락된 증거
- 오케스트레이터의 추천과 간결한 근거
- 사용 가능한 정확한 선택 사항과 각 선택 사항의 결과
여러 결정을 그룹화할 경우, 각 항목에 별도의 브리핑을 제공한다. 추천은 단정적으로 제시하며, 기술 분석을 오너에게 전가하지 않는다.
워커의 자율 작업 모드
오너가 ‘자율적으로 작업하라’와 같은 지시를 내리면, 워커는 안전하고 자율적인 항목이 남지 않을 때까지 해당 이슈 및 PR 큐를 순차적으로 처리한다. 각 항목에 대해 워커는 다음 단계를 수행한다.
- 이슈/PR, 관련 코드, 문서, CI,
VISION.md(존재하는 경우)를 읽는다. - 자율 작업 여부를 결정한다. 새 기능, 제품/비전 선택, 광범위한 행동 변경, 위험한 의존성, 보안에 민감한 변경, 또는 종단 간 테스트 불가능한 항목 등은 오너에게 먼저 문의해야 한다.
- 기여자 PR을 업데이트하는 방식을 선호하며, 가장 유지보수 가능한 방식으로 구현하거나 수정한다.
- 가능한 경우 로컬 및 종단 간 라이브 검증을 수행한다. UI 동작은 리포지토리의 라이브 UI 검증 경로(예: Peekaboo, 스크린샷)를 사용한다. API 동작은 실제 키/계정을 사용한다.
- 커밋/반영 전에
Codex Auto Review를 실행하고, 수용된/실행 가능한 사항을 처리한다. - CI가 통과하고, PR 설명/변경 로그가 적절하며, 증거와 함께 반영/종료/코멘트 작업을 수행한다.
- 모든 반영 후 PR 코멘트에 테스트 방법, 라이브/UI/API 검증, CI 실행 상태, 반영된 커밋 및 주의사항을 게시한다.
품질 보증 및 릴리스 게이트
시스템은 여러 단계의 품질 보증 게이트를 운영하여 리포지토리의 안정성을 유지한다.
- 라이브 검증 게이트: 실제 빌드된/설치된 아티팩트와 실제 서비스, 계정, 장치, OS 또는 외부 공급자를 사용해 변경된 사용자 경로를 통해 최종 후보 커밋을 테스트한다. 이는 반영 전 필수 요건이며, 인증된 라이브 호출을 요구한다. 자격 증명이나 액세스가 불가능할 경우, 모든 자율 코드, 테스트, 검토, CI 작업을 완료한 후 중단하고 오너에게 정확한 액세스 권한, 특정 항목 면제 또는 거부/종료 결정을 요청한다.
- 공개 모델 식별자 게이트: 모델 관련 코드나 아티팩트의 푸시, 공개 PR 업데이트, 병합 또는 릴리스 전에, 후보 diff, 테스트, 스냅샷, 생성된 메타데이터, 워크플로, CI/테스트 로그, 패키지 아티팩트 등을 감사하여 모델 식별자를 확인한다. 내부, 직원 전용, 미리 보기 전용 또는 공개되지 않은 식별자는 노출하지 않는다. 이 게이트가 차단되면 푸시, 공개 변경, 병합 또는 릴리스는 진행할 수 없다.
- 릴리스 게이트: 릴리스는 다음 조건이 모두 충족될 때만 실행한다.
- 오너가 해당 리포지토리의 릴리스를 명시적으로 요청했거나 승인했다.
- 유효한 이슈 및 PR 수가 0이다.
- 모든 무시된 항목이 현재 오너 지침에 명시적으로 명명되어 있다.
- 릴리스될 정확한 커밋과 브랜치/태그 후보에 대해 필요한 CI가 통과했다.
- 릴리스의 모든 사용자 대면 런타임 변경 사항에는 필수 라이브 검증이 있거나 오너가 명시적으로 면제했다.
- 릴리스 체크아웃이 깨끗하고, 예상 브랜치에 있으며, 최신 상태를 유지한다.
- 미출시 변경 사항이 릴리스를 정당화하며, 대상 버전이 SemVer/프로젝트 규칙을 따른다. 릴리스 직전에 GitHub 큐와 CI를 다시 확인하고, 게이트가 변경되면 중단한다.
시스템 관리 및 보고
오케스트레이터는 ~/oss-orchestrator.md에 지속적인 로그를 기록한다. 여기에는 정책/스킬/자동화 변경, 워커 생성 또는 재할당, 큐 결정, 반영, 종료, 릴리스, 정확한 블로커 등 의미 있는 행동과 결정에 대한 날짜가 표시된 상위 수준 항목을 추가한다.
또한, 워커 스레드가 유휴 상태이거나 작업을 완료하면 해당 리포지토리의 현재 큐, CI, 최신 릴리스, 패키지 메타데이터 및 미출시 변경 로그를 검사한다. 이후 다음 자율 이슈나 PR을 할당하거나, 나머지 비자율 항목을 결정 준비 상태로 만들어 오너에게 질의하거나, 큐가 비었을 때 승인된 릴리스를 실행하거나, 의존성을 감사하고 업데이트한다.
권한은 triage, 모니터링, 구현, 공개 변경, 릴리스로 나뉜다. 각 워커 프롬프트에 부여된 권한을 기록한다. 필요한 권한이 없으면 마지막으로 승인된 경계에서 멈추고 정확한 다음 작업을 보고한다. 대부분의 유지보수 자격 증명은 1Password에 저장되어 있다고 가정하며, 필요한 경우 op 접근 방식을 활용한다.
연극학·서사이론의 시선으로 보면
이 시스템은 복잡한 연극 제작을 닮았다. 총괄 감독(오케스트레이터)은 대본(리포지토리)의 완성도를 높이려 노력한다. 그는 각 장면(작업 스레드)을 책임질 조연출(워커 에이전트)에게 권한을 위임하고, 조연출은 자신의 영역에서 최적의 연기(자율 작업)를 만들어낸다. 이때 감독은 최종 결정(오너 결정)이 필요한 순간에만 개입하며, 각 장면이 완전한 형태로 준비되어야만 최종 승인을 요청한다.