Hướng dẫn chi tiết cấu trúc dự án Claude Code Project

Hướng dẫn chi tiết cấu trúc dự án Claude Code Project
1. Mục đích
Cấu trúc kho lưu trữ claude_code_project được thiết kế dành riêng cho việc phát triển phần mềm khi sử dụng Claude (Anthropic) làm trợ lý lập trình chính.
Mục tiêu chính:
. Giữ ngữ cảnh (context) cho Claude luôn sạch sẽ, tập trung và có cấu trúc
. Tạo kho lưu trữ các kỹ năng (skills) có thể tái sử dụng nhiều lần
. Tự động hóa các bước kiểm tra chất lượng, review code, refactor, release…
. Dễ dàng tài liệu hóa các quyết định kiến trúc (Architectural Decision Records – ADR)
. Phù hợp với quy trình phát triển dài hạn, nhiều người hoặc solo developer sử dụng AI hỗ trợ

2. Mô tả thành phần quan trọng
2.1. CLAUDE.md (tệp quan trọng nhất)
Đây là tệp ngữ cảnh chính mà bạn sẽ copy-paste hoặc attach cho Claude ở mỗi phiên làm việc dài.
Nội dung thường bao gồm:
. Vai trò của Claude trong dự án (ví dụ: “Bạn là kiến trúc sư kiêm senior developer full-stack…”)
. Quy tắc viết code (naming, folder structure, commit message…)
. Công nghệ stack đang dùng
. Các quyết định kiến trúc đã được thống nhất
. Link đến các SKILL.md cần dùng thường xuyên
. Các ràng buộc quan trọng (không dùng package X, phải tuân thủ Y…)
Nguyên tắc: Giữ CLAUDE.md dưới 4000–6000 token. Nếu dài hơn → tách thành nhiều CLAUDE.md theo module và tham chiếu.

2.2. Thư mục .claude/skills/
Mỗi thư mục con đại diện cho một kỹ năng tái sử dụng.
Ví dụ nội dung file skills/code-review/SKILL.md:
# Kỹ năng: Code Review Chuyên sâu
## Vai trò khi kích hoạt
Bạn là một senior code reviewer có 15 năm kinh nghiệm, cực kỳ khắt khe về clean code, performance, security và maintainability.
## Quy trình review bắt buộc
1. Tổng quan thiết kế
2. Đánh giá tên biến/hàm/class theo Clean Code
3. Kiểm tra SOLID, DRY, YAGNI
4. Security checklist (OWASP Top 10 nếu liên quan)
5. Performance & Big-O
6. Đề xuất cải thiện cụ thể (code snippet nếu cần)
7. Điểm số chất lượng (1–10) và lý do

## Câu lệnh kích hoạt phổ biến
"review", "cr", "code review file X", "đánh giá đoạn code sau"
Các kỹ năng khác tương tự: refactor, write-test, naming-suggestion, commit-message-generator…

2.3. Thư mục .claude/hooks/
Dùng để tự động hóa kiểm tra chất lượng (nếu bạn dùng extension / wrapper Claude).
Ví dụ:
pre-answer hook: kiểm tra xem câu trả lời có vi phạm quy tắc đặt tên không
post-answer hook: tự động chạy code linter nếu Claude sinh code
Hiện tại chủ yếu dùng thủ công hoặc tích hợp với các công cụ bên thứ ba.

2.4. docs/decisions/
Sử dụng định dạng ADR (Architectural Decision Records).
Ví dụ: 0001-use-htmx-instead-of-react.md
# 0001 – Sử dụng HTMX thay vì React cho frontend
## Trạng thái: Đã chấp nhận
## Bối cảnh
- Muốn giữ codebase đơn giản, ít JavaScript
- Team nhỏ, ưu tiên tốc độ phát triển
## Quyết định
Sử dụng HTMX + Go templating thay vì SPA React/Vue.
## Hậu quả
- Giảm bundle size đáng kể
- Tăng tốc độ phát triển giao diện
- Khó mở rộng thành ứng dụng mobile native sau này

2.5. src/{module}/CLAUDE.md
Khi dự án lớn, mỗi module lớn nên có CLAUDE.md riêng để giữ ngữ cảnh cục bộ.
Ví dụ: src/api/CLAUDE.md chỉ chứa thông tin về REST/GraphQL convention, auth middleware, error handling của module api.

3. Quy trình làm việc đề xuất (Best Practices)
. Mở phiên làm việc mới → copy nội dung CLAUDE.md chính
. Khi cần kỹ năng cụ thể → copy thêm nội dung SKILL.md tương ứng
. Khi Claude sinh code → dán vào file thật → commit
. Trước khi merge → chạy kỹ năng “code-review”
. Trước khi release → chạy kỹ năng “release”
. Mỗi khi quyết định kiến trúc quan trọng → tạo ADR mới trong docs/decisions/
. Định kỳ (1–2 tuần) cập nhật lại CLAUDE.md chính cho gọn gàng