Cloud와 GitHub로 PR까지 연결하기

이제 Codex를 '내 컴퓨터 안의 도우미'에서 '원격 동료'로 바꿀 차례

지금까지 우리는 Codex를 로컬 프로젝트 안에서 사용해 왔습니다. 파일을 고치게 하고, 테스트를 만들게 하고, 리팩터링을 부탁한 뒤 git diff로 확인했습니다. 이 흐름만으로도 충분히 강력합니다. 하지만 실제 앱 개발은 내 컴퓨터 안에서만 끝나지 않습니다.

앱이 조금만 커져도 작업은 GitHub 이슈로 정리되고, 기능은 브랜치로 나뉘며, 변경 사항은 Pull Request, 줄여서 PR로 검토됩니다. 팀으로 일하지 않더라도 PR 중심 흐름은 유용합니다. 왜냐하면 PR은 "내가 무엇을 바꿨는지", "왜 바꿨는지", "테스트는 통과했는지"를 한곳에 모아 주는 작업 기록장이기 때문입니다.

Codex Cloud는 이 흐름에서 특히 빛납니다. 로컬 Codex가 옆자리에서 바로바로 도와주는 짝꿍이라면, Codex Cloud는 GitHub 저장소를 보고 별도 환경에서 긴 작업을 맡아 처리한 뒤 PR로 결과를 가져오는 원격 동료에 가깝습니다. OpenAI의 Codex Cloud 문서에서도 클라우드 작업은 저장소, 설정 단계, 도구를 지정해 작업을 위임하고 결과를 diff나 PR 흐름으로 검토하는 방식으로 설명됩니다.¹

이 장의 목표는 단순합니다. 로컬에서 고치던 습관을 GitHub와 Codex Cloud까지 확장해, 긴 작업을 안전하게 맡기고 PR에서 검토하는 흐름을 만드는 것입니다.

먼저 GitHub 저장소에 프로젝트를 연결하기

Codex Cloud를 제대로 쓰려면 프로젝트가 GitHub 저장소에 올라가 있어야 합니다. 아직 GitHub 저장소가 없다면 먼저 빈 저장소를 만들고 로컬 프로젝트와 연결합니다.

예를 들어 현재 로컬 프로젝트가 이미 Git 저장소라면 다음 흐름으로 시작할 수 있습니다.

git status
git branch

작업 중인 변경 사항이 있다면 먼저 커밋하거나, 아직 불안하다면 별도 브랜치에 보관합니다. 초보자에게 가장 중요한 원칙은 "원격 저장소에 올리기 전에 현재 상태를 알고 있어야 한다"는 것입니다.

새 GitHub 저장소를 만들었다고 가정하면, 로컬 저장소에 원격 주소를 연결합니다.

git remote add origin https://github.com/your-name/my-app.git
git branch -M main
git push -u origin main

이미 origin이 있다면 다음 명령으로 확인할 수 있습니다.

git remote -v

여기서 main은 기준 브랜치입니다. 실제 제품 코드가 놓이는 중심 줄이라고 생각하면 됩니다. Codex든 사람이든 실험적인 변경을 바로 main에 밀어 넣는 습관은 위험합니다. 대신 기능 브랜치를 만들고, PR을 통해 검토한 뒤 main에 합치는 흐름을 사용합니다.

main 브랜치는 잠가 두는 것이 좋다

초보자일수록 main 보호가 필요합니다. 실수로 main에 직접 push하면 되돌릴 수는 있지만, 그 과정이 꽤 당황스럽습니다. 특히 Codex Cloud가 만든 변경, 로컬에서 만든 변경, GitHub에서 직접 수정한 변경이 섞이면 머릿속이 금방 복잡해집니다.

GitHub 저장소 화면에서 Settings → Branches 또는 Rulesets로 이동해 main 브랜치 보호 규칙을 만들 수 있습니다. 저장소나 조직 설정에 따라 화면 이름은 조금 다를 수 있지만, 기본적으로는 다음 성격의 규칙을 켜면 좋습니다.

• main에 직접 push하지 않고 PR을 통해서만 병합하기

• 병합 전에 CI 또는 테스트 체크가 통과해야 하도록 설정하기

