Codex 사용기

들어가며

요즘 "AI로 못하는 게 없네"라는 말이 익숙해졌습니다. Cursor나 Claude Code처럼 AI가 개발에 자연스럽게 녹아든 도구들이 하나둘 등장하고 있고, 저 역시 그 흐름 속에서 OpenAI의 Codex를 알게 되었습니다. 마침 개인 블로그 프로젝트를 시작하던 참이라, 실험 삼아 Codex를 직접 써보기로 결심했습니다.

Codex는 단순한 GPT 플러그인이나 코드 자동 완성기가 아닙니다. 개발 흐름에 문서화와 사고 과정을 동시에 녹여낼 수 있는 도구입니다. 코드 창 옆에 문서 탭을 두고, 그 안에서 설계 의도를 적고, GPT의 제안을 바로 받아볼 수 있는 이 경험은, 단순한 개발을 넘어 '사유하는 개발'을 가능하게 합니다.

---

Codex 설정 및 레포지토리 연결 흐름

Codex를 본격적으로 사용하기 전에 가장 먼저 해야 할 일은 GitHub 레포지토리를 Codex에 연결하는 작업입니다. 처음에는 "GPT 기반 코드 어시스턴트"라고 해서 로컬 개발 환경의 연장선으로만 생각했지만, Codex는 클라우드 상에서 실제 레포를 읽고, 커밋과 PR까지 함께 관리할 수 있는 환경을 제공합니다.

아래는 Codex 초기 화면에서 레포지토리를 선택하는 UI입니다:

