Codex App으로 프로젝트 관리하기

Codex App은 채팅창이 아니라 개발 지휘실이다

Codex App을 처음 열면 많은 사람이 익숙한 채팅 화면을 떠올립니다. 가운데에 대화창이 있고, 아래에는 프롬프트를 입력하는 칸이 있으니 자연스러운 반응입니다. 하지만 Codex App을 단순한 "코딩용 채팅창"으로만 쓰면 가장 중요한 장점을 놓치게 됩니다.

Codex App의 진짜 역할은 AI 코딩 작업을 한곳에서 관리하는 개발 지휘실입니다. OpenAI의 Codex App 문서도 이 앱을 여러 Codex 스레드를 병렬로 다루고, 워크트리와 자동화, Git 기능을 포함한 데스크톱 경험으로 설명합니다.¹ 여기서 말하는 스레드는 하나의 대화이면서 동시에 하나의 작업 공간입니다. 예를 들어 같은 프로젝트 안에서 이런 식으로 작업을 나눌 수 있습니다.

• "로그인 버튼이 모바일에서 깨지는 문제 수정" 스레드

• "README 설치 방법 문서화" 스레드

• "할 일 목록 필터 기능 추가" 스레드

• "사용하지 않는 컴포넌트 정리" 스레드

이렇게 나누면 AI에게 일을 맡기는 방식이 훨씬 명확해집니다. 예전에는 ChatGPT 대화 하나에 기능 구현, 버그 수정, 문서 작성, 에러 로그 분석을 모두 쌓아 두기 쉬웠습니다. 그러다 보면 대화가 길어지고, Codex가 이전 지시와 새 지시를 섞어 이해하고, 사용자는 "지금 이 변경이 어떤 작업에서 나온 거지?" 하고 헷갈리게 됩니다.

Codex App에서는 반대로 생각해야 합니다. 하나의 프로젝트 폴더 안에 여러 목적별 스레드를 만들고, 각 스레드의 변경 사항을 Git과 diff로 검토한 뒤, 필요한 것만 채택한다. 이것이 App 중심 워크플로우의 핵심입니다.

초보자라면 처음부터 많은 기능을 모두 쓰려고 하지 않아도 됩니다. 우선 다음 흐름만 익히면 충분합니다.

1. 왼쪽에서 프로젝트를 고른다.

2. 가운데 스레드에서 Codex에게 작업을 요청한다.

3. 오른쪽 파일 패널에서 바뀐 파일을 확인한다.

4. 터미널에서 실행·테스트·빌드를 확인한다.

5. 브라우저나 미리보기에서 실제 화면을 본다.

6. Git 패널에서 diff를 검토하고 커밋한다.

이 장에서는 이 흐름을 하나씩 연결해 보겠습니다.

프로젝트는 "Codex가 들어갈 작업실"이다

Codex App에서 프로젝트는 보통 컴퓨터의 특정 폴더와 연결됩니다. 웹 앱을 만든다면 my-todo-app, weather-dashboard, mini-saas 같은 폴더가 프로젝트가 됩니다. Codex는 이 폴더 안의 파일을 읽고, 필요한 경우 수정하고, 명령을 실행합니다.

초보자가 가장 먼저 기억해야 할 원칙은 간단합니다. Codex에게 맡길 프로젝트는 반드시 Git으로 관리하는 폴더여야 합니다. Git은 코드의 변경 기록을 남기는 도구입니다. 실수했을 때 이전 상태로 되돌아갈 수 있게 해 주는 안전벨트라고 생각하면 됩니다.

프로젝트를 열기 전에 아래 상태를 확인해 보세요.

• git status를 실행했을 때 현재 변경 사항을 이해할 수 있다.

• 아직 Git 저장소가 아니라면 git init으로 초기화할 준비가 되어 있다.

• 중요한 파일, 예를 들어 .env, API 키, 개인 자료가 프로젝트 안에 섞여 있지 않다.

• README.md나 AGENTS.md에 실행 방법이 간단히 적혀 있다.

프로젝트 폴더를 선택했다면, 처음 스레드에서는 바로 "앱 만들어줘"라고 하지 않는 편이 좋습니다. 먼저 Codex가 이 작업실을 어떻게 이해하는지 확인해야 합니다.

예를 들어 이렇게 요청합니다.

이 프로젝트 폴더를 먼저 읽고 구조를 설명해 줘.
아직 파일은 수정하지 마.
다음 내용을 알려줘.
1. 어떤 기술 스택으로 보이는지
2. 앱을 실행하는 명령이 무엇인지
3. 주요 폴더와 파일의 역할
4. 초보자가 조심해야 할 파일

이 프롬프트는 안전합니다. 파일을 수정하지 말라고 했고, Codex에게 먼저 지도를 그리게 했기 때문입니다. 낯선 건물에 들어가자마자 벽을 허무는 사람은 없습니다. 먼저 출입구, 전기 스위치, 비상구를 확인합니다. Codex 프로젝트도 마찬가지입니다.