• 최소 1명 이상의 리뷰 승인 후 병합하기

• 오래된 브랜치는 최신 main을 반영한 뒤 병합하기

혼자 개발하는 경우에도 이 규칙은 과하지 않습니다. 미래의 나도 팀원입니다. 오늘의 내가 밤늦게 급하게 push한 코드를 내일의 내가 울면서 고치는 일을 줄여 줍니다.

기능 브랜치에서 작업하고 PR로 제안하기

이제 기능 브랜치를 만들어 봅시다. 예를 들어 할 일 관리 앱에 검색 기능을 추가한다고 가정하겠습니다.

git checkout main
git pull origin main
git checkout -b feat/todo-search

여기서 중요한 명령은 git pull origin main입니다. 작업을 시작하기 전에 원격 main의 최신 상태를 가져옵니다. 이것을 습관으로 만들면 나중에 충돌이 크게 줄어듭니다.

로컬 Codex에게 짧은 작업을 맡긴다면 이렇게 요청할 수 있습니다.

할 일 목록 화면에 검색 입력창을 추가해줘.
범위는 src/components/TodoList.tsx와 관련 테스트 파일로 제한해줘.
기존 필터 기능이 있다면 깨뜨리지 말고, 검색어가 비어 있으면 전체 목록을 보여줘.
작업 후 npm test를 실행하고 결과를 요약해줘.

작업이 끝나면 늘 하던 대로 확인합니다.

git diff
npm test
git status

문제가 없다면 커밋합니다.

git add .
git commit -m "feat(todo): 할 일 검색 기능 추가"
git push -u origin feat/todo-search

이제 GitHub 웹 화면에서 PR을 만들 수 있습니다. 하지만 터미널에서 처리하고 싶다면 GitHub CLI를 쓰면 편합니다.

gh auth login
gh pr create --base main --head feat/todo-search --title "할 일 검색 기능 추가" --body "## 요약
- 할 일 목록 검색 입력창 추가
- 검색어 기준 필터링 적용

## 확인
- npm test 실행"

PR이 잘 만들어졌는지 확인하려면 다음 명령을 사용합니다.

gh pr view --web

또는 터미널에서 요약만 볼 수도 있습니다.

gh pr view

이제 변경은 단순한 로컬 수정이 아니라 검토 가능한 제안이 되었습니다. 이것이 PR 중심 워크플로의 핵심입니다.

언제 로컬 Codex를 쓰고, 언제 Codex Cloud에 맡길까

처음에는 모든 일을 Codex Cloud에 맡기고 싶을 수 있습니다. "클라우드에서 알아서 해준다니 멋지잖아?"라는 생각이 듭니다. 하지만 좋은 개발자는 도구를 많이 쓰는 사람이 아니라, 알맞은 상황에 알맞은 도구를 고르는 사람입니다.

짧고 즉각적인 작업은 로컬 Codex가 좋습니다. 예를 들어 버튼 문구 수정, 작은 컴포넌트 분리, 테스트 하나 추가, 에러 메시지 개선처럼 몇 분 안에 확인할 수 있는 일은 로컬에서 처리하는 편이 빠릅니다. 내 편집기와 터미널에서 바로 diff를 보고, 바로 실행하고, 바로 고칠 수 있기 때문입니다.

반대로 시간이 오래 걸리거나 변경 범위가 넓은 작업은 Codex Cloud에 잘 맞습니다. 예를 들어 대규모 리팩터링, 테스트 보강, 문서 정리, 이슈 기반 기능 구현, 실패한 CI 원인 분석처럼 작업 시간이 길고 여러 파일을 건드릴 가능성이 큰 일은 클라우드에 위임하는 편이 좋습니다. Codex Cloud는 별도 환경에서 작업을 실행하고 결과를 검토 가능한 형태로 남기는 흐름을 지원합니다.¹

간단히 나누면 이렇게 생각하면 됩니다.

처음에는 "짧으면 로컬, 길면 Cloud" 정도로만 기억해도 충분합니다.

Codex Cloud 환경 만들기

