시맨틱 버전 관리를 자동화한다는 것은 결국 "다음 배포를 얼마나 올릴지"를 commit 메시지에 맡기는 일이다. Conventional Commits의 대응 관계에 따르면 feat은 minor, fix는 patch, BREAKING CHANGE:가 붙은 commit은 major를 배포한다. semantic-release의 commit analyzer가 읽는 것도 메시지 자체이며, 그 commit이 어떤 파일을 바꿨는지는 보지 않는다.

이 방식은 commit을 쓰는 사람이 각 유형이 버전에 어떤 결과를 낳는지 이해한다는 전제 위에 서 있다. commit을 coding agent가 쓰는 일이 늘수록 이 전제는 흔들린다. 에이전트는 이번에 "무언가를 추가했다"는 이유만으로 feat이라고 쓸 수 있다. monorepo에서 문서 사이트의 오류를 고치고 fix(site)라고 쓰면 analyzer는 이것도 패키지의 patch로 센다. 리팩터링에 BREAKING CHANGE: 푸터를 붙이면 다음 병합 때 곧바로 major가 나간다. 어떤 규칙도 어기지 않았는데, 배포되는 버전은 이미 메인테이너가 의도한 버전이 아니다.

또 하나의 전제는 도구 쪽에 있다. 흔한 구성은 semantic-release가 배포를, commitlint가 commit 검사를 맡고, release notes를 위한 changelog preset을 더하는 방식이다. 세 도구는 설정 형식이 제각각이라 같은 유형 규칙을 release.config.js, commitlint.config.js, preset에 따로 적어야 한다. 규칙을 바꾸면 검사, 버전 분석, release notes 세 곳에서 똑같이 작동하는지 함께 확인해야 한다. 에이전트 입장에서도 규칙이 설정 파일과 플러그인에 흩어져 있으면 "이 유형은 무엇을 배포하는가"를 한곳에서 읽기 어렵다.

aronrepo는 이 문제를 위해 내가 만든 도구다. 에이전트와 메인테이너가 같은 규칙으로 일하고, 잘못 배포될 commit은 에이전트의 판단이 아니라 규칙이 막는다.

하나의 패키지, 고정된 하나의 규칙

aronrepo는 commit 검사, 버전 계획, release notes, npm 배포, GitHub Release를 하나의 패키지에 담았다. semantic-release, commitlint, conventional-changelog를 따로 설치할 필요가 없다.

자신의 프로젝트에 도입하려면 aronrepo GitHub 저장소의 README에서 “AI Coding Integration”에 있는 설치 프롬프트를 복사해 coding agent에 붙여 넣으면 된다. 에이전트가 프로젝트 환경에 맞춰 설정을 진행한다.

이 설계에는 몇 가지 트레이드오프가 있다.

유형은 고정, 의미는 하나씩

저장소는 commit 유형을 추가하거나 이름을 바꿀 수 없다. Feat는 새로운 기능, Improve는 기존 기능의 개선, Fix는 배포된 동작의 버그 수정, Upgrade는 런타임 의존성 변경, Chore는 유지보수 작업이다. Docs, Test, Build, CI 등은 배포하지 않는다. 목록에 없는 유형이거나 요약이 마침표로 끝나는 commit은 aronrepo check가 거부하고 올바른 헤더를 제안한다. 유형과 scope는 대소문자를 구분하지 않는다. fix(core): repair cache와 Fix(Core): Repair cache는 같은 commit이고, release notes는 요약의 첫 글자를 대문자로 바꾼다. Conventional Commits에서 옮겨 오는 저장소도 대부분의 commit을 기존처럼 쓸 수 있다.

유형을 고정하면 프로젝트별 맞춤 설정은 포기하게 된다. 나는 그 대가를 받아들인다. 유형을 바꿀 수 있으면 에이전트는 먼저 저장소마다 다른 방언을 익혀야 한다. 고정되어 있으면 이번 변경이 어떤 종류인지만 판단하면 되고, 배포 수준은 규칙이 정한다.

