병렬 리소스 격리
개요
여러 Claude 인스턴스가 동일한 프로젝트에서 작업하면 포트, 데이터베이스, 브라우저 인스턴스에서 충돌이 발생합니다. 이 스킬은 사전에 감지하고 조용히 적응하는 방법을 가르칩니다 — 사용 중인 리소스를 확인하고, 다른 것을 선택하고, 선택한 결과를 보고합니다.
핵심 원칙: 시스템 상태를 관찰하고, 조용히 적응하며, 터미널에 보고합니다. 조정 파일, 잠금 파일, 공유 상태가 필요 없습니다.
사용 시기
다음 작업을 수행하기 전에 항상 감지 확인을 실행하세요:
- 개발 서버 시작 (
next dev,npm run dev) - Playwright e2e 테스트 실행
- 데이터베이스에 쓰거나 어설션하는 테스트 실행
포트 격리 (개발 서버)
개발 서버를 시작하기 전에:
lsof -i :3000 -t 2>/dev/null
사용 중이면 위로 스캔하여(3001, 3002, ...) 빈 포트를 찾습니다. 다음 명령으로 시작하세요:
PORT=<free_port> next dev
webServer 설정이 있는 Playwright:
- 환경 변수를 통해 포트를 재정의하고, 동일한 포트를
baseURL로 전달합니다. - 환경 변수 기반 포트 재정의가 지원되지 않으면 사용자에게 플래그를 지정하고 설정 파일은 절대 수정하지 마십시오.
webServer 없는 Playwright (외부 서버):
- 빈 포트에서 개발 서버를 시작합니다.
- 재정의된 baseURL로 Playwright를 실행합니다:
BASE_URL=http://localhost:<free_port> npx playwright test
Playwright 설정에 하드코딩된 baseURL (일반적인 경우):
대부분의 설정은 환경 변수 대신 baseURL: 'http://localhost:3000'을 하드코딩합니다. 이 경우 BASE_URL=...이 작동하지 않습니다. 사용자에게 다음 정확한 수정 사항을 플래그로 지정하세요:
playwright.config.ts에baseURL이 하드코딩되어 있습니다. 다음으로 업데이트해 주세요:baseURL: process.env.BASE_URL || 'http://localhost:3000'이렇게 하면 설정 파일을 수정하지 않고도 환경 변수를 통해 포트를 재정의할 수 있습니다.
데이터베이스 격리 (Supabase)
DB에 쓰거나 어설션하는 테스트를 실행하기 전에:
- 격리가 필요한지 확인합니다:
- 읽기 전용 → DB 공유, 격리 건너뛰기
- 쓰기 / 변경 / DB 상태 어설션 → 격리
- 타임스탬프 기반 스키마 접두사를 생성합니다:
parallel_<epoch>_(예:parallel_1741234567_) - 격리된 스키마를 생성하고 마이그레이션을 실행합니다:
psql "$DATABASE_URL" -c "CREATE SCHEMA parallel_1741234567_;"
PGOPTIONS="--search_path=parallel_1741234567_" npx supabase db push
- 환경 변수를 통해 앱을 격리된 스키마로 지정합니다:
SUPABASE_SCHEMA=parallel_1741234567_ npx playwright test
- 테스트 완료 후: 스키마를 삭제합니다:
psql "$DATABASE_URL" -c "DROP SCHEMA parallel_1741234567_ CASCADE;"
Playwright 브라우저 격리
Playwright 테스트를 실행하기 전에:
- 충돌할 수 있는 실행 중인 Playwright 브라우저 프로세스를 확인합니다.
- 잠금 경합을 피하기 위해 브라우저 상태를 격리합니다 — 다음 방법 중 하나를 사용하세요:
TMPDIR=/tmp/playwright_<epoch> npx playwright test
또는 더 세부적으로 — 브라우저 경로만 격리:
PLAYWRIGHT_BROWSERS_PATH=/tmp/pw_browsers_<epoch> npx playwright install chromium
PLAYWRIGHT_BROWSERS_PATH=/tmp/pw_browsers_<epoch> npx playwright test
- Playwright 인스턴스가 위의 포트 격리에서 할당된 동일한 포트를 대상으로 하는지 확인합니다.
보고
적응 후, 한 번 보고하고 넘어갑니다:
⚡ 병렬 격리:
개발 서버: 포트 3005 (3000 사용 중이었음)
DB 스키마: parallel_1741234567_
Playwright: /tmp/playwright_1741234567
실제로 적응된 리소스만 보고합니다. 충돌이 없으면 아무 말도 하지 마십시오.
빠른 참조
| 리소스 | 감지 | 적응 | 정리 |
|---|---|---|---|
| 개발 서버 포트 | lsof -i :<port> | PORT=<next_free> | 필요 없음 |
| Supabase DB | 테스트가 쓰기/어설션하는지 확인 | parallel_<epoch>_ 스키마 | 테스트 후 스키마 삭제 |
| Playwright 브라우저 | 잠금 경합 확인 | TMPDIR 또는 PLAYWRIGHT_BROWSERS_PATH | 임시 디렉토리 자동 정리 |
일반적인 실수
다른 Claude의 프로세스 종료
- 문제: 포트 3000이 사용 중이어서 프로세스를 종료하여 해제함
- 해결책: 직접 시작하지 않은 프로세스는 절대 종료하지 마십시오. 다른 포트를 선택하세요.
포트 재정의를 위한 설정 파일 수정
- 문제:
playwright.config.ts또는next.config.js를 편집하면 Git 충돌이 발생함 - 해결책: 환경 변수를 사용하세요. 환경 변수가 작동하지 않으면 사용자에게 플래그를 지정하세요.
적응된 포트를 Playwright에 전달하는 것을 잊음
- 문제: 개발 서버는 3005에서 실행 중이지만 Playwright는 여전히 3000을 사용함
- 해결책: 항상 조정하세요 — 개발 서버에 할당된 포트를
BASE_URL로 Playwright에 전달해야 합니다.
필요하지 않은 DB 격리
- 문제: 읽기 전용 테스트를 위해 스키마를 생성하는 오버헤드 발생
- 해결책: 테스트가 DB 상태에 쓰거나 어설션하는 경우에만 격리하세요.
위험 신호
절대 하지 말 것:
- 리소스를 확보하기 위해 다른 프로세스 종료
- 포트를 변경하기 위해 설정 파일 수정
- 포트 충돌을 무시하고 되기를 바라기
- 테스트 후 DB 정리 건너뛰기
항상 할 것:
- 시작하기 전에 확인
- 환경 변수를 통해 조용히 적응
- 선택한 결과 보고
- 테스트 후 DB 스키마 정리