AI 주도 개발에서 PR이 홍수처럼 쏟아지기 전에, Labeler로 시각화해 두기

• AI가 작성한 PR
• 제목만으로는 내용을 상상할 수 없는 PR
• 규모(차이의 크기)를 확인하기 전까지는 알 수 없는 PR
• etc..

AI 주도 개발이 확산되면서, Claude Code나 GitHub Copilot과 같은 에이전트가 PR을 제출하는 것은 일상이 되었습니다. GitHub Copilot의 경우, Issue의 Assign에 Copilot을 지정하는 것만으로 클라우드 상에서 Issue를 처리하고 PR까지 생성해 줍니다. 여러 Issue를 병렬로 처리할 수 있게 된 반면, 생성된 PR을 사람이 체크하는 작업의 비중은 늘어나고 있습니다.

여기서 곤란한 점은 PR 목록을 봐도 내용의 경향을 파악할 수 없다는 것입니다. 제목만으로는 기능 추가, 버그 수정, 의존성 업데이트 중 무엇인지 판별할 수 없어, 결국 하나씩 열어서 차이(diff)를 확인하게 되기 쉽습니다. PR의 수가 늘어날수록 이러한 리뷰 부하가 서서히 영향을 미치게 됩니다.

이때 도움이 되는 것이 라벨(Label)입니다. 변경 종류(기능 추가, 버그 수정, 의존성 업데이트 등)나 건드리는 레이어(프론트엔드, 백엔드 등), 변경 규모를 라벨로 자동 부착해 두면, PR 목록 단계에서 내용을 짐작할 수 있습니다. 예를 들어 모델 변경이 포함된 PR이라면, label:model과 같이 필터링할 수 있습니다. 또한, 나중에 "어떤 종류의 PR이 많았는가"를 되돌아볼 수도 있습니다.

참고로, 여기서 소개하는 라벨링은 AI가 생성한 PR에만 국한된 이야기가 아닙니다. 사람이 제출한 PR에도 동일한 규칙으로 붙기 때문에, 팀 전체의 PR 경향을 시각화하는 메커니즘으로 사용할 수 있습니다.

Labeler(actions/labeler)는 PR에 대해 라벨을 자동으로 달아주는 GitHub 공식 Action입니다. 설정한 규칙과 일치하는 라벨이 자동으로 붙습니다.

구조는 간단하여, 규칙을 .github/labeler.yml에 쓰고, 그것을 호출하는 워크플로(Workflow)를 .github/workflows/에 두기만 하면 됩니다. 규칙은 "라벨 이름"과 "그 라벨을 붙이는 조건"의 조합으로 작성합니다.

# docs/ 하위이거나 Markdown을 변경한 PR에 docs 라벨을 붙임
docs:
- changed-files:
...

changed-files는 변경된 파일의 경로를 보는 조건이며, any-glob-to-any-file에 작성한 glob 중 어느 하나라도 일치하는 파일이 포함되어 있으면 해당 라벨(여기서는 docs)이 붙습니다. 라벨을 늘리고 싶을 때는 이 블록을 라벨의 수만큼 나열해 나가면 됩니다.

Labeler에서 정규 표현식을 사용할 수 있는 소재는 다음 두 가지입니다.

• 변경된 파일의 경로 (changed-files)
• 브랜치 이름 (head-branch / base-branch)

