핵심 정리

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

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

나누는 기준

프로젝트는 sandbox 경계이고, 그 경계가 컨텍스트 품질을 결정한다

Codex app에서 프로젝트는 "이 디렉터리 안에서 작업한다"는 작업 범위이자 sandbox 경계입니다. 프로젝트를 너무 크게 잡으면 sandbox 범위가 넓어지고 간접 컨텍스트도 함께 넓어집니다. 반대로 실제 작업 단위와 맞게 나누면 Codex가 읽어야 할 파일 범위가 좁아지고, 엉뚱한 파일을 참조하는 실수가 줄어듭니다. monorepo에서는 "저장소 하나 = 프로젝트 하나"로 고정하지 말고 실제 작업 단위로 나누는 편이 더 안정적입니다.

스레드는 단일 목표를 갖는 대화와 변경 흐름이다

스레드는 프로젝트 안에서 하나의 목표를 수행하는 작업 단위입니다. 버그 수정, 문서화, 리팩터링처럼 목표가 다르면 스레드를 나누는 편이 대화와 diff를 추적하기 쉽습니다. 하나의 스레드에서 여러 목표를 섞으면 대화가 길어지고 Codex가 어느 맥락에서 수정하는지 불분명해집니다. 짧고 명확한 스레드를 여러 개 운영하는 것이 긴 단일 스레드보다 검토하기 쉽습니다.

monorepo에서 프로젝트 분리가 필요한 트레이드오프

공식 문서는 monorepo에서도 성격이 다른 앱이나 패키지를 별도 프로젝트로 여는 방식을 권합니다. 그래야 sandbox가 필요한 파일만 포함하고, 컨텍스트도 더 좁고 정확하게 유지됩니다. 다만 프로젝트를 분리하면 두 앱 사이의 공유 코드를 수정할 때 어느 프로젝트에서 작업해야 하는지 결정해야 합니다. 이 트레이드오프를 이해하고 실제 의존 관계를 기준으로 경계를 정하는 것이 중요합니다.

monorepo 예시
- apps/web 수정: web 프로젝트
- apps/api 성능 점검: api 프로젝트
- 같은 web 코드베이스에서 두 접근을 병렬 실험:
  web 프로젝트 안에서 스레드 2개 또는 Worktree 2개

Worktree는 프로젝트 분리 없이 병렬 작업을 가능하게 한다

같은 프로젝트 안에서 서로 독립적인 구현을 동시에 돌리고 싶다면, 새 프로젝트를 만드는 대신 Worktree 스레드를 추가하는 편이 자연스럽습니다. Worktree는 Git worktree 위에서 별도 체크아웃을 만들기 때문에 현재 Local 작업을 건드리지 않고 병렬로 다른 작업을 진행할 수 있습니다.

프로젝트 / 스레드 / Worktree를 고르는 기준
- 프로젝트: sandbox 경계와 기본 컨텍스트를 분리할 때
- 스레드: 같은 프로젝트 안에서 목표만 나눌 때
- Worktree: 같은 프로젝트 안에서 구현을 병렬로 실험할 때

언제 분리할까

주의할 점

실패 예시
- web 프로젝트 안에서 API 성능 점검, 디자인 수정, 배포 스크립트 정리를 한 스레드에 몰아넣음
- 결과: 대화가 길어지고 diff도 섞여서 어떤 목표의 변경인지 검토가 어려워짐
- 대응: 목표가 다르면 스레드를 분리하고, 현재 작업을 건드리지 않는 병렬 구현은 Worktree로 분기