Codex Cloud가 GitHub 저장소에서 작업하려면 먼저 환경을 만들어야 합니다. 환경은 Codex가 클라우드에서 작업할 때 사용하는 작업실입니다. 어떤 저장소를 체크아웃할지, 어떤 브랜치를 기준으로 삼을지, 어떤 설치 명령을 실행할지, 어떤 환경 변수가 필요한지 정하는 곳입니다.

일반적인 흐름은 다음과 같습니다.

1. chatgpt.com/codex로 이동합니다.

2. GitHub 계정을 연결합니다.

3. Codex가 접근할 저장소를 선택합니다.

4. 새 환경을 만들고 기준 브랜치를 지정합니다.

5. 설치 명령을 설정합니다. 예를 들어 npm install, pnpm install, pip install -r requirements.txt 같은 명령입니다.

6. 필요한 환경 변수가 있다면 등록합니다.

7. 저장한 뒤 테스트 작업을 실행합니다.

Codex GitHub 연동 문서에 따르면 GitHub PR에서 Codex 코드 리뷰를 요청하거나 자동 리뷰를 사용하려면 저장소 연동과 관련 설정이 필요하며, @codex review 같은 방식으로 PR 검토를 요청할 수 있습니다.²

초보자가 가장 자주 실수하는 부분은 설치 명령입니다. 로컬에서는 이미 node_modules가 있어서 잘 되던 프로젝트도 클라우드 환경에서는 처음부터 의존성을 설치해야 합니다. 따라서 Node.js 프로젝트라면 보통 다음 중 하나를 환경 설정에 넣습니다.

npm install

또는 pnpm을 쓴다면 다음처럼 설정합니다.

corepack enable
pnpm install

테스트와 빌드 명령도 AGENTS.md에 적어 두면 좋습니다.

## Project commands

- Install dependencies: `pnpm install`
- Run tests: `pnpm test`
- Run lint: `pnpm lint`
- Build: `pnpm build`

## Working rules

- Do not modify files in `src/generated/`.
- Prefer small PRs.
- Always summarize changed files and validation results.

이 파일은 Codex가 프로젝트의 규칙을 기억하는 메모장입니다. 앞 장에서 다룬 AGENTS.md가 이제 Cloud 작업과 PR 리뷰에서도 중요한 기준이 됩니다.

Cloud에 맡기기 좋은 첫 작업: 문서 정리 PR

처음부터 대규모 기능을 맡기기보다는 위험이 낮은 작업으로 시작하는 것이 좋습니다. 예를 들어 README를 정리하는 작업은 Codex Cloud 연습용으로 훌륭합니다.

Codex Cloud에 다음처럼 요청해 봅니다.

이 저장소의 README를 초보자가 따라 하기 쉽게 개선해줘.

목표:
- 프로젝트 소개 추가
- 설치 방법 추가
- 개발 서버 실행 방법 추가
- 테스트 실행 방법 추가
- 주요 폴더 구조 설명 추가

제약:
- 코드 파일은 수정하지 마.
- README.md와 필요한 경우 docs/ 안의 문서만 수정해.

완료 기준:
- README만 봐도 새 개발자가 로컬에서 앱을 실행할 수 있어야 해.
- 변경 요약과 실행하지 못한 검증이 있다면 이유를 남겨줘.

이 프롬프트에는 목표, 범위, 제약, 완료 기준이 들어 있습니다. Codex Cloud에게 일을 맡길 때는 "좋게 정리해줘"보다 "어떤 파일을, 어떤 기준으로, 어디까지 바꿀지"를 알려 주는 편이 훨씬 안정적입니다.

작업이 끝나면 결과를 바로 병합하지 않습니다. 먼저 변경 파일을 봅니다. README가 실제 명령과 맞는지, 없는 명령을 만들어 내지는 않았는지, 패키지 매니저가 npm인지 pnpm인지 확인합니다.

문서 작업이 마음에 들면 PR을 만들거나, Cloud가 만든 브랜치에서 PR을 생성합니다. 이제 Codex Cloud는 단순히 코드를 뱉는 도구가 아니라 PR을 제안하는 작업자가 됩니다.

이슈에서 PR까지 맡기는 실전 예제

