플릿 브리프
병렬 에이전트는 공유 영역에서 실패합니다. 두 레인이 하나의 파일을 편집하는 경우입니다. 브리프는 디스패치 전에 이러한 충돌을 불가능하게 만듭니다. 실제 파일 맵에서 경계를 도출하세요. 절대 가정하지 마세요.
다음 순서로 브리프를 작성하세요
1. 먼저 파일 매핑
레인을 정의하기 전에 각 제안된 변경 사항이 영향을 미칠 파일을 나열하고 읽으세요. 파일을 읽지 않고 정의된 레인은 충돌을 기다리는 것과 같습니다.
2. 독점 소유권 할당
모든 파일은 정확히 하나의 소유 레인을 가집니다. 다음 표를 작성하세요:
| 레인 | 소유(쓰기) | 읽기 전용 |
|---|---|---|
| W1 — <이름> | path/a.ts, path/b.ts | path/shared.ts |
두 레인이 하나의 파일을 작성해야 하는 경우, 세 가지 옵션 중 하나를 명시적으로 선택하세요. 모호하게 남겨두지 마세요:
- 순차화: W2는 W1의 병합을 기다립니다.
- 병합: 두 레인을 하나로 합칩니다.
- 봉합: 한 레인이 확장 지점을 추가하고, 다른 레인이 이를 사용합니다.
3. 공유 영역 명명
둘 이상의 레인이 읽는 모든 파일을 나열하고, 누가 쓸 수 있는지 명시하세요.
이 목록은 현재 코드베이스에서 도출하세요. 다른 프로젝트의 목록을 가져오지 마세요. 확인할 가치가 있는 반복적인 패턴은 다음과 같습니다:
- 라이브 인바운드 경로: 웹훅이나 사용자 트래픽을 수신하는 모든 것. 여기서의 동시 편집은 프로덕션에서 실패하며, 테스트에서는 실패하지 않습니다.
- 엔진 및 디스패처 모듈: 여러 기능이 호출하는 모듈입니다.
- 추가 전용 매니페스트: 배포 구성, 라우트 테이블, 함수 목록. 플랫폼은 제한(함수 수, 파일 크기)을 부과합니다. 두 레인이 독립적으로 추가하면 제한을 위반할 수 있습니다.
- 널리 가져오는 내보내기: 추가적으로 확장하세요. 이름 변경은 모든 호출자에 영향을 미칩니다.
- 생성 또는 벤더링된 파일: 어떤 레인도 수동으로 편집해서는 안 됩니다.
한 번 충돌을 일으킨 파일은 영구적으로 공유 영역입니다. 다음 플릿이 이 지식을 상속받을 수 있도록 브리프에 기록하세요.
4. DO-NOT 목록 도출
각 DO-NOT은 파일이나 동작과 그 이유를 명시합니다. 이유 없는 금지는 무시됩니다. 근거가 있는 금지는 유지됩니다.
대부분의 코드베이스에 일반화되는 항목:
- 충돌 해결 중에
git add -A를 절대 사용하지 마세요. 충돌 마커와 다른 레인의 작업을 스테이징합니다. - 워커는 연결된 작업 트리에서 커밋하지 않습니다. 오케스트레이터가 커밋합니다.
- 테스트 스위트가 데이터베이스를 전역적으로 모의하는 경우, 단위 테스트 통과는 데이터베이스에 대해 아무것도 증명하지 않습니다. 명시적으로 말하세요.
- 한 줄의 정당성 없이 종속성을 추가하지 마세요.
- 레인 내에서 스키마 마이그레이션을 적용하지 마세요. 단일 검토 단계로 연기하세요.
- 조용히 실패하는 CLI 호출을 주의하세요. 예를 들어
gh pr create는--base를 명시적으로 필요로 하며, 체인된 heredoc은 오류를 삼킬 수 있습니다.
그런 다음 프로젝트별 항목을 추가하세요. 당신의 밤을 앗아간 모든 사건은 이유와 함께 여기에 속합니다.
5. 게이트 설정
레인별로 "완료"의 의미, 이를 증명하는 증거, 병합 전 검토자를 명시하세요.
유지할 기본값은 검토-후-라이브입니다: 빌드, 독립적인 리뷰, 수정 라운드, 병합. 레인의 작성자만의 판단으로 병합하지 마세요. 작성자의 에이전트는 자신의 diff에 대한 최악의 검토자입니다.
6. 보류 항목 표시
의도적으로 완료되지 않음 — 사람 필요 섹션을 만드세요. 명시적인 허가를 위해 보류된 항목은 의도적으로 보류됩니다. 준비된 것처럼 보인다고 레인이 이를 실행하도록 두지 마세요.
격리
빌드는 git 작업 트리에서 실행하세요. 메인 체크아웃이 아닙니다. 하나의 작업 디렉터리를 공유하는 플릿은 편집을 섞을 것입니다. 레인이 맵에도 불구하고 중첩되는 파일을 변경하는 경우, 각 레인에 자체 작업 트리를 제공하세요.
크기 조정
레인은 독립적으로 병합 가능해야 합니다. 레인이 다른 레인의 PR 없이 병합될 수 없다면, 그것은 레인이 아니라 단계입니다. 단계는 순차화하고, 레인은 병렬화하세요.
출력
프로젝트가 계획을 유지하는 곳에 브리프를 작성하고, "검증하되 가정하지 마라"는 경고와 함께 여세요. 소스 문서의 상태 라인은 체크포인트일 뿐이며 권위가 아닙니다. 디스패치하기 전에 라이브 커밋, 데이터베이스 상태, PR 검사 및 작업 트리 헤드를 다시 확인하세요.