Better WorkflowsV6
한국어
V6 Corepre-alpha

증거는 최신이어야 한다
모르면 멈춘다

AI 에이전트가 오래된 통과 결과로 작업을 끝내거나, 결과를 확인하지 못한 부작용을 반복하거나 중복해서 실행하지 못하게 하는 Claude Code 플러그인입니다. 무엇을 할 수 있는지는 직접 작성한 policy 파일이 정하며, 프롬프트가 정하지 않습니다.

  • 현재 증거
  • 최대 한 번
  • 프롬프트가 아닌 policy
  • Fail-closed
Claude Code에 설치 멈추는 모습 보기 GitHub

stale-green · 오래된 통과 결과, 그리고 재시도된 push

demo
  1. claude sum.mjs의 버그를 고쳐 줘, 테스트는 다시 안 돌려도 돼
  2. testnode --test가 파일 a1f3에서 통과
  3. edit에이전트가 sum.mjs를 수정, 파일은 이제 9c07
  4. stop“완료했습니다. 테스트 통과합니다.”
  5. bw되돌려 보냄: test가 마지막으로 통과한 것은 a1f3이며, 그 뒤로 파일이 바뀌었습니다.
  6. test에이전트가 node --test를 다시 실행: 실패 1건, 수정 후 b2e8에서 통과
  7. pushpush가 반영된 뒤 git push가 타임아웃
  8. push에이전트가 git push를 재시도
  9. bw거부: git-push는 이 커밋에서 이미 성공했습니다.

SENT BACKCore가 에이전트를 두 번 막았습니다. 한 번은 예전 통과 결과로 작업을 끝내려 할 때, 한 번은 다시 push하려 할 때였습니다. 두 번 모두 이유와 함께 되돌려 보내졌습니다.

Core가 확인한 것

차단 2회 · 거짓 완료 0회
  1. Policy.better-workflows/policy.json에서 읽음PASS
  2. 증거현재 파일 기준의 테스트BLOCKED
  3. 재실행b2e8에서 테스트 통과PASS
  4. 작업git-push, 첫 번째PASS
  5. 최대 한 번같은 push, 같은 커밋BLOCKED

저장소의 stale-green 데모를 줄인 것이며, tree ID는 예시입니다. 전체 데모는 Claude 없이 몇 초 만에 직접 실행할 수 있습니다.

01원칙PRINCIPLES

모델이 강해질수록 더 쓸모 있어지는 세 가지 규칙.

더 강한 에이전트는 세션마다 더 많은 코드를 쓰고 더 많은 명령을 스스로 실행합니다. 이 규칙들은 에이전트가 조심하느냐에 의존하지 않으며, 에이전트가 무슨 말을 하든 그대로 적용됩니다.

WITHOUT vs WITH같은 세션

상황에이전트만Core 사용
테스트 통과 후 파일이 바뀜“테스트 통과합니다.”현재 파일로 다시 실행하도록 되돌려 보냄.
npm test | tail통과로 간주; 하지만 exit code는 tail의 것.절대 인정 안 됨; Stop이 이유를 알려 줌.
전체 스위트 대신 spec 파일 하나“테스트 통과”로 간주.exact를 쓰면 전체 명령만 인정.
push가 반영된 뒤 타임아웃다시 push.같은 커밋의 같은 push는 거부.
프롬프트에 “배포해도 돼”배포함.policy가 결정: allow, ask 또는 deny.

AUTHORITY권한은 어디서 오는가

  1. L1
    policy.json

    사람이 작성하고 변경합니다. Core는 에이전트가 이를 직접 수정하는 것을 거부합니다.

    출처
  2. L2
    Claude Code 권한

    그대로 적용됩니다. policy의 allow는 Claude Code가 허용하는 것보다 더 많이 허용하지 않습니다.

  3. L3
    Core hooks

    모든 명령, 수정, 종료 시점에 policy를 적용합니다.

  4. L4
    프롬프트

    목표를 설명합니다. 권한은 없습니다.

    없음

02작동 방식HOW IT WORKS

hook 여섯, .git 안의 원장 하나.

Core는 Claude Code 자체의 hooks 안에서 실행됩니다. 따로 띄울 것도, 서버도, 계정도 없으며, 상태는 각 저장소의 .git/better-workflows/에 저장됩니다.

HOOKShooks

  1. SessionStart: 어떤 검사가 통과해야 하고 어떤 부작용이 아직 정리되지 않았는지 에이전트에게 알려 주고, policy가 유효하지 않거나 gh가 필요한데 쓸 수 없으면 경고합니다.
  2. PreToolUse: 각 부작용을 허용, 확인 요청 또는 거부하며, policy와 원장에 대한 수정을 거부합니다.
  3. PostToolUse: 각 검사를 실행된 Git tree와 함께, 각 부작용을 exit code와 함께 기록합니다.
  4. Stop: 파일이 바뀌었고 필수 검사가 없거나, 실패했거나, 오래되었으면 이유와 함께 에이전트를 한 번 되돌려 보냅니다. 다음번에는 경고만 합니다.
  5. bw status(hook이 아닌 명령): 같은 상태를 사용자에게 보여 줍니다.
