| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 9 | 18 | 4% |
| Commands | 4 | 1 | 11 | 25% |
| Section tags | 5 | 2 | 5 | 42% |
What each file covers
Sections
1 shared · 9 only in A · 18 only in B- − 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
- + Конвенції комітів
- + Перевірки якості pre-commit
- + Install pre-commit hooks (runs on every commit)
- + Run all checks manually
- + Install uv (Python package manager)
- + Create virtual environment and install Python dependencies
- + Install Node.js tools (markdown linter and Mermaid validator)
- + Install pre-commit hooks
- + Run all tests
- + Run with coverage
- + Run specific test
- + Lint and format Python code
- + Security scan
- + Type checking
- + Збірка EPUB
- + Generate ebook (renders Mermaid diagrams via Kroki.io API)
- + With options
- + Mermaid-діаграми
- CLAUDE.md
Commands
4 shared · 1 only in A · 11 only in B- − ruff check scripts/ && ruff format scripts/
- + 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
- pytest scripts/tests/ -v
- uv run scripts/build_epub.py
- mypy scripts/ --ignore-missing-imports
- python
Section tags
5 shared · 2 only in A · 5 only in B- − build
- − do-not
- + setup
- + types
- + testing-strategy
- + security
- + dependencies
- test
- lint-format
- git-pr
- api
- agent-behaviour
Line diff
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
luongnv89/claude-howto · uk/CLAUDE.md
@@ +1 @@
1<!-- i18n-source: CLAUDE.md -->
2<!-- i18n-source-sha: 63a1416 -->
3<!-- i18n-date: 2026-04-10 -->
4
5# CLAUDE.md
6
7Цей файл надає настанови для Claude Code (claude.ai/code) при роботі з кодом у цьому репозиторії.
8
9## Огляд проєкту
10
11Claude How To — це навчальний репозиторій з функцій Claude Code. Це **документація-як-код** — основний продукт — markdown-файли, організовані в пронумеровані навчальні модулі, а не виконуваний додаток.
12
13**Архітектура**: Кожен модуль (01-10) охоплює конкретну функцію Claude Code з готовими шаблонами для копіювання, Mermaid-діаграмами та прикладами. Система збірки валідує якість документації та генерує EPUB-книгу.
14
15## Типові команди
16
17### Перевірки якості pre-commit
18
19Уся документація повинна пройти чотири перевірки якості перед комітами (запускаються автоматично через pre-commit хуки):
20
21```bash
22# Install pre-commit hooks (runs on every commit)
23pre-commit install
24
25# Run all checks manually
26pre-commit run --all-files
27```
28
29П'ять перевірок:
301. **markdown-lint** — Структура та форматування Markdown через `markdownlint`
312. **cross-references** — Внутрішні посилання, якорі, синтаксис блоків коду (Python-скрипт)
323. **mermaid-syntax** — Валідація коректного парсингу всіх Mermaid-діаграм (Python-скрипт)
334. **link-check** — Доступність зовнішніх URL (Python-скрипт)
345. **build-epub** — EPUB генерується без помилок (при змінах `.md`)
35
36### Налаштування середовища розробки
37
38```bash
39# Install uv (Python package manager)
40pip install uv
41
42# Create virtual environment and install Python dependencies
43uv venv
44source .venv/bin/activate
45uv pip install -r scripts/requirements-dev.txt
46
47# Install Node.js tools (markdown linter and Mermaid validator)
48npm install -g markdownlint-cli
49npm install -g @mermaid-js/mermaid-cli
50
51# Install pre-commit hooks
52uv pip install pre-commit
53pre-commit install
54```
55
56### Тестування
57
58Python-скрипти в `scripts/` мають юніт-тести:
59
60```bash
61# Run all tests
62pytest scripts/tests/ -v
63
64# Run with coverage
65pytest scripts/tests/ -v --cov=scripts --cov-report=html
66
67# Run specific test
68pytest scripts/tests/test_build_epub.py -v
69```
70
71### Якість коду
72
73```bash
74# Lint and format Python code
75ruff check scripts/
76ruff format scripts/
77
78# Security scan
79bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
80
81# Type checking
82mypy scripts/ --ignore-missing-imports
83```
84
85### Збірка EPUB
86
87```bash
88# Generate ebook (renders Mermaid diagrams via Kroki.io API)
89uv run scripts/build_epub.py
90
91# With options
92uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
93```
94
95## Структура каталогів
96
97```
98├── 01-slash-commands/ # Ярлики, ініційовані користувачем
99├── 02-memory/ # Приклади постійного контексту
100├── 03-skills/ # Повторно використовувані можливості
101├── 04-subagents/ # Спеціалізовані AI-асистенти
102├── 05-mcp/ # Приклади Model Context Protocol
103├── 06-hooks/ # Автоматизація на основі подій
104├── 07-plugins/ # Пакетні функції
105├── 08-checkpoints/ # Знімки сесій
106├── 09-advanced-features/ # Планування, мислення, фони
107├── 10-cli/ # Довідник CLI
108├── scripts/
109│ ├── build_epub.py # Генератор EPUB (рендерить Mermaid через Kroki API)
110│ ├── check_cross_references.py # Валідація внутрішніх посилань
111│ ├── check_links.py # Перевірка зовнішніх URL
112│ ├── check_mermaid.py # Валідація синтаксису Mermaid
113│ └── tests/ # Юніт-тести для скриптів
114├── .pre-commit-config.yaml # Визначення перевірок якості
115└── README.md # Основний довідник (також індекс модулів)
116```
117
118## Настанови щодо контенту
119
120### Структура модуля
121Кожна пронумерована папка дотримується патерну:
122- **README.md** — Огляд функції з прикладами
123- **Файли прикладів** — Готові шаблони для копіювання (`.md` для команд, `.json` для конфігурацій, `.sh` для хуків)
124- Файли організовані за складністю функцій та залежностями
125
126### Mermaid-діаграми
127- Усі діаграми повинні успішно парситися (перевіряється pre-commit хуком)
128- Збірка EPUB рендерить діаграми через Kroki.io API (потрібен інтернет)
129- Використовуйте Mermaid для блок-схем, діаграм послідовностей та архітектурних візуалізацій
130
131### Перехресні посилання
132- Використовуйте відносні шляхи для внутрішніх посилань (напр., `(01-slash-commands/README.md)`)
133- Блоки коду повинні вказувати мову (напр., ` ```bash `, ` ```python `)
134- Якірні посилання використовують формат `#heading-name`
135
136### Валідація посилань
137- Зовнішні URL повинні бути доступні (перевіряється pre-commit хуком)
138- Уникайте посилань на тимчасовий контент
139- Використовуйте пермалінки де можливо
140
141## Ключові архітектурні рішення
142
1431. **Пронумеровані папки вказують порядок навчання** — Префікс 01-10 відображає рекомендовану послідовність вивчення функцій Claude Code. Ця нумерація навмисна; не реорганізовуйте за алфавітом.
144
1452. **Скрипти — утиліти, а не продукт** — Python-скрипти в `scripts/` підтримують якість документації та генерацію EPUB. Фактичний контент — у пронумерованих папках модулів.
146
1473. **Pre-commit — привратник** — Усі перевірки якості повинні пройти перед прийняттям PR. CI-конвеєр запускає ці ж перевірки як другий прохід.
148
1494. **Рендеринг Mermaid потребує мережі** — Збірка EPUB викликає Kroki.io API для рендерингу діаграм. Помилки збірки тут зазвичай пов'язані з мережею або невалідним синтаксисом Mermaid.
150
1515. **Це туторіал, а не бібліотека** — При додаванні контенту зосереджуйтесь на чітких поясненнях, готових прикладах та візуальних діаграмах. Цінність — у навчанні концепцій, а не у наданні повторно використовуваного коду.
152
153## Конвенції комітів
154
155Дотримуйтесь формату conventional commits:
156- `feat(slash-commands): Add API documentation generator`
157- `docs(memory): Improve personal preferences example`
158- `fix(README): Correct table of contents link`
159- `refactor(hooks): Simplify hook configuration examples`
160
161Скоуп повинен відповідати назві папки де можливо.
162
@@ −1 +1 @@
1+<!-- i18n-source: CLAUDE.md -->
2+<!-- i18n-source-sha: 63a1416 -->
3+<!-- i18n-date: 2026-04-10 -->
4+
15 # CLAUDE.md
26
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.
7+Цей файл надає настанови для Claude Code (claude.ai/code) при роботі з кодом у цьому репозиторії.
48
5−See also `.claude/CLAUDE.md` for stack/commands and `STYLE_GUIDE.md` for lesson structure.
9+## Огляд проєкту
610
7−## Critical commands
11+Claude How To — це навчальний репозиторій з функцій Claude Code. Це **документація-як-код** — основний продукт — markdown-файли, організовані в пронумеровані навчальні модулі, а не виконуваний додаток.
812
13+**Архітектура**: Кожен модуль (01-10) охоплює конкретну функцію Claude Code з готовими шаблонами для копіювання, Mermaid-діаграмами та прикладами. Система збірки валідує якість документації та генерує EPUB-книгу.
14+
15+## Типові команди
16+
17+### Перевірки якості pre-commit
18+
19+Уся документація повинна пройти чотири перевірки якості перед комітами (запускаються автоматично через pre-commit хуки):
20+
921 ```bash
10−# Quality gate (also runs on commit via pre-commit hooks)
22+# Install pre-commit hooks (runs on every commit)
23+pre-commit install
24+
25+# Run all checks manually
1126 pre-commit run --all-files
27+```
1228
13−# Tests
29+П'ять перевірок:
30+1. **markdown-lint** — Структура та форматування Markdown через `markdownlint`
31+2. **cross-references** — Внутрішні посилання, якорі, синтаксис блоків коду (Python-скрипт)
32+3. **mermaid-syntax** — Валідація коректного парсингу всіх Mermaid-діаграм (Python-скрипт)
33+4. **link-check** — Доступність зовнішніх URL (Python-скрипт)
34+5. **build-epub** — EPUB генерується без помилок (при змінах `.md`)
35+
36+### Налаштування середовища розробки
37+
38+```bash
39+# Install uv (Python package manager)
40+pip install uv
41+
42+# Create virtual environment and install Python dependencies
43+uv venv
44+source .venv/bin/activate
45+uv pip install -r scripts/requirements-dev.txt
46+
47+# Install Node.js tools (markdown linter and Mermaid validator)
48+npm install -g markdownlint-cli
49+npm install -g @mermaid-js/mermaid-cli
50+
51+# Install pre-commit hooks
52+uv pip install pre-commit
53+pre-commit install
54+```
55+
56+### Тестування
57+
58+Python-скрипти в `scripts/` мають юніт-тести:
59+
60+```bash
61+# Run all tests
1462 pytest scripts/tests/ -v
1563
16−# EPUB build (calls Kroki.io API to render Mermaid — needs network)
17−uv run scripts/build_epub.py
64+# Run with coverage
65+pytest scripts/tests/ -v --cov=scripts --cov-report=html
1866
19−# Python tooling
20−ruff check scripts/ && ruff format scripts/
21−mypy scripts/ --ignore-missing-imports
67+# Run specific test
68+pytest scripts/tests/test_build_epub.py -v
69+```
70+
71+### Якість коду
72+
73+```bash
74+# Lint and format Python code
75+ruff check scripts/
76+ruff format scripts/
77+
78+# Security scan
2279 bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/
80+
81+# Type checking
82+mypy scripts/ --ignore-missing-imports
2383 ```
2484
25−Pre-commit runs 5 checks: markdown-lint, cross-references, mermaid-syntax, link-check, build-epub (on `.md` changes). All must pass.
85+### Збірка EPUB
2686
27−## Architecture map
87+```bash
88+# Generate ebook (renders Mermaid diagrams via Kroki.io API)
89+uv run scripts/build_epub.py
2890
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.
91+# With options
92+uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5
93+```
3494
35−## Hard rules
95+## Структура каталогів
3696
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.
97+```
98+├── 01-slash-commands/ # Ярлики, ініційовані користувачем
99+├── 02-memory/ # Приклади постійного контексту
100+├── 03-skills/ # Повторно використовувані можливості
101+├── 04-subagents/ # Спеціалізовані AI-асистенти
102+├── 05-mcp/ # Приклади Model Context Protocol
103+├── 06-hooks/ # Автоматизація на основі подій
104+├── 07-plugins/ # Пакетні функції
105+├── 08-checkpoints/ # Знімки сесій
106+├── 09-advanced-features/ # Планування, мислення, фони
107+├── 10-cli/ # Довідник CLI
108+├── scripts/
109+│ ├── build_epub.py # Генератор EPUB (рендерить Mermaid через Kroki API)
110+│ ├── check_cross_references.py # Валідація внутрішніх посилань
111+│ ├── check_links.py # Перевірка зовнішніх URL
112+│ ├── check_mermaid.py # Валідація синтаксису Mermaid
113+│ └── tests/ # Юніт-тести для скриптів
114+├── .pre-commit-config.yaml # Визначення перевірок якості
115+└── README.md # Основний довідник (також індекс модулів)
116+```
46117
47−## Workflow preferences
118+## Настанови щодо контенту
48119
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`.
120+### Структура модуля
121+Кожна пронумерована папка дотримується патерну:
122+- **README.md** — Огляд функції з прикладами
123+- **Файли прикладів** — Готові шаблони для копіювання (`.md` для команд, `.json` для конфігурацій, `.sh` для хуків)
124+- Файли організовані за складністю функцій та залежностями
54125
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.
126+### Mermaid-діаграми
127+- Усі діаграми повинні успішно парситися (перевіряється pre-commit хуком)
128+- Збірка EPUB рендерить діаграми через Kroki.io API (потрібен інтернет)
129+- Використовуйте Mermaid для блок-схем, діаграм послідовностей та архітектурних візуалізацій
130+
131+### Перехресні посилання
132+- Використовуйте відносні шляхи для внутрішніх посилань (напр., `(01-slash-commands/README.md)`)
133+- Блоки коду повинні вказувати мову (напр., ` ```bash `, ` ```python `)
134+- Якірні посилання використовують формат `#heading-name`
135+
136+### Валідація посилань
137+- Зовнішні URL повинні бути доступні (перевіряється pre-commit хуком)
138+- Уникайте посилань на тимчасовий контент
139+- Використовуйте пермалінки де можливо
140+
141+## Ключові архітектурні рішення
142+
143+1. **Пронумеровані папки вказують порядок навчання** — Префікс 01-10 відображає рекомендовану послідовність вивчення функцій Claude Code. Ця нумерація навмисна; не реорганізовуйте за алфавітом.
144+
145+2. **Скрипти — утиліти, а не продукт** — Python-скрипти в `scripts/` підтримують якість документації та генерацію EPUB. Фактичний контент — у пронумерованих папках модулів.
146+
147+3. **Pre-commit — привратник** — Усі перевірки якості повинні пройти перед прийняттям PR. CI-конвеєр запускає ці ж перевірки як другий прохід.
148+
149+4. **Рендеринг Mermaid потребує мережі** — Збірка EPUB викликає Kroki.io API для рендерингу діаграм. Помилки збірки тут зазвичай пов'язані з мережею або невалідним синтаксисом Mermaid.
150+
151+5. **Це туторіал, а не бібліотека** — При додаванні контенту зосереджуйтесь на чітких поясненнях, готових прикладах та візуальних діаграмах. Цінність — у навчанні концепцій, а не у наданні повторно використовуваного коду.
152+
153+## Конвенції комітів
154+
155+Дотримуйтесь формату conventional commits:
156+- `feat(slash-commands): Add API documentation generator`
157+- `docs(memory): Improve personal preferences example`
158+- `fix(README): Correct table of contents link`
159+- `refactor(hooks): Simplify hook configuration examples`
160+
161+Скоуп повинен відповідати назві папки де можливо.
63162
