Thêm Tính Năng Mới

Một yêu cầu tính năng từ khách hàng xuất hiện trong công cụ quản lý dự án của bạn vào sáng thứ Hai. Đến thứ Sáu nó cần có mặt trên staging. Đó là nhịp điệu của outsourcing — yêu cầu rõ ràng, thời gian chặt chẽ, không có chỗ để code thăm dò. Sun Agent Kit cấu trúc toàn bộ chu trình phát triển tính năng: lên kế hoạch tiếp cận trên codebase thực tế, triển khai từng bước nhỏ đã được xác minh, test, và nhận review trước khi đẩy lên PR.

Tổng Quan

Mục tiêu: Giao một tính năng do khách hàng yêu cầu từ ticket đến code đã review, đã test, sẵn sàng merge
Thời gian: 30–120 phút (so với 4–16 giờ thủ công)
Agents sử dụng: planner, implementer, tester, reviewer
Commands: /sk:plan, /sk:cook, /sk:test, /sk:code-review

Yêu Cầu Trước Khi Bắt Đầu

• Sun Agent Kit đã cài đặt với dự án đã được index trước đó
• Mô tả tính năng rõ ràng — text từ ticket, acceptance criteria, hoặc tin nhắn từ khách hàng đều được
• Dự án compile được và các test hiện tại đang pass trước khi bắt đầu (chạy npm test để xác minh)
• Đã checkout một feature branch (git checkout -b feature/your-feature-name)

Quy Trình Từng Bước

Bước 1: Lên Kế Hoạch Tính Năng Dựa Trên Codebase Thực Tế

/sk:plan "add a dark mode toggle to the user dashboard — persists the preference in the database, applies via a CSS class on the root element, respects the system OS preference on first visit"

Điều gì xảy ra: Agent thực hiện:

1. Phân tích codebase để tìm các component, hook, endpoint, và database table liên quan
2. Viết kế hoạch triển khai với các bước có thứ tự (DB migration, API, hook, UI component)
3. Xác định các file import module bị ảnh hưởng và đánh dấu chúng để kiểm tra
4. Lưu kế hoạch vào plans/ để review trước khi triển khai

Bước 2: Triển Khai Tính Năng

/sk:cook "implement dark mode toggle per the plan in plans/phase-dark-mode.md"

Điều gì xảy ra: Agent thực hiện từng bước theo kế hoạch:

1. Tạo database migration để thêm column mới
2. Cập nhật API endpoint để nhận và lưu field mới
3. Mở rộng frontend hook để hỗ trợ tất cả các mode và kiểm tra các component phụ thuộc
4. Tạo UI component và tích hợp vào layout
5. Chạy typecheck để xác minh không có lỗi compilation

Bước 3: Chạy Test Suite

/sk:test "test the dark mode feature: theme persistence, API endpoint, hook behavior, and the system preference detection"

Điều gì xảy ra: Agent thực hiện:

1. Viết các test case bao gồm API endpoint, hook behavior, và UI component
2. Chạy các test mới cùng với test suite hiện có để kiểm tra regression
3. Báo cáo coverage cho các file đã thay đổi

Bước 4: Yêu Cầu Code Review

/sk:code-review "review the dark mode implementation for code quality, edge cases, and anything I should fix before the PR"

Điều gì xảy ra: Agent thực hiện:

1. Review từng file đã thay đổi về tính đúng đắn của logic, bảo mật, và edge case
2. Đánh dấu các vấn đề tiềm ẩn (ví dụ: FOUC khi server-side render, thiếu loading state)
3. Lưu báo cáo review vào plans/reports/ với các phát hiện được phân loại

Bước 5: Áp Dụng Feedback Review Và Ship

/sk:cook "apply the 2 review fixes: prevent flash of unstyled content on initial render, add loading state to the theme toggle during the PATCH request"

Điều gì xảy ra: Agent áp dụng từng bản fix từ báo cáo review, sau đó chạy lại test suite để xác nhận không có regression.

Ví Dụ Thực Tế: Khách Hàng Muốn Dark Mode Toggle Cho Dashboard

Tình huống: Design team của khách hàng gửi một Figma link và một ticket: “Người dùng đã yêu cầu dark mode. Toggle trong top navbar, lưu vào profile của họ, mặc định theo system preference.” Ticket phải có mặt trên staging vào thứ Năm. Hôm nay là thứ Ba.

Sáng thứ Ba — chu trình tính năng đầy đủ:

# Bước 1: Hiểu những gì đã có trước khi viết bất cứ thứ gì
/sk:scout "what theming or CSS variable infrastructure already exists in this project? Any partial dark mode work? Check the design system, globals.css, and any theme context."

