빠른 설정

로컬 환경이 담당하는 것
- setup script: 새 Worktree 준비
- action: 자주 쓰는 명령을 상단 버튼으로 등록
- platform override: macOS, Windows, Linux별 스크립트 분기

공유 규칙
- 설정은 프로젝트 루트의 .codex 아래에 둔다
- monorepo에서는 해당 .codex 가 있는 프로젝트 디렉터리를 열어야 한다

로컬 준비

setup script는 Worktree 격리의 부작용을 메우는 보완 장치다

Local environments는 Codex app에서 프로젝트마다 반복되는 준비 작업을 정리하는 층입니다. setup script는 새 Worktree가 만들어질 때 자동으로 실행됩니다. Worktree는 별도 Git 체크아웃이므로, 의존성 설치나 초기 빌드, 생성 파일 준비처럼 "격리된 디렉터리에서는 빠지기 쉬운 준비 단계"를 놓치는 경우가 생깁니다. setup script는 이 간격을 자동으로 메워 주기 때문에, Worktree를 만들 때마다 같은 환경을 일관되게 유지할 수 있습니다.

# setup script 예시
npm install
npm run build

action이 반복 검증 명령을 단축 버튼으로 고정하는 이유

action은 개발 서버 실행, 테스트 실행, 린트 실행처럼 자주 쓰는 명령을 상단 버튼으로 올려 두는 기능입니다. 반복 명령을 매번 다시 입력하지 않아도 되고, 실행 위치도 통합 터미널과 자연스럽게 연결됩니다. 일회성 디버깅 명령은 터미널에서 직접 실행하고, 세션마다 반복되는 검증 명령은 action으로 올리는 식으로 역할을 나누면 전체 흐름이 안정됩니다.

# action 예시
npm test

.codex 설정을 저장소에 커밋하면 팀 전체 작업 흐름이 일치한다

이 설정은 프로젝트 루트의 .codex 폴더에 저장하고, 필요하면 저장소에 커밋해 팀과 공유할 수 있습니다. .codex를 커밋하면 새 팀원이 프로젝트를 열었을 때 같은 setup script와 action이 자동으로 적용됩니다. "로컬에서는 잘 됐는데 다른 사람 Worktree에서 안 된다"는 문제를 줄이는 효과적인 방법입니다. 다만 개인 취향에 해당하는 action은 커밋하지 말고 로컬에만 두는 편이 팀 설정과 개인 설정을 분리하기 좋습니다.

현재 공식 문서 기준으로 local environments는 Codex app settings pane에서 설정하고, 생성된 파일은 프로젝트 루트의 .codex 폴더에 저장됩니다. 저장소 안에 프로젝트가 여러 개 있으면 공유 .codex가 들어 있는 프로젝트 디렉터리를 열어야 설정이 제대로 읽힙니다.

platform override로 운영체제마다 다른 준비 단계를 분기한다

macOS, Windows, Linux에서 명령 문법이 다르거나 도구 경로가 달라지는 경우, platform override를 이용해 운영체제별로 다른 스크립트를 지정할 수 있습니다. 이 기능이 없으면 팀 내에 다른 운영체제를 쓰는 사람이 있을 때 setup script를 공유하기 어렵습니다. platform override를 쓰면 같은 .codex 설정을 커밋하면서도 각자 환경에 맞는 준비 절차가 자동으로 실행됩니다.

setup script와 action을 나누는 기준
- 새 Worktree 가 생길 때 자동 준비해야 하는 것: setup script
- 사람이 눌러 실행하는 반복 검증 명령: action
- OS 별로 명령이 달라질 때: platform override

언제 자동화할까

주의할 점

실패 예시
- npm test 를 setup script 에 넣어 Worktree 생성 때마다 무거운 테스트가 자동 실행되게 함
- 결과: 준비 시간이 길어지고, 단순 환경 준비와 반복 검증이 섞여 Worktree 생성이 불안정해짐
- 대응: 자동 준비는 setup script, 반복 검증은 action 으로 분리한다