finishing-a-development-branch

Tổng quan

Kỹ năng này làm gì

Kỹ năng finishing-a-development-branch giúp bạn hoàn tất an toàn một nhánh development trong Git sau khi công việc đã được triển khai và bộ test đã pass. Nó dẫn bạn qua một quy trình rõ ràng, có thể lặp lại để bạn chọn nên merge cục bộ, push và mở Pull Request, giữ lại nhánh cho lần sau, hay xóa bỏ hoàn toàn nhánh đó.

Nguyên tắc cốt lõi của kỹ năng này rất đơn giản:

Verify tests → Xác định base branch → Hiển thị các lựa chọn → Thực thi lựa chọn → Dọn dẹp

Thay vì gõ lệnh Git ngẫu hứng hoặc quên các bước kiểm tra quan trọng, finishing-a-development-branch cung cấp cho tác nhân (agent) của bạn một checklist nhất quán cho giai đoạn kết thúc của một nhánh feature hoặc bugfix.

finishing-a-development-branch dành cho ai?

• Lập trình viên làm việc với các nhánh Git và muốn có một thói quen “kết thúc nhánh” có cấu trúc
• Các nhóm yêu cầu test phải pass trước khi merge hoặc mở PR
• Người dùng bộ kỹ năng obra/superpowers muốn agent quản lý workflow Git an toàn hơn
• Bất kỳ ai thường xuyên tự hỏi “Nhánh này đã sẵn sàng để merge chưa, và nên tích hợp nó như thế nào?”

Kỹ năng này đặc biệt phù hợp với những repository đã có test tự động và các base branch chuẩn như main hoặc master.

Những vấn đề kỹ năng này giải quyết

• Quên chạy test trước khi merge hoặc mở Pull Request
• Không chắc nhánh feature được tách ra từ nhánh nào
• Quyết định thiếu nhất quán về việc nên merge cục bộ, dùng PR hay bỏ đi phần công việc
• Các nhánh thừa thãi làm rác repository vì không có bước kết thúc rõ ràng

Bằng cách buộc kiểm tra test trước, sau đó đưa ra một tập nhỏ các lựa chọn rõ ràng, finishing-a-development-branch giảm thiểu sai sót và giúp Git workflow của bạn dễ đoán hơn.

Khi nào nên dùng kỹ năng này

Sử dụng finishing-a-development-branch khi:

• Một tính năng hoặc bản sửa lỗi đã được triển khai đầy đủ
• Bạn kỳ vọng tất cả test sẽ pass hoặc muốn chặn việc tích hợp khi test đang fail
• Bạn đã sẵn sàng quyết định nhánh này sẽ được tích hợp như thế nào, hoặc liệu nên bỏ nó đi

Kỹ năng này không phù hợp khi:

• Bạn vẫn đang tích cực code hoặc thử nghiệm trên nhánh
• Repository không có test hữu ích và bạn không thể chạy một bộ test có ý nghĩa
• Bạn cần quản lý release phức tạp với nhiều nhánh vượt quá workflow feature → base branch đơn giản

Nếu nhu cầu chính của bạn là viết code hoặc review thay đổi, hãy kết hợp kỹ năng này với các kỹ năng khác tập trung vào triển khai hoặc review code; finishing-a-development-branch chỉ tập trung vào bước tích hợp cuối cùng.

Cách sử dụng

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

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

Cài finishing-a-development-branch từ repository obra/superpowers bằng Skills CLI:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

Lệnh này giúp kỹ năng khả dụng trong môi trường agent của bạn để nó có thể áp dụng workflow Git được hướng dẫn cho repository hiện tại.

2. Xác nhận điều kiện tiên quyết của repository

Để kỹ năng hoạt động đúng như thiết kế, dự án của bạn nên:

• Là một Git repository với base branch rõ ràng (thường là main hoặc master).
• Có bộ test có thể chạy được, thường thông qua các lệnh như:
  • npm test
  • cargo test
  • pytest
  • go test ./...

Lệnh cụ thể sẽ phụ thuộc vào stack của bạn; kỹ năng giả định rằng tồn tại một lệnh test nào đó và có thể chạy trước khi tích hợp.

3. Thông báo việc sử dụng kỹ năng

