NM

기본 Skill 5 - bug-triage

NM_o — Tue, 1 Sep 2026 14:05:10 +0900

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

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

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

기본 Skill 4 - postgres-migration

NM_o — Tue, 1 Sep 2026 14:03:51 +0900

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 3 - quality-gate

NM_o — Tue, 1 Sep 2026 13:54:20 +0900

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

기본 Skill 2 - react-standard-screen

NM_o — Tue, 1 Sep 2026 13:50:42 +0900

사용자가 중요하게 생각하는 표준화된 레이아웃은 프롬프트 한 번으로 유지되지 않는다. 기존 컴포넌트와 레이아웃 규칙을 강제로 읽고 재사용하게 만드는 Skill이다.

경로 : .agents/skills/react-standard-screen/SKILL.md

---
name: react-standard-screen
description: 저장소에 이미 존재하는 표준 레이아웃, 디자인 토큰, 공통 컴포넌트, 훅, API 사용 패턴, 테스트 방식을 사용하여 React TypeScript 화면을 새로 만들거나 기존 화면을 표준화한다. 새로운 화면을 만들거나 기존 화면을 표준화할 때 사용한다. 백엔드만 변경하는 작업이나 데이터베이스만 변경하는 작업에는 사용하지 않는다.
---

# 목적

일회성 레이아웃이나 일관되지 않은 UI 패턴을 새로 만들지 않고 React 화면을 구현한다.

# 필수 확인 자료

코드를 수정하기 전에 다음 내용을 확인한다.

1. 프로젝트 루트의 `AGENTS.md`
2. `frontend/AGENTS.md`
3. `docs/frontend/layout-rules.md`
4. `docs/frontend/component-catalog.md`
5. 이번에 만들거나 수정할 화면과 가장 유사한 기존 기준 화면
6. 이번 요구사항을 처리하는 데 사용할 수 있는 기존 공통 컴포넌트

# 작업 절차

1. 구현하려는 화면의 유형을 확인하고, 가장 유사한 기존 기준 화면을 찾는다.

2. 이번 화면에서 재사용할 기존 공통 컴포넌트 목록을 작성한다.

3. 다음 화면 상태 중 빠진 것이 있는지 확인한다.

   - 최초 상태
   - 로딩 상태
   - 데이터가 없는 상태
   - 정상 처리 상태
   - 입력값 검증 오류 상태
   - 서버 오류 상태
   - 비활성화 상태
   - 읽기 전용 상태
   - 권한 부족 상태가 필요한 경우 해당 상태

4. 코드를 수정하기 전에 짧은 구현 계획을 제시한다.

5. 요구사항을 충족하는 데 필요한 가장 작은 범위만 변경한다.

6. 다음 조건을 모두 충족하지 않는다면 새로운 공통 컴포넌트를 만들지 않는다.

   - 기존 컴포넌트만으로 요구사항을 처리할 수 없다.
   - 새 컴포넌트가 다른 화면에서도 재사용될 가능성이 있다.
   - 새 컴포넌트의 사용 방법과 인터페이스가 문서화된다.
   - 새 컴포넌트의 Storybook Story와 테스트가 추가된다.

7. 프런트엔드 검증 명령을 실행한다.

8. 최종 Git Diff를 검토하여 다음 문제가 없는지 확인한다.

   - 기존 표준과 다른 스타일
   - 기존 공통 컴포넌트와 중복되는 컴포넌트
   - 요청 범위를 벗어난 변경

# UI 규칙

- 기존 디자인 토큰을 사용한다.

- 색상값을 직접 하드코딩하지 않는다.

- 프로젝트에 정의되지 않은 임의의 간격값을 사용하지 않는다.

- 저장소에서 명시적으로 허용하지 않는다면 인라인 스타일을 사용하지 않는다.

- 사용할 수 있는 공통 컴포넌트가 이미 존재하는 경우 화면 내부에 별도의 버튼, 모달, 테이블, 입력창 또는 상태 표시 컴포넌트를 만들지 않는다.

- 공통 레이아웃 컴포넌트를 우회하여 화면을 구성하지 않는다.

