crucible은(는) 무엇을 하나요?
병렬 도메인 정찰 → 적대적 제거 → 계획 → 검증 → SPEC → 구현 → PR.
파일 소유권 규칙
서브에이전트는 절대 파일을 쓰지 않습니다. 서브에이전트는 결과를 텍스트로 반환합니다. 오케스트레이터(여러분)가 모든 아티팩트를 작성합니다. 파일은 단계 간 핸드오프 수단이며, 서브에이전트 메모리는 그렇지 않습니다.
설정
호출 시 다음 항목을 파싱합니다:
- 도메인 (필수) — 감사할 사용자 관련 영역, 예:
player,curator - 범위 힌트 (선택 사항) — 도메인 내에서 집중할 범위 좁히기, 예:
lobby SSE,role selection
출력 디렉토리 결정: .crucible/run-<N>/ (N은 사용되지 않은 다음 정수).
이전 실행 확인: .crucible/에서 기존 실행 디렉토리를 스캔합니다. 각 findings.json을 읽습니다. 확인된 ID를 Phase 1 에이전트에 건너뛸 목록으로 제공합니다. 이미 알려진 수정된 문제를 재발견하지 말고, 노력을 격차에 집중합니다.
이번 실행에서 작성되는 파일 (모두 오케스트레이터가 작성):
| 파일 | 단계 | 역할 |
|---|---|---|
codebase-map.md | 1 | 이후 모든 다운스트림 에이전트에 그대로 주입되는 컨텍스트 |
recon-<domain>.json | 1 | 도메인별 원시 발견 결과 |
findings.json | 1→2→4 | 병합된 발견 결과, 각 단계마다 판정이 추가됨 |
PLAN.md | 3 | 우선순위별 수정 계획 |
SPEC.md | 5 | 발견 결과별 코드 변경 전후 및 테스트 케이스 |
Phase 1 — 정찰
에이전트를 실행하기 전에 반드시 references/recon-phase.md를 읽어야 합니다.
선언된 각 도메인에 대해 연구 에이전트 하나씩, 모두 병렬로 실행합니다. 각 에이전트에 다음을 제공: 코드베이스 경로, 도메인 이름, 범위 힌트(있는 경우), 이전에 알려진 건너뛸 ID.
에이전트는 JSON 텍스트를 반환합니다. 에이전트가 JSON 배열 대신 산문을 반환하면, assets/findings-schema.json의 정확한 스키마 형태로 한 번 재프롬프트합니다. 다시 실패하면 빈 recon-<domain>.json([])을 쓰고 codebase-map.md에 실패를 기록합니다. 계속 진행합니다. 하나의 도메인 실패는 복구 가능합니다. 실행을 중단하지 마십시오.
유효한 응답을 수집한 후:
- 각 에이전트 응답별로
recon-<domain>.json작성 codebase-map.md종합 — 주요 파일 경로, 도메인 경계, 공유 모듈, 규칙- 모든 도메인 발견 결과를
findings.json으로 병합
완료 기준: 모든 도메인에 recon-<domain>.json이 있고, codebase-map.md가 작성되었으며, findings.json이 작성되었습니다. Phase 2까지 references/adversarial-phase.md를 로드하지 마십시오.
Phase 2 — 적대적 검토
에이전트를 실행하기 전에 반드시 references/adversarial-phase.md를 읽어야 합니다.
발견 결과당 하나의 일반 에이전트를 실행합니다(같은 도메인의 발견 결과는 일괄 처리). 각 에이전트는 발견 JSON과 codebase-map.md를 받습니다. — 정찰 에이전트의 추론 과정은 받지 않습니다. 독립성 경계가 품질 관문입니다.
에이전트는 코드 증거와 함께 CONFIRMED / REJECTED / DOWNGRADED를 반환합니다. 각 판정을 findings.json의 해당 항목에 추가합니다. node scripts/validate-findings.cjs findings.json을 실행합니다. — Phase 3 전에 스키마 오류를 수정합니다.
유효성 검사기 자체가 실행 불가능한 경우 — node가 PATH에 없거나, 스크립트나 해당 스키마가 누락되었거나, 사용법 오류 또는 검증 시작 전의 모든 실패(Failed to load schema, Failed to parse JSON) — 이는 통과가 아닙니다. 발견 결과 출력과 SPEC 핸드오프 맨 위에 ⚠ findings unvalidated — validator unavailable: <reason>을 기록한 후 계속 진행합니다. 스키마 거부는 반대 경우이며 항상 차단합니다: 발견 결과를 수정하고, 재실행하고, 거부 시 진행하지 마십시오. 둘 다 현재 종료 코드 1을 반환하므로, 종료 코드가 아닌 오류 텍스트를 읽으십시오.
완료 기준: 모든 발견 결과에 adversarial_verdict 필드가 있습니다. 스키마 검증이 통과됩니다. 이 시점부터 references/recon-phase.md를 다시 로드하지 마십시오.
Phase 3 — 계획 수립
발견 결과 없음 확인: 종합하기 전에 findings.json에서 확인 + 등급 하향 항목을 셉니다. 0이면 .crucible/run-<N>/REPORT.md에 "적대적 검토 후 실행 가능한 발견 결과 없음." 한 줄을 씁니다. 중단합니다. — PR을 생성하지 마십시오.
findings.json에서 확인 및 등급 하향된 발견 결과를 종합하여 PLAN.md에 작성합니다:
- P1 (심각/높음): 핵심 흐름 손상, 데이터 손실, 영구 연결 해제
- P2 (중간): 사용자에게 보이는 오류, 복구 경로 누락
- P3 (낮음): 다듬기, 문서 변질, 복사 문제
근본 원인을 공유하는 발견 결과를 그룹화합니다 — 하나의 수정이 여러 문제를 해결할 수 있습니다. 그룹화 시: 그룹화된 발견 결과 중 가장 높은 심각도가 그룹의 우선순위를 설정합니다. 그룹화된 발견 결과의 수정 접근 방식이 충돌하면 분할합니다 — 공유 근본 원인이 공유 수정을 요구하지는 않습니다. 종속성이 있는 경우 수정 순서를 선언합니다. 거부된 발견 결과는 완전히 제외됩니다.
완료 기준: PLAN.md가 작성되었습니다. 모든 확인된 발견 결과가 정확히 한 번씩 나타납니다.
Phase 4 — 독립 검증
P1 + P2 발견 결과당 하나의 연구 에이전트를 실행합니다. 모두 병렬로 실행합니다. 각 에이전트에 다음과 같이 알립니다: "이 발견 결과를 작성한 에이전트가 아닙니다. 모든 사실 주장을 현재 소스 코드에서 확인하십시오."
각 에이전트는 확인: 파일이 경로에 존재하는지, 줄 번호가 설명된 코드와 일치하는지, 범위 이름이 올바른지, 설명된 패턴이 실제로 나타나는지. VERIFIED / CORRECTED [field: wrong → right] / REJECTED [reason]을 반환합니다.
모든 수정 사항을 PLAN.md와 findings.json에 적용합니다. 스키마 검증을 다시 실행합니다. PLAN.md와 findings.json이 일치해야 합니다. — 결과물 간 불일치가 없어야 합니다.
완료 기준: 모든 P1+P2 발견 결과가 검증되었습니다. 모든 수정 사항이 적용되었습니다. 스키마가 통과됩니다.
Phase 5 — SPEC
확인된 발견 결과별로 하나의 섹션으로 SPEC.md를 작성합니다 (P1 → P2 → P3 순서):
- 정확한 파일 경로 + 줄 범위 (검증됨)
- 이전 코드 (실제 소스, 의사 코드 아님)
- 이후 코드 (구체적인 수정)
- 테스트 케이스: 테스트가 검증해야 하는 동작당 한 문장
node scripts/validate-findings.cjs findings.json 최종 확인을 실행합니다.
완료 기준: 모든 PLAN.md 항목에 SPEC 섹션이 있습니다. 검증이 통과됩니다.
Phase 6 — 마무리
- 사용자 대상 동작을 변경하는 발견 결과에 대해 플로우 문서(
docs/flows/) 업데이트 implement스킬을SPEC.md와 함께 호출- PR 열기 — 이것이 HITL 게이트입니다. 중간 승인은 요청되지 않습니다.
PR 본문: PLAN.md 링크, 심각도별 발견 결과 수, SPEC.md 링크, 업데이트된 플로우 문서 목록.
절대 하지 말 것
-
절대 서브에이전트에게 파일을 쓰도록 요청하지 마십시오. 대신: 에이전트가 내용을 텍스트로 반환하게 하십시오. 직접 파일을 작성하십시오. 이유: 단계 간 상태는 파일에 저장됩니다. 에이전트가 직접 작성하면 오케스트레이터가 정식 복사본을 잃고 Phase 4 수정 후 결과물을 조정할 수 없습니다.
-
절대 적대적 에이전트에게 정찰 에이전트의 추론 체인을 제공하지 마십시오. 대신: 구조화된 발견 결과(JSON)와
codebase-map.md만 전달하십시오. 이유: 정찰 에이전트의 논리를 보면 적대적 에이전트가 동일한 가정에 고정됩니다. 독립성 경계가 false positive를 제거하는 요소입니다. -
절대 스키마 검증 실패 상태로 Phase 2를 넘어가지 마십시오. 대신: 계획을 종합하기 전에
findings.json에서 실패한 필드를 수정하십시오. 이유: 잘못된 발견 결과로 작성된 계획은 implement 스킬이 사용할 수 없는 잘못된 파일 경로와 줄 번호가 포함된 SPEC을 생성합니다. -
절대
verification: "pending"인 P1/P2 발견 결과가 있는 상태에서SPEC.md를 작성하지 마십시오. 대신:node scripts/validate-findings.cjs findings.json --pre-spec을 실행하고 Phase 5 전에 모든 실패를 해결하십시오. 이유:--pre-spec가드는 유효성 검사기 스크립트에 존재하지만 호출되지 않으면 보이지 않습니다. 이 호출을 건너뛰는 에이전트는 검증되지 않은 파일 경로로 SPEC을 작성하고 잘못된 줄 번호를 implement에 조용히 전달합니다.