기본 Skill 3 - quality-gate

해당 Skill은 코드를 생성하지 않고 최종 변경을 검사한다.

 

핵심 동작은 다음이어야 한다.

변경 파일 목록 확인
→ 관련 테스트 확인
→ Lint 실행
→ Type Check 실행
→ 단위 테스트 실행
→ 통합 테스트 실행
→ Build 실행
→ Git diff 검토
→ 위험도별 문제 보고

 

경로 : .agents/skills/quality-gate/SKILL.md

 

---
name: quality-gate
description: 선택한 Git 변경사항을 파일 수정 없이 검토하고, 저장소에 정의된 필수 검사를 실행하며, 결함과 작업 범위를 벗어난 변경을 찾아 PASS, FAIL, BLOCKED 중 하나로 판정한다. 기능 구현이 완료된 후 Commit, Pull Request 또는 Merge 전에 사용한다. 코드를 구현하거나 발견된 문제를 자동으로 수정하는 용도로 사용하지 않는다.
---

# 목적

선택한 변경사항이 사람의 승인을 받을 준비가 되었는지 판단한다.

이 Skill은 읽기 전용 작업 절차다.

파일을 수정하거나, 포맷을 변경하거나, Stage, Commit, Push 또는 Merge하지 않는다.

# 필수 확인 자료

검토를 시작하기 전에 다음 내용을 확인한다.

1. 프로젝트 루트의 `AGENTS.md`를 읽는다.
2. 관련된 하위 폴더의 `AGENTS.md`를 읽는다.
3. 현재 작업의 수용 기준을 읽는다.
4. 저장소에 `Definition of Done` 문서가 있다면 읽는다.

# 작업 절차

## 1. 검토 범위 결정

사용자가 다음 중 어떤 변경사항을 검토하려는지 확인한다.

- 아직 Commit하지 않은 변경사항
- Stage 된 변경사항
- 특정 Commit
- 현재 Branch와 기준 Branch의 차이
- 사용자가 지정한 파일

검토 범위를 결정할 수 없다면 `BLOCKED`를 반환한다.

## 2. Git 변경사항 확인

검토 범위에 따라 다음 내용을 확인한다.

- 현재 Branch
- Git 상태
- 변경된 파일 요약
- 전체 Diff
- Stage 된 Diff
- 선택한 기준 Branch와의 Diff

다음 문제가 있는지 확인한다.

- 작업과 관련 없는 변경
- 예상하지 못한 파일 삭제
- 자동 생성 파일 또는 임시 파일
- 로컬 설정 파일 또는 Secret
- 해결되지 않은 Merge 충돌

## 3. 변경 영역 분류

변경된 내용을 해당되는 영역으로 분류한다.

- 프런트엔드
- 백엔드
- 데이터베이스 Migration
- 테스트
- 의존성
- Build 또는 인프라
- 문서

## 4. 필수 검사 실행

`AGENTS.md`와 저장소의 스크립트에 정의된 명령을 실행한다.

검사에는 다음 항목이 포함될 수 있다.

- Lint
- 타입 검사
- 단위 테스트
- 통합 테스트
- End-to-End 테스트
- Migration 검증
- 운영용 Build

각 명령에 대해 다음 내용을 기록한다.

- 실행한 정확한 명령
- 명령을 실행한 작업 폴더
- `PASS`, `FAIL`, `BLOCKED`, `NOT RUN` 중 하나의 결과
- 간단한 결과 설명

실행하지 않은 명령을 통과했다고 보고하지 않는다.

## 5. Diff 검토

다음 문제가 있는지 확인한다.

- 요청한 동작이 구현되지 않음
- 승인된 작업 범위를 벗어난 변경
- 의미 있는 테스트가 없는 동작 변경
- 테스트가 삭제되거나 약화됨
- 예외 또는 입력값 검증 실패가 숨겨짐
- 권한 관련 회귀
- API 호환성 문제
- 안전하지 않은 Migration 변경
- 정당한 이유가 없는 의존성 추가
- 코드나 로그에 포함된 Secret 또는 민감정보

