Parallel Docs

---
name: parallel-docs
description: 두 사람 이상이 병행 작업하며 기록을 나중에 합치는 저장소에서 사용한다. 작업자 확인, docs_<id> 개인 폴더 규칙, 문서 스탬프, 반입 스캔과 병합 순서, 의미 충돌 가드를 정한다.
---

# 병행 작업 규칙

설정의 `parallelMode` 가 true 인 동안 적용된다. **이 규칙이 일반 진행 기록 규칙보다
우선한다.**

## 1. 작업자 확인

설정 `workers` 의 `git config user.email` 매핑으로 **자동 확정**한다.

다음 경우에만 사람에게 묻는다:

| 상황 | 물어볼 것 |
|---|---|
| 매핑에 없는 이메일 | `docs_<id>/` 폴더를 전부 나열해 "등록된 작업자: a, b - 누구십니까? (목록에 없으면 신규)" |
| 후보가 둘 이상 | 같은 선택지 형식 |
| 신규 작업자 | id 를 받고 **"신규 작업자 `<id>` 가 맞습니까? `docs_<id>/` 를 추가해 진행할까요?"** 를 한 번 더 확인 |

> [!IMPORTANT]
> 작업자가 확정되지 않은 상태에서는 **어떤 쓰기도 하지 않는다**(수정·커밋·push 전부).
> 잘못된 id 로 기록되면 병합 때 남의 기록에 섞인다. 사용자가 건너뛰려 해도 확정 없이는
> 진행하지 않는다.

신규 작업자 폴더는 승인 후에 만든다 - `docs_<id>/PROGRESS.md` + `docs_<id>/decisions/README.md`.

## 2. 메인 `docs/` 는 동결

병행 기간에 메인 `docs/` 는 읽기 전용이다. 예외 둘:

1. **`docs/SAFETY_GATE.md`** - 안전 게이트·마커 관련 변경은 개인 폴더에 두지 않고 즉시
   메인에 반영 + 그 자리에서 커밋·push 하고, 상대방에게 공유하라고 사용자에게 안내한다.
   **안전 정보는 병합을 기다리면 안 된다.**
2. **기계적 정합화** - supersede 상태 표기, 깨진 형식·죽은 참조 수선. 내용 병합은 여전히
   병합 절차로만.

## 3. 기록처

진행 기록 규칙의 기록처를 개인 폴더로 바꿔 적용한다. 형식·규칙은 동일하다.

| 평상시 | 병행 기간 |
|---|---|
| `docs/PROGRESS.md` | `docs_<id>/PROGRESS.md` |
| `docs/decisions/` | `docs_<id>/decisions/` |
| `docs/AI_USAGE.md` | `docs_<id>/AI_USAGE.md` |

## 4. 문서 스탬프

병행 관리 문서는 제목 바로 아래에 한 줄을 둔다:

```
> 최종 수정: YYYY-MM-DD HH:MM · <id>
```

수정할 때마다 갱신한다 - 병합 때 어느 사본이 최신인지 이걸로 판별한다.

> [!WARNING]
> **시각은 시스템 시계로 확인해 적는다.** 추정으로 적으면 병합 판별이 틀어진다 -
> 실제 오기록 사례가 있다. 훅이 켜져 있으면 자동 갱신된다.

## 5. 반입 스캔 - 매 세션 필수

작업자 확정 직후, 다른 작업자의 새 내용이 있는지 스캔한다.

`git fetch <remote>` 후:

1. 다른 작업자 `docs_<id>/` 폴더의 신규 생성·스탬프 갱신 여부
2. 새 커밋(다른 작업자 브랜치·master) 여부

새 내용이 있으면 요약을 제시하고 **"`<id>` 작업자의 새로운 내용이 있습니다 - merge
진행할까요?" 를 확인받는다.** 승인 없이 병합하지 않는다. 미루기로 하면 그 사실을 자기
현황판에 한 줄 남긴다 - 다음 세션이 다시 묻게.

## 6. 병합 순서

승인 후 이 순서로만 진행한다.

| # | 단계 |
|---|---|
| 1 | 반입분의 **안전 관련 변경부터** 파악 - `SAFETY_GATE.md` 변경, 새 ADR 의 안전 영향, `SAFETY-STUB`/`VIRTUAL-BYPASS` 마커 재스캔 |
| 2 | 반입 ADR 을 `docs/decisions/` 인덱스로 이관 |
| 3 | 현황판·기타 문서 병합 - 스탬프 최신 기준 |
| 4 | 코드는 **git 3-way 병합으로만** - 수기 파일 복사·덮어쓰기 금지 |
| 5 | `python .method/scripts/check_docs.py` 통과 확인 |
| 6 | 코드 병합이면 의미 충돌 검출(아래) |

각자 작업자 id 브랜치에서 커밋·push 하고, **master 병합·push 는 `mergeOwner` 한 사람이
한다.** 안전 관련 파일 충돌 해소는 사람이 diff 리뷰한다 - 자동 병합하지 않는다.

## 7. 의미 충돌 가드

텍스트 충돌이 없어도 의미가 충돌할 수 있다. 코드 병합 시:

- 양쪽이 함께 고친 파일부터 찾는다 - `base=$(git merge-base HEAD <반입 브랜치>)` 후
  `git diff --name-only $base HEAD` 와 `git diff --name-only $base <반입 브랜치>` 의
  교집합. 안전 파일이 걸리면 사람 diff 리뷰.
- 프로젝트에 스모크 스크립트가 있으면 실행 - 빌드 + 단위테스트 + 기동 로그.

## 8. 외부 폴더 반입

압축 사본 등 git 밖 경로로 코드가 들어오면:

1. 압축 해제 직후 MOTW 해제 - `Get-ChildItem -Path <반입폴더> -Recurse -File | Unblock-File`.
   `Zone.Identifier` 가 붙으면 일부 IDE 가 리소스 파일 처리를 거부한다.
2. 현행 코드와 diff 로 분기 여부·변경 내용 확인.
3. 안전 마커 재스캔.

반입 결과는 폴더 복사가 아니라 **브랜치·커밋으로** 들여온다.

## 9. ADR ID

병행 기간의 신규 ADR 은 `ADR-YYMMDD-<id>-slug.md` 형식을 쓴다 - 작업자 id 가 들어가야
병합 때 충돌하지 않는다. 상세는 `writing-adr` 스킬.