개인 개발 표준을 정의하는
AGENTS.md버전 관리 저장소
Codex에서 일관된 구현, 검증, 운영 관점 판단을 수행하기 위한 개발 가이드
Codex가 읽는 실행 원본은 영어
AGENTS.md이며, 한국어 참고본은docs/AGENTS.ko.md에서 확인할 수 있다.
- Codex 응답과 작업 방식에 일관된 행동 규칙 부여
- 질문 복잡도에 따른 출력 강도 자동 조절: FULL / STANDARD / BRIEF
- 응답 프로필 기반 분석 관점과 출력 강도 자동 선택
- 파일 탐색, 수정, 검증, 요약까지 이어지는 Codex 작업 루프 고정
- 원인이 불명확한 운영 장애에서 인프라 -> DB -> 트랜잭션 -> 동시성 -> 코드 순의 기본 조사 프레임 사용
| 원칙 | 설명 |
|---|---|
| 실행 우선 | 구현 요청은 제안에서 멈추지 않고 가능한 범위에서 직접 수정 |
| 구조 우선 | 코드보다 구조와 책임 경계를 먼저 확인 |
| 검증 필수 | 수정 후 가장 좁은 범위의 테스트/빌드/린트 실행 |
| 운영 기준 | TPS 200+ / 1,000만 row / 10배 스케일 전제 |
| 현실적 | placeholder 금지, 즉시 적용 가능한 코드 작성 |
| 변경 보호 | 사용자 변경사항을 되돌리지 않고 기존 스타일 존중 |
질문 맥락에서 분석 관점과 출력 강도를 자동 선택하거나 [DB], [BACKEND] 등으로 명시 지정한다. 이 표기는 별도의 에이전트에게 작업을 위임한다는 의미가 아니다.
| Agent | 관점 | 대표 상황 |
|---|---|---|
| BACKEND | 트랜잭션, 동시성, 객체 생성, 구조 | Java/Spring, API, 서비스 로직 |
| FRONTEND | 화면 책임, 상태·이벤트 흐름, 접근성, 렌더링 | Vue.js, React, JSP/JSTL 화면, 브라우저 UI |
| DB | 실행 계획, 인덱스, N+1, 비용 추정 | SQL, 조회 성능, slow query |
| INFRA | 배포, 네트워크, 캐싱, 수평 확장, SPOF | Docker, Nginx, EC2, CI/CD |
| BATCH | cursor/chunk, 트랜잭션 분리, 멱등성 | 대용량 처리, 스케줄러, 정산 |
| GENERATOR | DDL/API 스펙 기반 코드 생성 | DTO, VO, MyBatis XML, 테스트 템플릿 |
| LEGACY | 기존 구조 존중, 점진적 개선 | JSP, JSTL, Ant, eGov, WAS |
Java/Spring과 서버 로직은 [BACKEND · STANDARD], Vue.js/React/JSP 화면과 클라이언트 동작은 [FRONTEND · STANDARD]를 선택한다. 서버와 화면을 함께 변경하면 [BACKEND + FRONTEND · STANDARD]를 사용한다. JSP/JSTL이라도 화면 작업이 중심이면 FRONTEND를, Ant/eGov/WAS 등 레거시 애플리케이션 구조와 운영이 중심이면 LEGACY를 선택한다.
모든 답변 첫 줄에는 적용된 Agent와 강도를 표시한다.
[DB + BACKEND · FULL]
[BACKEND · STANDARD]
[FRONTEND · STANDARD]
[BACKEND + FRONTEND · STANDARD]
[INFRA · STANDARD]
[DEFAULT · BRIEF]
| 강도 | 적용 대상 | 포함 항목 |
|---|---|---|
| FULL | 분석, 설계, 아키텍처, 성능 튜닝 | 병목, 스케일 리스크, 장애 가능성, 개선안, 코드/DDL |
| STANDARD | 코드 리뷰, 버그 수정, 기능 구현 | 문제점, 수정 내용, 코드 예시, 검증 결과 |
| BRIEF | 문법 확인, 개념 질문, 단순 설정 | 핵심 답변만 간결하게 |
.
├── AGENTS.md # Dev OS for Codex 본체
├── docs/
│ └── AGENTS.ko.md # 한국어 참고본
├── README.md # 저장소 설명
└── skills/ # Codex 개인 Skill
├── pr-review/
├── spring-transaction-audit/
├── query-plan-review/
├── jpa-performance-review/
├── mybatis-xml-review/
├── test-generator/
├── logging-observability/
├── deploy-checklist/
└── skill-list/
필요하면 이후 standards/, templates/, prompts/, ci/를 추가한다.
| Skill | 용도 |
|---|---|
pr-review |
PR 변경점의 버그, 성능, 테스트 누락, 운영 리스크 리뷰 |
spring-transaction-audit |
Spring 트랜잭션, 락, 커넥션 점유, 동시성 점검 |
query-plan-review |
SQL 실행계획, 인덱스, 조인, 페이징 병목 분석 |
jpa-performance-review |
JPA N+1, fetch 전략, 영속성 컨텍스트 비용 점검 |
mybatis-xml-review |
MyBatis XML 동적 SQL, resultMap, count/paging 리뷰 |
test-generator |
JUnit, Mockito, Spring 통합 테스트 생성/보강 |
logging-observability |
로그 레벨, traceId/MDC, 메트릭, 장애 추적성 개선 |
deploy-checklist |
배포 전 migration, rollback, config, health check 점검 |
skill-list |
/스킬 요청 시 사용 가능한 Codex skill 목록과 로컬 설정 확인 |
codex-notes 저장소를 원본으로 두고, Codex가 읽는 위치에는 symlink를 둔다.
이렇게 하면 ~/AGENTS.md 또는 ~/.codex/AGENTS.md를 수정해도 실제로는 저장소의 AGENTS.md가 수정되어 Git 변경사항으로 추적된다.
~/AGENTS.md -> /path/to/codex-notes/AGENTS.md
~/.codex/AGENTS.md -> /path/to/codex-notes/AGENTS.md
기존 파일을 저장소 원본으로 교체하려면 아래처럼 실행한다.
ln -sf /path/to/codex-notes/AGENTS.md "$HOME/AGENTS.md"
ln -sf /path/to/codex-notes/AGENTS.md "$HOME/.codex/AGENTS.md"다른 PC에서는 저장소를 먼저 clone한 뒤 같은 방식으로 연결한다.
git clone https://github.com/Kormap/codex-notes.git /path/to/codex-notes
mkdir -p "$HOME/.codex"
ln -sf /path/to/codex-notes/AGENTS.md "$HOME/AGENTS.md"
ln -sf /path/to/codex-notes/AGENTS.md "$HOME/.codex/AGENTS.md"공통 규칙을 그대로 적용할 프로젝트 디렉터리에서 실행한다.
ln -sfn /path/to/codex-notes/AGENTS.md ./AGENTS.md이미 AGENTS.md가 일반 파일이거나 디렉터리라면 먼저 내용을 확인한 뒤 교체한다.
프로젝트별 규칙이 필요하면 symlink 대신 해당 프로젝트의 AGENTS.md를 사용한다. 더 구체적인 프로젝트 지침과 확립된 관례는 이 문서의 공통 기본값보다 우선하며, 프로젝트 파일에는 빌드·테스트 명령, 도메인 규칙, 배포 제한처럼 프로젝트 고유 정책만 둔다.
예시:
- 기본 언어, 검증 루프, 출력 형식은 유지
- 이 저장소에만 필요한 빌드/테스트 명령, 배포 금지 규칙, 도메인 용어만 추가
Codex가 개인 Skill을 자동 발견하려면 홈 디렉터리의 Codex Skill 경로 아래에 Skill 디렉터리가 있어야 한다.
이 저장소를 원본으로 유지하고 ~/.codex/skills에는 symlink를 두면, skill 수정사항을 복사 없이 즉시 반영할 수 있다.
복사본을 여러 위치에 두면 저장소 버전과 실제 Codex 사용 버전이 어긋날 수 있으므로 symlink를 기본 방식으로 사용한다.
~/.codex/skills/pr-review -> /path/to/codex-notes/skills/pr-review
ln -sfn /path/to/codex-notes/skills/pr-review "$HOME/.codex/skills/pr-review"여러 Skill을 한 번에 연결하려면 아래처럼 반복해서 연결한다.
mkdir -p "$HOME/.codex/skills"
for dir in /path/to/codex-notes/skills/*; do
name=$(basename "$dir")
ln -sfn "$dir" "$HOME/.codex/skills/$name"
done이미 같은 이름의 일반 디렉터리가 있으면 먼저 상태를 확인한 뒤 백업하거나 정리하고, symlink만 ln -sfn으로 교체한다.
Skill을 추가하거나 설명을 바꾼 뒤에는 Codex를 재시작하거나 Skill 목록을 다시 읽는 세션에서 확인한다.
반복 작업은 맥미니의 로컬 Codex 자동화를 기본 실행 경로로 둔다.
| 자동화 | 주기 | 결과 |
|---|---|---|
Weekly Query Tuning Drill |
매주 금요일 09:00 KST | Notion SQL 튜닝 최적화 DB에 문제 5개 생성 또는 로컬 리포트 생성 |
Weekly Codex Notes Review |
매주 월요일 09:00 KST | codex-notes 점검 리포트 생성 |
맥미니에서는 위 자동화를 ACTIVE로 유지한다.
맥북처럼 상시 실행하지 않는 장비에서는 같은 주기의 로컬 자동화를 PAUSED 상태로 유지한다.
Notion/GitHub 연동은 Codex 앱의 커넥터와 로컬 자동화를 통해 수행한다.
- 장기 개선 항목은
ROADMAP.md에서 관리한다.