AI Devkit Loop: từ fixkit tới plugin tái dùng được

TL;DR

• Một AI devkit là một harness theo vai trò (role harness): skills + agents + hooks đóng gói cho một việc. Một vòng lặp devkit là harness đó nhân một lớp vòng lặp: một lịch, một file lưu trạng thái (state file), và một điều kiện dừng (stop condition) kiểm chứng được. Harness nhân lớp vòng lặp. Sản phẩm đó là cả loạt bài gói trong một hình dạng.
• fixkit là ví dụ đã chạy, và nó có thật: trong lần chạy H1 một lỗi đi từ verified tới closed ở mức FULL qua một web-harness Playwright trên site trực tiếp, trình kiểm tra sổ trạng thái (ledger) đơn định chạm exit 0, và bất biến từ chối (refusal invariant) giữ vững (không sửa src/). Lịch + các đầu nối PR/ticket quanh nó là cơ chế, chưa chạy, và được ghi nhãn rõ.
• Cùng một hình dạng người tạo (maker), người kiểm (checker), điều kiện dừng tái dựng cho mobile, web, và PM dưới dạng bản phác thảo (design sketch); PM khó nhất: điều kiện dừng đặt trên tài liệu, không phải test. Đóng gói harness đã chứng minh thành một Claude Code plugin để đồng đội cài trong một bước.

📊 Bằng chứng kết quả (Beat 2, từ lần chạy H1 thật, đã có sẵn trên đĩa, không cần chạy mới): BUG-003 verified -> closed, capability_tier ASSIST -> FULL, method: computed-style, verified_by: ui-bug-agent (web-harness/playwright); computed-style overflow-x:auto tại #takeaway-snippet pre trên /blog/learn-claude-code-with-ai-mentor/ (cuộn được, không cắt ở 375px); viewport xác nhận chéo failingWidths:[]; trình kiểm tra engine exit 0; BUG-001 escalated, git diff -- src/ rỗng. Nguồn: ../shipwithai.io/.fixkit/H1-RUN-SUMMARY.md + BUG-003-codeblock-overflow.md.

Bạn đã có mọi khối từ Phần 2 tới Phần 7: năm khối và xương sống (spine), một điều kiện dừng kiểm chứng được, file lưu trạng thái tried/passed/open/blocked, các làn worktree với phân tách người tạo/người kiểm, một nhịp đập, và một bản cải tạo thật. Chúng vẫn là một danh sách linh kiện, chưa phải một sản phẩm đồng đội cài được. Bài này ghép chúng thành một hình dạng duy nhất và đóng gói nó. Một AI devkit chỉ là một harness đóng gói cho một vai trò, với một nhịp đập (heartbeat) bọc quanh:

vòng lặp devkit = harness theo vai trò (skills + agents + hooks)
                x lớp vòng lặp (lịch + file lưu trạng thái + điều kiện dừng kiểm chứng được)

Bạn sẽ đi qua fixkit theo hình dạng đó dựa trên lần chạy H1 thật, đọc đường ranh trung thực giữa cái đã chạy và cái chỉ là cơ chế, đặt ba vòng lặp thật trên bậc thang áp dụng, phác cùng hình dạng đó cho mobile/web/PM, và đóng gói harness thành một plugin. Yêu cầu trước: bạn đọc được exit code của một chốt chặn đơn định và cài được một Claude Code plugin (bài này không dạy lại cái nào). Đây là khung mà cả loạt bài chạy trên đó:

A loop is a recursive goal: you define a purpose and a verifiable stop condition, and the system iterates agents against it until the condition holds — without you prompting each turn.

Nói cách khác, một vòng lặp là một mục tiêu đệ quy: bạn định nghĩa một mục đích và một điều kiện dừng kiểm chứng được, rồi để hệ thống lặp các agent cho tới khi điều kiện đó thành hiện thực, mà không cần bạn prompt ở từng lượt.

AI devkit loop là gì?

Một AI devkit là một harness theo vai trò: skills + agents + hooks đóng gói cho một việc, như sửa lỗi. Một vòng lặp devkit là harness đó nhân một lớp vòng lặp: một lịch đánh thức nó, một file lưu trạng thái nhớ giữa các lần chạy, và một điều kiện dừng mà một mô hình khác kiểm được. Harness là cái gì; lớp vòng lặp là cái giữ-cho-chạy-mà-không-cần-bạn.