스레드는 작업 단위로 나눈다

Codex App에서 스레드는 대화이자 작업 흐름입니다. 하나의 스레드에 모든 일을 밀어 넣으면, 나중에 추적하기 어렵습니다. 초보자는 "프로젝트별로 하나의 대화만 있으면 되는 것 아닌가?"라고 생각하기 쉽지만, 실제 앱 개발에서는 목적별로 스레드를 나누는 편이 훨씬 안전합니다.

좋은 기준은 커밋 하나로 설명할 수 있는 일은 스레드 하나로 만든다입니다.

예를 들어 할 일 관리 앱을 만든다고 해 보겠습니다. 다음 작업들을 한 스레드에 모두 넣으면 복잡해집니다.

할 일 추가 기능 만들고, 삭제 기능도 만들고, 필터도 만들고,
디자인도 예쁘게 하고, README도 써 줘.

Codex가 열심히 일하더라도 결과물을 검토하기가 어렵습니다. 어떤 파일이 어떤 목적 때문에 바뀌었는지 한눈에 들어오지 않습니다. 더 좋은 방식은 다음처럼 나누는 것입니다.

스레드 A: 할 일 추가 기능 구현
스레드 B: 완료/미완료 필터 구현
스레드 C: 모바일 화면 스타일 개선
스레드 D: README 실행 방법 정리

각 스레드의 첫 요청도 작게 작성합니다.

목표: 할 일 추가 기능을 구현해 줘.
범위: src/components/TodoForm.tsx와 관련 상태 관리 파일만 수정해.
제약: 디자인 전체를 바꾸지 말고, 새 패키지는 설치하지 마.
완료 기준: 사용자가 입력 후 Enter 또는 추가 버튼을 누르면 목록에 새 할 일이 표시되어야 해.
수정 후 관련 테스트 또는 수동 확인 방법을 알려줘.

이런 식으로 쓰면 Codex는 무엇을 해야 하고, 무엇을 하지 말아야 하는지 분명히 알 수 있습니다. 이전 장에서 배운 목표, 맥락, 제약, 완료 기준이 App에서도 그대로 이어지는 셈입니다.

스레드 이름도 중요합니다. 가능하다면 스레드 제목을 "수정 부탁"처럼 애매하게 두지 말고, 작업 목적이 드러나게 관리하세요. 나중에 프로젝트가 커지면 스레드 목록이 작업 기록이 됩니다.

좋은 스레드 이름은 다음과 같습니다.

• fix-mobile-login-button

• add-todo-filter

• refactor-weather-api-client

• docs-update-install-guide

초보자에게 영어 이름이 부담스럽다면 한국어도 괜찮습니다. 핵심은 짧고 구체적인 것입니다. 버그 수정보다 모바일 로그인 버튼 위치 수정이 훨씬 좋습니다.

세 칸 레이아웃을 개발 흐름으로 읽기

Codex App의 화면은 보통 세 영역으로 이해하면 쉽습니다. 리서치 자료에서도 Codex App은 왼쪽에 프로젝트와 작업 목록, 가운데에 현재 채팅, 오른쪽에 파일·브라우저·터미널 같은 패널이 놓이는 구조로 설명됩니다.²

왼쪽은 어떤 프로젝트와 작업을 볼지 고르는 곳입니다. 프로젝트 목록, 스레드 목록, 자동화나 플러그인 진입점 등이 여기에 있습니다.

가운데는 Codex와 대화하며 지시를 내리는 곳입니다. 여기서 목표를 설명하고, 계획을 확인하고, 진행 중 방향을 수정하고, 결과 요약을 받습니다.

오른쪽은 실제 개발 결과를 검증하는 곳입니다. 파일 변경, diff, 터미널 실행 결과, 브라우저 미리보기, Git 상태 등을 확인합니다.

이 세 영역을 따로따로 보면 복잡하지만, 하나의 흐름으로 보면 간단합니다.

요청 → 코드 수정 확인 → 실행/테스트 → 화면 검증 → Git 리뷰

예를 들어 "날씨 대시보드의 카드 간격을 줄여 달라"는 작업을 맡긴다고 해 보겠습니다.

먼저 가운데 스레드에 요청합니다.

날씨 카드 사이의 세로 간격이 너무 넓어 보여.
관련 컴포넌트와 스타일 파일을 찾아서 간격을 조금 줄여 줘.
레이아웃 구조는 바꾸지 말고 spacing 값만 최소한으로 조정해.
수정 후 어떤 파일을 바꿨는지 설명해 줘.

