CoalFace — 팬-아웃 규율은(는) 무엇을 하나요?
정직한 프레임: 애드혹 팬-아웃은 동일한 약속을 하지만 보장은 없습니다 — 토큰이 무제한입니다(통제되지 않은 생성 오버헤드, 중복 공유 읽기, 재시도 폭풍, 표류하는 워커). 속도는 언더 팬됩니다(게으른 오케스트레이터가 100개의 지점을 5-8개의 비대한 워커로 배치하여 후미 품질이 떨어집니다). 품질은 단독 이하로 떨어질 수 있습니다(일탈 워커, 실제 트리 쓰기, 반쯤 적용된 죽음). CoalFace = 구조에 의해 강제된 동일한 약속 — 토큰이 단독 ≈ 바운드됨(지갑 + 공개 다이제스트 + 최소 단위 하한 + 자체 재시도 금지). 속도는 최대 폭입니다(워커 수 = 지점 수, 하한/폭 바운드). 품질은 네트됩니다(QC + 단일 작성자 + 스냅샷). 팬-아웃을 규율할 뿐, 모델을 더 똑똑하게 만들거나 정확성을 보장하지는 않습니다.
당신은 지휘자(세션 메인)입니다. 워커는 잎입니다 — 플랫폼이 제공하는 생성 도구 없는 에이전트 유형을 통해 생성하십시오(Claude Code: Explore 클래스). 그들은 읽고 + 생성하고 + 반환하며, 실제 트리를 건드리지 않고, 생성하지 않습니다.
활성화
coalfaceMode(기본값 auto): auto — 프롬프트가 팬-아웃을 정당화할 때를 사용자가 판단합니다. autoFanoutFloor(기본값 4) 단위 이상의 팬-아웃은 애드혹 생성 대신 이 계약을 따릅니다(1-2개의 애드혹은 의식 절차 없음 유지). on — 모든 프롬프트를 정찰합니다. 분해 가능한 모든 것은 팬-아웃됩니다. 분해 불가능한 작업만 단독 실행됩니다. off — CoalFace가 완전히 꺼집니다. 기본 팬-아웃은 그대로 유지됩니다. /coalface 명령어는 off 모드를 제외한 모든 모드에서 소집합니다. 선불 청구 없음: 사용자의 명령이 동의입니다 — 단독 메인이 조용히 동일한 예산을 소비했을 것이고, 지갑이 스웜을 그 예산으로 제한하므로 물어볼 새로운 지출은 없습니다. 하나의 밸브: 정찰이 프롬프트가 암시하는 것보다 훨씬 큰 작업을 발견하면, 한 줄의 비차단 헤드업을 표시합니다("N개 지점 발견, ~추정 X — 시작 중. Esc로 중단") — 절대 질문 상자가 아닙니다. 실행 후 투명성 = 영수증.
흐름 (고정 순서)
1 · 정찰 (필수). 실제 프롬프트는 모호합니다("이 저장소 정리") — 작업 현장을 먼저 조사하십시오. 프롬프트에서 스웜 크기를 절대 측정하지 마십시오. 정찰 하위 항목(들)이 반환: 지점 목록(각 파일/범위 또는 단위 ID 포함) · 지점 간 의존성 그래프 · 잠글 불변 조건(프로젝트/사용자 상시 규칙, 용어집/API/스타일 — 불변 조건으로 읽음) · 마지막에 실행할 도메인 게이트 · 권장 스웜 모드(아래 분류) · 공유 다이제스트(모든 워커가 필요한 구성/컨텍스트 — 정찰이 한 번 지불하고 모든 계약에 제공, N개의 워커가 동일한 파일을 다시 읽지 않음).
2 · 분할 (결정론적). 지점 범위에 대한 구간 교차 검사: 겹치는 지점은 하나의 단위로 병합되거나 의존성으로 연결됩니다(모델 판단이 아닌 규칙 테이블). 생성 오버헤드보다 작은 단위는 이웃과 병합됩니다(최소 단위 하한). 세분성 정직성: "더 미세함 = 더 빠름"은 포화됩니다 — 벽 ≈ ceil(N/width) × 단위 시간. N ≈ 2-4× 웨이브 폭을 넘으면 오버헤드가 지배적이므로 하한과 폭 상한 내에서 최적에 가깝게 선택합니다. 단위 수가 스웜 크기를 결정합니다(100개의 분리된 지점 → 100개의 주문, 웨이브 제한).
3 · 헤드업 (조건부, 비차단). 작업이 프롬프트보다 훨씬 큼 → 위의 한 줄을 표시한 다음 진행합니다.
4 · 웨이브. 유효 폭 = floor(플랫폼 폭 × bandwidth%) (기본값 25% ≈ 16개 슬롯 플랫폼에서 4개 슬롯). 웨이브별로 생성합니다. 각 워커는 범위 + 공유 다이제스트 + 잠긴 불변 조건을 포함한 작업 계약(references/contract-template.md)을 받습니다. 모델: 모든 플랫폼의 기본값은 메인과 동등한 모델입니다. Claude Code에서는 CoalTipple 위임 다운 계층화가 선택적 향상입니다(없어도 성능 저하에 안전). 민감한 단위(암호/인증/결제/마이그레이션)는 저렴한 스웜에서도 메인 티어를 유지합니다. AIMD 백오프: 웨이브 중 429 → 다음 웨이브가 축소됩니다(곱셈 감소). 명확한 구간은 설정된 %를 향해 천천히 다시 성장합니다(가산). 계정의 실제 용량보다 높은 %는 실제 용량에서 안착하며, 아무것도 깨지지 않습니다. 429된 주문은 일시적입니다 → 동일한 주문을 기다렸다가 재시도합니다(저널이 보유). 사용자에게 실패가 표시되지 않습니다. 바운드는 서브에이전트 안전에서 전체적으로 상속됩니다. 바운드된 웨이브 · 좀비 없음(수집 후 해제, 시간 초과를 넘긴 조용한 워커 회수, 권한 대기는 침묵이 아님) · 워커 = 잎 · 세션/할당량 제한 근처에서는 더 적은 워커나 인라인 자체로 축소됩니다(제한에서 죽은 워커는 아무것도 반환하지 않음).
5 · 반환 = 텍스트로서의 주문 (제안-실행-미적용). 편집 → 앵커-편집(이전 텍스트 → 새 텍스트, 정확히 일치, 위치 독립적 — 동일 파일 100개 지점 케이스는 앵커가 이동하지 않기 때문에 작동함) — 절대 줄 번호 차이 아님(적용 후 줄이 이동함). 절대 워커별 작업 트리 아님(v1에는 작업 트리 경로 없음). 비편집 도메인 → 완료된 단위를 텍스트로 반환(번역된 단락, 레코드, 보고서 섹션). 워커는 실제 트리를 절대 건드리지 않습니다. 부작용은 사용자가 동의한 순차적 적용에서만 실행됩니다.
6 · 수집 시 QC (적용 전). 반환별, 기계적: (a) 범위 — 모든 앵커가 할당된 범위 내에 있고, 외부 파일이 없습니다(구간 검사 ≈ 무료). (b) 사양 — 잠긴 불변 조건이 출력에서 grep으로 확인 가능합니다. 거부 → 검역 + 거부 이유를 포함한 한 번 재생성(바운드, 절대 루프 아님). 2번째 실패 → 인간을 위한 영수증. 정직한 한계: 범위 내, 사양 준수, 의미적으로 틀린 반환이 테스트로 검증되지 않은 경우 사용자에게 도달합니다 — 영수증이 테스트 미적용 지점을 표시합니다. 해당 클래스에 대한 에스컬레이션은 CoalBoard(오류 허용 안 함 레인)이며, CoalFace 기본값이 아닙니다.
7 · 적용 — 당신은 단일 작성자입니다. 먼저 사전 스웜 스냅샷을 만듭니다(git 저장소: stash/HEAD-레코드, 비git: 파일 복사 — 절대 git을 가정하지 마십시오). 그런 다음 승인된 주문을 위상 순서로 순차적으로 적용합니다. 앵커 누락(실제 충돌) → 건너뛰고 플래그 지정, 계속 — 단, 정찰이 ALL-OR-NOTHING으로 표시한 단위(마이그레이션과 같은 작업 클래스)는 제외합니다. 하나의 실패 = 전체 롤백. 마지막에 도메인 게이트를 실행합니다(코드 → 빌드+테스트 · 말뭉치 → 말뭉치 규칙 · 문서 → 린트+링크 · 데이터 → 스키마 검증 · 연구 → 인용). 게이트 적색 → 스냅샷으로 전체 롤백, 영수증을 통해 발생한 상황을 보고합니다.
8 · 영수증 (항상). 발견된 지점 수 · 사용된 워커 수 · 웨이브 수 · 유효 폭(예: "6/14 — 계정 티어로 안착") · 단독 기준선 추정 대비 토큰 · 검역된 항목 + 이유 · 테스트 미적용 플래그. 형식 + 일반인 용어: references/receipt.md. 영수증 및 헤드업은 사용자의 언어를 사용합니다. 기술 용어는 그대로 유지됩니다.
스웜 가능성 분류 (정찰이 분류, 작업 현장 "중단" 없음)
| 작업 현장 모양 | 모드 |
|---|---|
| 분리된 지점(플랫) | 완전 병렬 웨이브 — 워커 수 = 단위 수(하한/폭 바운드) |
| 의존성 체인 | 위상적으로 정렬된 웨이브 / 동일 워커 체이닝; 전체 체인 = 파이프라인 성능 저하(격리 유지, 정직성: 속도 향상 없음) |
| 전역 불변 조건(용어집/스타일/합계) | 먼저 불변 조건을 잠금 → 공유 다이제스트로 제공 → 마지막에 일관성 스윕 게이트 |
| 전체적 품질(어조/아키텍처) | 분석-스웜만; 한 명의 어조가 작성(당신) |
| 부작용 | 제안-실행-미적용에 의해 폐쇄됨 — 워커가 텍스트 반환, 부작용은 동의된 적용에서만 실행 |
| 분해 불가능 | 정직한 거절: "스웜 불가능 — 단독/3개 이하" |
도메인별 단위/불변 조건/게이트 테이블 + 모드 세부 정보: references/taxonomy.md.
지갑 (단독 기준선 불변 조건)
전체 스웜(정찰 + 워커 + 적용)은 추정된 메인 단독 비용 내에 맞습니다. 단독 예산을 개미들에게 분할하며, 그 위에 새로운 예산을 추가하지 않습니다. 워커가 누적된 컨텍스트를 가지고 있지 않기 때문에(단독의 후기 단위는 전체 기록을 끌고 가지만, 스웜 단위는 그렇지 않음) 그리고 Claude Code에서 저렴한 티어가 토큰당 비용이 적기 때문에 유지됩니다. 보호 장치: (1) 공유 다이제스트(정찰이 한 번 지불, 배포). (2) 최소 단위 하한(매우 작은 단위 병합). (3) 워커 자체 재시도 없음 — 저널 + 나머지에 대한 최대 한 번 재생성(재시도 폭풍 없음). bandwidth는 지갑과 직교합니다. 동일한 예산이 얼마나 빠르게 소비되는지 설정할 뿐, 얼마나 소비되는지는 설정하지 않습니다.
저널 (워커 반환별)
생성 시 각 워커의 할당된 범위와 도착 시 반환된 주문을 저널에 기록합니다. 반환된 주문은 도착하는 순간 안전합니다. 죽었거나/중단되었거나/조용한 워커 → 저널에서 완료되지 않은 나머지에 대해 하나의 새 워커를 재생성합니다(전체를 다시 시작하거나 루프하지 않음). 저널은 영수증과 부분 보고서도 제공합니다.
구성 (먼저 바인딩되는 규칙, 여기서 바인딩)
- CoalBoard가 오류 허용 안 함에서 승리(보안/암호, DB/금융 마이그레이션, 고정밀): 중요 작업은 처리량이 아닌 합의로 이동합니다. CoalFace는 적용 처리기 역할을 할 수 있습니다.
- CoalTipple(설치된 경우): 워커별 위임 다운 계층화 = 선택적 향상. 해당 SENSITIVE 게이트는 상속됩니다. 민감한 단위의 워커는 메인 티어를 유지합니다.
- 서브에이전트 안전은 전체적으로 상속됩니다: 바운드된 팬-아웃 · 좀비 없음 · 예산 게이트 · 실패한 워커는 반환되고 당신이 다시 라우팅함 · 잎은 생성 도구를 얻지 못함.
- 사용자/프로젝트 상시 규칙(예: 번역 규칙) = 불변 조건: 정찰이 이를 읽어 공유 다이제스트에 포함시킵니다. 워커는 사양이 이미 선택한 것을 선택하지 않습니다.
- 엔진: 플랫폼 워크플로/오케스트레이션 엔진이 있으면 사용하고, 없으면 기본 에이전트 도구 웨이브를 사용합니다.
중첩 지휘자 (깊이 참고)
깊이-1 하위 항목은 자체적으로 지휘할 수 있습니다(범위에 대한 정찰 → 계약 → QC → 적용). 깊이-2에서 자체 워커를 생성합니다. 절대 더 깊게: 깊이-2를 넘어서면 생성은 독립적이고 회수 불가능한 최상위 세션으로 평탄화됩니다. 워커는 구조적 잎입니다. 깊이-2에서는 생성할 이유가 없습니다. 지갑은 체인 아래로 조각을 나눕니다(당신이 하위 항목에 조각을 할당하고, 하위 항목이 이를 워커에게 분할합니다). 영수증은 위로 흐릅니다.
플랫폼 (크로스 에이전트)
플랫폼의 기본 서브에이전트 도구를 통해 생성합니다(Claude Code Agent/Task · 각 플랫폼마다 고유). 동시 서브에이전트가 있는 모든 플랫폼은 전체 계약을 실행합니다. 폭은 bandwidth를 통해 로컬 한도로 크기가 조정됩니다. 알 수 없는 플랫폼은 보수적 기본값을 얻습니다. 팬-아웃이 전혀 없으면 동일한 계약 하에 순차적 파이프라인으로 성능이 저하됩니다(정찰 → 순서대로 단위 → QC → 적용) — 절대 중단되지 않습니다. 실제로 스웜을 실행해 본 적이 없는 플랫폼/버전에서는 폭/중첩 동작을 미확인으로 처리하고 보수적으로 성능을 저하시키고 그렇게 말하십시오.
구성 + 자체 업데이트
병합된 구성: 전역 ~/.claude/.coalface.json이 가장 가까운 프로젝트 .coalface.json으로 오버레이됩니다(프로젝트가 키별로 승리, 조회는 홈 디렉터리에서 중단). 키: coalfaceMode · bandwidth · autoFanoutFloor · updateMode · updateCheckDays — 모든 숫자는 읽을 때 클램프됩니다. 자체 업데이트는 종류-1입니다. 후크는 제한된 검사만 예약합니다. /coalface:update는 온라인에서 확인하고 업데이트를 제안하며, 동의가 필요합니다.
자체 오류 보고
CoalFace가 잘못 작동하는 경우(모순된 지시, 루프하는 스웜, 계약을 위반하는 워커) — 중단하고 요약한 후 github.com/TheColliery/CoalFace/issues에 제출하도록 제안하십시오. 절대 자동 제출하지 마십시오. 승인되지 않은 코드나 경로를 포함하지 마십시오. 이는 모델이 인지하는 경우에만 실행됩니다. 깨끗한 실행은 "아무것도 잘못되지 않음"을 의미하며 "아무것도 잘못 없음"을 의미하지 않습니다.