Claude Code 병렬 세션 충돌 방지를 위한 워크플로 계약 가이드

실용적 조언

docs/WORKFLOW.md 파일을 만들고 에이전트 설정 파일(.md)에서 이를 링크하여 모든 세션이 규칙을 숙지하게 하라.
데이터베이스 변경이 포함된 모든 PR에 롤백 계획 작성을 강제하여 가용성을 높여라.

섹션별 상세

병렬 에이전트 운영 시 발생하는 데이터베이스 마이그레이션 번호 중복과 체인지로그 충돌 문제를 해결하기 위한 사전 점검 절차를 정의했다. 모든 에이전트는 코드를 작성하기 전 git fetch, 오픈된 PR 목록 확인, 미출시 체인지로그 검토를 수행하여 기존 작업과의 간섭을 차단한다. 이를 통해 두 에이전트가 동일한 마이그레이션 번호를 재사용하여 배포가 실패하는 상황을 방지한다.

데이터베이스 스키마 변경 시 서비스 중단을 막기 위해 반드시 2단계 프로세스를 준수하도록 규정했다. 컬럼 추가, 배포, 데이터 채우기, 배포 후 나중에 삭제하는 방식을 택하며, 파괴적인 SQL을 포함하는 PR에서는 반드시 백업 스냅샷 ID를 기록하도록 강제한다. 이러한 단계적 접근은 스키마 변경 도중 세션이 종료되거나 운영 환경이 파괴되는 리스크를 최소화한다.

에이전트가 자율적으로 수행하기 전 반드시 사용자에게 허가를 구해야 하는 '하드 스톱(Hard-stop)' 목록을 설정했다. 강제 푸시(force-push), 컬럼 삭제, 인증 범위 확대, 과금 관련 반복 작업 등 수용 기준을 벗어나는 고위험 작업이 이에 해당한다. 이는 에이전트의 자율성으로 인해 발생할 수 있는 보안 사고나 비용 폭탄을 예방하는 안전장치 역할을 한다.

모든 PR에는 스키마, 인증, RLS 또는 공용 API 수정 시 반드시 명확한 롤백 경로를 기술하도록 의무화했다. 되돌릴 커밋 지점, 롤백할 마이그레이션, 전환할 플래그 등을 구체적으로 명시하지 못하면 머지를 금지하는 원칙을 세웠다. 이는 에이전트가 작성한 코드가 문제를 일으켰을 때 즉각적인 복구 가능성을 보장하기 위한 실무적 합의이다.

용어 해설

데이터베이스 마이그레이션(Migration): — 데이터베이스 스키마의 변경 사항을 관리하는 프로세스이다. 여러 에이전트가 동시에 작업할 때 중복된 마이그레이션 번호를 생성하거나 충돌을 일으키는 문제를 방지하기 위해 순차적 관리가 필수적이다.
행 수준 보안(RLS): — Row-Level Security의 약자로, 데이터베이스 테이블의 각 행에 대해 사용자별 접근 권한을 제어하는 보안 정책이다. 에이전트가 이를 수정할 때 보안 사고가 발생할 수 있어 롤백 경로 작성이 강조된다.
강제 푸시(Force Push): — Git에서 원격 저장소의 이력을 로컬 이력으로 덮어쓰는 작업이다. 병렬 세션에서 한 에이전트가 강제 푸시를 하면 다른 에이전트의 작업이 유실될 수 있어 엄격한 제한이 필요하다.

언급된 도구

Claude Code추천

CLI 기반 AI 코딩 에이전트