Codex가 수정하면 오른쪽 파일 패널에서 어떤 파일이 바뀌었는지 봅니다. WeatherCard.tsx, Dashboard.css, tailwind.config.ts 같은 파일이 보일 수 있습니다. 여기서 예상하지 못한 파일, 예를 들어 package.json이나 인증 관련 파일이 바뀌었다면 멈춰야 합니다. 간격 수정에 새 패키지 설치나 인증 코드 변경은 보통 필요하지 않습니다.

그다음 터미널에서 개발 서버를 실행합니다.

npm run dev

브라우저 또는 미리보기 패널에서 화면을 확인합니다. 카드 간격이 정말 좋아졌는지, 모바일 화면에서도 깨지지 않는지 봅니다. 마지막으로 Git 패널에서 diff를 보고 "이 변경은 카드 간격 조정이라는 목적에 맞다"고 판단되면 커밋합니다.

이 과정은 느려 보이지만, 실제로는 AI가 빠르게 수정하기 때문에 전체 시간은 짧습니다. 사람이 해야 할 일은 모든 코드를 직접 쓰는 것이 아니라, AI가 한 일이 목적에 맞는지 판단하는 것입니다.

작업 상태를 보면 지금 무엇을 해야 하는지 알 수 있다

Codex App에서 여러 스레드를 동시에 돌리기 시작하면 가장 먼저 생기는 질문은 이것입니다.

"지금 어떤 작업이 진행 중이지?"

작업 상태를 읽을 줄 알면 혼란이 크게 줄어듭니다. 일반적으로 Codex App의 작업은 다음과 같은 상태로 이해할 수 있습니다.

Running 상태에서는 Codex가 아직 일하는 중입니다. 이때 계속 새 지시를 던지면 대화가 꼬일 수 있습니다. 단, Codex가 명백히 잘못된 방향으로 가고 있다면 기다리지 말고 바로 수정 지시를 줍니다.

예를 들어 Codex가 "간단한 CSS 수정" 요청을 받고 갑자기 UI 라이브러리를 설치하려 한다면 이렇게 말합니다.

방금 방향은 멈춰 줘.
새 패키지를 설치하지 말고 기존 CSS 또는 Tailwind 클래스만 사용해서 수정해.
변경 범위는 카드 컴포넌트와 스타일 파일로 제한해.

Waiting for approval은 특히 중요합니다. 이 상태는 Codex가 "이 행동은 사용자의 허락이 필요하다"고 판단했다는 뜻입니다. 초보자는 승인 버튼을 습관적으로 누르기 쉽지만, 승인 전에는 반드시 명령의 목적을 확인해야 합니다.

예를 들어 다음 명령은 비교적 흔합니다.

npm install
npm run dev
npm test
npm run build

각 명령의 의미를 간단히 이해하면 승인 판단이 쉬워집니다. npm install은 프로젝트에 필요한 패키지를 설치합니다. npm run dev는 개발 서버를 실행합니다. npm test는 테스트를 실행합니다. npm run build는 배포 가능한 결과물을 만들 수 있는지 확인합니다.

반면 아래와 같은 명령은 더 조심해야 합니다.

rm -rf dist
npm install some-new-package
git push origin main

rm -rf는 파일이나 폴더를 강제로 삭제할 수 있습니다. npm install some-new-package는 새 의존성을 추가합니다. git push origin main은 원격 저장소의 main 브랜치에 직접 코드를 올릴 수 있습니다. 상황에 따라 필요할 수 있지만, 초보자는 Codex에게 먼저 설명을 요구하는 편이 안전합니다.

이 명령을 실행하려는 이유와 영향을 설명해 줘.
어떤 파일이나 설정이 바뀔 수 있는지도 알려줘.
내가 승인하기 전에는 실행하지 마.

Completed가 보이면 일이 끝난 것처럼 느껴지지만, 실제로는 리뷰가 시작되는 시점입니다. Codex가 완료했다고 해서 프로젝트에 안전하게 반영되었다는 뜻은 아닙니다. 완료 후에는 반드시 파일 변경, 테스트 결과, 화면 결과, Git diff를 확인해야 합니다.

터미널은 "마법 버튼"이 아니라 검증 도구다

Codex App의 내장 터미널은 매우 편리합니다. 프로젝트를 실행하고, 테스트를 돌리고, 빌드 결과를 확인할 수 있습니다. 하지만 초보자에게 터미널은 동시에 위험해 보이는 영역이기도 합니다. 알 수 없는 글자가 빠르게 지나가고, 에러가 길게 나오면 겁이 납니다.

터미널을 어렵게 생각하지 마세요. 앱 개발에서 터미널은 주로 네 가지 일을 합니다.

• 필요한 패키지를 설치한다.

• 개발 서버를 실행한다.

• 테스트를 실행한다.

• 배포 전 빌드를 확인한다.

가장 많이 보게 될 명령은 다음과 같습니다.

Codex가 터미널 명령을 제안하면 바로 승인하지 말고, 이렇게 물어볼 수 있습니다.