minor와 major는 소유자가 정한다

기본값인 explicit 모드에서는 Bump(Minor)와 Bump(Major)를 제외한 모든 유형이 최대 patch만 배포하고, BREAKING CHANGE: 푸터는 거부된다. 즉 에이전트가 Feat라고 써도 patch까지만 나가며, minor나 major에는 명시적인 Bump commit이 필요하다. Conventional Commits 동작이 필요한 저장소는 auto 모드로 바꿀 수 있고, 이때 Feat는 minor를, 호환성을 깨는 푸터는 major를 배포한다.

두 모드의 차이는 버전 번호가 사용자에게 무엇을 뜻하느냐에 있다.

똑같은 나무 3눈금 카운터 두 대가 나란히 있다. 왼쪽은 큰 두 눈금이 황동 막대와 자물쇠로 고정되어 있고 열쇠는 책상 위에 있으며, 종이 카드는 가장 작은 눈금만 움직일 수 있다. 오른쪽은 카드가 톱니바퀴로 세 눈금 모두에 연결되어 있다.
왼쪽은 explicit: 카드는 patch만 움직이고, minor와 major는 소유자가 잠금을 풀 때까지 기다린다. 오른쪽은 auto: commit 유형이 톱니바퀴를 거쳐 어느 자리가 올라갈지를 바로 정한다.

explicit은 minor와 major를 대외적인 릴리스로 다루는 프로젝트에 맞는다. 공개 마이그레이션 가이드가 있는 프레임워크, 디자인 시스템, UI 컴포넌트 라이브러리가 그렇다. 이런 프로젝트의 major에는 대개 마이그레이션 문서, 공지, 호환 기간이 따르고, minor도 릴리스 노트나 문서 개편과 맞물릴 수 있다. 그 시점은 소유자가 정한다. 매일 병합되는 기능과 수정은 patch로 계속 내보내고, 밖에 설명할 만큼 쌓이면 Bump(Minor) 하나를 push한다. Bump는 배포 경로 검사의 대상이 아니므로 빈 commit이어도 된다. 예를 들면 git commit --allow-empty -m "Bump(Minor): Release the new theme API"다. 대가는 새 기능이 먼저 patch로 나온다는 점이다. ~ 범위로 patch만 받도록 고정한 사용자도 새 API를 받게 되는데, 엄격한 시맨틱 버전 정의로는 이것이 minor에 해당한다.

auto는 버전 번호를 주로 사람이 아니라 도구와 의존성 범위가 읽는 프로젝트에 맞는다. 팀 안에서 공유하는 패키지, 자사 애플리케이션이 쓰는 SDK, 기능이 단순한 CLI나 utility가 그렇다. 사용자는 ^ 범위로 자동 업그레이드하고, "새 API가 있는지, 호환성이 깨졌는지"를 버전이 정확히 반영하기를 원한다. 반면 minor마다 누군가 시점을 정할 필요는 없다. 이 경우 commit 유형과 BREAKING CHANGE: 푸터가 그대로 버전 번호가 되므로, PR 리뷰에서 commit 헤더와 푸터까지 살펴야 한다. CI의 aronrepo check --title은 형식 오류는 막지만, 변경이 정말 호환성을 깨는지는 판단하지 못한다.

모드를 고르는 일 자체도 소유자의 결정이다. aronrepo가 에이전트에게 주는 규칙에는 이렇게 적혀 있다. 도입할 때는 어떤 모드를 쓸지 소유자에게 물어야 한다. 이미 도입한 저장소에서는 사용자가 그 대화에서 요청하지 않는 한, 에이전트가 Bump(Major), Bump(Minor)나 호환성 파괴 표시를 써서는 안 된다.

배포 파일을 건드리지 않은 commit은 배포하지 않는다

