CLAUDE.md

1# CLAUDE.md
2 
3File này cung cấp hướng dẫn cho Claude Code (claude.ai/code) khi làm việc với code trong repository này.
4 
5## Tổng Quan Dự Án
6 
7Claude How To là một repository tutorial về các tính năng của Claude Code. Đây là **documentation-as-code** — sản phẩm chính là các file markdown được tổ chức thành các module học tập đánh số (01-10), không phải một ứng dụng thực thi.
8 
9**Kiến trúc**: Mỗi module (01-10) bao phủ một tính năng cụ thể của Claude Code với các template copy-paste, sơ đồ Mermaid, và ví dụ. Hệ thống build xác thực chất lượng documentation và tạo ebook EPUB.
10 
11## Các Lệnh Thường Dùng
12 
13### Kiểm Tra Chất Lượng Pre-commit
14 
15Tất cả documentation phải vượt qua bốn kiểm tra chất lượng trước khi commit (các kiểm tra này chạy tự động qua pre-commit hooks):
16 
17```bash
18# Cài đặt pre-commit hooks (chạy trên mỗi commit)
19pre-commit install
20 
21# Chạy tất cả các kiểm tra thủ công
22pre-commit run --all-files
23```
24 
25Bốn kiểm tra là:
261. **markdown-lint** — Cấu trúc và định dạng Markdown qua `markdownlint`
272. **cross-references** — Liên kết nội bộ, anchors, cú pháp code fence (Python script)
283. **mermaid-syntax** — Xác thực tất cả sơ đồ Mermaid parse đúng (Python script)
294. **link-check** — Các URL bên ngoài có thể truy cập được (Python script)
305. **build-epub** — EPUB tạo ra không có lỗi (khi có thay đổi `.md`)
31 
32### Thiết Lập Môi Trường Phát Triển
33 
34```bash
35# Cài đặt uv (Python package manager)
36pip install uv
37 
38# Tạo virtual environment và cài đặt Python dependencies
39uv venv
40source .venv/bin/activate
41uv pip install -r scripts/requirements-dev.txt
42 
43# Cài đặt Node.js tools (markdown linter và Mermaid validator)
44npm install -g markdownlint-cli
45npm install -g @mermaid-js/mermaid-cli
46 
47# Cài đặt pre-commit hooks
48uv pip install pre-commit
49pre-commit install
50```
51 
52### Testing
53 
54Các script Python trong `scripts/` có unit tests:
55 
56```bash
57# Chạy tất cả tests
58pytest scripts/tests/ -v
59 
60# Chạy với coverage
61pytest scripts/tests/ -v --cov=scripts --cov-report=html
62 
63# Chạy test cụ thể
64pytest scripts/tests/test_build_epub.py -v
65```
66 
67### Chất Lượng Code
68 
69```bash
70# Lint và format Python code
71ruff check scripts/
72ruff format scripts/
73 
74# Security scan
75bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
76 
77# Type checking
78mypy scripts/ --ignore-missing-imports
79```
80 
81### Build EPUB
82 
83```bash
84# Tạo ebook (render Mermaid diagrams qua Kroki.io API)
85uv run scripts/build_epub.py
86 
87# Với các tùy chọn
88uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
89```
90 
91## Cấu Trúc Thư Mục
92 
93```
94├── 01-slash-commands/      # Các lối tắt do người dùng gọi
95├── 02-memory/              # Ví dụ về bối cảnh liên tục
96├── 03-skills/              # Các khả năng có thể tái sử dụng
97├── 04-subagents/           # Các tác nhân AI chuyên dụng
98├── 05-mcp/                 # Ví dụ Model Context Protocol
99├── 06-hooks/              # Tự động hóa dựa trên sự kiện
100├── 07-plugins/             # Các tính năng được đóng gói
101├── 08-checkpoints/         # Các snapshot của phiên
102├── 09-advanced-features/   # Lập kế hoạch, suy nghĩ, background tasks
103├── 10-cli/                 # Tham chiếu CLI
104├── scripts/
105│   ├── build_epub.py           # EPUB generator (render Mermaid qua Kroki API)
106│   ├── check_cross_references.py   # Xác thực liên kết nội bộ
107│   ├── check_links.py          # Kiểm tra các URL bên ngoài
108│   ├── check_mermaid.py        # Xác thực cú pháp Mermaid
109│   └── tests/                  # Unit tests cho scripts
110├── .pre-commit-config.yaml    # Định nghĩa các kiểm tra chất lượng
111└── README.md               # Hướng dẫn chính (cũng là index của module)
112```
113 
114## Hướng Dẫn Nội Dung
115 
116### Cấu Trúc Module
117 
118Mỗi thư mục đánh số tuân theo pattern:
119- **README.md** — Tổng quan về tính năng với các ví dụ
120- **Các file ví dụ** — Template copy-paste (`.md` cho commands, `.json` cho configs, `.sh` cho hooks)
121- Các file được tổ chức theo độ phức tạp của tính năng và dependencies
122 
123### Sơ Đồ Mermaid
124- Tất cả sơ đồ phải parse thành công (được kiểm tra bởi pre-commit hook)
125- EPUB build render sơ đồ qua Kroki.io API (cần internet)
126- Sử dụng Mermaid cho flowcharts, sequence diagrams, và architecture visuals
127 
128### Cross-References
129- Sử dụng relative paths cho internal links (ví dụ: `(01-slash-commands/README.md)`)
130- Code fences phải chỉ định ngôn ngữ (ví dụ: ` ```bash `, ` ```python `)
131- Anchor links sử dụng format `#heading-name`
132 
133### Link Validation
134- Các URL bên ngoài phải có thể truy cập được (được kiểm tra bởi pre-commit hook)
135- Tránh link đến nội dung tạm thời
136- Sử dụng permalinks nếu có thể
137 
138## Các Điểm Kiến Trúc Quan Trọng
139 
1401. **Các thư mục đánh số thể hiện thứ tự học tập** — Prefix 01-10 thể hiện thứ tự được khuyến nghị để học các tính năng của Claude Code. Đánh số này có chủ đích; không tổ chức lại theo bảng chữ cái.
141 
1422. **Scripts là các tiện ích, không phải sản phẩm** — Các script Python trong `scripts/` hỗ trợ chất lượng documentation và tạo EPUB. Nội dung thực tế nằm trong các thư mục module đánh số.
143 
1443. **Pre-commit là người gác cổng** — Tất cả bốn kiểm tra chất lượng phải pass trước khi PR được chấp nhận. CI pipeline chạy các kiểm tra tương tự như lần thứ hai.
145 
1464. **Mermaid rendering cần network** — EPUB build gọi Kroki.io API để render diagrams. Các lỗi build ở đây thường là vấn đề network hoặc cú pháp Mermaid không hợp lệ.
147 
1485. **Đây là tutorial, không phải thư viện** — Khi thêm nội dung, tập trung vào giải thích rõ ràng, ví dụ copy-paste, và sơ đồ trực quan. Giá trị nằm ở việc dạy các khái niệm, không cung cấp code có thể tái sử dụng.
149 
150## Commit Conventions
151 
152Tuân theo format conventional commit:
153- `feat(slash-commands): Add API documentation generator`
154- `docs(memory): Improve personal preferences example`
155- `fix(README): Correct table of contents link`
156- `refactor(hooks): Simplify hook configuration examples`
157 
158Scope nên khớp với tên thư mục khi áp dụng.
159