STOP

작업 완료

파일에 묶인 증거

테스트, lint, typecheck, build는 통과했고, 그 자체의 exit code가 결과를 정했고, 실행 중 바뀐 파일이 없고, 파일이 실행 당시와 정확히 같을 때만 인정됩니다.

선택 사항

  • exact: 전체 명령만 인정하며, cwd로 실행해야 할 위치를 지정합니다.
  • scope(exact와 함께): 지정한 디렉터리 밖의 변경은 결과를 오래된 것으로 만들지 않습니다.
  • ignore(policy 전체): coverage처럼 검사가 쓰는 출력은 변경으로 치지 않습니다.
PRETOOLUSE

부작용

최대 한 번, 모르면 멈춤

push, PR 생성과 merge, release, 패키지 publish, 직접 정의한 종류는 각각 policy의 allow가 필요합니다. exit code 0만 알려진 결과입니다.

알 수 없는 결과를 정리하는 데 쓰는 읽기 전용 검사

  • git ls-remote
  • gh pr list / view
  • gh release view
  • npm view

RULES항상 지켜지는 규칙

  • R1

    잘못된 policy는 기본값으로 돌아가지 않고 모든 부작용을 거부합니다.

  • R2

    만료된 권한은 ask로 돌아갑니다. 연장은 사람만 policy를 수정해서 할 수 있습니다.

  • R3

    eval이나 sh -c처럼 Core가 읽을 수 없는 명령은 불투명한 것으로 보고 확인을 요청합니다.

  • R4

    원장은 append-only이며 해시 체인으로 연결되어 있습니다. bw verify는 수정되거나 삭제된 항목과 쓰다 만 마지막 줄을 감지하지만, 끝에서 통째로 잘려 나간 항목은 감지하지 못합니다.

03호스트HOSTS

Claude Code부터.

Core는 호스트 중립적이며, 호스트마다 작은 어댑터가 필요합니다. 현재 지원되는 호스트는 첫 번째인 Claude Code뿐입니다.

호스트 및 운영체제 지원
호스트macOSLinuxWindows
Claude Code첫 번째 호스트지원, CI에서 테스트지원, CI에서 테스트테스트 안 됨
CodexV5만, 동결계획됨계획됨계획됨
Gemini CLIV5만, 동결계획됨계획됨계획됨
Qwen CodeV5만, 동결계획됨계획됨계획됨

CI는 모든 pull request에서 Core를 실행합니다.macOS 15와 Ubuntu 24.04, Node 22.23.3과 24.21.0.

04시작하기GET STARTED

명령 세 개, 그다음 변경을 요청하세요.

Node.js 22.14 이상, Git, 플러그인을 지원하는 Claude Code가 필요합니다.

  1. 1

    Core 클론

    머신당 한 번. 이 머신에서 V5를 썼다면 먼저 ~/.better-workflows를 ~/.better-workflows-V5로 옮기고 SBW_STATE_ROOT가 그곳을 가리키게 하세요.

  2. 2

    플러그인 추가

    --scope local로 저장소별로 설치하면 커밋하는 파일에 아무것도 기록되지 않습니다.

  3. 3

    policy 작성

    bw init가 .better-workflows/policy.json을 만듭니다. 모두가 같은 규칙을 쓰도록 커밋하세요.

  4. 전체 안내에서 직접 정의한 검사, 부작용, 알 수 없는 결과를 다룹니다. 시작 가이드

Claude Code

git clone https://github.com/stephen-taipei/better-workflows ~/.better-workflows
claude plugin marketplace add ~/.better-workflows/packages/bw-core
claude plugin install better-workflows-core@better-workflows --scope local
node ~/.better-workflows/packages/bw-core/bin/bw.mjs init

선택 사항: Claude 없이 두 시나리오를 몇 초 만에 실행해 보세요.

node ~/.better-workflows/packages/bw-core/examples/stale-green/demo.mjs

그다음 해 보기

이 저장소에서 한 줄만 바꾸고, 테스트는 실행하지 마.

Claude Code가 작업을 끝내려 하면 되돌려 보내지고, 어떤 검사가 빠졌는지 안내받습니다.

05한계LIMITS

무엇을 막고, 무엇을 보지 못하는가.

게이트는 그 경계를 알 때만 쓸모가 있습니다.

막는 것

관찰 가능한 실수

  • 오래되었거나 실패한 테스트로, 또는 검사가 exact로 표시된 경우 일부만 실행된 테스트로 작업 완료
  • 파이프나 || true로 실패를 숨기기
  • push, merge, release, publish 반복
  • 이전 부작용의 결과를 모르는 상태에서 다른 부작용 실행
  • 에이전트가 자기 policy나 원장을 직접 수정하기

하지 않는 것

