writing-plans

Tổng quan về skill writing-plans

Skill writing-plans làm gì

writing-plans giúp bạn biến một feature spec hoặc tài liệu yêu cầu thành kế hoạch triển khai chi tiết trước khi bắt đầu code. Nhiệm vụ cốt lõi của skill này không phải là nảy ý tưởng, mà là tạo ra một bản kế hoạch có thể đem đi xây dựng và review được, trong bối cảnh người triển khai có rất ít ngữ cảnh về codebase nhưng vẫn cần chỉ dẫn rõ ràng ở cấp file, các bước test và thứ tự thực hiện công việc.

Ai nên dùng writing-plans

Skill này phù hợp nhất với engineer, tech lead và các workflow do agent điều phối khi đã có yêu cầu được khoanh phạm vi rõ ràng và giờ cần một execution plan cho Requirements Planning. Nó đặc biệt hữu ích khi phần việc trải trên nhiều file, có liên quan đến test và tài liệu, hoặc sẽ được bàn giao cho người khác ngoài tác giả ban đầu của spec.

Nhu cầu thực sự mà skill này giải quyết

Người dùng writing-plans thường muốn giảm tối đa việc phải đoán mò khi triển khai. Giá trị của nó không chỉ là “lập kế hoạch”, mà là “lập một kế hoạch đủ rõ để một engineer có năng lực có thể làm theo mà không vướng các giả định ẩn”. Điều đó bao gồm file nào cần chỉnh, cách chia việc thành các task nhỏ dễ xử lý, cần test gì, và nên tách scope ở đâu trước khi bắt đầu triển khai.

Điểm khác biệt của skill này so với một prompt chung chung

writing-plans skill có những quan điểm rõ ràng ở đúng những chỗ quan trọng:

• ép kiểm tra scope trước khi phân rã công việc
• yêu cầu map trách nhiệm của từng file trước khi viết task
• ưu tiên các bước nhỏ, có thể test được thay vì các phase lớn bao quát
• giả định người triển khai có ít ngữ cảnh về domain
• kèm theo reviewer prompt để kiểm tra xem kế hoạch có thực sự khả thi để triển khai hay không

Vì vậy, nó mạnh hơn hẳn kiểu prompt một dòng như “write me an implementation plan” nếu bạn quan tâm đến chất lượng bàn giao.

Khi nào writing-plans đặc biệt phù hợp

Hãy dùng writing-plans khi bạn có:

• một spec, ticket hoặc tài liệu yêu cầu bằng văn bản
• một thay đổi gồm nhiều bước với chi tiết triển khai đáng kể
• nhu cầu phối hợp giữa code, test và tài liệu
• một repository nơi ranh giới giữa các file và thứ tự thực hiện là yếu tố quan trọng

Nếu bạn chỉ cần một dàn ý nhanh hoặc ước lượng sơ bộ, skill này có thể nặng hơn mức cần thiết.

Cách dùng skill writing-plans

Bối cảnh cài đặt writing-plans

Repository này không cung cấp installer riêng ở cấp package ngay bên trong skill, nên cách writing-plans install thực tế là thêm bộ skill cha rồi gọi skill này từ đó:

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

Nếu môi trường của bạn dùng một skill loader khác, hãy cài collection obra/superpowers rồi chọn writing-plans từ skills/writing-plans.

Nên đọc các file này trước

Để đánh giá nhanh, hãy bắt đầu với:

• skills/writing-plans/SKILL.md
• skills/writing-plans/plan-document-reviewer-prompt.md

SKILL.md mô tả workflow lập kế hoạch thực tế. Reviewer prompt cho bạn thấy chuẩn chất lượng mà kế hoạch phải đạt, rất hữu ích trước khi bạn quyết định dùng skill này trong môi trường production.

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

writing-plans usage cho kết quả tốt nhất khi bạn cung cấp:

• spec hoặc yêu cầu nguồn
• repository đích hoặc khu vực codebase liên quan
• mọi ràng buộc về kiến trúc, công cụ, deadline hoặc backward compatibility
• nơi bạn muốn lưu output của kế hoạch nếu không dùng mặc định
• liệu công việc có nên tách thành nhiều kế hoạch độc lập hay không

