본문으로 건너뛰기

SpecWeave CLI 3.1.0무료 오픈소스

작업은 세션보다 오래 남아요.

코드는 에이전트가 작성해요. SpecWeave는 완료의 의미, 그것을 증명한 것, 멈춘 지점을 git의 일반 파일로 보관해서 Claude Code, Codex, 어떤 에이전트든 같은 작업을 이어갈 수 있어요.

npm i -g specweave
내 프로젝트에서 시작전체 명령

버전 3.1.0, 17 October 2026 출시. 무료 오픈소스.

$ specweave pickup
Picked up the handoff from claude@cloud (out of tokens): applied 7 uncommitted files.
SpecWeave pickup · you are codex@laptop
Increment 0001-resumable-checkout "Resumable checkout" (active) · tasks 1/2 done
Next: T-02 Restore the draft on return
  AC-01: Returning within 24 hours restores the cart and shipping choice
  AC-02: A paid order is never restored
  Files: src/restore.js | Test: npm test
Branch: main · in sync with origin/main · 3 uncommitted files
Last handoff: claude@cloud: out of tokens · next: finish restore on return
Notes:
- claude@cloud: Payment thread: drafts must never store card data
Claude Code가 핸드오프한 뒤 Codex로 실행한 두 번째 클론의 실제 출력이에요.

계획부터 완료까지 여섯 개의 명령

모든 단계가 파일을 남겨요. 체크박스만으로 닫히는 일은 없어요. 테스트가 실행되고, 출력이 저장되고, 검증이 통과할 때까지 인크리먼트는 열려 있어요.

  1. 01 인크리먼트 계획

    $ specweave create-increment "Resumable checkout"

    에이전트가 문제, 범위, 번호가 붙은 인수 기준, 접근 방식, 작업을 채워요. 작성하기 전에 sw-increment는 사용자의 결정이 필요한 것만 추천 답변과 함께 하나씩 물어보며, 기본값은 최대 5개이고 깊이는 planning.deepInterview로 정해요.

    spec.md각 작업에는 기준, 파일, 테스트가 명시돼요.

  2. 02 작업 맡기

    $ specweave task claim T-02

    맡은 기록이 원장에 남기 때문에 다른 에이전트가 같은 작업을 요청하면 거부돼요. 2시간이 지난 담당 기록은 오래된 것으로 보고 넘겨받을 수 있어요. specweave task next는 다음 작업을 기준 텍스트와 함께 출력해요.

    ledger.jsonl추가만 가능: 담당, 완료, 해제, 건너뜀, 차단 이벤트.

  3. 03 완료를 증명하기

    $ specweave task done T-02 --run "npm test"

    CLI가 테스트를 직접 실행해요. 종료 코드 0일 때만 작업이 완료로 기록되고, 커밋과 출력 끝부분이 증거로 남아요. 실패한 실행은 아무것도 기록하지 않아요.

    reports/task-T-02.txt전체 명령 출력과 종료 코드, 소요 시간.

  4. 04 인크리먼트 검증

    $ specweave verify

    testing.commands나 package.json, Cargo, pytest, Go에서 감지한 테스트, 린트, 빌드 명령을 실행하고 모든 인수 기준을 확인해요.

    reports/verify.json모든 명령과 기준이 통과해야만 ok가 true예요.

  5. 05 다른 모델로 리뷰

    $ specweave review

    코드를 작성한 모델과 다른 계열의 리뷰어에게 diff를 넘겨요. Codex는 Claude의 코드를, Claude는 OpenAI의 코드를 리뷰해요. 종료 코드 0이면 출시, 3이면 먼저 수정해야 해요. --brief는 어떤 도구에든 붙여 넣을 수 있는 브리프를 출력해요. 3.1.0의 새 기능이에요. 다른 모델로 리뷰하기를 참고하세요.

    reports/review-codex.md리뷰어 이름을 붙인 발견 사항과 판정.

  6. 06 닫기

    $ specweave complete 0001

    reports/verify.json이 없거나 ok가 아니면 거부해요. 그 없이 닫으려면 --reason이 필요하고, 사유는 인크리먼트와 함께 저장돼요.

    metadata.json완료됨, 또는 증거 없이 닫은 사유.

