claude-howto/vi/CLAUDE.md

CLAUDE.md

File 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.

Tổng Quan Dự Án

Claude 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.

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.

Các Lệnh Thường Dùng

Kiểm Tra Chất Lượng Pre-commit

Tất cả documentation phải vượt qua năm 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):

# Cài đặt pre-commit hooks (chạy trên mỗi commit)
pre-commit install

# Chạy tất cả các kiểm tra thủ công
pre-commit run --all-files

Năm kiểm tra là:

1. markdown-lint — Cấu trúc và định dạng Markdown qua markdownlint
2. cross-references — Liên kết nội bộ, anchors, cú pháp code fence (Python script)
3. mermaid-syntax — Xác thực tất cả sơ đồ Mermaid parse đúng (Python script)
4. link-check — Các URL bên ngoài có thể truy cập được (Python script)
5. markdown-rendering — Markdown render không lỗi (Python script)

Việc build EPUB không phải là một pre-commit hook — nó chỉ chạy trong CI (job build-epub trong .github/workflows/test.yml), vì nó cần binary mmdc cục bộ, vốn không có bản build hoạt động trên arm64.

Thiết Lập Môi Trường Phát Triển

# Cài đặt uv (Python package manager)
pip install uv

# Tạo virtual environment và cài đặt Python dependencies
uv venv
source .venv/bin/activate
uv pip install -r scripts/requirements-dev.txt

# Cài đặt Node.js tools (markdown linter và Mermaid validator)
npm install -g markdownlint-cli
npm install -g @mermaid-js/mermaid-cli

# Cài đặt pre-commit hooks
uv pip install pre-commit
pre-commit install

Testing

Các script Python trong scripts/ có unit tests:

# Chạy tất cả tests
pytest scripts/tests/ -v

# Chạy với coverage
pytest scripts/tests/ -v --cov=scripts --cov-report=html

# Chạy test cụ thể
pytest scripts/tests/test_build_epub.py -v

Chất Lượng Code

# Lint và format Python code
ruff check scripts/
ruff format scripts/

# Security scan
bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/

# Type checking
mypy scripts/ --ignore-missing-imports

Build EPUB

# Tạo ebook (render Mermaid diagrams bằng mmdc CLI cục bộ — không cần mạng)
uv run scripts/build_epub.py

# Với các tùy chọn
uv run scripts/build_epub.py --verbose --output custom-name.epub --lang vi

Cấu Trúc Thư Mục

├── 01-slash-commands/      # Các lối tắt do người dùng gọi
├── 02-memory/              # Ví dụ về bối cảnh liên tục
├── 03-skills/              # Các khả năng có thể tái sử dụng
├── 04-subagents/           # Các tác nhân AI chuyên dụng
├── 05-mcp/                 # Ví dụ Model Context Protocol
├── 06-hooks/              # Tự động hóa dựa trên sự kiện
├── 07-plugins/             # Các tính năng được đóng gói
├── 08-checkpoints/         # Các snapshot của phiên
├── 09-advanced-features/   # Lập kế hoạch, suy nghĩ, background tasks
├── 10-cli/                 # Tham chiếu CLI
├── scripts/
│   ├── build_epub.py           # EPUB generator (render Mermaid bằng mmdc cục bộ)
│   ├── check_cross_references.py   # Xác thực liên kết nội bộ
│   ├── check_links.py          # Kiểm tra các URL bên ngoài
│   ├── check_mermaid.py        # Xác thực cú pháp Mermaid
│   └── tests/                  # Unit tests cho scripts
├── .pre-commit-config.yaml    # Định nghĩa các kiểm tra chất lượng
└── README.md               # Hướng dẫn chính (cũng là index của module)

Hướng Dẫn Nội Dung

Cấu Trúc Module

Mỗi thư mục đánh số tuân theo pattern:

• README.md — Tổng quan về tính năng với các ví dụ
• Các file ví dụ — Template copy-paste (.md cho commands, .json cho configs, .sh cho hooks)
• Các file được tổ chức theo độ phức tạp của tính năng và dependencies

Sơ Đồ Mermaid

• Tất cả sơ đồ phải parse thành công (được kiểm tra bởi pre-commit hook)
• EPUB build render sơ đồ bằng mmdc CLI cục bộ (không cần internet, nhưng cần cài mmdc)
• Sử dụng Mermaid cho flowcharts, sequence diagrams, và architecture visuals

Cross-References

• Sử dụng relative paths cho internal links (ví dụ: (01-slash-commands/README.md))
• Code fences phải chỉ định ngôn ngữ (ví dụ: ```bash, ```python)
• Anchor links sử dụng format #heading-name

Link Validation

• Các URL bên ngoài phải có thể truy cập được (được kiểm tra bởi pre-commit hook)
• Tránh link đến nội dung tạm thời
• Sử dụng permalinks nếu có thể

Các Điểm Kiến Trúc Quan Trọng

1. 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.

2. 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ố.

3. Pre-commit là người gác cổng — Tất cả năm 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.

4. Mermaid rendering cần mmdc cục bộ — EPUB build gọi mmdc CLI cục bộ để render diagrams (không cần network). Các lỗi build ở đây thường là do chưa cài mmdc hoặc cú pháp Mermaid không hợp lệ. Bản thân EPUB build không chạy trong pre-commit — nó chỉ chạy trong CI.

5. Đâ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.

Commit Conventions

Tuân theo format conventional commit:

• feat(slash-commands): Add API documentation generator
• docs(memory): Improve personal preferences example
• fix(README): Correct table of contents link
• refactor(hooks): Simplify hook configuration examples

Scope nên khớp với tên thư mục khi áp dụng.