AGENTS.md 작성

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줄로 만들고 반복적인 실수 -> 원인 분석 -> 필요한 규칙을 추가하는 방식으로 하자