- 키보드로 화면을 조작할 수 있는 기능과 눈에 보이는 포커스 표시를 유지한다.

- 라벨과 입력값 검증 메시지는 기존 화면과 일관되게 작성한다.

- TypeScript의 엄격한 타입 검사를 유지한다.

- 타입 오류를 없애기 위한 목적으로 `any`를 사용하지 않는다.

# 검증

`AGENTS.md`에 정의된 검증 명령을 실행한다.

최소한 다음 항목을 검증한다.

- Lint 검사
- TypeScript 타입 검사
- 컴포넌트 테스트
- 관련 Storybook Story
- 운영용 Production Build

# 필수 최종 보고

작업이 끝나면 다음 내용을 보고한다.

1. 기준으로 사용한 기존 화면
2. 재사용한 공통 컴포넌트
3. 새로 만든 컴포넌트와 새로 만든 이유
4. 변경한 파일
5. 실행한 테스트와 명령
6. 기준 화면과 비교하여 아직 남아 있는 시각적 차이 또는 동작 차이

사용 예시

$react-standard-screen

사용자 조회 화면을 구현해라.

요구사항:
- 사용자명과 부서로 검색할 수 있어야 한다.
- 검색 결과를 테이블로 표시한다.
- 검색 결과가 없으면 안내 메시지를 표시한다.
- 조회 중에는 로딩 상태를 표시한다.
- 서버 오류가 발생하면 오류 메시지를 표시한다.

작업 규칙:
- 기존 표준 검색 화면을 기준으로 사용한다.
- 기존 공통 검색 패널과 데이터 테이블을 재사용한다.
- 새로운 스타일을 임의로 만들지 않는다.
- 코드를 수정하기 전에 기준 화면과 재사용할 컴포넌트를 보고한다.
- 관련 테스트와 프런트엔드 검증 명령을 실행한다.

이런 Skill이 있어야 Codex가 화면마다 새로운 버튼, 입력창, 간격, 모달을 마음대로 만드는 문제를 줄일 수 있다.

기본 Skill 1 - feature-clarifier

NM_o — Tue, 1 Sep 2026 13:49:08 +0900

해당 Skill은 사용자의 막연한 요청을 바로 코딩하지 않고 개발 가능한 작업으로 변환합니다.

경로 : .agents/skills/feature-clarifier/SKILL.md

---
name: feature-clarifier
description: 막연하거나 범위가 불분명한 기능 요청, 변경 요청, 버그 요청을 실제로 구현할 수 있는 작은 작업으로 구체화한다. 작업 범위, 제외 범위, 제약조건, 완료 조건, 영향받는 영역, 위험요소, 테스트 계획을 정리한다. 요청이 광범위하거나 모호하거나 여러 파일에 영향을 줄 가능성이 있을 때 코딩 전에 사용한다. 이 Skill을 사용하는 동안에는 코드를 수정하지 않는다.
---

# 목적

사용자의 비공식적이거나 막연한 요청을 검토 가능하고 테스트 가능한 개발 작업으로 변환한다.

# 필수 행동 규칙

1. 코드를 수정하지 않는다.

2. 프로젝트의 `AGENTS.md`와 요청에 가장 가까운 관련 문서를 읽는다.

3. 요청과 관련된 기존 코드를 확인하고 현재 시스템이 어떻게 동작하는지 파악한다.

4. 코드와 문서에서 확인된 사실과 아직 확인되지 않은 추측을 구분한다.

5. 구현 방식이나 작업 범위를 크게 바꿀 수 있는 누락된 정보가 있는지 확인한다.

6. 불필요하게 넓은 작업 범위나 대규모 재작성 계획이 포함되어 있다면 이를 지적한다.

7. 하나의 작업으로 독립적으로 개발하고 검증할 수 있는 가장 작은 변경을 우선한다.

8. 아래에 정의된 출력 형식에 맞춰 결과를 작성한다.

# 필수 출력 형식

## 목표

이번 작업을 통해 정확히 어떤 동작이 변경되어야 하는지 설명한다.

## 현재 동작

확인한 코드와 문서를 근거로 현재 시스템이 어떻게 동작하는지 설명한다.

