팀과 함께 쓰는 Codex 운영법

팀에서 Codex를 쓴다는 것의 진짜 의미

혼자 Codex를 쓸 때는 조금 느슨해도 괜찮습니다. 프롬프트가 애매하면 다시 물어보면 되고, 변경이 마음에 들지 않으면 git restore로 되돌리면 됩니다. 하지만 팀 프로젝트에서는 이야기가 달라집니다. 한 사람이 Codex로 만든 코드가 다른 사람의 작업과 섞이고, PR로 올라가고, CI를 통과하고, 결국 사용자에게 배포됩니다. 이때 Codex는 더 이상 "내 옆의 편리한 자동 완성 도구"가 아니라 팀의 개발 프로세스 안에서 움직이는 작업자에 가까워집니다.

그래서 팀에서 Codex를 도입할 때 가장 먼저 정해야 할 것은 "얼마나 많은 코드를 빨리 만들 수 있는가"가 아닙니다. 먼저 정해야 하는 것은 규칙, 리뷰, 책임 경계입니다. OpenAI의 Codex 워크플로 문서도 Codex를 일회성 도우미가 아니라 명확한 맥락과 완료 기준을 가진 팀원처럼 다룰 때 가장 잘 작동한다고 설명합니다.¹ 초보 팀일수록 이 문장을 가볍게 넘기면 안 됩니다. 팀원처럼 다룬다는 말은 "믿고 다 맡긴다"가 아니라 "일을 맡기기 전에 역할과 권한과 완료 기준을 알려준다"는 뜻입니다.

팀에서 Codex를 쓰는 좋은 모습은 이런 흐름입니다. 누군가 이슈를 잘게 쪼갭니다. Codex가 그중 하나를 맡습니다. Codex는 공통 규칙을 읽고 작업합니다. 사람이 diff를 봅니다. 테스트와 CI가 확인합니다. 리뷰어가 위험한 부분을 다시 봅니다. PR 본문에는 Codex가 무엇을 바꿨고 어떤 검증을 했는지 남습니다. 이 흐름이 반복되면 Codex는 팀의 속도를 높입니다.

반대로 나쁜 모습은 이렇습니다. "로그인 개선해줘" 같은 큰 요청을 Codex에게 던집니다. Codex가 여러 파일을 마음대로 바꿉니다. 초보 팀원이 diff를 제대로 보지 않고 병합합니다. 테스트가 삭제되었는데 아무도 모릅니다. 배포 후 인증이 깨집니다. 그제야 팀은 "AI가 이상한 코드를 만들었다"고 말합니다. 하지만 실제 문제는 AI가 아니라 운영 방식입니다.

이 장에서는 개인 실습에서 익힌 Codex 사용법을 팀 운영 규칙으로 바꾸는 방법을 다룹니다. 목표는 거창한 AI 개발 조직을 만드는 것이 아닙니다. 작은 팀도 바로 적용할 수 있는 안전한 기본값을 세우는 것입니다.

첫 번째 원칙: Codex에게도 팀 규칙을 읽게 하라

팀원이 새로 합류하면 보통 README, 개발 환경 문서, 코드 스타일, PR 규칙을 읽습니다. Codex에게도 같은 일이 필요합니다. 그 역할을 하는 핵심 파일이 AGENTS.md입니다. README.md가 사람에게 프로젝트를 설명한다면, AGENTS.md는 Codex에게 "이 저장소에서 일하는 방법"을 알려주는 문서입니다.

팀에서 사용하는 AGENTS.md는 저장소 루트에 두고 Git에 커밋하는 것이 좋습니다. 개인 취향은 개인 설정에 두고, 팀 전체가 따라야 하는 규칙만 저장소의 AGENTS.md에 넣습니다. Codex의 모범 사례 문서에서는 AGENTS.md에 프로젝트 구조, 실행 명령, 빌드·테스트·린트 명령, 작업 규칙, 완료 기준 같은 반복 지침을 담도록 권장합니다.²

초보 팀이라면 처음부터 완벽한 문서를 만들려고 하지 않아도 됩니다. 중요한 것은 짧고 명확해야 한다는 점입니다. "좋은 코드를 작성하라"는 규칙은 거의 도움이 되지 않습니다. 대신 "API 응답 형식을 바꾸지 말라", "인증 관련 변경 후에는 npm run test:auth를 실행하라", "프로덕션 비밀값 파일을 읽거나 수정하지 말라"처럼 행동으로 옮길 수 있는 문장이 좋습니다.

다음은 팀 프로젝트에서 바로 시작할 수 있는 AGENTS.md 예시입니다.

# AGENTS.md

## Project overview
이 저장소는 Next.js 기반 미니 SaaS 앱이다.
사용자는 로그인 후 프로젝트와 메모를 만들 수 있다.

## Repository structure
- `src/app/`: 라우트와 페이지
- `src/components/`: 재사용 UI 컴포넌트
- `src/lib/`: 인증, DB, 유틸 함수
- `src/server/`: 서버 액션과 API 로직
- `tests/`: 단위 테스트와 통합 테스트

## Working rules
- 한 작업에서 하나의 명확한 변경만 수행한다.
- 요청받지 않은 대규모 리팩터링을 하지 않는다.
- public API 응답 형식을 바꾸려면 먼저 사용자에게 확인한다.
- 인증, 결제, 권한, DB 마이그레이션 코드는 반드시 사람 리뷰가 필요하다.
- `.env`, `.env.local`, 비밀값 파일을 읽거나 출력하지 않는다.

