Tiếp Nhận Dự Án Có Sẵn

Bước vào một codebase 2 tuổi giữa chừng sprint mà không có ghi chú bàn giao nào là chuyện bình thường trong outsourcing. Team trước đã đi rồi, khách hàng đang chờ, và tài liệu duy nhất là một README lỗi thời trỏ đến một server không còn tồn tại nữa. Sun Agent Kit rút ngắn thời gian định hướng của bạn từ vài ngày xuống còn vài giờ bằng cách đọc codebase cho bạn và đưa ra đúng những gì bạn cần biết.

Tổng Quan

Mục tiêu: Hiểu đủ một codebase xa lạ để có thể đóng góp an toàn trong vòng một ngày làm việc
Thời gian: 1–2 giờ (so với 1–2 ngày đọc code thủ công)
Agents sử dụng: scout, researcher, doc-writer
Commands: /sk:scout, /sk:docs, /sk:graphify, /sk:ask

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

• Sun Agent Kit đã cài đặt và xác thực
• Quyền đọc repository (clone về local trước)
• Node.js hoặc runtime của dự án sẵn sàng để xác minh build
• Danh sách các task bạn cần giao đầu tiên (Jira, Linear, hoặc văn bản thường)

Quy Trình Từng Bước

Bước 1: Chạy Scout Ban Đầu

/sk:scout "I'm taking over this project. Give me a full orientation: tech stack, architecture, key modules, entry points, known issues in the code, and anything a new developer needs to know before touching anything."

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

1. Lập chỉ mục repository — file, phân tích ngôn ngữ, và cấu trúc thư mục
2. Vẽ bản đồ kiến trúc bằng cách xác định entry point, service module, và external dependency
3. Phát hiện tín hiệu code health như comment TODO/FIXME, module không có test coverage, và version mismatch
4. Viết báo cáo định hướng đầy đủ vào plans/reports/scout-orientation.md

Bước 2: Xây Dựng Knowledge Graph

/sk:graphify "map how data flows from a user placing an order to the billing module and the notification emails going out"

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

1. Trace call graph cho flow được yêu cầu qua các controller, service, và integration
2. Xác định data contract và đánh dấu bất kỳ sự không nhất quán nào (ví dụ: kiểu field không khớp giữa các service)
3. Tạo Mermaid diagram và lưu báo cáo knowledge graph đầy đủ vào plans/reports/

Bước 3: Tái Tạo Tài Liệu Còn Thiếu

/sk:docs "generate technical documentation for the auth module, the API endpoints, and the database schema — the existing README is outdated"

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

1. Đọc source file cho các module được yêu cầu và migration history
2. Khám phá route handler và document hình dạng request/response của chúng
3. Viết tài liệu về auth flow, API endpoint, và database schema
4. Xác minh endpoint và schema đã document so với source file thực tế trước khi lưu

Bước 4: Đặt Câu Hỏi Có Chủ Đích Về Các Vùng Chưa Quen

/sk:ask "how does the billing retry logic work when a Stripe charge fails? What happens to the order status?"

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

1. Tìm kiếm codebase để tìm các file liên quan và call site liên quan đến câu hỏi
2. Trace execution path end-to-end, bao gồm cả background worker và queue
3. Tổng hợp câu trả lời bằng ngôn ngữ đơn giản với trích dẫn file source để bạn có thể đào sâu vào code trực tiếp
4. Đánh dấu các edge case hoặc khoảng trống nó phát hiện khi trace flow

Bước 5: Hiểu Các Task Đầu Tiên Trong Bối Cảnh

/sk:ask "I need to fix a bug where users aren't receiving order confirmation emails. Walk me through the notification pipeline and where the failure is most likely to be."

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

1. Trace notification pipeline từ trigger event qua queue và worker đến delivery integration
2. Xác định các điểm lỗi có khả năng nhất dựa trên code
3. Trả về danh sách ưu tiên các vị trí cần điều tra, kèm tham chiếu dòng source

Ví Dụ Thực Tế: Bạn Tham Gia Một Dự Án Node.js 2 Năm Tuổi Giữa Sprint

Tình huống: Hôm nay thứ Hai. Vendor dài hạn của một khách hàng vừa offboard. Team bạn tiếp nhận dự án Node.js/React e-commerce. Có 3 ticket sprint đang tiến hành, một QA regression trong module cart, và khách hàng mong đợi một standup vào thứ Tư. Bạn không có context gì cả.

Sáng thứ Hai — 2 giờ để định hướng:

# Quét định hướng toàn diện — đọc báo cáo này trước mọi thứ khác
/sk:scout "complete orientation for a new engineer taking over this project mid-sprint. Tech stack, architecture, critical modules, test coverage gaps, and any time bombs in the code."