harness theo vai trò có ba phần. skills mang ý định dự án. agents mang các vai trò làm việc (cẩm nang agent chạy dài của Anthropic gọi đây là kỷ luật người tạo/người kiểm): một người tạo, một người kiểm tách biệt, một vai trò leo thang (escalation). hooks mang các rào chắn theo sự kiện. Giải phẫu đó là harness 5 lớp, và bài này ghép nó lại chứ không dẫn lại từ đầu.

Lớp vòng lặp cũng có ba phần. Một lịch hay nhịp đập tự đánh thức harness. Một file lưu trạng thái (tried/passed/open/blocked của Phần 4) nhớ qua các lần chạy, ngoài context window. Một điều kiện dừng kiểm chứng được (Phần 3) để một mô hình khác quyết là xong.

Đây là điểm phân biệt quan trọng. Một devkit (chỉ harness) là cái hầu hết các bài “dựng AI agent” giao. Một vòng lặp devkit thêm ba thứ giúp nó chạy không người trông và dừng trung thực. đoạn này là bước ghép: mọi thứ từ Phần 2 tới Phần 7 gọi tên một lần và ánh xạ vào hai nửa.

Điểm mấu chốt: Một devkit là một harness đóng gói cho một vai trò. Một vòng lặp devkit là harness đó cộng một nhịp đập, một bộ nhớ, và một định nghĩa hoàn thành mà một mô hình khác kiểm được. Cái đầu là một bản dựng (setup); cái sau là một hệ thống.

     HARNESS THEO VAI TRÒ                      LỚP VÒNG LẶP
  +--------------------------+        +----------------------------+
  |  skills (ý định)         |        |  lịch (nhịp đập)           |
  |  agents (người tạo /     |   x    |  file lưu trạng thái (nhớ) |  ->  vòng lặp devkit
  |   người kiểm / leo thang)|        |  điều kiện dừng (xong)     |
  |  hooks (rào chắn)        |        |                            |
  +--------------------------+        +----------------------------+

Đi qua fixkit: từ tiếp nhận bug tới bản vá đã kiểm chứng

Trong lần chạy H1 của fixkit (8/6/2026), một lỗi đi từ verified tới closed ở mức FULL. Một người tạo soạn bản vá; một người kiểm tách biệt quan sát lại trang trực tiếp (computed-style overflow-x: auto, không cắt ở 375px); trình kiểm tra sổ trạng thái đơn định trả exit 0; và một lỗi ngoài phạm vi (BUG-001) bị leo thang, không bị đụng tới. Đó là cái đã đáp xuống đâu trước khi ta đi qua vòng lặp. Các artifact nằm trên đĩa ở ../shipwithai.io/.fixkit/, nên không cái nào cần một lần chạy mới để xem.

Bước 1, tiếp nhận. Một lỗi trở thành một dòng sổ trạng thái BUG-*.md. Vì sao: dòng đó là đơn vị trạng thái mà chốt chặn về sau đọc. BUG-003 vào dưới dạng một lỗi tràn ngang code-block: một <pre> kết xuất (render) ra ngoài .article-body (đoạn “Your Takeaway”) cắt các dòng dài ở bề rộng hẹp. Kiểm: dòng tồn tại ở BUG-003-codeblock-overflow.md với state và symptom_layer: UI đã đặt.

Bước 2, người tạo soạn một bản vá đúng tầng. Một lỗi tầng UI định tuyến tới ui-bug-agent. Vì sao: bản vá phải nằm ở tầng của nguyên nhân, không phải tầng trên nó. Người tạo khoanh một quy tắc CSS (.code-snippet-takeaway :global(pre) soi chiếu lại fence của thân bài overflow-x: auto, lấy từ token). Kiểm: trường fix: của sổ trạng thái nêu file và quy tắc, không có giá trị thô và không đụng hard-lock.

Bước 3, người kiểm (nước đi then chốt). Một agent tách biệt xác minh dựa trên trang đã kết xuất, một cách độc lập (non-circular). Nó quan sát lại computed-style cộng viewport, không phải mã nguồn đã vá.

