predeploy-quality-gate

name	predeploy-quality-gate
description	배포/머지 전에 현재 Git 브랜치(HEAD) 변경사항을 품질 게이트로 검증하고, 차단(BLOCKER)/경고(WARN)/제안(SUGGEST) 항목을 리스트로 리포트하기. "배포 전 품질 점검", "quality gate", "머지 게이트", "현재 브랜치 코드 품질 검증" 요청에 사용하기. 프로젝트 유형(Flutter/Node/Python/Go/Rust 등)을 자동 탐지해 포맷/린트/타입체크/테스트를 가능한 범위에서 실행하고, 리팩터링 후 미사용/미참조 코드 제거를 제안하기. 변경 범위가 크면 sub-agent로 리뷰를 병렬화하기.

Predeploy Quality Gate (배포 전 품질 게이트)

목적

• 현재 브랜치(HEAD)의 변경사항을 기준 ref 대비 점검하고, 차단(BLOCKER)/경고(WARN)/제안(SUGGEST) 항목을 리스트로 반환하기.
• 자동 점검(명령 실행 + 휴리스틱)과 수동 점검(체크리스트 기반 리뷰)을 분리해 보고하기.

빠른 실행

• 자동 점검 스크립트 실행하기(기본: base 자동 탐지 + full 모드 + 작업 트리(workspace) 범위):
  • python3 ~/.codex/skills/predeploy-quality-gate/scripts/quality_gate.py
• 테스트를 생략하고 빠르게 확인하기:
  • python3 ~/.codex/skills/predeploy-quality-gate/scripts/quality_gate.py --mode quick
• 비교 기준 ref를 명시하기(예: main):
  • python3 ~/.codex/skills/predeploy-quality-gate/scripts/quality_gate.py --base origin/main
• 커밋된 변경만(PR diff처럼) 보려면:
  • python3 ~/.codex/skills/predeploy-quality-gate/scripts/quality_gate.py --scope committed
• 미추적 파일(untracked)을 제외하려면:
  • python3 ~/.codex/skills/predeploy-quality-gate/scripts/quality_gate.py --no-untracked

워크플로

1) 변경 범위 확정하기

• 기본 비교 기준을 origin/HEAD로 두고, 자동 탐지가 실패하면 --base로 지정하기.
• 기본 범위는 workspace이며, merge-base 대비 작업 트리(스테이징/미스테이징) 변경과 **미추적 파일(untracked)**까지 포함하기.
• PR diff처럼 커밋된 변경만 점검하려면 --scope committed로 base...HEAD(triple-dot) 범위를 사용하기.

2) 자동 점검 수행하기

• scripts/quality_gate.py 실행 결과에서 다음을 우선 확인하기.
  • 프로젝트 유형을 자동 탐지해 가능한 품질 점검 커맨드를 실행한다(없으면 스킵 + 제안으로 남김).
  • 실행 예시(환경/프로젝트에 따라 일부만 실행됨):
    • format:* (dart/black/gofmt/cargo fmt/노드 스크립트 등)
    • lint|analyze|typecheck:* (flutter analyze/go vet/cargo clippy/ruff/eslint/tsc 등)
    • tests:* (full 모드에서만. scripts/run_tests.sh가 있으면 최우선 사용)
  • diff 휴리스틱으로 감지된 차단/경고 항목

2-1) 노이즈 최소화 규칙(필수)

• 테스트 미실행 추정 금지: 실행 로그/실패 증거가 없으면 “테스트 미실행” 지적을 추가하지 말기.
• 빌드 넘버/버전 단독 변경은 의존성 변경 경고에서 제외하기.
• 디버그/로그 출력은 과도·민감정보 노출·운영 경로 영향이 명확할 때만 지적하고, 테스트 파일/디버그 가드/정상 로깅은 지적하지 말기.

3) 미사용/미참조 코드 제거 점검(필수)

• 자동 점검 출력에서 unused, never used, declared and not used 류가 감지되면:
  • 사용처가 없다면 코드/임포트/파일을 제거하기(클린업은 머지 게이트 항목).
  • 제거가 불가피하게 지연되면 WHY + 제거 계획(이슈/티켓)을 남기기.
• 리팩터링/이름 변경/라우팅 변경이 포함되면 아래를 추가로 확인하기.
  • 더 이상 호출되지 않는 핸들러/유틸/DTO/설정값/플래그
  • 임시 디버그 코드, no-op 분기, 주석 처리된 레거시 경로
  • “남아있지만 아무도 안 쓰는” 파일(파일명/모듈 경로로 rg/git grep로 사용처 확인)

4) 수동 점검(필수) 수행하기

• references/quality-gate.md를 로드하고, 변경 diff(특히 변경된 핵심 파일)를 체크리스트로 리뷰하기.
• 자동 점검이 포착하지 못하는 항목(의도 정합성, 트랜잭션/동시성, 운영/롤백, 중복 제거 등)을 별도로 확인하기.
• “확인 결과”를 차단/경고/제안 리스트에 추가하기.

5) 최종 리포트 작성하기

• 아래 출력 템플릿을 사용해, 차단(BLOCKER)이 있으면 최상단에 먼저 제시하기.
• 각 항목에 (분류 A~M) + 근거(파일/라인/코드) + 권장 조치를 포함하기.

대규모 변경(병렬 리뷰: sub-agent)

• 조건(권장): 변경 파일이 많거나(예: 30개+), 모듈/언어가 섞여 있거나, 보안/데이터 영향 범위가 넓을 때.
• 방법:
  • 2~3개의 sub-agent로 역할을 분리해 병렬 리뷰(예: ① 테스트/빌드 ② 보안/구성/의존성 ③ 클린업/미사용 코드/아키텍처).
  • 각 sub-agent에게 “담당 범위 파일 목록 + 기대 출력 형식(BLOCKER/WARN/SUGGEST + 근거 + 조치)”을 명시하고 결과를 회수한다.
  • 주 에이전트가 중복을 제거하고, 심각도 상향(복수 근거) 및 우선순위를 정리해 최종 리포트에 통합한다.
• sub-agent 프롬프트 템플릿(요약형):
  • 다음 변경 파일을 품질 게이트 기준으로 리뷰하고, BLOCKER/WARN/SUGGEST를 각각 5개 이내로 정리해줘. 각 항목은 (분류 A~M) + (파일:line) + 근거 1줄 + 권장 조치 1줄로 작성. 변경 파일: ...

출력 템플릿

요약

• 기준: <base>...HEAD|WORKTREE
• 범위: workspace|committed (untracked 포함/제외)
• 변경 파일: N개
• 자동 점검: 실행 커맨드 N개 / 실패 M개 (mode=quick|full)

차단(BLOCKER)

• [분류] 제목 (파일: path:line) / 근거: ... / 권장 조치: ...

경고(WARN)

• [분류] 제목 (파일: path:line) / 근거: ... / 권장 조치: ...

제안(SUGGEST)

• [분류] 제목 (파일: path:line) / 근거: ... / 권장 조치: ...

수동 확인 결과(체크리스트 기반)

• [분류] 확인 항목 / 결론: OK|보완 필요 / 근거: ... / 후속 조치: ...

레퍼런스

• 품질 게이트 전문: references/quality-gate.md
• 자동 점검 스크립트: scripts/quality_gate.py