
GitHub을 AI 워커의 OS로 사용하기 — 이미 존재했던 것과 아무도 문서화하지 않았던 것
요약
여러 AI 워커를 효율적으로 관리하기 위해 GitHub을 운영체제(OS)처럼 활용하는 워크플로우를 제안합니다. 이슈, PR, 문서화된 가이드를 통해 AI의 스코프 유지, 증적 관리, 리뷰 품질을 확보하는 전략을 다룹니다.
핵심 포인트
- GitHub을 AI 워커의 상태 관리 및 증적을 위한 OS로 활용
- 역할 분리를 위해 AGENTS.md, CLAUDE.md 등 버전 관리 문서 사용
- 비용과 속도 최적화를 위한 2단계(Tier 1/2) 리뷰 설계 적용
- Human-in-the-loop 구조를 통한 최종 결정권 유지
AI 코딩은 1모델·1세션·1PR의 문제가 아니게 되었다. 여러 AI 워커를 스코프(Scope)를 잃지 않고, 증적을 남기면서, 리뷰 품질을 유지하며 구동하려면 어떻게 해야 하는가. TheGateBreaker의 답은 GitHub 자체를 「OS」로 사용하는 것이다. 개별 요소는 공개 사례에 존재한다. 문서화되어 있지 않았던 것은 그 조합이었다. Perplexity가 외부 연구로서 뒷받침했다.
AI가 코드를 작성한다. 그것은 이제 당연한 일이 되었다.
문제는 다른 곳에 있다. 여러 AI 워커를, 동시에, 세션을 넘나들며, 스코프를 잃지 않고 구동하는 것이다.
한 명의 엔지니어가 작성하는 것보다 빠르게 코드가 나오는 상황에서도, 다음과 같은 것들을 잃기 쉽다:
스코프 (Scope): 워커가 Issue를 넘어선 작업을 조용히 시작하고 있지는 않은가 -
증적 (Traceability): 판단과 검증의 기록이 터미널 출력에만 남아 있지는 않은가 -
리뷰 품질 (Review Quality): 구현자와 심사자가 분리되어 있는가 -
상태 (State): 현재 어떤 워커가 어떤 태스크를 가지고 있는지 채팅 밖에서도 알 수 있는가 -
Human의 제어 (Human Control): 머지(Merge)·클로즈(Close)·공개의 판단이 누구의 손에 남아 있는가 -
단일 모델로 단일 태스크를 수행한다면 이 문제는 작다. 5개의 AI 워커를 병렬로 돌리면 제어력을 잃는다.
먼저 솔직히 말하겠다. 이 문제에 대한 답의 「부품」은 이미 공개 사례에 존재한다.
Perplexity의 Deep Research가 확인한 기존 패턴:
| 패턴 | 대표 사례 |
|---|---|
| GitHub Issue → AI PR → Human 머지 | GitHub Copilot Coding Agent, Devin |
| ... | |
| 우리가 처음은 아니다. |
역할 분리, Human-in-the-loop 머지, AI PR 리뷰——이것들은 확립된 패턴이다. 출발점으로 사용할 수 있다.
TheGateBreaker는 AI 개발 워크플로우를 실험하는 오픈 리포지토리(Open Repository)다. 운용 모델의 핵심은 두 가지 설계에 있다.
| 워커 | 역할 | 주요 서피스 (Surface) |
|---|---|---|
| Human | 최종 결정자 | Gmail / GitHub |
| ... | ||
역할은 벤더(Vendor)를 넘나들며 분리한다. ClaudeCode가 자신의 구현을 클로즈 심사할 수는 없다. Codex가 구현할 수도 없다. 이 분리는 「관습」이 아니라, AGENTS.md와 CLAUDE.md에 버전 관리된 문서로서 존재한다. |
Human의 의도
↓
ChatGPT가 GitHub Issue로 변환
...
중요한 것은 2단계 리뷰 설계다.
Tier 1 (경량 리뷰): 통상적인 PR 개발 중에 실행된다. Codex가 차이점(Diff)을 보고 정확성·스코프 이탈·명백한 버그를 체크한다. 가볍다. -
Tier 2 (클로즈 게이트): Issue가 클로즈 후보가 되었을 때만 실행된다. ClaudeCode가 먼저 자기 감사(Self-audit)를 하고(수락 기준을 성과물에 매핑), 그다음 Codex가 심층 리뷰를 수행하며, 마지막으로 Human이 판단한다. -
왜 매번 심층 리뷰를 하지 않는가.
실제로 시도해 보았다. 두 가지 비용이 나타났다.
Codex의 심층 리뷰는 토큰 소비가 크다. 매번 Thorough Review를 실행하면 쿼터(Quota)가 금방 고갈된다. 게다가 ClaudeCode가 구현 → Codex가 리뷰 → ClaudeCode가 수정 → 재리뷰라는 사이클이 심층 모드로 매 PR마다 실행되면, 1개의 Issue를 해결하는 데 소요되는 실시간이 현저히 증가한다.
심층 리뷰를 「클로즈 판단 시에만」으로 한정하는 것은 비용 관리이자 속도 관리이기도 하다. 평소의 개발은 Tier 1로 빠르게 움직이고, 최종 확인 시에만 Tier 2를 사용한다——이것이 실운용에서 도출한 설계다.
Perplexity의 Gap Analysis는 공개 사례에 존재하지 않는 것을 5가지 특정했다:

