writing-plans

Tổng quan

Kỹ năng writing-plans làm gì

Kỹ năng writing-plans giúp bạn biến một bản đặc tả sản phẩm hoặc tài liệu yêu cầu kỹ thuật thành một kế hoạch hoàn chỉnh, sẵn sàng triển khai trước khi bất kỳ ai đụng vào code. Nó được thiết kế cho các tình huống bạn có một tính năng hoặc thay đổi nhiều bước cần phát hành, và bạn muốn một kế hoạch rõ ràng, đã được phân rã mà một kỹ sư khác có thể làm theo mà không cần bối cảnh từ trước.

Với writing-plans, bạn tạo ra một kế hoạch:

• Giả định người thực thi là một developer có năng lực nhưng mới với codebase và domain của bạn.
• Chỉ rõ các file cần tạo hoặc chỉnh sửa cho từng phần việc.
• Nêu rõ các bài test, cập nhật tài liệu và bước kiểm tra thủ công bắt buộc.
• Chia nhỏ công việc thành các đầu việc nhỏ, có thể ship độc lập với ranh giới rõ ràng.

Điều này giúp việc bàn giao công việc dễ dàng hơn, review kế hoạch thuận tiện hơn, và tránh phình phạm vi hoặc bỏ sót edge case. Nó phản ánh các thực hành như DRY, YAGNI, TDD và commit thường xuyên, nhưng tập trung vào lập kế hoạch dự án và phân rã đầu việc, không phải sinh code.

writing-plans dành cho ai?

Hãy dùng kỹ năng writing-plans nếu bạn là:

• Tech lead và engineering manager cần quy trình lập kế hoạch lặp lại được cho tính năng và refactor.
• Developer cá nhân muốn làm rõ hướng tiếp cận trước khi triển khai các thay đổi rủi ro hoặc cắt ngang nhiều phần hệ thống.
• Các team dùng subagent hoặc làm việc phân tán cần kế hoạch dạng văn bản rõ ràng để phối hợp cộng tác viên.

writing-plans đặc biệt phù hợp khi:

• Bạn có spec hoặc yêu cầu cho một tính năng, migration, hoặc integration.
• Công việc đụng đến nhiều file, component hoặc service.
• Bạn muốn người khác có thể triển khai công việc mà không phải hỏi bạn liên tục.

Không nên dùng khi:

• Bạn vẫn đang brainstorm vấn đề hoặc giải pháp (hãy dùng một kỹ năng ideation/brainstorming trước).
• Đầu việc rất nhỏ (vd: sửa một dòng) và không cần kế hoạch chính thức.
• Bạn chủ yếu tìm code review hoặc sinh code, không phải lập kế hoạch.

Vị trí của writing-plans trong workflow của bạn

Repository giả định writing-plans được dùng sau giai đoạn brainstorming và trong một worktree riêng dành cho dự án. Quy trình thường là:

1. Brainstorm và làm rõ spec (ngoài phạm vi kỹ năng này).
2. Tạo hoặc mở một worktree riêng cho tính năng.
3. Chạy kỹ năng writing-plans để tạo kế hoạch triển khai.
4. Lưu kế hoạch (mặc định) vào:
   • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md
   • hoặc vị trí lưu kế hoạch tùy chọn do bạn định nghĩa.
5. Tuỳ chọn gọi một plan document reviewer subagent dùng template có sẵn để kiểm tra kế hoạch trước khi triển khai.

Cách sử dụng

Cài đặt và thiết lập

1. Cài đặt kỹ năng writing-plans

Bạn có thể cài đặt kỹ năng trực tiếp từ repository obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill writing-plans

Lệnh này sẽ kéo về định nghĩa kỹ năng writing-plans và các prompt hỗ trợ để bạn có thể dùng trong chính dự án của mình.

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

Sau khi cài đặt, hãy xem các file chính này để hiểu và điều chỉnh workflow:

• skills/writing-plans/SKILL.md – Mô tả chính về cách kỹ năng hoạt động, bao gồm phạm vi, cấu trúc kế hoạch và giả định về kỹ sư triển khai.
• skills/writing-plans/plan-document-reviewer-prompt.md – Template prompt tái sử dụng cho một subagent review kế hoạch đã hoàn thành.

Đường dẫn trên máy bạn có thể khác tuỳ cách bạn vendor hoặc mirror repository, nhưng tên file sẽ giống nhau.

Chuẩn bị chạy writing-plans

3. Xác nhận spec và phạm vi

Trước khi dùng writing-plans, hãy đảm bảo bạn có:

• Một bản spec hoặc tài liệu yêu cầu rõ ràng cho tính năng hoặc thay đổi.
• Đủ chi tiết để xác định các component chính, integration và ràng buộc.

Kỹ năng này có bước Scope Check: nếu spec của bạn bao phủ nhiều subsystem độc lập, nó kỳ vọng công việc đã được chia thành các spec sub-project riêng trong giai đoạn brainstorming. Nếu chưa, bạn nên:

• Chia công việc thành các kế hoạch riêng, mỗi subsystem một kế hoạch.
• Đảm bảo mỗi kế hoạch có thể tạo ra phần mềm hoạt động, có thể test độc lập.