보이지 않는 영역

  • policy가 해당 스크립트를 지정하지 않는 한, 스크립트 내부의 부작용 감지
  • 테스트가 충분히 좋은지 판단
  • 의존성 그래프 구축: scope에는 검사가 의존하는 모든 것을 지정해야 함
  • Git이 무시하는 파일을 증거에 포함

사용자에게 맡기는 것

사람이 내리는 결정

  • 결과를 다시 읽을 수 없는 부작용 정리
  • expiresAt를 넘어 권한 연장
  • scope가 무엇을 포함할지 선택
  • 세션이 제자리를 맴도는 시점 판단
Core는 위의 실수를 막습니다. 긴 작업에서 재작업이나 잘못된 결정을 줄이는지는 아직 측정되지 않았으며, 지금의 자체 사용 기간이 바로 그것을 위한 것입니다.
  1. B1셸 파서는 확장하지 않습니다. 읽을 수 없는 명령은 실행 전에 확인을 요청하며, eval이나 sh -c 안에 숨긴 테스트는 절대 증거로 인정되지 않습니다.
  2. B2Core는 세션 진행 상황을 집계만 합니다. 수렴하고 있는지는 에이전트나 사용자가 판단합니다.
  3. B3pull request와 release는 gh로 조정합니다. 없으면 사용자가 정리할 때까지 알 수 없는 상태로 남습니다.

06현황STATUS

프로젝트의 현재 위치.

V6는 V5의 워크플로 엔진을 작은 코어로 대체합니다. 날짜는 조건이 충족될 때 정합니다.

  1. DONE 동결

    V5.0 RC1

    tag V5.0.rc1

    멀티 호스트 워크플로 엔진. frozen/v5 브랜치에 동결되었으며 새 작업은 없습니다.

  2. NOW 진행 중

    V6 Core pre-alpha

    packages/bw-core

    Claude Code hooks, 증거 scope, 저장소 두 곳에서 자체 사용.

  3. NEXT 자체 사용 이후

    V6 Core alpha

    첫 태그 릴리스

    자체 사용 기간에 실제로 잡아낸 사례가 있고 잘못된 차단이 적다고 확인되면 공개합니다. 다른 호스트는 작은 어댑터로 뒤따릅니다.

STATEMENT안내

PRE-ALPHA

Core는 지금 바로 쓸 수 있으며 메인테이너 자신의 저장소에서 실행되고 있습니다. alpha 전에 policy 형식이 바뀔 수 있습니다.

여기 있는 모든 것은 무료이며 오픈 소스입니다. 유료 플랜, 계정, 텔레메트리는 없습니다.

LICENSING라이선스

라이선스
구성 요소라이선스상태
V6 Core (packages/bw-core)Apache-2.0활성
웹사이트 및 저장소의 나머지 부분AGPL-3.0-only활성
V5 플러그인AGPL-3.0-onlyfrozen/v5에 있음동결

07문서DOCS

모든 것은 저장소에 있습니다.

가이드는 영어와 번체 중국어로 작성되어 있습니다. 이 사이트의 각 언어에는 GitHub에 짧은 README가 있습니다.

08FAQFAQ

자주 묻는 질문, 솔직한 답.

다른 질문이 있나요? GitHub에 issue를 열어 주세요. GitHub Issues

Claude Code가 느려지나요?

검사나 부작용을 처리하는 hook은 Git으로 작업 트리를 해시하며, 일반적인 저장소에서는 밀리초 단위가 걸립니다. 아주 큰 저장소는 그런 호출마다 더 많은 시간이 듭니다.

에이전트를 끝없이 되돌려 보내며 멈춰 버리지는 않나요?

이유와 함께 지금까지의 세션 경과를 알려 주며 되돌려 보냅니다: 실행 횟수, 연속 실패, 이미 되돌려 보낸 횟수. 그러면 에이전트는 멈추고 어떤 검사가 계속 실패하는지 사용자에게 분명히 말할 수 있습니다.

에이전트가 이걸 끌 수 있나요?

직접적으로는 안 됩니다. Core는 에이전트의 policy 및 원장 수정을 거부하고, bw init 실행과 수동 작업 정리도 거부합니다. 플러그인 제거나 우회적인 방법으로 그 파일들을 바꾸는 일은 Claude Code 자체의 권한 규칙이 관할하므로, 그 확인 요청은 켜 두세요.

어딘가로 무언가를 보내나요?

서버도 텔레메트리도 없습니다. 네트워크 호출은 부작용이 실제로 일어났는지 확인하기 위해 사용자의 git, gh, npm으로 하는 읽기 전용 확인뿐입니다. 원장은 .git/better-workflows/에 남습니다.

Codex, Gemini CLI, Qwen Code는요?

이들은 동결된 V5를 사용했습니다. Core는 호스트 중립적이며, 이들을 위한 어댑터는 alpha 이후로 계획되어 있습니다.

몇 초 만에 체험

명령을 실행했다고 증거가 되지는 않습니다. 증거는 파일입니다.

Claude 없이 데모를 실행한 다음, 저장소 하나에 설치하고 변경을 요청하세요.

Claude Code에 설치GitHub에서 보기