Khi bắt đầu quá trình kết thúc nhánh, kỹ năng mong đợi bạn (hoặc agent của bạn) thông báo rõ ràng:

"I'm using the finishing-a-development-branch skill to complete this work."

Điều này giúp workflow minh bạch với cộng tác viên và cho biết quy trình có cấu trúc đang được áp dụng.

Các bước workflow được hướng dẫn

Bước 1: Verify tests

Trước khi đưa ra bất kỳ quyết định tích hợp nào, kỹ năng sẽ chạy hoặc nhắc bạn chạy bộ test của dự án. Các lệnh thường gặp gồm:

npm test
# or
cargo test
# or
pytest
# or
go test ./...

• Nếu test fail: kỹ năng báo số lượng lỗi, hiển thị chi tiết và dừng quy trình. Nó sẽ cho biết không thể tiếp tục merge hoặc tạo PR cho đến khi test pass.
• Nếu test pass: workflow sẽ chuyển sang bước tiếp theo.

Cổng kiểm soát “tests first” nghiêm ngặt này giúp tránh merge hoặc gửi Pull Request với code đang bị hỏng.

Bước 2: Xác định base branch

Tiếp theo, finishing-a-development-branch xác định nhánh mà nhánh development hiện tại được tách ra, sử dụng các lệnh Git như:

git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Nếu không thể tự động xác định base branch, kỹ năng sẽ quay lại hỏi một câu làm rõ, ví dụ:

"This branch split from main - is that correct?"

Việc xác nhận base branch chính xác rất quan trọng vì nó quyết định nơi công việc của bạn sẽ được merge, hoặc PR sẽ target nhánh nào.

Bước 3: Hiển thị các lựa chọn tích hợp

Khi test đã pass và base branch đã được xác định, kỹ năng sẽ đưa ra đúng bốn lựa chọn ngắn gọn:

Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

Các lựa chọn được giữ cố ý ngắn gọn, tránh giải thích rườm rà để bạn có thể chọn nhanh.

Một số cách dùng điển hình:

• Option 1 – Bạn muốn merge nhanh tại local, thường trong các dự án cá nhân nhỏ hoặc khi bạn là maintainer duy nhất.
• Option 2 – Bạn làm việc trong team và cần code review, CI hoặc phê duyệt thông qua nền tảng Git hosting như GitHub.
• Option 3 – Bạn chưa sẵn sàng quyết định, nhưng muốn chắc chắn rằng test đã pass và trạng thái nhánh đã rõ ràng.
• Option 4 – Bạn chỉ thử nghiệm, hoặc hướng tiếp cận đã lỗi thời, và bạn muốn xóa nhánh một cách gọn gàng.

Bước 4: Thực thi lựa chọn

Dựa trên câu trả lời của bạn, kỹ năng sẽ thực hiện các thao tác Git tương ứng và việc dọn dẹp liên quan. Mặc dù SKILL.md gốc lược bớt một số lệnh chi tiết, ý định là:

• Với local merge: checkout sang base branch, merge nhánh development, và tùy chọn xóa nhánh đã hoàn tất nếu phù hợp.
• Với push + PR: push nhánh lên remote và hướng dẫn bạn tạo Pull Request target base branch đã được xác định.
• Với keep as-is: giữ nguyên nhánh hiện tại và ghi chú rõ ràng rằng bạn sẽ tự xử lý việc tích hợp sau.
• Với discard: loại bỏ hoặc xóa nhánh một cách an toàn sau khi xác nhận đó đúng là điều bạn muốn.

Trong suốt bước này, kỹ năng ưu tiên tính nhất quán và an toàn: không merge khi test đang fail, không merge vào nhánh base sai, và tránh mất mát công việc ngoài ý muốn.

Mẹo sử dụng thực tế

Tích hợp vào workflow cá nhân

• Chạy finishing-a-development-branch bất cứ khi nào bạn cho rằng một feature đã “xong”.
• Hãy coi bước kiểm tra test là cổng chất lượng cuối cùng trước khi quyết định merge hay PR.
• Trong môi trường làm việc nhóm, mặc định ưu tiên Option 2 để đảm bảo review và pipeline CI được kích hoạt.

Sử dụng cùng quy ước của team