## Coding conventions
- TypeScript에서는 `any`를 새로 추가하지 않는다.
- 서버 입력값 검증에는 `zod`를 사용한다.
- 에러 응답은 `{ error: string }` 형식을 유지한다.
- UI 컴포넌트는 기존 `Button`, `Card`, `Input` 컴포넌트를 우선 사용한다.

## Verification
- 일반 변경 후: `npm run lint`와 `npm test`를 실행한다.
- 프론트엔드 변경 후: `npm run build`를 실행한다.
- 인증 변경 후: `npm run test:auth`를 반드시 실행한다.
- 실행하지 못한 검증이 있으면 이유를 최종 보고에 적는다.

## Definition of Done
작업 완료 보고에는 다음을 포함한다.
- 변경 요약
- 변경한 파일 목록
- 실행한 테스트와 결과
- 실행하지 못한 검증과 이유
- 남은 위험 또는 후속 작업

여기서 핵심은 "완료 정의", 즉 Definition of Done입니다. Codex에게 "수정해줘"라고만 말하면 수정 자체가 목표가 됩니다. 하지만 팀에서는 수정 후 검증, 보고, 리뷰 가능성이 모두 포함되어야 합니다. 완료 정의를 AGENTS.md에 넣어두면 매번 프롬프트에 길게 쓰지 않아도 Codex가 같은 기준을 따르게 됩니다.

팀이 커지면 루트 AGENTS.md 하나만으로 부족할 수 있습니다. 예를 들어 src/payments/ 아래에는 결제 관련 규칙이 따로 필요할 수 있습니다. 이때는 하위 디렉터리에 별도의 AGENTS.md를 두어 더 구체적인 규칙을 추가합니다. 중요한 점은 규칙을 많이 쓰는 것이 아니라, Codex가 반복해서 실수한 부분을 하나씩 문서화하는 것입니다. Codex가 같은 실수를 두 번 했다면 그 실수는 프롬프트가 아니라 팀 규칙으로 승격할 후보입니다.

설정도 팀의 일부다: config.toml과 권한 표준

AGENTS.md가 "어떻게 코드를 작성할지"를 알려준다면, 설정 파일은 "어떤 환경과 권한으로 일할지"를 정합니다. 팀 프로젝트에서는 개인마다 Codex 설정이 제각각이면 결과도 흔들립니다. 한 사람은 네트워크 접근을 넓게 열어두고, 다른 사람은 읽기 전용으로만 쓰고, 또 다른 사람은 MCP 도구를 마음대로 추가한다면 같은 이슈를 맡겨도 결과가 달라질 수 있습니다.

따라서 팀은 저장소 단위의 기본 설정을 정해야 합니다. 개인 설정은 ~/.codex/config.toml에 둘 수 있지만, 팀 표준은 저장소 안의 .codex/config.toml 또는 팀 문서에 관리하는 편이 좋습니다. 설정에는 모델 선택 기준, 승인 정책, 샌드박스 모드, MCP 서버, 플러그인 allowlist 같은 항목이 들어갑니다.

예시는 다음과 같습니다.

# .codex/config.toml 예시

[profile.default]
reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[profile.review]
reasoning_effort = "high"
approval_policy = "never"
sandbox_mode = "read-only"

[profile.safe-edit]
reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[network]
default_access = "deny"
allowed_domains = [
  "registry.npmjs.org",
  "api.github.com"
]

[mcp]
allowed_servers = [
  "github",
  "linear",
  "figma-readonly",
  "playwright-local"
]

이 예시는 실제 팀 규칙을 설명하기 위한 형태입니다. 프로젝트와 Codex 버전에 따라 지원되는 키 이름이나 위치는 달라질 수 있으므로, 팀에서는 공식 설정 문서를 확인한 뒤 현재 환경에 맞게 조정해야 합니다. 중요한 것은 설정의 철학입니다. 기본은 좁게, 필요할 때만 넓게입니다.

특히 MCP와 플러그인은 편리하지만 위험 면도 있습니다. GitHub 이슈를 읽고, Figma 디자인을 참고하고, Linear 티켓을 가져오는 것은 생산성을 높입니다. 하지만 연결된 도구가 많아질수록 Codex가 볼 수 있는 정보와 실행할 수 있는 행동도 늘어납니다. OpenAI의 모범 사례도 MCP를 모든 도구에 한 번에 연결하기보다, 실제로 반복되는 수동 작업을 줄여주는 고가치 통합부터 좁게 시작하라고 권장합니다.²

팀의 allowlist는 다음처럼 단순하게 시작하면 됩니다.

# Codex tool allowlist

## 허용
- GitHub MCP: 이슈, PR, 체크 상태 읽기
- Figma MCP: 디자인 파일 읽기 전용
- Playwright MCP: 로컬 앱 브라우저 검증
- Linear MCP: 이슈 내용 읽기

## 승인 필요
- GitHub에 댓글 작성
- PR 생성
- 의존성 설치
- 외부 네트워크 접근
- 대량 파일 수정

## 금지
- 프로덕션 DB 접속
- 비밀값 읽기 또는 출력
- 배포 실행
- 결제 설정 변경
- main 브랜치 직접 푸시

Codex를 안전하게 쓰는 팀은 "무엇을 할 수 있는가"보다 "무엇은 아직 하면 안 되는가"를 먼저 정합니다. OpenAI가 설명한 Codex 안전 운영 원칙에서도 샌드박싱, 사람 승인, 네트워크 정책, 상세한 텔레메트리 같은 다층 방어가 중요하게 다뤄집니다.³

팀 이슈는 Codex가 처리하기 좋은 단위로 쪼갠다

