OpenAI Codex use cases를 읽어도 팀 도입이 안 되는 이유——AGENTS.md부터 시작하는 3단계

OpenAI Codex use cases 팀 도입을 고려하고 있다면, 공식 카탈로그를 그대로 따라 하기 전에 알아야 할 것이 있다. use cases를 읽어도 “우리 팀에서는 어떻게 써야 하지?”에서 막히는 건 카탈로그의 구조 때문이다.

이 글에서는 Codex 공식 use cases를 그대로 따라 하는 게 아니라, 팀 업무로 번역하는 방법을 정리한다. 포인트는 3가지다. 작업 단위 정리, 저장소 규칙(AGENTS.md) 정비, 검증 루프 설계. 코딩 에이전트 도입에서 차이를 만드는 건 모델 성능이 아니라 이 3가지 준비에 있다.

OpenAI Codex use cases 팀 도입 — 카탈로그를 읽어도 진전이 없는 이유

OpenAI는 Codex 활용 사례를 공식 문서로 정비해 두었다. 카탈로그 형식으로 “이런 작업에 쓸 수 있다”는 구체적인 예시가 나열되어 있다. 자료 자체는 질이 높다.

문제는 카탈로그의 구조에 있다.

공식 use cases는 범용적인 작업 카테고리로 쓰여 있다. “테스트 생성”, “버그 수정”, “코드 리뷰”. 어느 팀에나 해당되는 것처럼 보이지만, 어느 팀의 구체적 업무에도 그대로 맞지 않는다.

예를 들어 “테스트 생성”이라 해도 우리 팀이 다루는 테스트가 단위 테스트인지, E2E 테스트인지, 특정 CI 환경에 의존하는 것인지에 따라 방법이 완전히 다르다. use cases는 “뭘 할 수 있는가”는 알려주지만, “우리 업무 어디에, 어떤 단위로 적용할 것인가”는 알려주지 않는다.

이 간극을 메우는 것이 아래에서 설명하는 ‘재매핑’ 절차다.

작업 단위 → 저장소 규칙 → 검증 루프 순으로 재매핑한다

OpenAI Codex use cases 팀 도입을 성공시키려면, 3단계를 순서대로 밟아야 한다.

스텝 1: 우리 팀의 ‘작업 단위’를 정리한다

처음에 할 일은 Codex use cases를 읽는 것이 아니다. 우리 팀이 반복하고 있는 작업을 써 내는 것이다.

• 매주 PR 작성에서 같은 패턴의 코드 변경을 반복하고 있지 않은가
• 테스트 추가 누락으로 반려가 반복되고 있지 않은가
• 문서 업데이트가 코드 변경을 따라가지 못하고 있지 않은가
• 의존 패키지 버전 확인을 수작업으로 하고 있지 않은가

이 ‘반복’ 목록이 Codex use cases와의 대응표가 된다. use cases를 위에서 아래로 읽는 게 아니라, 우리의 반복 작업에서 역으로 찾아가는 것이다.

스텝 2: AGENTS.md로 저장소 규칙을 고정한다

작업 단위가 정해지면, 다음은 저장소에 규칙을 쓴다. OpenAI 공식 best practices에서도 반복 프롬프트를 AGENTS.md로 문서화할 것을 권장하고 있다.

AGENTS.md는 코딩 에이전트에 대해 “이 저장소에서는 이렇게 해라”라는 지침서다.

AGENTS.md에 쓸 항목 예시:

# AGENTS.md

## 기본 규칙
- 테스트 없는 PR은 만들지 않는다
- 새 함수에는 반드시 JSDoc 주석을 단다
- 환경 변수는 .env.example에 추가한다

## 금지 사항
- node_modules나 dist 디렉터리 변경
- 기존 API 엔드포인트 시그니처 변경 (사전 리뷰 필수)

