subagent-driven-development

Tổng quan về skill subagent-driven-development

subagent-driven-development thực sự làm gì

Skill subagent-driven-development là một quy trình để triển khai một kế hoạch thực thi bằng cách tách công việc thành các tác vụ độc lập, giao từng tác vụ cho một subagent mới, rồi rà soát mọi kết quả theo hai lượt: kiểm tra bám sát spec trước, đánh giá chất lượng code sau. Giá trị thực của nó không nằm ở chuyện “dùng nhiều agent hơn”, mà ở việc chủ động cô lập ngữ cảnh để mỗi worker chỉ nhận đúng tác vụ, yêu cầu và phần code context cục bộ mà nó cần.

Khi nào skill này phù hợp nhất

subagent-driven-development skill phù hợp nhất với những ai đã có sẵn kế hoạch và cần biến kế hoạch đó thành phần triển khai đáng tin cậy ngay trong phiên làm việc hiện tại. Skill này đặc biệt hợp khi:

• các tác vụ phần lớn là độc lập
• bạn muốn agent điều phối chỉ tập trung vào orchestration
• bạn muốn bắt được cả lệch yêu cầu lẫn code cẩu thả
• bạn cần một vòng review lặp lại được, thay vì chỉ một prompt viết code dùng một lần

Bài toán mà skill này giải quyết

Người dùng tìm đến subagent-driven-development for Agent Orchestration khi kiểu prompt thông thường như “hãy triển khai kế hoạch này” bắt đầu hỏng theo những cách rất dễ đoán: agent trộn nhiều việc vào với nhau, quên ràng buộc, làm quá tay, hoặc sinh ra code nhìn có vẻ ổn nhưng lại lệch spec. Skill này đưa ra một mẫu bàn giao-và-review có kỷ luật để giảm những lỗi đó.

Điểm khác biệt so với một prompt chung chung

Những khác biệt quan trọng của skill này đều rất thực dụng:

• Fresh subagent per task thay vì một agent chạy dài mang theo lịch sử ngữ cảnh bị nhiễu
• Explicit task packets với toàn bộ nội dung task được dán thẳng vào prompt, thay vì bắt worker tự suy ra yêu cầu từ nhiều file rải rác
• Mandatory questions before coding để các chỗ chưa rõ lộ ra sớm
• Two-stage review tách riêng câu hỏi “có làm đúng spec không?” khỏi “code có tốt không?”

Sự tách bạch này rất quan trọng. Nhiều team review chất lượng trước khi xác minh phạm vi, khiến những phần làm thừa hoặc làm thiếu khó bị phát hiện hơn.

Khi nào không nên chọn skill này

Đừng bắt đầu với subagent-driven-development nếu bạn chưa có một kế hoạch triển khai đủ cụ thể, nếu các tác vụ phụ thuộc nhau quá chặt, hoặc nếu phần việc đó thực ra nên nằm trong một luồng thực thi song song tách khỏi phiên hiện tại. Trong các tình huống đó, bước lập kế hoạch hoặc một skill thực thi khác thường sẽ là điểm khởi đầu tốt hơn.

Cách dùng skill subagent-driven-development

Cài đặt skill subagent-driven-development

Nếu bạn cài skill từ repository này qua Skills CLI, dùng:

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

Sau đó hãy mở skill đã cài cùng các prompt template hỗ trợ trước khi chạy lần đầu.

Hãy đọc các file này trước

Để vào việc nhanh, hãy đọc các file theo thứ tự sau:

1. SKILL.md
2. implementer-prompt.md
3. spec-reviewer-prompt.md
4. code-quality-reviewer-prompt.md

Trình tự này giúp bạn nắm workflow trước, rồi mới đi vào đúng hình dạng prompt dành cho implementer và hai bước review.

Hiểu rõ calling pattern trước khi bắt đầu

Trong thực tế, subagent-driven-development usage không phải là một lệnh thần kỳ duy nhất. Bạn dùng nó bằng cách đóng vai trò coordinator:

1. lấy một task từ plan
2. dispatch một implementer subagent mới với prompt có phạm vi rất chặt
3. yêu cầu subagent báo cáo lại
4. chạy spec reviewer trên chính phần code đã thay đổi
5. chỉ khi spec đạt mới chạy code quality reviewer
6. chấp nhận, yêu cầu chỉnh sửa, hoặc dispatch lại

Nếu bạn bỏ qua các cổng review này thì thực chất bạn không còn dùng skill theo đúng thiết kế nữa.

