github-cli

거대한 AI 생성 풀 리퀘스트 하나를 검토 가능한 스택으로 바꾸기 (새 탭에서 열림)

AI 코딩 에이전트는 짧은 시간에 대규모 기능을 구현하지만, 모든 변경을 하나의 거대한 PR에 담는 방식은 리뷰 품질과 병합 속도를 떨어뜨린다. 이 글은 기능을 데이터·API·애플리케이션 연결·UI처럼 논리적 계층으로 나누고, 각 계층을 작은 PR로 쌓는 “스택드 풀 리퀘스트(stacked pull requests)”를 대안으로 제시한다. 이를 통해 에이전트의 생산성은 유지하면서도 각 변경을 독립적으로 검토하고 관리할 수 있다. ## AI가 만든 대규모 PR의 문제 - 쇼핑 어시스턴트에 상품 검색 기능을 추가하면 다음 변경이 한 PR에 함께 들어가기 쉽다. - 새 데이터 모델과 시드 데이터 - API 라우트와 입력 검증 - 클라이언트 연결 - UI 및 빈 상태·오류 상태·대체 상태 - 결과적으로 1,000~1,700줄 이상의 큰 diff가 만들어질 수 있다. - 리뷰어는 변경 내용을 한 번에 이해하기 어렵고, PR 설명이 길지만 구체적이지 않으면 검토를 뒤로 미루게 된다. - 리뷰가 늦어지면서 문맥이 사라지고 피드백 품질이 낮아지며, 충돌과 수동 동기화가 늘어난다. - 결국 기능이 충분히 검토되지 않은 채 병합될 위험이 커진다. ## 스택드 풀 리퀘스트의 기본 원리 - 하나의 대형 PR 대신 기능을 논리적으로 분해해 여러 개의 작은 PR로 만든다. - 각 PR은 하나의 관심사만 다루며, 리뷰어가 한 번에 이해할 수 있는 크기로 제한한다. - PR은 의존성 순서에 따라 연결된다. - 하위 계층이 먼저 구현되고, 상위 계층은 그 변경을 기반으로 작업한다. - 이전 계층에서 얻은 문맥은 다음 계층으로 자연스럽게 이어지므로, 전체 기능을 매번 처음부터 읽을 필요가 없다. - 데이터 담당자, 백엔드 담당자, UI 담당자처럼 변경 영역에 맞는 리뷰어를 배정할 수 있다. ## 상품 검색 기능의 스택 구조 | 계층 | 브랜치 | 작업 내용 | 의존 대상 | |---|---|---|---| | L1 | `feat/catalog-data` | 타입이 지정된 카탈로그, 시드 데이터, 검증, 데이터 접근 모듈 | `main` | | L2 | `feat/search-api` | 검증을 포함한 `/api/products/search` 엔드포인트 | L1 | | L3 | `feat/chat-grounding` | 채팅이 API를 호출하고 실제 상품 데이터에 기반해 응답 | L2 | | L4 | `feat/grounded-ui` | 상품 인용 카드와 UI 상태 처리 | L3 | - 데이터, API, 애플리케이션 연결, UX가 각각 독립된 작업 단위가 된다. - 각 계층은 자체적으로 리뷰할 수 있지만, 전체 기능은 계층 간 의존성을 통해 완성된다. - 가장 기반이 되는 작업을 스택의 아래쪽에 배치하고, 그 위에 이를 사용하는 작업을 쌓는다. ## GitHub 도구와 초기 설정 - GitHub는 PR 화면뿐 아니라 터미널에서도 스택드 PR을 관리할 수 있다. - `gh-stack` CLI 확장 설치: ```bash gh extension install github/gh-stack ``` - 코딩 에이전트가 스택 구조를 이해하고 생성·관리하도록 관련 스킬을 설치할 수 있다. ```bash gh skill install github/gh-stack ``` 또는: ```bash npx skills add github/gh-stack ``` - 스택을 시작하기 전에 스택의 기준 브랜치(stack base)를 정해야 한다. - 일반적으로 `main`이 기준이 된다. - CI 검사와 병합 규칙이 전체 스택에서 이 기준을 바탕으로 평가된다. - 모든 계층에 CI가 존재하는지 확인해야 한다. - 각 PR 계층마다 CI 검사가 실행된다. - 따라서 작은 PR이라도 테스트와 규칙 검증을 통과해야 한다. ## 에이전트별 작업 분담 - 에이전트에게 전체 기능을 한 번에 맡기기보다, 계층별로 역할과 범위를 지정한다. - 예시 구성: - L1: 데이터 모델러 에이전트 - L2: 백엔드 에이전트 - L3: 프론트엔드 에이전트 - L4: 프론트엔드 에이전트 - 각 에이전트는 하나의 작업 스트림과 엄격한 범위를 따르도록 구성한다. - 이런 방식은 에이전트가 자동화 루프에서 작업하더라도 결과물이 지나치게 커지는 것을 방지한다. - 작업 순서는 데이터 기반을 먼저 만들고, API, 채팅 연결, UI 순으로 진행한다. ## 실용적인 적용 방법 - 기능을 시작할 때 먼저 데이터·도메인 모델·API·애플리케이션 연결·UI로 나눈다. - 각 PR이 단일 관심사만 포함하는지 확인한다. - 기반 브랜치를 먼저 만들고, 각 후속 브랜치를 바로 이전 계층에서 파생한다. - 계층별로 적절한 리뷰어를 배정하고, 각 PR에 해당 계층의 목적과 검증 방법을 명확히 작성한다. - AI 에이전트에는 “전체 기능 구현”이 아니라 특정 스택 계층과 변경 범위를 명시하는 것이 좋다. - 스택드 PR은 리뷰 부담을 줄이는 대신 브랜치 의존성을 관리해야 하므로, CLI와 자동화 도구를 함께 사용하는 것이 효과적이다.

