Pier_v1/worktree-human-ai-guide.md

# 사람 + AI의 모듈별 Git Worktree 협업 가이드

## 1. 목표

한 프로젝트의 모듈마다 사람 한 명과 AI 세션을 배정한다. AI는 해당 worktree에서 세션을 시작하는 것만으로 담당 범위와 인수인계 내용을 파악해야 한다.

사용자는 매번 프로젝트 전체와 담당 영역을 설명하지 않고, 이번에 할 일만 요청한다.

> 작업실은 따로, 연결 규칙은 함께, 결과는 검토해서 통합한다.

이 문서는 협업 구조의 설계안이다. 경로와 모듈 이름은 예시이며, 실제 프로젝트에 맞게 정한다. 이미 설정이나 검증을 마쳤다고 가정하지 않는다.

## 2. 기본 개념

| 용어 | 비개발자용 설명 |
|---|---|
| 저장소 | 프로젝트 파일과 변경 이력을 보관하는 곳 |
| main | 검토를 마친 공식 버전의 브랜치 |
| 브랜치 | 공식 버전과 별도로 진행하는 수정안 |
| worktree | 특정 브랜치를 펼쳐 놓고 작업하는 별도 폴더 |
| 모듈 | 로그인·결제·보고서처럼 역할별로 나눈 기능 |
| 커밋 | 변경 내용을 기록하는 단위 |
| 병합 | 수정안을 다른 브랜치에 반영하는 작업 |
| PR | 변경 내용을 검토하고 병합하기 위한 요청 |

Git worktree는 같은 저장소에 연결된 여러 작업 폴더에서 서로 다른 브랜치를 동시에 다루게 해 준다. 보통 각 worktree에는 담당 모듈만이 아니라 프로젝트 전체가 들어 있다. [web:3]

## 3. 전체 구성

```text
하나의 프로젝트 저장소
│
├─ 통합 worktree / main
│   └─ 통합 담당 사람 + AI
│      공통 틀, 모듈 연결, 변경 검토, 최종 검증
│
├─ 로그인 worktree / feature/login-task
│   └─ 로그인 담당 사람 + AI
│
├─ 결제 worktree / feature/payment-task
│   └─ 결제 담당 사람 + AI
│
└─ 보고서 worktree / feature/report-task
    └─ 보고서 담당 사람 + AI
```

서로 다른 컴퓨터에서 일한다면 각자 저장소를 받아 사용한다. 한 컴퓨터의 worktree 폴더를 모두가 공유할 필요는 없다. Worktree는 로컬 작업 폴더를 관리하는 기능이다. [web:3]

모듈 담당자와 작업실은 유지할 수 있지만, 브랜치 이름은 실제 작업 단위에 맞춰 관리한다. 작업이 끝나 병합되었다면 다음 작업을 어떤 브랜치와 기준 버전에서 시작할지 명확히 정한다.

## 4. 역할과 책임

| 역할 | 책임 |
|---|---|
| 모듈 담당 사람 | 이번 작업 요청, 범위 변경 판단, 결과 검토 |
| 모듈 AI | 담당 범위 내 구현·검증, 인수인계 기록 |
| 통합 담당자 | 공통 변경 조율, 병합 순서 결정, 전체 동작 확인 |

AI가 다른 모듈을 읽는 것과 수정하는 것을 구분한다. 연결 방식을 이해하려면 참조가 필요할 수 있지만, 수정 권한까지 자동으로 넓어지는 것은 아니다.

## 5. 충돌을 줄이는 원칙

### 5.1 수정 영역을 나눈다

| 담당 | 주 수정 영역 | 협의 대상 |
|---|---|---|
| 로그인 | 로그인 코드·테스트·문서 | 공통 사용자 정보 |
| 결제 | 결제 코드·테스트·문서 | 주문 정보·공통 설정 |
| 보고서 | 보고서 코드·테스트·문서 | 공통 데이터 형식 |
| 통합 | 공통 틀·연결부 | 영향을 받는 모듈 담당자 |

같은 파일을 여러 사람이 수정하면 worktree가 달라도 병합 시 충돌할 수 있다. 폴더 분리와 담당 범위 분리를 함께 운영한다. [web:4][web:9]

### 5.2 연결 약속을 먼저 정한다

모듈 사이에 전달하는 정보의 이름·형식·의미를 합의한다.

예: 로그인 모듈이 사용자 번호를 `userId`로 전달한다면, 결제 모듈도 같은 의미와 형식으로 받아야 한다.

연결 규칙이 바뀌면 영향을 받는 담당자에게 알리고, 필요한 공통 변경을 먼저 반영한다. [web:9]

### 5.3 공통 부분은 변경 창구를 정한다

공통 설정, 공통 데이터 형식, 전체 구조 변경은 담당 모듈의 일반 작업과 구분한다. 필요하면 변경 요청으로 전달하고 통합 담당자가 조율한다.

### 5.4 작은 단위로 검토하고 합친다

오랫동안 따로 작업한 결과를 한 번에 합치기보다, 검토 가능한 작은 변경부터 통합한다. 최신 공식 버전의 변경을 진행 중 작업에 반영하고, 합친 상태도 확인한다. [web:4][web:9]