Codex에게 일을 잘 맡기는 팀은 이슈를 잘 씁니다. 반대로 이슈가 엉성하면 Codex도 엉성하게 일합니다. "대시보드 개선"은 너무 큽니다. "대시보드의 빈 상태 화면에 안내 문구와 CTA 버튼을 추가하고, 기존 카드 레이아웃은 바꾸지 않는다"는 Codex가 처리하기 좋은 작업입니다.

팀 이슈를 Codex 친화적으로 쪼갤 때는 한 번에 하나의 명확한 변경만 담아야 합니다. 재현 가능한 입력, 관련 파일, 로그, 문서 링크, acceptance criteria, 반드시 통과해야 할 테스트가 들어가면 좋습니다. 이렇게 작성된 이슈는 IDE, CLI, Codex Cloud, Codex App 어디에서 실행해도 비슷한 결과를 기대할 수 있습니다.

다음은 나쁜 이슈와 좋은 이슈의 차이입니다.

나쁜 이슈:

대시보드 좀 보기 좋게 고쳐주세요.

좋은 이슈:

## Goal
`/dashboard`에서 프로젝트가 0개일 때 빈 화면 안내를 추가한다.

## Context
현재 `src/app/dashboard/page.tsx`는 프로젝트가 없으면 카드 영역만 비어 보인다.
기존 UI 컴포넌트는 `src/components/ui/empty-state.tsx` 패턴을 참고한다.

## Scope
- `/dashboard` 빈 상태 UI 추가
- "첫 프로젝트 만들기" 버튼 추가
- 버튼 클릭 시 `/projects/new`로 이동

## Constraints
- 프로젝트 목록 카드 레이아웃은 변경하지 않는다.
- 새 의존성을 추가하지 않는다.
- 인증 로직은 수정하지 않는다.

## Acceptance criteria
- 프로젝트가 0개이면 안내 문구와 CTA 버튼이 보인다.
- 프로젝트가 1개 이상이면 기존 목록이 그대로 보인다.
- 모바일 375px 폭에서도 버튼이 화면 밖으로 넘치지 않는다.

## Verification
- `npm run lint`
- `npm run build`
- 가능하면 `/dashboard` 빈 상태를 브라우저에서 확인

이슈가 이렇게 쓰여 있으면 Codex는 추측을 덜 합니다. 작업 범위가 좁고, 건드리지 말아야 할 영역이 분명하고, 완료 기준이 검증 가능합니다. 초보 팀원도 리뷰할 때 "Codex가 이슈의 acceptance criteria를 만족했는가?"를 기준으로 볼 수 있습니다.

실무에서는 이슈 템플릿을 만들어두는 것이 좋습니다.

## Goal
무엇을 바꾸려는가?

## Why
왜 필요한가? 사용자 문제나 버그 배경은 무엇인가?

## Context
관련 파일, 로그, 스크린샷, 문서, 이전 PR 링크

## Scope
이번 작업에 포함되는 것

## Out of scope
이번 작업에서 하지 않을 것

## Constraints
유지해야 할 API, 디자인, 보안, 성능 조건

## Acceptance criteria
완료되었다고 판단할 수 있는 구체적 조건

## Required verification
반드시 통과해야 할 테스트, 린트, 빌드, 브라우저 확인

## Human review focus
사람 리뷰어가 특히 봐야 할 부분

여기서 Out of scope는 생각보다 중요합니다. Codex는 친절해서 종종 "이왕이면" 주변 코드까지 정리하려고 합니다. 하지만 팀 프로젝트에서 이왕이면은 위험할 수 있습니다. 작은 이슈는 작게 끝나야 리뷰가 쉽고 병합도 안전합니다.

위임부터 병합까지: 팀 표준 워크플로

이제 Codex에게 작업을 맡긴 뒤 PR까지 가는 팀 표준 흐름을 정해봅시다. 이 흐름은 App, CLI, IDE, Cloud 어디에서 작업하든 유지되어야 합니다. 도구 화면은 달라도 팀의 체크포인트는 같아야 합니다.

기본 워크플로는 다음과 같습니다.

1. 이슈를 Codex 친화적 단위로 정리한다.

2. 브랜치 또는 worktree를 만든다.

3. Codex에게 작업을 맡긴다.

4. Codex 작업 로그와 diff를 확인한다.

5. 로컬에서 테스트를 실행한다.

6. PR 템플릿을 작성한다.

7. GitHub Actions 또는 CI를 통과시킨다.

8. 리뷰어를 지정한다.

9. AI가 생성·수정한 범위를 PR에 표시한다.

10. 사람 리뷰 후 병합한다.

이 목록에서 중요한 것은 "Codex가 했으니 바로 PR"이 아니라는 점입니다. Codex 작업은 초안입니다. 사람과 CI가 확인한 뒤에야 팀 코드가 됩니다.

브랜치 이름도 표준화하면 추적이 쉬워집니다.

git checkout main
git pull
git checkout -b codex/issue-128-dashboard-empty-state

또는 여러 작업을 병렬로 돌릴 때는 worktree를 사용합니다.

git worktree add ../myapp-empty-state -b codex/issue-128-empty-state
git worktree add ../myapp-auth-test -b codex/issue-129-auth-test
git worktree add ../myapp-docs -b codex/issue-130-docs

Codex App을 쓰는 팀이라면 작업별 스레드를 분리하고, 각 스레드가 독립된 worktree에서 움직이도록 운영하는 것이 좋습니다. Codex App은 여러 작업 스레드와 worktree, 자동화, diff 리뷰를 관리하는 데 적합한 표면으로 설명됩니다.⁴ CLI를 쓰는 팀도 원리는 같습니다. 한 이슈, 한 브랜치, 한 diff입니다.

