GitHub의 AI Agent 실행 워크스페이스 진화: Copilot 코딩 Agent와 전용 macOS Runner 협업 Runbook

지난 10년간 GitHub는 코드, issue, PR, Actions, 권한 모델을 사람의 협업을 위한 그래프로 묶어 왔습니다. 사람이 코드를 작성하고, PR을 열고, PR을 리뷰하고, CI가 통과하면 사람이 머지하는 흐름이 표준이었습니다. 2025–2026의 결정적 변화는 「코드를 쓰는」 주체가 바뀐다는 점입니다. 저장소는 「코드 창고」에서 「Agent의 실행 샌드박스」로 진화하고 있습니다.

이 전환을 함께 미는 제품 형태가 세 가지입니다. Copilot 코딩 Agent(cloud agent)는 Issue 할당이나 Chat 프롬프트를 시작점으로 Actions의 전용 VM을 띄우고, RAG로 저장소를 검색하고, 작업을 계획하며, draft PR에 commit을 push합니다. .github/agents/ 커스텀 Agent는 팀이 여러 전문 역할(성능 최적화, 테스트 작성, 문서 관리)을 선언할 수 있게 합니다. Agentic Workflows(gh-aw, 기술 프리뷰)는 .github/workflows/ 안의 자연어 Markdown을 Actions YAML로 컴파일하고, Copilot / Claude / Codex가 샌드박스에서 이벤트 기반의 상시 자동화를 수행합니다.

세 계층이 겹치면 GitHub의 제품 의미는 「사람이 코드를 쓴다 → 저장소에 보관된다」에서 「사람이 목표를 적는다 → Agent가 저장소 안에서 실행한다 → 사람이 draft PR을 검토한다 → CI/CD가 배포를 트리거한다」로 이동합니다. 개별 도구를 쫓는 것보다 이 전환을 이해하는 것이 더 중요하며, 이를 떠받치는 컴퓨팅 계약(셀프 호스트 Runner, 전용 Apple Silicon 노드)이 새로운 토대가 됩니다.

많은 팀이 Copilot 코딩 Agent나 Claude Code를 GitHub-hosted Runner에 곧장 연결합니다. 단기적으로는 편하지만, 장기적으로는 다음 네 가지 비용에 부딪힙니다:

• 분 단위 풀 × Agent 장기 작업: Agent 작업은 컴파일, 단위 테스트, 보안 스캔을 반복합니다. 단일 Job의 wall time이 30분을 넘는 경우가 흔합니다. 분당 과금에 이웃 Job 노이즈가 더해져 월간 청구액이 비선형으로 증가합니다.
• 서명 자산 노출 위험: 공유 Runner에서는 secrets가 Agent 환경에 주입됩니다. 프롬프트 인젝션이나 악성 의존성을 만나면 서명 인증서와 프로비저닝 프로파일에 실질적인 유출 경로가 생깁니다. GitHub의 SafeOutputs MCP Gateway, Agent Workflow Firewall(AWF), threat detection job은 바로 이 위험을 막기 위해 Agent의 쓰기 권한을 실행 환경으로부터 물리적으로 분리합니다.
• 「사람이 draft PR을 검토」하는 부하가 예측 불가능: Agent는 하룻밤에 수십 개의 draft PR을 열 수 있습니다. AGENTS.md와 커스텀 Agent의 가드레일이 없으면 리뷰어가 침몰합니다. GitHub는 draft PR을 사람이 승인하기 전까지 CI/CD를 돌리지 않도록 설계하여, 「사람이 루프에 있다」는 스위치를 기본 제공합니다.
• Apple Silicon 자원을 과소평가: iOS/macOS 프로젝트는 Agent에게 Xcode, 시뮬레이터, TestFlight 업로드를 맡깁니다. DerivedData, 서명 keychain, 버전 고정된 Xcode가 필요합니다. 이러한 요구는 범용 클라우드 macOS Runner에서는 느리고 비쌉니다. 전용 노드가 더 저렴하고 감사 친화적입니다.

이 항목들을 검토에 올리면 결론은 분명합니다. Agent 실행 워크스페이스에는 전용 컴퓨팅 자원과 명시적 보안 계약이 필요합니다. 범용 Runner로 「대충 돌리기」는 통하지 않습니다.

아래 표는 자주 혼동되는 세 가지 개념을 엔지니어링 시각으로 정렬한 것입니다. 팀 검토 시 올바른 진입점을 고르는 데 유용합니다.