이번에는 실제 기능 구현에 가까운 예제를 보겠습니다. GitHub 이슈를 하나 만든다고 가정합니다.

제목: [feature] 로그인 실패 시 에러 메시지 개선

## 배경
현재 로그인 실패 시 콘솔에는 에러가 보이지만, 사용자 화면에는 안내가 부족하다.

## 목표
- 이메일 또는 비밀번호가 틀렸을 때 화면에 에러 메시지를 보여준다.
- 서버 오류일 때는 "잠시 후 다시 시도해 주세요" 메시지를 보여준다.
- 로그인 버튼의 로딩 상태는 기존 동작을 유지한다.

## 범위
- 로그인 화면과 관련 테스트만 수정한다.
- 인증 API 스펙은 변경하지 않는다.
- 디자인 시스템에 없는 새 UI 라이브러리는 추가하지 않는다.

## 완료 기준
- 실패 케이스 테스트가 추가된다.
- npm test가 통과한다.
- PR 설명에 변경 요약과 테스트 결과가 포함된다.

이슈를 잘 쓰면 Codex에게 줄 프롬프트의 절반은 이미 완성된 셈입니다. 이제 Codex Cloud나 GitHub 댓글에서 다음처럼 요청할 수 있습니다.

@codex implement this issue.
로그인 화면과 관련 테스트 범위에서만 수정해줘.
npm test를 실행하고, PR 설명에 변경 요약과 테스트 결과를 남겨줘.

GitHub 연동이 활성화된 저장소에서는 PR이나 이슈 댓글에서 @codex 멘션을 통해 클라우드 작업을 시작하는 흐름을 사용할 수 있습니다. 특히 @codex review는 PR 안에서 코드 리뷰를 요청하는 전용 명령으로 동작합니다.²

작업이 완료되어 PR이 생기면 이제 사람의 일이 시작됩니다. Codex가 구현했다는 이유로 바로 병합하면 안 됩니다. AI가 만든 PR도 신입 개발자가 올린 PR처럼 봐야 합니다. 잘했을 가능성도 있고, 놓친 것이 있을 가능성도 있습니다.

PR 검토는 다섯 가지를 함께 본다

Codex Cloud 작업 결과를 검토할 때는 PR의 초록색 체크 하나만 보면 부족합니다. 테스트가 통과해도 의도와 다른 변경이 들어갈 수 있고, 코드가 깔끔해 보여도 보안상 위험한 처리가 숨어 있을 수 있습니다.

PR에서는 최소한 다음 다섯 가지를 함께 확인합니다.

• 파일 diff: 어떤 파일이 실제로 바뀌었는지 봅니다.

• 작업 요약: Codex가 무엇을 했다고 설명했는지 확인합니다.

• 터미널 로그: 설치, 테스트, 빌드 명령이 실제로 실행되었는지 봅니다.

• 테스트 결과: 실패한 테스트를 무시하지 않았는지 확인합니다.

• CI 상태: GitHub Actions 같은 자동 검사 결과가 통과했는지 봅니다.

예를 들어 로그인 실패 메시지 PR에서 diff를 볼 때는 이런 질문을 던집니다.

이 변경이 정말 로그인 실패 메시지만 다루는가?
인증 API 동작을 바꾸지는 않았는가?
사용자에게 서버 내부 오류 메시지를 그대로 노출하지는 않는가?
테스트가 성공 케이스와 실패 케이스를 모두 다루는가?
기존 로그인 성공 흐름이 깨지지 않았는가?

이 질문에 답할 수 있어야 병합할 준비가 된 것입니다.

@codex review로 PR 코드 리뷰 받기

PR을 열었다면 Codex에게 리뷰를 요청할 수 있습니다. GitHub PR 댓글에 다음처럼 남깁니다.

@codex review

그러면 Codex가 PR diff를 읽고 코드 리뷰를 남깁니다. 공식 문서에서도 @codex review를 사용해 GitHub PR에서 Codex 코드 리뷰를 요청할 수 있고, 자동 리뷰를 켜면 새 PR에 대해 자동으로 리뷰가 실행될 수 있다고 설명합니다.²