이 명령은 무엇을 확인하기 위한 거야?
프로젝트 파일을 변경하니, 아니면 읽기/실행만 하니?
실패하면 어떤 정보를 보면 돼?

처음에는 번거롭게 느껴질 수 있지만, 몇 번만 반복하면 명령의 의미가 익숙해집니다. Codex가 단순히 코드를 써 주는 도구가 아니라, 개발 과정을 설명해 주는 선생님처럼 느껴지기 시작합니다.

실전에서는 터미널 결과를 다시 Codex에게 해석하게 하는 것도 좋습니다. 예를 들어 테스트가 실패했다면 에러 전체를 무작정 붙여 넣지 말고, 관련 부분만 전달합니다.

npm test를 실행했더니 TodoForm.test.tsx에서 실패했어.
아래 에러를 보고 원인을 설명해 줘.
아직 파일은 수정하지 말고, 가능한 수정 방향을 2가지로 제안해 줘.

[에러 메시지 붙여넣기]

중요한 점은 "바로 고쳐"가 아니라 "먼저 설명해 줘"입니다. 초보자는 Codex가 무엇을 고치려는지 이해한 뒤 승인하는 습관을 들여야 합니다.

브라우저와 미리보기 패널로 실제 화면을 확인한다

프론트엔드 작업에서는 코드가 맞아 보여도 화면이 이상할 수 있습니다. 간격이 깨지거나, 버튼이 화면 밖으로 밀리거나, 다크 모드에서 글자가 안 보일 수 있습니다. 이런 문제는 diff만 봐서는 알아차리기 어렵습니다.

Codex App의 내장 브라우저는 이 지점에서 강력합니다. OpenAI 문서에 따르면 Browser Use는 Codex가 앱 안의 브라우저를 직접 조작해 로컬 개발 서버와 파일 기반 미리보기를 확인하고, 클릭·입력·렌더링 상태 검사·스크린샷·수정 검증을 수행할 때 사용할 수 있습니다.³

쉽게 말해, Codex가 "코드만 보는 것"에서 한 걸음 나아가 "실제 화면을 보는 것"에 가까워집니다.

예를 들어 로그인 폼이 있다고 해 보겠습니다. 사용자는 이렇게 요청할 수 있습니다.

개발 서버를 실행한 뒤 로그인 페이지를 브라우저에서 확인해 줘.
이메일 입력칸, 비밀번호 입력칸, 로그인 버튼이 모바일 너비에서도 세로로 잘 배치되는지 봐 줘.
문제가 있으면 먼저 원인을 설명하고, 최소 수정안을 제안해 줘.

Codex가 브라우저를 사용할 수 있는 환경이라면, 로컬 페이지를 열고 화면 상태를 확인하는 흐름을 만들 수 있습니다. 사용자는 오른쪽 미리보기에서 직접 결과를 볼 수 있습니다.

UI 작업에서는 텍스트 설명보다 스크린샷이 훨씬 효과적일 때가 많습니다. "예쁘게 해 줘"는 너무 모호합니다. 대신 이렇게 말합니다.

첨부한 스크린샷을 기준으로 수정해 줘.
문제는 세 가지야.
1. 카드 제목과 본문 사이 간격이 너무 좁아.
2. 버튼이 오른쪽에 붙어 있어서 답답해 보여.
3. 모바일에서 카드 그림자가 너무 강해.

새 라이브러리는 설치하지 말고 기존 CSS만 조정해.
수정 후 브라우저에서 다시 확인해 줘.

이 프롬프트는 화면 문제를 구체적으로 짚습니다. Codex가 추측할 공간이 줄어듭니다.

브라우저 패널을 쓸 때도 안전 원칙은 같습니다. 로컬 개발 서버나 테스트용 페이지는 비교적 안전하지만, 실제 계정, 결제, 관리자 화면이 관련된 작업은 조심해야 합니다. 로그인된 브라우저 상태가 필요한 외부 사이트 작업에는 Codex Chrome extension을 사용할 수 있는데, 공식 문서는 LinkedIn, Salesforce, Gmail, 내부 도구처럼 로그인 상태가 필요한 사이트에서 Chrome을 사용하게 할 때 활용한다고 설명합니다.⁴ 이런 작업은 편리하지만 계정과 개인정보가 얽히므로, 초보자는 반드시 옆에서 확인하면서 진행하는 편이 좋습니다.

파일 패널에서는 "무엇이 바뀌었는지"부터 본다

Codex가 작업을 마친 뒤 가장 먼저 볼 곳은 요약 문장이 아닙니다. 요약은 도움이 되지만, 최종 근거는 아닙니다. 진짜 근거는 파일 변경 사항입니다.

파일 패널에서는 다음 순서로 확인합니다.

1. 어떤 파일이 바뀌었는가?

2. 내가 요청한 범위 안의 파일인가?

