NM

Codex가 오류를 보자마자 추측으로 코드를 여러 곳 수정하는 것을 막고 다음 순서로 처리하게 한다.

경로 : .agents/skills/bug-triage/SKILL.md

---
name: bug-triage
description: 오류, 테스트 실패, 비정상 동작, 프로그램 중단, 예상하지 못한 API 응답 또는 성능 저하 문제를 증거에 기반하여 분석하고 필요한 경우 최소 범위로 수정한다. 실패 경로를 추적하고, 원인 가설을 검증하며, 근본 원인을 확인하고, 회귀 테스트를 추가한다. 새로운 기능 개발이나 광범위한 리팩터링 작업에는 사용하지 않는다.
---

# 목적

추측에 따라 여러 코드를 수정하지 않고, 확인된 증거를 바탕으로 결함의 원인을 분석한다.

# 기본 행동

- 기본 동작은 문제의 원인을 분석하는 것이다.

- 사용자가 명시적으로 수정을 요청하지 않았다면 코드를 수정하지 않는다.

- 확인된 증거와 아직 검증되지 않은 가정을 명확히 구분한다.

- 문제를 재현하지 못했다면 근본 원인이 확인되었다고 주장하지 않는다.

- 여러 개의 추측성 변경보다 하나의 작고 검증 가능한 수정안을 우선한다.

# 필수 확인 자료

문제 분석을 시작하기 전에 다음 내용을 확인한다.

1. 프로젝트 루트의 `AGENTS.md`를 읽는다.

2. 문제가 발생한 모듈에 적용되는 가장 가까운 `AGENTS.md`를 읽는다.

3. 버그 신고 내용, 수용 기준, 오류 로그가 있다면 확인한다.

4. 관련 소스코드와 테스트코드를 확인한다.

5. 문제를 재현할 수 있는 명령 또는 사용자 작업 흐름을 파악한다.

# 작업 절차

## 1. 결함 내용 다시 정리

다음 내용을 정리한다.

- 원래 기대한 동작
- 실제로 발생한 동작
- 문제가 발생한 환경
- 확인 가능한 경우 문제가 발생한 버전 또는 Branch
- 문제 재현 절차
- 오류 메시지 또는 잘못된 출력 결과
- 문제 발생 빈도와 발생 조건

사용자가 신고한 실제 문제를 임의로 다른 문제로 해석하거나 바꾸지 않는다.

확인된 내용과 아직 확인되지 않은 내용을 구분해서 작성한다.

## 2. 문제 재현

가능한 가장 작고 신뢰할 수 있는 방법으로 문제를 재현한다.

다음 우선순위로 재현 방법을 선택한다.

1. 현재 실패하고 있는 기존 테스트

2. 해당 문제만 검증하는 집중된 자동 테스트

3. 로컬 환경의 API 또는 UI를 이용한 재현

4. 문제만 분리한 최소 재현 코드 또는 최소 재현 환경

재현할 때 사용한 정확한 명령이나 작업 순서와 실제 결과를 기록한다.

문제를 재현하지 못한 경우에는 다음 내용을 보고한다.

- 어떤 재현 방법을 시도했는지
- 어떤 결과가 나왔는지
- 재현에 필요한 어떤 조건이 부족한지
- 현재 확인할 수 있는 로그나 코드상의 증거
- 아직 검증되지 않은 원인 가설

재현하지 못한 상태에서는 추정한 원인을 확정된 사실로 표현하지 않는다.

## 3. 오류 발생 범위 좁히기

정상적인 값이나 동작이 어느 지점부터 잘못되기 시작하는지 확인한다.

웹 요청과 관련된 문제라면 필요한 범위에서 다음 흐름을 추적한다.

- 사용자가 화면에 입력한 값
- React의 로컬 상태
- API 요청 Payload
- 서버의 네트워크 응답
- Controller가 받은 입력값
- 입력값 검증 결과
- Application Service의 처리
- Transaction 범위
- Repository Query
- 데이터베이스 조회 또는 저장 결과
- API 응답 객체 변환
- React 화면 렌더링 결과

