Bắt Đầu Dự Án Mới

Nhận brief từ khách hàng và biến nó thành một skeleton dự án hoạt động được trong cùng ngày — đó là dấu hiệu của một team làm việc tốc độ cao. Với Sun Agent Kit, bạn đưa brief trực tiếp vào toolchain — các quyết định kiến trúc, cấu trúc thư mục, thiết lập CI, và kế hoạch phát triển đều được tạo ra trước khi bạn viết một dòng business logic nào.

Tổng Quan

Mục tiêu: Đi từ brief của khách hàng đến một skeleton dự án đang chạy, có kế hoạch sẵn sàng để phát triển tính năng
Thời gian: 30–60 phút (so với 4–8 giờ thủ công)
Agents sử dụng: planner, reviewer
Commands: /sk:bootstrap, /sk:plan, /sk:scout, /sk:docs

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

Sun Agent Kit đã cài đặt (hướng dẫn cài đặt)
Node.js 18+ hoặc Bun runtime đã sẵn sàng
Một project brief — văn bản thuần, PDF, hoặc URL đến tài liệu spec đều được
Git đã khởi tạo trong thư mục đích (git init)
Thông tin xác thực cho các dịch vụ bên thứ ba được đề cập trong brief (có thể bổ sung sau)

Quy Trình Từng Bước

Bước 1: Bootstrap Skeleton Dự Án

/sk:bootstrap "Node.js REST API for an e-commerce platform — PostgreSQL, Express, JWT auth, product catalog, cart, orders"

Điều gì xảy ra: Agent sẽ:

Phân tích mô tả dự án để xác định tech stack, database và các domain
Tạo cấu trúc thư mục với routes, controllers, services và models
Cài đặt framework và các dependencies
Tạo các file cấu hình (.env.example, tsconfig.json, Dockerfile)
Chạy kiểm tra TypeScript để đảm bảo skeleton biên dịch thành công

Bước 2: Tạo Kế Hoạch Triển Khai

/sk:plan "Three sprints: Sprint 1 auth + catalog, Sprint 2 cart + orders, Sprint 3 payments + admin panel"

Điều gì xảy ra: Agent sẽ:

Đọc cấu trúc codebase đã tạo và xây dựng dependency graph
Viết các file phase cho từng sprint trong thư mục plans/
Chia nhỏ từng phase thành các task và giải quyết các dependency giữa chúng
Xác định critical path và lưu tổng quan vào plans/plan.md

Bước 3: Review Kiến Trúc

/sk:scout "review the generated structure and flag any architectural concerns before development starts"

Điều gì xảy ra: Agent sẽ:

Quét scaffold được tạo và đọc các file dự án
Kiểm tra middleware còn thiếu, thư mục rỗng và các khoảng trống cấu trúc
Đánh dấu các cảnh báo (ví dụ: thiếu rate limiting, thư mục migrations rỗng)
Lưu báo cáo kiến trúc vào plans/reports/scout-report.md

Bước 4: Tạo Tài Liệu Ban Đầu

/sk:docs "generate README, API overview, and local dev setup guide"

Điều gì xảy ra: Agent sẽ:

Đọc các file cấu hình để hiểu thiết lập dự án
Khám phá các route stub và tài liệu hóa các hình dạng request/response dự kiến
Viết README, tổng quan API và hướng dẫn thiết lập dev local
Xác minh các cross-reference nội bộ trong tài liệu được giải quyết đúng

Bước 5: Commit Baseline

/sk:git cm

Điều gì xảy ra: Agent sẽ:

Stage tất cả file dự án, tuân theo .gitignore (.env bị loại trừ tự động)
Viết commit message theo quy ước mô tả scaffold
Tạo commit ban đầu làm baseline cho Sprint 1

Ví Dụ Thực Tế: Khách Hàng Gửi Brief Cho Ứng Dụng E-Commerce

Tình huống: Một khách hàng gửi email brief 2 trang vào chiều thứ Ba. Họ cần một backend MVP cho cửa hàng thời trang trực tuyến: đăng ký người dùng, duyệt sản phẩm, giỏ hàng, thanh toán với Stripe, và một admin panel để quản lý kho hàng. Thời hạn giao là 6 tuần.

Sáng thứ Hai bạn chạy:

# 1. Bootstrap từ văn bản brief (paste hoặc pipe vào)
/sk:bootstrap "E-commerce backend: user auth (email + Google OAuth), product catalog with categories and variants, shopping cart with session persistence, Stripe checkout, order history, admin CRUD for products and orders. Stack: Node.js, Express, PostgreSQL, Redis for sessions."

