Communitygithub.com

afrizzal/ratchet

Claude Code를 위한 재개 가능한 엔지니어링 루프 — 코드베이스를 검사하여 수용 기준이 있는 백로그를 만들고, 한 번에 하나의 검증된 커밋씩 실행합니다.

ratchet란 무엇인가요?

Ratchet Loop는 Claude Code가 코드베이스를 체계적이고 안전하게 개선할 수 있도록 설계된 실행기(executor) 스킬입니다. 이 스킬의 핵심은 '전진만 허용한다(forward motion only)'는 원칙입니다. 즉, 각 작업 항목은 완전히 완료되고 검증된 후에만 커밋되며, 그렇지 않은 경우에는 그 이유가 Ledger에 명확히 기록됩니다. 이는 AI가 무한 루프에 빠지거나 부분적인 변경 사항을 남기는 문제를 방지합니다. 이 스킬은 v1(단일 파일)과 v2(병렬 레인 지원) 두 가지 백로그 형식을 지원하며, `--lane`, `--only`, `--verify fresh` 등 다양한 옵션을 제공합니다. 특히 고위험 작업(인증, 결제, 데이터베이스 마이그레이션 등)은 엄격한 게이트를 통과해야만 실행되며, 사람의 검토를 요구합니다. v2 레인 시스템을 통해 여러 AI 에이전트가 서로 다른 작업 영역(lane)에서 동시에 작업할 수 있도록 병렬 실행을 안전하게 지원합니다. 또한 실행 전에 전체 상태를 검증하고, 충돌 복구, 커밋 컨벤션 감지 등 일련의 프리플라이트 단계를 거쳐 안정성을 보장합니다. `--dry-run` 옵션을 사용하면 실제로 어떤 작업이 수행될지 미리 확인할 수 있습니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add afrizzal/ratchet

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

Ratchet Loop — 실행기

당신은 ratchet 백로그를 실행하고 있습니다. 당신의 계약은 전진만 허용된다: 항목은 완료-검증-커밋되거나, 완료되지 않아서 Ledger가 그 이유를 정확히 명시하는 상태입니다. 그 사이에 어떤 것도 실행 결과로 남지 않습니다.

백로그 파일은 상태의 단일 소스입니다. 당신은 상태 비저장(stateless)입니다. 이전 실행이 다른 에이전트에 의해 수행되었다고 가정하고(실제로 자주 그렇습니다) 매 실행을 처음처럼 대하십시오. 당신이 배우고 중요하다고 판단되는 모든 것은 파일에 기록되어야 하며, 당신의 '머리'에 남아 있어서는 안 됩니다.

먼저 실행기 규칙을 로드하십시오. 이 SKILL.md가 있는 폴더(즉, 이 스킬의 디렉토리)에서 executor-rules.md를 읽은 후에 어떤 항목도 다루지 마십시오 — 실제 운영에서 추출된 13개의 바인딩 규칙입니다. 규칙과 당신의 직관이 충돌할 때는 규칙을 따르십시오.

호출

/ratchet-loop [경로] [--lane 이름] [--max-items N] [--only ID[,ID...]] [--verify inline|fresh] [--dry-run]
  • 경로 — 백로그 파일. 기본값: ratchet/BACKLOG.md, 없으면 BACKLOG.md (저장소 루트에). 둘 다 없으면 알리고 /ratchet-audit 또는 /ratchet-backlog create를 제안하십시오. 확인된 경로는 아래 모든 곳에서 백로그 파일이며, 해당 디렉토리는 루프의 상태 디렉토리입니다 (기본값 ratchet/).
  • --lane 이름 — v2 백로그 전용 (v1 파일에서는 오류): Lane: 이름이 있는 항목으로만 자격을 제한하고 상태는 lanes/이름.md에만 기록합니다. 이는 병렬 안전 모드입니다 — 아래 "v2 백로그 — 레인"을 참조하십시오. --lane은 상태 선택자(state selector)이지, 라우팅이 아닙니다: 고위험 게이트의 --only 요구 사항을 절대 충족하지 않습니다.
  • --max-items N — 이번 실행에서 N개의 항목이 종료 상태에 도달하면 중지합니다.
  • --only — 나열된 ID로만 자격을 제한합니다 (의존성은 여전히 존중됩니다). 또한 고위험 게이트가 요구하는 명시적 라우팅 신호입니다 — 아래 참조.
  • --verify — 검증 모드, "검증 모드"를 참조하십시오. 기본값 inline.
  • --dry-run — 0단계(Phase 0)만 수행합니다: 검증하고, 실행 계획과 실제 실행이 수행할 복구를 보고하며, 아무것도 쓰거나 커밋하지 않습니다.

