병렬 개발 규칙 시스템
3개 터미널(Claude Code 세션)을 동시에 사용하여 프로젝트 초기 반복 작업을 병렬로 진행하는 체계
핵심: 계약 기반 분리 → 독립 개발 → 순차 통합
개요
왜 병렬 개발인가?
일반적인 단일 터미널 개발에서는 Auth → Layout → API를 순차적으로 구현합니다.
병렬 개발은 **계약(contracts/)**을 먼저 정의하고, Mock 데이터를 활용해 3개 터미널이 동시에 구현한 뒤, 마지막에 통합합니다.
일반 개발: Auth ──→ Layout ──→ API ──→ 통합 (순차)
병렬 개발: 계약 정의 ──→ ┌─ Auth ──┐
├─ Layout ──┤ ──→ 통합 (병렬)
└─ API ──┘
전체 흐름
Phase 0 Phase 1~2 Phase 3
(터미널 A만) (3개 병렬) (순차 통합)
────────── ────────── ──────────
A: 계약 정의 → Config, DB → 통합 지원
패키지 설치 Auth, RBAC
환경변수
B: (대기) → 테마, 레이아웃 → mock→실제
CRUD 페이지
C: (대기) → 에러 구조 → mock→실제
API, 미들웨어
문서 구성
Stage 1~7: 핵심 규칙
| Stage | 파일 | 내용 |
|---|
| 1 | parallel-dev-contracts.md | 모듈 간 인터페이스 계약 정의 |
| 2 | parallel-dev-dependencies.md | 의존성 분류 및 레벨 배정 |
| 3 | parallel-dev-file-conflict.md | 파일 충돌 방지 (소유권, 잠금) |
| 4 | parallel-dev-terminal-roles.md | 터미널별 역할 및 워크플로우 |
| 5 | parallel-dev-integration.md | 통합 절차 및 검증 |
| 6 | parallel-dev-templateize.md | 템플릿화 및 재사용 |
| 7 | parallel-dev-coding-conventions.md | 코드 수준 충돌 방지 (타입/함수/import/네이밍) |
Round 1~4: 보강 규칙 (27개 누락 변수 해결)
| Round | 파일 | 해결 변수 |
|---|
| 1 | parallel-dev-enforcement.md | A-1, A-2, B-1, B-2, D-1 (치명적 5건) |
| 2 | parallel-dev-semantic-safety.md | D-3, D-4, A-3, A-4 (높음 4건) |
| 3 | parallel-dev-existing-rules-bridge.md | C-12, E-12, B-3~4, C-3, C-5 (8건) |
| 4 | parallel-dev-automation.md | A-5, B-5, C-4, C-6, D-2, D-5, D-6, E-3~5 (10건) |
템플릿 (프로젝트에 복사하여 사용)
| 파일 | 용도 |
|---|
templates/parallel-dev-quickstart.md | 빠른 시작 가이드 (1페이지 요약) |
templates/parallel-dev-contracts.ts | TypeScript 계약 코드 템플릿 |
templates/parallel-dev-prompts.md | 터미널별 Claude 프롬프트 (복사용) |
templates/parallel-dev-checklist.md | 전체 실행 체크리스트 |
templates/parallel-dev-claude-section.md | CLAUDE.md 삽입용 병렬 개발 블록 |
templates/parallel-dev-handover.md | 터미널별 Handover 양식 |
검증 스크립트
| 스크립트 | 용도 |
|---|
templates/scripts/check-phase-gate.sh | Phase 전환 가능 여부 검증 |
templates/scripts/check-ownership.sh | 파일 소유권 위반 탐지 |
templates/scripts/check-integration.sh | 통합 검증 일괄 실행 |
templates/scripts/check-circular-deps.sh | 순환 의존 탐지 |
읽기 순서 (권장)
- 이 README → 전체 개요 파악
- quickstart.md → 실행 흐름 한눈에 보기
- Stage 1~6 → 순서대로 읽으며 원리 이해
- enforcement.md → 강제 장치 (치명적 문제 해결)
- 나머지 Round 2~4 → 필요 시 참조
적용 방법
새 프로젝트에서 병렬 개발 시작
1. templates/parallel-dev-quickstart.md 읽기
2. templates/parallel-dev-contracts.ts → src/contracts/ 복사
3. templates/parallel-dev-prompts.md → 변수 채워서 각 터미널에 붙여넣기
4. templates/parallel-dev-checklist.md → 프로젝트에 복사하여 진행 추적
5. templates/parallel-dev-claude-section.md → 프로젝트 CLAUDE.md에 삽입
6. templates/scripts/ → 프로젝트 scripts/에 복사
관련 문서
- 기술 R&D 규칙 — 새로운 기술을 연구/검증하는 방법론 (Spike→POC→Integration→Iteration)
- 글로벌 개발 규칙 — 모든 프로젝트 공통 규칙