# Vẽ bản đồ module cart cụ thể — đó là nơi có regression
/sk:graphify "trace the full data flow through the cart module: add to cart, update quantity, apply coupon, checkout handoff"

# Tái tạo docs rõ ràng đã lỗi thời
/sk:docs "update README with current stack and setup steps, and generate API docs for the cart and checkout routes"

# Trả lời câu hỏi cấp bách nhất
/sk:ask "there's a regression in cart — coupon codes that previously worked are now returning 400. What changed in the cart or coupon service recently and where should I look first?"

Kết quả: Đến trưa thứ Hai bạn đã có một báo cáo định hướng chi tiết, một sơ đồ data-flow của module cart, docs đã được làm mới, và một nguyên nhân gốc rễ có khả năng cao cho regression (một thay đổi schema đã đổi tên column nhưng middleware validation chưa được cập nhật). Bạn bước vào standup thứ Tư đã submit fix xong rồi.

So Sánh Thời Gian

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

1. Chạy scout trước khi chạm vào bất kỳ code nào ✅

Scout cho bạn cái nhìn tổng quan về mọi thứ. Sửa code trước khi bạn hiểu kiến trúc là cách các regression tinh vi bị đưa vào. Luôn định hướng trước.

2. Dùng /sk:graphify cho các flow cụ thể, không phải toàn bộ codebase ✅

Yêu cầu “toàn bộ data flow của ứng dụng” tạo ra một graph quá tải. Hãy thu hẹp phạm vi theo domain: “trace the checkout flow from cart submission to payment confirmation.”

3. Đặt câu hỏi có chủ đích với /sk:ask thay vì đọc file thủ công ✅

Thay vì mở 12 file để hiểu cách retry hoạt động, hãy hỏi bằng ngôn ngữ tự nhiên. Agent trích dẫn dòng source để bạn có thể đào sâu vào code khi cần.

4. Bỏ qua scout để “lao vào luôn” ❌

Lao thẳng vào ticket mà không định hướng dẫn đến logic trùng lặp, giả định sai về data contract, và các bug mất hàng ngày để trace. Thời gian scout sẽ tiết kiệm cho bạn nhiều giờ.

5. Tin tưởng docs được tạo ra mà không tự xác minh một flow chính ❌

Docs được tạo ra chính xác nhưng không phải là không thể sai. Chọn flow quan trọng nhất trong sprint đầu tiên của bạn và trace thủ công để xác minh docs. Khi bạn tin một flow, bạn có thể tin phần còn lại.

Xử Lý Sự Cố

Vấn đề: Scout report rất dài và khó điều hướng

Giải pháp: Yêu cầu một báo cáo con tập trung: /sk:scout "focus only on the auth module and the API layer, skip the frontend". Bạn có thể chạy nhiều scout có phạm vi thay vì một scout khổng lồ.

Vấn đề: /sk:graphify tạo ra sơ đồ trống hoặc không đầy đủ

Giải pháp: Trace phụ thuộc vào import path có thể đọc được. Nếu dự án dùng path alias (như @/services/billing) chưa được resolve trong tsconfig, hãy chạy /sk:ask "list all path aliases in tsconfig and their resolved paths" trước.

Vấn đề: /sk:ask đưa ra câu trả lời tự tin nhưng sai

Giải pháp: Luôn kiểm tra các trích dẫn dòng source trong output câu trả lời. Nếu câu trả lời có vẻ sai, chạy /sk:scout "re-analyze src/services/billing.ts specifically" để đọc lại tập trung vào file.

Vấn đề: Tài liệu được tạo ra không khớp với schema database thực tế

Giải pháp: Việc tạo schema doc đọc migration file. Nếu migration được apply không theo thứ tự hoặc một số bị bỏ qua trong môi trường local, sẽ có sự khác biệt. Chạy /sk:ask "list all migration files and their applied status" để phát hiện sự không nhất quán.

Bước Tiếp Theo

• Sửa Bug Có Hệ Thống — task đầu tiên sau khi onboarding thường là một regression hoặc bug fix
• Thêm Tính Năng Mới — sau khi đã hiểu codebase, thêm vào nó một cách tự tin
• Bắt Đầu Dự Án Mới — cho khi bạn build greenfield thay vì kế thừa brownfield

Điểm mấu chốt: Bạn không nên dành hơn một buổi sáng để đọc code của người khác từ đầu — /sk:scout và /sk:graphify biến hai ngày khảo sát code đau đớn thành hai giờ định hướng có cấu trúc.