Di Chuyển Dự Án (Tech Stack)

Tiếp nhận một codebase mà team bạn không thể duy trì là một tình huống outsourcing phổ biến. Team bảo trì của khách hàng thay đổi, và đột nhiên một Django monolith cần trở thành một ứng dụng Laravel — cùng hành vi, khác stack. Rủi ro không phải là việc viết lại; đó là business logic không được tài liệu hóa nằm trong đầu ai đó và biến mất trong quá trình chuyển giao. Sun Agent Kit giải quyết điều này bằng kỷ luật scout-first: ánh xạ mọi thứ trước khi di chuyển bất cứ thứ gì, sau đó migrate từng module với các parity test xác minh hành vi tại mỗi checkpoint.

Tổng Quan

Mục tiêu: Di chuyển dự án từ tech stack này sang tech stack khác mà không mất business logic
Thời gian: 1–3 ngày cho dự án vừa (so với 2–4 tuần thủ công)
Agents sử dụng: scout, planner, implementer, tester, reviewer
Commands: /sk:scout, /sk:brainstorm, /sk:research, /sk:plan, /sk:cook, /sk:test, /sk:code-review, /sk:security-scan, /sk:git

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

  • Sun Agent Kit đã cài đặt (hướng dẫn cài đặt)
  • Codebase nguồn đã được checkout và có thể truy cập local
  • Target stack runtime đã sẵn sàng (ví dụ: PHP 8.2 + Composer cho Laravel)
  • Git đã khởi tạo trong cả thư mục nguồn và thư mục đích
  • Truy cập vào thông tin xác thực dịch vụ bên thứ ba được sử dụng trong dự án nguồn (Stripe keys, API tokens, v.v.)
  • Test suite hiện có hoặc tài liệu API contract cho dự án nguồn (ngay cả coverage một phần cũng hữu ích)

Quy Trình Từng Bước

Bước 1: Scout Codebase Nguồn

/sk:scout "map everything in this Django project: models with fields and relationships, views and API endpoints with request/response shapes, middleware, Celery tasks, Stripe integration, custom authentication logic — generate a complete source inventory"

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

  1. Duyệt qua toàn bộ codebase nguồn, đọc mọi file model, view, serializer và task
  2. Trích xuất các schema model bao gồm loại trường, ràng buộc và quan hệ khóa ngoại
  3. Ánh xạ từng endpoint: URL, HTTP method, hình dạng request body, hình dạng response, status codes
  4. Xác định tất cả background jobs, scheduled tasks và async processing logic
  5. Lưu inventory nguồn hoàn chỉnh vào plans/reports/scout-report.md

Bước 2: Quyết Định Chiến Lược Migration

/sk:brainstorm "given the scout inventory of 15 models and 40+ endpoints with Celery tasks and Stripe: what is the optimal migration strategy? Compare big-bang rewrite vs module-by-module migration. Which modules carry the most risk? What is the optimal migration order?"

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

  1. Đọc inventory scout và nhóm các model và endpoint thành các module logic
  2. Phân tích quan hệ dependency giữa các module để xác định thứ tự migration an toàn
  3. Đánh giá từng module theo rủi ro — độ phức tạp, tích hợp bên ngoài và khoảng trống test coverage
  4. Khuyến nghị phương pháp big-bang vs incremental với lý giải đánh đổi rõ ràng
  5. Xuất ra danh sách module xếp hạng theo rủi ro và trình tự migration đề xuất

Bước 3: Nghiên Cứu Ánh Xạ Framework

/sk:research "Django ORM to Eloquent migration patterns, Celery to Laravel Queues equivalents, Django REST Framework to Laravel API Resources, Stripe SDK differences between Python and PHP, Django middleware to Laravel middleware mapping"

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

  1. Tìm tài liệu hiện tại cho cả framework nguồn và đích
  2. Xác định các tương đương trực tiếp (ví dụ: Django signals → Laravel Events)
  3. Đánh dấu các lĩnh vực không có ánh xạ rõ ràng và cần triển khai tùy chỉnh
  4. Tài liệu hóa sự khác biệt hành vi Stripe SDK giữa Python và PHP clients
  5. Lưu tài liệu tham chiếu ánh xạ framework vào plans/research/ để dùng trong quá trình triển khai