# the H1 checker binding (web-harness, headless Playwright drive.js)
--selector '#takeaway-snippet pre' --prop overflow-x --expected auto
# -> { ok: true, value: "auto" }   PASS (cuộn được, không cắt mép phải)
--selector html --widths 1240,768,375
# -> { ok: true, failingWidths: [] }   không tràn ở mức trang

Vì sao: một người tạo tự chấm bản khác biệt (diff) của mình là tự chấm bài mình. Đây là phân tách người tạo/người kiểm (Phần 5) làm thật. Kiểm: người kiểm đọc overflow-x: auto từ DOM trực tiếp ở localhost:4321, và lượt đọc viewport trả failingWidths: [].

Bước 4, leo thang và bất biến từ chối. Nguyên nhân gốc của BUG-001 là một organism ArticleHero của @shipwithai/design (khoảng cách 96px từ đoạn trích tới thân bài trên các bài không ảnh). Vòng lặp từ chối sửa src/ phía tiêu thụ và leo thang thay vì vậy. Vì sao: vá phía tiêu thụ sẽ rẽ nhánh SSOT của design. Kiểm: git diff -- src/ rỗng, validateLedger.ok = true, và sổ trạng thái giữ nguyên escalated. diff rỗng là bằng chứng của một lần không-sửa đúng đắn.

Bước 5, chốt chặn sổ trạng thái đơn định quyết là xong. Chốt chặn là một máy trạng thái thật: plugins/shipwithai-fixkit-core/lib/ledger-validator.js xuất validateLedger, applyTransition, STATES, LAYER_METHODS, được chống lưng bởi ADR 0004-deterministic-ledger-gate.md. Vì sao: “closed” không thể chỉ là lời người tạo nói. Kiểm: BUG-003 đọc state: closed, capability_tier: FULL, trình kiểm tra engine exit 0; tests/run-all.js theo từng nền tảng chạy lại exit 0 (core 99 check xanh, web 75 check xanh).

Bước 6, trung thực gắn sẵn. Console không sạch: ba lần HTTP 404, tất cả không liên quan tới BUG-003 (một artifact document-status do tiền kết xuất (prerender) ở chế độ dev và một asset author-avatar thiếu). Phương án dự phòng astro build && preview trung thành với prod bị chặn bởi một lỗi bản dựng OG-image __dirname không liên quan. Nên BUG-003 đóng trên ràng buộc computed-style đúng tầng, với GAP-A/B/C ghi trong H1-GAPS.md thay vì phủ lấp. chi phí Pool-2 và các phán quyết agent theo từng gap của lần chạy đó do agent báo, không kiểm chứng được trên đĩa, nên coi là xấp xỉ và đừng đọc con số cứng nào ra.

Giờ tới phần không chạy. H1 là một lần chạy chốt chặn thủ công trên nhánh gate-run/h1-realsite, và Ethan chạy mọi git push. Cú kích hoạt theo lịch (một cloud Routine hay cron) và các đầu nối PR/ticket chưa bao giờ được chạy. Đây là hình dạng của chúng, không phải một dấu vết (trace):

# == CƠ CHẾ (chưa chạy): chỉ hình dạng đấu nối, KHÔNG phải trace H1 ==
schedule:            # một cron/Routine đánh thức fixkit (laptop đóng)
  cron: "..."
on_verified_close:   # các đầu nối KHÔNG bắn trong H1:
  - open_pr:         "...patch + ledger advance..."
  - update_ticket:   "...state: closed, tier: FULL..."
# Thực tế H1: chạy thủ công, chỉ chốt chặn. Ethan chạy mọi git push.

Đó đúng là điểm của bản thiết kế (blueprint): định nghĩa hoàn thành (chốt chặn) có thể là phần hoàn thiện nhất từ rất lâu trước khi vòng lặp quanh nó tồn tại.

Điểm mấu chốt: Người kiểm của fixkit không bao giờ đọc bản vá, nó đọc lại trang đã kết xuất. Một người tạo tự chấm bản khác biệt của mình là tự chấm bài mình; một người kiểm quan sát lại computed-style trực tiếp mới là lý do closed có nghĩa. Bằng chứng độc lập đó chính là toàn bộ chốt chặn.

Bản thiết kế có thật sự tổng quát hoá? Ba vòng lặp thật trên bậc thang

