Codex AGENTS.md 프롬프트 분석 — 범용성과 유용성을 높이는 프로젝트 운영 규칙
AGENTS.md는 Codex에게 코드를 어떻게 작성할지보다, 프로젝트의 의사결정 경계와 완료 기준을 알려주는 운영 계약이다.
원문 이미지
작업 원칙
프로젝트 예외
1. AGENTS.md란 무엇인가
AGENTS.md는 Codex 같은 코딩 에이전트가 저장소를 탐색하고 코드를 수정할 때 읽는 프로젝트 지침 파일이다. 단순한 코딩 스타일 문서와 달리 다음을 정의한다.
- 어떤 설계를 우선하는가
- 무엇을 하지 말아야 하는가
- 기존 시스템을 어떻게 확장하는가
- 어떤 의존성과 라이브러리를 우선하는가
- 작업 완료를 무엇으로 증명하는가
- 프로젝트 고유의 예외와 금지 경로는 무엇인가
좋은 AGENTS.md는 에이전트의 자유를 없애는 문서가 아니라, 반복되는 판단 기준을 저장소 가까이에 고정하는 실행 가능한 헌장이다.
2. 기본 작업 원칙의 범용성
이미지의 첫 번째 원칙 묶음은 대부분의 소프트웨어 프로젝트에 적용할 수 있다.
검증된 패턴 우선
해결책을 처음부터 발명하기 전에 성숙한 제품·라이브러리·오픈소스 프로젝트가 같은 문제를 어떻게 해결하는지 확인하라는 원칙이다.
문제 정의
→ 기존 패턴 조사
→ 현재 프로젝트에 맞는 최소 적용
→ 근거와 트레이드오프 기록
범용성이 높은 이유는 언어나 프레임워크가 바뀌어도 유효하기 때문이다. Java/Spring, Python/FastAPI, TypeScript, Go 프로젝트 모두에서 재사용할 수 있다.
주의할 점은 기존 제품의 사용을 그대로 복사하라는 뜻이 아니라는 점이다. 라이선스, 보안, 성능, 운영 복잡도와 현재 요구사항을 확인한 뒤 채택해야 한다.
단순성 우선
현재 요구사항을 충족하는 가장 단순한 구현을 선택하라는 원칙은 에이전트의 과잉 설계를 줄인다.
- 추측성 설정값 감소
- 불필요한 추상화 감소
- 과도한 간접 계층 감소
- 테스트 범위 축소
- 운영·디버깅 비용 감소
그러나 단순성은 무조건 코드량을 줄이는 것이 아니다. 보안·재시도·멱등성·감사·복구가 필요한 시스템에서 이를 삭제하는 것은 단순화가 아니라 위험 제거의 실패다.
작동하는 수직 슬라이스 우선
최소한의 엔드투엔드 제품을 먼저 작동시킨 뒤 기능을 하나씩 올리는 원칙이다.
입력
→ 핵심 로직
→ 저장
→ 출력
→ 테스트
→ 다음 기능
이 방식은 AI 코딩 에이전트와 특히 잘 맞는다. 에이전트가 한 번에 거대한 구조를 만들도록 두는 대신, 매 단계마다 실행 가능한 결과와 검증 지점을 만든다.
모듈과 관심사 분리
모듈화는 단순히 디렉터리를 나누는 것이 아니다.
- 변경 이유가 다른 코드를 분리
- 외부 시스템을 포트와 어댑터 뒤에 격리
- 데이터 소유권을 명확히 함
- 테스트 경계를 만든다
- 팀 간 충돌 범위를 줄인다
모듈 수를 늘리는 것 자체는 목표가 아니다. 응집도와 변경 독립성이 실제로 좋아지는지 확인해야 한다.
검증된 의존성 우선
이미 설치된 의존성의 문서와 타입을 먼저 확인한 뒤 직접 구현하거나 패키지를 추가하라는 원칙은 실무적으로 매우 유용하다.
현재 의존성 확인
→ 공식 문서·타입·버전 확인
→ 기존 기능 재사용 가능성 검증
→ 추가 패키지의 비용·보안·유지보수 평가
→ 필요할 때만 추가
이 규칙은 바이브 코딩에서 흔한 “기능이 없다고 추정하고 새 패키지를 추가하는 문제”를 줄인다.
3. 가장 논쟁적인 원칙: 하위 호환성을 유지하지 말 것
이미지의 다음 문장은 강력하지만 그대로 범용화하면 위험하다.
하위 호환성을 유지하지 마세요. 호환 레이어·폴백·마이그레이션을 덧붙이는 대신 쓰이지 않는 경로를 삭제하세요.
유용한 적용 범위
다음과 같은 내부·폐기 경로에는 유용하다.
- 사용처가 없는 내부 메서드
- 더 이상 호출되지 않는 모듈
- 테스트되지 않는 낡은 어댑터
- 사용하지 않는 설정 키
- 죽은 feature flag
- 이미 교체된 내부 구현
반드시 예외를 둬야 하는 범위
다음은 영향 분석과 전환 계획 없이 깨뜨리면 안 된다.
- 외부 공개 API
- 모바일·웹 클라이언트 계약
- Kafka 이벤트 스키마
- 금융·정산·원장 데이터
- 고객 파일·저장 포맷
- 데이터베이스 마이그레이션
- 운영 자동화·GitOps 계약
- 보안·감사 로그
따라서 범용 AGENTS.md에는 다음처럼 쓰는 편이 안전하다.
- Remove obsolete internal paths instead of adding speculative compatibility layers.
- Preserve external API, event-schema, financial-data, and operational compatibility
unless impact analysis, migration steps, rollback, and consumer verification are complete.
4. 프로젝트 예외 섹션의 역할
두 번째 이미지의 프로젝트 예외는 범용 원칙을 실제 저장소에 맞게 조정하는 부분이다.
# 프로젝트 예외
- 건드리면 안 되는 경로
- 작업 완료 전 반드시 실행할 검증 명령
- 규제·보안상 반드시 지켜야 할 사항
이 섹션이 중요한 이유는 프로젝트마다 안전 기준이 다르기 때문이다.
| 프로젝트 | 예외로 고정할 내용 |
|---|---|
| 금융·정산 | 원장·정산 이력 수정/삭제 금지, 역분개 사용 |
| Kubernetes | 운영 namespace 직접 변경 금지, GitOps 경로 사용 |
| 개인정보 | 로그·트레이스 PII 마스킹 |
| SaaS API | 외부 계약·버전·deprecation 정책 |
| ML/RAG | 데이터셋·모델·프롬프트 버전과 평가 게이트 |
| 규제 시스템 | 감사로그·승인·보존·접근권한 |
즉 기본 원칙은 재사용하고, 예외 섹션에는 프로젝트의 실제 위험을 기록한다.
5. 범용 AGENTS.md 추천 구조
# AGENTS.md
## 작업 원칙
- 검증된 패턴을 조사한 뒤 최소 구현을 선택한다.
- 작동하는 엔드투엔드 결과를 유지하며 단계적으로 확장한다.
- 모듈 경계와 관심사를 분리한다.
- 기존 의존성을 먼저 조사한다.
- 내부의 obsolete path는 제거한다.
## 안전한 변경
- 외부 API·이벤트·데이터·운영 계약은 영향 분석 없이 깨뜨리지 않는다.
- 변경 전 테스트·롤백·마이그레이션 계획을 확인한다.
- Secret·개인정보·감사로그를 보호한다.
## 프로젝트 예외
- 수정 금지 경로: ...
- 완료 전 실행 명령: ...
- 규제·보안 규칙: ...
## 완료 기준
- 테스트 통과
- 정적 분석 통과
- 보안 검사 통과
- 문서·마이그레이션 갱신
- 변경 파일·검증 결과·롤백 경로 보고
6. Codex·Claude·팀 협업에서의 유용성
AGENTS.md는 Codex에만 유용한 것이 아니다. 저장소 규칙을 읽는 여러 Agent와 사람에게 공통 기준을 제공한다.
AGENTS.md
├─ Codex
├─ Claude Code
├─ CI/CD 작업
├─ 코드 리뷰어
└─ 새로운 팀원
다만 에이전트마다 지침 파일의 탐색 규칙과 우선순위가 다를 수 있다. 따라서 중요한 규칙은 각 도구의 공식 문서와 프로젝트 하네스에서 실제로 읽히는지 확인해야 한다.
7. LION 관점의 평가
이 프롬프트를 LION의 컴퓨터과학·운영 렌즈로 평가하면 다음과 같다.
| 렌즈 | 평가 |
|---|---|
| 소프트웨어공학 | 단순성·모듈화·단계적 확장 원칙이 강함 |
| 보안 | 프로젝트 예외에 Secret·PII·권한 규칙을 추가해야 함 |
| 데이터베이스 | 마이그레이션·스키마 호환성 예외가 필요함 |
| 분산시스템 | 이벤트 순서·멱등성·계약 버전 규칙이 필요함 |
| 운영체제·클라우드 | 배포·롤백·관측성·운영 명령을 명시해야 함 |
| AI·데이터 | 평가셋·프롬프트·모델 버전·비용 게이트를 추가해야 함 |
| 프로젝트관리 | 완료 기준과 담당자·검증 명령이 있으면 강해짐 |
결론
이미지의 AGENTS.md는 복잡도를 억제하고, Codex가 검증된 방식으로 작동하도록 만드는 좋은 기본 프롬프트다. 범용성이 높은 핵심은 다음 세 가지다.
- 검증된 패턴 우선
- 최소한의 작동하는 구현 우선
- 의존성·모듈·관심사 명확화
반면 “하위 호환성을 유지하지 말라”는 원칙은 그대로 사용하면 범용성과 안전성을 떨어뜨린다. 내부의 죽은 코드는 제거하되, 외부 API·이벤트·금융 데이터·운영 계약은 마이그레이션과 검증을 거쳐야 한다.
좋은 AGENTS.md는 에이전트를 무조건 보수적으로 만들거나 무조건 공격적으로 만들지 않는다. 현재 요구사항에는 단순하게, 외부 계약과 운영 자산에는 신중하게 행동하도록 경계를 나눈다.
References
이 글은 사용자가 제공한 AGENTS.md 이미지의 원칙을 대상으로 범용성과 실무 유용성을 분석한 글이다. 프로젝트별 예외·권한·규제·운영 계약은 실제 저장소에 맞게 별도로 작성해야 한다.