danghong.me Docs

Appearance

Engineering Standards ​

Quy chuẩn từ lúc viết dòng code đầu tiên tới khi thay đổi được merge. Phần triển khai ở Deployment.

1. TIÊU CHUẨN LẬP TRÌNH (PROGRAMMING STANDARDS) ​

  • TypeScript First: 100% Type-safe. Sử dụng Interface/Type để định nghĩa rõ "hợp đồng dữ liệu". Không dùng any (ESLint báo lỗi).
  • Component-Driven: Phát triển theo hướng nguyên tử (Atomic), mỗi Component chỉ làm một việc duy nhất.
  • Client Components: Chỉ thêm "use client" khi cần state/tương tác, và đặt nó ở dòng đầu tiên của file (Turbopack báo lỗi nếu đặt sau import).
  • Next.js 16: Phiên bản này có nhiều thay đổi so với kiến thức phổ biến. Đọc hướng dẫn trong website/node_modules/next/dist/docs/ trước khi dùng API mới (xem website/AGENTS.md).
  • Naming Convention:
    • Components: PascalCase (VD: ProductDetail.tsx).
    • Functions/Variables: camelCase (VD: openProduct).
    • Folders/Routes: kebab-case (VD: products-hub, life-mentors).

2. QUY TRÌNH PHÁT TRIỂN (WORKFLOW) ​

2.1. Git & Branching ​

  • main: Code ổn định, nguồn để deploy.
  • Quy trình hiện tại: làm việc rồi merge thẳng vào main, push main, deploy (không bắt buộc PR). CI chạy trên mỗi lần push vào main. Job docs-sync chỉ chạy trên PR, nên khi không qua PR thì tự kiểm: sửa code phải sửa docs/ trong cùng commit.

2.2. Kiểm tra tự động (CI) ​

Workflow .github/workflows/ci.yml chạy trên mọi Pull Request và mỗi lần push vào main:

JobThư mụcLệnh
Websitewebsite/npm ci → npm run lint → npm run build
Docsdocs/npm ci → npm run build (VitePress báo lỗi nếu có link hỏng)
Mediamedia/npm ci → npm test (logic dựng dữ liệu, render và kiểm tra tên file upload)

2.3. Chạy local ​

bash
cd website && npm install && npm run dev     # http://localhost:3000
cd docs    && npm install && npm run dev     # http://localhost:5173 (npm run check: cổng kiểm docs)
cd media   && npm install && npm run dev     # Pages Functions + D1/R2 local, xem docs sites/media/ops

3. DOCUMENTATION AS SINGLE SOURCE OF TRUTH ​

  • Tài liệu chỉ sống trong docs/. Không tạo bản sao ở README, Google Docs hay Notion; ở đó chỉ đặt link tới docs.danghong.me.
  • Thay đổi hành vi một site (trang mới, dữ liệu mới, đổi điều hướng) thì cập nhật trang tương ứng trong docs/ trong cùng commit. Bảng ánh xạ ở CLAUDE.md.
  • Link giữa các tài liệu dùng đường dẫn tương đối (../sites/www/sitemap.md), không dùng file:///…. Luật đầy đủ ở Conventions.

4. MCP COLLABORATION (LÀM VIỆC VỚI AI) ​

Để AI Agent (Antigravity, Claude…) làm việc hiệu quả nhất:

  1. Context First: AI đọc Conventions, brief và ops của site cần sửa trước khi code.
  2. Atomic Edits: Thực hiện thay đổi nhỏ, xác thực từng bước.
  3. Audit Questions:
    • Code đã đúng Type chưa? npm run lint và npm run build có pass không?
    • Component có tái sử dụng được không?
    • Tài liệu trong docs/ đã được cập nhật theo thay đổi chưa?