Nếu không có spec thực sự, skill thường vẫn tạo ra cấu trúc có vẻ hợp lý nhưng phần hướng dẫn triển khai sẽ yếu hơn.

Bắt đầu bằng câu thông báo bắt buộc

Hướng dẫn upstream yêu cầu agent phải thông báo rõ:

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

Nếu bạn tích hợp skill này vào một agent workflow, hãy giữ nguyên câu đó. Nó giúp việc gọi skill trở nên rõ ràng và giảm nhập nhằng về chuẩn lập kế hoạch đang được áp dụng.

Dùng trước khi code, lý tưởng nhất là trong một worktree riêng

Skill này được thiết kế cho giai đoạn lập kế hoạch trước triển khai và giả định nó chạy trong một worktree riêng được tạo từ upstream bởi một brainstorming workflow. Kể cả khi bạn không dùng đúng thiết lập companion đó, ý đồ vẫn rất quan trọng: hãy lập kế hoạch trong một ngữ cảnh tách biệt trước khi sửa code, để bản kế hoạch là một artifact có chủ đích chứ không phải sản phẩm phụ phát sinh trong lúc code.

Cách biến một mục tiêu thô thành prompt tốt hơn

Prompt yếu:

• “Make a plan for adding billing.”

Prompt tốt hơn:

• “Use the writing-plans skill to create an implementation plan for adding team billing to our SaaS app. Spec: docs/specs/team-billing.md. Repo areas likely involved: apps/web, services/billing, db/schema. Constraints: Stripe is already used for individual billing, do not break existing subscriptions, include migration and rollback considerations, and call out tests and docs. If the spec spans independent subsystems, propose separate plans.”

Vì sao cách này hiệu quả:

• nêu rõ spec
• chỉ ra các file hoặc module có khả năng liên quan
• nêu các ràng buộc ảnh hưởng trực tiếp đến cách phân rã công việc
• cho phép tách scope thay vì ép dồn vào một kế hoạch quá lớn

Hãy đi đúng trình tự lập kế hoạch của skill writing-plans

Một writing-plans guide tốt nên đi theo đúng thứ tự ngầm định trong repository:

1. kiểm tra xem spec có nên tách thành nhiều kế hoạch riêng hay không
2. map file với trách nhiệm trước khi chia nhỏ task
3. viết các task triển khai nhỏ, dễ xử lý
4. thêm test, tài liệu và các bước xác thực
5. review kế hoạch đã hoàn thành đối chiếu lại với spec

Bỏ qua bước cấu trúc file là cách phổ biến nhất dẫn đến các task mơ hồ.

Output tốt của writing-plans nên có gì

Một kế hoạch tốt từ writing-plans for Requirements Planning thường nên bao gồm:

• mục tiêu của kế hoạch và spec được liên kết
• các file cần tạo mới hoặc chỉnh sửa
• lý do mỗi file tồn tại hoặc cần thay đổi
• các task đủ nhỏ để có thể hoàn thành và kiểm chứng độc lập
• hướng dẫn test, không chỉ riêng các bước code
• cập nhật tài liệu hoặc migration nếu có liên quan
• đủ chi tiết để một engineer khác không bị khựng lại khi thực hiện

Nếu output chủ yếu chỉ là các phase theo chủ đề như “backend”, “frontend”, “QA”, thì gần như chắc là vẫn còn quá thô.

Vị trí lưu kế hoạch mặc định và khi nào nên đổi

Skill này gợi ý lưu kế hoạch tại:

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

Hãy override khi repo của bạn đã có quy ước lập kế hoạch sẵn, chẳng hạn docs/plans/ hoặc specs/implementation/. Điều quan trọng là tính nhất quán và dùng một đường dẫn để reviewer có thể tìm lại về sau.

Cách dùng reviewer prompt

Sau khi soạn xong kế hoạch, hãy dùng plan-document-reviewer-prompt.md như một template review vòng hai. Các tiêu chí review của nó rất thực tế:

