ACC

AI / Repository

ACC는 인터랙티브 웹 데모 저장소이자, acc-ci 범용 CI 자동화 CLI를 포함한 운영 템플릿 레포입니다.

3줄 요약

앱 레이어: 이모지 물리 시뮬레이션 데모 웹 앱
자동화 레이어: 테스트/Mock/CI 부트스트랩 CLI (acc-ci)
운영 레이어: GitHub Actions 기반 품질/보안/리뷰 자동화 스택

GitHub 주소

빠른 시작

git clone https://github.com/jjunhaa0211/ACC
cd ACC
npm install
npm run serve:ci          # -> http://127.0.0.1:4173

# 품질 체크
npm run lint
npm run test:e2e:ci
npm run test:lighthouse

acc-ci란?

acc-ci는 ACC에 포함된 범용 CI 자동화 CLI입니다. 프로젝트 진입 직후 필요한 테스트/Mock/CI 골격을 빠르게 만들고 동일한 검증 기준을 로컬과 CI에 강제하는 도구입니다.

해결하려는 문제

프로젝트마다 CI 템플릿을 처음부터 다시 만들며 품질 편차 발생
로컬 통과와 CI 실패가 반복되는 환경 불일치
Mock 데이터 관리가 느슨해 회귀 탐지 시점이 늦어짐
AI PR 증가 대비 본문 품질/추적성 기준 부재

명령 체계

# 전체 자동화 (권장)
node acci/bin/acc-ci.mjs bootstrap --project . --provider github

# 단계별 실행
node acci/bin/acc-ci.mjs detect --project .
node acci/bin/acc-ci.mjs init --project .
node acci/bin/acc-ci.mjs scaffold-tests --project .
node acci/bin/acc-ci.mjs setup-ci --project . --provider github
node acci/bin/acc-ci.mjs verify --project . --ci

명령별 역할

detect: 파일 시그니처 기반 생태계 감지
init: .acci/config.json 생성 또는 재사용
scaffold-tests: Mock 데이터와 계약 테스트 생성
setup-ci: Universal CI + AI PR 정책 파일 생성
verify: mock 검증 후 install/lint/test/(coverage) 실행
bootstrap: init → scaffold-tests → setup-ci → verify 일괄

설정 파일 구조

{
  "project": { "ecosystem": "node" },
  "commands": {
    "install": ["npm ci"],
    "lint": ["npm run lint"],
    "test": [
      "npm run test:mock --if-present",
      "npm run test --if-present",
      "npm run test:e2e:ci --if-present"
    ],
    "coverage": ["npm run test:coverage --if-present"]
  },
  "qualityGates": {
    "requireLint": true,
    "requireTests": true,
    "requireMockValidation": true
  }
}

대표 생성물

.acci/config.json: 프로젝트별 실행 정책
.github/workflows/acc-universal-ci.yml: 범용 품질 게이트
.github/workflows/ai-pr-policy.yml: AI PR 본문 정책
tests/mocks/users.mock.json: Mock 계약 데이터
tests/generated/mock-contract.test.mjs: Node 계약 테스트

부트스트랩 흐름

bootstrap
├─ init            → .acci/config.json
├─ scaffold-tests  → tests/mocks/*, tests/generated/*
├─ setup-ci        → .github/workflows/*, .github/scripts/*
└─ verify          → mock 검증 + install/lint/test

재실행 전략

# 기존 생성물 강제 갱신
npm run acc-ci -- bootstrap --project . --provider github --force

# verify 생략 (파일 생성만)
npm run acc-ci -- bootstrap --project . --provider github --skip-verify

# 실행 없이 어떤 명령이 도는지 확인
npm run acc-ci -- bootstrap --project . --provider github --dry-run

# coverage까지 포함해 전체 검증
npm run acc-ci -- bootstrap --project . --provider github --with-coverage

자주 나오는 실패 패턴

Mock data file missing: tests/mocks/users.mock.json 누락
Unsupported ecosystem: 감지 가능한 파일 시그니처 부족
lint/test 실패: .acci/config.json 명령 정의 먼저 점검

GitHub Actions 운영

ACC는 목적별 워크플로를 계층적으로 구성합니다.

1단계: acc-ci 생성 워크플로

acc-universal-ci.yml: universal verify + 아티팩트 업로드
ai-pr-policy.yml: AI PR 본문 계약 검사 + blocker 승인 정책

2단계: 저장소 운영 워크플로

web-ci.yml: quality/secret/dependency/e2e/lighthouse + 집계
pr-preview.yml: PR preview 배포 + 캡처 이미지 코멘트
deploy-pages.yml: Pages 배포 + 헬스체크 + 롤백

3단계: 보안/준수 워크플로

sbom.yml: CycloneDX SBOM 생성
codeql.yml: 정적 보안 분석

4단계: AI 리뷰 보조 워크플로

ai-pr-review.yml: fallback 규칙 기반 리뷰 코멘트
gemini-pr-review.yml: Gemini/CodeRabbit 리뷰 자동화

프로젝트 적용 가이드

1. acci 소스 포함 + 스크립트 등록

{
  "scripts": {
    "acc-ci": "node acci/bin/acc-ci.mjs",
    "acc-ci:bootstrap": "node acci/bin/acc-ci.mjs bootstrap --project . --provider github"
  }
}

2. 1차 부트스트랩 실행

npm run acc-ci:bootstrap

완료 기준: bootstrap complete 로그 출력

3. config.json 팀 표준 튜닝

commands.install: lockfile 전략에 맞는 설치 명령
commands.lint: monorepo/패키지별 lint 명령
commands.test: 단위/통합/E2E 순서와 옵션

4. 브랜치 보호 및 필수 체크 연결

최소 권장: ACC Universal CI, Web CI, AI Review Policy
보안 강화: SBOM (CycloneDX), CodeQL

5. GitHub AI App 연동

@codex review          # ChatGPT Codex Connector
@coderabbitai review   # CodeRabbit App
/gemini review         # Gemini 리뷰 App

Go-live 체크리스트

bootstrap/verify가 로컬과 CI 모두 통과
required checks가 실제 병합 조건으로 적용
PR 코멘트(Visual Report, Final Digest)가 자동 생성
팀 문서에 운영 규칙과 예외 처리 기준 반영