Có, và bằng chứng không phải một vòng lặp bóng bẩy mà là một dải trải. Hệ sinh thái có các vòng lặp thật ở ba nấc khác nhau của bậc thang áp dụng, và chính cái dải đó là lập luận: bắt đầu thủ công với một chốt chặn thật, thêm một xương sống, chỉ tự động hoá khi phán quyết đã đáng tin. bậc thang chạy: thủ công, rồi +xương sống, rồi giới hạn bằng /goal, rồi nhịp đập hằng đêm, rồi leo đồi (hill-climbing).

Ba vòng lặp thật nằm trên đó (nguồn: audit JOB-B, kiểm chứng trên đĩa).

Vòng lặp fix-pack .fixkit có chốt chặn đơn định mạnh nhất và một lần chạy trên site thật đã được chứng minh, nhưng vỏ vòng lặp vẫn còn nằm trên kế hoạch. Chốt chặn là phần hoàn thiện nhất (máy trạng thái sổ trạng thái, run-all.js exit 0); lần chạy H1 là thật. Nhưng không có LOOP-SPEC-fixpack.md, không có xương sống LOOP-STATE, không có nhịp đập. Chốt chặn đã chứng minh, vòng lặp chưa dựng.

Vòng lặp thành phần shipwithai-design đang ở Phase 0 tới 1, là xương sống thủ công giàu nhất trong hệ sinh thái. Một LOOP-STATE.md thật mang 10 verified / 4 open / 3 tried / 2 blocked dòng (chạm gần nhất 30a8431, 22/6/2026); pnpm test là 650/650 vitest, exit 0; validate-spec của toolkit là 65/65, chạy lại độc lập exit 0; dấu vết thật theo từng lần chạy nằm ở docs/loop-runs/. Nhưng nó do người khởi động mỗi lần chạy và do người merge (“Nothing merged, Ethan merges”), không có lịch. Xương sống là thật; sự tự chủ thì không.

Vòng lặp phân loại gap-log (chủ đề Phần 7) đạt tới Phase 3. nhịp đập cron đã chạy thật trên master suốt 4 ngày trong tuần (16 tới 19/6/2026), với các state auto-commit [skip ci] do máy ghi (e8e7298, 6f8dd77, d99d377, a7cc2ab) là tổ tiên của origin/master, và gaplog-state.json do máy ghi lúc 2026-06-19T00:35:26Z. Đó là lịch sử dấu vết tích luỹ thật, và nó là vòng lặp duy nhất có mầm liệu cho nấc 5 (leo đồi): bộ xếp hạng từ khoá gác lại một gap mà bộ não agent suy luận ra đúng. Sau đó workflow được gỡ khỏi master ở bản phát hành v1.0.0 (4d88bbf, “release tree wins”) và giờ nằm trên một feature branch, nên nó đã-từng-chạy-thật, không còn lên lịch. Xem bản cải tạo đầu tiên của chúng tôi để biết hành trình; đoạn này trích nấc, không kể lại câu chuyện.

Dưới cả ba, engine chốt chặn -toolkit chạy 6 chốt chặn đơn định ở exit 0 (validate-spec, test, test:manifest, audit-anti-patterns, export-for-ai:health, meta-check); việc điều phối nó đã lên kế hoạch, chưa chạy.

Điểm mấu chốt: Không vòng lặp nào trong hệ sinh thái là “xong”. Một cái có chốt chặn mạnh nhất nhưng không có vỏ vòng lặp; một cái có xương sống giàu nhất nhưng người khởi động mọi lần chạy; một cái chạy trên cron thật rồi bị gỡ lịch ở một bản phát hành. Bản thiết kế không phải một vòng lặp đã hoàn tất, nó là con đường mà cả ba đang ở đâu đó dọc theo.

Cùng một hình dạng tái dựng cho mobile, web và PM ra sao?

Cùng một hình dạng ba phần (người tạo soạn, một người kiểm tách biệt xác minh dựa trên một điều kiện dừng, leo thang từ chối việc ngoài phạm vi) tái dựng cho bất kỳ vai trò nào; chỉ thang chấm (rubric) của người kiểm đổi. Bảng dưới phác ba cái. Đây là các bản phác thảo, không phải vòng lặp đã dựng. Chỉ dòng fixkit đã chạy thật.