세 계층은 배타적이지 않습니다. 성숙한 팀은 Copilot 코딩 Agent를 「코드 작성」 기본 진입점으로 삼고, .github/agents/로 역할(테스트 Agent, 성능 Agent, 문서 Agent)을 좁히며, Agentic Workflows로 이벤트 기반 상시 Agent(CI 실패 자동 분석, Issue 자동 트리아지)를 함께 굴립니다. 결과적으로 GitHub는 「이벤트 → Agent → 제한된 쓰기」의 깔끔한 실행 평면이 됩니다.

「Agent가 내 저장소를 직접 만지게 한다」는 구성에서는 모델 선택보다 보안 계약이 더 중요합니다. GitHub Agentic Workflows는 이 계층을 명시적으로 드러내며, 셀프 호스트 환경으로 옮길 때도 그대로 적용할 가치가 있습니다:

• SafeOutputs MCP Gateway: Agent는 GitHub API를 직접 호출하지 않습니다. 의도한 쓰기 작업을 Gateway에 선언하면 Gateway가 artifact로 버퍼링합니다. Agent가 종료된 뒤에는 쓰기 권한을 가진 별도 Job이 검증, 정제, 레이트 제한을 거쳐 실행합니다. Agent 본체는 항상 읽기 전용이고 secrets를 보유하지 않습니다.
• Agent Workflow Firewall(AWF): Agent를 격리 컨테이너에 넣고 iptables + Squid 프록시로 egress를 통제하며, 도메인 allowlist만 허용합니다. 프롬프트 인젝션 이후의 데이터 유출과 외부 C2를 차단합니다.
• Threat Detection Job: Agent의 patch를 적용하기 전, 보안 특화 Agent가 프롬프트 인젝션, 자격 증명 유출, 악성 코드 패턴을 한 번 스캔합니다. 의심스러우면 워크플로우 전체를 실패시킵니다.
• Branch Protection + 사람 검토: Copilot 코딩 Agent는 자신이 만든 브랜치에만 push할 수 있고, draft PR은 사람의 승인이 있어야 CI/CD가 시작됩니다. 배포 경로에서 「사람」은 여전히 fail-safe 밸브입니다.

2025년 OpenAI, Cursor, Jules, Amp, Factory가 함께 정한 AGENTS.md 규격은 Agent 실행 워크스페이스의 「사람 측 계약」입니다. 저장소 루트에 「Agent를 위한 README」를 두어 프로젝트 구조, 빌드 명령, 테스트 명령, 스타일 제약, 보안 주의 사항을 예측 가능한 위치에 제공합니다.

• 계층 해석: 하위 디렉터리에도 AGENTS.md를 둘 수 있고, Agent는 변경 대상 파일에서 가장 가까운 파일을 채택합니다. OpenAI 본가 저장소에는 현재 88개의 AGENTS.md가 있습니다.
• Must-follow / Should 분리: 「main에 직접 commit 금지」, 「Xcode 16.2 고정」 같은 하드 규칙과 「Swift Testing 우선」 같은 소프트 선호를 함께 적을 수 있어 Agent 행동이 수렴합니다.
• README와 상호 보완: README는 사람과 외부 기여자, AGENTS.md는 Agent를 위한 것입니다. 빌드 절차, 긴 컨텍스트 규칙, 보안 주의 사항은 AGENTS.md에 적습니다.
• Copilot CLI와 호환: JetBrains, VS Code의 Copilot CLI Agent는 글로벌 ~/.copilot/agents/.agent.md를 이미 지원하여 팀 규약 위에 개인 선호를 겹쳐 둘 수 있습니다.

iOS/macOS 프로젝트에서는 AGENTS.md에 Xcode 고정 명령, xcodebuild 진입점, 서명 사전 스크립트, -strict-concurrency=complete 같은 게이트, 전용 Runner 라벨과 디스크 루트 경로, 손대선 안 되는 디렉터리를 적습니다. 규칙이 명시적일수록 Agent의 「자유 행동」 비율은 낮아집니다. 이는 기존 NUKCLOUD 전용 Apple Silicon 노드 Runbook의 「베이스라인 고정, SSH 베이스라인, 캐시 분할, 서명 격리」 체크리스트와 같은 사고이며, AGENTS.md는 그 Agent 가독 버전이라고 보면 됩니다.

아래 수치는 일반적인 iOS/macOS CI + Agent 도입 현장의 내부 정렬값입니다. 자릿수의 기준으로 삼고 자사 측정값을 우선시하시기 바랍니다:

