Codex

빠른 선택
- IDE extension: 현재 열어 둔 파일을 바로 읽고 고칠 때
- CLI: 명령 실행, 로그 확인, 검증 루프를 자주 돌릴 때
- Codex app: 여러 프로젝트와 스레드를 병렬로 관리할 때
- Codex web: 긴 작업을 클라우드에서 백그라운드로 맡길 때

모드 선택
- Local: 현재 작업 디렉터리를 직접 수정
- Worktree: Git worktree로 변경을 격리
- Cloud: 원격 환경에서 병렬 실행

핵심 흐름
1. 새 스레드에서 Worktree 모드 선택
2. 시작 브랜치 선택
3. Codex가 별도 worktree 생성
4. 백그라운드에서 작업 진행
5. 필요하면 Handoff로 Local로 가져와 검증

나누는 기준
- 프로젝트: 작업 범위와 sandbox 경계
- 스레드: 하나의 목표와 대화 흐름
- Worktree: 같은 프로젝트 안 병렬 구현

추천 운영
- 저장소가 다르면 별도 프로젝트
- monorepo라도 앱이나 패키지 경계가 다르면 별도 프로젝트
- 같은 코드베이스 안의 다른 목표는 별도 스레드

git status
git add <related-files>
git commit -m "checkpoint before codex task"

# Codex 작업 후
git diff
git status

model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
model_reasoning_effort = "high"
personality = "friendly"

[profiles.review]
model_reasoning_effort = "high"
web_search = "disabled"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

클라우드 작업 순서
1. 컨테이너 생성 + 저장소 checkout
2. setup script 실행
3. 인터넷 접근 정책 적용
4. 에이전트가 명령 실행, 수정, 검증
5. 결과 diff와 답변 표시

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

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

# AGENTS.md

## Repo layout
- app/: 사용자 화면
- lib/: 공용 로직

## Run and test
- npm run build
- npm test

## Conventions
- 새 파일은 kebab-case
- 테스트가 가능하면 같이 추가

## Done when
- 관련 테스트 통과
- diff 검토 완료

탐색 순서의 큰 흐름
1. ~/.codex/AGENTS.override.md 또는 ~/.codex/AGENTS.md
2. 저장소 루트의 AGENTS.override.md 또는 AGENTS.md
3. 현재 작업 디렉터리까지 내려오며 더 가까운 AGENTS 파일

원칙
- 더 가까운 디렉터리 지침이 더 강합니다.
- 여러 파일은 root -> leaf 순서로 합쳐집니다.

Goal:
- 무엇을 바꿀지

Context:
- 관련 파일, 재현 절차, 현재 상태

Constraints:
- 건드리면 안 되는 API, 성능 조건, 스타일 규칙

Done when:
- 어떤 테스트와 어떤 결과가 나오면 끝인지

/plan

목표:
- 인증 모듈 리팩터링

계획에 꼭 포함할 것:
- 단계별 파일 이동 범위
- 각 단계의 검증 방법
- 롤백 전략
- 사용자 영향이 없는지 확인하는 기준

자주 쓰는 슬래시 명령
/status       현재 모델, 승인 정책, writable roots 확인
/permissions  권한 프리셋 변경
/compact      긴 대화 압축
/fork         현재 대화를 새 스레드로 분기
/resume       저장된 세션 이어서 작업
/mention      특정 파일을 대화에 붙이기

권장 사용 흐름
1. Codex app과 IDE를 같은 프로젝트로 연다
2. composer에서 `IDE context` 옵션을 확인한다
3. 현재 보고 있는 파일을 자연어로 가리키려면 `Auto context`를 켠다
4. 컨텍스트 포함 여부가 불확실하면 잠시 끄고 결과를 비교한다

통합 터미널 기본 흐름
1. Cmd+J 로 현재 스레드의 터미널을 연다
2. 테스트, 린트, git 상태 확인 같은 검증 명령을 실행한다
3. Codex에게 현재 터미널 출력 기준으로 다음 행동을 요청한다
4. 반복 명령이면 action 으로 승격한다

기억할 단축키
- Cmd+J: 터미널 열기/닫기
- Ctrl+L: 터미널 화면 지우기
- Cmd+K: 명령 팔레트

검증 루프
1. 재현 절차를 먼저 준다.
2. 최소 수정으로 고치게 한다.
3. 가장 작은 관련 테스트를 다시 돌리게 한다.
4. git diff를 검토한다.
5. 필요하면 /review로 한 번 더 점검한다.

GitHub에서 쓰는 기본 패턴
1. Codex Cloud를 설정한다.
2. 리포지터리에서 Code review를 켠다.
3. PR 댓글에 @codex review 를 남긴다.
4. 리뷰가 아니라 작업 위임이면 @codex 뒤에 작업을 적는다.

예:
@codex review
@codex fix the CI failures

앱 안 Git 검토 흐름
1. diff pane에서 변경 내용을 확인한다
2. 문제 줄에는 inline comment로 수정 방향을 남긴다
3. 괜찮은 부분만 chunk 단위로 stage 하거나 불필요한 부분은 revert 한다
4. 검증이 끝나면 app 안에서 commit, push, PR 생성까지 이어 간다
5. 복잡한 Git 작업은 통합 터미널로 넘긴다

역할 나누기
- AGENTS.md: 저장소 규칙과 기본 지침
- Skills: 반복 가능한 작업 절차 패키지
- MCP: 외부 시스템과 도구 연결
- Automations: 정기적으로 돌아가는 백그라운드 작업

README 기준 빠른 흐름
1. Unity에 패키지 설치
2. Unity에서 MCP for Unity 창 열기
3. 서버 시작 후 MCP 클라이언트 연결
4. 에이전트가 Unity 도구를 호출

핵심 포인트
- localhost:8080 기반 MCP 엔드포인트
- 에셋, 씬, 스크립트, 테스트, 콘솔 읽기까지 폭넓은 도구 제공
- 여러 Unity 인스턴스를 resource + tool로 선택 가능

unity-cli status
unity-cli editor play --wait
unity-cli console --filter all
unity-cli exec "Application.dataPath"

codex exec "summarize the repository structure"
codex exec --json "summarize the repository structure"
codex exec --ephemeral "triage this repository"
codex exec --output-schema ./schema.json -o ./result.json "Extract metadata"
codex exec resume --last "continue from the previous run"

안전한 자동화 순서
1. 일반 스레드에서 프롬프트를 수동 검증한다
2. 자동화로 승격한다
3. Git 저장소면 local 또는 worktree 실행 방식을 고른다
4. 첫 몇 회차는 Triage Inbox에서 결과를 집중 검토한다
5. 끝난 실행은 archive 해서 인박스와 worktree를 정리한다