리뷰 범위를 좁히고 싶다면 이렇게 요청할 수도 있습니다.

@codex review for security regressions

또는 초보자 프로젝트에서 자주 놓치는 테스트 관점으로 요청할 수 있습니다.

@codex review focusing on missing tests and edge cases

프론트엔드 작업이라면 접근성과 UI 상태를 강조할 수 있습니다.

@codex review focusing on loading, empty, error, and accessibility states

Codex 리뷰가 남긴 댓글은 무조건 따를 필요는 없습니다. AI 리뷰도 의견입니다. 하지만 무시하기 전에 "왜 이런 지적을 했는지"는 확인해야 합니다. 특히 인증, 권한, 개인정보, 결제, 데이터 삭제와 관련된 지적은 가볍게 넘기면 안 됩니다.

자동 리뷰를 켜기 전에 AGENTS.md부터 정리하기

Codex 자동 리뷰를 켜면 모든 PR에 Codex가 리뷰를 남길 수 있습니다. 편리하지만, 기준이 모호하면 리뷰 품질도 흔들립니다. 그래서 자동 리뷰를 켜기 전에 AGENTS.md에 리뷰 규칙을 정리하는 것이 좋습니다.

예를 들어 미니 SaaS 프로젝트라면 다음과 같이 쓸 수 있습니다.

## Review guidelines

- 새 API 라우트는 반드시 인증 여부를 확인해야 한다.
- 사용자별 데이터는 항상 ownerId 또는 userId로 소유권을 검증해야 한다.
- 비밀번호, 토큰, API 키를 로그에 남기면 안 된다.
- DB 쿼리는 문자열 연결 대신 파라미터 바인딩 또는 ORM 안전 API를 사용한다.
- UI 변경에는 로딩, 빈 상태, 에러 상태를 고려한다.
- 테스트가 없는 새 기능은 P1 문제로 지적한다.
- 단순 포맷팅 문제는 ESLint와 Prettier가 처리하므로 리뷰에서 반복 지적하지 않는다.

OpenAI의 GitHub 코드 리뷰 문서는 저장소의 AGENTS.md에 리뷰 지침을 작성해 Codex 리뷰가 따르게 할 수 있다고 안내합니다.² 즉, AGENTS.md는 코드 생성 규칙뿐 아니라 리뷰 기준이기도 합니다.

여기서 좋은 규칙은 구체적인 규칙입니다. "좋은 코드로 작성하기"는 애매합니다. 반면 "새 API 라우트는 인증 미들웨어를 거쳐야 한다"는 확인할 수 있습니다. Codex에게도 사람에게도 확인 가능한 기준이 좋은 기준입니다.

Codex 리뷰 댓글에 수정 요청하기

PR 리뷰에서 문제가 발견되면 사람이 직접 고칠 수도 있고, Codex에게 다시 맡길 수도 있습니다. 예를 들어 Codex가 만든 PR에서 테스트가 부족하다는 리뷰가 달렸다면 다음처럼 댓글을 남깁니다.

@codex address the review feedback.
특히 로그인 실패 케이스 테스트를 추가하고,
기존 성공 로그인 테스트가 깨지지 않는지 확인해줘.
변경 후 npm test 결과를 PR에 남겨줘.

또는 사람이 직접 지적한 내용을 Codex에게 반영시킬 수도 있습니다.

@codex update this PR.
리뷰어 의견대로 서버 오류 메시지를 그대로 노출하지 말고,
사용자에게는 일반화된 메시지만 보여줘.
그리고 관련 테스트를 추가해줘.

이때도 마찬가지로 결과를 그대로 믿지 않습니다. Codex가 후속 커밋을 푸시하면 다시 diff를 보고, 테스트를 보고, 리뷰 댓글이 해결되었는지 확인합니다.

좋은 흐름은 이렇습니다.

1. 사람이 이슈와 완료 기준을 쓴다.

2. Codex Cloud가 구현하고 PR을 만든다.

3. Codex 리뷰와 사람 리뷰가 문제를 찾는다.

4. Codex가 수정 커밋을 추가한다.

5. 사람이 최종 diff와 CI를 보고 병합한다.