레포지토리를 선택하면, Codex는 해당 브랜치(main, develop, 혹은 feature/*) 기준으로 변경 사항을 추적하고, 대화창에 입력한 자연어 요청을 기반으로 코드 생성/수정/리팩토링/문서화/PR 작성 등의 작업을 직접 수행해줍니다.

예를 들어, “MDX 기반 블로그 글 목록 정렬 추가해줘”라고 요청하면,

• 관련 컴포넌트 파일을 자동으로 열어
• 날짜 기준 정렬 로직을 추가한 후
• 커밋 메시지까지 자동으로 제안해주고
• 원하면 PR까지 작성해줍니다

이 흐름은 단순한 편집기의 자동 완성 수준이 아니라, Git 워크플로우 전체를 포함하는 AI 파트너에 가깝다는 느낌을 주었습니다.

클라우드 vs 로컬 개발 환경

Codex는 개발 환경 설정 방식에서도 유연성을 제공합니다.

• 클라우드 기반 환경: OpenAI가 제공하는 Web IDE를 그대로 활용하면서 브라우저에서 바로 레포를 탐색하고 작업할 수 있습니다. 별도의 세팅 없이 바로 시작할 수 있다는 점에서 빠른 실험에 유리합니다.

---

Codex 사용 예시

1. 내가 원하는 바를 ChatGPT 사용하는 것 처럼 구체적으로 요청 한다.

2. Codex가 현재 환경을 컨테이너에서 설치하여 동일하게 세팅한다. 

3. 요구 사항에 확인이 필요한 내용에 대해서  레포지토리의 코드를 Codex가 읽고 판단한다. 

4. 필요한 패키지와 코드를 Codex가 설치하고 작성해준다. 

5. 작업 완료된 내용과 함께 해당 레포지토리로 브랜치를 만들고, 커밋을 추가하여 PR을 올린다. 

---

agents.md — Codex에게 나를 설명하는 문서

Codex를 처음 접하고 가장 먼저 만든 파일은 agents.md였습니다. 단순히 "React, TypeScript 좋아합니다"를 적는 문서가 아니라, Codex에게 저라는 개발자가 어떤 맥락과 스타일을 가지고 있는지를 알려주는 소개서였습니다.

최근 Toss에서 공개한 fundamentals.md를 참고해 다음과 같은 항목들을 정리했습니다

• 컴포넌트 원칙: 재사용보다 "의도 명확성"을 우선하며, 불필요한 추상화를 피합니다.
• 상태 관리 기준: 전역보다는 컴포넌트 로컬을 선호하되, 공유되는 상태는 단일 entry로 분리합니다.
• 스타일링: Tailwind + Shadcn UI 기반의 유틸리티 우선 접근, 필요 시 Radix 기반 커스터마이징
• 커밋 컨벤션: Airbnb 스타일의 type: 메시지 포맷을 사용하며, 개조식으로 상세 내역 정리
• PR 템플릿: 아래 항목 기준으로 작성
  • 🔍 이슈/배경
  • ✨ 변경사항 요약
  • ✅ 리뷰 포인트
  • 📸 UI 변화 (있다면)
  • 🧪 테스트 결과

Codex가 이 문서를 기반으로 PR 생성, 커밋 메시지 추천, 디렉토리 탐색을 보다 문맥 있게 수행하는 모습을 보면서, 단순한 코드 추천기를 넘어서는 가능성을 체감할 수 있었습니다.

---

Codex가 도와준 사례들

1. Tailwind v4 설정 중 PostCSS 오류 디버깅

Tailwind CSS v4에서는 postcss.config.js 설정 방식이 바뀌었는데, 저는 기존처럼 tailwindcss만 설정해놓고 계속 스타일이 적용되지 않아 헤매고 있었습니다. Codex에게 설정 파일을 열어보이며 설명을 요청하자, @tailwindcss/postcss를 plugin으로 등록해야 한다는 것을 짚어줬고, 공식 문서 링크까지 제시해주며 바로 수정할 수 있었습니다.

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

2. MDX 파일 기반 블로그 라우팅 구현

블로그 글들을 /posts/[slug] 형태로 렌더링하려 할 때, fs 모듈을 통해 .mdx 파일을 불러오고, 메타데이터를 추출해 정렬하는 작업이 필요했습니다. Codex는 이 과정에서:

• 메타데이터를 추출하는 getAllPosts() 함수 템플릿 제공
• slug 변환 로직 정리
• dynamic route에서 getStaticPaths 사용 시 주의할 점 정리

까지 단계별로 설명해주어, 구현 뿐 아니라 이해를 동반한 작업이 가능했습니다.

실제로 위와 같이 pr 까지 완료하면 작업 내용이 반영이 되는 것을 확인할 수 있었습니다. 아쉬운 점이라고 한다면 제가 agents.md에 작성을 해뒀음에도 불구하고 PR 내용이 제가 원하는 템플릿대로 작성이 안되는 것 같아서 이 부분은 추가로 찾아서 반영을 해봐야 될 것 같습니다. 

3. 다크모드 토글 커스터마이징

Radix UI + Tailwind 환경에서 useTheme() 훅을 사용해 system theme를 따르던 기존 구조를, 사용자가 명시적으로 dark/light를 선택할 수 있게 바꾸려 했습니다. Codex는 아래 세 가지를 조합해 동작하는 구조를 함께 설계해줬습니다:

• localStorage 연동
• classList 기반 Tailwind 다크모드
• hydration 오류 방지를 위한 조건 분기

그 결과, 초기 깜빡임 없는 사용자 제어형 다크모드 전환 기능을 완성할 수 있었습니다.

---

아쉬웠던 점 — 연관된 맥락을 다루는 능력은 아직 부족하다

Codex는 각 파일 단위의 문맥 이해력은 굉장히 뛰어났지만, 프로젝트 전반의 흐름을 유기적으로 파악하는 능력은 다소 부족했습니다.

예를 들어, A 기능을 구현하면서 그에 필요한 환경 설정이나 상태 구조를 B, C 문서에 동시에 나눠 작업하고 있을 때, Codex는 "B는 A와 연결되어 있다"는 사실을 자동으로 추론하진 못했습니다.

매번 저장된 순간의 context만 기준으로 판단하다보니, 동시성이나 연결성에 대한 고려는 사용자가 직접 문서로 명시해줘야 하는 구조였죠. 이는 아직까지 Codex가 한 명의 팀원처럼 전체 프로젝트 구조를 파악하진 못한다는 점을 보여줍니다.

이 점에서, 단일 편집기 맥락뿐 아니라 project graph 수준의 이해와 연결된 문서의 해석력을 키울 수 있다면, Codex는 진짜 "기획-설계-구현을 연결하는 파트너"로 진화할 수 있을 것입니다.

---

문서화와 개발을 동시에 한다는 것의 의미

Codex를 통해 느낀 가장 큰 변화는 코드를 짜기 전에 글을 먼저 쓰게 되었다는 것이었습니다.

• "왜 이 구조를 선택했는가?"
• "지금 무엇을 구현하려고 하는가?"
• "어떤 규칙을 따르고 있는가?"

이런 질문들을 먼저 글로 적어보는 과정이 생기고, 이를 기반으로 Codex와 대화를 시작하면서 코드를 작성하게 됩니다. 이 흐름 자체가 마치 작은 아키텍처 문서를 계속 써나가는 듯한 경험이었고, 개발자이자 문서 작성자라는 정체성을 스스로에게 더 명확히 새겨주는 계기가 되었습니다.

---

마무리하며 — 함께 일하는 AI, Codex

Codex는 아직 완벽하지는 않지만, 정말 같이 일하는 동료처럼 느껴지는 도구였습니다. 코드를 자동으로 써주는 도구가 아니라, 내가 왜 이렇게 생각했는지를 같이 고민해주는 친구이자, 내가 놓친 부분을 짚어주는 리뷰어에 가까웠습니다. 

그리고 제가 아직은 취업을 계속해서 도전하고 있는 개발자이지만, 만약 회사에서 근무하고 있다면 Codex는 퇴근 후에도 조용히 남아서 문서를 정리하고, 반복적인 코드를 리팩토링하고, 내가 놓쳤던 테스트 코드를 작성해주는 동료가 되어줄 수 있을 것 같다는 상상을 해봤습니다.

예를 들어 미국과 인도에 있는 동료들이 시차를 두고 작업을 이어가듯, Codex는 제가 하루를 마치고 잠든 동안에도 계속 프로젝트를 살펴줄 수 있을지도 모릅니다. 그런 의미에서 Codex는 단순한 AI 도구를 넘어, 제 하루를 연장해주는 파트너처럼 느껴졌습니다.