subagent-driven-development

Tổng quan

subagent-driven-development là gì?

subagent-driven-development là một kỹ năng điều phối agent để chạy một kế hoạch triển khai dưới dạng chuỗi các tác vụ độc lập, mỗi tác vụ được xử lý bởi một subagent mới. Với mỗi tác vụ, bạn sẽ:

1. Khởi tạo một subagent implementer chuyên trách.
2. Chạy một subagent spec compliance reviewer.
3. Chạy một subagent code quality reviewer.

Cả ba được giữ trong một phạm vi ngữ cảnh được kiểm soát chặt chẽ để chỉ tập trung vào tác vụ hiện tại, trong khi phiên chính của bạn vẫn được giữ trống để điều phối và ra quyết định.

Kỹ năng này dành cho ai?

subagent-driven-development được thiết kế cho các lập trình viên và đội ngũ:

• Đang dùng AI coding assistant (như Claude / claude-code) và muốn kết quả đáng tin cậy hơn.
• Làm việc từ một kế hoạch triển khai đã được viết thành các tác vụ riêng biệt.
• Cần một quy trình có cấu trúc, lặp lại được để triển khai và review mã trong một phiên AI duy nhất.
• Quan tâm cả đến tính đúng spec lẫn chất lượng mã, chứ không chỉ "chạy được là được".

Kỹ năng này đặc biệt phù hợp với quy trình làm việc xoay quanh GitHub, nơi bạn có thể truyền SHAs, file kế hoạch và diff vào các subagent.

Kỹ năng này giải quyết vấn đề gì?

Kỹ năng này xử lý các vấn đề thường gặp khi dùng một AI agent duy nhất cho toàn bộ quy trình phát triển end‑to‑end:

• Phình to ngữ cảnh: Một agent tích lũy quá nhiều lịch sử và mất tập trung.
• Lệch spec: Việc triển khai dần dần lệch khỏi kế hoạch hoặc yêu cầu ban đầu.
• Review yếu: Cùng một ngữ cảnh vừa viết mã vừa tự review, dễ bỏ sót lỗi.

subagent-driven-development áp dụng một pattern rõ ràng: agent mới cho mỗi tác vụ, ngữ cảnh chặt chẽ, và review hai bước (spec rồi đến quality). Điều này cải thiện độ đúng đắn, giữ phạm vi thay đổi nhỏ gọn, và giúp bạn dễ suy luận hơn về từng bước trong kế hoạch triển khai.

Khi nào subagent-driven-development phù hợp?

Hãy dùng kỹ năng này khi:

• Bạn đã có một kế hoạch triển khai được chia thành các tác vụ.
• Các tác vụ phần lớn là độc lập – không cần phải điều phối chéo liên tục.
• Bạn dự định hoàn thành kế hoạch trong phiên hiện tại, không trải dài nhiều ngày.

Nếu bạn chưa có kế hoạch, hoặc các tác vụ phụ thuộc chặt chẽ và thay đổi nhanh, có thể bạn nên:

• Brainstorm hoặc thiết kế kế hoạch trước bằng các kỹ năng khác hoặc tự lên kế hoạch thủ công.
• Dùng một quy trình tự do hơn với một agent duy nhất cho giai đoạn khám phá.

Cách sử dụng

Cài đặt

1. Thêm kỹ năng vào môi trường của bạn

Cài đặt kỹ năng subagent-driven-development từ repository obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill subagent-driven-development

Lệnh này sẽ tải definition của kỹ năng và các prompt template hỗ trợ vào môi trường đã bật skills, để bạn có thể điều phối subagent cho từng tác vụ trong kế hoạch.

2. Xem các file cốt lõi

Sau khi cài đặt, mở thư mục skill trong repository (hoặc qua trình duyệt skills của bạn) và xem qua:

• SKILL.md – mô tả tổng quan, khi nào nên dùng và workflow cốt lõi.
• implementer-prompt.md – template cho subagent implementer.
• spec-reviewer-prompt.md – template cho subagent spec compliance reviewer.
• code-quality-reviewer-prompt.md – template cho subagent code quality reviewer.

Hãy coi đây là các template để sao chép hoặc điều chỉnh, tích hợp vào tự động hóa hay hệ thống tool của riêng bạn.

Chuẩn bị kế hoạch triển khai

1. Viết hoặc tinh chỉnh danh sách tác vụ

Trước khi dùng subagent-driven-development, hãy chuẩn bị một kế hoạch triển khai với các tác vụ:

• Được giới hạn phạm vi rõ ràng và có thể kiểm thử.
• Phần lớn độc lập với nhau.
• Được mô tả đủ chi tiết để một subagent implementer có thể hành động mà không phải đoán.

Mỗi tác vụ nên có thể copy‑paste nguyên văn vào prompt của implementer dưới dạng “FULL TEXT of task from plan”.

2. Quyết định thư mục làm việc và chiến lược Git

Các prompt template giả định một workflow dựa trên Git và một thư mục làm việc cụ thể:

