# 보조 워크트리 만들기 (PC마다 1개)

작성 2026-08-31. 대상 = 각 PC에서 일하는 AI. 이 문서대로 하면 한 PC에서 창 두 개가
서로 밟지 않고 동시에 일한다.

## 왜 이렇게 하나

- **동기화 밖에 둔다.** `C:\Program_coding` 은 Synology Drive 동기화 루트다. 워크트리를
  그 안에 두면 NAS 사본이 편집을 되돌린다(2026-08-31에 `.claude/dev_up.py` 가 두 번
  옛 사본으로 덮였다). 그래서 워크트리는 **동기화 루트 밖**에 만든다.
- **포트를 나눈다.** 두 폴더가 같은 포트를 쓰면 나중에 뜬 쪽이 앞의 것을 죽인다.
- **브랜치를 나눈다.** git 은 같은 브랜치를 두 워크트리가 동시에 체크아웃하지 못한다.

## 이름 규칙

| 대상 | 규칙 | 이 PC(노트북)의 실제 값 |
|---|---|---|
| 폴더 | 동기화 루트 밖, `C:\Aislo_wt\<이름>` | `C:\Aislo_wt\aislo-b0506` |
| 메인 폴더 브랜치 | `main` 또는 `main_<pc>_<번호>` | `main` |
| 보조 트리 브랜치 | `sub_<pc>_<번호>` | `sub_laptop_1` |

PC 이름을 브랜치에 박아 두면 원격 목록만 봐도 어느 기계 것인지 갈린다
(현재 원격: `main`, `main_desktop_1`, `main_laptop_1`, `sub_laptop_1`).

## 만드는 절차

먼저 그 PC의 동기화 루트를 확인한다 — `.SynologyWorkingDirectory` 파일이 있는 폴더가
루트다. 새 워크트리 경로가 그 아래로 들어가면 안 된다.

```powershell
# 1) 워크트리 생성 (메인 폴더에서 실행)
New-Item -ItemType Directory C:\Aislo_wt
git -C "<메인 폴더>" worktree add C:\Aislo_wt\<이름> -b sub_<pc>_<번호> origin/main

# 2) 메인 폴더와 한 벌로 쓸 것들을 링크로 연결 (전부 gitignore 대상이라 안 딸려온다)
$M = "<메인 폴더>"; $W = "C:\Aislo_wt\<이름>"
New-Item -ItemType Junction $W\venv      -Target $M\venv
New-Item -ItemType Junction $W\.claude   -Target $M\.claude
New-Item -ItemType Junction $W\docs      -Target $M\docs
New-Item -ItemType Junction $W\storage   -Target $M\storage
New-Item -ItemType SymbolicLink $W\CLAUDE.md -Target $M\CLAUDE.md
New-Item -ItemType SymbolicLink $W\AGENTS.md -Target $M\AGENTS.md

# 3) 프론트 의존성 (워크트리마다 따로 필요)
cd $W\config; npm install
```

`graphify-out` 링크가 있다면 옛 경로를 가리키므로 새로 건다 —
대상은 `<메인 폴더>\docs\wiki\graphify-out\<날짜>`.

## 서버 띄우기 — 포트가 갈린다

| 폴더 | 백엔드 | vite |
|---|---|---|
| 메인 | 8000 | 5173 |
| 보조 | 8001 | 5174 |

메인 폴더는 그대로다.

```powershell
./venv/Scripts/python.exe .claude/dev_up.py
```

보조 트리는 `dev_up.py` 가 8000·5173 고정이라 **환경변수를 주고 직접 띄운다**.

```powershell
$env:SERVER_PORT='8001'; $env:FRONTEND_DEV_PORT='5174'; $env:AISLO_API_PORT='8001'
Start-Process "$W\venv\Scripts\python.exe" -ArgumentList 'main.py' -WorkingDirectory $W `
  -RedirectStandardOutput "$W\tmp\server.log" -RedirectStandardError "$W\tmp\server.err.log"

$env:AISLO_VITE_PORT='5174'
Start-Process "$W\venv\Scripts\python.exe" -ArgumentList '.claude\browser_driver.py' `
  -WorkingDirectory $W -RedirectStandardOutput "$W\tmp\browser_driver.out.log" `
  -RedirectStandardError "$W\tmp\browser_driver.err.log"
```

각 변수가 하는 일 — `SERVER_PORT` 백엔드, `FRONTEND_DEV_PORT` vite, `AISLO_API_PORT`
vite 프록시가 볼 백엔드(`config/vite.config.ts`), `AISLO_VITE_PORT` 브라우저 드라이버가
열 주소. 넷을 한 벌로 맞춰야 프록시가 옆 포트로 새지 않는다.

확인: `5174/api/health` 가 200이면 프록시가 8001을 보고 있는 것이다.

**백엔드·DB 는 원래 한 벌을 공유해도 된다.** 백엔드를 고치는 작업일 때만 8001을 따로 띄운다.
프론트만 만질 때는 vite 만 5174로 올리고 `AISLO_API_PORT=8000` 을 주면 된다.

## 지켜야 할 것

- **`git worktree remove` 를 쓰지 않는다.** Windows 긴 경로(`node_modules`)에서 실패하면
  공유 `.git` 과 `.claude` 까지 지운다(2026-08-30 실제 사고 2건). 폴더 정리가 필요하면
  사용자에게 요청한다. 옮기는 것은 `git worktree move` 로 안전하다 — 폴더 이동과 포인터
  두 개를 git 이 같이 고친다.
- **워크트리를 지울 때는 링크부터 끊는다.** `.claude`·`docs`·`storage`·`venv` 는 메인
  폴더를 가리키는 링크라, 재귀 삭제가 링크를 따라가면 원본이 날아간다. `cmd /c rmdir <링크>`
  로 링크만 먼저 떼고 폴더를 지운다.
- **커밋했으면 그 자리에서 push.** PC 이동이 곧 인수인계다. 로컬에만 있으면 다음 PC가 못 받는다.
- **같은 브랜치를 두 트리가 못 쓴다.** 메인이 `main` 을 물고 있으면 보조는 `sub_*` 여야 한다.
- **공유되는 것을 기억한다** — `venv` `.claude` `docs`(PLAN.md) `storage`(프로젝트 자료), DB.
  코드 파일만 갈릴 뿐 이것들은 한 벌이다. `PLAN.md` 는 자기 섹션만 고친다.
- **`.claude/` 는 git 밖이고 동기화 안이다.** 두 PC의 AI가 같은 파일을 고치면 나중 동기화가
  앞의 것을 덮는다. 고치기 전에 사용자에게 알린다.

## 이 PC(노트북) 현재 상태

```
C:\Program_coding\임도설계 및 견적자동화 프로그램 개발   [main]          8000 · 5173
C:\Aislo_wt\aislo-b0506                                [sub_laptop_1]   8001 · 5174
```

원격에 `sub_laptop_1` 을 미리 만들어 두었다(`origin/sub_laptop_1`, main 과 같은 지점).