CLAUDE.md

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