AI가 일하는 속도를 가져가고, 사람은 판단과 책임을 유지하는 구조입니다.

GitHub CLI로 PR 작업을 터미널에서 처리하기

웹 화면이 편할 때도 있지만, 개발자는 터미널에서 작업 흐름을 이어 가고 싶을 때가 많습니다. GitHub CLI인 gh를 사용하면 이슈 확인, PR 생성, PR 보기, 체크 상태 확인을 터미널에서 처리할 수 있습니다.

처음 한 번은 로그인합니다.

gh auth login
gh auth status

현재 브랜치에서 PR을 만들려면 다음처럼 실행합니다.

gh pr create \
  --base main \
  --title "로그인 실패 메시지 개선" \
  --body-file pr.md

pr.md 파일을 미리 만들어 두면 PR 설명을 더 깔끔하게 작성할 수 있습니다.

## 요약

- 로그인 실패 시 사용자 안내 메시지 추가
- 서버 오류와 인증 실패 메시지 분리
- 실패 케이스 테스트 추가

## 테스트

- [x] npm test
- [x] npm run lint

## 관련 이슈

Closes #12

PR을 브라우저에서 열려면 다음 명령을 사용합니다.

gh pr view --web

현재 PR의 체크 상태를 보고 싶다면 다음처럼 확인할 수 있습니다.

gh pr checks

리뷰어의 댓글을 반영한 뒤 push하면 PR은 자동으로 업데이트됩니다.

git add .
git commit -m "test(auth): 로그인 실패 케이스 보강"
git push

Codex가 만든 브랜치도 결국 Git 브랜치입니다. 사람이 만든 브랜치와 똑같이 보고, 똑같이 검토하고, 똑같이 테스트해야 합니다.

CI/CD에 Codex Action 연결하기

조금 더 나아가면 GitHub Actions에서 Codex를 실행할 수도 있습니다. openai/codex-action은 GitHub Actions 워크플로 안에서 Codex CLI를 설치하고 실행할 수 있게 해 주며, OpenAI API 키 같은 값은 GitHub Secrets로 제공해야 합니다.³

처음부터 복잡한 자동 수정 봇을 만들 필요는 없습니다. 초보자에게 추천하는 첫 단계는 "PR이 열리면 Codex가 리뷰 코멘트를 남기는 워크플로"입니다. 예시는 다음과 같습니다.

name: Codex PR Review

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  codex-review:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v5
        with:
          ref: refs/pull/${{ github.event.pull_request.number }}/merge

      - name: Run Codex review
        id: codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          sandbox: read-only
          prompt: |
            이 PR의 변경 사항만 리뷰해줘.
            보안, 버그 가능성, 테스트 누락을 중심으로 봐줘.
            단순 포맷팅 문제는 지적하지 마.
            AGENTS.md의 Review guidelines를 따라줘.

      - name: Post Codex feedback
        if: steps.codex.outputs.final-message != ''
        uses: actions/github-script@v7
        env:
          CODEX_FINAL_MESSAGE: ${{ steps.codex.outputs.final-message }}
        with:
          script: |
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.payload.pull_request.number,
              body: process.env.CODEX_FINAL_MESSAGE,
            });

여기서 sandbox: read-only는 Codex가 파일을 수정하지 않고 읽기 중심으로 리뷰하도록 만드는 설정입니다. openai/codex-action은 샌드박스와 안전 전략을 제공하며, 기본적으로 권한을 줄이는 방식의 안전 설정도 지원합니다.³

중요한 점은 권한을 작게 시작하는 것입니다. 처음부터 contents: write 권한을 주고 자동 커밋까지 허용하면 편해 보이지만, 실수했을 때 영향도 커집니다. 처음에는 읽기와 코멘트 작성 정도로 시작하고, 팀이 충분히 신뢰할 수 있을 때 자동 수정 PR 같은 흐름으로 확장하는 편이 안전합니다.

Secrets는 절대 프롬프트에 쓰지 않는다

Codex Cloud나 GitHub Actions를 쓰다 보면 API 키, 데이터베이스 URL, 토큰 같은 비밀 값이 필요할 수 있습니다. 이때 절대 프롬프트에 직접 붙여 넣으면 안 됩니다.