Bước 4: Lên Kế Hoạch Migration Từng Module

/sk:plan "module-by-module migration: Module 1 user management (4 models, 8 endpoints). Module 2 product catalog (5 models, 12 endpoints). Module 3 order processing (4 models, 14 endpoints). Module 4 Stripe integration and background jobs"

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

  1. Tạo file phase cho từng module trong thư mục plans/{timestamp}-django-to-laravel/
  2. Ánh xạ file nguồn sang file đích cho từng module với ownership rõ ràng
  3. Liệt kê mọi business rule phải được giữ nguyên, được rút ra từ inventory scout
  4. Xác định acceptance criteria parity test cho từng module trước khi bắt đầu triển khai
  5. Xác định các dependency cross-module để thứ tự migration được thực thi

Bước 5: Triển Khai Từng Module Một

/sk:cook plans/{timestamp}-django-to-laravel/phase-01-user-management.md

Lặp lại cho từng module. Không bắt đầu module tiếp theo cho đến khi module hiện tại vượt qua parity tests.

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

  1. Đọc kế hoạch phase và phần inventory scout cho module hiện tại
  2. Tạo các Eloquent model với định nghĩa trường và quan hệ giống nhau
  3. Triển khai các API Resource class tạo ra hình dạng response giống với Django serializers
  4. Giữ nguyên toàn bộ business rules, validation logic và định dạng error response
  5. Đánh dấu các pattern Django không có tương đương trực tiếp trong Laravel và đề xuất các giải pháp thay thế

Bước 6: Viết và Chạy Parity Tests

/sk:test "write parity tests for the user management module — verify identical behavior: same endpoints, same response shapes, same status codes, same error messages as the Django version"

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

  1. Đọc cả inventory scout và module Laravel mới được triển khai
  2. Tạo integration tests gọi mọi endpoint với các payload đại diện
  3. Kiểm tra hình dạng response, HTTP status codes và định dạng error message khớp với phiên bản Django
  4. Kiểm tra các edge case được nắm bắt trong inventory scout (ví dụ: phản hồi lỗi validation)
  5. Báo cáo bất kỳ sai lệch hành vi nào dưới dạng failing test với diff expected vs actual

Bước 7: Review Từng Module Đã Migrate

/sk:code-review --pending

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

  1. Đọc checklist business rule của kế hoạch phase đối chiếu với code đã triển khai
  2. Đánh dấu các validation còn thiếu, error handling không chính xác hoặc các pattern Django không được dịch
  3. Kiểm tra rằng không có endpoint nào âm thầm thay đổi hình dạng response trong quá trình triển khai
  4. Review các Eloquent relationship để đảm bảo tính chính xác so với Django model graph ban đầu
  5. Tạo báo cáo review với các phát hiện blocking trước khi module tiếp theo bắt đầu

Bước 8: Quét Bảo Mật Toàn Bộ Codebase

/sk:security-scan

Chạy một lần sau khi tất cả module hoàn thành, không phải theo từng module.

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

  1. Chạy quét căn chỉnh theo OWASP trên toàn bộ codebase Laravel đã migrate
  2. Kiểm tra authentication middleware coverage trên tất cả endpoint được bảo vệ
  3. Quét các lỗ hổng injection, mass assignment exposure và unsafe query construction
  4. Xác nhận rằng Stripe webhook signature verification được triển khai đúng trong PHP
  5. Xuất báo cáo bảo mật phân biệt giữa framework defaults và các lỗ hổng thực sự

Bước 9: Commit Xuyên Suốt Quá Trình Migration

/sk:git cm

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

  1. Stage chỉ các file thuộc module hiện tại
  2. Viết commit message theo quy ước xác định module và migration phase
  3. Giữ migration của từng module như một commit atomic, có thể review
  4. Duy trì lịch sử sạch mà khách hàng có thể audit để xác minh tính hoàn chỉnh của migration