## 6. AI가 시작할 때 알아야 할 세 가지

| 구분 | 내용 | 유지 방식 |
|---|---|---|
| 공통 규칙 | 프로젝트 구조, 협업 원칙, 검증 방식 | 팀이 공유 |
| 담당 명세 | 현재 worktree의 역할과 수정 경계 | worktree별 설정 |
| 인수인계 | 완료 사항, 미해결 문제, 다음 단계 | 모듈별 기록 |

역할과 이번 작업은 분리한다.

- 역할: 이 작업실은 결제 담당이다.
- 현재 상태: 환불 기능 구현 중이며 일부 검증이 남았다.
- 이번 요청: 환불 실패 시 안내 화면을 만든다.

새 세션이 역할을 파악했다고 해서 이전 작업을 임의로 재개하게 하지는 않는다. 이번 작업 요청이 없다면 상태만 보고하고 기다리도록 정한다.

## 7. Claude Code용 파일 배치 예시

```text
결제 worktree/
├─ .gitignore
├─ CLAUDE.md
├─ CLAUDE.local.md
├─ src/modules/payment/
├─ tests/payment/
└─ docs/modules/payment/
   └─ HANDOFF.md
```

| 파일 | 목적 | Git 공유 |
|---|---|---|
| `CLAUDE.md` | 팀 공통 규칙 | 공유 |
| `CLAUDE.local.md` | 이 worktree의 담당 역할 | 제외 |
| `HANDOFF.md` | 모듈별 진행 상황과 인수인계 | 공유 |

Claude Code는 시작 위치와 상위 경로의 지침 파일을 읽는다. 이 설계에서는 worktree 최상위 폴더에서 실행하고, 그 위치에 공통 지침과 로컬 담당 지침을 둔다. 지침은 짧고 구체적으로 유지한다. [web:29]

Codex를 사용한다면 시작 시 읽는 `AGENTS.md` 체계에 맞춰 별도로 구성한다. Claude Code용 파일 이름이 모든 AI 도구에서 동일하게 동작한다고 가정하지 않는다. [web:16]

## 8. 공통 지침 예시: CLAUDE.md

```markdown
# 프로젝트 공통 작업 규칙

## 시작
- 현재 폴더와 브랜치를 확인한다.
- 이 worktree의 담당 지침을 확인한다.
- 담당 지침이 없거나 서로 모순되면 수정하지 말고 사람에게 알린다.
- 담당 모듈의 인수인계와 실제 변경 상태를 확인한다.

## 작업 경계
- 담당 범위 밖 파일을 임의로 수정하지 않는다.
- 다른 모듈은 연결 이해를 위해 참조할 수 있다.
- 공통 설정과 연결 규칙 변경은 사전 협의한다.
- 요청과 무관한 정리나 대규모 이름 변경을 함께 하지 않는다.

## 기존 변경 보호
- 기존 변경의 작성자나 목적을 추정하지 않는다.
- 확인되지 않은 변경을 삭제하거나 덮어쓰지 않는다.
- 충돌하는 변경을 발견하면 사람에게 확인한다.

## 검증과 기록
- 실제로 실행한 검증과 실행하지 못한 검증을 구분한다.
- 성공하지 않은 검증을 성공했다고 기록하지 않는다.
- 종료 전에 변경 내용과 남은 일을 인수인계 문서에 기록한다.
```

## 9. 담당 지침 예시: CLAUDE.local.md

```markdown
# 이 worktree의 담당 범위

## 역할
- 결제 모듈 전용 작업실이다.
- 담당 사람을 도와 결제 기능을 구현하고 검증한다.

## 수정 허용
- src/modules/payment/
- tests/payment/
- docs/modules/payment/

## 참조 가능하나 직접 수정하지 않음
- 로그인 모듈
- 보고서 모듈
- 공통 데이터 형식
- 프로젝트 공통 설정과 전체 틀

## 인수인계 위치
- docs/modules/payment/HANDOFF.md

## 범위 밖 변경이 필요할 때
- 임의로 수정하지 않는다.
- 필요한 변경, 이유, 영향 범위를 정리한다.
- 사람에게 알리고 통합 담당자에게 전달할 요청을 작성한다.

## 세션 시작
1. 현재 폴더와 브랜치가 담당 작업과 맞는지 확인한다.
2. 인수인계와 실제 파일 변경 상태를 확인한다.
3. 담당 범위와 현재 상태를 짧게 보고한다.
4. 이번 작업 요청이 없다면 구현을 시작하지 않는다.

## 세션 종료
- 변경 파일과 변경 이유를 기록한다.
- 실행한 검증과 결과를 기록한다.
- 미검증 사항, 막힌 점, 다음 단계를 기록한다.
```

## 10. 인수인계 문서 예시: HANDOFF.md

```markdown
# 결제 모듈 인수인계

## 현재 목표
- 현재 요청과 완료 기준

## 완료 사항
- 구현한 내용
- 관련 커밋 또는 검토 요청

## 진행 중
- 미완료 작업과 현재 상태

## 검증
- 실제 실행한 검증과 결과
- 실행하지 못한 검증 및 이유

## 미해결 문제
- 문제, 영향, 확인이 필요한 사항

## 다른 담당자에게 요청할 사항
- 공통 부분 변경 등

## 다음 단계
- 이어서 할 작업
```