던전 & 데스크톱: GitHub Copilot CLI로 절차적으로 생성되는 로그라이크 만들기 (새 탭에서 열림)

GitHub Dungeons는 GitHub 저장소를 터미널에서 플레이할 수 있는 로그라이크 던전으로 변환한 Go 기반 GitHub CLI 확장이다. 저장소의 최신 커밋 SHA를 시드로 삼아 BSP(Binary Space Partitioning) 방식으로 방과 통로를 생성하므로, 같은 커밋에서는 같은 맵이 만들어지고 코드가 변경되면 던전도 달라진다. 저자는 GitHub Copilot CLI의 `/delegate`와 에이전트를 활용해 구현과 문서화를 위임하고, 게임 설계와 플레이 경험에 집중했다. ## 코드 저장소가 로그라이크 던전이 되는 방식 - 저장소의 코드 구조를 바탕으로 방, 통로, 적, 출구가 있는 던전을 생성한다. - 플레이어는 터미널에서 화살표 키로 이동하며 버그와 싸우고 출구를 찾아야 한다. - HP가 0이 되면 처음부터 다시 시작하는 영구 사망(permadeath) 구조를 따른다. - 저장소마다 맵의 구조가 달라지고, 커밋이 바뀔 때마다 새로운 레이아웃이 만들어진다. - 최신 커밋 SHA를 난수 생성의 시드로 사용한다. - 같은 커밋은 항상 같은 던전을 생성한다. - 서로 다른 저장소는 구조적으로 서로 다른 맵을 만든다. - 코드 변경은 던전의 변화로 이어진다. ## 로그라이크와 절차적 생성 - 로그라이크는 1980년대 게임 *Rogue*에서 시작된 장르다. - 주요 특징은 다음과 같다. - 실행할 때마다 달라지는 절차적 생성 맵 - 죽으면 다시 시작하는 영구 사망 - 텍스트 기반 인터페이스 - 절차적 생성은 콘텐츠를 사람이 하나씩 설계하는 대신, 규칙과 무작위성을 이용해 알고리즘으로 생성하는 방식이다. - 하나의 던전을 직접 만드는 것이 아니라, 여러 던전을 생성할 수 있는 시스템을 만든다는 점이 핵심이다. - 이러한 구조 덕분에 매 플레이마다 레이아웃과 상황이 달라져 반복 플레이가 가능해진다. ## BSP 기반 던전 생성 - BSP(Binary Space Partitioning)는 큰 공간을 반복해서 더 작은 영역으로 나누는 알고리즘이다. - 기본 흐름은 다음과 같다. - 전체 던전을 하나의 큰 직사각형 공간으로 설정한다. - 공간을 두 영역으로 분할한다. - 각 영역을 재귀적으로 다시 나눈다. - 충분히 작은 영역 안에 방을 배치한다. - 방들을 통로로 연결한다. - BSP가 로그라이크에 적합한 이유는 다음과 같다. - 직사각형 방을 만들기 쉽다. - 방 사이의 연결 구조를 보장하기 쉽다. - 완전히 무작위인 맵보다 구조적으로 이해하기 쉽다. - 일정한 규칙 안에서 무작위성이 생겨 매번 다른 맵을 만들 수 있다. - 결과적으로 맵은 무질서하지 않으면서도 반복 플레이에 적합하고, 막다른 길이나 이동 불가능한 구조를 줄일 수 있다. ## GitHub Copilot CLI를 활용한 개발 - 저자는 Go 문법을 모두 직접 작성하기보다, Copilot CLI에 원하는 동작을 자연어로 설명하는 방식으로 개발했다. - `/delegate` 명령은 작업을 클라우드에서 실행되는 Copilot 코딩 에이전트에 위임한다. - 개발자는 요구사항을 평문으로 작성한다. - 에이전트가 비동기적으로 코드를 구현한다. - 작업이 끝나면 결과가 Pull Request로 생성된다. - 개발자는 PR을 검토하고 수정해 완성도를 높인다. - 예를 들어 다음과 같은 요구를 위임했다. - 레벨이 올라갈수록 적을 늘리고, 대신 체력 회복 아이템도 추가하기 - 플레이어를 무적으로 만드는 치트 코드 추가하기 - Copilot이 초기 구현과 보일러플레이트를 맡는 동안 저자는 난이도 조정, 게임 메커니즘, 이스터 에그 등 플레이 경험에 집중했다. ## 에이전트를 통한 문서화 - 저자는 Copilot으로 “dungeon scribe”라는 별도 에이전트도 생성했다. - 이 에이전트는 다음 작업을 수행했다. - 던전 생성 방식에 대한 문서 작성 - ASCII 아트 다이어그램 생성 - BSP 기반 레이아웃 생성 과정 설명 - 이를 통해 구현 코드뿐 아니라 알고리즘의 동작 원리와 프로젝트 구조도 함께 문서화할 수 있었다. ## 실용적인 결론 절차적 생성과 커밋 기반 시드를 결합하면 코드 저장소 자체를 재현 가능하면서도 변화하는 게임 세계로 만들 수 있다. 또한 Copilot CLI의 `/delegate`처럼 구현 작업을 에이전트에 위임하고 결과를 PR 단위로 검토하는 방식은, 개발자가 반복적인 코딩보다 기능 설계와 사용자 경험에 집중하는 데 유용하다.

