Quick Reference

체크포인트의 목적은 "깨끗해 보이는 Git 상태"가 아니라 작업 전 변경과 Codex가 만든 변경을 구분하는 것입니다. 기존 작업이 있으면 버리거나 덮어쓰지 말고, 의도에 맞는 기준점·branch·worktree를 먼저 선택합니다.

# 시작 전: 현재 변경을 먼저 읽는다.
git status --short
git diff --stat

# 작업 후: 새 변경의 범위와 내용을 읽는다.
git diff --check
git diff
git status --short

기준점을 만드는 방법

Codex CLI의 현재 quickstart는 task 전후 Git checkpoint를 만들고 되돌릴 수 있게 하라고 안내합니다. 하지만 checkpoint가 항상 "임시 커밋 하나"여야 하는 것은 아닙니다. 깨끗한 HEAD, 검토한 커밋, 또는 별도 worktree 중 무엇이 현재 변경을 가장 잘 보존하는지 선택합니다.

변경이 없고 단일 작업이다
-> 현재 HEAD를 시작점으로 기록하고 task 후 diff를 검토

관련 변경이 이미 완성됐다
-> 그 변경만 commit한 뒤 새 task의 diff를 분리

미완성 변경을 건드리면 안 된다
-> 현재 checkout은 그대로 두고 worktree에서 task 시작

commit을 만든다면 작업 목표를 숨기는 "misc" 대신 기준점을 설명하는 message를 씁니다. 반대로 shared branch에서 아직 검토되지 않은 변경을 임시 commit으로 밀어 넣는 것이 팀 규칙에 맞지 않으면, local branch나 worktree를 사용합니다. 기준점은 협업 규칙을 우회하는 수단이 아닙니다.

작업 후 읽는 순서

git diff --check는 공백 오류 같은 형식 문제를 빠르게 찾지만, 동작 검증을 대신하지는 않습니다. git diff로 수정 파일·API 변경·삭제를 읽고, task가 약속한 test나 build를 실행한 뒤 상태를 다시 확인합니다.

1. git diff --check    -> 형식상 깨진 부분 확인
2. git diff            -> 변경의 의도와 범위 확인
3. 관련 test/build     -> 동작 확인
4. git status --short  -> 남은 생성물·의도하지 않은 파일 확인
5. commit 또는 handoff -> 검토한 변경만 다음 단계로 이동

문제가 생겼을 때는 먼저 어떤 파일이 task 이전에도 수정돼 있었는지 확인합니다. 자신이 만든 새 파일·변경만 골라 되돌리는 것과, 기존 사용자 변경을 포함해 checkout 전체를 강제로 되돌리는 것은 전혀 다른 작업입니다. 후자는 명시적인 승인과 정확한 범위 없이는 수행하지 않습니다.

Worktree가 필요한 순간

Git worktree는 같은 Git metadata를 공유하면서도 별도 checkout에서 작업하게 합니다. ChatGPT desktop app의 Codex에서는 Git repository에서 Local과 Worktree chat을 나누고 handoff할 수 있습니다. Local을 방해하지 않고 병렬 chat을 돌리거나, 현재 dirty working tree를 보존해야 할 때 적합합니다.

Worktree를 고를 신호
- 현재 checkout의 미완성 변경을 건드릴 수 없다.
- 다른 agent 또는 사람이 같은 branch를 수정하고 있다.
- 두 구현 방식을 독립적으로 test해야 한다.

Worktree만으로 해결되지 않는 것
- branch 병합과 코드 review
- test 환경·secret·생성 파일의 검증
- 어떤 변경을 commit할지에 대한 판단

Codex의 worktree 생성·handoff 범위는 worktree와 handoff, 변경을 읽는 review 흐름은 검증과 리뷰 루프에서 이어서 확인할 수 있습니다.