PR 템플릿에는 AI 작업 흔적을 남깁니다. 이것은 부끄러운 표시가 아니라 추적 가능성을 높이는 장치입니다.

## Summary
- 대시보드 빈 상태 UI 추가
- 첫 프로젝트 만들기 CTA 연결

## Codex involvement
- Codex가 초안 구현을 생성함
- 사람이 diff를 검토하고 문구를 수정함
- 인증 로직과 데이터 조회 로직은 변경하지 않음

## Changed files
- `src/app/dashboard/page.tsx`
- `src/components/dashboard/EmptyProjectState.tsx`

## Verification
- [x] `npm run lint`
- [x] `npm run build`
- [ ] 브라우저 모바일 확인: 로컬 환경 이슈로 미실행

## Review focus
- 빈 상태 조건이 프로젝트 0개일 때만 적용되는지
- CTA 링크가 올바른지
- 모바일 레이아웃이 깨지지 않는지

## Risks
- 실제 사용자 데이터가 많은 계정에서는 별도 영향 없음

이런 PR 본문은 리뷰어를 편하게 합니다. 리뷰어는 "무슨 일이 있었는지"를 추리하지 않아도 됩니다. Codex가 만든 코드라도 결국 팀이 병합하는 코드입니다. 기록이 남아야 나중에 문제가 생겼을 때 원인을 찾을 수 있습니다.

초보 팀원을 위한 리뷰 루틴

초보 팀원이 Codex를 쓸 때 가장 위험한 순간은 결과가 그럴듯해 보일 때입니다. 코드가 깔끔해 보이고, 파일 이름도 그럴싸하고, 설명도 자신감 있게 나오면 그대로 병합하고 싶어집니다. 하지만 Codex의 자신감은 검증 결과가 아닙니다. 팀 리뷰 루틴은 이 착각을 막아야 합니다.

초보 팀원에게는 다음 순서로 리뷰하도록 훈련시키는 것이 좋습니다.

첫째, 변경 의도와 diff를 비교합니다. 이슈는 빈 상태 UI 추가였는데 인증 로직이 바뀌었다면 바로 멈춰야 합니다. 좋은 코드를 추가했는지가 아니라 요청한 범위 안에서 바꿨는지가 먼저입니다.

둘째, 삭제된 코드를 확인합니다. Codex가 테스트를 삭제하거나, 에러 처리를 단순화하거나, "사용되지 않는 코드"라고 판단해 중요한 방어 로직을 지울 수 있습니다. 삭제는 추가보다 더 위험할 때가 많습니다.

셋째, 낯선 API와 새 의존성을 확인합니다. Codex가 잘 모르는 라이브러리 API를 그럴듯하게 사용할 수 있습니다. 새 패키지가 추가되었다면 왜 필요한지, 라이선스와 보안 문제가 없는지 확인해야 합니다.

넷째, 보안 관련 코드를 집중해서 봅니다. 인증, 권한, 결제, 세션, 쿠키, CORS, 파일 업로드, SQL 쿼리, 외부 API 호출은 항상 사람 리뷰가 필요합니다. OpenAI의 안전 운영 글에서도 AI 코딩 에이전트 도입에는 샌드박스, 승인, 네트워크 제한, 감사 가능한 로그가 함께 필요하다고 강조합니다.³

다섯째, 테스트 결과를 믿되 테스트 범위를 의심합니다. npm test가 통과했다는 사실은 중요하지만, 그 테스트가 이번 변경을 실제로 검증하는지는 별개의 문제입니다. 빈 상태 UI를 추가했는데 빈 상태 테스트가 없다면 통과한 테스트만으로는 부족합니다.

실전 리뷰 프롬프트도 팀 표준으로 만들어두면 좋습니다.

이 diff를 리뷰해줘.

관점:
1. 이슈의 acceptance criteria를 만족하는가?
2. 요청 범위를 벗어난 변경이 있는가?
3. 테스트가 삭제되거나 약해진 부분이 있는가?
4. 인증, 권한, 개인정보, 비밀값과 관련된 위험이 있는가?
5. 새 의존성이나 낯선 API 사용이 적절한가?

출력 형식:
- Must fix
- Should consider
- Looks good
- 사람이 직접 확인해야 할 항목

하지만 여기서도 중요한 원칙이 있습니다. 실패 테스트나 애매한 구현을 발견했을 때 곧바로 "다시 고쳐줘"라고 Codex에게 던지지 마세요. 먼저 사람이 원인을 설명해야 합니다.

나쁜 재지시:

테스트 깨져. 고쳐줘.

좋은 재지시:

`ProjectList.test.tsx`의 "renders empty state" 테스트가 실패한다.
원인은 빈 상태 조건이 `projects === null`일 때만 적용되고,
실제 로더는 프로젝트가 없을 때 빈 배열 `[]`을 반환하기 때문이다.

수정 지시:
- `projects.length === 0` 조건을 사용해 빈 상태를 렌더링하라.
- 데이터 로딩 로직은 바꾸지 말라.
- `ProjectList.test.tsx`의 기존 테스트는 삭제하지 말라.
- 수정 후 `npm test -- ProjectList.test.tsx`를 실행하라.

사람이 원인을 설명하면 Codex는 훨씬 안정적으로 수정합니다. 반대로 원인을 모른 채 "고쳐줘"만 반복하면 Codex는 추측을 쌓아가고, 세션의 맥락은 점점 흐려집니다.