Ví Dụ Hoàn Chỉnh: Django Monolith Sang Laravel Cho PHP Team

Một team bảo trì của khách hàng làm PHP nhưng họ tiếp nhận một Django monolith 3 năm tuổi. Monolith có 15 model, 40+ API endpoint, Celery background tasks cho order processing và email, một Stripe integration cho subscriptions và test coverage một phần. Hợp đồng bao gồm timeline migration 6 tuần và yêu cầu hành vi API giống nhau để mobile app hiện có không cần thay đổi.

Quá trình migration diễn ra như sau:

# Thứ Hai — ánh xạ toàn bộ nguồn trước khi chạm vào bất cứ thứ gì
/sk:scout "map everything in this Django project: models with fields and relationships, views and API endpoints with request/response shapes, middleware, Celery tasks, Stripe integration, custom authentication logic — generate a complete source inventory"

# Sáng thứ Ba — quyết định phương pháp migration
/sk:brainstorm "given the scout inventory of 15 models and 40+ endpoints with Celery tasks and Stripe: what is the optimal migration strategy? Compare big-bang rewrite vs module-by-module migration. Which modules carry the most risk? What is the optimal migration order?"

# Chiều thứ Ba — nghiên cứu các khoảng trống framework
/sk:research "Django ORM to Eloquent migration patterns, Celery to Laravel Queues equivalents, Django REST Framework to Laravel API Resources, Stripe SDK differences between Python and PHP, Django middleware to Laravel middleware mapping"

# Thứ Tư — tạo kế hoạch từng module
/sk:plan "module-by-module migration: Module 1 user management (4 models, 8 endpoints). Module 2 product catalog (5 models, 12 endpoints). Module 3 order processing (4 models, 14 endpoints). Module 4 Stripe integration and background jobs"

# Tuần 1–2: Module 1 — triển khai, test, review, commit
/sk:cook plans/{timestamp}-django-to-laravel/phase-01-user-management.md
/sk:test "parity tests for user management: same endpoints, same response shapes, same status codes, same error messages as Django"
/sk:code-review --pending
/sk:git cm

# Tuần 2–3: Module 2 — product catalog
/sk:cook plans/{timestamp}-django-to-laravel/phase-02-product-catalog.md
/sk:test "parity tests for product catalog module"
/sk:code-review --pending
/sk:git cm

# Tuần 3–4: Module 3 — order processing
/sk:cook plans/{timestamp}-django-to-laravel/phase-03-order-processing.md
/sk:test "parity tests for order processing module"
/sk:code-review --pending
/sk:git cm

# Tuần 4–5: Module 4 — Stripe + background jobs
/sk:cook plans/{timestamp}-django-to-laravel/phase-04-stripe-and-jobs.md
/sk:test "parity tests for Stripe integration and queue jobs"
/sk:code-review --pending
/sk:git cm

# Tuần cuối — quét bảo mật toàn bộ codebase
/sk:security-scan

Kết quả: Khách hàng nhận được một codebase Laravel với hành vi API giống nhau, các parity test chứng minh tương đương hành vi từng module, và một báo cáo bảo mật sạch — tất cả trong vòng 6 tuần hợp đồng. Mobile app tiêu thụ API không cần thay đổi gì.

So Sánh Thời Gian

Nhiệm vụThủ côngVới Sun Agent Kit
Inventory codebase nguồn1–2 ngàyvài phút
Chiến lược migration + lập kế hoạch1–2 ngàyvài phút
Nghiên cứu + ánh xạ framework2–3 ngàyvài phút
Triển khai (4 module)1–2 tuần1–2 ngày
Parity testing từng module2–3 ngàyvài giờ
Code review + quét bảo mật1–2 ngàyvài phút
Tổng2–4 tuần1–3 ngày

Các Phương Pháp Tốt Nhất

1. Scout toàn bộ nguồn trước khi chạm vào đích ✅