상태 파일. 아래 모든 곳에서, 당신의 원장(ledger)과 저널(journal) 쓰기는 상태 파일로 이동합니다: v1에서는 백로그 파일 자체입니다. v2에서는 레인의 파일, lanes/<lane>.md이고, 백로그 파일은 읽기 전용입니다.

0단계 — 사전 점검 (절대 건너뛰지 말고, 절대 순서를 바꾸지 마십시오)

  1. 백로그 파일을 전체 읽고 구조를 검증하십시오: 상단 근처의 버전 마커 — 정확히 <!-- ratchet:v1 --> 또는 정확히 <!-- ratchet:v2 --> (:lane을 포함한 마커는 당신이 레인 파일을 가리켰다는 의미이므로 거절하고 실제 백로그를 가리키십시오); v1의 경우, 네 개의 섹션 모두 (## Items, ## Ledger, ## Journal, 선택적으로 ## Global checks); v2의 경우, ## Lanes + ## Items (+ 선택적 ## Global checks), 백로그에 Ledger/Journal 없음, 추가로 아래 "v2 백로그 — 레인"의 v2 구조 검사; ID는 [A-Z]+-\d+ 패턴과 일치하고 고유해야 함; 모든 항목은 Spec과 ≥1개의 수락 기준(Acceptance criterion)을 가져야 함; 항목당 하나의 Ledger 행 (v2: 레인 파일에서 Lane: 이름)이 있어야 하며, 법적 상태 집합(todo / in-progress / done / blocked / needs-human / skipped) 중 하나여야 합니다. 구조적 결함 → STOP, 정확한 문제를 보고하고, /ratchet-backlog validate를 제안하십시오. 잘못된 형식의 파일을 추측하지 마십시오. 구조를 깨지 않는 항목별 결함 — 오래된 증거, 게이트가 없는 항목에 대한 실행 불가능한 기준 — 은 파일을 거부하지 않고 해당 항목을 보류(parking)하여 처리됩니다. (전체 계약: ratchet 저장소의 docs/backlog-format.md; 필요한 검사는 여기에 나열된 것들입니다.)
  2. 클린 워킹 트리(working tree)를 요구하십시오 — 루프 상태 예외. git status는 추적된 파일에 대해 스테이지되거나 스테이지되지 않은 변경 사항이 없음을 보여주어야 합니다. 발견된 더티(dirty) 상태를 분류하십시오:
    • 당신의 상태 — v1: 백로그 파일 및 상태 디렉토리. v2: 레인 파일만. 추적되지 않음 → 사용자 더티가 아님; 3단계에서 커밋됩니다 (v1에서 이것은 큐레이터가 갓 작성한 백로그가 기록에 들어가는 방식입니다). 추적되었지만 더티 → 이전 실행에서 남겨진 상태 (충돌 또는 동기화되지 않은 sha 백필); 한 줄 저널링하고 3단계가 커밋하도록 둡니다.
    • v2 전용 — 당신 것이 아닌 것은 당신이 정리할 대상이 아닙니다. BACKLOG.md는 당신에게 읽기 전용이므로 "이전 실행 상태"가 아닙니다: 추적된 더티 → 창 밖의 사람의 편집 또는 병합 잔해 → STOP하고 보고하십시오. 추적되지 않음 (백로그 또는 레인 파일) → 큐레이터의 출력이 커밋되지 않았습니다; 이것은 통합 브랜치(integration branch)에서만 괜찮으며, 3단계가 v1과 똑같이 ratchet: add backlog로 커밋합니다. 레인 브랜치에서 추적되지 않은 상태는 백로그가 커밋되기 전에 실행되었음을 의미합니다 → STOP ("먼저 통합 브랜치에 백로그를 커밋하십시오"). 다른 레인의 파일, 더티이거나 in-progress 행을 보유함: 두 번째 실행이 이 워크트리를 사용하고 있을 수 있습니다 → STOP ("가능한 활성 병렬 실행 — 각 레인에 자체 워크트리를 제공하십시오"). 절대 커밋하지 말고, 절대 복구하지 마십시오. 레인 워크트리에서 더티 또는 추적되지 않은 NEXT.md: 정확히 그대로 두십시오 (절대 스테이지하거나 커밋하지 마십시오 — 통합 브랜치 전용입니다) 그리고 보고서에 기록하십시오.
    • in-progress Ledger 항목에 속하는 더티 소스 경로는 충돌 잔해이며, 3단계에서 처리됩니다 — 저널 테일과 항목의 Evidence/Spec을 통해 속성을 확인하십시오; 속성이 모호하면 STOP하고 물어보십시오.
    • 다른 더티 추적 파일 → STOP하고 사용자에게 물어보십시오 (그들의 작업은 당신이 감출 것이 아닙니다). 이 불변성은 당신의 실패 복구를 안전하게 만듭니다.
    • v2 — 어떤 쓰기 작업보다 먼저, 지금 레인의 활성 상태(liveness)를 결정하십시오. --lane이 이름을 지정한 레인, 또는 순차 모드에서 당신이 작업할 첫 번째 레인 (아래 "v2 백로그 — 레인" 참조)의 실행 마커를 읽으십시오. 닫힘(Closed) → 새로운 실행입니다. 열림(Open), 현재 브랜치를 이름으로 지정함 → 충돌 잔해; 기존 마커 아래에서 계속합니다. 열림, 다른 브랜치를 이름으로 지정함 → 레인이 다른 곳에서 활성화되어 있을 수 있습니다: STOP. 그런 다음, 기본 레인 실행 또는 --lane 없는 순차 실행인 경우 장벽 사전 조건을 확인하십시오 — 다른 모든 레인이 닫히고 병합됨 — 여기서 충족되지 않으면 거절하십시오. 이 단계의 모든 거절은 3단계가 아무것도 쓰기 전에 발생하므로, 시작되지 말아야 할 실행은 마커를 남기지 않습니다.
  3. 복구한 다음, 복구를 한 번 커밋하십시오. in-progress에 고정된 Ledger 행은 충돌한 실행의 잔해입니다 — v2에서는 당신의 레인 파일에 있는 행만; 다른 레인의 in-progress는 활성 병렬 실행일 수 있으며 절대 건드리지 마십시오. 각 행에 대해: 2단계에서 속성이 확인된 소스 경로(실행기 규칙 9)가 아직 남아 있다면 정확히 되돌리십시오; found in-progress from a crashed run — reset to todo를 저널링하십시오; 행을 다시 todo로 설정하십시오. 이것이 실행기가 할 수 있는 유일한 역방향 상태 이동이며, 오직 사전 점검 시에만 가능합니다. 그런 다음 2-3단계에서 건드린 모든 것을 포함하는 하나의 커밋을 만드십시오 — 첫 실행 상태 (ratchet: add backlog) 또는 복구 (ratchet: recover state). v2에서, 동일한 커밋은 레인의 시작 저널 라인도 전달합니다, 이는 2단계가 찾은 것에 따라 다릅니다: 새로운 레인은 - <날짜> run started (lane <이름>, branch <브랜치>)를 얻습니다; 당신의 브랜치에서 열려 있는 레인은 - <날짜> found open run from <날짜> — presumed crashed, recovering를 얻고 두 번째 run started는 없습니다 (기존 마커가 여전히 레인의 시작 마커이며, 당신의 run ended가 그것과 균형을 이룰 것입니다). 커밋할 다른 것이 없으면, 해당 라인만 ratchet(<레인>): run open으로 커밋하십시오. v1에서 2-3단계가 아무것도 찾지 못하면 커밋할 것이 없습니다.
  4. Ledger와 전체 저널을 읽으십시오 — v2에서, 이는 당신의 것뿐만 아니라 모든 레인 파일의 원장과 저널을 의미합니다 (당신은 하나의 레인에 쓰고, 모든 것을 읽습니다). 저널은 당신의 유산입니다 — 이전 시도, 알려진 함정, 실패한 가설. 저널이 실패했다고 말하는 것을 새로운 이유 없이 다시 시도하지 마십시오.
  5. 녹색 기준선(Green baseline)을 설정하십시오. ## Global checks 아래의 모든 명령을 결정론적 형태로 한 번 실행하십시오 — 콜드(cold), 증분 캐시 없음, 실행 중인 개발 서버의 생성된 타입에 의존하지 않음 (따뜻한 tsc --noEmit은 CI가 실행하는 것처럼 콜드로 실행된 동일한 검사가 빨간색인 동안 녹색을 보고할 수 있습니다). Global check가 캐시에 민감해 보이고 백로그가 이를 고정하지 않은 경우 콜드 폼을 직접 실행하고 저널에 불일치를 기록하십시오. 빨간색 기준선 → STOP하고 보고하십시오 (깨진 시작점에서 ratchet을 전진시킬 수 없습니다) — 단, [BASELINE] 태그가 지정된 항목이 존재하고 당신이 실행할 수 있는 경우 (v1: 항상; v2: 해당 Lane:이 당신의 --lane과 일치하거나 --lane이 주어지지 않은 경우)는 예외이며, 이 경우 해당 항목이 파일 순서보다 앞서는 필수 첫 번째 선택입니다. v2 --lane X 실행에서 [BASELINE] 항목이 다른 레인에 속하면 STOP하고 보고하십시오: "baseline-blocked by <ID> in lane <Y> — run that lane first, merge, then relaunch". 대기는 중지이며, 다른 레인에 대한 쓰기가 아닙니다.
  6. git log --oneline -15에서 저장소의 커밋 컨벤션을 감지하십시오 (컨벤셔널 커밋? 일반 문장? 범위 접두사?). 일치시킬 것입니다.
  7. 브랜치를 확인하십시오. 저장소의 기본 브랜치에 있고 저장소가 PR 기반이거나 푸시 투 디플로이(push-to-deploy)인 경우 첫 번째 커밋 전에 작업 브랜치(ratchet/<범위-또는-날짜>) 생성을 제안하십시오 — /ratchet-ship이 나중에 PR을 엽니다. 사용자의 명시적 동의가 있을 때만 기본 브랜치에서 진행하십시오. v2 --lane X 실행에서 브랜치는 선택 사항이 아닙니다: ratchet/X가 존재하면 재개하고, 그렇지 않으면 통합 브랜치 헤드에서 생성하며, 통합 브랜치보다 뒤쳐져 있다면 병합하십시오 — 아래 "v2 백로그 — 레인"을 참조하십시오.
  8. NEXT.md (상태 디렉토리에)가 존재하면 읽으십시오. /ratchet-recommend의 라우팅된 계획입니다: 항목별 verify 할당을 존중하십시오 — SUPERVISED 또는 SENIOR로 라우팅된 항목은 --verify fresh가 필요합니다. fresh가 적용되지 않은 경우, 이 실행에서 실행될 SUPERVISED/SENIOR 항목만 보류하십시오 (자격을 통과하고 --only와 일치함); 이 실행 범위 밖의 항목은 건드리지 않고 그대로 둡니다 — 해당 웨이브 명령은 이미 올바른 플래그를 가지고 있습니다. NEXT.md가 마지막 Ledger 변경 (v2: 당신의 레인 파일에 대한 마지막 변경)보다 오래된 경우, 그것이 오래되었다고 말하고 재생성을 제안하십시오 — v1: 평소처럼 상태 디렉토리에; v2: 통합 브랜치에서, 레인 워크트리에서는 절대 안 됩니다. 호출자의 명시적 플래그가 NEXT.md를 재정의합니다. v2에서 읽기 전용: NEXT.md를 쓰거나, 스테이지하거나, 커밋하지 마십시오.
  9. 계획을 발표하십시오: 순서대로 자격 있는 항목, 이유가 있는 보류된 항목, 브랜치, 적용 중인 중지 조건. --dry-run에서는 여기서 멈추십시오 — 드라이 런은 아무것도 쓰지 않으므로, 실제로 만드는 대신 2-3단계가 만들었을 커밋을 보고하십시오. 따라서 드라이 런은 레인을 절대 열지 않습니다: run started 마커가 기록되거나 커밋되지 않으므로, 열린 레인을 남기지 않습니다.

자격

항목은 다음 모든 조건이 참일 때 자격이 있습니다: Ledger 상태 todo · 휴먼 게이트 태그 없음 ([USER-DECISION], [OPS], [RISKY]) · 모든 Depends: ID가 done임 (v2: 교차 레인 의존성은 당신의 워크트리에서 보이는 done 행으로만 계산됩니다 — 완료 및 병합됨) · 제공된 경우 --only와 일치 · 제공된 경우 --lane과 일치. 파일 순서대로 자격 있는 항목을 가져가십시오. 모든 --only ID가 존재하지만 호출된 레인의 Lane:을 가지지 않는 경우, 이는 오류입니다 ("SEC-01은 ui 레인에 있습니다. --lane ui로 다시 실행하거나 NEXT.md를 재생성하십시오"), 조용한 "백로그 고갈"이 아닙니다. 휴먼 게이트된 todo 항목: 해당 Ledger 상태를 needs-human으로 설정하고 태그를 메모로 추가한 후 (한 번), 계속 진행하십시오. 보류된 항목은 사람이 보류를 해제할 때까지 보류 상태로 유지됩니다 — 상태를 todo로 되돌리고, 게이트 태그를 제거하고, 결정을 저널링합니다 (형식의 "Human transitions" 절차); 당신이 직접 이 작업을 수행하지 마십시오.

고위험 게이트 (기계적). 항목의 Spec 또는 Evidence가 다음 트리거 목록 중 하나라도 언급하면 고위험입니다 (실행기 규칙 1에서 그대로): 인증/권한, 테넌트 경계(companyId / 소유권 범위), 결제 또는 금전 계산, GL/분개 전기, 데이터베이스 마이그레이션, 비밀/환경 변수, 파일 또는 행 삭제, 세션/쿠키 처리. 게이트되지 않은 고위험 항목은 둘 다 참일 때만 실행 가능합니다: (a) --verify fresh가 적용 중이고, (b) 호출자가 --only에 명시적으로 해당 항목을 나열한 경우 — 즉, 사람 또는 NEXT.md 라우팅이 이 실행을 위해 선택한 경우. --lane은 절대 (b)로 간주되지 않습니다. 그렇지 않으면 needs-human으로 보류하십시오 (메모: "고위험; /ratchet-recommend를 통해 라우팅"). 예외: [BASELINE] 항목은 --only 요구 사항에서 면제됩니다 — 해당 태그 자체가 사람의 라우팅이며, 실행은 그것 없이는 진행될 수 없습니다 — 하지만 트리거 목록에 닿고 fresh를 사용할 수 있는 경우 해당 항목에 대해 fresh 검증을 사용하십시오. 당신이 어떤 모델인지 스스로 평가하지 마십시오 — 플래그가 결정합니다. 인증 또는 금전에 대한 잘못된 "녹색"은 Ratchet이 방지하기 위해 존재하는 가장 비용이 많이 드는 실패입니다; 사람의 한 번 훑어보는 비용은 항상 더 낮습니다.

v2 백로그 — 레인

v2 백로그 (<!-- ratchet:v2 -->)는 레인별로 상태를 분할합니다: 백로그는 ## Lanes + ## Items를 보유하고 (각 항목은 Lane: <이름>을 전달함), 각 레인의 Ledger + Journal은 lanes/<lane>.md에 있습니다 — 단일 작성자, 따라서 병렬 에이전트가 동일한 파일에 절대 쓰지 않습니다. 전체 계약: ratchet 저장소의 docs/backlog-format.md §5; 실행기가 필요한 모든 것은 아래에 있습니다.

v2 구조 검사 (사전 점검 1단계 추가). 다음 중 하나라도 있으면 STOP하십시오: ## Lanes 없음; 첫 번째 레인의 Scope가 리터럴 (rest)가 아님 또는 두 번째 레인도 (rest)를 주장함 (정확히 하나의 기본 레인); 명명된 레인 범위의 중복; Lane:이 없거나 선언되지 않은 레인을 명명하는 항목; 선언된 레인이지만 lanes/<lane>.md가 없거나 <!-- ratchet:v2:lane <이름> --> 마커가 파일 이름 및 선언과 일치하지 않음; 어디에도 Ledger 행이 없는 항목, 잘못된 레인 파일에 있는 행, 또는 파일 간 중복 행. 레인 파일을 생성하지 마십시오 — 그건 큐레이터의 작업입니다 (/ratchet-backlog). --lane X 실행에서 거부 범위: 백로그, lanes/X.md, 또는 X 자체 항목의 행 상주에서의 결함은 STOP입니다; 다른 레인 파일에 국한된 내부 손상은 큰 WARN입니다 — 보고하지만 절대 건드리지 마십시오.

실행 마커 (활성 신호). 저널을 아래에서 위로 스캔할 때 발견된 첫 번째 실행 마커가 run started이면 레인은 열려 있습니다. 실행은 작업할 레인에 - <날짜> run started (lane <이름>, branch <브랜치>)를 추가하고 커밋하여 레인을 열니다 (사전 점검 3단계, 또는 ratchet(<레인>): run start). 실행이 끝나면 - <날짜> run ended (lane <이름>, branch <브랜치>, N items, <SHA 범위>)를 추가하고 ratchet(<레인>): run end로 커밋하여 레인을 닫습니다. 마커가 없는 레인은 닫힌 것으로 간주됩니다. --lane 실행은 해당 레인만 열고 닫습니다. 순차 실행 (레인 지정 없음)은 항목 순서대로 각 레인을 열고, 그 레인의 모든 자격 있는 항목을 실행하고, 다음 레인으로 이동하기 전에 닫습니다.

실행 루프 (각 항목에 대해)

자격 있는 각 항목에 대해 다음 단계를 순서대로 수행하십시오. --max-items 또는 --only가 중지 조건을 충족하면 루프를 중단하십시오.

  1. 항목을 선택하고 Ledger를 업데이트하십시오: 항목의 Ledger 행을 in-progress로 설정하십시오. v1: 백로그 파일에서; v2: 레인 파일에서.
  2. Spec을 읽고 이해하십시오: 항목의 Spec과 모든 Acceptance 기준을 주의 깊게 읽으십시오. 저널에 기록된 이전 시도 또는 함정을 확인하십시오.
  3. 구현을 실행하십시오: Spec을 충족하고 모든 Acceptance 기준을 통과하는 코드 변경을 만드십시오. 필요에 따라 파일을 수정하고, 테스트를 추가하고, 문서를 업데이트하십시오.
  4. 변경 사항을 검증하십시오: --verify 모드에 따라 검증을 수행하십시오. inline 모드에서는 기준을 충족하는지 확인하기 위해 자체 검증(예: 테스트 실행)을 수행하십시오. fresh 모드에서는 --verify fresh가 요구하는 대로 추가 검증(예: 더 엄격한 테스트, 수동 검토)을 수행하십시오.
  5. 결과를 저널링하고 Ledger를 업데이트하십시오: 성공하면 Ledger 행을 done으로 설정하고, 검증 증거(예: 테스트 결과, 스크린샷)를 기록하십시오. 실패하면 Ledger 행을 blocked로 설정하고, 실패 이유와 함께 저널에 기록하십시오. 특수한 경우: needs-human은 사람의 개입이 필요함을 나타냅니다. skipped는 항목이 건너뛰어졌음을 나타냅니다.
  6. 커밋을 만드십시오: 변경 사항을 스테이지하고, 저장소의 커밋 컨벤션을 따르는 커밋 메시지로 커밋하십시오. 커밋 메시지는 항목 ID를 참조해야 합니다 (예: feat(scope): implement SEC-01).
  7. 루프를 반복하십시오: 다음 자격 있는 항목으로 이동하거나 중지 조건을 확인하십시오.

검증 모드

  • --verify inline (기본값): 각 항목의 Acceptance 기준을 실행기 자체적으로 검증합니다. 예를 들어, 단위 테스트를 실행하거나, linter를 실행하거나, 기타 자동화된 검사를 수행합니다. 이 모드는 빠르지만, 복잡한 또는 고위험 변경 사항에 대해서는 충분하지 않을 수 있습니다.
  • --verify fresh: 각 항목에 대해 추가적이고 더 엄격한 검증을 수행합니다. 이는 일반적으로 --only와 함께 사용되며, 고위험 게이트를 통과하는 데 필요합니다. fresh 모드는 더 많은 시간과 리소스를 소비하지만, 더 높은 신뢰도를 제공합니다.

상태 파일 형식

v1

<!-- ratchet:v1 -->
## Items

| ID | Spec | Acceptance | Depends | Lane |
|----|------|------------|---------|------|
| SEC-01 | Implement authentication | User can log in | - | - |

## Ledger

| ID | Status | Note |
|----|--------|------|
| SEC-01 | todo | - |

## Journal

- 2024-01-01 run started
- 2024-01-01 SEC-01: implemented

## Global checks

- `npm run lint`
- `npm test`

v2

백로그 파일 (BACKLOG.md):

<!-- ratchet:v2 -->
## Lanes

| Lane | Scope |
|------|-------|
| auth | (rest) |
| ui | components/* |

## Items

| ID | Spec | Acceptance | Depends | Lane |
|----|------|------------|---------|------|
| SEC-01 | Implement authentication | User can log in | - | auth |
| UI-01 | Add login button | Button appears | SEC-01 | ui |

## Global checks

- `npm run lint`

레인 파일 (lanes/auth.md):

<!-- ratchet:v2:lane auth -->
## Ledger

| ID | Status | Note |
|----|--------|------|
| SEC-01 | todo | - |

## Journal

- 2024-01-01 run started (lane auth, branch ratchet/auth)

종료 상태

  • done: 항목이 성공적으로 구현 및 검증되었습니다.
  • blocked: 항목이 외부 의존성 (예: 다른 항목, 사람의 결정)에 의해 차단되었습니다.
  • needs-human: 항목이 사람의 개입이 필요합니다 (예: 고위험 결정, 명확하지 않은 요구 사항).
  • skipped: 항목이 건너뛰어졌습니다 (예: 더 이상 관련이 없거나, 구현할 수 없음).
  • in-progress: 항목이 현재 구현 중입니다 (충돌 후 복구 중에만 발생해야 함).
  • todo: 항목이 아직 시작되지 않았습니다.

사람의 전환

사람은 다음을 수행할 수 있습니다:

  • 항목의 상태를 needs-human에서 todo로 변경하고 게이트 태그를 제거합니다.
  • 항목의 상태를 blocked에서 todo로 변경합니다.
  • 항목의 상태를 done 또는 skipped와 같은 최종 상태로 직접 변경합니다.
  • 저널에 결정을 기록합니다.

실행기는 이러한 전환을 직접 수행하지 않으며, 사람이 수행할 것이라고 가정합니다.

오류 처리

  • 구조적 오류: 파일 형식이 잘못되었거나, 누락된 필드가 있거나, 잘못된 ID 형식이 있는 경우 STOP하고 정확한 문제를 보고하십시오.
  • 실행 오류: 항목 구현 중 오류가 발생하면 (예: 테스트 실패, 컴파일 오류), 오류를 저널링하고 항목을 blocked로 표시하십시오.
  • 충돌 복구: 사전 점검 중에 in-progress 항목이 발견되면, 소스 변경 사항을 되돌리고 항목을 todo로 재설정한 후 복구 커밋을 만드십시오.
  • 게이트 위반: 고위험 항목이 적절한 게이트 (--only + --verify fresh) 없이 실행되려고 하면, 항목을 needs-human으로 보류하십시오.

보안 고려 사항

  • 비밀/환경 변수: 비밀 또는 환경 변수를 다루는 항목은 특별한 주의가 필요합니다. 이러한 항목은 항상 fresh 검증과 --only 라우팅이 필요합니다.
  • 데이터베이스 마이그레이션: 데이터베이스 마이그레이션은 되돌릴 수 없는 변경을 방지하기 위해 항상 사람의 검토가 필요합니다.
  • 권한 상승: 인증 또는 권한과 관련된 변경 사항은 보안 허점을 방지하기 위해 엄격한 검증이 필요합니다.

NEXT.md 형식

NEXT.md (선택 사항)은 /ratchet-recommend에 의해 생성된 라우팅 계획을 포함합니다:

# Next Items

- SEC-01: verify=fresh (reason: auth, high-stakes)
- UI-01: verify=inline

NEXT.md가 존재하면, 해당 verify 할당은 기본값 또는 --verify 플래그를 재정의합니다. NEXT.md가 오래된 경우 (마지막 Ledger 변경보다 오래된 경우), 실행기는 이를 무시하고 재생성을 제안해야 합니다.

한계

  • 병렬 실행: 각 레인은 한 번에 하나의 실행기 인스턴스만 가질 수 있습니다. 병렬 실행을 위해서는 별도의 워크트리와 별도의 레인이 필요합니다.
  • 상태 크기: 백로그 파일은 많은 항목으로 인해 매우 커질 수 있습니다. 효율적인 처리를 위해 적절하게 분할하는 것을 고려하십시오.
  • 의존성: 교차 레인 의존성은 의존하는 레인이 완전히 병합될 때까지 해결되지 않을 수 있습니다.
  • Global checks: Global checks는 결정론적 형태로 실행되어야 합니다 (콜드, 증분 캐시 없음). 캐시에 민감한 검사는 문제를 일으킬 수 있습니다.

관련 명령어

  • /ratchet-audit: 코드베이스를 분석하고 새로운 백로그를 생성합니다.
  • /ratchet-backlog: 백로그를 생성하거나 검증합니다.
  • /ratchet-recommend: 백로그를 분석하고 실행할 다음 항목을 추천합니다 (NEXT.md 생성).
  • /ratchet-ship: 완료된 레인을 위한 PR을 엽니다.
  • /ratchet-validate: 백로그 형식을 검증합니다.

참조

  • Ratchet 저장소
  • docs/backlog-format.md — 전체 백로그 형식 명세
  • executor-rules.md — 바인딩 실행기 규칙

관련 스킬