aronrepo는 배포 경로로 commit이 배포되는 내용을 건드렸는지 판단한다. 기본값은 공개 workspace 패키지의 디렉터리이며, 테스트, fixture, benchmark, 예제, changelog 등은 제외된다. 배포 유형의 commit이 어떤 배포 경로도 바꾸지 않았다면 aronrepo check가 병합 전에 거부하고, 배포도 일어나지 않는다. 앞에서 말한 Fix(Site)는 배포하지 않는 유형으로 고쳐 쓰라는 요구를 받는다.

소포, 브라우저 창, 시험관 아이콘이 그려진 흰 카드 줄이 철망을 단 나무틀을 지난다. 소포 카드는 나무 상자로 들어가고, 브라우저와 시험관 카드는 금속 레일을 따라 옆의 흰 종이 상자에 쌓인다.
배포로 이어지는 것은 공개 패키지의 내용을 바꾼 commit뿐이다. 사이트와 테스트 변경도 그대로 병합되지만 버전을 올리지는 않는다.

모든 판단에 이유가 있다

aronrepo explain은 다음 버전과 각 commit이 배포되거나 배포되지 않는 이유를 보여 준다. aronrepo release도 배포할 때 같은 판단을 기록하고, --dry-run은 계획과 release notes만 출력한다. 에이전트는 배포 브랜치에 push하기 전에 explain을 실행할 수 있고, PR을 리뷰하는 메인테이너도 같은 결론을 본다. explain --json은 배포될 commit(head)과 release notes 전체도 출력하므로, CI가 이를 job 요약에 올리면 승인하는 내용과 실제로 배포되는 내용이 같아진다.

중단된 배포를 이어서 마칠 수 있다

monorepo 배포는 중간에 실패하기 쉽다. 일부 패키지는 이미 npm에 올라갔는데 tag는 아직 push되지 않은 상태다. aronrepo release는 먼저 모든 패키지를 스테이징용 dist-tag로 배포하고, 레지스트리가 모두 제공하는 것을 확인한 뒤에야 정식 dist-tag를 옮기며, 이어서 tag를 push하고 GitHub Release를 만든다. 같은 job을 다시 실행하면 같은 commit에서 이미 배포된 버전은 건너뛰고, 빠진 tag나 release는 채운다. 버전은 vX.Y.Z tag에서만 읽으며, package.json에 다시 써서 commit하지 않는다.

언제 배포할지는 메인테이너가 정할 수 있다

push하면 배포하는 방식은 CI의 기본 구성일 뿐이다. 출시 주기가 정해진 프로젝트는 PR을 계속 main에 병합하고 스테이징 배포도 평소처럼 하면서, 정식 배포만은 메인테이너가 시점을 정하고 싶어 하는 경우가 많다. 여기에는 release 브랜치도 Release PR도 필요 없다. aronrepo의 버전은 직전 tag부터 배포할 commit까지로 계산하므로, 월요일부터 목요일까지 병합한 Fix 네 개를 금요일에 배포해도 patch 한 번이 되고, release notes에는 네 건이 함께 실린다.

바꿀 것은 트리거다. main에 push할 때는 explain --json만 실행해 버전, commit, release notes를 job 요약에 남긴다. 정식 배포는 수동으로 실행하는 workflow로 바꿔 미리 보기의 commit과 버전을 입력받고, required reviewers를 설정한 GitHub Environment에서 실행한다. 승인 기록은 GitHub의 배포 이력에 남는다. 배포 단계에서는 다음을 실행한다.

aronrepo release --branch main --expect 1.2.4

release는 먼저 체크아웃한 commit이 실제로 origin/main에 있는지 확인해, feature 브랜치의 commit이 main으로 배포되는 일을 막는다. --expect는 배포 시점에 계획을 다시 계산하고, 승인할 때 본 버전과 다르면 아무것도 배포하지 않고 멈춘다. 다음 배포는 이 tag부터 다시 계산하므로, 승인 뒤에 병합된 commit은 다음 버전으로 넘어간다. 전체 workflow 예시는 aronrepo README에 있다.