코드를 확인하지 못한 내용은 현재 동작으로 단정하지 않는다.

## 작업 범위

이번 작업에 반드시 포함해야 하는 기능과 동작만 작성한다.

## 작업 제외 범위

요청과 관련은 있지만 이번 작업에는 포함하지 않아야 하는 기능과 변경사항을 작성한다.

범위가 불필요하게 커지는 것을 방지하기 위해 명확하게 구분한다.

## 관련 파일 및 모듈

변경 가능성이 있는 다음 항목을 정리한다.

- 파일
- 패키지
- React 컴포넌트
- Spring Boot 클래스
- API
- 데이터베이스 Migration
- 테스트
- 설정 파일
- 관련 문서

아직 확정되지 않은 파일은 변경 대상이라고 단정하지 말고 예상 대상이라고 표시한다.

## 제약조건

작업 중 반드시 지켜야 하는 제약조건을 작성한다.

필요에 따라 다음 내용을 포함한다.

- 기존 아키텍처
- 기존 코딩 패턴
- 하위 호환성
- UI 표준
- 보안과 권한
- 성능
- 외부 연계
- 데이터베이스
- 사용 가능한 의존성
- 변경하면 안 되는 영역

## 가정

아직 코드, 문서 또는 사용자 답변으로 확인되지 않았지만 작업 계획을 세우기 위해 임시로 가정한 내용을 작성한다.

가정을 확인된 사실처럼 표현하지 않는다.

## 확인 질문

답변에 따라 구현 방식, 데이터 구조, 권한, API 계약 또는 작업 범위가 실제로 달라지는 질문만 작성한다.

사소하거나 코드 확인으로 해결할 수 있는 질문은 사용자에게 묻지 않는다.

질문이 없어도 작업을 안전하게 구체화할 수 있다면 질문 없음이라고 작성한다.

## 완료 조건

구현 완료 여부를 사람이 명확하게 판단할 수 있는 조건을 작성한다.

각 조건은 가능하면 다음과 같이 통과 또는 실패를 판정할 수 있어야 한다.

- 사용자가 수행할 수 있는 동작
- API 응답
- 화면 상태
- 오류 처리
- 권한 처리
- 데이터 저장 결과
- 테스트 결과

“정상적으로 동작한다”처럼 검증 기준이 불분명한 표현만 사용하지 않는다.

## 테스트 계획

이번 변경을 검증하기 위해 필요한 테스트를 작성한다.

해당되는 경우 다음 테스트를 포함한다.

- 단위 테스트
- React 컴포넌트 테스트
- Spring Boot API 테스트
- 서비스 테스트
- PostgreSQL 통합 테스트
- 권한 테스트
- 회귀 테스트
- 브라우저 E2E 테스트
- 수동 확인 항목

정상 상황뿐 아니라 오류와 예외 상황도 포함한다.

## 위험요소

이번 작업으로 발생할 수 있는 다음 위험을 작성한다.

- 기존 기능의 회귀
- API 호환성 문제
- 데이터 손상 또는 유실
- 권한 누락
- 성능 저하
- 동시성 문제
- 테스트되지 않은 조건
- 현재 정보만으로 확인할 수 없는 부분

확인된 문제와 가능성이 있는 위험을 구분한다.

## 제안 작업 단계

작업을 작고 검토 가능한 순서로 나눈다.

각 단계는 가능하면 다음 조건을 만족해야 한다.

- 하나의 명확한 목적이 있다.
- 변경 범위가 작다.
- 독립적으로 검증할 수 있다.
- 실패했을 때 쉽게 되돌릴 수 있다.
- 앞 단계와 뒤 단계의 의존관계가 명확하다.

# 중단 조건

작업 정의서와 구현 계획을 작성한 후 작업을 중단한다.

사용자가 계획을 명시적으로 승인하기 전에는 다음 작업을 수행하지 않는다.

- 소스코드 수정
- 파일 생성 또는 삭제
- 데이터베이스 Migration 작성
- 새로운 의존성 추가
- 테스트 코드 수정
- 설정 파일 수정
- Commit 또는 Push