• Chọn một directory nơi implementer sẽ thao tác.
• Quyết định cách bạn theo dõi thay đổi (ví dụ, BASE_SHA và HEAD_SHA cho mỗi tác vụ).

Bạn sẽ truyền các giá trị này vào prompt của spec reviewer và code quality reviewer để việc review chính xác hơn.

Chạy workflow cho từng tác vụ

1. Khởi tạo một subagent implementer

Với mỗi tác vụ N, tạo một subagent implementer mới sử dụng template trong implementer-prompt.md.

Các điểm chính từ template:

• Implementer được nói rõ: “You are implementing Task N: [task name]”.
• Bạn paste toàn bộ nội dung tác vụ vào phần ## Task Description.
• Bạn điền:
  • Context – tác vụ này nằm ở đâu trong hệ thống của bạn.
  • directory – thư mục nơi cần thay đổi.

Implementer được hướng dẫn phải:

1. Hỏi làm rõ trước khi bắt đầu nếu có điểm nào chưa rõ.
2. Triển khai chính xác những gì tác vụ yêu cầu.
3. Viết và chạy test khi phù hợp.
4. Tự kiểm tra lại việc triển khai.
5. Commit phần công việc.
6. Tạo một báo cáo rõ ràng về những gì đã làm.

Vì bạn tạo subagent mới cho mỗi tác vụ, nó chỉ nhìn thấy ngữ cảnh bạn cung cấp và không kế thừa lịch sử không liên quan từ phiên chính.

2. Chạy review tuân thủ spec

Khi implementer hoàn thành và báo cáo lại, hãy khởi chạy một subagent spec compliance reviewer sử dụng spec-reviewer-prompt.md.

Trong template này bạn:

• Paste yêu cầu của tác vụ vào ## What Was Requested.
• Paste báo cáo của implementer vào ## What Implementer Claims They Built.

Spec reviewer được dặn rõ là không được tin báo cáo của implementer và phải:

• Đọc mã thực tế.
• So sánh từng dòng với yêu cầu.
• Xác định các yêu cầu bị thiếu, phần làm thừa/không mong muốn, và các hiểu nhầm.

Nếu spec reviewer phát hiện vấn đề, bạn lặp lại với implementer (có thể là cùng worker hoặc một subagent mới) để xử lý các thiếu sót trước khi chuyển sang tác vụ tiếp theo.

3. Chạy review chất lượng mã

Sau khi đã qua bước spec compliance, khởi chạy một subagent code quality reviewer sử dụng code-quality-reviewer-prompt.md.

Template này kỳ vọng một mô tả tác vụ theo phong cách code review, ví dụ:

Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from implementer's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]

Reviewer sẽ kiểm tra:

• Độ sạch sẽ và khả năng bảo trì của phần triển khai.
• Trách nhiệm và interface của từng file (mỗi file nên có một trách nhiệm rõ ràng nếu có thể).
• Các file mới hoặc chỉnh sửa có kích thước và mức độ tách nhỏ hợp lý không.
• Độ phủ test và khả năng hiểu, test từng unit một cách độc lập.

Họ trả về feedback có cấu trúc: điểm mạnh, các vấn đề (Critical / Important / Minor), và một đánh giá tổng thể.

Sau đó bạn có thể quyết định:

• Chấp nhận thay đổi như hiện tại.
• Yêu cầu implementer thực hiện các refactor bổ sung.

Điều chỉnh workflow cho môi trường của bạn

1. Tùy biến prompt cho stack của bạn

Các template trong implementer-prompt.md, spec-reviewer-prompt.md và code-quality-reviewer-prompt.md được thiết kế chung chung. Hãy điều chỉnh chúng cho phù hợp với:

• Ngôn ngữ lập trình và framework bạn dùng.
• Quy ước test (ví dụ, pytest, Jest, Go test).
• Cấu trúc và cách đặt tên trong repository của bạn.

Hãy giữ cấu trúc lõi – subagent mới, các section rõ ràng, mô tả nhiệm vụ cụ thể – ngay cả khi bạn tùy biến chi tiết.

2. Tự động hóa các bước lặp lại

Khi đã quen với pattern này, bạn có thể script hoặc tool hóa nó:

• Gói ba lần gọi subagent (implementer → spec reviewer → code quality reviewer) thành một lệnh duy nhất cho mỗi tác vụ.
• Tự động tạo prompt cho từng tác vụ từ file kế hoạch.
• Tự động điền BASE_SHA và HEAD_SHA bằng cách đọc metadata của Git.

Cách này biến subagent-driven-development thành một workflow tự động lặp lại được cho cả đội.

3. Khi nào kỹ năng này không phù hợp

Bạn có thể cần một cách tiếp cận khác khi:

• Các tác vụ phụ thuộc lẫn nhau quá nhiều và không thể tách riêng rõ ràng.
• Bạn chưa có một kế hoạch triển khai rõ ràng.
• Bạn cần công việc dài hạn, kéo dài nhiều phiên, nơi ngữ cảnh phải được giữ trong nhiều ngày.

