Molayo

© 2026 Molayo

Qiita헤드라인2026. 06. 15. 13:25

AI agent를 GitHub Actions에 도입하기 전에 결정해야 할 경계선

요약

GitHub Actions에 AI 에이전트를 도입할 때 고려해야 할 운영 경계선과 가이드라인을 제시합니다. 에이전트의 권한 범위, 작업 조건, 그리고 인간의 리뷰 비용을 최소화하기 위한 단계적 접근 방식을 다룹니다.

핵심 포인트

  • 에이전트의 읽기/쓰기 권한 및 작업 중단 조건을 명확히 정의해야 함
  • 초기 단계에서는 수정보다 CI 실패 원인 조사 위주로 활용 권장
  • repo 전체가 아닌 특정 파일 및 경로에 대해서만 제한적 권한 부여 필요
  • 에이전트의 작업 범위를 규정하는 'Task contract' 설정이 중요함

GitHub의 Agentic Workflows preview를 보고 가장 먼저 든 생각은 "드디어 agent가 CI 측면에 들어왔구나"였습니다.

지금까지의 coding agent는 대개 editor나 issue 옆에 있었습니다. 인간이 task를 던지면, branch가 생기고, PR diff를 확인합니다. 두려움은 있지만, 여전히 "인간이 호출한 작업"이라는 감각이 남아 있습니다.

하지만 GitHub Actions 쪽으로 넘어오면 이야기가 조금 달라집니다. CI failure, issue triage, docs update와 같은 repo event에 대해 agent가 움직일 수 있습니다. 편리합니다. 상당히 편리하죠. 다만, frontend repo에서 이를 무분별하게 도입하면 review queue가 순식간에 혼탁해집니다.

이 기사에서는 GitHub의 신기능 소개가 아니라, AI agent를 GitHub Actions에 넣기 전에 정해두어야 할 경계선을 정리합니다.

agent를 도입할 때, 자칫 "어떤 model이 똑똑한가", "prompt를 어떻게 작성할 것인가"부터 시작하고 싶어집니다.

하지만 Actions에 넣는다면, 먼저 결정해야 할 것은 이쪽입니다.

  • agent가 읽어도 되는 것
  • agent가 변경해도 되는 것
  • agent가 멈추는 조건
  • 인간이 review에서 볼 로그
  • PR을 생성해도 되는 task와, comment만 남겨야 하는 task

이 부분이 모호한 상태로 agent를 가동하면, 성공했을 때나 실패했을 때나 판단하기 어렵습니다.

"뭔가 고쳐줬네"라는 PR은 기분이 좋습니다. 하지만 어떤 로그를 보고, 어떤 파일을 읽었으며, 어디를 건드리지 않았는지 알 수 없는 PR은 review 비용이 높습니다.

처음부터 바로 commit / push까지 허용하지 않는 것이 좋습니다.

처음 시작한다면 CI failure analysis가 다루기 쉬울 것이라고 생각합니다. frontend repo라면 lint, typecheck, unit test, Playwright의 실패가 입구가 됩니다.

이 단계에서 agent에게 시키는 일은 수정이 아니라 조사입니다.

allowed:
- read workflow logs
- read test output
...

출력 또한 PR이 아니라, issue comment나 workflow summary로도 충분합니다.

CI failure summary:
- failed job: typecheck
- suspected files:
...

이것만으로도 꽤 도움이 됩니다. 중요한 것은 agent의 출력을 "수정 완료"로 취급하지 않는 것입니다. 아직은 조사 메모일 뿐입니다.

다음에 write permission을 부여하더라도, repo 전체에 부여하지 않는 것이 좋습니다.

예를 들어 frontend repo라면, 처음에는 이 정도가 무난합니다.

  • docs / README의 추종
  • Storybook example의 가벼운 수정
  • unit test fixture의 업데이트
  • component demo의 copy 수정
  • lint / format의 명확한 수정