3. 새 파일이나 삭제된 파일이 있는가?

4. 설정 파일이나 잠금 파일이 바뀌었는가?

5. 변경량이 작업 크기에 비해 과하지 않은가?

예를 들어 "버튼 문구를 바꿔 줘"라고 했는데 package-lock.json, vite.config.ts, src/api/auth.ts가 바뀌었다면 이상합니다. 버튼 문구 변경에 그런 파일들이 필요할 가능성은 낮습니다. 이때는 Codex에게 바로 물어봅니다.

내 요청은 버튼 문구 변경이었는데 package-lock.json과 vite.config.ts가 바뀐 이유가 뭐야?
필요 없는 변경이라면 되돌려 줘.

반대로 "날씨 API 호출 로직을 분리해 줘"라고 했다면 src/api/weather.ts, src/hooks/useWeather.ts, 관련 테스트 파일이 바뀌는 것은 자연스럽습니다.

초보자는 diff의 모든 코드를 완벽하게 이해하지 못해도 됩니다. 처음에는 "파일 목록"만 잘 봐도 큰 사고를 줄일 수 있습니다. AI가 엉뚱한 영역을 건드렸는지 확인하는 것만으로도 충분히 가치가 있습니다.

Git 패널은 Codex 결과를 받아들이기 전 마지막 관문이다

Git 패널은 Codex App을 개발 지휘실로 만들어 주는 핵심 요소입니다. Codex가 만든 변경을 그대로 믿고 저장소에 반영하는 대신, 파일별로 보고, diff를 확인하고, 필요한 것만 스테이지하고, 의미 있는 커밋으로 남길 수 있습니다.

여기서 diff라는 단어가 중요합니다. diff는 "변경 전과 변경 후의 차이"입니다. Codex가 실제로 무엇을 바꿨는지 보여 주는 증거입니다.

초보자는 커밋을 너무 크게 만들기 쉽습니다.

커밋 1개:
- 로그인 버그 수정
- 버튼 디자인 변경
- README 수정
- 패키지 업데이트
- 테스트 추가

이렇게 하면 나중에 문제가 생겼을 때 어떤 변경이 원인인지 찾기 어렵습니다. 가능하면 커밋은 작은 의미 단위로 나눕니다.

커밋 1: fix login button layout on mobile
커밋 2: add todo filter tests
커밋 3: update README setup guide

Git 패널에서 변경 파일을 확인할 때는 다음 질문을 던져 보세요.

• 이 변경은 현재 스레드의 목표와 직접 관련이 있는가?

• 되돌려도 되는 실험성 변경이 섞여 있지 않은가?

• 테스트 파일이 함께 추가되거나 수정되었는가?

• 설정 파일 변경이 있다면 이유가 설명되었는가?

• 커밋 메시지 한 줄로 설명할 수 있는가?

커밋 메시지는 Codex에게 초안을 맡길 수 있습니다. 다만 그대로 쓰기 전에 의미를 확인해야 합니다.

이번 변경에 맞는 커밋 메시지를 3개 제안해 줘.
너무 과장하지 말고, 실제 변경 범위를 기준으로 작성해.
형식은 다음 중 하나로 해 줘.
- feat: ...
- fix: ...
- docs: ...
- refactor: ...

예를 들어 결과는 이렇게 나올 수 있습니다.

fix: correct mobile spacing in login form
feat: add completed filter to todo list
docs: update local development setup guide

여기서 중요한 것은 feat, fix, docs, refactor 같은 접두사가 멋있어 보이기 때문이 아닙니다. 커밋의 성격을 짧게 분류하면 나중에 변경 기록을 읽기 쉬워집니다.

워크트리는 병렬 작업을 위한 안전 칸막이다

Codex App의 큰 장점 중 하나는 여러 스레드를 병렬로 다룰 수 있다는 점입니다. 하지만 동시에 여러 AI 작업이 같은 코드를 수정하면 충돌이 날 수 있습니다.

예를 들어 스레드 A는 TodoList.tsx에 필터 기능을 추가하고, 스레드 B는 같은 TodoList.tsx의 디자인을 바꾼다고 해 보겠습니다. 두 작업이 같은 파일의 같은 부분을 수정하면, 나중에 합칠 때 Git 충돌이 생길 수 있습니다. 충돌은 두 변경이 서로 겹쳐서 Git이 자동으로 합칠 수 없는 상태를 말합니다.

이 문제를 줄이기 위해 사용하는 것이 워크트리입니다. 워크트리는 하나의 Git 저장소에서 별도의 작업 폴더를 만들어 서로 다른 브랜치를 동시에 작업할 수 있게 해 주는 기능입니다. 쉽게 말해 같은 프로젝트의 복사된 작업 책상을 여러 개 만드는 것입니다.

