Dựng lại workflow Helix của Shopify trong Claude Code

1. Shopify dựng lại app 300 màn hình bằng coding agent

Video mở đầu bằng tin Shopify vừa dựng lại (rebuild) app di động chính của họ, và trong quá trình đó đã công bố một AI coding workflow mà kênh AI LABS gọi là "tuyệt vời". Để hiểu vì sao chuyện này lớn, theo AI LABS, cần thấy đây là một việc khổng lồ: họ rebuild một app rất lớn với 300 màn hình, và toàn bộ được làm bằng AI coding agent.

Nhưng Shopify không giao cả việc cho một agent trong một lần. Họ dùng một workflow có cấu trúc chặt chẽ từ đầu tới cuối, nhờ đó app vẫn giữ được đúng tiêu chuẩn của họ.

Vấn đề là Shopify chỉ nói về phương pháp, chứ chưa bao giờ cho thấy cụ thể nó được làm ra sao. Vì vậy nhóm AI LABS lần lại từng bước (retrace) và tự dựng lại cùng workflow đó cho mình. Theo họ, các bước trong workflow của Shopify cho agent một quy trình mà nó không thể "nói khéo để thoát ra" (a process it can't talk its way out of). Thế nhưng ngay cả khi đã có workflow đó, agent vẫn tìm cách làm hỏng việc, và nhóm đã thêm một thay đổi giải quyết triệt để vấn đề này.

AI LABS tự giới thiệu: họ là một công ty phần mềm và đây là kênh của họ. Trong video này, họ sẽ cho xem workflow của Shopify và cách họ dựng nó, để người xem cũng chạy được cùng vòng lặp AI coding đó trên app của chính mình.

Shopify gọi công cụ đứng sau vòng lặp này là Helix. Họ làm ra Helix vì đang viết lại app theo một cách khác với cách nó được build ban đầu (theo bài viết của Shopify, họ chuyển app từ React Native về native Swift và Kotlin). Tóm tắt điều họ làm: lấy một màn hình của app cũ và yêu cầu agent chuyển nó sang phiên bản mới. Helix sau đó đọc màn hình đó.

2. Helix: checkpoint, bốn lớp kiểm tra và sub-agent

Sau khi đọc màn hình, Helix chia công việc thành những task nhỏ hơn gọi là checkpoint. Một người trong nhóm Shopify xem lại (review) các checkpoint này trước tiên. Rồi sau khi được duyệt, mỗi checkpoint phải vượt qua bốn lớp kiểm tra nghiêm ngặt trước khi Helix bắt đầu làm checkpoint tiếp theo. Bốn lớp kiểm tra này bảo đảm app đạt đúng tiêu chuẩn của họ.

Helix dùng sub-agent để làm phần lớn công việc. Lý do chính khiến họ dùng sub-agent cho mọi thứ là context window mới tinh (fresh context window). Nếu một agent làm một task rất dài và giữ mọi thứ trong cùng một context window, sẽ phát sinh vấn đề. Khi mọi thứ dồn vào cùng một context window, lượng thông tin trở nên quá nhiều với agent, nó bắt đầu quên những điều quan trọng ở giữa, và chất lượng công việc bắt đầu đi xuống. Sub-agent ngăn chuyện đó bằng cách giữ một context window riêng cho từng task.

3. Hai ý cốt lõi, và vì sao workflow này dùng được ngoài chuyện chuyển đổi app

Toàn bộ vòng lặp xoay quanh hai thứ. Thứ nhất là checkpoint, chính là những mẩu việc nhỏ vừa nói. Thứ hai là bốn lớp kiểm tra mà Shopify gọi là gate. Một gate là một bài kiểm tra mà công việc phải vượt qua; việc nào trượt sẽ bị chặn, không được chuyển sang task tiếp theo cho tới khi gate đó được thông qua.

Dù Shopify dùng workflow này để chuyển một app từ dạng này sang dạng khác, AI LABS cho rằng nó dùng được rộng hơn thế nhiều. Quy trình này cho phép bạn build những feature rất lớn, đồng thời bảo đảm thứ bạn build đạt tiêu chuẩn của app và trông cũng đẹp.

Helix hiện vẫn là công cụ nội bộ, người ngoài không có quyền truy cập. Nhưng Shopify đã công bố toàn bộ cách họ thiết lập, nên AI LABS tự tạo workflow của mình và thử nó trên một dự án demo: một hệ thống HR (quản lý nhân sự). App đó đã được build xong toàn bộ, và nhóm chỉ đang thêm feature vào. Họ hứa sẽ giải thích chi tiết từng bước làm gì, để người xem có thể tái tạo cùng workflow khi làm app của mình.

4. Skill orchestrator: chỉ cần prompt một skill

Vì tự tay chạy từng bước của vòng lặp sẽ cần rất nhiều input từ phía người dùng, nhóm tạo một skill và đặt tên là orchestrator. Orchestrator là skill duy nhất bạn cần prompt; nó tự lo mọi phần còn lại. Input của bạn chỉ cần tới hai lần, phần thời gian còn lại orchestrator tự xử lý tất cả.

Phần mô tả của skill trên màn hình tóm gọn cả vòng lặp: lập kế hoạch checkpoint có gate, viết test và prototype, rồi cho từng checkpoint đi qua implement, behavior gate, UI gate, adversarial review gate, cuối cùng giao cho con người review. Dòng đầu phần thân ghi rằng nó chỉ điều phối chứ không tự làm việc; mỗi phần việc thật đều giao cho một sub-agent mới.

---
name: orchestrator
description: Build a whole feature end-to-end through subagents. It plans gated checkpoints, writes tests and prototypes, then loops each checkpoint through implement → behavior gate (CLI/code tests, UI e2e last) → UI gate (live vs prototype) → adversarial review gate until every checkpoint passes, then hands it to a human to review. Use when the user says "build X", "orchestrate X", "/orchestrator <feature>", or asks to resume an orchestrated feature.
---

# Orchestrator

You coordinate; you don't do the work. Every piece of real work goes to a fresh subagent, so

Nhưng trước khi build bằng nó, video đi qua các phần cốt lõi của vòng lặp, bắt đầu từ checkpoint.

5. Checkpoint xếp từ đơn giản tới phức tạp, và agent Checkpoint Planner

Như đã nói, checkpoint thực chất là những phần nhỏ của một feature lớn. Shopify làm theo nguyên tắc: chừng nào một checkpoint chưa hoàn thành đúng cách thì checkpoint kế tiếp không được bắt đầu. Họ chia việc thành các checkpoint theo thứ tự độ phức tạp tăng dần. Nghĩa là các task nhỏ nhất được build trước, rồi tới task phức tạp hơn một chút, và cứ thế. Lý do: mỗi checkpoint được build chồng lên checkpoint trước nó, nên nếu một quyết định ban đầu bị sai, bạn bắt được nó khi nó vẫn còn nhỏ và còn rẻ để sửa.

Để chia feature thành các phần nhỏ, nhóm tạo một agent tên là Checkpoint Planner. Agent này nhận feature lớn mà bạn giao cho orchestrator và chia nó thành các checkpoint. Nó ghi các checkpoint ra một file định dạng JSON, vì cấu trúc JSON dễ hiểu với agent và agent dễ tìm được thứ nó cần trong file. File định nghĩa agent trên màn hình:

---
name: checkpoint-planner
description: Breaks a large feature into small, ordered, gated checkpoints and writes them as JSON to docs/checkpoints/<feature-slug>.json. Checkpoint 1 is the smallest thing that can pass; each later checkpoint is a bit bigger and builds on the one before. Use when the user wants a feature planned, split into steps, or broken into checkpoints before implementation.
tools: Read, Glob, Grep, Bash, Write
---

You plan features for this HR management system (FastAPI in `apps/api`, Next.js in `apps/web`, Postgres in `supabase/migrations`). You write a plan file and nothing else. Never edit code, migrations, or other docs.

Nhưng có một việc bạn phải tự làm: review các checkpoint này. Dù JSON có cấu trúc, con người thực ra rất khó đọc trực tiếp file đó mà hiểu được. File trở thành một khối văn bản có cấu trúc khổng lồ, quá nhiều để một người theo dõi. Vì lý do đó, nhóm build thêm một trang web viewer đơn giản để dễ dàng xem agent đã lên kế hoạch gì.

6. Chạy thử: thêm hệ thống payroll vào app HR

Quy trình diễn ra thế này: bạn nói với orchestrator feature muốn thêm vào app. Trong demo, câu lệnh gõ vào Claude Code là:

/orchestrator i want to add a payroll system to this app

Orchestrator khởi động hai sub-agent. Một sub-agent kiểm tra trạng thái hiện tại của app và bảo đảm app đang chạy (trên màn hình là bước "Phase 0 preflight"). Sub-agent còn lại là agent Checkpoint Planner mà nhóm đã tạo. Nếu Checkpoint Planner có câu hỏi, nó sẽ hỏi bạn (trong demo, nó hỏi những điều như nhân viên được trả lương theo cách nào, thuế và khấu trừ xử lý ra sao, nghỉ không lương có trừ lương không, ai được xem phiếu lương nào). Sau đó nó ghi ra toàn bộ checkpoint, và orchestrator mở viewer để bạn review.

Viewer cho bạn thấy từng bước theo thứ tự, bước nào đang được làm, và mỗi task cần gì để được coi là xong. Nhóm cũng dặn Checkpoint Planner giữ ngôn ngữ đơn giản để bạn dễ hiểu cách diễn đạt.

Ở thời điểm này, orchestrator cũng giao cho một sub-agent khác việc lập kế hoạch test. Sub-agent đó ghi chi tiết cách từng checkpoint sẽ được kiểm tra, để mọi thứ được ghi lại ngay từ đầu.

Đây là một trong những bước bạn cần làm kỹ: review để biết kế hoạch không thiếu feature nào, và toàn bộ thời gian agent bỏ ra để implement sẽ không bị phí. Review xong, bạn hoặc yêu cầu sửa, hoặc duyệt. Khi bạn duyệt kế hoạch, orchestrator bắt đầu build, khởi đầu từ checkpoint 1.

7. Gate khác rule thế nào: hook trả về exit code 2

Nhưng trước khi xem checkpoint 1 được build ra sao, cần hiểu một checkpoint phải vượt qua những gì thì mới được tính là xong. (Ở đây kênh chen một lời mời subscribe và bấm nút hype.)

Thứ cho phép một checkpoint đi qua thực chất là một điểm review, và Shopify gọi các điểm review này là gate. Thông thường bạn đưa yêu cầu review dưới dạng prompt. Nhưng một gate khác với một rule trong chỉ dẫn mà bạn đưa vào prompt hay vào file, vì rule chỉ là lời khuyên. Agent quên rule khi đang làm việc, và bạn phải nhắc lại. Gate thì khác: chừng nào gate chưa được thông qua, nó không cho agent chuyển sang task tiếp theo.

Để bảo đảm thiết lập của mình không cho agent làm task tiếp theo khi gate chưa qua, nhóm tạo một hook. Hook này chạy mỗi lần agent định dừng lại. Khi agent cố dừng, hook trả về exit code 2. Exit code 2 ở đây không dùng để báo có lỗi xảy ra trong lúc làm việc; nó chỉ dùng để thúc agent làm nốt việc rồi tiếp tục. Hook của nhóm báo cho agent rằng việc chưa xong, nên nó phải tiếp tục cho tới khi các gate được thông qua. Theo AI LABS, đây là cùng một khái niệm mà họ mượn từ Ralph loop (kỹ thuật cho agent chạy lặp đến khi việc thật sự xong).

8. Bốn gate của Shopify

Shopify dùng bốn gate trong workflow của họ:

1. Behavior gate: kiểm tra feature có chạy hay không.
2. UI gate: kiểm tra màn hình có trông giống design mong muốn không.
3. Code review gate: kiểm tra phần code bên dưới có tốt không.
4. Final review: lần review cuối cùng của chính bạn.

Video bắt đầu từ việc thiết lập behavior gate. Trước đó, video có một đoạn quảng cáo cho Hedra.

9. Gate 1, Behavior: viết test trước code

Behavior gate gồm toàn bộ phần kiểm thử có thể làm mà không cần dùng tới browser và agent điều khiển browser. Thay vì kiểm tra app bằng cách bấm qua lại trên giao diện, agent viết những đoạn kiểm tra nhỏ dưới dạng code, dùng feature đúng theo cách một người dùng thật sẽ dùng. Những đoạn kiểm tra nhỏ này gọi là test, và chúng đã được lên kế hoạch và hiện trong viewer lúc trước.

Lý do lên kế hoạch test trước, như kênh đã nhắc trong các video trước, là để agent có một chuẩn rõ ràng mà đối chiếu công việc của nó, nhờ đó nó tự xác minh được feature có chạy đúng như dự định không. Các test này cố bao phủ càng nhiều trường hợp càng tốt, để xác minh rằng luồng xử lý bên dưới app vẫn chạy đúng với nhiều input khác nhau.

Để việc này dễ hơn, nhóm sửa lại skill TDD Planner từ video trước cho hợp với workflow này (trên màn hình nó có tên test-planner). Skill này về cơ bản lên kế hoạch và viết test cho feature được giao cho nó.

---
name: test-planner
description: Plan and write the tests for a feature, bottom-up. Everything that code or the CLI can verify (pure logic, API endpoints, DB constraints, auth/role rules) is tested without a browser. UI end-to-end tests come last and cover only what the lower layers can't. Use when the user asks to plan tests, write tests, or add test coverage for a feature or checkpoint (e.g. "/test-planner leave accrual").
---

# Test planner

**If you're running as a subagent** (for example, launched by `/orchestrator`), you can't launch subagents. Do the steps marked "subagent"

Skill này bảo đảm mọi thứ có thể xác minh mà không cần browser đều được test ở bước này. Lý do là rất nhiều thứ không cần browser để kiểm tra, ví dụ một manager có được phép duyệt đơn nghỉ phép của ai đó hay không. Với việc đó, agent có thể dùng một đoạn code để xác minh trực tiếp, chứ không cần bấm nút để xem đơn đã được duyệt hay chưa. Sub-agent lập kế hoạch test lúc trước chính là đang làm theo skill này.

10. Gate 1 chạy thật trên checkpoint 1

Bước này đến sau bước trước đó, nơi các checkpoint được agent tạo ra. Khi bạn đã duyệt các checkpoint được đưa ra cho bạn xem, orchestrator bắt đầu làm checkpoint 1.

Việc đầu tiên orchestrator làm là khởi động vài sub-agent để viết test, thứ cần cho gate đầu tiên. Lúc đầu tất cả test đều trượt, vì feature mà chúng kiểm tra chưa được viết.

Khi test đã xong, orchestrator khởi động một sub-agent khác để thực sự viết code cho checkpoint này. Rồi orchestrator dùng thêm một sub-agent nữa để chạy test và bảo đảm từng test đều pass. Khi mọi test pass, gate 1 được đánh dấu là đã qua cho checkpoint 1, và orchestrator chuyển sang vòng review tiếp theo: UI gate.

11. Gate 2, UI review: Shopify dùng Gemini làm người soát design

UI review gate là một trong những gate quan trọng nhất vì nó ảnh hưởng trực tiếp tới trải nghiệm người dùng. Do Shopify đang chuyển một app sang một dạng khác, việc giữ design giống hệt trở nên rất quan trọng.

Với gate này, Shopify dùng các model Gemini làm một người review design cầu toàn (perfectionist design reviewer). Lý do là khi thử nghiệm, họ thấy các model này có khả năng nhận biết không gian (spatial awareness) rất tốt, nghĩa là model biết mọi thứ nằm ở đâu trên màn hình và lớn cỡ nào. Vì thế Gemini bắt được cả những khác biệt nhỏ về khoảng cách và kích thước giữa hai màn hình.

Nhưng khi bạn làm dự án của riêng mình, hoặc build cho khách hàng, bình thường bạn không có gì để review đối chiếu cả.

12. Khi không có gì để so: HTML prototype và file design.md

Trong những trường hợp đó, nhóm AI LABS tạo HTML prototype trước. Làm prototype giúp họ nhanh chóng demo phần hình ảnh của sản phẩm và thử nhiều hướng đi khác nhau mà không lo ảnh hưởng tới dự án chính. Prototype cũng là thứ họ đưa khách hàng xem để được duyệt.

Để tạo prototype, họ dùng một skill khác tên là prototype. Skill này build cả prototype thành một file duy nhất, mở ra và bấm qua lại được, để thấy thứ mình muốn có thực sự đang được tạo ra không.

---
name: prototype
description: Build a single-file, clickable HTML prototype of a UI screen or flow, following the design directions given in the request. Use when the user asks to prototype, mock up, or sketch a UI (e.g. "/prototype leave request form, dense, neutral palette", "mock up the attendance dashboard").
---

# Prototype

Build a static HTML prototype of the UI the user asked for. It's for looking at and clicking through, not production code.

Skill này làm theo chỉ dẫn riêng của dự án, như file design.md. Đó là một file có cấu trúc liệt kê mọi chi tiết design cần để dựng giao diện (trên màn hình là file DESIGN.md của app HR với tên, mô tả và bảng màu primary, secondary, neutral, surface, border, warning, error...). Nhóm đã tạo sẵn một file như vậy cho app bằng skill design-md-planner, skill họ cung cấp trong bộ design system của AI LABS trong cộng đồng của kênh. Theo mô tả trên màn hình, skill này phỏng vấn người dùng về sản phẩm và gu thẩm mỹ, chọn một hướng thẩm mỹ cụ thể, viết file DESIGN.md theo định dạng DESIGN.md của Google rồi kiểm tra nó bằng CLI chính thức @google/design.md cho tới khi sạch lỗi lint.

Có file đó rồi, prototype được tạo ra trước khi UI được build. Trong demo, hai prototype payroll-payslips.html và payroll-admin.html được dựng song song với test plan ngay sau khi kế hoạch checkpoint xong.

13. So prototype với app thật bằng hai Claude sub-agent

Để so prototype với app đã build, nhóm dùng một skill riêng (review-ui). Skill này bảo đảm phần hình ảnh khớp nhau, đồng thời bảo đảm cả hai hành xử giống nhau khi bạn tương tác.

---
name: review-ui
description: Compare the live UI of the web app against its HTML prototype in prototypes/ and report the visual and behavioral gaps. Screenshots both, then two parallel reviewers (subagents, or `claude -p`) diff them, one for visuals and one for behavior. Use when the user asks to review, check, or diff the implemented UI against a prototype (e.g. "/review-ui leave-request", "does the attendance page match the prototype?").
---

# Review UI against prototype

Trước khi so bất cứ thứ gì, skill còn kiểm tra prototype và app đang ở cùng một trạng thái. Ví dụ, một form chưa submit và một form đã submit là hai trạng thái khác nhau, nên skill bảo đảm cả prototype lẫn app đều đang hiển thị form ở cùng trạng thái.

Nhưng nhóm không dùng Gemini cho việc này. Thay vào đó, skill giao phép so sánh cho Claude trong một session mới, bằng cách khởi chạy nó ngay từ trong session hiện tại (mô tả skill ghi là claude -p).

Không phải checkpoint nào cũng cần gate này, vì gate 1 đã test phần lớn mọi thứ mà không cần browser. Đó là lý do một số checkpoint hiện trong viewer lúc trước không có gate này (nhãn "Looks right: no screen").

Khi orchestrator tới một checkpoint cần gate này, nó khởi động hai Claude sub-agent riêng biệt chạy song song. Một cái review màn hình trông thế nào, cái kia review màn hình hành xử ra sao. Không cái nào được thấy chỉ dẫn của dự án, nên chúng chỉ đánh giá app dựa trên prototype và file design.md. Mỗi cái trả về một bản review các khác biệt, và orchestrator gộp hai bản lại. Bản review gộp đó quyết định gate này qua hay trượt.

14. Gate 3, adversarial review: một agent bắt lỗi, một agent sửa

Đến đây feature đã chạy và trông giống prototype, nhưng code bên dưới vẫn có thể là một mớ hỗn độn. Đó là chỗ gate tiếp theo vào cuộc. Gate thứ ba thực chất là adversarial review gate. Adversarial review nghĩa là nó được dựng ra để phản bác code.

Shopify có quy trình review rất nặng vì họ cần bảo đảm thứ họ ship đạt tiêu chuẩn. Phương pháp của họ dùng hai agent đối kháng (adversarial) kiểm tra code theo một bộ chuẩn mà Shopify đã viết ra. Mọi vấn đề hai agent tìm thấy đều phải được sửa, và chỉ khi cả hai agent cùng duyệt thì gate này mới qua.

Nhóm AI LABS cũng làm với hai agent, nhưng thay vì để cả hai cùng chỉ trích code, họ chọn một vòng lặp đối kháng: một agent chỉ trích, agent kia sửa. Agent thứ nhất là adversarial agent, về cơ bản mặc định rằng code sai và cố tìm ra vấn đề trong nó. Agent thứ hai là fixer agent, thực sự sửa những vấn đề mà adversarial agent tìm ra.

File của fixer agent trên màn hình:

---
name: fixer
description: The adversarial-reviewer's counterpart in an /adversarial-loop debate. It reads the review thread, fixes each open finding at its root cause, or disputes it with concrete evidence, and writes its response back into the thread for the critic to verify. Use only inside /adversarial-loop.
tools: Read, Edit, Write, Glob, Grep, Bash
---

Để điều phối, nhóm có một skill tên là adversarial loop, quản lý giao tiếp giữa hai agent:

name: adversarial-loop
description: Coordinate a multi-round debate between two agents until the code is clean. adversarial-reviewer (the critic) assumes everything is wrong; fixer implements fixes or disputes them with evidence. They exchange findings through a shared thread file, and each keeps its memory across rounds. Use as the orchestrator's review gate, or when the user asks for an adversarial review-and-fix loop on recent changes (e.g. "/adversarial-loop", "have the critic and fixer go at checkpoint 3").

Khi behavior gate và UI gate đã qua, orchestrator khởi động adversarial agent và chờ bản review của nó. Nếu adversarial agent báo về là không có vấn đề gì, orchestrator chỉ việc đánh dấu gate là xong. Ngược lại, orchestrator khởi động fixer agent để sửa, rồi adversarial agent kiểm tra lại code. Hai agent qua lại như vậy, và gate chỉ xong khi adversarial agent duyệt code.

15. Gate 4: con người khép vòng, và file learnings

Bước cuối cùng là human in the loop, và đây là bước rất quan trọng. Dù agent có chuẩn và có thứ để đối chiếu khi review, chúng vẫn không review được từ góc nhìn của một con người. Bạn cần bảo đảm feature hoạt động đúng khi một người thật sự dùng nó.

Vì vậy, khi mọi checkpoint đã xong, bạn cần test feature để chắc nó chạy đúng như bạn muốn. Bạn cũng xem có chỗ nào trong đó có thể chạy tốt hơn hoặc trông đẹp hơn, để yêu cầu những thay đổi nhỏ cho feature.

Khi bạn yêu cầu thay đổi, orchestrator biến chúng thành checkpoint mới, đi qua đúng các gate như cũ. Nó cũng ghi feedback của bạn vào một file learnings mà mọi agent đều đọc trước khi bắt đầu làm việc.

16. Orchestrator chỉ dừng hai lần, và "được phép sai, không được phép ship"

Toàn bộ workflow vừa đi qua được chạy bởi một skill duy nhất, orchestrator đã nói ở đầu. Khi bạn chỉ cần prompt skill này, nó chạy qua cả workflow, từ lập checkpoint cho tới giao feature hoàn chỉnh để bạn review.

Orchestrator chỉ dừng lại chờ bạn hai lần. Một lần sau khi lập kế hoạch checkpoint, để bạn duyệt. Lần nữa khi đã xong, để bạn kiểm tra app và khép lại chu trình. Như vậy agent có thể làm sai dọc đường, nhưng các gate không bao giờ để việc chưa xong lọt qua.

Shopify diễn đạt điều này như sau: một lần thử được phép sai; nó không được phép ship cho tới khi không còn sai nữa (nguyên văn trong bài viết: "An attempt is allowed to be wrong. It is not allowed to ship until it isn't.").

AI LABS nói toàn bộ workflow này bạn có thể tự tạo bằng cách prompt Claude, mô tả task bạn muốn skill thực hiện. Còn các skill nhóm đã tạo trong workflow này nằm trong cộng đồng trả phí AI Labs Pro của kênh. Video kết thúc bằng lời cảm ơn người xem và hẹn gặp ở video sau.