• Agent 단일 Job wall time: Copilot 코딩 Agent가 「버그 수정 + 테스트 추가」를 수행하면 보통 8–25분, 「모듈 리팩터링 + 풀 빌드」는 30–90분에 이릅니다. 공유 분 단위 풀의 P95 대기 시간은 릴리스 피크에 15–45분 수준입니다.
• draft PR 페이스: Copilot 코딩 Agent 도입 후 중형 팀은 일일 draft PR 수가 이전 대비 2–5배 늘어나는 경향을 보입니다. 병목은 「코드 작성」에서 「PR 검토」로 이동하며, AGENTS.md와 .github/agents가 그 레버 역할을 합니다.
• SafeOutputs 효과: SafeOutputs + AWF를 켜면 Agent 본체는 GITHUB_TOKEN, secrets, MCP API 키를 일절 보유하지 않습니다. 프리뷰 기간의 threat detection job 거부율은 약 0.5–2%이며, 대부분은 프롬프트 인젝션 유사 콘텐츠 오탐입니다.
• 전용 Apple Silicon 효과: NUKCLOUD 전용 노드에 Agent 전용으로 --concurrent-jobs 2–4를 예약하면, 풀 xcodebuild Job의 wall time이 범용 macOS Runner 대비 통상 25–40% 단축됩니다. DerivedData 캐시 히트가 누적되면 추가로 30–60%가 줄어듭니다.
• 리뷰 부하의 변화: Copilot 코딩 Agent는 PR을 열기 전에 자체적으로 Copilot Code Review를 1회 수행하므로, 첫 라운드의 사람 리뷰 시간이 단축됩니다. 대신 리뷰어는 설계 의도와 시스템 경계에 집중해야 하며, 구문 수준 지적은 줄어듭니다.

전용 Apple Silicon Runner와 결합하는 최소 실행 가능 Runbook입니다. 순서대로 적용하면 충분하며, 첫 날부터 완벽한 모습을 추구할 필요는 없습니다.

1. 01
   AGENTS.md 한 장 작성: 루트에 Must-follow(Xcode 버전, 빌드 명령, 손대지 말 디렉터리, Branch Protection)와 Should(스타일, 커밋 형식)를 기재합니다. 필요한 하위 디렉터리에 추가로 둡니다. OpenAI Codex / Cursor / Copilot CLI가 모두 해석합니다.
2. 02
   .github/agents/ 커스텀 Agent 선언: 최소 세 역할——테스트 Agent(*Tests*만 수정, 풀 단위 테스트 실행), 문서 Agent(.md와 changelog만 수정), 성능 Agent(먼저 벤치마크 후 수정). prompt로 도구 호출 범위와 필수 단계를 묶습니다.
3. 03
   Agentic Workflows(gh-aw) 도입: Markdown으로 issue 트리아지, CI 실패 자동 수정, 문서 점검을 기술합니다. SafeOutputs를 켜서 Agent 본체를 읽기 전용으로 유지하고 모든 쓰기를 제한된 Job을 통과시킵니다.
4. 04
   전용 Apple Silicon Runner 등록: 주문 페이지에서 NUKCLOUD 전용 노드를 개통하고 셀프 호스트 Runner로 등록한 뒤 agent-macos, xcode-16, signing-isolated 등 라벨을 부여합니다. 서명 keychain은 「쓰기 권한 Job」에만 마운트합니다.
5. 05
   보안 계약 부설: 노드에서 Squid + iptables로 AWF를 재현합니다. secrets는 모두 OIDC + 클라우드 KMS로 옮겨 Agent 컨테이너가 직접 읽을 수 없도록 합니다. draft PR은 사람 검토를 통과해야 CI/CD에 진입합니다.
6. 06
   리뷰 루프와 KPI: 주간으로 「draft PR 수 / 리뷰 소요 시간 / 사람 반려율 / threat detection 적중률」을 회고하고, KPI에 따라 AGENTS.md와 커스텀 Agent prompt를 미세 조정합니다. Swift 6 엄격 동시성 CI 게이트 Runbook의 「단계적, 롤백 가능」 페이스와 함께 진행합니다.

아래 표는 리뷰 정렬용입니다. 구체 수치는 재무와 네트워크 팀이 자사 버전을 채워 넣으면 됩니다.

이 표의 핵심은 「어느 쪽이 더 싸냐」가 아니라 「Agent 실행 워크스페이스를 문서로 입증할 수 있느냐」입니다. 전용 노드라면 SafeOutputs, AWF, 사람 검토 규율을 구체적 노드와 Runner 라벨에 안착시킬 수 있어 슬로건에 머무르지 않습니다.