역할 경계: 맡길 일, 검토할 일, 사람이 소유할 일

팀 운영에서 아주 유용한 구분이 있습니다. Codex에게 완전히 위임할 일, Codex가 제안하되 사람이 검토할 일, 처음부터 사람이 소유해야 할 일을 나누는 것입니다. 일부 팀 교육 프레임워크에서도 AI 작업을 delegate, review, own으로 나누어 운영 기준을 세우는 방식을 소개합니다.⁵

초보 팀에서는 다음처럼 시작할 수 있습니다.

## Delegate: Codex에게 맡겨도 좋은 일
- README의 실행 방법 업데이트
- 단순 테스트 케이스 추가
- 명확한 버그 재현이 있는 작은 수정
- 반복적인 타입 오류 수정
- 린트/포맷 정리
- 변경 로그 초안 작성

## Review: Codex가 제안하고 사람이 판단할 일
- 중간 규모 리팩터링
- API 응답 구조 변경 제안
- 성능 최적화
- UI 구조 개선
- 테스트 전략 변경
- 의존성 업데이트

## Own: 사람이 직접 소유해야 할 일
- 핵심 아키텍처 결정
- 인증/권한 모델 설계
- 결제 및 과금 정책
- 개인정보 처리 방식
- 프로덕션 DB 마이그레이션
- 보안 사고 대응
- 법무/저작권 판단

이 구분은 Codex를 못 믿어서 만드는 것이 아닙니다. 사람 팀원에게도 같은 원칙을 적용합니다. 신입 개발자에게도 바로 결제 시스템 설계를 혼자 맡기지는 않습니다. Codex도 마찬가지입니다. 반복적이고 검증 가능한 일부터 맡기고, 판단이 필요한 일은 사람이 책임져야 합니다.

반복 지식은 Skills와 프롬프트로 저장한다

팀이 Codex를 몇 주만 써도 반복되는 프롬프트가 생깁니다. "PR 설명 써줘", "CI 실패 원인 요약해줘", "이슈를 구현 가능한 단위로 쪼개줘", "테스트를 먼저 추가해줘" 같은 요청입니다. 이런 요청을 매번 손으로 쓰면 팀원마다 품질이 달라집니다. 이때 Skills와 공통 프롬프트가 필요합니다.

Skill은 Codex가 특정 작업을 팀 방식대로 수행하도록 만든 재사용 가능한 절차입니다. 예를 들어 PR 리뷰 Skill에는 팀의 리뷰 기준, 출력 형식, 위험 분류 기준을 담을 수 있습니다. 릴리스 노트 Skill에는 커밋을 읽는 순서, 사용자에게 보여줄 문장 톤, 내부 변경을 제외하는 규칙을 담을 수 있습니다.

처음부터 거대한 Skill 라이브러리를 만들 필요는 없습니다. 다음 세 가지부터 시작하면 충분합니다.

## 추천 팀 Skill 1: issue-triage
목적: 새 이슈를 Codex 작업에 적합한 단위로 정리한다.
출력: Goal, Context, Scope, Acceptance criteria, Verification
위험도: 낮음

## 추천 팀 Skill 2: pr-description
목적: 현재 브랜치 diff를 읽고 PR 본문 초안을 만든다.
출력: Summary, Changed files, Verification, Risks, Review focus
위험도: 낮음

## 추천 팀 Skill 3: test-gap-review
목적: 변경된 코드에 대해 누락된 테스트 관점을 찾는다.
출력: Existing coverage, Missing cases, Suggested tests
위험도: 중간

Skill을 만들 때는 하나의 Skill이 하나의 일을 하게 해야 합니다. "릴리스 전체 자동화 Skill"처럼 빌드, 테스트, 배포, 알림, 롤백을 모두 넣으면 실패했을 때 원인을 찾기 어렵습니다. 대신 generate-release-notes, check-release-readiness, draft-deploy-plan처럼 작게 나누는 편이 좋습니다.

공통 프롬프트 저장소도 효과적입니다.

# prompts/codex-review.md

다음 diff를 팀 리뷰 기준으로 검토해줘.

반드시 확인할 것:
- 요청 범위 밖 변경
- 삭제된 테스트
- 인증/권한 관련 위험
- 새 의존성 추가
- 에러 처리 약화
- 타입 안정성 저하

출력:
1. Must fix
2. Should consider
3. Test gaps
4. Human review focus

팀원은 이 파일을 복사해 쓰거나, Codex에게 "prompts/codex-review.md 기준으로 리뷰해줘"라고 요청할 수 있습니다. 이렇게 하면 선임 개발자의 리뷰 관점이 팀 전체에 퍼집니다.

자동화는 저위험 작업부터 시작한다

Codex Automations는 반복 작업을 정해진 시간이나 조건에 맞춰 실행할 수 있게 해줍니다. 예를 들어 매일 아침 새 이슈를 분류하거나, CI 실패를 요약하거나, 릴리스 전 변경 로그 초안을 만들 수 있습니다. Codex App의 자동화 기능은 반복 작업을 백그라운드에서 실행하고, 프로젝트와 프롬프트와 실행 주기를 지정하는 방식으로 소개됩니다.²

하지만 자동화는 팀이 이미 잘 수행하고 있는 일을 자동으로 반복하게 만들 때 효과적입니다. 아직 사람이 해도 흔들리는 작업을 자동화하면 흔들림만 빨라집니다.

처음 자동화하기 좋은 작업은 다음과 같습니다.

