Better WorkflowsV6
Tiếng Việt
V6 Corepre-alpha

Chứng cứ phải mới.
Chưa rõ thì dừng.

Một plugin cho Claude Code giúp AI agent không kết thúc dựa trên một kết quả test xanh đã cũ, và không lặp lại hay chồng thêm các tác động phụ mà nó chưa từng thấy kết quả. Những gì nó được phép làm đến từ tệp policy do bạn viết, không bao giờ từ prompt.

  • Bằng chứng hiện tại
  • Nhiều nhất một lần
  • Policy, không phải prompt
  • Lỗi thì đóng
Cài cho Claude Code Xem nó chặn GitHub

stale-green · một kết quả xanh đã cũ, rồi một lần push thử lại

demo
  1. claude sửa lỗi trong sum.mjs, không cần chạy lại test
  2. testnode --test đạt trên các tệp a1f3
  3. editagent sửa sum.mjs, các tệp giờ là 9c07
  4. stop“Xong. Test đều đạt.”
  5. bwTrả lại: test đạt lần cuối trên a1f3; các tệp đã thay đổi từ đó.
  6. testagent chạy lại node --test: 1 lỗi, sửa xong, đạt trên b2e8
  7. pushgit push hết thời gian chờ sau khi push đã thành công
  8. pushagent thử lại git push
  9. bwTừ chối: git-push đã thành công ở commit này.

SENT BACKCore đã chặn agent hai lần: một lần khi nó định kết thúc dựa trên một lần pass cũ, một lần khi nó định push lại. Cả hai lần nó đều bị trả lại kèm lý do.

Core đã kiểm tra gì

2 LẦN CHẶN · 0 LẦN XONG GIẢ
  1. Policytừ .better-workflows/policy.jsonPASS
  2. Bằng chứngtest trên các tệp như hiện tạiBLOCKED
  3. Chạy lạitest đạt trên b2e8PASS
  4. Hành độnggit-push, lần đầuPASS
  5. Nhiều nhất một lầncùng push, cùng commitBLOCKED

Rút gọn từ demo stale-green trong repository; các id tree chỉ mang tính minh họa. Tự chạy bản demo đầy đủ trong vài giây, không cần Claude.

01Nguyên tắcPRINCIPLES

Ba quy tắc càng hữu ích khi mô hình càng mạnh.

Agent càng mạnh thì mỗi phiên viết càng nhiều mã và tự chạy càng nhiều lệnh. Các quy tắc này không dựa vào việc agent cẩn thận; chúng vẫn đúng dù nó nói gì.

WITHOUT vs WITHcùng một phiên

Tình huốngChỉ có agentCó Core
Test đạt, rồi một tệp thay đổi“Test đều đạt.”Bị trả lại để chạy lại trên các tệp hiện tại.
npm test | tailTính là xanh; exit code là của tail.Không bao giờ được tính; Stop nêu lý do.
Một tệp spec thay cho cả bộ testTính là “test đều đạt.”Với exact, chỉ toàn bộ lệnh mới được tính.
Push hết thời gian chờ sau khi đã thành côngPush lần nữa.Cùng push ở cùng commit bị từ chối.
Prompt nói “bạn có thể publish”Publish luôn.Policy quyết định: allow, ask hoặc deny.

AUTHORITYthẩm quyền đến từ đâu

  1. L1
    policy.json

    Do một người viết và thay đổi. Core từ chối các chỉnh sửa trực tiếp của agent đối với nó.

    NGUỒN
  2. L2
    Quyền của Claude Code

    Vẫn áp dụng. allow trong policy không bao giờ cấp nhiều hơn những gì Claude Code cho phép.

  3. L3
    Hook của Core

    Thực thi policy trên mọi lệnh, mọi chỉnh sửa và mỗi lần dừng.

  4. L4
    Prompt

    Mô tả mục tiêu. Không mang thẩm quyền nào.

    KHÔNG

02Cách hoạt độngHOW IT WORKS

Sáu hook, một sổ cái trong .git.

Core chạy bên trong chính các hook của Claude Code. Không cần khởi động gì, không server, không tài khoản; trạng thái nằm trong .git/better-workflows/ của từng repository.

HOOKScác hook

  1. SessionStart: cho agent biết những kiểm tra nào phải đạt và những tác động phụ nào chưa được xử lý, đồng thời cảnh báo nếu policy không hợp lệ hoặc cần gh nhưng không dùng được.
  2. PreToolUse: cho phép, hỏi hoặc từ chối từng tác động phụ, và chặn việc sửa policy cũng như sổ cái.
  3. PostToolUse: ghi lại mỗi lần kiểm tra cùng Git tree mà nó chạy trên đó, và mỗi tác động phụ cùng exit code của nó.
  4. Stop: nếu có tệp thay đổi và một kiểm tra bắt buộc còn thiếu, thất bại hoặc đã cũ, trả agent lại một lần kèm lý do; lần sau chỉ cảnh báo.
  5. bw status (một lệnh, không phải hook): hiển thị cùng trạng thái đó cho bạn.