즉, "어떤 파일을 변경한 PR인가", "어떤 이름의 브랜치에서 나온 PR인가"를 기준으로 규칙을 설정하여 라벨을 붙입니다. 경로는 **/*.ts나 models.ts, src/api/**와 같은 glob으로, 브랜치 이름은 ^fix/와 같은 정규 표현식으로 작성할 수 있습니다.

"내용을 보고 판단하는" 것이 아니라, 어디까지나 경로와 브랜치 이름이라는 규칙 기반의 정적인 판정입니다. 역으로 말하면, 여기에 해당하지 않는 것(PR의 제목이나 본문, 차이의 행 수, 작성자)은 Labeler만으로는 다룰 수 없습니다. 이 부분은 기사 후반부에서 보조 워크플로나 전용 Action을 조합하여 보완해 나가겠습니다.

PR의 내용을 읽고 라벨을 붙이고 싶다면, LLM에 PR의 차이(diff)를 전달하여 동적으로 태그를 다는 방법도 생각할 수 있습니다. 유연하지만 API 키가 필요하며, PR이 나올 때마다 사용한 만큼의 비용이 발생합니다.

반면 Labeler는 경로와 브랜치 이름 규칙에 일치시키기만 하는 정적인 메커니즘이므로, 추가적인 API 이용료가 들지 않습니다. 판정이 단순한 만큼 동작도 예측하기 쉽고, PR마다 결과가 흔들리는 일도 없습니다. 우선은 무료로 안정적으로 돌아가는 Labeler를 토대로 삼고, 부족한 부분만 나중에 추가해 나가는 것을 추천합니다.

라벨은 너무 많이 늘리면 목록이 어지러워지므로, 처음에는 "종류", "영역", "규모"의 세 방향으로 좁히는 것이 밸런스가 좋습니다. 여기서는 웹 개발 프로젝트를 상정한 샘플을 제시합니다. 실제 라벨은 사용 중인 프로젝트의 디렉토리 구성에 맞춰 정규 표현식(glob)을 조정해 주세요.

라벨	부착 조건 이미지	알 수 있는 내용
docs	docs/**, **/*.md를 변경	문서 관련 PR
deps	package.json, pnpm-lock.yaml 등을 변경	의존성 패키지 업데이트
frontend	src/frontend/**, **/*.tsx를 변경	프론트엔드 측 변경
backend	src/api/**, src/server/**를 변경	백엔드 측 변경
model	**/models/**, models.ts를 변경	데이터 모델·스키마 변경
test	**/*.test.ts, tests/**를 변경	테스트 추가·수정
ci/cd	.github/workflows/**를 변경	파이프라인 변경
ai-prompt	.claude/** 등 프롬프트 정의를 변경	AI 프롬프트 관련 변경
size:*	차이(diff)의 행 수(후술할 보조 기능으로 산출)	PR의 규모

docs나 deps, ci/cd 같은 항목은 변경 파일의 경로가 거의 그대로 라벨에 대응하므로, Labeler와 궁합이 좋은 부류입니다. 반면 size:*는 경로만으로는 결정할 수 없기 때문에, 후반부 응용 단계에서 다른 메커니즘을 사용합니다.

여기서부터는 심플한 Todo 앱(Node.js + Express) 리포지토리를 소재로, 실제로 구동한 설정을 올려보겠습니다. 우선 경로 기반의 라벨링부터 시작하여, 그 다음에 브랜치명·제목·규모를 활용한 응용을 추가해 나가는 흐름입니다.

Labeler를 구동하려면 규칙을 작성하는 .github/labeler.yml과 이를 호출하는 워크플로(Workflow) 두 가지를 준비해야 합니다.

먼저 호출 측 워크플로입니다. PR을 트리거로 하여 actions/labeler를 실행하기만 하면 됩니다.

name: Labeler
on:
- pull_request_target
...

pull_request_target으로 구동하는 이유는 포크(Fork)로부터 온 PR에서도 쓰기(라벨 부착)가 가능하도록 하기 위해서입니다. 라벨을 붙이려면 pull-requests: write 권한이 필요합니다.

다음은 규칙을 정의하는 labeler.yml입니다. Todo 앱의 구성에 맞춰 변경 파일의 경로로부터 라벨을 결정하도록 설정했습니다.

ci/cd:
- changed-files:
- any-glob-to-any-file:
...

any-glob-to-any-file에 나열된 glob 중 어느 하나라도 일치하는 파일이 변경 사항에 포함되어 있다면 해당 라벨이 붙습니다. 예를 들어 src/models/todo.js를 건드린 PR에는 model이, docs/ 하위 디렉토리나 임의의 Markdown 파일을 건드린 PR에는 docs가 붙습니다. 참고로, 붙이려는 라벨이 GitHub 상에 아직 존재하지 않는 경우 Labeler가 자동으로 생성해 줍니다.

브랜치명 규약이 정해져 있다면, 종류별 라벨도 Labeler 단독으로 붙일 수 있습니다. github-script를 작성할 필요는 없습니다. head-branch에 브랜치명의 정규 표현식을 나열하면, 그중 하나와 일치할 때 라벨이 붙습니다.

fix:
- head-branch:
- '^fix/'
...

배열은 OR 조건이므로, fix/login-bug든 hotfix/login-bug든 fix 라벨이 붙습니다.

경로 조건(changed-files)과 조합하고 싶을 때는 all:로 묶으면 AND 조건이 됩니다. 다음 예시는 "브랜치명이 feature/로 시작하면서, 동시에 src/ 하위 디렉토리를 변경했을 때"만 라벨이 붙습니다.

feature-src:
- all:
- head-branch:
...

다만 주의할 점이 있습니다. AI 에이전트가 생성하는 브랜치명은 반드시 fix/나 feature/ 같은 규약을 따르지 않을 수도 있습니다. Claude Code처럼 claude/...

와 같이 독자적인 prefix를 붙이기도 합니다. 이 경우에는 브랜치명만으로는 종류를 판별할 수 없으므로, 다음 단계인 PR 타이틀을 통한 판별로 폴백(fallback)합니다.

Labeler는 타이틀이나 본문을 볼 수 없기 때문에, 타이틀로부터 종류를 판별하고 싶을 때는 별도의 워크플로우를 준비해야 합니다. 여기서는 actions/github-script를 사용하여, Conventional Commits 형식의 타이틀(feat:, fix: 등)을 정규 표현식(Regular Expression)으로 매칭하여 type:* 라벨을 붙입니다.

name: PR Title Labeler
on:
  pull_request_target:
...

types에 edited를 포함했기 때문에, 나중에 타이틀을 수정했을 때도 라벨이 다시 붙습니다. 타이틀이 규약에 맞지 않으면 아무 작업도 하지 않고 종료합니다.

변경 규모(차이점의 행 수) 또한 Labeler로는 판별할 수 없습니다. 전용 Action(pascalgn/size-label-action 또는 CodelyTV/pr-size-labeler)을 사용하는 방법도 있습니다. 여기서는 actions/github-script로 additions + deletions를 집계하여 size:*를 붙이는 자체 구현 방식을 소개합니다.

name: PR Size Labeler
on:
  pull_request_target:
...

임계값은 다음과 같이 설정했습니다. 프로젝트의 입도(granularity)에 맞춰 조정해 주세요.

라벨	변경 행 수 (additions + deletions)
size:XS	~10
size:S	~50
size:M	~200
size:L	~500
size:XL	501~

두 가지 포인트가 있습니다. 첫 번째는 재실행 시 오래된 size:* 라벨이 남지 않도록, 이번에 붙이는 것 이외의 size 라벨을 삭제한다는 점입니다. 두 번째는 synchronize(추가 push) 시에도 재평가되도록 types에 포함했다는 점입니다. 이를 통해 PR에 내용을 추가하여 차이점이 늘어났을 때도 규모 라벨이 다시 교체됩니다.

라벨이 붙기 시작하면, 그다음은 그것을 사용하여 살펴보기만 하면 됩니다.

가장 간편한 방법은 PR 목록의 필터입니다. GitHub 검색창에 label:type:fix label:size:XS와 같이 여러 라벨을 나열하면 AND 조건으로 좁혀볼 수 있습니다. '작은 버그 수정 PR'만 골라내어 한꺼번에 리뷰하는 등의 방식으로 활용할 수 있습니다.

건수를 집계하여 경향을 보고 싶을 때는 gh 명령어가 편리합니다. 특정 라벨이 붙은 머지된(merged) PR의 건수를 셀 수도 있습니다.

최근에 모델(model) 변경이 몇 번 있었는지 시각화할 수 있습니다.

Issue의 사이즈가 적절하게 세분화되었는지 확인하는 것도 가능합니다. size:XL만 계속 나열된다면, 조금 더 작게 분할한 뒤에 AI에게 전달하는 것이 좋겠다는 통찰을 얻을 수 있습니다.

더 나아가고 싶다면, 이 집계를 정기적으로 실행하여 대시보드화하거나, 새로운 PR에 라벨이 붙는 타이밍에 Slack으로 알림을 보내는 등의 발전도 고려할 수 있습니다. 우선은 필터와 gh를 통한 집계부터 시작하고, 필요해지면 자동화해 나가는 것을 추천합니다.

Labeler로 PR을 시각화하는 흐름을 기초부터 응용까지 살펴보았습니다.

• 기초: Labeler로 변경 파일의 경로로부터 라벨을 붙임 (docs, deps, model 등). 무료로 안정적으로 운영 가능
• 응용: 브랜치명으로 종류를 판별. 규약이 있다면 Labeler 단독으로 완결
• 응용: PR 타이틀이나 차이점의 행 수는 github-script나 전용 Action으로 보완 (type:*, size:*)
• 활용: PR 목록 필터나 gh 명령어 집계로 PR의 경향을 되돌아봄

우선 경로 기반의 라벨만이라도 설정하면, PR 목록의 가시성이 훨씬 좋아집니다.

라벨을 설정함으로써, 서두에서 보았던 PR 목록도 이와 같이 대략적으로 파악할 수 있는 형태로 변화했습니다. AI 주도 개발에서 PR의 수가 늘어날수록, 이 시각화의 효과는 더욱 커질 것입니다.