• độ đầy đủ
• mức độ bám sát spec
• chất lượng phân rã task
• khả năng triển khai thực tế

Đây là một điểm khác biệt hữu ích của writing-plans skill: nó không dừng ở bước tạo nội dung, mà còn cho bạn một bước kiểm tra chấp nhận nhẹ nhưng đủ thực dụng cho chính artifact kế hoạch đó.

Workflow thực tế hoạt động hiệu quả

Một workflow đáng tin cậy thường trông như sau:

1. thu thập spec và ngữ cảnh repo
2. chạy writing-plans
3. kiểm tra xem việc tách kế hoạch đã đúng chưa
4. rà lại ranh giới file và độ mịn của task
5. chạy reviewer prompt cho kế hoạch
6. chỉnh sửa kế hoạch trước khi bắt đầu triển khai

Với cách này, skill phát huy giá trị tốt nhất như một cổng kiểm soát ở khâu planning, chứ không chỉ là công cụ hỗ trợ viết cho nhanh.

Câu hỏi thường gặp về skill writing-plans

writing-plans có phù hợp với người mới không?

Có, miễn là người mới đã có một spec đủ cụ thể. Skill này bù đắp việc thiếu ngữ cảnh về codebase bằng cách buộc phải nêu rõ file liên quan và hướng dẫn test. Nó kém hữu ích hơn khi vấn đề thật sự nằm ở chỗ tư duy sản phẩm vẫn còn mơ hồ.

Nó khác gì so với việc chỉ nhờ AI viết implementation plan?

Các prompt chung thường tạo ra bản kế hoạch trau chuốt nhưng nông. writing-plans hữu ích hơn vì nó đẩy mạnh việc phân rã ở cấp file, khả năng test được và chất lượng bàn giao cho người triển khai. Điều này thường giúp giảm việc phải làm lại khi bắt tay vào code.

Khi nào không nên dùng writing-plans?

Hãy bỏ qua nếu:

• thay đổi quá nhỏ và cục bộ
• bạn vẫn đang quyết định scope sản phẩm
• bạn cần khám phá kiến trúc hơn là lập kế hoạch thực thi
• công việc mang tính thử nghiệm cao và gần như chắc sẽ đổi ngay

Trong những trường hợp đó, vài ghi chú gọn nhẹ có thể phù hợp hơn một kế hoạch chính thức.

Nó có yêu cầu stack hoặc framework cụ thể không?

Không. Skill này định hướng theo quy trình chứ không phụ thuộc framework. Lời khuyên của nó dùng được trên nhiều stack vì tập trung vào cách phân rã công việc, trách nhiệm file, test và khả năng review.

writing-plans có xử lý được spec lớn không?

Có, nhưng chỉ khi bạn tôn trọng bước kiểm tra scope. Nguồn gốc của skill nói rất rõ rằng nhiều subsystem độc lập thường nên được tách thành các kế hoạch riêng. Nếu bạn cố nhồi thành một kế hoạch khổng lồ, chất lượng task gần như chắc chắn sẽ giảm.

Chỉ riêng writing-plans đã đủ cho Requirements Planning chưa?

Với Requirements Planning thiên về triển khai, thường là đủ. Với yêu cầu ở giai đoạn discovery thì chưa. Skill này giả định bạn đã biết cần xây cái gì và giờ cần một lộ trình đáng tin cậy để bắt tay vào làm.

Cách cải thiện skill writing-plans

Cung cấp ngữ cảnh repository mạnh hơn

Cách dễ nhất để cải thiện kết quả của writing-plans là nêu rõ các thư mục, module hoặc file có khả năng liên quan. Skill này muốn map trách nhiệm file từ sớm; nếu bạn đưa ra trước các điểm chạm có khả năng xảy ra, output sẽ cụ thể hơn và bớt chung chung hơn nhiều.

Tách các subsystem độc lập ngay từ đầu

Nếu spec của bạn trộn nhiều mối quan tâm không liên quan trực tiếp, hãy tách chúng trước khi yêu cầu một kế hoạch cuối cùng. Ví dụ:

• thay đổi auth
• thay đổi billing
• thay đổi admin UI