세부적인 프로젝트 규칙은 이 Skill에 중복해서 작성하지 않고 `AGENTS.md`에 정의된 규칙을 적용한다.

## 6. 발견사항 분류

다음 심각도를 사용한다.

- `Blocker`: Commit 또는 Merge하면 안 되는 문제
- `High`: 실제 결함이거나 심각한 회귀일 가능성이 높은 문제
- `Medium`: 일반적으로 수정해야 하는 실제 문제
- `Low`: 작업을 막지는 않는 작은 개선사항

확인된 결함과 가능성만 있는 위험을 구분한다.

## 7. 전체 결과 판정

다음 중 하나의 결과를 반환한다.

### PASS

다음 조건을 모두 충족할 때만 사용한다.

- 모든 필수 검사가 통과했다.
- `Blocker` 또는 `High` 발견사항이 없다.
- Diff가 승인된 작업 범위와 일치한다.
- 변경된 동작에 의미 있는 테스트가 있다.

### FAIL

다음 중 하나에 해당할 때 사용한다.

- 필수 검사가 실패했다.
- `Blocker` 또는 `High` 발견사항이 있다.
- 요청한 동작이 완성되지 않았다.
- 위험한 작업 범위 밖 변경이 존재한다.

### BLOCKED

다음 중 하나에 해당할 때 사용한다.

- 필수 도구 또는 서비스를 사용할 수 없다.
- 검토 범위를 알 수 없다.
- 수용 기준이 없다.
- 필수 검증을 완료할 수 없다.

필수 검사가 실행되지 않았다면 `PASS`를 반환하지 않는다.

# 필수 최종 보고서

## 전체 결과

`PASS`, `FAIL`, `BLOCKED` 중 하나를 작성한다.

## 검토 범위

정확히 무엇을 검토했는지 작성한다.

## 변경 요약

요청된 변경과 실제 변경사항을 요약한다.

## 발견사항

각 발견사항에 다음 내용을 포함한다.

- 심각도
- 파일과 위치
- 증거
- 영향
- 권장 수정 방향

## 검증 결과

| 명령 | 작업 폴더 | 결과 | 설명 |
|---|---|---|---|

## 테스트 범위

어떤 수용 기준이 테스트되었고, 어떤 수용 기준이 테스트되지 않았는지 작성한다.

## 작업 범위 검토

작업과 관련 없는 변경이나 의심스러운 변경을 보고한다.

## 남아 있는 위험

실행하지 못한 검사, 확인되지 않은 가정, 테스트하지 못한 조건을 보고한다.

# 정확성 규칙

- 실제로 실행하지 않은 명령을 실행했다고 보고하지 않는다.
- 컴파일에 성공했다는 이유만으로 기능이 정확하다고 판단하지 않는다.
- 확인되지 않은 가설을 확정된 결함으로 보고하지 않는다.
- 작업 폴더의 파일을 수정하지 않는다.

 

사용 예시

$quality-gate

현재 Branch와 main Branch의 차이를 품질검사해라.

다음 기준을 적용해라.

- 코드는 수정하지 않는다.
- 관련 없는 변경을 찾는다.
- AGENTS.md에 정의된 검증 명령을 모두 실행한다.
- Migration과 의존성 변경을 별도로 검토한다.
- 실행하지 못한 검사는 통과로 처리하지 않는다.
- 최종 결과를 PASS, FAIL, BLOCKED 중 하나로 보고한다.

 

Codex의 /review 명령도 커밋되지 않은 변경, 특정 커밋, 기준 브랜치 대비 변경 등을 검토할 수 있다. 회사의 리뷰 기준을 code-review.md로 만들고 AGENTS.md에서 참조하도록 수정하면 리뷰 일관성이 높아진다.