Điều này ngăn một kế hoạch trở nên quá cồng kềnh và giúp căn chỉnh công việc với các đơn vị có thể deploy.

4. Chuẩn bị worktree và file kế hoạch

Hướng dẫn upstream giả định bạn:

• Làm việc trong một worktree riêng cho tính năng (đã thiết lập trong giai đoạn brainstorming).

• Lưu kế hoạch triển khai thu được tại:

  • docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Bạn có thể override vị trí này nếu team thích cấu trúc thư mục khác, chẳng hạn docs/plans/ hoặc planning/. Điều quan trọng là kế hoạch được commit vào version control, được version cùng với code và dễ tìm lại sau này.

Chạy kỹ năng và viết kế hoạch

5. Thông báo và bắt đầu phiên lập kế hoạch

Khi bạn gọi kỹ năng hoặc bắt đầu cuộc trò chuyện lập kế hoạch, nên nói rõ:

"I'm using the writing-plans skill to create the implementation plan."

Điều này giúp làm rõ mục tiêu là một kế hoạch triển khai có cấu trúc, không phải khám phá thiết kế hay sinh code.

6. Lập bản đồ cấu trúc file trước

Trước khi liệt kê đầu việc, writing-plans nhấn mạnh phân rã ở cấp độ file:

• Xác định những file sẽ được tạo hoặc chỉnh sửa.
• Gán cho mỗi file một trách nhiệm duy nhất, rõ ràng.
• Thiết kế các đơn vị với interface và ranh giới được định nghĩa tốt.

Ở giai đoạn này, kế hoạch nên trả lời được:

• Logic mới sẽ nằm ở đâu?
• Những file hiện có nào sẽ được chạm tới, và vì sao?
• Các file này tương tác với nhau ở mức độ high-level như thế nào?

Việc chốt cấu trúc file hợp lý từ sớm giúp phân rã đầu việc, review và refactor về sau dễ dàng hơn nhiều.

7. Chia nhỏ công việc thành các đầu việc "bite-sized"

Khi bản đồ file đã rõ, hãy dùng writing-plans để biến spec thành chuỗi đầu việc nhỏ, có thể hiểu độc lập. Hướng dẫn upstream nhấn mạnh:

• Mỗi đầu việc phải có mục tiêu rõ ràng và có thể hành động.
• Đầu việc nên đủ nhỏ để cho phép commit thường xuyên.
• Kế hoạch nên DRY (không lặp chỉ dẫn) và tránh công việc kiểu YAGNI (không làm các bước suy đoán).

Với mỗi đầu việc, kế hoạch nên bao gồm:

• Những file nào sẽ bị tác động.
• Cần thay đổi code hoặc cấu hình ở mức độ high-level ra sao.
• Cần thêm hoặc cập nhật những test nào.
• Bất kỳ tài liệu nào cần cập nhật.

Mục tiêu là một kỹ sư với rất ít bối cảnh vẫn có thể nhặt bất kỳ đầu việc nào và hoàn thành với sự tự tin.

8. Lên kế hoạch cho testing và tài liệu

writing-plans kỳ vọng bạn gắn testing và tài liệu trực tiếp vào kế hoạch:

• Xác định các unit test, integration test hoặc end-to-end test cần thêm hoặc cập nhật.
• Nêu rõ cách chạy test (ví dụ: lệnh, entry point chạy test) khi phù hợp.
• Chỉ định các cập nhật tài liệu cần thiết, như các section README, hướng dẫn người dùng hoặc API docs.

Điều này đảm bảo chất lượng và khả năng bảo trì là phần trung tâm của kế hoạch, không phải phần nghĩ thêm sau cùng.

Review và lặp lại trên kế hoạch

9. Dùng template plan document reviewer (tùy chọn nhưng nên dùng)

File plan-document-reviewer-prompt.md cung cấp một prompt có cấu trúc cho plan document reviewer subagent. Mục đích của nó là:

• Kiểm tra kế hoạch có đầy đủ và khớp với spec không.
• Xác nhận việc phân rã đầu việc có thực tế và có thể triển khai.
• Đảm bảo một kỹ sư có thể triển khai kế hoạch mà không bị tắc.

Template liệt kê các hạng mục để reviewer kiểm tra, bao gồm:

• Completeness – Không còn TODO, placeholder hoặc bước bị thiếu cho các yêu cầu quan trọng.
• Spec Alignment – Kế hoạch bao phủ spec mà không bị phình phạm vi lớn.
• Task Decomposition – Các đầu việc có ranh giới rõ ràng và có thể triển khai.
• Buildability – Một kỹ sư có năng lực có thể làm theo kế hoạch từ đầu đến cuối.

Reviewer được hướng dẫn tập trung vào các vấn đề có thể gây trục trặc thực sự khi triển khai, không sa đà vào câu chữ hay sở thích phong cách.

Bạn có thể tích hợp bước review này vào CI, quy trình review, hoặc review thủ công.

10. Lặp lại dựa trên phản hồi