## 낮은 위험
- 새 이슈 요약과 라벨 제안
- PR 설명 초안 작성
- CI 실패 로그 요약
- 주간 변경 사항 요약
- 문서와 README 업데이트 후보 제안

## 중간 위험
- 테스트 케이스 초안 생성
- 의존성 업데이트 PR 초안
- 리팩터링 후보 목록 작성
- 브라우저 검증 리포트 작성

## 높은 위험: 자동 실행 금지 또는 명시 승인 필요
- 배포 실행
- DB 마이그레이션 적용
- 비밀값 접근
- 인증/결제 코드 자동 수정
- 대량 파일 삭제 또는 이동
- main 브랜치 직접 푸시

예를 들어 매일 오전 9시에 이슈를 정리하는 자동화는 안전한 출발점입니다.

Automation: daily-issue-triage
Schedule: 매주 평일 오전 9시
Prompt:
GitHub의 새 이슈를 읽고 다음 형식으로 분류해줘.
코드는 수정하지 마라.

출력:
- 이슈 번호
- 요약
- 예상 작업 유형: bug / feature / docs / refactor / question
- Codex 작업 가능 여부: yes / needs-human-clarification / no
- 필요한 추가 정보
- 추천 acceptance criteria 초안

금지:
- 이슈를 닫지 마라.
- 담당자를 지정하지 마라.
- 외부 댓글을 작성하지 마라.

자동화의 핵심은 "결과가 검토 대기열에 들어온다"는 감각입니다. Codex가 한 일을 사람이 훑고 승인하는 구조가 유지되어야 합니다. 특히 배포, DB, 보안, 비용이 걸린 작업은 사람 승인 없이 실행하지 않는 것이 기본입니다.

외부 도구 연결은 최소 권한으로

팀은 곧 이런 유혹을 느낍니다. "GitHub, Slack, Linear, Jira, Notion, Figma, Sentry, Datadog을 모두 연결하면 Codex가 우리 팀을 완전히 이해하지 않을까?" 이론적으로는 매력적입니다. 실제로는 위험합니다. 너무 많은 도구 연결은 권한 표면을 넓히고, 컨텍스트 노이즈를 늘리고, 문제가 생겼을 때 추적을 어렵게 만듭니다.

MCP나 플러그인을 연결하기 전에 팀은 네 가지 질문을 해야 합니다.

1. 이 정보가 저장소 밖에 있어서 매번 복사하기 번거로운가?
2. 이 정보가 자주 바뀌어서 실시간 접근이 필요한가?
3. Codex가 단순히 읽는 것을 넘어 도구 행동을 해야 하는가?
4. 이 통합을 팀이 반복적으로 사용할 것인가?

네 질문 중 두 개 이상에 "예"라고 답하지 못한다면 아직 연결하지 않는 편이 낫습니다.

처음 연결하기 좋은 도구는 대체로 읽기 중심입니다. GitHub 이슈 읽기, PR 체크 상태 읽기, Figma 디자인 읽기, 로컬 Playwright 검증 정도가 적당합니다. Slack 메시지 쓰기, Jira 상태 변경, 배포 플랫폼 조작, DB 접근은 훨씬 나중에 검토해야 합니다.

외부 도구 권한 정책도 문서로 남겨야 합니다.

# Codex external tool policy

## GitHub
- 이슈/PR 읽기: 허용
- PR 생성: 사람 승인 필요
- main 브랜치 푸시: 금지
- 리뷰 댓글 작성: 승인 필요

## Figma
- 디자인 파일 읽기: 허용
- 디자인 파일 수정: 금지

## Slack
- 메시지 읽기: 특정 채널만 승인 필요
- 메시지 작성: 기본 금지

## Database
- 로컬 개발 DB: 승인 후 제한적 허용
- 스테이징 DB: 읽기 전용도 기본 금지, 필요 시 관리자 승인
- 프로덕션 DB: 금지

## Secrets
- 실제 비밀값 읽기, 출력, 저장: 금지
- 환경 변수 이름 참조: 허용

Codex가 외부 도구를 잘 쓰게 만드는 것보다 중요한 것은, 잘못 쓰지 못하게 만드는 것입니다.

병렬 작업과 서브에이전트는 작게 시작한다

Codex의 강력한 기능 중 하나는 여러 작업을 병렬로 진행할 수 있다는 점입니다. App에서는 여러 스레드와 worktree를 통해 작업을 나눌 수 있고, 팀은 한 이슈는 버그 수정, 다른 이슈는 문서 업데이트, 또 다른 이슈는 테스트 보강처럼 동시에 진행할 수 있습니다. 하지만 병렬성은 생산성을 높이는 동시에 운영 복잡도도 높입니다.

초보 팀은 처음부터 "스프린트 전체를 Codex에게 병렬로 맡기자"라고 생각하면 안 됩니다. 먼저 서로 파일이 겹치지 않는 작은 작업 세 개 정도로 실험하세요.

좋은 병렬 작업 예시는 다음과 같습니다.

Thread A: `/dashboard` 빈 상태 UI 추가
Thread B: `README.md` 설치 문서 업데이트
Thread C: `tests/auth.test.ts`에 세션 만료 테스트 추가

나쁜 병렬 작업 예시는 다음과 같습니다.

Thread A: 인증 구조 개선
Thread B: 로그인 UI 변경
Thread C: 세션 저장 방식 변경
Thread D: 권한 미들웨어 리팩터링

두 번째 예시는 모두 인증 주변 파일을 건드릴 가능성이 큽니다. 병렬 실행 자체는 가능해도 병합 시 충돌과 의미 충돌이 생기기 쉽습니다. 병렬 작업은 파일 소유권과 통합 기준이 분명할 때만 효과적입니다.