Nếu team bạn có quy tắc branching và review cụ thể (ví dụ: luôn PR vào develop trước, hoặc không tự động xóa nhánh), hãy điều chỉnh cách bạn chọn các option sao cho phù hợp với những quy tắc đó. Cấu trúc của kỹ năng giúp bạn tuân thủ các chính sách ấy một cách nhất quán hơn.

Kết hợp với các kỹ năng superpowers khác

Trong bộ obra/superpowers, finishing-a-development-branch được thiết kế để bổ trợ cho các kỹ năng hỗ trợ triển khai, refactor hoặc testing. Hãy dùng các kỹ năng kia để phát triển nhánh, sau đó gọi kỹ năng này khi bạn thực sự sẵn sàng tích hợp.

FAQ

Tôi nên chạy kỹ năng finishing-a-development-branch khi nào?

Hãy chạy finishing-a-development-branch khi bạn đã triển khai xong thay đổi, kỳ vọng test sẽ pass và đã sẵn sàng quyết định cách tích hợp nhánh (merge, PR, giữ lại hoặc loại bỏ). Nó được thiết kế làm bước cuối trong vòng đời của nhánh, không phải công cụ hỗ trợ coding hàng ngày.

Nếu test fail thì chuyện gì xảy ra?

Nếu test fail, kỹ năng sẽ báo chi tiết các lỗi và dừng quy trình. Nó sẽ không tiếp tục merge hoặc tạo Pull Request. Bạn cần sửa các test đang fail trên nhánh, chạy lại test, và chỉ sau đó mới gọi finishing-a-development-branch lần nữa.

Tôi có thể dùng kỹ năng này khi không có bộ test tự động không?

Kỹ năng được xây dựng xoay quanh nguyên tắc “verify tests first”. Dù về mặt lý thuyết bạn có thể điều chỉnh để dùng trong dự án không có test, nhưng như vậy là bỏ qua một trong các cơ chế bảo vệ cốt lõi. Để đạt hiệu quả tốt nhất, hãy dùng trong các repository nơi bạn có thể chạy lệnh như npm test, cargo test, pytest hoặc go test ./....

Nó quyết định merge vào nhánh nào như thế nào?

finishing-a-development-branch cố gắng xác định base branch bằng cách dùng merge-base của Git với các tên nhánh phổ biến như main hoặc master. Nếu kết quả không rõ ràng, nó sẽ hỏi bạn xác nhận base branch. Cách làm này giúp merge và Pull Request luôn target đúng nhánh.

Nó có tự động tạo Pull Request không?

Hành vi được mô tả của kỹ năng là “push and create a Pull Request” khi bạn chọn Option 2. Cơ chế cụ thể phụ thuộc vào cách môi trường agent của bạn tích hợp với nền tảng Git hosting. Ở mức tối thiểu, nó sẽ push nhánh của bạn và hướng dẫn bạn mở PR nhắm vào base branch đã được phát hiện.

Nó có tự động xóa nhánh của tôi không?

Mô tả trong SKILL tập trung vào việc đưa ra lựa chọn và thực thi workflow, bao gồm cả dọn dẹp. Hành vi xóa cụ thể có thể phụ thuộc vào cách môi trường của bạn diễn giải bước cleanup. Hãy coi Option 4 (discard this work) là hành động có thể phá hủy dữ liệu và chỉ chọn khi bạn chắc chắn không còn cần nhánh đó.

finishing-a-development-branch có phù hợp với quy trình release phức tạp không?

Kỹ năng này hướng tới các nhánh feature hoặc fix đơn giản, merge trở lại một base branch duy nhất. Nếu bạn quản lý nhiều nhánh release dài hạn, hotfix, hoặc pipeline triển khai phức tạp, bạn vẫn có thể dùng finishing-a-development-branch cho từng nhánh riêng lẻ, nhưng có thể cần thêm quy trình hoặc công cụ khác để bao quát chiến lược release tổng thể.

Làm sao để cài lại finishing-a-development-branch?

Sử dụng Skills CLI trỏ tới repository obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill finishing-a-development-branch

Sau khi cài đặt, hãy làm theo workflow của kỹ năng: chạy test, xác nhận base branch, chọn một option, và để kỹ năng xử lý các bước tích hợp và dọn dẹp.