# 2. Lên kế hoạch theo timeline 6 tuần giao hàng
/sk:plan "6 weeks, 2-week sprints. Sprint 1: auth + catalog. Sprint 2: cart + checkout. Sprint 3: orders + admin."

# 3. Scout để phát hiện vấn đề trước khi team bắt đầu làm ticket
/sk:scout "review generated scaffold for security gaps, missing middleware, and any structural issues"

# 4. Viết docs để khách hàng review
/sk:docs "README with setup instructions, API contract stubs, deployment notes for the client's AWS environment"

# 5. Commit và push
/sk:git cm

Kết quả: Đến giữa buổi sáng, team đã có một skeleton dự án compiling được, một kế hoạch nhiều phase với các task được tổ chức theo từng phase, một báo cáo scout ghi nhận các cảnh báo, và tài liệu sạch mà khách hàng có thể đọc. Việc phát triển tính năng bắt đầu ngay lập tức.

So Sánh Thời Gian

Công việc	Thủ công	Với Sun Agent Kit
Cấu trúc thư mục + file config	1–2 giờ	vài phút
Nghiên cứu + cài dependencies	30–60 phút	vài phút
Kế hoạch sprint + task breakdown	1–2 giờ	vài phút
Review kiến trúc	30–60 phút	vài phút
README + docs ban đầu	30–60 phút	vài phút
Tổng	4–8 giờ	30–60 phút

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

1. Đưa ngôn ngữ domain vào prompt bootstrap ✅

Mô tả càng cụ thể — data model, dịch vụ bên thứ ba, ràng buộc của team — thì scaffold càng chính xác. “Node.js API with Stripe and PostgreSQL” cho kết quả tốt hơn “web backend”.

2. Chạy scout trước khi commit vào kế hoạch ✅

Scout agent đọc skeleton được tạo ra và phát hiện các vấn đề cấu trúc trước khi chúng trở thành technical debt. Chạy nó giữa bootstrap và plan, không phải sau đó.

3. Đừng bỏ qua /sk:plan ngay cả với dự án nhỏ ✅

Ngay cả một dự án 2 tuần cũng được hưởng lợi từ một kế hoạch viết sẵn. Nó vừa là tài liệu onboarding cho đồng đội mới vừa là tài liệu tham chiếu phạm vi cho khách hàng.

4. Đưa một câu mơ hồ vào /sk:bootstrap ❌

/sk:bootstrap "build a website" tạo ra một skeleton chung chung sẽ cần làm lại đáng kể. Dành 10 phút để trích xuất các chi tiết cụ thể từ brief của khách hàng trước.

5. Commit file .env ❌

Lệnh commit của Sun Agent Kit tự động tuân theo .gitignore, nhưng hãy kiểm tra lại trước khi push. Không bao giờ commit thông tin xác thực thật, dù là vào private repo.

Xử Lý Sự Cố

Vấn đề: Bootstrap treo ở bước cài đặt dependency

Giải pháp: Kiểm tra mạng và quyền truy cập npm/bun registry. Nếu cài đặt vẫn thất bại, hãy scaffold dự án trước rồi chạy npm install thủ công sau khi bootstrap hoàn thành.

Vấn đề: File phase trong plan quá chi tiết (100+ task mỗi phase)

Giải pháp: Mô tả sprint của bạn quá rộng. Thu hẹp mỗi sprint xuống 2–3 tính năng chính: /sk:plan "Sprint 1: user registration and JWT auth only".

Vấn đề: Scout report trống

Giải pháp: Scout agent cần ít nhất một số source file để phân tích. Chạy sau khi /sk:bootstrap hoàn thành, không phải trước.

Vấn đề: TypeScript lỗi trong skeleton được tạo ra

Giải pháp: Chạy /sk:fix "fix all TypeScript errors in the generated scaffold" — debugger agent giải quyết các lỗi import và type trong các file được tạo ra.

Bước Tiếp Theo

Tiếp Nhận Dự Án Có Sẵn — dùng khi bạn tiếp nhận từ một team khác thay vì bắt đầu từ đầu
Thêm Tính Năng Mới — bước tiếp theo sau khi scaffold đã sẵn sàng
Xây Dựng REST API — đi sâu hơn về thiết kế API và triển khai endpoint

Điểm mấu chốt: Brief của khách hàng không nên nằm trong hộp thư đến của bạn hơn một giờ — /sk:bootstrap biến nó thành một skeleton dự án compiling được với kế hoạch viết sẵn trong khi bạn uống cà phê.