| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 29 | 9 | 3% |
| Commands | 4 | 11 | 1 | 25% |
| Section tags | 6 | 6 | 1 | 46% |
What each file covers
Sections
1 shared · 29 only in A · 9 only in B- − Tổng Quan Dự Án
- − Các Lệnh Thường Dùng
- − Kiểm Tra Chất Lượng Pre-commit
- − Cài đặt pre-commit hooks (chạy trên mỗi commit)
- − Chạy tất cả các kiểm tra thủ công
- − Thiết Lập Môi Trường Phát Triển
- − Cài đặt uv (Python package manager)
- − Tạo virtual environment và cài đặt Python dependencies
- − Cài đặt Node.js tools (markdown linter và Mermaid validator)
- − Cài đặt pre-commit hooks
- − Testing
- − Chạy tất cả tests
- − Chạy với coverage
- − Chạy test cụ thể
- − Chất Lượng Code
- − Lint và format Python code
- − Security scan
- − Type checking
- − Build EPUB
- − Tạo ebook (render Mermaid diagrams qua Kroki.io API)
- − Với các tùy chọn
- − Cấu Trúc Thư Mục
- − Hướng Dẫn Nội Dung
- − Cấu Trúc Module
- − Sơ Đồ Mermaid
- − Cross-References
- − Link Validation
- − Các Điểm Kiến Trúc Quan Trọng
- − Commit Conventions
- + Critical commands
- + Quality gate (also runs on commit via pre-commit hooks)
- + Tests
- + EPUB build (calls Kroki.io API to render Mermaid — needs network)
- + Python tooling
- + Architecture map
- + Hard rules
- + Workflow preferences
- + Token Efficiency
- CLAUDE.md
Commands
4 shared · 11 only in A · 1 only in B- − pip install uv
- − uv venv
- − uv pip install -r scripts/requirements-dev.txt
- − npm install -g markdownlint-cli
- − npm install -g @mermaid-js/mermaid-cli
- − uv pip install pre-commit
- − pytest scripts/tests/ -v --cov=scripts --cov-report=html
- − pytest scripts/tests/test_build_epub.py -v
- − ruff check scripts/
- − ruff format scripts/
- − uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
- + ruff check scripts/ && ruff format scripts/
- pytest scripts/tests/ -v
- mypy scripts/ --ignore-missing-imports
- uv run scripts/build_epub.py
- python
Section tags
6 shared · 6 only in A · 1 only in B- − setup
- − code-style
- − types
- − testing-strategy
- − security
- − dependencies
- + do-not
- build
- test
- lint-format
- git-pr
- api
- agent-behaviour
Line diff
luongnv89/claude-howto · vi/CLAUDE.md
@@ −1 @@
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
luongnv89/claude-howto · CLAUDE.md
@@ +1 @@
1# CLAUDE.md
2
3Tutorial repo. Output is markdown in numbered modules `01-` through `10-`, not an app. Scripts in `scripts/` exist only to validate docs and build the EPUB.
4
5See also `.claude/CLAUDE.md` for stack/commands and `STYLE_GUIDE.md` for lesson structure.
6
7## Critical commands
8
9```bash
10# Quality gate (also runs on commit via pre-commit hooks)
11pre-commit run --all-files
12
13# Tests
14pytest scripts/tests/ -v
15
16# EPUB build (calls Kroki.io API to render Mermaid — needs network)
17uv run scripts/build_epub.py
18
19# Python tooling
20ruff check scripts/ && ruff format scripts/
21mypy scripts/ --ignore-missing-imports
22bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
23```
24
25Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on `.md` changes). All must pass.
26
27## Architecture map
28
29- `01-` … `10-` — tutorial modules. **Numbered prefix = learning order**, not alphabetical. Do not reorganize.
30- Each module: `README.md` + copy-paste templates (`.md`, `.json`, `.sh`).
31- `scripts/` — utilities (EPUB builder, link/mermaid/cross-ref validators). Not the product.
32- `02-memory/*.md` — CLAUDE.md templates users copy into their own projects. Don't confuse with this file.
33- `openspec/` — spec-driven change proposals.
34
35## Hard rules
36
37- **YOU MUST NOT commit or push without explicit user request.**
38- **YOU MUST NOT add `Co-Authored-By: Claude`** to any commit message.
39- Always activate `.venv` before running Python scripts (check `venv/`, `.venv/`, `env/`).
40- Internal links use **relative paths** (e.g. `01-slash-commands/README.md`); anchors use `#heading-name`.
41- Code fences **must** declare a language (`bash`, `python`, `json`, …) — the cross-reference check fails otherwise.
42- External URLs must be reachable and stable. No ephemeral links.
43- Mermaid diagrams must parse (validated pre-commit). Broken EPUB build is usually invalid Mermaid or no network to Kroki.
44- Commit format: `type(scope): subject` where `scope` matches the module folder (e.g. `feat(slash-commands):`, `docs(memory):`, `fix(README):`).
45- Do not reorganize the `01-`–`10-` numbering. The order is the curriculum.
46
47## Workflow preferences
48
49- For lesson edits, follow `STYLE_GUIDE.md` for structure/naming/diagrams.
50- Small fixes → minimal diff. Don't rewrite a section to fix a typo.
51- When adding a module page: README + templates first, then update root `README.md` index and `LEARNING-ROADMAP.md` if order/timing changes.
52- Tutorial > library: prioritize clear explanations and copy-paste examples over reusable abstractions.
53- If a quality check fails, fix the underlying issue. Don't bypass with `--no-verify`.
54
55## Token Efficiency
56- Never re-read files you just wrote or edited. You know the contents.
57- Never re-run commands to "verify" unless the outcome was uncertain.
58- Don't echo back large blocks of code or file contents unless asked.
59- Batch related edits into single operations. Don't make 5 edits when 1 handles it.
60- Skip confirmations like "I'll continue..." Just do it.
61- If a task needs 1 tool call, don't use 3. Plan before acting.
62- Do not summarize what you just did unless the result is ambiguous or you need additional input.
63
@@ −1 +1 @@
11 # CLAUDE.md
22
3−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.
3+Tutorial repo. Output is markdown in numbered modules `01-` through `10-`, not an app. Scripts in `scripts/` exist only to validate docs and build the EPUB.
44
5−## Tổng Quan Dự Án
5+See also `.claude/CLAUDE.md` for stack/commands and `STYLE_GUIDE.md` for lesson structure.
66
7−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.
7+## Critical commands
88
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−
15−Tấ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−
179 ```bash
18−# Cài đặt pre-commit hooks (chạy trên mỗi commit)
19−pre-commit install
20−
21−# Chạy tất cả các kiểm tra thủ công
10+# Quality gate (also runs on commit via pre-commit hooks)
2211 pre-commit run --all-files
23−```
2412
25−Bốn kiểm tra là:
26−1. **markdown-lint** — Cấu trúc và định dạng Markdown qua `markdownlint`
27−2. **cross-references** — Liên kết nội bộ, anchors, cú pháp code fence (Python script)
28−3. **mermaid-syntax** — Xác thực tất cả sơ đồ Mermaid parse đúng (Python script)
29−4. **link-check** — Các URL bên ngoài có thể truy cập được (Python script)
30−5. **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)
36−pip install uv
37−
38−# Tạo virtual environment và cài đặt Python dependencies
39−uv venv
40−source .venv/bin/activate
41−uv pip install -r scripts/requirements-dev.txt
42−
43−# Cài đặt Node.js tools (markdown linter và Mermaid validator)
44−npm install -g markdownlint-cli
45−npm install -g @mermaid-js/mermaid-cli
46−
47−# Cài đặt pre-commit hooks
48−uv pip install pre-commit
49−pre-commit install
50−```
51−
52−### Testing
53−
54−Các script Python trong `scripts/` có unit tests:
55−
56−```bash
57−# Chạy tất cả tests
13+# Tests
5814 pytest scripts/tests/ -v
5915
60−# Chạy với coverage
61−pytest scripts/tests/ -v --cov=scripts --cov-report=html
16+# EPUB build (calls Kroki.io API to render Mermaid — needs network)
17+uv run scripts/build_epub.py
6218
63−# Chạy test cụ thể
64−pytest scripts/tests/test_build_epub.py -v
65−```
66−
67−### Chất Lượng Code
68−
69−```bash
70−# Lint và format Python code
71−ruff check scripts/
72−ruff format scripts/
73−
74−# Security scan
75−bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
76−
77−# Type checking
19+# Python tooling
20+ruff check scripts/ && ruff format scripts/
7821 mypy scripts/ --ignore-missing-imports
22+bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
7923 ```
8024
81−### Build EPUB
25+Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on `.md` changes). All must pass.
8226
83−```bash
84−# Tạo ebook (render Mermaid diagrams qua Kroki.io API)
85−uv run scripts/build_epub.py
27+## Architecture map
8628
87−# Với các tùy chọn
88−uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
89−```
29+- `01-` … `10-` — tutorial modules. **Numbered prefix = learning order**, not alphabetical. Do not reorganize.
30+- Each module: `README.md` + copy-paste templates (`.md`, `.json`, `.sh`).
31+- `scripts/` — utilities (EPUB builder, link/mermaid/cross-ref validators). Not the product.
32+- `02-memory/*.md` — CLAUDE.md templates users copy into their own projects. Don't confuse with this file.
33+- `openspec/` — spec-driven change proposals.
9034
91−## Cấu Trúc Thư Mục
35+## Hard rules
9236
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−```
37+- **YOU MUST NOT commit or push without explicit user request.**
38+- **YOU MUST NOT add `Co-Authored-By: Claude`** to any commit message.
39+- Always activate `.venv` before running Python scripts (check `venv/`, `.venv/`, `env/`).
40+- Internal links use **relative paths** (e.g. `01-slash-commands/README.md`); anchors use `#heading-name`.
41+- Code fences **must** declare a language (`bash`, `python`, `json`, …) — the cross-reference check fails otherwise.
42+- External URLs must be reachable and stable. No ephemeral links.
43+- Mermaid diagrams must parse (validated pre-commit). Broken EPUB build is usually invalid Mermaid or no network to Kroki.
44+- Commit format: `type(scope): subject` where `scope` matches the module folder (e.g. `feat(slash-commands):`, `docs(memory):`, `fix(README):`).
45+- Do not reorganize the `01-`–`10-` numbering. The order is the curriculum.
11346
114−## Hướng Dẫn Nội Dung
47+## Workflow preferences
11548
116−### Cấu Trúc Module
49+- For lesson edits, follow `STYLE_GUIDE.md` for structure/naming/diagrams.
50+- Small fixes → minimal diff. Don't rewrite a section to fix a typo.
51+- When adding a module page: README + templates first, then update root `README.md` index and `LEARNING-ROADMAP.md` if order/timing changes.
52+- Tutorial > library: prioritize clear explanations and copy-paste examples over reusable abstractions.
53+- If a quality check fails, fix the underlying issue. Don't bypass with `--no-verify`.
11754
118−Mỗ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−
140−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.
141−
142−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ố.
143−
144−3. **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−
146−4. **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−
148−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.
149−
150−## Commit Conventions
151−
152−Tuâ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−
158−Scope nên khớp với tên thư mục khi áp dụng.
55+## Token Efficiency
56+- Never re-read files you just wrote or edited. You know the contents.
57+- Never re-run commands to "verify" unless the outcome was uncertain.
58+- Don't echo back large blocks of code or file contents unless asked.
59+- Batch related edits into single operations. Don't make 5 edits when 1 handles it.
60+- Skip confirmations like "I'll continue..." Just do it.
61+- If a task needs 1 tool call, don't use 3. Plan before acting.
62+- Do not summarize what you just did unless the result is ambiguous or you need additional input.
15963