에이전트에게 주는 것은 문서가 아니라 데이터

규칙을 README에만 적어 두면 에이전트는 여전히 그것을 읽고 기억해야 한다. aronrepo는 하나의 정책을 세 가지 출구로 내보낸다.

  • aronrepo policy --json은 저장소의 모드, 배포 경로, 각 유형의 배포 수준과 설명을 출력한다.
  • aronrepo agents --write는 정책 블록을 AGENTS.md에 쓰며, 명령은 저장소의 패키지 매니저에 맞게 생성된다. 블록이 오래되면 aronrepo agents와 aronrepo doctor가 실패하므로, 유형 표를 손으로 옮겨 적을 일이 없다.
  • aronrepo check는 commit-msg hook, PR의 각 commit, PR 제목에 같은 검사를 실행한다. 헤더가 맞지 않으면 제안하는 형식을 출력한다.

README에는 coding agent에 그대로 붙여 넣을 수 있는 도입용 프롬프트도 있다. 저장소를 살펴보고, 어떤 모드를 쓸지 소유자에게 묻고, semantic-release와 commitlint를 제거하고, hook과 CI를 추가한 뒤, 마지막으로 doctor, explain, release --dry-run을 실행해 다음 버전을 보고하는 흐름이다. 도입 작업 자체에는 Build, CI, Chore(Agent)처럼 배포하지 않는 유형을 쓴다.

semantic-release, release-please, changesets와 비교

JavaScript 프로젝트에서 흔히 쓰는 배포 도구에는 다른 방식이 두 가지 더 있다. release-please도 Conventional Commits를 읽지만 바로 배포하지 않는다. 대신 Release PR을 관리하다가 그 PR을 병합할 때 tag와 GitHub Release를 만든다. changesets는 commit 메시지를 아예 보지 않는다. 개발자가 변경마다 changeset 파일을 붙여 patch, minor, major 중 무엇을 배포할지 적는다.

항목aronreposemantic-releaserelease-pleasechangesets
버전 판단 근거고정된 commit 유형commit 메시지(기본은 Angular 규약, preset 교체 가능)Conventional Commits 메시지따로 작성하는 changeset 파일
minor, major를 정하는 주체explicit: 소유자가 Bump를 씀, auto: commit 유형commit 유형과 BREAKING CHANGEcommit 유형과 !, Release-As로 버전 지정 가능각 changeset에 선언한 수준
배포 시점기본은 배포 브랜치에 push하면 배포, 수동 트리거로 메인테이너가 승인한 commit을 배포할 수도 있음배포 브랜치에 push하면 배포Release PR을 병합할 때changeset version과 publish 실행 시, 보통 Version Packages PR을 거침
버전 번호 저장 위치git tag에만, package.json에 다시 쓰지 않음git tag, 다시 쓰려면 @semantic-release/git을 추가로 설치해야 하며 공식적으로 권장하지 않음Release PR이 package.json과 manifest에 기록changeset version이 package.json에 기록
Release notesGitHub Release 본문GitHub Release 본문, CHANGELOG.md는 플러그인 추가 설치 필요CHANGELOG.md와 GitHub Release패키지별 CHANGELOG.md
commit 검사내장 check: hook, PR의 각 commit과 PR 제목없음, commitlint 별도 설치없음commit을 보지 않음, changeset status로 changeset 누락 검사 가능
배포 파일을 건드리지 않은 배포 유형 commit병합 전에 거부, 배포하지 않음메시지대로 배포단일 패키지는 그대로 배포, monorepo는 변경 경로로 패키지를 판별해당 없음, 배포 여부는 changeset이 정함
monorepo지원, 모든 패키지가 하나의 버전을 공유코어는 한 번에 패키지 하나만 배포, monorepo는 커뮤니티 플러그인 필요manifest 설정, 패키지별 독립 버전, 연동 가능주요 설계 대상, 패키지별 독립 버전, fixed, linked로 묶기 가능
npm 배포내장, 스테이징용 dist-tag로 먼저 배포하고 모두 갖춰지면 전환내장(@semantic-release/npm)맡지 않음, 워크플로에 배포 단계를 따로 작성내장 changeset publish, npm에 아직 없는 버전만 배포
프리릴리스alpha, beta, rc, canary 브랜치프리릴리스 브랜치와 channelprerelease 설정pre enter, pre exit 모드와 snapshot
중단 후 재실행빠진 배포, tag, Release를 채움tag를 배포 전에 push하므로 배포 실패 시 수동 복구배포를 맡지 않음publish를 다시 실행하면 이미 배포된 버전은 건너뜀
배포 전 미리 보기explain(--json은 commit과 release notes 포함), release --dry-run--dry-runRelease PR 자체changeset status
에이전트용 규칙policy --json, AGENTS.md 블록 생성없음없음없음
적용 범위JavaScript, npm 배포만다국어, 플러그인에 의존다국어, 언어별 strategy 제공JavaScript 패키지 매니저의 workspace