비유해 보겠습니다. 하나의 책상 위에 두 사람이 동시에 같은 설계도를 고치면 종이가 찢어질 수 있습니다. 하지만 같은 설계도를 복사해 각자 다른 책상에서 수정한 뒤, 마지막에 비교하며 합치면 훨씬 안전합니다. 워크트리가 바로 이 역할을 합니다.

Codex App의 워크트리 기반 작업 방식은 다음 상황에서 특히 유용합니다.

• 한 스레드는 버그를 고치고, 다른 스레드는 문서를 수정할 때

• 현재 main 작업 환경을 깨뜨리지 않고 실험 기능을 만들어 볼 때

• 오래 걸리는 리팩터링을 백그라운드에서 돌리면서 작은 수정은 따로 진행할 때

• 같은 저장소에서 여러 대안을 비교해 볼 때

하지만 워크트리가 있다고 해서 충돌이 완전히 사라지는 것은 아닙니다. 같은 파일의 같은 줄을 여러 스레드가 고치면 여전히 충돌이 생길 수 있습니다. 다만 작업 중 서로의 파일을 덮어쓰는 위험이 줄어들고, 나중에 Git diff와 merge 과정에서 차분히 비교할 수 있습니다.

초보자는 병렬 작업을 시작할 때 다음 규칙을 지키면 좋습니다.

1. 같은 파일을 건드릴 가능성이 큰 작업은 동시에 맡기지 않는다.

2. 각 스레드의 목표와 수정 범위를 명확히 적는다.

3. 완료된 스레드는 바로 diff를 확인하고 필요 없는 변경을 정리한다.

4. 하나의 작업을 병합하기 전 다른 스레드 결과와 겹치는지 확인한다.

예를 들어 다음 두 스레드는 동시에 돌려도 비교적 안전합니다.

스레드 A: README에 로컬 실행 방법 추가
스레드 B: TodoItem 컴포넌트의 체크박스 접근성 개선

반면 다음 두 스레드는 충돌 가능성이 높습니다.

스레드 A: TodoList 컴포넌트 구조 리팩터링
스레드 B: TodoList 컴포넌트에 필터 기능 추가

이런 경우에는 먼저 리팩터링을 끝내고 커밋한 뒤, 그다음 필터 기능을 추가하는 편이 안전합니다.

실전 예제: 할 일 앱을 Codex App으로 관리하기

이제 실제로 작은 앱 개발 흐름을 상상해 보겠습니다. 프로젝트는 todo-app이고, 목표는 할 일 관리 앱을 조금씩 완성하는 것입니다.

첫 번째 스레드는 프로젝트 파악용입니다.

이 프로젝트를 읽고 구조를 설명해 줘.
아직 파일은 수정하지 마.
앱 실행 명령, 주요 컴포넌트, 상태 관리 방식, 테스트 명령을 정리해 줘.

Codex가 src/App.tsx, src/components/TodoList.tsx, package.json 등을 읽고 설명합니다. 이 설명이 맞아 보이면 다음 스레드를 만듭니다.

두 번째 스레드는 기능 구현입니다.

목표: 할 일을 완료/미완료로 필터링하는 기능을 추가해 줘.
범위: TodoList와 관련 컴포넌트만 수정해.
제약: 새 패키지는 설치하지 마. 기존 스타일 구조를 유지해.
완료 기준: 전체, 진행 중, 완료됨 버튼으로 목록이 필터링되어야 해.
수정 후 npm test 또는 수동 확인 방법을 알려줘.

Codex가 작업을 완료하면 파일 패널을 봅니다. 예상 파일은 TodoList.tsx, TodoFilter.tsx, TodoList.test.tsx 정도입니다. 만약 package.json이 바뀌었다면 이유를 확인합니다.

그다음 터미널에서 테스트를 실행합니다.

npm test

테스트가 통과하면 브라우저에서 개발 서버를 엽니다.

npm run dev

화면에서 전체, 진행 중, 완료됨 버튼을 눌러 봅니다. 필터가 제대로 작동하면 Git 패널로 이동합니다. diff를 보고 커밋합니다.

feat: add todo status filter

세 번째 스레드는 문서화입니다.

README에 방금 추가된 필터 기능 사용 방법을 짧게 추가해 줘.
설치 방법이나 기술 스택 설명은 바꾸지 마.
변경 범위는 README.md로 제한해.

이 스레드는 코드가 아니라 문서만 바꾸므로 별도 커밋으로 남깁니다.

docs: document todo filter usage

이렇게 작업하면 프로젝트 기록이 깔끔해집니다. Codex가 많은 일을 해도, 사용자는 각 변경의 의미를 추적할 수 있습니다.

실전 예제: 날씨 대시보드 화면 검증하기

이번에는 브라우저 패널을 활용하는 예입니다. weather-dashboard 프로젝트에서 날씨 카드가 데스크톱에서는 괜찮지만 모바일에서는 너무 좁게 보인다고 합시다.