Với mobile, người tạo là một agent màn hình hay tính năng; người kiểm là một ma trận bản dựng/thiết bị (nó dựng được và chạy xanh trên các thiết bị mục tiêu không) cộng các làn so khác ảnh chụp màn hình (screenshot-diff) với một bản nền. Phần khó nhất là trình giả lập (simulator) chập chờn và lệch chuẩn nền.

Với web, người tạo là một agent thành phần hay trang; người kiểm là một thang chấm e2e (Playwright) cộng khả năng tiếp cận (a11y, axe), xanh. Phần khó nhất là a11y có tiêu chí một phần chủ quan, nên thang chấm của người kiểm khó làm hoàn toàn đơn định hơn.

Riêng PM là ca khó nhất: người tạo viết và phân loại tài liệu (brief, cụm phản hồi); điều kiện dừng đặt trên tài liệu, không phải test. Một thang chấm hay danh sách kiểm mà một mô hình thứ hai chấm, không bao giờ là lời tự nhận của người viết. Phần khó nhất: chấm văn xuôi là điều kiện dừng khó nhất trong loạt bài. “Xong” trên một brief thật sự mờ, và đây là nơi vòng lặp cần nhất một con người trong hộp chờ (inbox).

Mọi dòng là cùng một hình dạng, đó là điểm: fixkit không đặc biệt, nó chỉ là phiên bản đã chạy. Dòng PM là sức căng sống mà Phần 9 nhặt lên.

Điểm mấu chốt: Đổi vai trò không đổi vòng lặp, nó đổi thang chấm của người kiểm. Một bản vá “xong” khi một test quan sát lại nó; một brief “xong” khi một thang chấm do một mô hình thứ hai chấm nói thế. Điều kiện dừng càng mờ, con người trong hộp chờ càng quan trọng.

Đóng gói một vòng lặp devkit thành Claude Code plugin ra sao?

Gom harness theo vai trò (skills + agents + hooks, cộng chốt chặn đơn định) vào một Claude Code plugin, xuất bản nó lên một marketplace, và một đồng đội cài cả harness trong một lệnh. plugin giao harness; lớp vòng lặp (lịch + đầu nối) là phần mỗi đội đấu nối vào repo của mình. Đây là chỗ một Claude Code plugin loop thôi là thứ bạn chạy và trở thành thứ bạn xuất bản.

Một plugin gom các file SKILL, các định nghĩa .claude/agents/, và hooks. shipwithai-fixkit là một marketplace plugin thật nơi mỗi pack nền tảng giao tests/run-all.js riêng (chạy lại exit 0), nên chốt chặn đi bên trong plugin. Về các bước cài, xem cài một plugin; đoạn này lo phần đóng gói, không phải cơ chế cài.

shipwithai-fixkit/                 # marketplace plugin
'-- plugins/shipwithai-fixkit-core/
    |-- skills/                    # ý định dự án
    |-- agents/                    # người tạo / người kiểm / leo thang
    |-- hooks/                     # rào chắn theo sự kiện
    '-- tests/run-all.js           # chốt chặn, exit 0, đi cùng trong plugin

# đi cùng trong plugin            |   đấu nối theo từng repo
#   skills + agents + hooks        |     lịch (cron/Routine)
#   chốt chặn đơn định             |     đầu nối PR/ticket

Cái bạn có thể trao cho một đồng đội hôm nay là harness cộng chốt chặn (đã chứng minh). Lịch và các đầu nối PR/ticket là phần đấu nối theo repo mà họ hoàn thiện (cơ chế). Đó là ranh giới, vẽ trung thực.

Điểm mấu chốt: Một vòng lặp devkit trở nên tái dùng được ngay khi chốt chặn đi vào bên trong plugin. Đồng đội của bạn không thừa kế các prompt của bạn, họ thừa kế định nghĩa hoàn thành của bạn. Cái lịch họ tự đấu nối; tiêu chuẩn cho “đã sửa” thì cài sẵn.

Kết

Giờ bạn có bản thiết kế (harness nhân lớp vòng lặp), một lượt đi qua fixkit bạn tin được vì artifact nằm trên đĩa, một đường ranh rõ giữa cái đã chạy (chốt chặn + người tạo/người kiểm/leo thang/sổ trạng thái) và cái là cơ chế (lịch + đầu nối), ba vòng lặp thật đặt trung thực trên bậc thang, một bảng khác biệt một trang cho mobile/web/PM, và một cách đóng gói harness thành một plugin.