서브에이전트나 역할별 에이전트를 쓰는 경우에도 마찬가지입니다. 역할을 나누면 코드 탐색, 보안 리뷰, 테스트 관점 검토를 동시에 할 수 있습니다. 하지만 토큰 비용과 추적 비용이 늘어납니다. 단순한 한 줄 수정에는 과합니다. 복잡한 PR 리뷰처럼 병렬 가치가 있을 때만 사용하세요.

예를 들어 큰 PR 리뷰에서는 이런 식으로 요청할 수 있습니다.

이 PR을 main 브랜치와 비교해 리뷰해줘.

역할을 나눠서 확인해줘.
- 코드 경로 탐색: 어떤 기능 흐름이 영향을 받는지 요약
- 보안 리뷰: 인증, 권한, 입력 검증, 비밀값 노출 위험 확인
- 테스트 리뷰: 누락된 테스트와 약해진 테스트 확인

조건:
- 코드는 수정하지 말고 리뷰만 해라.
- 각 역할의 발견 사항을 분리해서 보고하라.
- 최종 섹션에 사람이 반드시 확인해야 할 항목을 정리하라.

이런 역할 분리는 Codex를 "한 명의 만능 개발자"가 아니라 "작은 검토 팀"처럼 쓰는 방식입니다. 다만 팀 규칙은 동일합니다. 최종 판단과 병합 책임은 사람에게 있습니다.

운영 지표를 봐야 규칙이 좋아진다

관리자나 테크 리드는 Codex 도입 후 "느낌상 빨라졌다"에 머물면 안 됩니다. 팀 규칙이 효과적인지 보려면 지표가 필요합니다. 지표는 사람을 감시하기 위한 것이 아니라, Codex 운영 규칙을 개선하기 위한 신호입니다.

처음 볼 만한 지표는 다음과 같습니다.

## 사용량과 비용
- 팀별 Codex 작업 수
- 작업당 평균 토큰 또는 비용
- 긴 작업 상위 목록
- 실패 후 재시도 횟수

## 작업 품질
- Codex 작업 성공률
- 사람 수정 없이 통과한 PR 비율
- 리뷰에서 발견된 AI 오류 유형
- 범위 밖 변경 발생 횟수
- 삭제된 테스트 또는 약해진 테스트 발견 횟수

## 검증 품질
- Codex PR의 CI 실패율
- 자주 실패하는 테스트 명령
- 빌드 실패 원인 유형
- 테스트 없이 병합된 Codex PR 수

## 보안과 권한
- MCP/플러그인 접근 기록
- 승인 요청 발생 횟수
- 거부된 위험 작업 수
- 비밀값 접근 시도 또는 차단 기록
- 외부 네트워크 접근 요청

## 팀 학습
- AGENTS.md 업데이트 횟수
- 공통 프롬프트 재사용 횟수
- Skill 실패 사례와 개선 횟수
- 신규 팀원 온보딩 후 첫 PR까지 걸린 시간

이 지표를 바탕으로 매주 15분만 회고해도 팀 운영이 빠르게 좋아집니다. 예를 들어 Codex PR의 CI 실패율이 높다면 프롬프트보다 AGENTS.md의 Verification 섹션을 먼저 고쳐야 할 수 있습니다. 범위 밖 변경이 자주 발생한다면 이슈 템플릿의 Out of scope를 강화해야 합니다. 특정 MCP 도구에서 승인 요청이 과도하게 발생한다면 권한을 줄이거나 사용 기준을 다시 정해야 합니다.

운영 지표는 Codex를 평가하는 도구이기도 하지만, 더 정확히는 팀의 요청 품질을 비추는 거울입니다. Codex가 자주 헷갈린다면 팀의 문서, 테스트, 이슈, 책임 경계가 헷갈리게 되어 있을 가능성이 큽니다.

팀 온보딩: 새 팀원에게 이렇게 가르친다

Codex를 팀에 도입할 때 초보 팀원에게 "그냥 써보세요"라고 하면 안 됩니다. 처음부터 안전한 루틴을 몸에 익히게 해야 합니다. 좋은 온보딩은 기능 설명이 아니라 작업 습관 훈련입니다.

첫날에는 Codex에게 코드를 작성시키기보다 읽고 설명하게 합니다.

이 저장소의 `AGENTS.md`를 읽고,
초보 개발자가 작업 전에 알아야 할 규칙을 10줄 이내로 요약해줘.
코드는 수정하지 마라.

다음으로 작은 문서 작업을 맡깁니다.

README의 로컬 실행 섹션을 확인하고,
현재 `package.json` 스크립트와 맞지 않는 부분만 수정해줘.
코드는 수정하지 말고 README만 수정해라.
수정 후 diff를 요약해줘.

그다음 테스트 추가 작업으로 넘어갑니다.

`src/lib/formatDate.ts`의 기존 동작을 읽고,
현재 동작을 바꾸지 않는 단위 테스트를 추가해줘.
구현 파일은 수정하지 마라.
테스트 추가 후 해당 테스트만 실행해줘.

마지막으로 작은 버그 수정을 시도합니다.

`formatDate(null)` 호출 시 앱이 깨지는 버그를 수정해줘.
기대 동작은 빈 문자열 반환이다.
테스트를 먼저 추가하고 실패를 확인한 뒤 구현을 수정해줘.
기존 테스트는 삭제하지 마라.