나쁜 예는 다음과 같습니다.

@codex 배포 오류를 고쳐줘.
DATABASE_URL은 postgres://user:[email protected]/db 야.
OPENAI_API_KEY는 sk-... 야.

이런 방식은 피해야 합니다. 비밀 값은 GitHub Secrets, Codex 환경 변수, 배포 플랫폼의 시크릿 설정처럼 별도의 안전한 저장소에 넣어야 합니다. Codex에게는 "환경 변수 이름"만 알려 주면 됩니다.

@codex 배포 오류를 확인해줘.
DATABASE_URL과 OPENAI_API_KEY는 환경 변수로 제공된다고 가정해.
값을 코드나 로그에 출력하지 마.

AGENTS.md에도 다음 규칙을 넣어 두면 좋습니다.

## Security rules

- Never print secrets or environment variable values.
- Never commit `.env` files.
- Use environment variable names only in documentation.
- If a secret seems required, ask the maintainer instead of inventing one.

Codex를 원격 동료처럼 쓴다는 것은, 권한과 비밀 관리도 동료에게 맡길 때처럼 신중해야 한다는 뜻입니다.

로컬 수정과 Cloud 수정이 충돌하지 않게 하기

Codex Cloud를 쓰기 시작하면 새로운 문제가 생깁니다. 내가 로컬에서 파일을 고치는 동안 Cloud도 같은 파일을 고칠 수 있습니다. 두 사람이 같은 문서를 동시에 수정하면 충돌이 나는 것처럼, 로컬 Codex와 Codex Cloud도 같은 파일을 건드리면 충돌이 날 수 있습니다.

이 문제를 줄이는 기본 습관은 간단합니다.

git checkout main
git pull origin main

항상 최신 main에서 새 브랜치를 시작합니다.

git checkout -b feat/profile-settings

작업별로 브랜치를 분리합니다.

git checkout -b fix/login-error-message

Codex Cloud에 맡긴 작업이 있다면, 같은 파일을 로컬에서 동시에 크게 고치지 않는 것이 좋습니다. 꼭 병렬로 해야 한다면 10장에서 배운 git worktree를 사용합니다.

git worktree add ../my-app-login fix/login-error-message
git worktree add ../my-app-profile feat/profile-settings

이렇게 하면 같은 저장소를 서로 다른 폴더에서 서로 다른 브랜치로 열 수 있습니다. 하나는 로컬 Codex 작업용, 하나는 Cloud PR 검토용으로 나누면 훨씬 안전합니다.

PR이 병합된 뒤에는 로컬 main을 갱신하고 브랜치를 정리합니다.

git checkout main
git pull origin main
git branch -d fix/login-error-message

원격 브랜치까지 삭제했다면 로컬의 오래된 원격 참조를 정리합니다.

git fetch -p

이 작은 습관들이 쌓이면 Codex Cloud를 여러 번 써도 저장소가 지저분해지지 않습니다.

PR을 병합하기 전 마지막 체크리스트

Codex가 만든 PR이든 사람이 만든 PR이든 병합 전에는 같은 기준으로 확인해야 합니다. 특히 초보자는 "AI가 테스트를 돌렸다고 했으니 괜찮겠지"라는 마음을 조심해야 합니다. 말한 것과 실제 로그가 다를 수 있고, 테스트가 충분하지 않을 수도 있습니다.

병합 전에는 다음 질문에 답해 봅니다.

• 이 PR이 해결하려는 이슈나 목표가 명확한가?

• 변경 파일이 예상 범위를 벗어나지 않았는가?

• 보안, 권한, 개인정보와 관련된 위험은 없는가?

• 테스트, 린트, 빌드가 실제로 통과했는가?

• Codex 리뷰 또는 사람 리뷰에서 남은 미해결 댓글은 없는가?

• PR 설명만 읽어도 무엇이 바뀌었는지 이해할 수 있는가?

모두 괜찮다면 병합합니다. GitHub 웹 화면에서 Merge pull request를 눌러도 되고, 터미널에서 처리할 수도 있습니다.