Vài cách việc này hỏng: giao harness nhưng ngụ ý lịch và đầu nối đã chạy (chúng không chạy trong H1); coi một dấu vết từ bản demo là bằng chứng các chốt chặn thật đã qua; gọi nhịp đập gap-log là “chạy hằng đêm” khi nó chạy rồi bị gỡ lịch; trình bày các bản phác thảo mobile/web/PM như đã dựng. Mỗi cái là cái bẫy nợ-hiểu-biết (comprehension debt) mà Phần 9 nói tới.

Bạn dựng được vòng lặp và đóng gói nó. Phần 9, loop-failure-modes-staying-engineer, là nửa khó hơn: hai kỹ sư dựng cùng một vòng lặp và nhận kết quả trái ngược, vì vòng lặp không biết sự khác biệt, bạn mới biết.

FAQ

AI devkit loop là gì?

Một AI devkit là một harness theo vai trò: skills, agents, và hooks đóng gói cho một việc (chẳng hạn sửa lỗi). Một vòng lặp devkit thêm một lớp vòng lặp lên trên: một lịch đánh thức nó, một file lưu trạng thái nhớ giữa các lần chạy, và một điều kiện dừng kiểm chứng được mà một mô hình khác kiểm. devkit là bản dựng; vòng lặp là cái cho nó chạy và dừng mà không cần bạn prompt từng lượt.

Devkit và vòng lặp devkit khác nhau ở đâu?

Một devkit là harness đứng một mình: cài nó và bạn có skills, agents, và hooks cho một vai trò. Một vòng lặp devkit là harness đó nhân ba thứ làm nó tự chủ và trung thực: một nhịp đập (nó thức theo lịch), một bộ nhớ (một file lưu trạng thái ngoài context window), và một định nghĩa hoàn thành mà một người kiểm tách biệt xác minh. Hầu hết các bài “dựng AI agent” giao cái đầu; vòng lặp là cái thứ hai.

Tôi có cần fixkit để dựng vòng lặp devkit của riêng mình không?

Không. fixkit là ví dụ đã chạy vì nó có một điều kiện dừng đơn định, thật (một chốt chặn sổ trạng thái quan sát lại trang đã kết xuất, exit 0 hay không) và một lần chạy thật trên site trực tiếp. Bản thiết kế mới là cái tổng quát hoá: một người tạo soạn, một người kiểm tách biệt xác minh dựa trên một điều kiện dừng, leo thang từ chối việc ngoài phạm vi, và một chốt chặn quyết là xong. Đổi vai trò thì bạn chỉ đổi thang chấm của người kiểm.

Vì sao devkit PM khó đóng thành vòng lặp nhất?

Vì điều kiện dừng của nó đặt trên tài liệu, không phải test. Một bản vá lỗi “xong” khi một test quan sát lại hành vi đã kết xuất; một brief hay một lượt phân loại phản hồi “xong” khi một thang chấm do một mô hình thứ hai chấm nói thế, và chấm văn xuôi thật sự mờ. Hình dạng người tạo/người kiểm vẫn đứng, nhưng phán quyết của người kiểm mềm hơn, nên một vòng lặp PM dựa nặng nhất vào một con người trong hộp chờ.

Tôi có thể xuất bản một vòng lặp devkit dưới dạng Claude Code plugin không?

Bạn có thể xuất bản nửa harness hôm nay: skills, agents, hooks, và chốt chặn đơn định gom vào một Claude Code plugin mà một đồng đội cài trong một lệnh (shipwithai-fixkit là một marketplace plugin thật, kèm chốt chặn). Lớp vòng lặp, cái lịch đánh thức nó và các đầu nối PR/ticket, là phần mỗi đội đấu nối vào repo của mình. Tiêu chuẩn cho “xong” cài sẵn; nhịp đập bạn tự thêm cục bộ.

Đọc tiếp gì nữa

• Nhật ký hành trình: cải tạo vòng lặp thật đầu tiên (Phần 7): bản retrofit gap-log mà bản thiết kế này tổng quát hoá.
• Harness Claude Code 5 lớp: giải phẫu harness theo vai trò mà devkit đóng gói.
• Cài một Claude Code plugin: phía cài đặt của phần đóng gói.