## 완료 기준
- CI가 통과할 것
- 타입 체크(tsc --noEmit)가 통과할 것
- 변경 대상의 테스트가 추가 또는 업데이트되어 있을 것

여기서 중요한 건 AGENTS.md가 “프롬프트 팁 모음”이 아니라는 점이다. 이건 저장소에 귀속되는 운영 규칙이며, 에이전트뿐 아니라 사람 리뷰어에게도 유효한 문서가 된다.

스텝 3: 검증 루프를 설계한다

작업 단위와 규칙이 갖춰져도, 결과를 검증하는 구조가 없으면 “돌아가는 것 같은데 품질은 모르겠다”는 상태가 된다.

OpenAI 공식 가이드가 권장하는 검증 설계 기준은 명확하다.

검증 유형	확인 대상	구체적 예시
사양 체크	에이전트가 뭘 “완료”로 보는가	AGENTS.md의 done 정의와 대조
실행 체크	실제로 코드가 돌아가는가	테스트 실행, 빌드, lint
현실 체크	결과가 사용자 기대와 맞는가	스크린샷 확인, 수동 리뷰
기록 체크	다음 세션에서 배움이 이어지는가	로그, 핸드오프 기록

4가지를 전부 하라는 말이 아니다. 작업의 위험도에 따라 강도를 조절한다. 의존 패키지 버전 업데이트라면 실행 체크만으로 충분하지만, API 시그니처 변경이라면 4가지 전부 필요하다.

AGENTS.md가 왜 그렇게까지 중요한가

코딩 에이전트 도입 글을 읽으면 프롬프트 작성법이나 모델 선정에 화제가 집중되기 쉽다. 하지만 팀에서 지속적으로 쓰려면, 개별 프롬프트보다 저장소에 정착하는 규칙이 훨씬 영향이 크다.

이유는 3가지다.

1. 프롬프트는 사라지지만 AGENTS.md는 남는다

좋은 프롬프트를 떠올려도 채팅 이력에 묻히면 다음 세션에서는 못 쓴다. AGENTS.md는 저장소에 커밋되므로, 누가 언제 에이전트를 써도 같은 규칙이 적용된다.

2. 에이전트의 “해서는 안 될 것”을 정의할 수 있다

코딩 에이전트에 뭘 할 수 있느냐보다, 뭘 해서는 안 되느냐가 팀 운영에서는 더 중요하다. “프로덕션 DB 스키마는 건들지 마라”, “이 디렉터리 파일은 변경하지 마라”. 금지 사항을 명문화하는 것만으로 사고 리스크가 대폭 줄어든다.

3. 사람의 리뷰 비용이 내려간다

AGENTS.md에 규칙이 적혀 있으면 리뷰어는 “규칙에 맞는가”만 확인하면 된다. 규칙이 없으면 에이전트 출력을 처음부터 평가해야 해서, 결국 수동 리뷰와 같은 공수가 든다.

OpenAI가 공식 문서에서 AGENTS.md를 전면에 내세우는 건 이런 운영상의 이유 때문이다. 모델 성능을 홍보하는 곳에서 일부러 “먼저 규칙을 써라”라고 말하고 있다. 이 우선순위 설정 자체가 코딩 에이전트의 실용 단계를 보여준다.

Codex와 Claude Code를 ‘운영 표면’으로 비교한다

Codex와 Claude Code는 둘 다 코딩 에이전트로 자주 거론된다. 하지만 “어느 모델이 더 똑똑한가”로 비교해도 팀 도입의 판단 재료가 되지 않는다.

비교해야 하는 건 운영 표면——즉, 팀이 일상적으로 접하는 인터페이스, 규칙 문서, 가시화 구조다.