Skill này cần đầu vào gì

Hãy chuẩn bị các đầu vào sau trước khi dispatch bất kỳ subagent nào:

• nguyên văn task từ plan
• acceptance criteria hoặc requirements
• bối cảnh kiến trúc liên quan
• working directory hoặc phạm vi repo
• mọi ghi chú về dependency hoặc thứ tự thực hiện
• baseline commit hoặc SHA để review diff
• số thứ tự task và tên task để tiện trace

Các template gốc ngầm cho thấy khá rõ rằng bạn nên dán toàn bộ task vào prompt, chứ không nên bảo subagent “tự đi đọc file plan”.

Biến một mục tiêu thô thành prompt implementer mạnh hơn

Một prompt yếu thường kiểu:

• “Implement task 4 from the plan.”

Một prompt subagent-driven-development guide mạnh hơn nên có:

• Task title and number
• Full task text
• Why this task exists
• Where in the repo to work
• Constraints on file structure
• Whether tests are required
• What to do if assumptions become necessary
• A requirement to ask questions before coding

Cấu trúc này rất quan trọng vì skill được xây quanh ý tưởng kiểm soát ngữ cảnh, chứ không phải để agent tự diễn giải toàn bộ repo theo ý nó.

Ví dụ về một task packet tốt hơn

Khi dispatch implementer, hãy dùng cấu trúc kiểu sau:

• Task N: [name]
• FULL TEXT of task from plan
• Context: where this fits, dependencies, architecture
• Work from: [directory]
• Requirements: implement exactly what is specified
• If anything is unclear, ask before starting
• Write tests if required by task
• Commit, self-review, and report back

Cách này đáng tin cậy hơn nhiều so với việc bảo worker tự đi khám phá rộng khắp, vì skill mặc định rằng coordinator phải chịu trách nhiệm đóng gói đầu bài cho tốt.

Vì sao review spec phải diễn ra trước review chất lượng trong subagent-driven-development

Đây là một trong những điểm đáng giá nhất khi cân nhắc subagent-driven-development install: thứ tự này là có chủ đích.

Hãy chạy spec reviewer trước để trả lời:

• code có triển khai đúng thứ được yêu cầu không?
• có bỏ sót yêu cầu nào không?
• có thêm phần việc không được yêu cầu không?
• có hiểu sai task không?

Chỉ sau đó mới nên chạy code quality reviewer để kiểm tra maintainability, cách decomposition, trách nhiệm của từng file và hình dạng thay đổi. Nếu bạn đảo thứ tự, code nhìn đẹp có thể che mất lỗi về phạm vi.

Cách dùng spec reviewer hiệu quả

Template spec-reviewer-prompt.md rất thẳng tay: nó yêu cầu reviewer không được tin báo cáo của implementer và phải kiểm tra đối chiếu với code thực tế từng dòng. Khi bạn chỉnh sửa template này, hãy giữ nguyên tinh thần đó. Reviewer cần:

• toàn bộ yêu cầu của task
• đầu ra mà implementer tự báo cáo
• quyền truy cập vào phần code đã thay đổi

Mục tiêu ở đây là xác minh độc lập, không phải xác nhận xã giao cho có.

Cách dùng code quality reviewer hiệu quả

Bước review chất lượng code ở đây không phải kiểu soi style chung chung. Trong skill này, trọng tâm là:

• mỗi file có một trách nhiệm rõ ràng
• interface được xác định tốt
• code được tách thành các đơn vị dễ hiểu
• bám sát cấu trúc file đã được định trước
• task này có làm phát sinh file mới quá to hoặc làm file cũ phình lên quá mức hay không

Điểm kiểm tra cuối đặc biệt hữu ích vì subagent rất hay giải bài bằng cách nhét quá nhiều thứ vào một thay đổi duy nhất.

Quy trình subagent-driven-development nên áp dụng trong một repo thực tế

Một vòng subagent-driven-development usage thực tế thường trông như sau:

1. chọn task độc lập tiếp theo
2. chụp lại commit hiện tại làm baseline
3. dispatch implementer với toàn bộ nội dung task
4. thu lại phần tóm tắt và danh sách file đã đổi
5. chạy spec review đối chiếu với yêu cầu và code
6. nếu spec fail, trả lại các thiếu sót cụ thể cho implementer
7. nếu spec pass, chạy code quality review
8. nếu chất lượng không đạt, yêu cầu chỉnh sửa đúng trọng tâm
9. merge hoặc chuyển sang task tiếp theo