STOP

Kết thúc

bằng chứng gắn với tệp

Một lần test, lint, typecheck hoặc build chỉ được tính nếu nó đạt, exit code của chính nó quyết định kết quả, không tệp nào thay đổi trong lúc chạy, và các tệp vẫn y như lúc nó chạy.

Tùy chọn

  • exact: chỉ toàn bộ lệnh mới được tính, và cwd xác định nơi lệnh phải chạy.
  • scope (cùng với exact): thay đổi bên ngoài các thư mục đã chỉ định không làm kết quả bị cũ.
  • ignore (toàn bộ policy): đầu ra do kiểm tra tự ghi, như coverage, không bị tính là thay đổi.
PRETOOLUSE

Tác động phụ

nhiều nhất một lần, chưa rõ thì dừng

Push, tạo và merge PR, release, publish package và các loại tùy chỉnh của bạn đều cần allow từ policy. Chỉ exit code 0 mới là kết quả đã biết.

Các kiểm tra chỉ đọc dùng để xác minh kết quả chưa rõ

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

RULEScác quy tắc luôn đúng

  • R1

    Một policy không hợp lệ sẽ từ chối mọi tác động phụ thay vì quay về mặc định.

  • R2

    Một quyền đã hết hạn sẽ quay về ask. Chỉ một người mới gia hạn được, bằng cách sửa policy.

  • R3

    Các lệnh Core không đọc được, như eval hay sh -c, được coi là không minh bạch và sẽ được hỏi.

  • R4

    Sổ cái chỉ ghi thêm và được nối chuỗi bằng hash; bw verify phát hiện các mục bị sửa hoặc bị xóa và một dòng cuối ghi dở, nhưng không phát hiện các mục bị cắt nguyên vẹn khỏi phần cuối.

03HostHOSTS

Claude Code trước tiên.

Core không phụ thuộc host; mỗi host cần một adapter nhỏ. Claude Code là host đầu tiên và là host duy nhất được hỗ trợ hiện nay.

Hỗ trợ host và hệ điều hành
HostmacOSLinuxWindows
Claude CodeHost đầu tiênHỗ trợ, kiểm thử trong CIHỗ trợ, kiểm thử trong CIChưa kiểm thử
CodexChỉ V5, đã đóng băngDự kiếnDự kiếnDự kiến
Gemini CLIChỉ V5, đã đóng băngDự kiếnDự kiếnDự kiến
Qwen CodeChỉ V5, đã đóng băngDự kiếnDự kiếnDự kiến

CI chạy Core trên mọi pull request.macOS 15 và Ubuntu 24.04, Node 22.23.3 và 24.21.0.

04Bắt đầuGET STARTED

Ba lệnh, rồi yêu cầu một thay đổi.

Cần Node.js 22.14 trở lên, Git, và Claude Code có hỗ trợ plugin.

  1. 1

    Clone Core

    Một lần cho mỗi máy. Nếu từng chạy V5 trên máy này, trước hết hãy chuyển ~/.better-workflows thành ~/.better-workflows-V5 và trỏ SBW_STATE_ROOT tới đó.

  2. 2

    Thêm plugin

    Cài cho từng repository với --scope local, để không có gì bị ghi vào các tệp bạn commit.

  3. 3

    Viết policy

    bw init tạo .better-workflows/policy.json. Hãy commit nó để mọi người dùng chung một bộ quy tắc.

  4. Hướng dẫn đầy đủ trình bày các kiểm tra của riêng bạn, tác động phụ và kết quả chưa rõ. Hướng dẫn bắt đầu

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

Tùy chọn: chạy cả hai tình huống không cần Claude, trong vài giây.

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

Rồi thử ngay

Sửa một dòng trong repository này, và đừng chạy test.

Khi Claude Code cố kết thúc, nó sẽ bị trả lại và được cho biết kiểm tra nào còn thiếu.

05Giới hạnLIMITS

Nó chặn được gì, và không thấy được gì.

Một cổng kiểm soát chỉ hữu ích khi bạn biết ranh giới của nó.

Chặn được

Lỗi quan sát được

  • Kết thúc dựa trên một lần test đã cũ hoặc thất bại, hoặc chỉ chạy một phần khi kiểm tra được đánh dấu exact
  • Một pipe hoặc || true che giấu lỗi
  • Push, merge, release hoặc publish lặp lại
  • Tác động phụ khi một tác động trước đó chưa rõ kết quả
  • Agent sửa trực tiếp policy hoặc sổ cái của chính nó

Không làm được

Nằm ngoài tầm nhìn

  • Thấy tác động phụ bên trong một script, trừ khi policy nêu tên script đó
  • Đánh giá test của bạn có đủ tốt hay không
  • Xây dựng đồ thị phụ thuộc: một scope phải liệt kê mọi thứ mà kiểm tra phụ thuộc vào
  • Tính các tệp bị Git bỏ qua vào bằng chứng