먼저 스레드를 만듭니다.

날씨 대시보드의 모바일 레이아웃을 점검해 줘.
개발 서버를 실행하고 브라우저에서 화면을 확인해.
문제가 있으면 바로 수정하지 말고 먼저 문제 목록과 수정 계획을 제안해 줘.

이 요청은 바로 수정하지 말라고 했기 때문에 안전합니다. Codex가 화면을 확인한 뒤 이런 식으로 말할 수 있습니다.

문제:
1. 360px 너비에서 카드 내부 padding이 커서 온도 텍스트가 줄바꿈됩니다.
2. 날씨 아이콘과 설명 텍스트 사이 간격이 좁습니다.
3. 하단 예보 리스트가 가로 스크롤 없이 압축됩니다.

제안:
- 모바일 구간에서 카드 padding을 줄입니다.
- 아이콘 영역에 최소 너비를 지정합니다.
- 예보 리스트는 작은 화면에서 세로 배치로 전환합니다.

이제 사용자가 승인합니다.

좋아. 제안한 1번과 3번만 반영해 줘.
2번은 지금 수정하지 마.
새 패키지는 설치하지 말고 CSS만 수정해.
수정 후 브라우저에서 360px 기준으로 다시 확인해 줘.

이처럼 계획을 받은 뒤 일부만 선택할 수 있습니다. Codex를 쓰면 모든 제안을 받아들여야 한다고 생각하기 쉽지만, 실제로는 사용자가 편집장입니다. 필요한 것만 채택하면 됩니다.

수정이 끝나면 파일 패널에서 CSS 파일 변경을 보고, 브라우저에서 모바일 화면을 확인하고, Git 패널에서 커밋합니다.

fix: improve weather dashboard mobile layout

실전 예제: 버그 수정 스레드와 리팩터링 스레드 분리하기

앱 개발 중에는 "버그를 고치다 보니 코드가 지저분해서 리팩터링도 하고 싶다"는 순간이 자주 옵니다. 여기서 초보자가 많이 하는 실수는 버그 수정과 리팩터링을 한 번에 맡기는 것입니다.

예를 들어 로그인 후 대시보드로 이동하지 않는 버그가 있다고 합시다.

나쁜 요청은 이렇습니다.

로그인 버그 고치고 auth 코드도 깔끔하게 리팩터링해 줘.

이 요청은 범위가 넓습니다. 버그 수정 때문에 바뀐 것인지, 리팩터링 때문에 바뀐 것인지 구분하기 어렵습니다.

더 좋은 방식은 스레드를 나누는 것입니다.

먼저 버그 수정 스레드입니다.

목표: 로그인 성공 후 대시보드로 이동하지 않는 버그를 고쳐 줘.
범위: 인증 흐름과 라우팅 관련 파일만 확인해.
제약: 구조 리팩터링은 하지 마. 동작을 고치는 최소 변경만 해.
완료 기준: 로그인 성공 시 /dashboard로 이동해야 해.
수정 후 원인, 변경 내용, 확인 방법을 알려줘.

이 작업이 끝나고 테스트 또는 수동 검증을 통과하면 커밋합니다.

fix: redirect to dashboard after login

그다음 별도 리팩터링 스레드를 만듭니다.

방금 로그인 버그 수정은 유지한 상태에서 auth 관련 코드의 중복을 줄이는 리팩터링 계획을 제안해 줘.
아직 수정하지 마.
기능 동작이 바뀌면 안 되고, 변경 파일과 위험도를 함께 설명해 줘.

계획을 보고 승인한 뒤 리팩터링합니다. 이렇게 하면 문제가 생겼을 때 버그 수정 커밋은 유지하고, 리팩터링 커밋만 되돌릴 수 있습니다.

Codex App은 이런 분리에 적합합니다. 스레드를 목적별로 나누고, Git 패널로 커밋을 나누면 AI 작업이 프로젝트 관리 흐름 안으로 들어옵니다.

승인 요청을 만났을 때의 초보자 체크리스트

Codex가 Waiting for approval 상태가 되면 긴장할 필요는 없습니다. 다만 습관적으로 승인하지도 마세요. 아래 질문에 답할 수 있으면 승인해도 좋습니다.

• 이 명령은 왜 필요한가?

• 파일을 수정하는가, 실행만 하는가?

• 프로젝트 폴더 밖에 영향을 주는가?

• 네트워크를 사용하거나 새 패키지를 설치하는가?

• Git 원격 저장소에 push하는가?

• 실패해도 되돌릴 수 있는가?

만약 답을 모르겠다면 Codex에게 물어보면 됩니다.

승인하기 전에 이 명령의 목적과 영향 범위를 초보자도 이해할 수 있게 설명해 줘.
위험한 점이 있다면 대안 명령도 제안해 줘.

특히 다음 작업은 신중해야 합니다.