최종 응답에는 아직 코드를 수정하지 않았다는 사실을 명확하게 표시한다.

사용 예시

$feature-clarifier

사용자 목록 화면에 검색 조건 저장 기능을 추가하려고 한다.

현재 저장소를 확인하고 다음 작업을 수행해라.

- 아직 코드는 수정하지 않는다.
- 현재 검색 조건이 어디에서 관리되는지 확인한다.
- 기존에 비슷한 기능이 있는지 찾는다.
- 이번 작업의 포함 범위와 제외 범위를 구분한다.
- 확인된 사실과 가정을 구분한다.
- 완료 조건과 테스트 계획을 작성한다.
- 작업을 작고 검토 가능한 단계로 나눈다.

이 Skill을 사용하면 '대충 알아서 만들어줘'라는 요청이 바로 수십 개 파일 수정으로 이어지는 것을 막을 수 있다.

기본 Skills 목록

NM_o — Tue, 1 Sep 2026 13:35:46 +0900

처음부터 Skill을 20개씩 만들면 오히려 Codex가 어떤 Skill을 사용해야 할지 혼란스러워진다.

Skill	목적
feature-clarifier	막연한 요구를 개발 가능한 작업으로 구체화
react-standard-screen	공통 레이아웃을 지키는 React 화면 구현
postgres-migration	DB 변경과 Migration 검토
bug-triage	오류 재현, 원인 추적, 최소 수정
quality-gate	테스트, Lint, Build, Diff 리뷰 수정

AGENTS.md 작성

NM_o — Tue, 1 Sep 2026 12:02:20 +0900

AGENTS.md는 Skill보다 먼저 만들어야 한다.

Skill은 특정 업무 절차이고, AGENTS.md는 Codex가 저장소에서 작업할 때 항상 적용받는 기본규칙이다. Codex는 작업을 시작하기 전에 AGENTS.md를 읽고, 루트에서 현재 작업 폴더까지 더 구체적인 지침을 조합한다.

AGENTS.md 예시

# Project

이 저장소는 다음으로 구성되어 있습니다.

- React + TypeScript 프론트엔드
- Spring Boot 백엔드
- PostgreSQL 인프라

변경사항은 작고, 검토하기 쉬우며, 테스트할 수 있는 단위로 작업합니다.

# Required Work Process

1. 변경사항을 제안하기 전에 관련 코드를 먼저 확인합니다.
2. 현재 동작 방식을 충분히 이해하기 전에는 파일을 수정하지 않습니다.
3. 변경 대상이 3개 파일을 초과하는 경우, 먼저 작업 계획을 제시합니다.
4. 변경 범위는 사용자가 요청한 범위로 제한합니다.
5. 동작이 변경되는 경우 관련 테스트를 추가하거나 수정합니다.
6. 구현 후 관련 검증 명령을 실행합니다.
7. 작업 완료를 보고하기 전에 최종 변경사항(diff)을 검토합니다.
8. 다음 내용을 작업 결과에 포함합니다.
   - 변경된 파일
   - 실행한 명령어
   - 테스트 결과
   - 남아 있는 위험 요소

# Git Safety

- main 브랜치에서 직접 작업하지 않습니다.
- 사용자가 커밋하지 않은 변경사항을 삭제하거나 되돌리지 않습니다.
- 강제 푸시(force push)를 하지 않습니다.
- 사용자의 명시적인 지시 없이 기존 사용자 커밋을 amend하지 않습니다.
- 자동 생성된 비밀정보, 로컬 설정 파일 또는 인증정보를 커밋하지 않습니다.

# General Coding Rules

- 새로운 패턴을 도입하기보다 기존 프로젝트의 패턴을 우선적으로 사용합니다.
- 현재 사용 중인 기술 스택만으로 해결할 수 없는 경우가 아니라면 새로운 의존성을 추가하지 않습니다.
- 새로운 의존성을 추가하기 전에 왜 필요한지 설명합니다.
- 요청과 관련 없는 리팩터링을 하지 않습니다.
- 빌드 실패나 테스트 실패를 숨기지 않습니다.
- 검증 명령이 정상적으로 통과하지 않았다면 작업이 성공했다고 보고하지 않습니다.