에이전트가 commit을 쓰는 상황에 놓고 보면, 네 도구의 차이는 "누가 언제 배포 수준을 정하는가"에 있다. semantic-release는 commit 메시지를 쓰는 순간 정해지고 병합하면 바로 배포된다. release-please도 메시지가 정하지만, Release PR 덕분에 배포 전에 버전 번호와 changelog를 한 번 더 볼 수 있다. changesets는 수준을 changeset 파일에 적으므로, 에이전트가 changeset을 쓴다면 수준도 에이전트가 고르고 PR 리뷰가 이를 걸러야 한다. aronrepo는 explicit 모드에서 minor와 major를 에이전트의 손에서 빼내고, 배포하지 말아야 할 commit은 병합 전에 거부한다.

패키지별 독립 버전이 필요하다면 changesets가 더 알맞다. 여러 언어를 지원해야 하거나 GitHub 화면에서 PR을 병합하는 방식으로 배포를 승인하고 싶다면 release-please가 낫다. npm 이외의 배포 대상이나 특정 플러그인이 필요하다면 semantic-release의 생태계가 가장 풍부하다.

설치 규모

기능을 하나의 패키지에 모으면 의존성도 함께 줄어든다. 아래 숫자는 각 구성을 새 디렉터리에서 npm install --ignore-scripts로 설치한 결과다. 패키지 수는 npm이 보고한 added 수, 크기는 node_modules의 du 값이다. semantic-release 단독 설치에는 commit 검사가 없으므로, aronrepo와 범위가 맞는 것은 "semantic-release와 commitlint" 조합이다. release-please와 changesets는 commit을 검사하지 않으므로 각자의 CLI만 측정했다.

항목aronreposemantic-releaserelease-pleasechangesets
측정 패키지aronrepo(측정일 최신 버전)semantic-release 25.0.9release-please 17.11.2@changesets/cli 3.0.3
Node.js 요구 사항22.18 이상^22.14 또는 24.10 이상22 이상^22.11, ^24 또는 26 이상
직접 의존성4283121
설치 후 전체 패키지 수7301(commitlint 포함 시 345)16240
node_modules 크기2.7 MB79 MB(commitlint 포함 시 105 MB)93 MB3.7 MB
주 패키지 압축 해제 크기366 kB128 kB929 kB89 kB

설치된 패키지 수

npm install --ignore-scripts · added · 2026-11-07

aronrepo는 패키지 7개, changesets는 40개, release-please는 162개를 설치한다. aronrepo와 범위가 비슷한 semantic-release와 commitlint 조합은 345개를 설치한다.

설치된 패키지 수
  • aronrepo7
  • changesets 3 (@changesets/cli)40
  • release-please 17162
  • semantic-release 25 (commit 검사 없음)301
  • semantic-release 25 + commitlint345