gh pr merge --squash --delete-branch

squash는 PR 안의 여러 커밋을 하나로 합쳐 병합하는 방식입니다. 작은 프로젝트에서는 히스토리가 깔끔해져서 편합니다. 다만 팀 규칙이 있다면 그 규칙을 따르세요.

병합 후에는 로컬도 최신 상태로 맞춥니다.

git checkout main
git pull origin main

이제 Codex Cloud가 만든 변경이 내 로컬 프로젝트에도 반영되었습니다.

실전 워크플로: 작은 팀의 하루

마지막으로 하루 흐름으로 정리해 보겠습니다. 예를 들어 2명이 만드는 미니 SaaS 프로젝트가 있고, Codex Cloud를 원격 동료처럼 쓰기로 했다고 합시다.

아침에 개발자는 GitHub 이슈를 정리합니다. "결제 실패 시 안내 메시지 개선", "프로젝트 목록 테스트 추가", "README 배포 섹션 보강"처럼 작업을 작게 나눕니다.

짧은 UI 문구 수정은 로컬 Codex로 처리합니다.

결제 실패 토스트 문구를 더 친절하게 바꿔줘.
관련 파일만 수정하고 테스트는 건드리지 마.

테스트 보강처럼 시간이 걸리는 작업은 Codex Cloud에 맡깁니다.

@codex implement tests for the project list page.
빈 상태, 로딩 상태, API 실패 상태를 포함해줘.
pnpm test를 실행하고 결과를 PR에 남겨줘.

PR이 올라오면 자동 Codex 리뷰가 먼저 달립니다. 사람이 그 리뷰를 보고 중요한 지적을 확인합니다. 부족한 부분이 있으면 댓글로 다시 요청합니다.

@codex address the missing empty-state test.
그리고 테스트 이름을 한국어가 아니라 기존 스타일처럼 영어로 맞춰줘.

CI가 통과하고 사람이 diff를 확인하면 병합합니다. 병합 후 로컬 main을 pull하고, 다음 작업 브랜치를 만듭니다.

이 흐름이 익숙해지면 Codex는 더 이상 "가끔 코드를 만들어 주는 도구"가 아닙니다. 이슈를 받고, 브랜치에서 일하고, PR을 올리고, 리뷰를 받고, 수정하는 협업 흐름 안에 들어온 원격 동료가 됩니다.

이번 장에서 기억할 것

Codex Cloud와 GitHub를 연결하는 핵심은 자동화 자체가 아닙니다. 핵심은 로컬 파일 수정 중심에서 PR 중심 워크플로로 넘어가는 것입니다.

짧은 작업은 로컬 Codex로 빠르게 처리합니다. 긴 작업, 넓은 변경, 이슈 기반 구현, 테스트 보강, 문서화는 Codex Cloud에 맡깁니다. 하지만 어떤 경우에도 결과를 그대로 병합하지 않습니다. PR diff, 작업 요약, 로그, 테스트 결과, CI 상태를 함께 보고 의도한 변경인지 확인합니다.

@codex review와 자동 리뷰는 좋은 보조 리뷰어입니다. 다만 좋은 리뷰를 받으려면 AGENTS.md에 팀 규칙과 리뷰 기준을 구체적으로 써 두어야 합니다. GitHub Actions에 openai/codex-action을 연결하면 자동 검사 흐름도 만들 수 있지만, 처음에는 읽기 권한과 코멘트 중심으로 작게 시작하는 것이 안전합니다.

마지막으로 Git 기본 습관을 잊지 마세요. 작업 전 pull, 작업별 브랜치 분리, 필요할 때 worktree, PR 병합 후 브랜치 정리. 이 네 가지가 Codex Cloud 시대에도 저장소를 안전하게 지켜 줍니다.

다음 장에서는 Codex를 더 멀리 확장합니다. MCP, 플러그인, Skills를 이용해 Codex가 GitHub뿐 아니라 다른 도구와 지식까지 연결해 일하도록 만드는 방법을 살펴보겠습니다.

참고

¹Web - Codex | OpenAI Developers

²Code review in GitHub - Codex | OpenAI Developers

³openai/codex-action GitHub repository