Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
Rule Branch는 GitHub 리포지토리와 개발 규칙을 연결하여, 규칙의 불일치 탐지부터 근거 기반 개정안 작성, 검토/승인 및 AI 배포까지 전 과정을 통합 관리하는 도구입니다. 이를 통해 복잡한 개발 방침 변경 이력을 체계적으로 추적하고 다음 개발 단계에 지시를 전달할 수 있습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기"라이브러리는 업데이트했고, 코드도 수정했다. 하지만 AI가 읽는 개발 규약에는 오래된 방식이 남아있다."
AI 코딩 지원 도구에 규칙을 전달하기 위해 AGENTS.md나 CLAUDE.md 같은 파일을 준비한다. 이 시점에서는 유용할 수 있지만, 의존 관계나 개발 방침이 바뀌면 지시 파일의 재검토가 필요해진다.
규칙을 만드는 것뿐만 아니라, 변화를 감지하고 채택할 내용을 결정하며, 다음 개발 단계까지 전달하는 과정을 관리하고 싶다.
이러한 과제를 위해 개발된 것이 Rule Branch이다. GitHub 리포지토리와 개발 규칙을 연결하여 불일치 탐지, 근거 기반의 개정안 작성, 검토/승인, AI용 지시 파일 배포를 하나의 흐름으로 통합하고 있다. 화면이나 리포지토리에서는 RuleBranch로 표기한다.[1]
본고에서는 사용자가 무엇을 확인하고 어떤 조작을 통해 다음 단계로 진행할 수 있는지 주요 화면과 함께 소개한다.
TL;DR (5줄 요약)
AGENTS.md 등으로 변환하여 Draft PR로 배포한다.Rule Branch에서 다루는 핵심 대상은 개발 규칙과 그 규칙을 변경하는 판단이다.
먼저 GitHub 리포지토리에서 규칙 후보를 추출하고 채택할 내용을 확인한다. 이후에는 승인된 규칙과 의존 관계의 변화를 대조하여 재검토가 필요한 부분을 찾는다.
발견된 불일치로부터 근거 기반의 개정안을 만들 수 있다. 채택한 버전을 AI용 지시 파일로 변환하고 GitHub의 Draft PR로 배포한다. 규칙의 원본과 변경 이력은 Firestore에서 관리한다.[1:1]
開発ルールを見つける、見直す、届けるという三つの段階
찾고, 재검토하고, 전달하는 과정을 연결한다. 마지막으로 획득/읽기/구현 테스트는 개발 환경에서 확인한다.
예를 들어, 여러 리포지토리에서 공통의 개발 방침을 사용하거나 AI용 지시 파일을 지속적으로 유지보수해야 할 때 이 흐름을 사용할 수 있다.
한편, Rule Branch 자체가 앱 기능을 구현하는 것은 아니다. 다음 개발 단계에서 참조되어야 하는 규칙을 근거와 이력과 함께 정리하여 전달하는 역할을 담당한다.
사용의 진입점은 GitHub 로그인이다. 하지만 로그인만 한다고 리포지토리가 자동으로 연동되는 것은 아니다. GitHub App을 연결하고 분석할 리포지토리를 선택해야 한다.[3]
관리 단위는 주로 다음 두 가지이다.
Workspace는 사용자나 멤버, 공통 관리 기능을 모아둔 장소다. 개인 Workspace에서는 오너가 사용하며, 조직 Workspace에서는 멤버와 역할을 관리한다.
Project는 대상이 되는 개발 프로젝트와 그 규칙을 모아둔 장소다. GitHub 리포지토리를 연결하고 Project별로 규칙, 차이 탐지, 반영 상황, 판단 기록을 확인할 수 있다.
Rule BranchのWorkspace概要。Projectやルールの状況、対応が必要な項目を確認する画面
Workspace 개요를 진입점으로 삼고, 다음으로 확인하는 제안이나 미반영된 규칙으로 이동한다.
Project 생성 시 이름과 슬러그를 입력하고, GitHub App 설치와 대상 리포지토리를 선택한다. 필요에 따라 주요 언어, 프레임워크, 주목할 테마, 제안 시 고려해 주었으면 하는 보충 지시도 설정할 수 있다.[3:1]
名前、スラッグ、GitHubリポジトリを指定するProject作成画面
먼저 대상을 선택하고 필요한 경우에만 상세 설정을 입력한다.
초기 분석에서는 README, 기존 AI용 지시 파일, 의존 관계 설정 파일, 소스 코드의 일부 등으로부터 규칙 후보를 추출한다. 파일 수나 읽어들이는 범위에는 상한선이 있으며, 리포지토리 전체를 무제한으로 읽어들이는 것은 아니다.[4]
분석이 끝나면 후보 내용과 근거를 확인한다. '후보가 생겼다'와 '팀 규약으로 채택했다'는 별개의 단계이다.
규칙을 하나의 긴 문서에 담으면, 길게 유지하고 싶은 방침과 라이브러리 버전에 의존하는 절차가 뒤섞이기 쉽다.
Rule Branch에서는 추상도에 따라 3개의 레이어(Layer)로 나누어 관리한다.[5]
*레이어의 사용 구분. 적용 범위와 강제도는 레이어와 별도로 설정한다.
예를 들어, '사용자의 안전을 우선시한다'는 방침은 L1에, '종속 업데이트 시 호환성을 확인한다'는 판단 기준은 L2에, 구체적인 입력 검증 절차는 L3으로 정리할 수 있다.
규칙 목록에서는 레이어, 상태, 적용 레벨 등을 확인할 수 있다. '후보', '유효', '재확인 필요'와 같은 상태를 통해 아직 채택하지 않은 것과 재검토가 필요한 것을 구분할 수 있다.[5:1]
レイヤーや状態を確認できるProjectのルール一覧
규칙을 나열하는 것뿐만 아니라, 후보/유효/재확인 필요로 구분하여 다룬다.
수동으로 만드는 경우에는 먼저 제목, 규칙 키, 레이어, 종류, 적용 레벨 등을 설정하고, 그 후에 초안의 본문을 등록한다. 본문은 Markdown으로 작성하며, 변경 이유나 변경 종류를 첨부할 수 있다.[5:2]
본문을 수정할 때는 과거 버전을 덮어쓰지 않고 새로운 Version으로 제안한다. 새로운 제안이 승인될 때까지는 승인된 현행 버전을 유지한다.[6]
'현재 사용 중인 규칙'과 '다음 채택을 검토하는 규칙'을 병행하여 다룰 수 있다는 것이 이 버전 관리의 장점이다.
적용 대상 리포지토리를 한정하거나, 변경을 감시하는 종속 관계를 기록하는 설정도 있다. 다만, 언어나 디렉터리 등의 적용 조건 메타데이터를 기록할 수 있는 것과 모든 조건에서 자동으로 배포 대상을 좁힐 수 있는 것은 같지 않다. 현재의 배포처 제한에는 대상 리포지토리 지정 기능을 사용한다.[5:3]
Rule Branch에서는 리포지토리 상태와 승인된 규칙의 불일치를 Drift라고 부른다. 화면 상에서는 '불일치 감지'에서 확인할 수 있다.
여기서 중요한 것은, 최초 후보 추출과 지속적인 Drift 감지를 분리하는 것이다. 전자는 기존 리포지토리에서 규칙 후보를 찾는 처리이고, 후자는 주로 package.json의 종속 선언과 승인된 규칙을 비교하는 처리이다. 임의의 소스 변경이나 설계 변경을 포괄적으로 감지하는 기능은 아니다.[1:2]
공개 매뉴얼에서는 React 17 사용으로 정한 규칙과 React 18.3.1의 종속 선언 간의 모순을 수동 스캔으로 감지한 사례를 소개하고 있다. 이는 매뉴얼에 기재된 관측 사례일 뿐, 본고에서 새롭게 실행한 검증은 아니다.[7]
사용자는 지적 사항을 열어 중요도나 설명 외에도 대상 파일, 행, 커밋 등의 근거를 확인한다.
要確認ルールや指摘を確認する、ずれの検知画面
지적 건수만으로 판단하지 않고, '상세/근거 보기'에서 대상을 확인한다.
해당 지적 사항은 '대응 대상에 추가', 이번에는 대응하지 않는 것은 이유를 적어 '보류'를 선택한다. 보류한 후 재검토할 경우에는 다시 열 수도 있다.[7:1]
종속 선언과 규약이 달라도 어느 쪽을 고쳐야 하는지는 프로젝트의 의도에 따른다. 예를 들어, 업데이트 자체가 의도하지 않은 변경이라면, 규약이 아니라 코드 쪽으로 되돌리는 판단도 있을 수 있다.
감지되었다고 즉시 규약을 수정하는 것이 아니라, 먼저 대응 방침을 결정한다. Rule Branch에서는 이 판단과 개정안을 만드는 작업이 분리되어 있다.
대응 중인 지적 사항에서 '제안 생성'을 실행하면 새로운 Rule Version이 만들어진다. Version 상세에서는 현행 버전과의 차이점, 변경 후 본문, 변경 이유, Evidence, 관련 Drift를 확인할 수 있다.[7:2][6:1]
本文の差分、根拠、自動評価、レビュー記録を確認するVersion詳細画面
AI의 설명뿐만 아니라, 변경할 본문과 그 근거를 같은 화면에서 확인한다.
내용이 적절하면 승인하고, 채택하지 않을 경우 이유를 입력하여 거부한다. 거부하더라도 승인된 현행 버전은 변하지 않는다. AI 안을 고친 후 채택하고 싶다면 '수정판 생성'을 사용한다.[6:2]
제안 중인 버전에서 수정판을 만들면, 원래의 제안은 취소되고 새로운 제안으로 리뷰를 계속할 수 있다. 이를 통해 AI 안을 그대로 채택했는지, 사람이 손을 댔는지를 이력으로 구분할 수 있다.
Workspace의 '승인 대기'에서는 '사람 확인', 'AI 평가 중', '미평가' 등을 전환하며 Project나 확인 이유로 대상을 좁힐 수 있다. Project를 하나씩 열지 않고, 리뷰할 것을 찾기 위한 화면이다.[6:3]
Projectや確認理由で提案を絞り込める承認待ち画面
대상 제안을 열고, Version 상세에서 채택 여부를 판단한다.
일반적인 승인은 사람이 수행한다. 임의의 자동 승인 기능도 있지만, 기본적으로 비활성화된 manual
이며, 도입한 것만으로 모든 규칙이 자동 승인되는 것은 아니다.[8]
대상은 명시적으로 허가하고 AI 데이터 이용에 동의한 Workspace 중, 기존 승인 버전이 있는 저위험 L3 규칙의 유지보수 개정 등에 한정된다. Gemini, Vertex AI 평가 및 Model Armor 검사를 거치고, 애플리케이션 측 조건까지 충족했을 때만 승인으로 진행된다. 정보가 부족하거나 평가에 실패할 경우, 사람의 확인 단계로 돌아간다.
도입 시에는 승인 상태를 변경하지 않고 임시 판정(仮判定)을 기록하는 shadow
으로, 인간의 판단과 비교한다. 평가 점수를 정답률로 간주하지 않는다는 것도 운영 방침에 포함된다. 최초 채택, Drift 대응 판단, 최종 GitHub 병합은 자동 승인을 사용할 경우에도 사람에게 남아있다.[8:1]
규칙을 승인하면 다음 단계는 개발 환경에 전달하는 것이다. Rule Branch는 대상이 되는 승인된 규칙으로부터 리포지토리별로 선택한 지시 파일을 생성한다.[1:3][9]
출력처는 AGENTS.md,
CLAUDE.md,
.github/copilot-instructions.md,
그리고 .rulebranch/rules/ 배하의 레이어별 파일이다.
이 변환은 승인된 내용을 매번 AI에게 다시 말하게 하는 처리가 아니다. 결정론적 컴파일러를 사용하여 동일한 입력에서 동일한 내용을 생성한다.[9:1]
기존의 AGENTS.md 등에서는 다음 마커로 둘러싸인 Rule Branch 관리 구역을 업데이트하고, 그 바깥쪽 수기 작성 부분을 유지한다.[10]
<!-- BEGIN RULEBRANCH MANAGED RULES -->
여기에 승인된 규칙이 생성된다.
<!-- END RULEBRANCH MANAGED RULES -->
이는 구분하는 설명 예시이다. 최초에는 기존 파일에 관리 구역을 추가하고, Draft PR로 변경 내용을 확인한다. 마커의 불일치나 기존 파일과의 정합성 문제가 있으면 무조건 덮어쓰지 않고 처리를 중단한다.[10:1]
Project의 '반영 상황'에서는 리포지토리별 생성물, PR 이력, 병합 후 검증 상태를 확인할 수 있다. '생성 파일 생성/업데이트'에서 생성 처리를 실행하는 경로도 있다.[11]
Draft PR、検証待ち、不一致、検証済みなどを確認する反映状況画面
생성 작업 완료뿐만 아니라 실제 Draft PR과 반영 상태를 확인한다.
Rule Branch가 만드는 것은 Draft PR이며, 자동으로 병합하지 않는다. GitHub에서 차이점을 확인하고 사람이 병합한다. 그 후 Rule Branch로 생성 파일과 기본 브랜치상의 내용을 대조한다.[11:1]
上段は承認、生成、Draft PR、マージ、検証。下段は開発環境での取得、読取、テスト
상단은 배포까지의 단계, 하단은 개발 환경에서의 확인. '검증됨'이 의미하는 것은 배포 파일의 정합성이다.
불일치가 있으면 대상 파일을 확인하고 재생성한 복구용 PR을 리뷰한다. 여러 리포지토리가 대상인 경우, 일부에 반영과 전체 대상에 반영도 구분하여 처리한다.[11:2]
PR을 병합한 후에는 개발 환경에서 그 변경 사항을 가져와 개발 AI가 새로운 지시 파일을 읽어야 한다.
Rule Branch로 승인하는 것만으로는 실행 중인 AI 세션에 새로운 명령이 주입되는 것이 아니다. 파일이 도착했는지, AI가 읽었는지, 구현이 규약에 맞는지 여부는 각각 별도로 확인한다. 마지막은 코드 리뷰나 테스트로 확신한다.[1:4]
나중에 규칙을 읽으면 '본문은 알겠는데, 왜 이 방침을 세웠는지'가 모호해지는 경우가 있다.
Rule Branch에서는 Version을 승인할 때 판단 기록을 자동 생성한다. 판단 이유, 배경, 변경 종류, 승인 코멘트, 근거, 승인된 Version으로의 링크를 확인할 수 있다.[12]
判断の背景、承認内容、根拠、承認したVersionを確認する判断記録の詳細
최신 본문뿐만 아니라 그 때 승인한 버전과 판단의 이유를 추적한다.
목록에서는 키워드, 관련 규칙, 기간 등으로 검색하여 규칙별로 모아서 표시할 수 있다. 오래된 판단 기록 링크는 그 판단으로 승인했던 Version을 가리키며, 나중에 현행판으로 대체되는 것은 아니다.[12:1]
판단 기록은 읽기 전용이며, 수동 작성/편집/삭제 화면은 없다. 채택의 경위를 확인하고 싶을 때는 판단 기록, 누가 어떤 작업을 했는지 조사하고 싶을 때는 감사 로그 등 목적에 따라 구분하여 사용한다.[12:2][13]
조직 Workspace에서는 여러 Project에 공통되는 조직 규칙과 Project 고유의 규칙을 관리할 수 있습니다.
Project 측에서 조직 규칙을 대체하는 override,
양쪽을 모두 채택하는 extend,
이유를 기록하여 상위 규칙을 적용하지 않도록 하는 deny와 같은 관계 설정을 합니다. 조직의 필수 규칙에 대해서는 하위 Project로부터의 대체나 미적용을 허용하지 않습니다.[14]
다만, 현재 출력 파일은 리포지토리 단위입니다. 언어나 디렉터리의 일부에 한정된 예외 등 표현할 수 없는 조건부 대체/미적용은 생성 처리에서 거부될 수 있습니다. 임의의 조건을 그대로 실행할 수 있는 범용 정책 엔진으로 간주하기보다는, 대응하는 적용 범위를 확인하고 사용해야 합니다.[9:2]
조직 Workspace에는 Owner(소유자), Administrator(관리자), Maintainer(유지보수자), Member(멤버), Viewer(뷰어)의 역할이 있습니다. 예를 들어, Project의 표준/권장 규칙 승인은 Maintainer 이상이 수행하고, 조직 규칙 승인은 Administrator 이상이 수행합니다. 개인 Workspace에서는 Owner가 작업을 수행합니다.[6:4][13:1]
중복된 규칙 통합, 불필요해진 규칙 폐지/아카이브와 같은 라이프사이클도 처리할 수 있습니다. 단순히 규칙을 늘리는 것뿐만 아니라, 운영을 지속하는 과정에서 정리하기 위한 기능입니다.[6:5]
조직 기능은 공개 소스와 매뉴얼에 기반한 소개이며, 게재된 개인 Workspace 이미지가 조직 역할의 동작을 보여주는 것은 아닙니다.[14:1]
진입점 역할을 하는 Web UI는 공개 리포지토리의 README에서 열 수 있습니다. 로그인 전에는 서비스 설명과 로그인 화면을 확인할 수 있습니다. 실제로 분석/배포하려면, 로그인 외에도 대상 리포지토리에 대한 GitHub App 연결과 동작하는 백엔드 구성이 필요합니다.[1:5]
로컬에서 화면이나 상태를 확인할 방법으로 Firestore Emulator와 고정 seed를 사용하는 절차를 준비했습니다. 세팅은 공개 리포지토리의 로컬 개발 환경을 참고해 주십시오.
고정 seed는 화면을 재현하기 위한 데이터이며, 실제로 AI를 호출한 결과나 분석 정확도를 나타내는 것은 아닙니다.[1:6]
실제 경로를 시도하는 경우에는, 작은 검증 전용 리포지토리부터 시작하면 원래 규칙, 변경 내용, 생성된 지시사항을 비교하기 쉽습니다.
GitHub App과 Google Cloud 측의 구성은 GCP 구축 절차, 후보 확인부터 GitHub에 배포까지는 최초 규칙 배포에 통합했습니다.
첫 번째 확인에서는 후보를 하나 채택하고 Draft PR 내용을 확인하여 병합(merge)한 후 반영 상태를 대조합니다. 그 후에 의존 선언을 변경하고, 불일치 감지 및 개정안 검토로 진행하면 일련의 과정을 따라가기 쉽습니다.
Rule Branch는 브라우저 내에서만 분석이 완료되는 구조가 아닙니다. 코드, 설정 파일, 규칙 본문, 근거 발췌 중 필요한 범위를 서버와 설정된 AI provider로 전송합니다. 업무 리포지토리를 다룰 경우에는 그 이용 조건과 운영 방침을 확인한 후 연동해야 합니다. GitHub의 OAuth token이나 installation token은 AI provider에게 전달되지 않는 구조입니다.[1:7]
기술 구성은 Next.js・React・TypeScript 기반의 Web, Python Worker, Firestore, Cloud Tasks, Google Cloud상의 실행 인프라가 중심이며, AI 처리에 Gemini를 이용합니다. AI는 후보나 개정안을 반환하고, 권한 확인, 상태 전이(state transition), 파일 생성, 배포 대조 등은 애플리케이션 코드가 담당합니다.[1:8]
Rule Branch가 목표로 하는 것은 개발 규약의 보관 장소를 늘리는 것이 아닙니다.
'무엇이 바뀌었는지', '어떤 규칙을 어떻게 수정할지', '무엇을 승인했는지', '어디까지 배포되었는지'를 연결하는 것입니다.
최초 후보 추출로 규칙을 정리하고, 의존 관계와의 불일치를 근거와 함께 확인합니다. 개정안을 검토하여 채택하면 AI용 지시 파일로 배포합니다. 나중에 판단을 되돌아보기 위해 버전과 이유도 남깁니다.
코드가 바뀌면, 규칙도 자라납니다. 키운 규칙을 다음 개발에서 사용할 수 있는 형태로 전달하는 것입니다.
AI에게 넘겨줄 규칙을 만든 후, 그 업데이트를 어떻게 지속할 것인가. Rule Branch는 그 유지보수와 인수인계를 지탱하기 위한 애플리케이션입니다.
아래는 작성 시 확인한 공개 커밋 30d1e32397bec4b4cb05c0e86b21d427c9f384d5을 참조하고 있습니다. 게재 화면 역시 동일 커밋의 공개 매뉴얼 이미지입니다.
RuleBranch README: 목적, 현재 탐지 범위, 출력 위치, AI 역할, 기술 구성, 이용 시 전제 조건 등을 참조하세요. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎
로그인, Workspace, Project: GitHub App 연결, Project 생성, 최초 분석, 개요 화면 등을 참조하세요. ↩︎ ↩︎
최초 규칙 추출 구현: README, 설정, 지시 파일을 우선하고 소스 일부를 상한선까지 수집하는 처리입니다. ↩︎
규칙의 개념과 작성/편집: 레이어(Layer), 상태(State), Version, 적용 대상, 종속성 감시 등을 참조하세요. ↩︎ ↩︎ ↩︎ ↩︎
Version 검토와 라이프사이클: 승인(Approval), 거부(Rejection), 수정본(Revision), 승인 대기(Pending Approval), 권한(Permission), 통합/폐지(Integration/Deprecation) 등을 참조하세요. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎
불일치 탐지 및 개정 제안: React의 종속 선언 관측 예시, 지적 판단, 수동 스캔, 제안 생성 등을 참조하세요. ↩︎ ↩︎ ↩︎
자동 평가/인간 에스컬레이션 운영: manual, shadow, auto, 대상 조건, 평가 실패 시 인간 확인 등을 참조하세요. ↩︎ ↩︎
기존 AI 지시 파일과의 공존: 관리 영역(Management Area), 수기 작성 부분 유지, 일관성 결함 시 중단에 대해 다룹니다. ↩︎ ↩︎
GitHub 반영: Draft PR, 인간에 의한 Merge, 반영 검증, 여러 리포지토리로의 반영 등을 참조하세요. ↩︎ ↩︎ ↩︎
멤버, 개인 설정, 감사 로그: 멤버, 역할(Role), 감사 로그에 대해 다룹니다. ↩︎ ↩︎
조직 규칙과 Project 규칙의 관계: override, extend, deny, 필수 규칙 보호, 화면 관측 범위 등을 참조하세요. ↩︎ ↩︎
