AIGate 운영 문서

개요

지금까지 만든 것

AIGate는 로컬 변경사항, secret 위험, 프로젝트 기반 점수, PR 준비 상태, 릴리스 준비 상태를 점검하는 CLI입니다.

패키지는 npm의 aigate-cli로 공개되어 있으며, GitHub Actions와 npm Trusted Publishing으로 태그 기반 자동 배포가 가능합니다.

Codex, Gemini, Claude Code가 같은 저장소 규칙을 따르도록 통합 파일을 생성하는 기능도 포함되어 있습니다.

npm

설치와 빠른 실행

설치 없이도 npx로 바로 실행할 수 있습니다.

npm install -g aigate-cli
aigate --version
aigate check

npx aigate-cli check

프로세스

전체 운영 프로세스

AIGate는 개발자가 커밋하기 전부터 PR, CI, 릴리스, npm 배포까지 같은 기준으로 검증하도록 설계되었습니다.

프로세스

상황별 사용 예시

AIGate는 모든 순간에 같은 명령을 쓰는 도구가 아니라, 프로젝트 상태와 위험도에 따라 다른 루틴을 빠르게 꺼내 쓰는 도구입니다.

상황

처음 저장소에 도입할 때

프로세스

기본 설정을 고르고, 부족한 문서/AI 지침/hook을 단계적으로 만듭니다.

예시 명령

aigate start --route default --ask-steps
aigate doctor
aigate install-hook --pre-push

상황

AI가 코드를 많이 바꾼 뒤

프로세스

변경 파일과 secret 위험을 먼저 보고, 테스트 실패는 AI 수정 프롬프트로 넘깁니다.

예시 명령

aigate check
aigate test
aigate aitest

상황

PR을 열기 직전

프로세스

push 전 gate를 통과시키고, PR 설명과 리뷰어용 요약을 생성합니다.

예시 명령

aigate git-ready
aigate push -u origin feature/my-work
aigate pr-check

상황

private GitLab 모노레포

프로세스

프로필을 고정하고 turbo 실행기 감지 후 workspace 테스트를 대체 실행하며 GitHub/npm 패키지 검사를 앱 점수에서 제외합니다.

예시 명령

aigate setup --hosting gitlab --ci-provider gitlab --project-type app --package-manager pnpm
aigate test
aigate evaluate-project

상황

오픈소스 공개 준비

프로세스

README, 기여 문서, 이슈 템플릿, CODEOWNERS를 만들고 저장소 기반 점수를 확인합니다.

예시 명령

aigate start --route oss --owner @team
aigate evaluate-project --deep --report
aigate github setup --dry-run

상황

릴리스 전후

프로세스

태그와 npm 상태를 점검하고, 배포 후 상태 추세를 남깁니다.

예시 명령

aigate release-check --npm
npm run ci
aigate trends record

상황

로컬 상태를 비우거나 제거할 때

프로세스

먼저 삭제 대상을 미리 본 뒤, 확실할 때만 --force로 적용합니다.

예시 명령

aigate clean
aigate clean --force
aigate uninstall --force

릴리스

릴리스 자동화 차트

첫 배포 이후에는 버전 bump와 태그 push가 릴리스의 핵심 트리거입니다.

명령어

명령어 맵

설정

startstart --route defaultstart --route ossinitresetsetupsettingsintegrate

첫 실행

doctordemoinstall-hook

보호 게이트

checktestaitestgit-readypushpr

유지보수

cleanuninstalldelete

보고서

ai reportpr-checkgithub commentgithub checkgithub setuptrendsreportevaluate-projectverify-enforcementcompliance-reportdashboardaudit-report

릴리스

release-checkrelease-check --npmbranch-strategybranch-strategy --comparenotify

명령어

전체 명령어와 사용 과정