Cách này giữ cho coordinator luôn là người kiểm soát thứ tự và tiêu chí chấp nhận.

Những ràng buộc ảnh hưởng trực tiếp đến chất lượng đầu ra

Skill này hoạt động tốt nhất khi bạn tôn trọng đúng ranh giới của nó:

• task độc lập luôn hiệu quả hơn task rối phụ thuộc
• yêu cầu nêu rõ luôn tốt hơn yêu cầu để agent tự suy
• phạm vi repo hẹp tốt hơn kiểu “cứ xem quanh rồi quyết định”
• vòng lặp task ngắn tốt hơn các batch nhiều tính năng lớn
• quy tắc escalation rõ ràng tốt hơn việc tự đoán trong im lặng

Nếu bạn thấy mình cần một subagent phải tự điều hòa quá nhiều thành phần chuyển động trong toàn bộ codebase, thì rất có thể task đó đã quá rộng đối với workflow này.

Lỗi phổ biến khi bắt đầu áp dụng

Sai lầm lớn nhất là gắn nhãn subagent-driven-development skill nhưng vẫn viết prompt lỏng tay. Workflow này chỉ phát huy hiệu quả nếu bạn thực sự đóng gói ngữ cảnh cẩn thận và ép quy trình review đi đúng thứ tự. Nếu không, bạn sẽ chỉ gánh thêm overhead của orchestration mà không nhận lại được mức tăng chất lượng tương xứng.

Câu hỏi thường gặp về skill subagent-driven-development

subagent-driven-development có phù hợp cho người mới bắt đầu không?

Có, miễn là bạn đã hiểu rõ task mình muốn triển khai. Workflow này khá minh bạch và các prompt template đi kèm giúp giảm đáng kể phần phải đoán mò. Nhưng nó không thay thế cho bước lập kế hoạch. Người mới chưa có implementation plan rõ ràng sẽ dễ lúng túng vì skill này giả định rằng định nghĩa task đã tồn tại sẵn.

Khi nào tôi không nên dùng subagent-driven-development?

Hãy bỏ qua subagent-driven-development khi:

• bạn vẫn đang ở giai đoạn khám phá vấn đề
• các task phụ thuộc nhau sâu
• requirements còn thay đổi liên tục
• một người hoặc một agent phải liên tục suy luận trên toàn bộ hệ thống

Đây là một execution pattern, không phải discovery pattern.

Skill này khác gì so với việc chỉ bảo một agent viết hết mọi thứ?

Một prompt dài duy nhất thường trộn cả lập kế hoạch, triển khai, kiểm chứng và review trong cùng một context window. Skill này tách các vai trò đó ra. Điều này thường giúp tăng độ tập trung, dễ phát hiện requirement drift hơn, và giữ ngữ cảnh của coordinator cho orchestration thay vì tiêu hao vào code generation.

Skill này có cần công cụ đặc biệt không?

Không. Trong thư mục skill này không có script đặc biệt nào được đóng gói sẵn. Repository cung cấp các markdown prompt template chứ không phải mã tự động hóa. Bạn có thể áp dụng pattern này ở bất cứ đâu miễn là có thể dispatch subagents và chạy các tác vụ code review.

subagent-driven-development chỉ dành cho dự án lớn phải không?

Không. Nó vẫn dùng được cho thay đổi nhỏ, nhưng giá trị rõ nhất xuất hiện khi một plan có nhiều task độc lập và cái giá của việc bỏ sót yêu cầu đủ lớn để xứng đáng với overhead review.

Trước khi cài, nên nhìn vào bằng chứng nào trong repository?

Với skill này, bằng chứng quan trọng nhất nằm ở thiết kế workflow trong SKILL.md và ba prompt template. Không có helper script hay thư mục resource nào âm thầm làm phần việc cốt lõi, nên quyết định cài đặt của bạn nên tập trung vào việc cấu trúc prompt và kỷ luật review có khớp với cách team bạn ship code hay không.

Cách cải thiện skill subagent-driven-development

Hãy viết task packet tốt hơn, đừng chỉ kéo prompt dài hơn

Muốn cải thiện kết quả của subagent-driven-development skill, hãy tăng độ chính xác thay vì tăng độ dài. Những phần bổ sung hữu ích nhất là:

• acceptance criteria chính xác
• non-goals được nêu rõ
• ghi chú kiến trúc chỉ liên quan đến task này
• ranh giới file hoặc thư mục
• ví dụ về hành vi mong đợi
• kỳ vọng về test