패키지 수 데이터 표 보기
설치된 패키지 수 · 설치된 패키지 수
구성설치된 패키지 수
aronrepo7
changesets 3 (@changesets/cli)40
release-please 17162
semantic-release 25 (commit 검사 없음)301
semantic-release 25 + commitlint345

2026년 11월 7일 새 디렉터리에서 npm install --ignore-scripts를 실행하고 npm이 보고한 added 수를 기록했다. commitlint 조합에는 @commitlint/cli와 @commitlint/config-conventional이 포함된다.

측정 방법

node_modules 크기

npm install --ignore-scripts · du node_modules · 2026-11-07

aronrepo의 node_modules는 약 2.7MB, changesets는 약 3.7MB다. release-please는 약 93MB, semantic-release와 commitlint 조합은 약 105MB다.

MB (du로 측정)
  • aronrepo2.7
  • changesets 3 (@changesets/cli)3.7
  • release-please 1793
  • semantic-release 25 (commit 검사 없음)79
  • semantic-release 25 + commitlint105
설치 크기 데이터 표 보기
node_modules 크기 · MB (du로 측정)
구성MB (du로 측정)
aronrepo2.7
changesets 3 (@changesets/cli)3.7
release-please 1793
semantic-release 25 (commit 검사 없음)79
semantic-release 25 + commitlint105

위 차트와 같은 설치에서 node_modules를 du로 측정했다. 파일 시스템의 블록 크기에 따라 값이 조금 달라질 수 있다.

측정 방법

범위가 비슷한 semantic-release와 commitlint 조합과 비교하면, 패키지 수는 345개에서 7개로, 크기는 약 105MB에서 약 2.7MB로 줄었다. 사실 aronrepo 주 패키지 자체는 semantic-release보다 크다(압축 해제 후 약 366kB 대 128kB). commit 검사와 CLI를 함께 담았기 때문이다. 차이는 거의 전부 의존성 트리에서 나온다. aronrepo의 직접 의존성은 semver, js-yaml, picomatch, tinyglobby 네 개뿐이다.

changesets도 가볍다. commit을 분석하지 않고 GitHub Release도 만들지 않으며, 그 부분은 별도의 GitHub Action에 맡기기 때문이다. release-please의 CLI 설치 규모는 semantic-release에 가깝지만, 대부분의 프로젝트는 공식 GitHub Action으로 실행하므로 프로젝트의 의존성에 들어가지 않는다.

맞는 조건과 대가

aronrepo의 범위는 의도적으로 좁다. ESM만 지원하고 Node.js 22.18 이상이 필요하다. 한 저장소에서 배포하는 패키지는 모두 하나의 버전을 공유한다. 패키징에는 저장소의 패키지 매니저를 쓰고, 배포는 항상 npm을 거친다. commit 유형을 직접 정의하거나, 패키지마다 버전을 따로 올리거나, npm이 아닌 레지스트리 흐름을 쓰는 일은 설계 범위 밖이다.

이미 자체적인 안전한 배포 파이프라인이 있는 프로젝트도 전부 바꿀 필요는 없다. CLI 뒤의 함수는 aronrepo/node에서, commit 규약과 버전, release notes 보조 함수는 aronrepo에서 export된다. 버전, tag, notes 결정만 aronrepo에 맡기고, 패키징과 검증, 업로드는 기존 스크립트에 남겨 둘 수 있다.

내가 aronrepo에서 겨냥한 것은 하나다. 버전 판단을 "commit을 쓴 사람이 제대로 판단했는가"에서 "규칙이 병합 전에 막을 수 있는가"로 옮기는 것. 에이전트는 앞으로도 유형을 잘못 고를 것이다. 달라지는 점은, 잘못 골랐을 때 check가 거부하고 대신 쓸 형식을 알려 주며, minor와 major는 언제나 소유자가 명시적으로 적어야 한다는 것이다.