명령어	용도	언제 쓰는가
`npm install -g aigate-cli`	CLI를 전역 설치합니다.	처음 사용하는 개발자 환경
`npx aigate-cli check`	설치 없이 현재 저장소 상태를 확인합니다.	빠른 체험 또는 CI 전 점검
`aigate start`	화살표 메뉴 또는 route 옵션으로 프로젝트 설정 흐름을 실행합니다.	처음 프로젝트에 AIGate를 적용할 때
`aigate start --route default --ask-steps`	추천 설정 단계를 예/아니오로 확인하며 실행합니다.	처음 적용할 때 필요한 단계만 고르고 싶을 때
`aigate start --route default --steps init,repo-files`	지정한 설정 단계 ID만 실행하고 나머지는 건너뜁니다.	문서화된 온보딩이나 반복 실행
`aigate start --route oss --owner @team`	README, 기여 문서, 이슈 템플릿, PR 템플릿, CODEOWNERS를 생성합니다.	공개 저장소 기여 흐름을 열 때
`aigate start --route ai --provider all`	AIGate 설정과 Codex/Gemini/Claude 지침 파일을 생성합니다.	AI assistant 규칙을 한 번에 심을 때
`aigate init`	AIGate 기본 설정 파일과 리포트 폴더를 만듭니다.	새 프로젝트에 AIGate를 적용할 때
`aigate reset`	AIGate 설정과 settings, 리포트 placeholder를 다시 작성합니다.	설정을 처음 상태로 되돌릴 때
`aigate clean --force`	생성된 AIGate 리포트와 로컬 상태를 삭제합니다.	리포트와 generated state를 비울 때
`aigate uninstall --force`	AIGate 설정, .aigate 디렉터리, AIGate 소유 hook을 제거합니다.	프로젝트에서 AIGate를 제거할 때
`aigate setup --language <en\|ko\|ja\|zh>`	CLI 출력 언어를 저장합니다.	팀 기본 언어를 맞출 때
`aigate setup --hosting gitlab --ci-provider gitlab`	GitLab 프로젝트 프로필을 저장합니다.	GitHub 기준이 맞지 않는 내부 GitLab 앱
`aigate settings`	현재 AIGate 설정을 확인합니다.	설정 검증
`aigate doctor`	첫 실행 환경, Git hook, 프로젝트 기반 상태를 진단합니다.	처음 실행하거나 저장소 상태를 점검할 때
`aigate demo`	파일을 바꾸지 않고 AIGate 사용 흐름을 보여줍니다.	처음 체험하거나 팀에 사용법을 설명할 때
`aigate install-hook --pre-push`	git push 전에 git-ready가 실행되도록 pre-push hook을 설치합니다.	push 실수를 로컬에서 막고 싶을 때
`aigate check`	변경 파일, 실제 secret finding, 민감 파일 제거 상태를 요약합니다.	커밋 전 가벼운 점검
`aigate test`	Git readiness와 root script, turbo task, pnpm workspace, workspace package 테스트 명령을 감지해 실행합니다. turbo 실행기가 없으면 workspace script로 대체 실행합니다.	커밋 전 실제 테스트까지 확인할 때
`aigate ai report`	현재 문제점, 잘된 점, 방향성, AI 전달 프롬프트를 정리합니다.	AI에게 프로젝트 개선 방향을 맡기기 전
`aigate ai report --apply --provider codex`	AI 프로젝트 브리프를 CLI에 전달하고 실시간 에이전트 출력과 stdout/stderr 리포트를 남깁니다.	명시적으로 AI 자동 조치를 허용할 때
`aigate aitest`	테스트 실패를 AI가 고칠 수 있도록 프롬프트 파일을 생성합니다.	실패 원인을 AI 에이전트에 넘길 때
`aigate aitest --apply --provider codex`	AI CLI를 호출하고 실행 로그, 종료 코드, stdout/stderr를 표시합니다.	명시적으로 AI 자동 조치를 허용할 때
`aigate git-ready`	테스트, secret scan, 프로젝트 점수를 포함한 게이트를 실행합니다.	커밋/푸시 전 필수 점검
`aigate push -u origin <branch>`	검증 통과 후 git push를 실행합니다.	브랜치를 원격에 올릴 때
`aigate pr-check`	PR 준비 상태 리포트를 생성합니다.	PR 설명 작성 전
`aigate pr --title "..."`	GitHub CLI를 통해 PR을 생성합니다.	브랜치 푸시 후
`aigate github comment --pr <number>`	PR에 AIGate 요약 댓글을 작성합니다.	리뷰어에게 gate 결과를 남길 때
`aigate github check --format json`	GitHub Checks/Actions용 summary payload를 생성합니다.	CI에서 AIGate 결과를 표시할 때
`aigate github setup --owner @team`	PR 템플릿과 CODEOWNERS를 설정합니다.	공개 기여 흐름을 정리할 때
`aigate trends record`	프로젝트 상태 스냅샷을 기록합니다.	릴리스 전후 상태 추세를 남길 때
`aigate trends show`	기록된 상태 추세를 요약합니다.	팀 리뷰나 주간 점검 때
`aigate report --format markdown`	로컬 워크플로 리포트를 출력합니다.	상태 공유
`aigate report --format sarif`	secret finding을 SARIF로 출력합니다.	보안 도구 연동
`aigate evaluate-project`	저장소 기반 점수를 계산합니다.	오픈소스 공개 준비 확인
`aigate evaluate-project --deep --report`	Git signal을 포함한 상세 평가 보고서를 만듭니다.	릴리스/분기 리뷰
`aigate verify-enforcement --apply`	GitHub/GitLab API로 서버측 AIGate 필수 검사를 검증하고 검증 증거를 기록합니다.	CI 필수 검사가 실제 merge를 막는지 확인할 때
`aigate compliance-report`	컴플라이언스 통제 리포트를 생성합니다.	감사/운영 준비 공유
`aigate dashboard`	로컬 HTML 상태 대시보드를 작성합니다.	self-hosted reporting 시작
`aigate branch-strategy`	팀 규모와 릴리스 흐름에 맞는 브랜치 전략을 추천합니다.	브랜치 정책 설계
`aigate branch-strategy --compare`	여러 브랜치 전략 제안을 점수, 강점, 위험, 전환 단계로 비교합니다.	팀에 맞는 브랜치 모델을 선택할 때
`aigate branch-strategy --apply`	브랜치 정책, 릴리스, hotfix, PR, CODEOWNERS, 정책 팩 초안을 생성합니다.	정책 파일을 시작할 때
`aigate integrate all`	Codex, Gemini, Claude Code 통합 문서를 생성합니다.	AI assistant가 같은 규칙을 따르게 할 때
`aigate release-check`	패키지, workflow, tag 상태를 점검합니다.	릴리스 태그 생성 전
`aigate release-check --npm`	프로필을 감지해 npm registry, GitHub/GitLab, package manager 상태를 확인하고 app에 해당 없는 npm/package version gate는 제외합니다.	자동 배포 전후
`aigate audit-report`	거버넌스와 정책 상태를 요약합니다.	운영 감사와 공개 준비 리뷰
`aigate notify send --channel terminal`	로컬 알림 이벤트를 출력합니다.	게이트 차단 상황 확인
`aigate git-ready --notify-channel slack`	BLOCK 상황에서 Slack webhook 알림을 전송합니다.	민감 정보나 고위험 변경이 차단될 때
`aigate notify test --channel slack`	Slack, Discord, Teams, email, Linear, Jira payload를 테스트합니다.	팀 채널 연동 점검