Nếu reviewer (con người hoặc subagent) phát hiện các vấn đề như thiếu yêu cầu, bước mâu thuẫn hoặc đầu việc quá mơ hồ:

• Cập nhật file kế hoạch với các chỉnh sửa.
• Chạy lại hoặc gọi lại reviewer nếu cần.
• Khi kế hoạch được phê duyệt, hãy coi nó là nguồn sự thật cho việc triển khai.

Điều chỉnh writing-plans cho team của bạn

11. Tuỳ biến cấu trúc và quy ước

Mặc dù kỹ năng upstream định nghĩa hành vi và mặc định khá rõ, bạn có thể điều chỉnh bằng cách:

• Thay đổi vị trí lưu file kế hoạch để khớp với layout của repository.
• Thêm checklist riêng của team (vd: review bảo mật, test hiệu năng) như các đầu việc lặp lại.
• Tích hợp kế hoạch với issue tracker bằng cách map các đầu việc sang ticket.

Vì writing-plans chủ yếu nói về workflow có cấu trúc và quản lý dự án, nó phù hợp với nhiều ngôn ngữ lập trình, framework và domain khác nhau.

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

Khi nào tôi nên dùng kỹ năng writing-plans?

Hãy dùng writing-plans bất cứ khi nào bạn có một tính năng, refactor hoặc integration nhiều bước cùng một spec tương đối rõ ràng và bạn muốn một kế hoạch triển khai bằng văn bản mà một kỹ sư khác có thể thực thi mà không cần bối cảnh. Nó đặc biệt hữu ích trước các thay đổi phức tạp đụng đến nhiều file hoặc subsystem.

Khi nào writing-plans không phù hợp?

writing-plans không lý tưởng khi:

• Bạn vẫn đang mò mẫm giải pháp và spec còn bất ổn.
• Khối lượng công việc quá nhỏ đến mức một kế hoạch chính thức chỉ làm tăng overhead.
• Bạn chỉ tìm kiếm code generation hoặc code review, chứ không phải phân rã đầu việc và lập kế hoạch dự án.

Trong những trường hợp đó, hãy dùng các kỹ năng tập trung vào brainstorming, thiết kế hoặc coding.

Tôi có bắt buộc phải dùng đường dẫn mặc định docs/superpowers/plans/ không?

Không. Hướng dẫn upstream đề xuất lưu kế hoạch tại:

• docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md

Nhưng cũng nêu rõ rằng ưu tiên của người dùng về vị trí lưu kế hoạch sẽ override mặc định này. Bạn có thể lưu kế hoạch ở bất kỳ thư mục hoặc quy ước đặt tên nào phù hợp với repository và tiêu chuẩn tài liệu của team.

Tôi có thể dùng writing-plans cho dự án không phải code không?

Kỹ năng này được viết với dự án phần mềm và codebase trong đầu, bao gồm mapping file và test. Tuy vậy, các ý tưởng cốt lõi—chia nhỏ công việc thành đầu việc nhỏ, mapping trách nhiệm và kiểm tra tính đầy đủ—có thể được thích ứng cho các workflow kỹ thuật khác. Nó hiệu quả nhất trong bối cảnh có ít nhất một khái niệm về file, test hoặc tài liệu cần cập nhật.

writing-plans giúp onboarding và bàn giao như thế nào?

Vì writing-plans giả định người triển khai có zero context với codebase của bạn và gu thẩm mỹ đáng ngờ, nó khuyến khích bạn:

• Giải thích code nên nằm ở đâu và vì sao.
• Ghi rõ test và tài liệu.
• Loại bỏ mơ hồ trong các đầu việc.

Điều này khiến việc bàn giao cho thành viên mới, contractor hoặc subagent dễ dàng hơn nhiều. Họ có thể làm theo kế hoạch trực tiếp thay vì phải suy ngược ý định từ spec.

writing-plans liên quan thế nào tới các công cụ quản lý dự án?

writing-plans mang tính bổ trợ, không thay thế các công cụ quản lý dự án:

• Nó cung cấp cho bạn một kế hoạch dạng văn bản có cấu trúc giải thích cách triển khai spec ở cấp độ code và file.
• Sau đó bạn có thể map các đầu việc trong kế hoạch sang các công cụ như Jira, GitHub Issues hoặc Linear.

Kỹ năng này nằm ở giao điểm của quản lý dự án, template workflow và viết báo cáo kỹ thuật, mang lại một pattern có thể tái sử dụng cho các kế hoạch triển khai nhất quán.

Tôi có thể chỉ dùng reviewer prompt mà không dùng toàn bộ kỹ năng không?

Có. File plan-document-reviewer-prompt.md có thể được dùng độc lập như một template review cho bất kỳ tài liệu dạng kế hoạch nào. Bạn có thể dùng nó làm prompt cho subagent để:

• Review các kế hoạch viết bằng writing-plans.
• Kiểm tra các kế hoạch tạo ra bởi quy trình hoặc công cụ khác.

Tuy nhiên, bạn sẽ có kết quả nhất quán nhất khi cả bản kế hoạch lẫn bước review đều bám theo workflow của writing-plans.