이 순서에는 이유가 있습니다. 읽기, 문서, 테스트, 작은 수정 순으로 위험도를 높입니다. 초보 팀원은 Codex가 어떤 식으로 파일을 읽고, diff를 만들고, 테스트를 실행하고, 보고하는지 차근차근 배웁니다. 처음부터 인증 리팩터링이나 결제 기능을 맡기지 않습니다.

팀 규칙은 한 번 정하고 끝나는 것이 아니다

Codex 운영법은 고정된 규정집이 아닙니다. 팀의 코드베이스가 바뀌고, Codex 기능이 바뀌고, 팀원의 숙련도가 바뀌면 규칙도 바뀌어야 합니다. 중요한 것은 규칙을 계속 갱신하는 루프입니다.

가장 단순한 운영 루프는 다음과 같습니다.

1. Codex 작업에서 문제가 생긴다.
2. 원인을 분류한다.
   - 이슈가 애매했는가?
   - AGENTS.md 규칙이 부족했는가?
   - 테스트가 없었는가?
   - 권한이 너무 넓었는가?
   - 리뷰 체크리스트가 약했는가?
3. 같은 문제가 반복될 가능성이 있으면 문서나 설정에 반영한다.
4. 다음 작업에서 개선되었는지 확인한다.

예를 들어 Codex가 자꾸 console.log를 남긴다면 AGENTS.md에 "디버깅용 console.log를 최종 diff에 남기지 말라"고 추가합니다. Codex가 새 패키지를 자주 설치한다면 "새 production dependency 추가는 명시 승인 없이는 금지"라고 설정합니다. 리뷰어가 매번 PR 설명을 다시 쓰고 있다면 pr-description Skill을 만듭니다.

이렇게 팀 운영 지식이 문서, 설정, Skill, 자동화로 축적되면 Codex 사용은 개인기에서 시스템으로 바뀝니다.

실전 운영 템플릿: 작은 팀의 시작 세트

마지막으로, 지금 바로 팀 저장소에 넣을 수 있는 최소 운영 세트를 정리해봅시다. 이 정도만 있어도 Codex를 무작정 쓰는 단계에서 벗어날 수 있습니다.

/codex-team
  AGENTS.md
  .codex/
    config.toml
  .github/
    ISSUE_TEMPLATE/
      codex-task.md
    pull_request_template.md
  prompts/
    codex-review.md
    codex-fix-ci.md
    codex-issue-triage.md
  docs/
    codex-policy.md
    codex-onboarding.md

codex-policy.md에는 팀의 기본 원칙을 짧게 씁니다.

# Codex Team Policy

## 기본 원칙
- Codex는 팀원이 아니라 팀원이 감독하는 작업자다.
- 모든 Codex 변경은 사람 리뷰 후 병합한다.
- main 브랜치 직접 푸시는 금지한다.
- 보안, 인증, 결제, DB 변경은 반드시 담당자 승인이 필요하다.

## 작업 원칙
- 한 작업은 하나의 이슈와 하나의 브랜치로 관리한다.
- 작업 전 acceptance criteria를 작성한다.
- 작업 후 diff, 테스트, 위험을 PR에 기록한다.

## 권한 원칙
- 기본은 최소 권한이다.
- 읽기 전용으로 충분한 작업은 읽기 전용으로 실행한다.
- 외부 도구 연결은 allowlist에 있는 것만 사용한다.
- 배포와 DB 변경은 자동화하지 않는다.

## 리뷰 원칙
- Codex 결과를 그대로 병합하지 않는다.
- 변경 의도와 diff를 먼저 비교한다.
- 삭제된 테스트와 보안 관련 변경을 집중 확인한다.
- CI 통과는 필수지만 충분조건은 아니다.

이 템플릿은 작은 팀에도 부담스럽지 않습니다. 핵심은 문서의 양이 아니라 합의입니다. "우리는 Codex를 어디까지 믿고, 어디서 사람이 멈춰 세울 것인가?"에 대한 합의가 있어야 합니다.

마무리: Codex 생산성은 운영 성숙도만큼 나온다

Codex는 팀의 속도를 높일 수 있습니다. 하지만 규칙이 없는 팀에서는 혼란도 빠르게 키웁니다. 이 장의 핵심은 단순합니다. 팀에서 Codex를 쓰려면 생산성보다 먼저 운영 기준을 세워야 합니다.

공통 AGENTS.md로 프로젝트 기억을 만들고, config.toml과 승인 정책으로 권한을 통제합니다. 이슈는 Codex가 처리하기 좋은 작은 단위로 쪼개고, 브랜치부터 PR 병합까지 추적 가능한 흐름을 고정합니다. 초보 팀원에게는 diff와 테스트를 보는 리뷰 루틴을 훈련시키고, 반복되는 지식은 Skill과 프롬프트와 자동화로 저장합니다. 외부 도구 연결은 최소 권한으로 시작하고, 관리자는 비용과 품질과 보안 지표를 정기적으로 봅니다.

Codex를 잘 쓰는 팀은 "AI가 코드를 대신 짠다"고 말하지 않습니다. "우리는 AI가 참여해도 안전하게 돌아가는 개발 시스템을 만들었다"고 말합니다. 이제 마지막 장에서는 이 운영 기준을 바탕으로, 아이디어 하나를 실제 출시 가능한 최종 프로젝트로 끝까지 밀어붙여 보겠습니다.

참고

¹Workflows - Codex | OpenAI Developers

²Best practices - Codex | OpenAI Developers

³Running Codex safely at OpenAI

⁴What Is the OpenAI Codex App? A Practical 2026 Guide for Teams Using AI Coding Agents

⁵Codex Workshops for engineering teams | Codex Workshop