Chúng có thể cùng nằm trong một đợt phát hành ở góc độ sản phẩm, nhưng vẫn nên có kế hoạch riêng nếu có thể triển khai và test độc lập.

Yêu cầu map trách nhiệm file một cách tường minh

Nếu bản nháp đầu tiên còn mơ hồ, hãy yêu cầu:

• “List each file to add or modify and state its responsibility before writing tasks.”

Cách này bám rất sát cấu trúc của skill và thường xử lý được tình trạng phân rã công việc còn mờ.

Ép độ hạt task nhỏ hơn

Một lỗi phổ biến là task quá lớn để triển khai an toàn. Hãy yêu cầu:

• task phải tạo ra tiến độ có thể test được
• mỗi task có ranh giới rõ ràng
• có bước xác thực cụ thể sau mỗi thay đổi lớn

Đây là điểm writing-plans usage cải thiện rõ nhất: task nhỏ hơn sẽ dễ review, dễ giao việc và dễ thực thi hơn.

Biến yêu cầu test thành thứ cụ thể

Đừng chỉ yêu cầu “include tests”. Thay vào đó, hãy chỉ rõ:

• cấp độ test nào là quan trọng
• những test suite hiện có nào cần cập nhật
• có cần migration, integration hoặc regression check hay không

Skill vốn đã coi trọng test, nhưng các ràng buộc tốt hơn sẽ làm kế hoạch hữu ích hơn rất nhiều.

Nâng chất bản nháp đầu bằng vòng lặp chỉnh sửa theo reviewer

Hãy dùng reviewer template như một công cụ biên tập, không chỉ là cổng kiểm cuối cùng. Sau bản kế hoạch đầu tiên, hãy hỏi:

• còn thiếu yêu cầu nào từ spec không
• task nào chưa đủ actionable
• chỗ nào người triển khai có thể bị mắc lại
• có dấu hiệu scope creep không

Cách này thường tạo ra bản nháp thứ hai sắc nét hơn nhiều so với các prompt kiểu chung chung như “improve the plan”.

Để ý các lỗi thường gặp này

writing-plans skill yếu đi khi:

• spec chưa hoàn chỉnh
• ranh giới file chỉ là phỏng đoán, không bám vào repo thực tế
• task chỉ mô tả kết quả mà không có bước triển khai
• có nhắc đến test nhưng không gắn với thay đổi code cụ thể
• một kế hoạch quá lớn che lấp nhiều deliverable độc lập

Nếu gặp các dấu hiệu này, hãy sửa lại đầu vào trước khi vội kết luận skill có vấn đề.

Thêm các ràng buộc làm thay đổi lựa chọn triển khai

Những ràng buộc hữu ích bao gồm:

• yêu cầu backward compatibility
• kỳ vọng về hiệu năng
• độ an toàn của migration
• thứ tự triển khai lên môi trường
• nghĩa vụ cập nhật tài liệu
• quy định không thêm dependency mới

Các chi tiết này giúp writing-plans for Requirements Planning tạo ra kế hoạch phù hợp với môi trường của bạn, thay vì một phương án lý tưởng nhưng quá chung.

Đối chiếu kế hoạch với nhu cầu bàn giao thực tế

Tiêu chí đánh giá đúng rất đơn giản: một engineer khác có ít ngữ cảnh liệu có thể triển khai từ tài liệu này mà không phải liên tục hỏi lại hay không? Nếu chưa, hãy tiếp tục cải thiện kế hoạch cho đến khi lựa chọn file, ranh giới task và các bước xác thực đều đã rõ ràng.

Giữ kế hoạch gọn, không lặp và tập trung vào triển khai

Hướng dẫn gốc nhấn mạnh DRY, YAGNI, TDD và commit thường xuyên. Trong thực tế, điều đó có nghĩa là loại bỏ các task trùng lặp, tránh công việc mang tính suy đoán và ưu tiên các bước tăng dần có thể code và kiểm chứng nhanh. Những nguyên tắc này ảnh hưởng đến chất lượng output nhiều hơn là chỉ thêm thật nhiều diễn giải.