반대로, 처음부터 건드리지 않는 것이 좋은 곳도 있습니다.

.github/workflows/**

package.json

  • lockfile
  • auth / payment / permission 주변
  • release / deploy script
  • migration script

"frontend니까 안전하다"라고 단정할 수 없습니다. CSS 수정이라도 범위가 넓어지면 화면 전체에 영향을 미칩니다. copy 변경이라도 product의 의미가 바뀔 수 있습니다.

따라서, workflow contract를 명시합니다.

Task contract:
- CI failure의 원인이 lint / unit test / typecheck 범위라면 수정해도 좋다
- 건드려도 되는 path:
...

이 contract가 있으면 인간의 review가 상당히 편해집니다.

diff만 보고 "뭐, 돌아가겠지"라고 판단하는 것이 아니라, "애초에 agent가 건드려도 되는 범위였는가"를 먼저 확인할 수 있기 때문입니다.

agent의 PR은 인간의 PR보다 review surface를 더 넓게 잡는 것이 좋습니다.

최소한으로 확인해야 할 것은 이 5가지입니다.

  • PR diff (PR 차이)
  • GitHub Actions log (GitHub Actions 로그)
  • agent session log (agent 세션 로그) 또는 chat context (채팅 컨텍스트)
  • 実行した command (실행한 커맨드)
  • agent が触らなかった範囲 (agent가 건드리지 않은 범위)

특히 중요한 것은 마지막 두 가지입니다.

"테스트 통과했습니다"라는 말만으로는 부족합니다. 어떤 command (커맨드)를 실행했는지. pnpm test 인지, 대상 테스트만 수행했는지, typecheck (타입 체크)는 확인했는지, build (빌드)는 확인하지 않았는지 말이죠.

agent는 그럴싸하게 설명할 수 있습니다. 그러므로 설명의 자연스러움이 아니라, 작업의 흔적을 보는 것이 좋습니다.

PR template (PR 템플릿)에 넣는다면 다음과 같은 형태가 됩니다.

## Agent work log
- Trigger:
- Allowed scope:
...

사람이 작성하는 PR에서도 사용할 수 있지만, agent PR에서는 거의 필수적이라고 생각합니다.

개인적으로 처음 4가지는 이 정도 수준입니다.

read-only (읽기 전용)로 시작할 수 있습니다.

실패한 job (작업), 의심스러운 file (파일), 재현 command (커맨드), 관련 PR의 차이점만 정리해도 가치가 있습니다. 수정까지 맡기는 것은 그 이후에 해도 됩니다.

API 명이나 command (커맨드)가 변경되었을 때의 추종입니다.

실패하더라도 rollback (롤백)하기 쉽고, review (리뷰)도 용이합니다. 단, product claim (제품 클레임)을 마음대로 수정하지 않도록, 수정 가능한 section (섹션)을 제한하는 것이 좋습니다.

component (컴포넌트)의 props (프롭스) 변경에 story (스토리)가 따라오지 않는 것과 같은 수정입니다.

frontend (프론트엔드)에서는 꽤 은근하게 효과적입니다. PR diff (PR 차이)와 화면 확인이 연결되므로, agent의 작업을 평가하기 쉽습니다.

label (라벨) 부착, duplicate (중복) 후보 제시, 재현 정보 부족 지적 정도까지입니다.

갑자기 issue (이슈)를 close (종료)하게 하는 것은 너무 과합니다. 처음에는 suggestion (제안) 수준에 머무는 것이 좋습니다.

이 부분은 신중해도 괜찮습니다.

의존성 업데이트는 lockfile (락파일), build output (빌드 결과물), runtime (런타임) 동작에까지 파급됩니다.

특히 frontend (프론트엔드)는 plugin (플러그인), bundler (번들러), CSS, SSR, test runner (테스트 러너)의 궁합 문제로 망가질 수 있습니다. agent가 PR을 생성하는 것은 괜찮더라도, 자동 merge (머지)는 별개의 문제입니다.

release note (릴리스 노트)의 초안 정도라면 괜찮습니다.

하지만 tag (태그) 생성, publish (배포), deploy trigger (배포 트리거)는 초기 대상으로 삼지 않는 것이 좋습니다. 실패했을 때 되돌리는 방법이 repo (레포지토리) 내의 diff (차이)만으로는 해결되지 않기 때문입니다.

이곳은 agent의 똑똑함보다, review (리뷰)의 책임이 더 무겁습니다.

"작은 수정처럼 보이는" 것일수록 위험합니다. guard (가드) 조건을 한 줄 바꾸는 것만으로 동작이 변합니다.

이는 단순히 리뷰하기가 매우 힘듭니다.

agent는 방대한 양의 CSS를 건드릴 수 있습니다. 동작할 수도 있겠죠. 하지만 의도한 UI인지, 기존의 design system (디자인 시스템)에 맞는지, mobile (모바일)에서 깨지지 않는지를 확인하는 것은 사람의 몫입니다.

처음에는 Storybook example (스토리북 예시)의 작은 수정 정도로 제한하는 것이 현실적입니다.

구두 약속으로는 잊어버리기 마련입니다.

agent용 workflow (워크플로우)에는 최소한 다음을 포함하고 싶습니다.

permissions:
  contents: read
  pull-requests: write
...

실제 YAML 코드가 이대로 작동한다는 뜻은 아닙니다. 중요한 것은 이러한 contract (계약)를 workflow (워크플로우) 근처에 두는 것입니다.

agent에게 "적당히 잘 고쳐줘"라고 말하는 것이 아니라, "이 범위 내에서는 고쳐도 좋다. 이 범위를 넘어서면 멈춰라"라고 명시하는 것입니다.

모든 것을 PR로 만들면 review queue (리뷰 큐)가 혼란스러워집니다.

예를 들어, 다음과 같이 나눕니다.

Create PR when:
- changed paths are inside allowed scope
- no dependency update is required
...

이러한 경계선이 없으면, agent는 "무언가 할 수 있을 것 같다"고 느낄 때마다 PR을 만들려 할 것입니다.

하지만 우리가 정말로 원하는 것은 PR의 수를 늘리는 것이 아닙니다. 사람이 안심하고 검토할 수 있는 작업 단위로 만드는 것입니다.

Actions에 들어온 agent는 더 이상 editor extension (에디터 확장 프로그램)이 아닙니다. repo automation (레포지토리 자동화)입니다.

따라서 가장 먼저 살펴봐야 할 것은 model (모델)의 성능 지표가 아니라, workflow (워크플로우)의 경계선입니다.

읽을 수 있는 로그. 접근 가능한 path (경로). 중단 조건. PR (Pull Request)에 작성해야 할 확인 범위. comment (코멘트)로 중단할 판단 기준.

이러한 부분들을 먼저 결정해 두면 agent (에이전트)를 상당히 사용하기 쉬워집니다. 반대로 이 부분을 결정하지 않은 채 자동화를 진행하면, 편리해 보이는 PR은 늘어나지만 review (리뷰) 부채도 함께 늘어납니다.

첫걸음으로는 read-only (읽기 전용) 방식의 CI failure analysis (CI 실패 분석)만으로도 충분합니다. 거기서부터 docs (문서), Storybook, 좁은 범위의 test (테스트) 수정으로 확장해 나갑니다. release (릴리스)나 dependency update (의존성 업데이트)는 운영 방식이 보인 다음에 해도 늦지 않습니다.

agent (에이전트)를 repo (레포지토리)에 도입한다면, 가장 먼저 만들어야 할 것은 prompt (프롬프트) 모음이 아니라, 읽을 수 있는 로그와 되돌릴 수 있는 PR (Pull Request)이라고 생각합니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0