Những chi tiết này giúp implementer tập trung hơn và giúp spec reviewer bắt lệch hướng dễ hơn.

Làm ranh giới task sắc nét hơn

Rất nhiều lỗi đến từ việc chia việc chưa khéo. Nếu một subagent vừa phải điều phối nhiều phần chuyển động, vừa tự quyết kiến trúc, vừa phải suy ra yêu cầu, hãy tách task nhỏ hơn. Task tốt là task đủ hẹp để câu hỏi “đã triển khai đúng chính xác điều được yêu cầu chưa?” có thể được kiểm chứng dễ dàng.

Giữ nguyên bước hỏi trước khi làm

Template implementer nói rất rõ rằng worker phải hỏi lại trước khi bắt đầu, và phải hỏi tiếp nếu trong lúc triển khai xuất hiện bất ngờ. Hãy giữ hành vi này. Triệt tiêu các yêu cầu làm rõ sẽ tạo ra đầu ra nhanh nhưng thiếu tin cậy, đi ngược lại mục tiêu của skill.

Nâng chất lượng review bằng đầu vào so sánh mạnh hơn

Với spec reviewer, hãy cung cấp:

• toàn bộ nội dung requirement
• báo cáo của implementer
• các file đã đổi hoặc phạm vi diff
• mọi loại trừ đã nêu rõ

Với code quality reviewer, hãy cung cấp:

• BASE_SHA
• HEAD_SHA
• tóm tắt task
• phần plan liên quan

Những mốc so sánh cụ thể này giúp review vượt khỏi mức nhận xét cảm tính.

Theo dõi các failure mode thường gặp này

Những vấn đề subagent-driven-development for Agent Orchestration phổ biến nhất là:

• implementer tự suy diễn thêm tính năng
• task packet bỏ sót một ràng buộc quan trọng
• reviewer tin phần tóm tắt của implementer quá nhiều
• code quality review chạy trước spec review
• task quá lớn nên không thể kiểm chứng sạch sẽ
• file phình to mà không được kiểm soát

Tất cả các lỗi này đều có thể phòng tránh bằng cách đóng gói task tốt hơn và siết chặt các cổng kiểm tra.

Lặp lại sau đầu ra đầu tiên

Nếu lượt đầu còn yếu, đừng vội bỏ hết để làm lại từ đầu. Trước hết hãy xác định lớp nào đang hỏng:

• spec failure: yêu cầu mơ hồ, thiếu, hoặc bị làm quá tay
• quality failure: decomposition, maintainability, hoặc cấu trúc file có vấn đề
• coordination failure: cách chia task hoặc đóng gói ngữ cảnh bị sai

Sau đó chỉ chỉnh đúng lớp đó. Cách này giữ cho workflow hiệu quả hơn nhiều.

Siết chặt hướng dẫn về cấu trúc file

Một chi tiết rất hữu ích từ quality template là kiểm tra xem phần triển khai có bám theo cấu trúc file đã định hay không, và các file mới tạo có đang quá lớn ngay từ đầu không. Nếu bạn quan tâm đến maintainability, hãy nêu ranh giới file mong muốn ngay trong task packet thay vì hy vọng reviewer sẽ phát hiện muộn hơn.

Tạo một checklist cục bộ có thể tái sử dụng

Nếu bạn dùng subagent-driven-development thường xuyên, hãy giữ một checklist coordinator ngắn gọn:

• plan đã tồn tại
• task là độc lập
• toàn bộ task đã được dán vào prompt
• đã kèm các ràng buộc
• đã chụp baseline SHA
• implementer được yêu cầu làm rõ trước khi code
• spec review đã hoàn tất
• quality review đã hoàn tất

Thói quen nhỏ này giúp tăng tính nhất quán hiệu quả hơn nhiều so với việc cứ viết prompt dài hơn.

Tinh chỉnh skill cho đúng workflow của riêng bạn

Skill gốc được thiết kế có chủ đích để giữ nhẹ và gọn. Muốn nó hiệu quả hơn trong môi trường của bạn, hãy chỉnh các prompt template theo stack và chuẩn review của team:

• thêm các lệnh test của bạn
• thêm các quy tắc kiến trúc riêng của repo
• định nghĩa rõ thế nào là over-engineering
• chỉ rõ định dạng report bạn muốn
• đưa vào các failure pattern thường gặp trong codebase của bạn

Kiểu tùy biến cục bộ này thường cải thiện subagent-driven-development usage tốt hơn là thêm thật nhiều lý thuyết.