명령, 플래그, 파일 이름은 specweave 3.1.0 기준이에요. 인크리먼트, 작업, 리뷰어는 이 페이지 전체에서 쓰는 예시예요.

토큰이 떨어져도 끝이 아니에요

떠나는 도구에서 "hand off"라고 하고, 다음 도구에서 "pick up where I left off"라고 하세요. Codex가 Claude Code가 시작한 작업을 같은 머신이나 다른 머신에서 이어갈 수 있어요. 도구 사이에 복사하는 것은 없어요. specweave handoff가 스냅샷을 specweave-handoff와 wip/<branch>에 푸시하고 원장 이벤트를 추가해요.

  • handoff --all활성 인크리먼트 전체와 로컬 작업이 있는 모든 중첩 저장소의 색인 하나를 작성해요.
  • pickup --list대기 중인 핸드오프를 최신순으로 보여 주고 아무것도 바꾸지 않아요.
  • pickup <id 또는 제목>여러 개가 대기 중일 때 특정 핸드오프를 선택해요.
  • handoff --no-push핸드오프를 원격에 푸시하지 않고 이 머신에만 보관해요.
핸드오프와 이어받기 자세히 보기

떠나는 쪽: claude@cloud로 실행 중인 Claude Code

$ specweave handoff --reason "out of tokens"
Handed off 0001-resumable-checkout (released T-02, pushed your uncommitted edits).
To continue in any tool, machine or account, say "pick up" there (or run `specweave pickup`).
Details: .specweave/increments/0001-resumable-checkout/handoff.md

원격의 specweave-handoff와 wip/<branch>로 푸시된 스냅샷, 그리고 원장의 핸드오프 이벤트

도착하는 쪽: codex@laptop으로 실행 중인 Codex

$ specweave pickup
Picked up the handoff from claude@cloud (out of tokens): applied 7 uncommitted files.
SpecWeave pickup · you are codex@laptop
Increment 0001-resumable-checkout "Resumable checkout" (active) · tasks 1/2 done
Next: T-02 Restore the draft on return

이어받기 줄은 Codex로 실행한 두 번째 클론의 실제 출력이에요. 핸드오프 줄은 같은 실행에서 CLI가 출력한 정확한 메시지예요.

사용 한도, 닿기 전에 처리해요

specweave auto-handoff on는 Claude Code, Codex, Grok Build에 훅을 추가해요. 모든 훅이 로컬 체크포인트를 저장하고, 어떤 사용 구간이든 95%에 이르면 모드에 따라 동작이 정해져요. (Grok은 퍼센트를 알려 주지 않으므로 턴이 속도 제한에 걸릴 때 훅이 동작해요.)

SpecWithCode 사용량 패널: Codex 주간 10% 남음, Claude 세션 2% 남음, 주간 54% 남음, 주간 Fable 84% 남음, 각각 초기화 시각 표시
실제 캡처 · SpecWithCode 사용량 패널, 훅이 지켜보는 구간
  • suggest기본값
    임계값에 닿으면
    핸드오프 준비가 됐다고 한 번만 알려 주고 계속 작업해요.
    이럴 때 사용
    기본값. 전환 시점은 직접 정해요.
  • enforce
    임계값에 닿으면
    specweave handoff를 실행하고 세션을 멈춰요.
    이럴 때 사용
    작업 경계에서 깔끔하게 멈춰야 하는 무인 실행에 적합해요.
  • checkpoint
    임계값에 닿으면
    로컬 체크포인트만 저장하고 핸드오프는 하지 않아요.
    이럴 때 사용
    크레딧이나 프록시 덕분에 한도를 넘어서도 작업이 계속되는 요금제에 적합해요.
  • --at 90임계값을 옮겨요. 기본값은 95예요.
  • --wait-under 30가득 찬 모든 구간이 그 분 이내에 초기화되면 아무것도 하지 않아요. 기본값은 30이에요.
  • autocompact onClaude Code를 100만 토큰 근처가 아닌 40만 토큰에서 압축해서 후반 턴이 작게 유지돼요.