# Frontend

- TypeScript의 strict 모드를 사용합니다.
- 명확하게 문서화된 사유가 없는 한 `any` 타입을 사용하지 않습니다.
- 기존 레이아웃과 디자인 시스템 컴포넌트를 재사용합니다.
- 임의의 색상, 간격 또는 컴포넌트 변형을 추가하지 않습니다.
- 서버 상태와 로컬 UI 상태를 분리하여 관리합니다.
- 필요한 경우 다음 상태를 모두 고려합니다.
  - 로딩 상태
  - 데이터가 없는 상태
  - 오류 상태
  - 비활성화 상태
  - 읽기 전용 상태

# Backend

- 컨트롤러에 비즈니스 로직을 작성하지 않습니다.
- API 경계에서는 요청 DTO와 응답 DTO를 사용합니다.
- 트랜잭션 경계를 명확하게 설정합니다.
- 영속성 엔티티를 API를 통해 직접 노출하지 않습니다.
- 입력값을 검증합니다.
- 정상 처리와 실패 처리에 대한 테스트를 모두 추가합니다.

# Database

- 데이터베이스 스키마 변경은 버전이 관리되는 마이그레이션을 통해 적용합니다.
- 이미 적용된 기존 마이그레이션 파일을 수정하지 않습니다.
- 실제로 항상 지켜져야 하는 데이터 규칙이 있다면 제약조건을 추가합니다.
- 새로운 기능에서 추가된 쿼리에 필요한 인덱스를 검토합니다.

# Verification

Frontend:
- npm run lint
- npm run typecheck
- npm run test
- npm run build

Backend:
- ./gradlew test
- ./gradlew build

# Definition of Done

다음 조건을 모두 충족한 경우에만 작업이 완료된 것으로 판단합니다.

- 요청된 동작이 구현되었습니다.
- 관련 테스트가 통과했습니다.
- 린트와 타입 검사가 통과했습니다.
- 빌드가 통과했습니다.
- 최종 변경사항에 요청과 관련 없는 수정이 포함되어 있지 않습니다.
- 동작 방식이나 개발 규칙이 변경된 경우 관련 문서도 수정되었습니다.

OpenAI도 AGENTS.md를 지나치게 길게 만들기보다 실제로 반복되는 실수와 필요한 명령만 넣으라고 권장한다. 같은 문제가 두 번 발생하면 그때 규칙을 추가하는 방식이 좋다.

처음에는 30~60줄로 만들고 반복적인 실수 -> 원인 분석 -> 필요한 규칙을 추가하는 방식으로 하자

바이브코딩을 위한 Codex 환경설정

NM_o — Tue, 1 Sep 2026 11:27:39 +0900

Codex는 사용자 공통 설정과 프로젝트 설정을 구분한다.

사용자 공통 설정
~/.codex/config.toml

프로젝트 설정
project/.codex/config.toml

CLI, IDI연동, Codex 데스크톱 앱은 설정 계층을 공유한다. 여기에는 기본 모델, 승인 정책, sandbox, MCP 등을 설정할 수 있다.

approval_policy = "on-request"
sandbox_mode = "workspace-write"
model_reasoning_effort = "medium"

Windows 네이티브 환경이라면 다음 설정도 검토한다.

[windows]
sandbox = "elevated"

workspace-write는 Codex가 작업 저장소에서는 파일을 수정할 수 있지만 무제한으로 컴퓨터 전체를 변경하지 못하도록 제한한다. on-request는 추가 권한이 필요한 명령을 실행할 때 사용자 승인을 요청한다. Windows에서는 공식 문서가 elevated sandbox를 우선 권장한다.

AI 에이전트가 편하게 작업하는 것보다 잘못된 명령이 미치는 범위를 제한하는 것이 우선이기 때문에 초기에는 다음 설정을 사용하지 말아야 한다.

danger-full-access
approval_policy = "never"
무제한 네트워크 접근
운영 DB 접속 권한
관리자 계정 또는 운영 Secret 접근

바이브코딩용 프로젝트 구조

NM_o — Tue, 1 Sep 2026 11:16:52 +0900