비교 축	OpenAI Codex	Claude Code
공식 문서 중심	use cases 카탈로그 + best practices	로컬 하네스 + hooks/skills
규칙 문서 단위	AGENTS.md (저장소 단위)	CLAUDE.md + Skills + Hooks (프로젝트+글로벌)
검증 루프 설계	테스트·스크린샷·diff 확인 권장	테스트+스크린샷+MCP 연동으로 자동화
작업 가시화	태스크 분해·진행을 에이전트 측에서 관리	Dashboard 확장, 세션 로그, 토큰 추적
외부 서비스 연동	API를 통한 통합	MCP(Model Context Protocol)로 50+ 서비스 네이티브 연동
도입 시 먼저 요구되는 것	“작업을 use case로 분류해라”	“하네스(CLAUDE.md, hooks, skills)를 정비해라”

이 표에서 보이는 건 어느 쪽이 우수하다는 게 아니라, 입구가 다르다는 것이다.

Codex는 “뭘 할 것인가(use case)”에서 시작한다. 팀 업무를 카탈로그에 대조하고, 맞는 것부터 시도한다.

Claude Code는 “어떻게 돌릴 것인가(harness)”에서 시작한다. 로컬 환경에 규칙 문서를 놓고, hooks(이벤트 구동 자동 실행)와 skills(커스텀 명령)를 쌓아 올린다.

어느 접근이든 최종적으로 도달하는 곳은 같다. “저장소에 규칙을 쓰고, 반복 작업을 자동화하고, 검증 루프로 품질을 담보한다.” 다른 건 거기에 이르는 순서와 도중에 만지는 도구의 입자도뿐이다.

어떤 팀에 맞는가, 어떤 팀에는 아직 이른가

도입 효과가 높은 팀

• 반복 패턴이 명확한 팀: 매주 같은 종류의 PR, 같은 포맷의 테스트 추가, 정기적인 버전 업데이트 등 패턴화된 작업이 많다
• 저장소 규칙이 이미 어느 정도 문서화된 팀: 코딩 규약, 리뷰 기준, CI 설정이 정리되어 있다. AGENTS.md로의 전기(轉記)가 바로 가능하다
• 리뷰 병목이 있는 팀: 리뷰어의 시간이 부족해 PR이 체류하고 있다. 에이전트에 1차 체크를 맡겨 사람의 리뷰를 고부가가치 판단에 집중시킬 수 있다

아직 이른 팀

• 저장소에 규칙이 전혀 없는 팀: AGENTS.md에 뭘 쓸지 정할 수 없는 상태에서 에이전트를 넣어도 출력 품질 기준이 없어 평가조차 못 한다. 먼저 규칙 정비가 선행되어야 한다
• 작업 단위가 매번 다른 팀: 탐색적 개발이나 프로토타이핑 중심으로 반복 패턴이 없다. 에이전트는 정형 작업 자동화가 장점이고, 미정의 작업에는 약하다
• 에이전트 출력을 확인하는 구조가 없는 팀: 테스트도 CI도 없이 수동 확인에 의존한다. 에이전트가 생성한 코드를 검증할 수단이 없으면, 도입은 기술 부채를 가속시킬 뿐이다

오늘부터 할 수 있는 가장 작은 실행 단계

여기까지 읽고 “해 보고 싶다”고 생각했다면, 오늘 할 일은 딱 하나다.

내 저장소에 AGENTS.md 초안을 쓴다.

완벽할 필요 없다. 아래 템플릿을 복사해서 빈칸을 내 프로젝트에 맞게 채우면 된다.

# AGENTS.md

## 이 저장소에 대해
- [프로젝트 한 줄 설명]
- 주요 기술 스택: [언어, 프레임워크, DB 등]

## 기본 규칙
- [ ] 테스트 없는 변경 금지
- [ ] [팀 고유 규칙 1]
- [ ] [팀 고유 규칙 2]

## 금지 사항
- [건드리면 안 되는 디렉터리나 파일]
- [변경에 사전 승인이 필요한 영역]

## 완료 기준
- [ ] CI가 통과할 것
- [ ] [팀 고유 완료 기준]