에이전트를 SpecWithCode에서 실행하나요? 제공업체 구독마다 머신 하나를 쓰세요. 각 머신은 제공업체별로 계정 하나에 계속 로그인해 두고, 용량이 더 필요하면 구독을 수동으로 바꾸는 대신 머신을 추가하세요.

자동 핸드오프 가이드

기본 스킬 일곱 개, 필요하면 네 개 더

스킬은 에이전트가 필요할 때 불러오는 짧은 지침이에요. 3.1.0부터는 선택 스킬이 프로젝트에 필요할 때 켜져요. specweave skills list에서 각각이 켜진 이유를 보고, enable 또는 disable로 바꿀 수 있어요.

모든 프로젝트에서

sw-increment
인크리먼트를 하나의 spec.md로 계획하고 중요한 결정을 먼저 물어봐요.
sw-grill-me
계획의 모든 결정이 정리될 때까지 라운드별로 인터뷰해요. planning.deepInterview를 deep으로 설정하면 모든 새 인크리먼트에서 실행돼요.
sw-do
인크리먼트를 작업 단위로 진행해요: 담당, 파일 안에서 구현, 테스트, 커밋, 증거와 함께 완료. 혼자서, 무인으로, 또는 병렬 레인으로 실행할 수 있어요.
sw-auto
모든 작업이 끝날 때까지 인크리먼트를 무인으로 실행한 뒤 검증하고 닫아요.
sw-review
새 컨텍스트 또는 다른 모델 계열의 적대적 리뷰. 모든 발견 사항에 파일과 줄 번호가 달려 있어요.
sw-done
인크리먼트를 닫아요: 작업 완료, verify 통과, 새 컨텍스트 리뷰, 그다음 complete.
sw-handoff
작업을 다른 도구, 계정, 머신으로 넘기고 그쪽에서 이어받아요.

프로젝트에 필요할 때

sw-glossary
프로젝트 공용 용어집 GLOSSARY.md을 만들어요. specweave glossary check --strict는 어긋나면 CI를 실패시켜요.
sw-sync
인크리먼트를 GitHub, Jira, Azure DevOps로 푸시해요. 프로젝트에 트래커가 있으면 켜져요.
sw-project
프로젝트 허브를 읽고 업데이트해요. .specweave/project/hub.json이 있으면 켜져요.
sw-jev
선택지가 정해진 결정을 Jev에게 넘겨요. jev.enabled가 설정되면 켜져요.
스킬 레퍼런스

직접 확인할 수 있는 기록

위의 모든 것은 저장소의 일반 파일이에요. 기록은 git 리뷰와 접근 제어로 보호되며, 이 파일들이 변조 방지 감사 시스템인 것은 아니에요.

  • spec.md

    완료의 의미

    계획할 때 작성하고 코드 전에 읽어요.

  • ledger.jsonl

    일어난 일

    담당, 증거가 있는 완료, 메모, 핸드오프.

  • reports/

    증명한 것

    작업 로그, verify.md, verify.json, 리뷰 보고서.

  • handoff.md

    멈춘 지점

    specweave handoff가 작성해요.

  • specweave note

    다음 에이전트를 위한 메모

    원장에 저장되고 pickup로 볼 수 있어요.

  • .specweave/memory/

    세션이 끝나도 남는 결정

    사실 하나당 파일 하나로 MEMORY.md에 색인되고 커밋되어서 모든 도구와 계정이 볼 수 있어요.

  • specweave dashboard

    모든 것을 한눈에 보는 보드

    로컬 전용이며 기본값은 127.0.0.1 포트 3456이에요. 읽는 데 모델 호출이 필요 없어요.

  • specweave report

    누가 무엇을 했는지 한 페이지로

    도구, 세션, 핸드오프, 증거를 reports/handoff-report.html에 HTML 타임라인으로 정리해요.

