AgentSkillsCN

predeploy-quality-gate

在部署或合并前，对当前Git分支（HEAD）的变更进行质量门禁验证，并以列表形式汇报阻断（BLOCKER）、警告（WARN）及建议（SUGGEST）项。可用于“部署前质量检查”“quality gate”“合并门禁”“当前分支代码质量验证”等需求。自动识别项目类型（如Flutter、Node、Python、Go、Rust等），在可行范围内执行格式化、Lint检查、类型检查及测试，并在重构后建议移除未使用或未引用的代码。若变更范围较大，则可借助子代理实现评审的并行化。

SKILL.md
--- frontmatter
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