소요 시간은 15분 정도. 이것만으로 코딩 에이전트 도입의 ‘첫 번째 벽’——규칙이 아무것도 없는 상태——을 넘을 수 있다.

다음 단계는 이 AGENTS.md를 써서 Codex나 Claude Code로 작은 태스크(테스트 추가나 타입 정의 수정 등)를 하나 실행해 보는 것이다. 결과가 기대대로면 규칙을 추가하고, 기대와 다르면 규칙을 수정한다. 이 사이클이 돌기 시작하면 use cases 카탈로그의 읽는 법도 달라진다.

관련 기사: 하네스 엔지니어링 완전 가이드 | 에이전틱 엔지니어링 완전 가이드

OpenAI Codex use cases 팀 도입 자주 묻는 질문

Q. AGENTS.md는 Codex 전용 파일인가요?

A. 아닙니다. AGENTS.md는 저장소에 놓는 규칙 문서이며 특정 도구에 의존하지 않습니다. OpenAI 공식 문서에서 권장하는 명칭이지만, Claude Code에서는 CLAUDE.md가 같은 역할을 합니다. 둘 다 “저장소 고유 규칙을 에이전트에 전달한다”는 목적은 동일합니다.

Q. Codex와 Claude Code, 어느 쪽을 먼저 써 봐야 하나요?

A. 팀 상황에 따릅니다. 공식 use cases 카탈로그에 맞춰 “뭘 할 것인가”부터 정하고 싶으면 Codex. 로컬 환경에서 파일 조작이나 MCP 연동 중심으로 “어떻게 돌릴 것인가”부터 시작하고 싶으면 Claude Code. 둘 다 AGENTS.md(또는 CLAUDE.md) 정비가 전제인 점은 공통입니다.

Q. use cases 카탈로그를 읽는 의미가 없나요?

A. 읽는 의미는 있습니다. 다만 “이대로 따라 하자”가 아니라 “우리 팀에서 어떤 작업이 이 패턴에 해당하는가”의 시선으로 읽으면 효과적입니다. 카탈로그는 답이 아니라, 자기 작업을 분류하기 위한 참조 프레임으로 쓰는 게 올바른 읽는 법입니다.

Q. AGENTS.md는 몇 줄 정도가 적절한가요?

A. 50~100줄이 기준입니다. 너무 길면 에이전트도 사람도 안 읽습니다. 기본 규칙·금지 사항·완료 기준 3섹션으로 좁히고, 특정 태스크 고유 규칙은 별도 파일로 분리해 링크하는 편이 운영하기 쉽습니다.

Q. 소규모 팀(2~3명)에서도 도입 의미가 있나요?

A. 있습니다. 소규모 팀이야말로 한 명이 리뷰어와 코더를 겸하는 경우가 많아, 에이전트에 1차 체크를 맡기는 효과가 큽니다. 다만 AGENTS.md 정비에 시간을 너무 쓰면 본말전도이므로, 최소한의 규칙부터 시작해 점진적으로 추가하는 게 현실적입니다.

회원 가입(무료)으로 매주 월요일 뉴스레터 받기 →

이 글을 쓴 사람: VibeCoding Tailor(@shuntailor). 코딩 에이전트를 활용한 블로그 운영·팀 업무 자동화를 일상적으로 실천. OpenAI Codex와 Claude Code 양쪽을 업무에서 운용하며, AGENTS.md·publish gate·검증 루프 설계를 자사 워크플로에 도입하고 있다.

소스 리스트:

• OpenAI Developers — Codex use cases (공식 문서)
• OpenAI Developers — Codex best practices (공식 가이드)
• Anthropic — Claude Code 공식 문서
• Mitchell Hashimoto — AI 도입 여정 (하네스 엔지니어링 사례)
• VS Code Marketplace — Claude Code Dashboard (운영 가시화 도구)

최종 업데이트: 2026년 4월 10일