예시에서 대시보드가 읽는 내용

대시보드가 인크리먼트 0001-resumable-checkout에 대해 읽는 내용
인크리먼트0001-resumable-checkout 이어서 진행할 수 있는 체크아웃
상태진행 중
작업2개 중 1개 완료
다음 작업T-02 돌아왔을 때 초안 복원
기준AC-01 24시간 안에 돌아오면 장바구니와 배송 선택을 복원한다. AC-02 결제가 끝난 주문은 복원하지 않는다.
파일과 테스트src/restore.js, npm test
마지막 핸드오프claude@cloud, 토큰 소진. codex@laptop가 이어받음.

이 페이지 맨 위에 보이는 specweave pickup 실행과 같은 결과로 만들었어요. 내 프로젝트에서 specweave dashboard를 실행하면 내 것을 볼 수 있어요.

이미 쓰는 도구와 연결해요

모두 선택 사항이며, 설정하기 전까지는 꺼져 있어요.

  • 코드 탐색

    $ specweave lsp refs src/restore.js restoreDraft

    언어 서버가 제공하는 참조, 정의, 호버 타입, 심볼 덕분에 에이전트가 더는 grep을 돌리지 않아요. specweave lsp setup가 저장소의 언어에 맞는 서버를 골라요.

    LSP 가이드

  • Jev

    $ specweave jev route "<prompt>"

    약 250ms 안에 선택지가 정해진 결정을 내려요. 어떤 스킬이나 모델 등급을 쓸지, 셸 명령을 실행해도 안전한지, 가져온 텍스트를 한 번 더 봐야 하는지 등이에요. specweave jev setup로 사용 설정하세요.

    Jev 소개

  • 프로젝트 허브

    $ specweave project brief

    모든 도구가 읽는 공유 목표, 컨텍스트, 산출물, 루틴을 .specweave/project/hub.json에 담아요. --harness codex는 다른 도구용 브리프를 내보내요.

    이식 가능한 프로젝트 가이드

  • 기존 저장소

    $ specweave get owner/repo

    저장소를 워크스페이스에 클론하고 등록하거나, --all로 조직의 모든 저장소를 한 번에 등록해요. --dry-run은 이미 있는 체크아웃을 가져오는 과정을 미리 보여 줘요.

    워크스페이스 도입 가이드

  • 이슈 트래커

    $ specweave sync push

    선택 사항이에요. 팀이 GitHub Issues, Jira, Azure DevOps에서 계획한다면 인크리먼트를 그쪽으로 푸시하세요.

    트래커 동기화 가이드
모든 연동

같은 인크리먼트를 데스크톱 앱에서 실행하세요

SpecWithCode 워커 스레드는 브랜치 하나에서 작업하고 풀 리퀘스트 하나를 열어요. 인크리먼트의 형태와 정확히 같아요. 체크리스트는 인크리먼트의 작업 목록이고, 원장 기록은 이 페이지의 명령이에요. 스레드끼리는 서로의 파일을 수정하지 않고 원장에 메모를 남겨요.

SpecWithCode 보기
SpecWithCode워커 스레드
결과를 보고하는 SpecWithCode 워커 스레드: 실행한 명령과 출력, 차단 요소 없음, 변경된 파일 두 개
워커 스레드가 결과, 증거, 변경한 파일을 보고해요. SpecWithCode 1.0.21, 2026년 10월 15일.

완료의 의미를 적어 두면 도구는 자유롭게 바꿀 수 있어요

빠른 시작3.1의 변경 사항