초보자에게 가장 좋은 기본값은 보수적인 권한입니다. 처음에는 Codex가 읽고 계획하고, 사용자가 승인한 뒤 수정하게 하세요. 익숙해진 다음에 작은 작업부터 자동화 범위를 넓히면 됩니다.

프로젝트 관리 루틴 만들기

Codex App을 잘 쓰는 사람과 그렇지 않은 사람의 차이는 도구 지식보다 루틴에서 갈립니다. 매번 즉흥적으로 요청하면 결과도 즉흥적입니다. 반대로 일정한 흐름을 만들면 Codex가 프로젝트 안에서 안정적으로 일합니다.

추천 루틴은 다음과 같습니다.

1. 새 작업마다 새 스레드를 만든다.
2. 목표, 범위, 제약, 완료 기준을 적는다.
3. 큰 작업은 먼저 계획만 받는다.
4. Codex가 수정한 파일 목록을 확인한다.
5. 터미널에서 테스트 또는 빌드를 실행한다.
6. 브라우저/미리보기로 실제 화면을 본다.
7. Git 패널에서 diff를 검토한다.
8. 작은 의미 단위로 커밋한다.
9. 완료된 스레드는 요약을 남긴다.

스레드 마지막에는 이렇게 정리하게 할 수 있습니다.

이번 작업을 다음 형식으로 요약해 줘.
- 목표
- 변경 파일
- 주요 변경 내용
- 실행한 검증 명령
- 남은 TODO
- 추천 커밋 메시지

이 요약은 나중에 PR 설명, 이슈 댓글, 작업 일지로 활용할 수 있습니다. 1인 개발자에게도 유용하고, 팀 프로젝트에서는 더 중요합니다.

이슈를 쓰는 팀이라면 스레드 첫 요청에 이슈 번호를 넣어도 좋습니다.

이 작업은 GitHub Issue #42와 관련 있어.
목표는 모바일 로그인 버튼 위치를 수정하는 거야.
변경 후 커밋 메시지와 PR 설명에 #42를 연결할 수 있게 요약해 줘.

이렇게 하면 Codex가 만든 변경이 프로젝트 관리 시스템과 이어집니다. AI 작업이 "어딘가에서 나온 코드"가 아니라, 이슈와 커밋과 PR로 추적되는 작업이 됩니다.

App과 IDE를 함께 쓸 때의 역할 분담

Codex App은 강력하지만, 모든 코드를 직접 손으로 편집하기에 가장 좋은 도구는 아닐 수 있습니다. 세밀한 수동 편집은 VS Code, Cursor, Windsurf 같은 IDE가 더 편할 때가 많습니다.

역할을 나누면 좋습니다.

예를 들어 Codex가 만든 코드가 거의 맞지만 변수명 하나가 마음에 들지 않는다면, 굳이 다시 프롬프트를 보내지 않고 IDE에서 직접 고쳐도 됩니다. 반대로 여러 파일에 걸친 반복 수정이나 테스트 실패 원인 분석은 Codex에게 맡기는 편이 빠릅니다.

중요한 것은 도구 싸움이 아닙니다. Codex App은 작업을 지휘하고 검토하는 곳, IDE는 사람이 직접 세밀하게 만지는 곳으로 생각하면 자연스럽습니다.

이 장에서 가져갈 핵심

Codex App을 잘 쓰면 여러 AI 작업이 흩어진 채팅이 아니라 하나의 개발 지휘실 안에 정리됩니다. 왼쪽 프로젝트 목록에서 작업을 고르고, 가운데 스레드에서 지시하고, 오른쪽 패널에서 파일·터미널·브라우저·Git 상태를 확인하는 흐름을 만들 수 있습니다.

초보자에게 가장 중요한 습관은 세 가지입니다. 첫째, 스레드를 작업 단위로 나누세요. 둘째, Codex가 만든 변경을 diff와 실행 결과로 확인하세요. 셋째, 작은 커밋으로 기록을 남기세요.

Codex App은 AI에게 일을 맡기는 도구이지만, 최종 판단은 여전히 사용자에게 있습니다. 바로 그 점 때문에 Git 패널, 파일 패널, 터미널, 브라우저가 중요합니다. Codex가 빠르게 움직일수록 사용자는 더 좋은 지휘자가 되어야 합니다.

다음 장에서는 이 흐름을 터미널 중심으로 확장해 Codex CLI의 필수 사용법을 익힙니다. App이 개발 지휘실이라면, CLI는 가장 빠르게 명령을 내리고 자동화 흐름을 만들 수 있는 작업 도구입니다.

참고

¹App - Codex | OpenAI Developers

²Codex App Beginner Guide: Installation, Sandbox, Parallel Tasks, Skills, and MCP

³In-app browser - Codex app | OpenAI Developers

⁴Codex Chrome extension - Codex app | OpenAI Developers