이 문서는 업무 기록이다. 오래된 기록이 실제 파일 상태와 다를 수 있으므로, AI는 기록과 현재 상태를 함께 확인한다.

## 11. .gitignore의 역할

`.gitignore`는 아직 Git이 추적하지 않는 파일 중, 변경 기록에 포함하지 않을 파일을 지정하는 목록이다. 접근 권한이나 AI의 수정 권한을 설정하는 기능은 아니다. [web:30]

이 설계에서는 다음을 넣는다.

```gitignore
/CLAUDE.local.md
```

로그인 작업실과 결제 작업실의 로컬 역할 파일을 Git으로 전달하지 않도록 하여, 서로 다른 담당 지침이 공통 변경 사항에 섞이지 않게 한다.

- 공통 규칙과 인수인계는 공유한다.
- worktree별 역할 설정은 로컬에 둔다.
- 로컬 파일은 새 worktree를 만들 때 따로 생성한다.
- `.gitignore` 자체는 팀에 공유할 수 있다. [web:32]

이미 추적 중인 파일은 `.gitignore`에 적는 것만으로 제외되지 않는다. 별도의 추적 해제가 필요하다. [web:30]

담당 모듈 외의 코드를 `.gitignore`에 넣어 작업 범위를 제한하려고 해서는 안 된다. 파일 접근 제한과 Git 추적 제외는 별개다.

## 12. 최초 설정과 일상 사용

### 최초 설정: 작업실을 만들 때

1. 담당 모듈과 담당자를 정한다.
2. 수정 허용 경로와 협의 대상을 정한다.
3. 작업용 브랜치와 worktree를 만든다.
4. 공통 지침을 준비한다.
5. worktree별 로컬 담당 지침을 생성한다.
6. 인수인계 문서를 준비한다.
7. 새 AI 세션으로 자동 인식 여부를 확인한다.

최초 설정 절차는 스크립트나 작업실 생성 도구로 자동화할 수 있다. 로컬 지침이 빠지면 임의로 역할을 추정하지 않고 중단하도록 설계한다.

### 일상 사용: 작업할 때

1. 자기 worktree 폴더를 연다.
2. 그 폴더에서 AI를 실행한다.
3. AI의 담당 범위·현재 상태 확인을 읽는다.
4. 이번 작업만 요청한다.
5. 결과와 검증 기록을 검토한다.
6. 작은 단위로 검토 요청을 보낸다.
7. 통합 담당자가 병합하고 전체 상태를 확인한다.

## 13. 자동 인식과 강제 제한은 다르다

| 요구 | 장치 |
|---|---|
| 자기 담당 범위를 안다 | 자동 로딩 지침 |
| 새 세션도 이어받는다 | 인수인계 문서와 시작 절차 |
| 범위 밖 변경을 시도하지 못하게 한다 | 별도 권한 설정·검사 장치 |
| 범위 밖 변경이 공식 버전에 들어가지 않게 한다 | 변경 경로 검사·검토·병합 규칙 |

지침 파일은 AI의 행동을 안내하지만 강제 잠금은 아니다. Claude Code 문서도 지침과 권한·훅 같은 강제 장치를 구분한다. [web:29]

Worktree 역시 파일 시스템, 실행 중인 서버, 외부 데이터까지 모두 격리하는 장치라고 간주하지 않는다. 이 가이드의 핵심은 작업 파일 분리와 담당 경계 관리다.

## 14. 도입 확인 체크리스트

- [ ] 각 worktree에 담당 사람과 모듈이 정해져 있다.
- [ ] 수정 허용 경로와 협의 대상이 명확하다.
- [ ] 공통 연결 규칙과 변경 창구가 정해져 있다.
- [ ] 세션 시작 시 담당 지침이 실제로 로딩된다.
- [ ] 담당 지침이 없으면 역할을 추정하지 않는다.
- [ ] 인수인계 위치가 명시되어 있다.
- [ ] 기존 변경과 검증 상태를 추정하지 않는다.
- [ ] 로컬 담당 지침이 Git 변경 사항에 섞이지 않는다.
- [ ] 새 worktree 생성 시 로컬 지침이 배치된다.
- [ ] 범위 밖 변경 처리 절차가 있다.
- [ ] 통합 후 전체 검증 책임자가 정해져 있다.

## 15. 완료 판정

새 AI 세션을 담당 worktree에서 시작한 뒤, 배경 설명 없이 다음을 묻는다.

> 네 담당 범위와 현재 상태를 설명해 봐.

AI가 다음을 정확히 말할 수 있어야 한다.

- 맡은 모듈
- 수정 가능한 경로
- 협의가 필요한 영역
- 인수인계에 기록된 상태와 실제 확인한 상태
- 이번 작업 요청이 없을 때 기다려야 한다는 규칙

최종 목표는 AI 세션이 바뀌어도 담당 역할과 업무 기록은 작업실에 남아 있는 것이다.