Git

브랜치와 배포 흐름

main은 보호된 안정 브랜치이며, codex/*와 feature/* 같은 작업 브랜치에서 PR을 만든 뒤 병합합니다. release/*와 hotfix/*는 배포 안정화와 긴급 수정에 예약되어 있습니다.

npm install -g aigate-cli
aigate setup --language ko
aigate ai report
aigate start --route default --ask-steps
aigate start --route oss --dry-run
aigate reset --dry-run
aigate clean
aigate start --route ai --provider all
git switch -c feature/my-change
aigate doctor
aigate install-hook --pre-push
aigate test
aigate aitest
aigate git-ready
git add <files>
git commit -m "feat: short summary"
aigate push -u origin feature/my-change
aigate pr-check --output .aigate/reports/pr.md
aigate pr --title "feat: short summary"
aigate github comment --pr <number>
aigate github check --output .aigate/reports/github-check.md
aigate trends record
aigate branch-strategy --compare
aigate github setup --owner @your-org/team --dry-run
aigate release-check --npm

기능

현재 구현된 기능

npm 패키지 aigate-cli 공개 배포와 npx 실행

Git 변경사항과 untracked 파일 기반 readiness check

aigate start 기반 안내형 시작 루트

aigate start --route default 기반 단계별 기본 설정

aigate reset, clean, uninstall 기반 초기화와 삭제 명령

aigate start --route oss 기반 오픈소스 시작 파일 생성

aigate test 기반 turbo 실행기 감지형 root/workspace 테스트 자동화

pnpm-workspace.yaml, package.json workspaces, apps/*, packages/* 테스트 탐지와 대체 실행

aigate ai report 기반 AI 프로젝트 상태 브리프

aigate aitest 기반 AI 수정 프롬프트, 실시간 에이전트 로그, 선택적 에이전트 실행

doctor, demo, install-hook 기반 첫 실행 UX

doctor 기반 generatedBy 버전 드리프트 경고

pre-push Git hook 설치

doctor와 evaluate-project 기반 권고형/부분강제/검증된 서버강제 AIGate enforcement 진단

verify-enforcement 기반 GitHub/GitLab 서버강제 라이브 검증과 검증 증거 기록

검증된 서버강제 없이 AIGate CI 게이트만 있을 때 evaluate-project 최종 점수 A등급 상한 적용

secret 패턴 탐지와 SARIF 출력

git-ready, guarded push, guarded PR 생성 흐름

GitHub PR comment와 GitHub Checks summary payload

PR 템플릿과 CODEOWNERS 안내형 설정

재사용 가능한 공개 GitHub Action

프로젝트 상태 추세 기록

private 앱, GitLab, pnpm 자동 프로필 감지와 설정 고정

doctor, AI 지침, branch strategy 정책팩의 GitHub/GitLab 프로필 정합성

Markdown, HTML, JSON, SARIF 리포트

컴플라이언스 리포트와 로컬 HTML 상태 대시보드

프로젝트 점수와 deep Git signal 평가

브랜치 전략 추천, 제안 비교, 정책 팩 생성

Codex/Gemini/Claude Code 통합 파일 생성

한국어/영어/일본어/중국어 CLI 설정

release-check와 앱 프로필 인식 release-check --npm

npm Trusted Publishing 기반 자동 배포

GitHub CI, OpenSSF Scorecard, GitHub Release 운영

터미널, Slack BLOCK, Discord, Teams, email, Linear, Jira 알림

GHCR Docker 이미지와 Homebrew tap 공개 배포

기능

미래에 구현할 기능

Slack BLOCK 알림을 제품 수준 UX로 고도화

중앙 알림 정책 강화

Linear/Jira workflow 연동 심화

standalone binary 배포

조직 대시보드

SSO/SAML, 엔터프라이즈 거버넌스