Để bạn quyết

Quyết định do con người đưa ra

  • Xử lý một tác động phụ mà kết quả không thể đọc lại
  • Gia hạn một quyền quá expiresAt
  • Chọn phạm vi mà một scope bao phủ
  • Quyết định khi nào một phiên đang đi vòng quanh
Core chặn được các lỗi nêu trên. Việc nó có giảm làm lại hoặc quyết định sai trong các tác vụ dài hay không thì chưa được đo; giai đoạn tự dùng hiện tại là để làm việc đó.
  1. B1Bộ phân tích shell không mở rộng thêm: lệnh nó không đọc được sẽ được hỏi trước khi chạy, và một test giấu trong eval hoặc sh -c không bao giờ được tính là bằng chứng.
  2. B2Core chỉ đếm diễn tiến của một phiên. Phiên có đang hội tụ hay không là do agent hoặc bạn đánh giá.
  3. B3Pull request và release được đối soát bằng gh; nếu không có nó, chúng sẽ ở trạng thái chưa rõ cho đến khi bạn xử lý.

06Trạng tháiSTATUS

Dự án đang ở đâu.

V6 thay engine workflow của V5 bằng một core nhỏ. Ngày tháng chỉ có khi đạt được điều kiện.

  1. DONE Đã đóng băng

    V5.0 RC1

    tag V5.0.rc1

    Engine workflow đa host. Đóng băng trên nhánh frozen/v5; không phát triển thêm.

  2. NOW Đang làm

    V6 Core pre-alpha

    packages/bw-core

    Hook của Claude Code, scope bằng chứng, tự dùng trên hai repository.

  3. NEXT Sau giai đoạn tự dùng

    V6 Core alpha

    bản phát hành có tag đầu tiên

    Phát hành khi giai đoạn tự dùng cho thấy chặn được lỗi thật và ít chặn nhầm. Thêm host sẽ theo sau dưới dạng adapter nhỏ.

STATEMENTtuyên bố

PRE-ALPHA

Core dùng được ngay hôm nay và đang chạy trên chính các repository của người bảo trì. Định dạng policy vẫn có thể thay đổi trước alpha.

Mọi thứ ở đây đều miễn phí và mã nguồn mở. Không có gói trả phí, tài khoản hay telemetry.

LICENSINGgiấy phép

giấy phép
PhầnGiấy phépTrạng thái
V6 Core (packages/bw-core)Apache-2.0đang hoạt động
Website và phần còn lại của repositoryAGPL-3.0-onlyđang hoạt động
Plugin V5AGPL-3.0-onlytrên frozen/v5đã đóng băng

07Tài liệuDOCS

Mọi thứ đều nằm trong repository.

Các hướng dẫn được viết bằng tiếng Anh và tiếng Trung phồn thể. Mỗi ngôn ngữ trên trang này có một README ngắn trên GitHub.

08Câu hỏi thường gặpFAQ

Câu hỏi thường gặp, trả lời thẳng.

Còn điều gì khác? Hãy mở một issue trên GitHub. GitHub Issues

Nó có làm Claude Code chậm đi không?

Các hook xử lý một kiểm tra hoặc một tác động phụ sẽ băm cây làm việc bằng Git, mất vài mili giây trong một repository bình thường. Repository rất lớn sẽ tốn thêm thời gian ở mỗi lần gọi như vậy.

Nó có bị kẹt, trả agent lại mãi không?

Nó trả agent lại kèm lý do và diễn tiến của phiên cho đến lúc đó: số lần chạy, số lần thất bại liên tiếp, số lần đã bị trả lại. Khi đó agent có thể dừng và nói rõ với bạn kiểm tra nào cứ thất bại.

Agent có tắt nó được không?

Không trực tiếp. Core từ chối các chỉnh sửa của agent đối với policy và sổ cái, đồng thời từ chối bw init và việc xử lý thủ công một hành động. Việc gỡ plugin, hoặc thay đổi các tệp đó bằng cách vòng vo, do chính các quy tắc quyền của Claude Code quản lý, vì vậy hãy giữ các lời nhắc xác nhận đó luôn bật.

Nó có gửi dữ liệu đi đâu không?

Không có server và không có telemetry. Các lệnh gọi mạng duy nhất là những kiểm tra chỉ đọc bằng git, gh và npm của chính bạn, để xác nhận một tác động phụ đã xảy ra hay chưa. Sổ cái nằm trong .git/better-workflows/.

Còn Codex, Gemini CLI hay Qwen Code thì sao?

Chúng đã chạy V5, vốn đã đóng băng. Core không phụ thuộc host, và adapter cho chúng được dự kiến sau alpha.

Thử trong vài giây

Chạy một lệnh không phải là bằng chứng. Các tệp mới là.

Chạy demo không cần Claude, rồi cài lên một repository và yêu cầu một thay đổi.

Cài cho Claude CodeXem trên GitHub