| 격차 (Gap) | 내용 |
|---|---|
| A | 클로즈(Close) 추천 전의 자기 감사 게이트 (Self-audit gate) — 주요 제품 어디에도 문서화되어 있지 않음 |
| B | PM과 구현자가 다른 모델, 크로스 벤더(Cross-vendor)가 정책을 담당 — 실천 사례는 있으나 명문화되어 있지 않음 |
| C | 리포지토리가 운영 메모리 (AGENTS.md, WORKER_BOARD.md, Worker Report) 역할을 수행 — 공개 사례에서 찾아볼 수 없음 |
| D | 구현자 ≠ 심사자를 명시적인 거버넌스 정책 (Governance policy)으로 기록 — 관습이 아닌 문서로 존재 |
| E | 이슈 클로즈(Issue Close)를 PR 머지(Merge)와는 별개의 게이트 판단으로 두는 설계 — 분리된 사례가 없음 |
Gemini 또한 같은 방향을 지지했으나, C(리포지토리 = 운영 메모리)와 E(클로즈 게이트)를 독립적으로 특정하지는 못했다.
TheGateBreaker의 신규성은 개별 요소가 아니다. 조합이다. GitHub 네이티브 운영 모델로서, 명시적인 역할, 클로즈 게이트, 영구 리포트를 조합한 것이다. Perplexity가 이를 외부에서 뒷받침했다 — 현재로서는 이 프로젝트에서 가장 강력한 외부 검증이다.
병렬 워커의 브랜치 충돌
여러 AI 워커가 동일한 작업 트리(Working tree)를 사용하면, git의 브랜치 상태가 자신도 모르는 사이에 변경될 수 있다. ClaudeCode가 구현을 마치고 커밋(Commit)하려고 했을 때, 다른 작업이 브랜치를 전환해 버리는 상황이 발생한다. 대책: 커밋 전에 반드시 브랜치를 확인한다.
PR 없는 직접 push가 게이트를 무효화한다
Tier 2 클로즈 게이트는 PR의 diff를 Codex에게 보여주기 때문에 성립한다. main에 직접 push한 뒤 사후에 PR을 생성하면, diff는 0이 된다. Codex는 아무것도 심사할 수 없다. 게이트가 작동하는 것처럼 보이지만, 실제로는 작동하지 않는 것이다. 이를 운영 중에 발견하고, "클로즈 후보 변경 사항은 feature branch에 두고, PR을 연 다음에 Tier 2를 시작한다"라는 규칙을 명시했다. 시스템을 만들어도, 빈틈을 메우는 규칙을 쓰지 않으면 작동하지 않는다.
Gmail Inbox가 Human의 진척 컨트롤 큐(Queue)
Human은 GitHub를 계속 폴링(Polling)할 필요가 없다. 워커의 완료, 리뷰 결과, 판단 요청이 Gmail로 전달된다. Human은 Gmail을 기점으로 GitHub를 열어 판단한다. 이를 통해 Human이 상시 모니터링하지 않아도 제어력을 유지할 수 있다.
야크 쉐이빙 (Yak shaving)의 유혹
운영 모델을 정비하다 보면, "운영 모델을 만드는 것" 자체가 목적이 되어버릴 위험이 있다. 현재 있는 것을 정의하고, 수익이 발생하거나 자동화가 정말로 필요해지기 전까지는 자동화하지 않는다 — 라는 명시적인 보류(Shelving)가 필요했다.
지금 바로 채택할 것:
- GitHub Issue를 태스크 스펙(Task spec)으로 사용
- PR을 리뷰 서피스(Review surface)로 사용
- Worker Report를 세션 로그(Session log)로 사용
- Issue Close Gate (Tier 1 경량 / Tier 2 심층의 2단계)
- Gmail Inbox를 Human의 진척 컨트롤 큐로 사용
보류 항목 (트리거가 발생할 때까지):
- Perplexity API 브릿지
- 커스텀 GitHub App · GitHub Actions 자동화
- 풀 대시보드 (Full dashboard)
보류를 해제하는 트리거: 프로젝트에서 수익이 발생할 때, Perplexity/Gemini의 수동 워크플로우가 진정한 병목(Bottleneck)이 될 때, GitHub · Worker Report · Gmail의 상태 불일치가 운영상의 고통이 될 때.
이 모델은 작동하고 있다. 검증은 현재까지 1개의 프로젝트뿐이다.
- 워커 역할 매트릭스(Worker role matrix)를 다른 프로젝트나 다른 팀에 이식할 수 있는가
- Tier 2 클로즈 게이트의 비용이 품질 향상에 상응하는가 (그렇게 느끼고 있지만 수치는 없다)
- Perplexity의 "외부 리서치 워커" 능력이 다른 토픽에서도 재현되는가 (#455은 1회의 실험)
- 이 모델이 성립하기 위한 조건은 무엇인가 — Human의 관여량, 워커 수, 태스크의 종류
"당연히 그래야 한다"라고 아직 단정 지을 수는 없다. 그래서 기록으로 남긴다.
AI Worker OS 시리즈 Article 2입니다. Article 1: 왜 AI는 자신의 PR을 리뷰해서는 안 되는가
팔로우를 기다립니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기