GitHub 에이전틱 워크플로의 토큰 효율성 향상 (새 탭에서 열림)

GitHub Agentic Workflows는 반복 실행되는 CI 자동화인 만큼 토큰 비용이 누적되기 쉬우며, YAML과 실행 로그를 분석하면 이를 체계적으로 줄일 수 있다. GitHub는 토큰 사용량을 표준화해 수집하고, 감사·최적화 워크플로를 통해 불필요한 MCP 도구를 제거하거나 GitHub CLI로 대체했다. 그 결과 동작을 바꾸지 않고도 요청당 수천 토큰을 절약할 수 있었다. ## 토큰 사용량을 표준화해 기록 - Claude CLI, Copilot CLI, Codex CLI 등 에이전트 프레임워크마다 로그 형식이 달라 사용량 비교가 어려웠다. - 인증 정보를 에이전트에 직접 노출하지 않도록 사용하는 API 프록시를 활용해 모든 실행의 토큰 사용량을 한 형식으로 수집했다. - 각 워크플로는 `token-usage.jsonl` 아티팩트를 생성한다. - API 호출별 입력 토큰 - 출력 토큰 - 캐시 읽기·쓰기 토큰 - 모델과 제공업체 - 호출 시각 - 실행 로그와 이 데이터를 결합해 워크플로별 일반적인 토큰 소비 패턴과 이상 실행을 파악했다. ## 감사·최적화 워크플로로 자동 개선 - **Daily Token Usage Auditor** - 최근 실행의 토큰 사용량을 워크플로별로 집계한다. - 사용량이 급증한 워크플로, 비용이 큰 워크플로, 비정상적인 실행을 탐지한다. - 예를 들어 평소 4번의 LLM 턴으로 끝나던 작업이 18턴까지 늘어난 경우를 표시한다. - **Daily Token Optimizer** - 감사 결과가 나온 워크플로의 YAML과 최근 로그를 분석한다. - 불필요한 동작과 구체적인 최적화 방안을 GitHub Issue로 제안한다. - 감사·최적화 도구 자체도 에이전트 워크플로이므로 사용량을 함께 측정할 수 있고, 이를 통해 개선 작업이 반복되는 순환 구조를 만든다. ## 사용하지 않는 MCP 도구 제거 - LLM API는 상태를 유지하지 않기 때문에 MCP 도구의 함수명과 JSON 스키마가 매 요청에 포함되는 경우가 많다. - GitHub MCP 서버의 도구가 40개라면 매 턴마다 10~15KB의 스키마가 추가될 수 있다. - 실제로 두 도구만 사용하는 에이전트라면 나머지 38개 도구의 스키마는 매번 순수한 오버헤드가 된다. - 도구 설정과 실제 호출 기록을 대조하면 장기간 사용되지 않은 도구를 식별할 수 있다. - 스모크 테스트에서는 사용하지 않는 MCP 도구를 제거해 요청당 컨텍스트를 8~12KB 줄였고, 동작 변경 없이 실행당 수천 토큰을 절약했다. ## 데이터 조회를 GitHub CLI로 대체 MCP 호출은 단순한 데이터 조회에도 LLM의 판단 과정을 요구한다. - 에이전트가 도구를 선택하고 인자를 구성한 뒤 결과를 받는 과정 전체가 추가 LLM 호출이 된다. - 이 과정에서 도구 스키마, 인자 JSON, 응답 데이터가 모두 토큰을 소비한다. - 반면 `gh pr diff` 같은 GitHub CLI 명령은 결정적인 API 요청이므로 LLM 추론 단계가 필요 없다. GitHub는 두 가지 방식으로 MCP 데이터 조회를 CLI로 옮겼다. - **에이전트 실행 전 데이터 다운로드** - 항상 필요한 PR diff, 변경 파일 목록 등을 에이전트 시작 전에 `gh` 명령으로 가져온다. - 결과를 작업 공간 파일에 저장하고 에이전트가 파일을 읽도록 한다. - MCP 호출과 별도 추론 라운드트립을 제거하며, 에이전트가 Bash 도구를 활용해 데이터를 효율적으로 처리할 수 있다. - **에이전트 내부 CLI 프록시** - 실행 중 어떤 데이터를 가져올지 에이전트가 결정해야 하는 경우 사용한다. - 인증 토큰을 노출하지 않는 투명 HTTP 프록시가 CLI 요청을 GitHub API로 전달한다. - 에이전트는 `gh pr view --json` 같은 명령을 실행하고 구조화된 결과를 받는다. - 보안상 “에이전트에 비밀정보를 직접 제공하지 않는다”는 원칙을 유지하면서 토큰 사용량을 줄인다. ## 효율성 측정에서 고려할 요소 단순히 토큰 개수만 비교하면 최적화 효과를 정확히 판단하기 어렵다. - 모델별 토큰 가격이 다르다. - Claude Haiku와 Sonnet은 비슷한 토큰 수를 사용할 수 있지만 Haiku가 토큰당 약 4배 저렴하다. - 이를 반영하기 위해 모델과 토큰 종류에 가중치를 적용한 **Effective Tokens(ET)** 지표를 사용한다. ```text ET = m × (1.0 × I + 0.1 × C + 4.0 × O) ``` - `m`: 모델 비용 배수 - Haiku = 0.25 - Sonnet = 1.0 - Opus = 5.0 - `I`: 새로 처리한 입력 토큰 - `C`: 캐시에서 읽은 토큰 - `O`: 출력 토큰 - 출력 토큰은 입력 토큰보다 비용 영향이 크므로 4배 가중치를 적용한다. - 따라서 최적화가 토큰 수를 줄였는지뿐 아니라, 더 저렴한 모델을 사용했는지와 작업 품질을 유지했는지도 함께 평가해야 한다. 반복 실행되는 에이전트 워크플로는 먼저 사용량을 관측하고, 실제 사용 도구만 남기며, 결정적인 데이터 조회를 CLI나 사전 다운로드로 이동하는 방식이 효과적이다. 특히 MCP를 편리하다는 이유로 전체 등록하기보다 워크플로별 최소 도구만 구성하고, ET 같은 비용 반영 지표로 품질 저하 없이 최적화되는지 검증하는 것이 권장된다.