Trong các trường hợp đó, hãy dùng các kỹ năng hoặc quy trình tập trung vào lập kế hoạch, kiến trúc, hoặc long‑term agent, rồi quay lại subagent-driven-development khi bạn đã sẵn sàng thực thi các tác vụ rời rạc.

Câu hỏi thường gặp (FAQ)

"subagent-driven-development" thực tế nghĩa là gì?

Trong thực tế, subagent-driven-development có nghĩa là bạn không yêu cầu một agent "toàn tri" vừa lập kế hoạch, vừa viết mã, vừa review tất cả. Thay vào đó, bạn:

• Duy trì điều phối và ngữ cảnh tổng thể trong phiên chính.
• Với mỗi tác vụ, tạo một subagent mới với đúng lượng thông tin nó cần.
• Chạy subagent đó để triển khai tác vụ, rồi chạy thêm hai subagent nữa để review.

Cách này tách bạch trách nhiệm, giữ ngữ cảnh ở mức dễ quản lý và tăng độ tin cậy cho từng bước trong kế hoạch triển khai.

Điều này khác gì với một phiên coding bình thường dùng một agent?

Với một agent duy nhất, toàn bộ lịch sử hội thoại và thay đổi mã sẽ dồn vào cùng một ngữ cảnh, dẫn tới:

• Lẫn lộn giữa yêu cầu cũ và mới.
• Các pattern suy luận giống nhau được dùng cho cả việc viết mã lẫn review.

Còn subagent-driven-development thì:

• Dùng prompt và vai trò riêng cho triển khai và review.
• Khởi động mỗi subagent với ngữ cảnh được chọn lọc, không phải toàn bộ lịch sử phiên.
• Áp dụng thứ tự review ưu tiên spec rồi mới đến chất lượng.

Điều này thường cho ra các bản triển khai chính xác hơn và các review thẳng thắn hơn.

Tôi có bắt buộc phải làm đúng y nguyên các template không?

Không. Các template trong repository là ví dụ về cách cấu trúc prompt cho implementer, spec reviewer và code quality reviewer. Bạn được kỳ vọng sẽ:

• Giữ pattern tổng thể: implementer → spec review → quality review.
• Giữ các hành vi quan trọng (ví dụ, spec reviewer phải đọc mã thật và không tin hoàn toàn vào báo cáo).

Trong khung đó, bạn có thể chỉnh câu chữ, thêm hướng dẫn riêng cho dự án, và tích hợp với tool cũng như quy ước của đội.

Tôi có thể dùng subagent-driven-development mà không cần Git không?

Template cho code quality reviewer giả định có các trường như BASE_SHA và HEAD_SHA, rất tự nhiên trong workflow dùng Git. Nếu bạn không dùng Git:

• Bạn vẫn có thể áp dụng cùng các ý tưởng cốt lõi – subagent mới và review hai bước.
• Thay SHAs bằng cách tham chiếu trạng thái trước/sau riêng của bạn (ví dụ, mã số archive hoặc đường dẫn snapshot).

Kỹ năng này không bắt buộc dùng Git; nó chỉ đưa ra các ví dụ định hướng Git.

Kỹ năng này có phụ thuộc vào model AI cụ thể nào không?

Repository không khóa cứng bạn vào một model cụ thể, nhưng rõ ràng nhắm tới các model coding hiện đại, đa dụng như Claude / claude-code của Anthropic. Bạn nên:

• Dùng một model có khả năng đọc và suy luận về mã lẫn test.
• Đảm bảo môi trường của bạn hỗ trợ spawn nhiều subagent với prompt tùy chỉnh.

Nếu stack của bạn hỗ trợ agent tools hoặc task runner, bạn có thể nối những template này vào hệ thống đó.

Làm sao biết nên dùng subagent-driven-development thay vì kỹ năng superpowers khác?

File SKILL.md mô tả các tiêu chí quyết định: dùng subagent-driven-development khi bạn đã có kế hoạch triển khai, các tác vụ phần lớn độc lập, và bạn dự định làm việc trong phiên hiện tại. Nếu một trong các điều này không đúng, bạn có thể:

• Dùng các kỹ năng lập kế hoạch hoặc brainstorming để xây dựng kế hoạch trước.
• Dùng các pattern thực thi hoặc lập kế hoạch khác cho công việc phụ thuộc chặt hoặc kéo dài nhiều phiên.

Tôi nên bắt đầu từ đâu trong repository?

Nếu bạn đang đánh giá có nên cài đặt hoặc áp dụng kỹ năng này, hãy bắt đầu với:

1. SKILL.md – để hiểu lý do tồn tại và workflow ở mức cao.
2. implementer-prompt.md – để xem cách định nghĩa vai trò cho subagent implementer.
3. spec-reviewer-prompt.md – để hiểu cách kiểm tra tuân thủ spec.
4. code-quality-reviewer-prompt.md – để xem các kiểm tra thêm về chất lượng và cấu trúc mã.

Từ đó, bạn có thể tùy biến các template này, tích hợp vào hệ thống điều phối agent hoặc workflow tự động của riêng bạn và khai thác tối đa subagent-driven-development.