project/
├── AGENTS.md
├── PLANS.md
├── README.md
│
├── .codex/
│   └── config.toml
│
├── .agents/
│   └── skills/
│       ├── feature-clarifier/
│       │   └── SKILL.md
│       ├── react-standard-screen/
│       │   └── SKILL.md
│       ├── spring-feature/
│       │   └── SKILL.md
│       ├── postgres-migration/
│       │   └── SKILL.md
│       ├── bug-triage/
│       │   └── SKILL.md
│       └── quality-gate/
│           └── SKILL.md
│
├── docs/
│   ├── agent/
│   │   ├── task-template.md
│   │   ├── code-review.md
│   │   └── definition-of-done.md
│   ├── architecture/
│   │   └── overview.md
│   ├── frontend/
│   │   ├── layout-rules.md
│   │   └── component-catalog.md
│   └── backend/
│       └── coding-rules.md
│
├── frontend/
│   ├── AGENTS.md
│   └── ...
│
├── backend/
│   ├── AGENTS.md
│   └── ...
│
├── infra/
│   └── docker-compose.yml
│
└── scripts/
    ├── dev-start
    ├── check-frontend
    ├── check-backend
    └── check-all

폴더	역할
최상위 AGENTS.md	프로젝트 전체 공통 규칙
frontend/AGENTS.md	React 작업 규칙
backend/AGENTS.md	Spring Boot 작업 규칙
PLANS.md	복잡한 작업 계획 작성 형식
.codex/config.toml	Codex 프로젝트 설정
.agents/skills	반복 작업 워크플로
task-template.md	Codex에 전달할 작업 요청 양식
code-review.md	AI 코드리뷰 기준
definition-of-done.md	기능 완료 판정 기준
layout-rules.md	화면 표준화 기준
scripts	빌드/테스트 명령 단순화

Skill이란 무엇인가?

NM_o — Tue, 1 Sep 2026 11:10:50 +0900

Skill은 반복 작업을 일관되게 처리하도록 만드는 재사용 가능한 작업 매뉴얼이다.

Skill은 하나의 폴더이며 필수 파일은 SKILL.md이다. 필요에 따라 스크립트, 참고 문서, 템플릿도 함께 넣을 수 있다.

my-skill/
├── SKILL.md
├── scripts/       선택 사항
├── references/    선택 사항
├── assets/        선택 사항
└── agents/
    └── openai.yaml 선택 사항

Codex는 처음부터 모든 Skill 내용을 전부 읽지 않는다. 우선 각 Skill의 name과 description을 보고 관련 Skill을 고른 뒤, 필요한 경우 전체 SKILL.md를 읽는다. 따라서 description을 구체적으로 작성하는 것이 매우 중요하다.

SKILL.md 구조는 다음과 같다.

---
name: skill-name
description: 이 Skill을 언제 사용하고 언제 사용하지 않아야 하는지 설명
---

Codex가 따라야 할 구체적인 작업 절차

Skill은 어디에 만들어야 하는가?

1. 프로젝트 전용 Skill은 저장소 안에 만들어야 한다.

project/.agents/skills/

2. 개인적으로 모든 프로젝트에서 사용해야 할 Skill은 사용자 홈 폴더에 만든다.

$HOME/.agents/skills/

Skill 실행 방법

Codex CLI 또는 IDE에서 다음과 같이 명시적으로 실행할 수 있다.

$feature-clarifier
$react-standard-screen
$quality-gate

또는 /skills 명령으로 사용할 수 있는 skilld을 확인할 수 있다.

Skill을 직접 지정하지 않아도 프롬프트 내용이 description과 일치하면 Codex가 자동으로 선택할 수 있다.하지만 초기에는 잘못된 Skill이 실행되는 것을 막기 위해 명시적으로 $skill-name을 붙이는 방식을 권장한다.

Codex에서 Skill을 만들 때는 내장 Skill Creator를 사용할 수 있다.

Skill Creator는 어떤 일을 하는 Skill인지, 언제 실행할지, 스크립트가 필요한지를 질문하며 초안을 만들어 준다.

$skill-creator