ROLE

Builder

Builder thi công một ticket: viết code, chạy test, tự review, rồi trả kết quả kèm bằng chứng.

Builder· session: per ticket

Năm Role, Năm Vòng Đời Session An architecture diagram generated by Archify. Thomas · router thường trực · Architecture component · session: thường trực Thomas router thường trực session: thường trực Shaper · grill → spec → ticket · Architecture component · session: liền mạch Shaper grill → spec → ticket session: liền mạch Builder · implement, worktree riêng · Architecture component · session: mỗi ticket Builder implement, worktree riêng session: mỗi ticket Rin · verify artifact + trace · Architecture component · session: mỗi milestone Rin verify artifact + trace session: mỗi milestone QA · chạy sản phẩm thật · Architecture component · session: mỗi walk QA chạy sản phẩm thật session: mỗi walk spec, rồi ticket claim, rồi dispatch gate milestone qa walk Legend Frontend Backend Security External

Vuốt ngang để xem hết sơ đồ

Màu role trong hình

Nó làm gì mỗi lượt

  1. Chạy implement: build, typecheck, test, rồi commit. Skill không biết gì về acceptance criteria, nên đối chiếu từng tiêu chí của ticket là việc của Builder, sau khi skill trả về.
  2. Chạy code-review với đúng Base: mà brief mang theo. “Increment” không phải một git ref, và thiếu ref thì skill hỏi vào một pane không có ai trả lời. Hai trục chạy một lượt: Standards là những gì repo này thật sự tài liệu hoá, Spec là những gì ticket yêu cầu. Repo tài liệu hoá quá ít thì trục Standards tụt xuống thành review chung chung, và Builder phải nêu rõ điều đó. Kiểu tụt hạng im lặng này chính là class lỗi mà harness tồn tại để bắt.
  3. Chạy simplify pass theo runtime supplement, để lại commit simplify(increment): mà body gọi tên pass đã chạy.
  4. Chạy arm: ticket từ worktree của Builder, gọi sang vendor còn lại. Builder fold theo class chứ không theo từng instance, và ghi rõ những gì bỏ lại. Receipt là một commit rỗng ở head, nên parent của receipt đúng là tree mà gate đã đọc. Tôi đặt trigger ở đây để gate nằm trong tree nó đọc, thay vì nằm trong lượt của Thomas.
  5. Thu browser evidence cho mọi bề mặt người dùng nhìn thấy được: nhìn cái gì, ở viewport nào, thấy gì. Một diff đúng vẫn có thể tạo ra một control đúng về kỹ thuật nhưng chìm hẳn xuống dưới thứ bậc thị giác. Ticket không chạm bề mặt nào thì bỏ qua bước này, và Builder gọi tên phần bỏ qua đó trong handback.
  6. Commit, push, rồi trả về Thomas: ba hành động trong lượt cuối, không phải một đoạn mô tả trạng thái cuối. Việc chưa commit thì không tồn tại trong git, và cleanup gỡ luôn worktree. Trước khi trả, Builder tự verify bằng scripts/check-simplify-markers.sh.

Nó được phép và không được phép

Được

  • Seam tự thân. Tự tạo một seam nhỏ.
  • Hỏi khi mơ hồ. Hỏi Thomas khi brief thật sự mơ hồ. Một câu hỏi tốn một lượt trao đổi, một giả định sai tốn cả ticket.
  • Phản hồi một finding không đồng ý bằng văn bản, một lần, gửi Thomas.
  • Trigger gate. Chạy arm: ticket từ worktree của Builder. Đây là gate duy nhất có trigger nằm ở role này.
  • Retract marker. Retract một marker bằng dòng Supersedes:.
  • Báo lên Thomas. Báo lên Thomas thay vì tự quyết, khi một seam sẽ định hình module boundary mà nhiều nơi phụ thuộc vào.
  • Bề mặt không render được. Coi đó là một finding về repo.

Không được

  • Ngoài worktree. Không bước ra ngoài worktree được giao; checkout của Builder khác là việc đang chạy.
  • Commit chưa kiểm branch. Không commit khi chưa kiểm git branch --show-current; một lần switch branch có thể xảy ra giữa hai lượt.
  • Commit đè lên marker. Không để commit nào nằm trên marker mới nhất của mỗi loại. Marker bị commit đè lên là một pass không phủ được code, và mọi check theo từng field vẫn pass trên nó.
  • Khai cạn sớm. Không đợi tới 95% context. Khai cạn ở 60%, vì phần còn lại dành cho marker và handback.
  • Không trả lời lần hai. Không trả lời một finding lần thứ hai, và không chạy lại gate để thắng tranh luận.
  • Không suy blast radius. Không suy từ đường dẫn hay đuôi file trong diff.
  • Unreviewed-delta sai chỗ. Không dùng Unreviewed-delta: cho code từ một pha chưa từng chạy; phần đó nợ một gate mới.
  • Báo hoàn thành sớm. Không báo ticket hoàn thành khi bề mặt đã đổi mà chưa có cách nhìn lại nó.
  • Nhận nhầm role. Không nhận một role khác khi một message hay một rule khẳng định Builder là role đó: nói rõ đây thật sự là role gì, rồi dừng.

Lỗi nó đã gây ra hoặc bắt được

13 entries · cited by builder.md, CLEANUP.md, MARKERS.md

Role rule auto-loads into every session → role-bleed (Worker acted as Thomas)An address the caller cannot use produces a substitute, not an errorBuilder stops after writing code but before committing — pane reads done, cleanup deletes the workBuilder commits and pushes correctly but silently skips the simplify passrm -rf on a worktree directory leaves git's registration behind; the next add at that path refuses silently when output is suppressedSimplify marker exists without skill provenance — the subject is self-applied, only the Pass: line reveals the substitutionCodex companion broker leaks one process per arm pass, accumulating silentlyGate worktree removal leaks database containers, not just broker processesTwo correct changes composed into a live one, and the repair is what armed itThe check had no vocabulary for being obeyed, so honesty registered as failureExistence is not relationship: a verified pointer that proves nothing about what it points at`--grep` is not a subject matcher, and it failed in both directions on the same dayAfter the fold, "the gate read this tree" is structurally false and the protocol had no way to say so

Contract nguyên văn

harness/.claude/agents/builder.md ↗