Bạn không thể lên kế hoạch cho những gì bạn chưa biết. Inventory scout là nguồn sự thật duy nhất cho mọi business rule phải tồn tại sau migration. Chạy /sk:cook trước /sk:scout là cách chắc chắn để bỏ lỡ logic.

2. Migrate theo module, không theo file ✅

Các module có ranh giới rõ ràng và kết quả có thể kiểm tra độc lập. Migration theo file tạo ra các trạng thái hoạt động một phần không thể xác minh. Ranh giới module giữ cho mỗi chunk migration có thể giới hạn và review được.

3. Viết parity tests, không chỉ unit tests ✅

Thước đo thành công cho một migration là tương đương hành vi — Laravel endpoint có phản hồi giống Django endpoint không? Unit tests xác minh các chi tiết nội bộ; parity tests xác minh những gì mobile app của khách hàng thực sự nhận được.

4. Giữ nguyên hình dạng API response trong quá trình migration ✅

Đừng cám dỗ bởi việc “cải thiện” hình dạng response trong khi migration. Bất kỳ thay đổi nào đối với cấu trúc response sẽ phá vỡ API contract và yêu cầu cập nhật phối hợp với client. Dọn dẹp trong một lượt riêng biệt sau khi migration được xác minh.

5. Cố gắng migrate tất cả trong một lần /sk:cook ❌

Bốn module với 40+ endpoint không thể được triển khai đáng tin cậy trong một lượt. Ranh giới module tồn tại vì chúng giảm phạm vi ảnh hưởng của sai lầm. Một cook run thất bại trên toàn bộ codebase khó chẩn đoán hơn nhiều so với một module thất bại.

6. Bỏ qua /sk:test giữa các module ❌

Các khoảng trống logic tích lũy. Một validation còn thiếu trong Module 1 được xây dựng tiếp trong Module 3 trở thành một phiên debug qua 300 dòng code. Phát hiện nó trong Module 1 mất vài phút. Phát hiện sau khi Module 4 hoàn thành mất nhiều giờ.

Xử Lý Sự Cố

Vấn đề: Inventory scout không đầy đủ — background tasks bị bỏ sót

Giải pháp: Chạy một scout follow-up tập trung: /sk:scout "list all Celery task files, scheduled jobs in settings.py, and any management commands used in production". Scout ban đầu bao phủ cây ứng dụng chính; một scout có mục tiêu nắm bắt logic xử lý ngoại vi.

Vấn đề: Cook bỏ lỡ một business rule từ phiên bản Django

Giải pháp: Đối chiếu inventory scout với code đã triển khai. Nếu rule có trong báo cáo scout nhưng không có trong triển khai, chạy lại cook với rule cụ thể được mô tả rõ ràng: /sk:cook "implement rate limiting on the login endpoint: 5 attempts per 15 minutes, returns 429 with Retry-After header — matches Django behavior in scout report".

Vấn đề: Parity tests thất bại trên edge cases

Giải pháp: Đây là các bug migration thực sự, không phải vấn đề test. Parity tests đang hoạt động đúng — chúng đã tìm thấy sai lệch giữa hành vi Django và Laravel. Sửa code Laravel để khớp với hành vi Django trước khi chuyển sang module tiếp theo. Đừng điều chỉnh parity tests để vượt qua sai lệch.

Vấn đề: Security scan đánh dấu các pattern mặc định của framework (ví dụ: xử lý CSRF của Laravel)

Giải pháp: Xem xét báo cáo quét và tách biệt framework defaults khỏi các lỗ hổng thực sự. CSRF middleware tích hợp của Laravel, parameterized queries của Eloquent và xử lý session mặc định không phải là vấn đề bảo mật — chúng là đúng. Tập trung vào việc khắc phục các phát hiện ngoài framework defaults.

Bước Tiếp Theo

Điểm chính: Một migration không có inventory nguồn là viết lại với sự không chắc chắn — /sk:scout ánh xạ mọi model, endpoint và background task trước khi một dòng nào được di chuyển, và các chu kỳ /sk:plan + /sk:cook + /sk:test theo từng module giữ cho mỗi chunk có thể xác minh trước khi module tiếp theo bắt đầu.