# Bước 2: Lên kế hoạch với context đó
/sk:plan "dark mode toggle: DB persistence to user_preferences, CSS variable-based theming, system preference default, toggle in DashboardLayout navbar, smooth transition on switch"

# Bước 3: Triển khai theo kế hoạch
/sk:cook "implement dark mode per plans/phase-dark-mode.md — follow the plan exactly, don't add anything not in the plan"

# Bước 4: Test kỹ lưỡng — khách hàng sẽ QA trực tiếp
/sk:test "full test coverage for dark mode: API, hook, component, SSR flash prevention, accessibility"

# Bước 5: Review trước PR
/sk:code-review "review dark mode implementation — focus on edge cases: users with no preference set, users switching from system to explicit, the SSR hydration path"

# Bước 6: Commit và push
/sk:git cm "feat: add dark mode toggle with user preference persistence"

Kết quả: Tính năng có mặt trên staging chiều thứ Tư, sớm hơn một ngày so với deadline. Khách hàng review vào sáng thứ Năm và approve. Ước tính thủ công: 2–3 ngày.

So Sánh Thời Gian

Các Thực Hành Tốt Nhất

1. Luôn chạy /sk:scout trước /sk:plan với các vùng chưa quen ✅

Kế hoạch chỉ tốt bằng context đầu vào. Nếu bạn đang thêm vào một module chưa từng đụng, hãy scout nó trước. Một lần scout ngắn ngăn một giờ làm lại khi kế hoạch không tính đến infrastructure đã có sẵn.

2. Giữ prompt cook trong phạm vi kế hoạch ✅

Hãy cho /sk:cook biết để follow file kế hoạch. Nếu bạn mô tả tính năng bằng lời thay vì vậy, nó có thể đưa ra các quyết định kiến trúc khác với kế hoạch đã đề ra — dẫn đến sự lệch lạc giữa kế hoạch và code.

3. Fix feedback review trước khi mở PR ✅

Output của reviewer agent là một cổng trước-PR, không phải commentary tùy chọn. Fix các vấn đề được đánh dấu dù chúng có vẻ nhỏ — các vấn đề “non-blocking” đến tay khách hàng trông như công việc chưa hoàn chỉnh.

4. Để /sk:cook thêm những thứ không được yêu cầu ❌

Nếu kế hoạch nói “thêm theme toggle” mà cook tạo ra một hệ thống theming đầy đủ với 6 file mới, hãy chạy /sk:cook "implement only what is in the plan, nothing extra". Scope creep trong triển khai tạo ra scope creep trong review và testing.

5. Chạy /sk:test sau review fixes ❌ (bỏ qua bước này)

Review fix thay đổi code. Code thay đổi có thể làm hỏng test. Luôn chạy /sk:test sau khi áp dụng review feedback, dù các fix trông có vẻ trivial.

Xử Lý Sự Cố

Vấn đề: /sk:cook lệch khỏi kế hoạch và thêm scope ngoài

Giải pháp: Tham chiếu file kế hoạch rõ ràng và cụ thể: /sk:cook "implement only the steps in plans/phase-dark-mode.md step 2 — nothing else".

Vấn đề: /sk:test viết test mock tất cả mọi thứ và không test gì có ý nghĩa

Giải pháp: Hướng dẫn test agent: /sk:test "write integration tests that test the actual database write and read for theme preference — no mocking the DB layer".

Vấn đề: /sk:code-review đánh dấu một vấn đề nhưng không gợi ý cách fix

Giải pháp: Hỏi trực tiếp: /sk:ask "how should I fix the FOUC issue flagged in plans/reports/review-dark-mode.md — what's the standard pattern for this in Next.js?".

Vấn đề: Tính năng hoạt động ở local nhưng fail trong CI build

Giải pháp: Chạy /sk:fix "CI build failing after dark mode feature — error: [paste error]". Agent xử lý sự khác biệt môi trường giữa local và CI.

Bước Tiếp Theo

• Sửa Bug Có Hệ Thống — cho khi một tính năng gây ra regression cần điều tra có cấu trúc
• Xây Dựng REST API — khi tính năng yêu cầu xây dựng một API layer mới trước
• Triển Khai Xác Thực — cho các tính năng phụ thuộc vào identity người dùng và phân quyền

Điểm mấu chốt: Tính năng không trượt deadline vì engineer chậm — chúng trượt vì triển khai không có kế hoạch gặp phải độ phức tạp bất ngờ. /sk:plan loại bỏ bất ngờ trước khi viết một dòng code.