예를 들어 다음과 같이 추적한다.

```text
사용자 입력값은 정상
→ React State도 정상
→ API 요청 Payload도 정상
→ Controller 입력값도 정상
→ Repository Query에서 검색 조건이 누락됨
→ 잘못된 조회 결과 반환

사용 예시

원인 분석

$bug-triage

사용자 조회 화면에서 두 번째 페이지로 이동하면
검색 조건이 사라진다.

아직 코드는 수정하지 마라.

1. 재현
2. 데이터 흐름 추적
3. 원인 가설 검증
4. 근본 원인
5. 최소 수정안
6. 회귀 테스트 계획

순서로 보고해라.

수정

$bug-triage

사용자 조회 화면의 페이지 이동 시 검색 조건이 사라지는
문제를 재현하고 수정해라.

조건:
- 상태관리 라이브러리는 추가하지 않는다.
- 관련 없는 화면은 변경하지 않는다.
- 회귀 테스트를 추가한다.
- 프런트엔드 검사 명령을 실행한다.
- 확인되지 않은 원인은 사실처럼 보고하지 않는다.

PostgreSQL의 테이블, 컬럼, 제약조건, 인덱스, 데이터 보정 작업을 항상 같은 검토 절차로 수행하게 한다.

경로 : .agents/skills/postgres-migration/SKILL.md

---
name: postgres-migration
description: 저장소에서 현재 사용하고 있는 마이그레이션 도구를 이용하여 PostgreSQL 스키마 및 데이터 마이그레이션을 계획하고, 생성하거나 검토한다. 테이블, 컬럼, 제약조건, 인덱스, ENUM, 시퀀스 또는 기존 데이터 보정 작업에 사용한다. 애플리케이션 코드만 변경하는 작업이나 스키마 변경이 필요하지 않은 일반적인 SELECT 쿼리 튜닝에는 사용하지 않는다.
---

# 목적

저장소의 기존 규칙을 따르면서 PostgreSQL 마이그레이션 작업을 안전하고, 점진적이며, 일관되게 수행한다.

# 기본 행동

- 사용자가 분석이나 검토를 요청한 경우에는 파일을 수정하지 않는다.

- 사용자가 구현을 명시적으로 요청한 경우에도 파일을 수정하기 전에 현재 상태를 확인하고 작업 계획을 작성한다.

- Flyway 또는 Liquibase를 사용한다고 임의로 가정하지 않는다. 저장소에서 이미 사용하고 있는 마이그레이션 도구를 확인하여 그대로 사용한다.

- 저장소에 마이그레이션 도구가 없다면 해당 사실을 보고하고, 새로운 도구를 도입하기 전에 작업을 중단한다.

- 운영 데이터베이스에 접근하거나 운영 데이터베이스를 수정하지 않는다.

# 필수 확인 자료

변경사항을 만들기 전에 다음 내용을 확인한다.

1. 프로젝트 루트의 `AGENTS.md`를 읽는다.

2. 가장 가까운 백엔드 또는 데이터베이스 관련 `AGENTS.md`를 읽는다.

3. 저장소의 데이터베이스 및 마이그레이션 문서를 읽는다.

4. Build 설정을 확인한다.

5. 마이그레이션 설정과 최근 마이그레이션 파일을 확인한다.

6. 요청한 변경사항의 영향을 받는 Entity, Repository, Query 및 테스트를 확인한다.

# 작업 절차

## 1. 현재 상태 확인

다음 내용을 확인한다.

- 프로젝트에서 사용하는 PostgreSQL 버전
- 마이그레이션 도구와 마이그레이션 파일 경로
- 마이그레이션 파일 명명 규칙
- 현재 테이블 및 컬럼 정의
- 이미 존재하는 제약조건과 인덱스
- 영향을 받는 데이터를 읽거나 저장하는 애플리케이션 코드
- 새로운 스키마 조건을 위반할 가능성이 있는 기존 데이터
- 저장소 문서에 정의된 배포 관련 전제조건

ORM Entity 정의만 보고 현재 데이터베이스 상태를 판단하지 않는다.

스키마가 어떻게 변경되어 왔는지를 판단하는 기준 정보는 마이그레이션 이력이다.

## 2. 변경 유형 분류

요청한 작업을 다음 유형 중 하나 이상으로 분류한다.

- 새로운 구조를 추가하는 스키마 변경
- 제약조건 변경
- 인덱스 변경
- 기존 데이터 보정
- 이름 변경
- 데이터 타입 변환
- 데이터를 삭제하거나 기존 구조를 제거하는 파괴적 스키마 변경
- 호환성 또는 배포 순서와 관련된 변경

파일을 수정하기 전에 변경 유형을 먼저 보고한다.

## 3. 위험 평가

다음 위험이 있는지 확인한다.

- 데이터가 손실될 가능성
- 기존 `NULL` 값
- 기존 중복 값
- 유효하지 않은 외래키 값
- 테이블 잠금
- 오랜 시간이 걸릴 수 있는 데이터 변경 작업
- 배포 중 애플리케이션 호환성
- 롤백 또는 복구의 어려움
- 기존 Query와 인덱스에 미치는 영향

파괴적인 변경, 데이터 타입의 허용 범위를 줄이는 변경, 이름 변경 또는 컬럼 삭제의 경우에는 마이그레이션 전략이 명확해질 때까지 파일을 수정하지 않는다.

즉시 파괴적인 변경을 적용하면 호환성이 깨질 수 있는 경우에는 `확장-마이그레이션-축소` 방식의 접근을 우선한다.

1. 새로운 구조를 추가한다.

2. 기존 데이터를 변경하거나 새로운 구조에 맞게 보정한다.

3. 기존 구조와 새로운 구조를 모두 처리할 수 있는 호환 가능한 애플리케이션 코드를 배포한다.

4. 새로운 구조가 실제로 사용되고 있는지 확인한다.

5. 이후 별도의 마이그레이션에서 기존 구조를 제거한다.

## 4. 작업 계획 보고

파일을 수정하기 전에 다음 내용을 보고한다.

- 새로 추가하거나 수정할 파일
- 마이그레이션 유형
- 기존 데이터 보정 방법
- 애플리케이션 호환성에 미치는 영향
- 실행할 검증 명령
- 아직 해결되지 않은 위험

제안하는 변경사항을 사용자가 요청한 범위로 제한한다.

## 5. 마이그레이션 생성

다음 규칙을 따른다.

- 새로운 버전의 마이그레이션 파일을 생성한다.

- 이미 적용되었을 가능성이 있는 기존 마이그레이션 파일은 절대로 수정하지 않는다.

- 저장소의 기존 파일 명명 규칙과 SQL 작성 형식을 따른다.

- 제약조건과 인덱스에 명시적인 이름을 지정한다.

- 실제 데이터 규칙을 나타내는 경우에는 데이터베이스 제약조건을 추가한다.

- 어떤 Query를 지원하기 위한 것인지 확인하지 않고 인덱스를 추가하지 않는다.

- 기존 데이터에 `NULL` 값이 있을 가능성을 처리하지 않은 상태에서 `NOT NULL` 제약조건을 추가하지 않는다.

- 기존 중복 데이터를 확인하지 않은 상태에서 `UNIQUE` 제약조건을 추가하지 않는다.

- 기존 데이터를 사용자에게 알리지 않고 삭제하거나 변경하지 않는다.

- 하나의 마이그레이션에 서로 관련 없는 스키마 변경사항을 함께 넣지 않는다.

- 사용자의 명시적인 승인 없이 새로운 마이그레이션 라이브러리를 추가하지 않는다.

- 저장소의 트랜잭션 전략과 충돌하는 PostgreSQL 전용 기능을 사용할 때는 그 이유를 문서화한다.

## 6. 관련 코드 변경

승인된 작업 범위에서 반드시 필요한 경우에만 다음 항목을 변경한다.

- 영속성 매핑
- 요청 DTO 및 응답 DTO
- 입력값 검증
- Repository 및 Query
- 테스트 Fixture
- 초기 데이터 또는 Seed 데이터
- 데이터베이스 문서

요청과 관련 없는 리팩터링은 수행하지 않는다.

## 7. 검증

`AGENTS.md`에 정의된 명령을 사용한다.

해당되는 경우 최소한 다음 내용을 검증한다.

1. 비어 있는 테스트 데이터베이스에 전체 마이그레이션이 정상적으로 적용된다.

2. 저장소에 업그레이드 경로 테스트가 있다면, 이전 스키마 상태에서 새로운 마이그레이션이 정상적으로 적용된다.

3. 제약조건이 유효하지 않은 데이터를 정상적으로 거부한다.

4. 기존의 유효한 데이터를 계속 정상적으로 읽을 수 있다.

5. 보정된 데이터가 예상한 값을 가지고 있다.

6. 영향을 받는 Repository 테스트와 통합 테스트가 통과한다.

7. 백엔드 Build가 통과한다.

8. 인덱스가 의도한 Query 유형을 지원한다.

9. 기존 마이그레이션 파일이 수정되지 않았다.

검증을 수행할 수 없다면 해당 항목을 실행하지 않았다고 보고한다.

SQL 내용을 눈으로 확인한 것만으로 성공했다고 보고하지 않는다.

# 검토 모드

기존 마이그레이션을 검토할 때는 다음 절차를 따른다.

1. 파일을 수정하지 않는다.

2. 마이그레이션 파일과 관련 애플리케이션 코드를 확인한다.

3. 데이터 손실 위험과 호환성 위험을 확인한다.

4. `NULL`, 중복 데이터 및 외래키 관련 가정을 확인한다.

5. 트랜잭션과 테이블 잠금에 미치는 영향을 확인한다.

6. 테스트가 유효한 데이터와 유효하지 않은 데이터를 모두 검증하는지 확인한다.

7. 발견한 문제를 심각도에 따라 구분하여 보고한다.

# 필수 최종 보고서

## 마이그레이션 요약

어떤 스키마 또는 데이터 변경을 수행했는지 설명한다.

## 변경된 파일

변경한 모든 파일과 각 파일을 변경한 이유를 작성한다.

## 호환성

애플리케이션 및 배포 호환성에 미치는 영향을 설명한다.

## 데이터 처리

기존 데이터 검증, 데이터 보정 및 기존 데이터 보존 방법을 설명한다.

## 검증

실행한 각 명령과 결과를 작성하고, 성공·실패·실행하지 않음 중 어떤 상태인지 명시한다.

## 남아 있는 위험

아직 해결되지 않은 위험과 운영 시 고려사항을 작성한다.

# 금지 사항

- 운영 데이터베이스에 연결하지 않는다.

- 어떤 데이터베이스인지 명확하지 않은 상태에서 파괴적인 SQL을 실행하지 않는다.

- 이미 적용된 마이그레이션 파일을 수정하지 않는다.

- 마이그레이션 실패 또는 테스트 실패를 숨기지 않는다.

- 테스트를 통과시키기 위한 목적으로 데이터베이스 제약조건을 약화하지 않는다.

- 복구 방법을 실제로 검증하지 않았다면 해당 마이그레이션을 되돌릴 수 있다고 주장하지 않는다.

사용 예시

분석

$postgres-migration

user_account 테이블에 status 컬럼을 추가하려고 한다.

아직 파일을 수정하지 말고 다음만 보고해라.

1. 현재 Migration 방식
2. 영향을 받는 코드
3. 기존 데이터 위험
4. Migration 계획
5. 필요한 테스트

구현

$postgres-migration

승인된 계획에 따라 user_account.status 컬럼 추가를 구현해라.

조건:
- 기존 사용자는 ACTIVE로 보정한다.
- 적용된 Migration은 수정하지 않는다.
- 기존 Migration 명명 규칙을 따른다.
- PostgreSQL 통합 테스트를 실행한다.
- 최종 diff와 검증 결과를 보고한다.

해당 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에서 참조하도록 수정하면 리뷰 일관성이 높아진다.