Конвенції та правила форматування для внеску в Claude How To. Дотримуйтесь цього гайду, щоб тримати контент консистентним, професійним та зручним для підтримки.

Зміст

• Іменування файлів та каталогів
• Структура документа
• Заголовки
• Форматування тексту
• Списки
• Таблиці
• Блоки коду
• Посилання та перехресні посилання
• Діаграми
• Використання емодзі
• YAML Frontmatter
• Зображення та медіа
• Тон та голос
• Повідомлення комітів
• Чеклист для авторів

Іменування файлів та каталогів

Каталоги уроків

Каталоги уроків використовують двозначний числовий префікс з kebab-case описом:

01-slash-commands/
02-memory/
03-skills/
04-subagents/
05-mcp/

Номер відображає порядок навчального шляху від початківця до просунутого.

Імена файлів

Правила

• Використовуйте нижній регістр для всіх імен файлів та каталогів (крім документів верхнього рівня як README.md, CATALOG.md)
• Використовуйте дефіси (-) як розділювачі слів, ніколи підкреслення або пробіли
• Тримайте назви описовими, але стислими

Структура документа

Кореневий README

Кореневий README.md дотримується порядку:

1. Логотип (елемент <picture> з варіантами dark/light)
2. Заголовок H1
3. Вступна цитата (однорядкова ціннісна пропозиція)
4. Секція "Чому цей довідник?" з таблицею порівняння
5. Горизонтальна лінія (---)
6. Зміст
7. Каталог функцій
8. Швидка навігація
9. Навчальний шлях
10. Секції функцій
11. Початок роботи
12. Найкращі практики / Усунення проблем
13. Внесок / Ліцензія

README уроку

Кожен README.md уроку дотримується порядку:

1. Заголовок H1 (напр., # Slash Commands)
2. Короткий вступний абзац
3. Таблиця швидкого довідника (опціонально)
4. Архітектурна діаграма (Mermaid)
5. Детальні секції (H2)
6. Практичні приклади (нумеровані, 4-6 прикладів)
7. Найкращі практики (таблиці Do's and Don'ts)
8. Усунення проблем
9. Пов'язані гайди / Офіційна документація
10. Метадані документа у футері

Файл функції/прикладу

Окремі файли функцій (напр., optimize.md, pr.md):

1. YAML frontmatter (якщо потрібно)
2. Заголовок H1
3. Призначення / опис
4. Інструкції з використання
5. Приклади коду
6. Поради з налаштування

Розділювачі секцій

Використовуйте горизонтальні лінії (---) для відділення основних регіонів документа:

---

## Нова основна секція

Розміщуйте їх після вступної цитати та між логічно окремими частинами документа.

Заголовки

Ієрархія

Правила

• Один H1 на документ — лише заголовок сторінки
• Ніколи не пропускайте рівні — не стрибайте з H2 на H4
• Тримайте заголовки стислими — прагніть до 2-5 слів
• Використовуйте sentence case — великі літери тільки для першого слова та власних назв (виняток: назви функцій залишаються як є)
• Додавайте емодзі-префікси тільки в кореневому README для заголовків секцій (див. Використання емодзі)

Форматування тексту

Виділення

Цитати для виносок

Використовуйте цитати з жирними префіксами для важливих нотаток:

> **Note**: Custom slash commands have been merged into skills since v2.0.

> **Important**: Never commit API keys or credentials.

> **Tip**: Combine memory with skills for maximum effectiveness.

Підтримувані типи виносок: Note, Important, Tip, Warning.

Абзаци

• Тримайте абзаци короткими (2-4 речення)
• Додавайте порожній рядок між абзацами
• Починайте з ключового моменту, потім надавайте контекст
• Пояснюйте «чому», а не тільки «що»

Списки

Ненумеровані списки

Використовуйте дефіси (-) з 2-пробіловим відступом для вкладеності:

- First item
- Second item
  - Nested item
  - Another nested item
    - Deep nested (avoid going deeper than 3 levels)
- Third item

Нумеровані списки

Використовуйте нумеровані списки для послідовних кроків, інструкцій та ранжованих елементів:

1. First step
2. Second step
   - Sub-point detail
   - Another sub-point
3. Third step

Описові списки

Використовуйте жирні мітки для списків ключ-значення:

- **Performance bottlenecks** - identify O(n^2) operations, inefficient loops
- **Memory leaks** - find unreleased resources, circular references
- **Algorithm improvements** - suggest better algorithms or data structures

Правила

• Підтримуйте консистентні відступи (2 пробіли на рівень)
• Додавайте порожній рядок перед та після списку
• Тримайте елементи списку паралельними за структурою
• Уникайте вкладеності глибше 3 рівнів

Таблиці

Стандартний формат

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data     | Data     | Data     |

Поширені патерни таблиць

Порівняння функцій (3-4 колонки):

| Feature | Invocation | Persistence | Best For |
|---------|-----------|------------|----------|
| **Slash Commands** | Manual (`/cmd`) | Session only | Quick shortcuts |
| **Memory** | Auto-loaded | Cross-session | Long-term learning |

Do's and Don'ts:

| Do | Don't |
|----|-------|
| Use descriptive names | Use vague names |
| Keep files focused | Overload a single file |

Швидкий довідник:

| Aspect | Details |
|--------|---------|
| **Purpose** | Generate API documentation |
| **Scope** | Project-level |
| **Complexity** | Intermediate |

Правила

• Жирний для заголовків таблиці, коли вони є мітками рядків (перша колонка)
• Вирівнюйте пайпи для читабельності у вихідному коді (опціонально, але бажано)
• Тримайте вміст комірок стислим; використовуйте посилання для деталей
• Використовуйте форматування коду для команд та шляхів файлів у комірках

Блоки коду

Теги мов

Завжди вказуйте тег мови для підсвічування синтаксису:

Конвенції

# Comment explaining what the command does
claude mcp add notion --transport http https://mcp.notion.com/mcp

• Додавайте рядок коментаря перед неочевидними командами
• Робіть всі приклади готовими до копіювання та вставки
• Показуйте і прості, і просунуті версії де доречно
• Включайте очікуваний вивід коли це допомагає розумінню (використовуйте блок коду без тегу)

Блоки встановлення

Використовуйте цей патерн для інструкцій з встановлення:

# Copy files to your project
cp 01-slash-commands/*.md .claude/commands/

Багатокрокові робочі процеси

# Step 1: Create the directory
mkdir -p .claude/commands

# Step 2: Copy the templates
cp 01-slash-commands/*.md .claude/commands/

# Step 3: Verify installation
ls .claude/commands/

Посилання та перехресні посилання

Внутрішні посилання (відносні)

Використовуйте відносні шляхи для всіх внутрішніх посилань:

[Slash Commands](01-slash-commands/)
[Skills Guide](03-skills/)
[Memory Architecture](02-memory/#memory-architecture)

З каталогу уроку назад до кореня або сусіда:

[Back to main guide](../README.md)
[Related: Skills](../03-skills/)

Зовнішні посилання (абсолютні)

Використовуйте повні URL з описовим текстом якоря:

[Anthropic's official documentation](https://code.claude.com/docs/en/overview)

• Ніколи не використовуйте "click here" або "this link" як текст якоря
• Використовуйте описовий текст, що має сенс поза контекстом

Якорі секцій

Посилайтесь на секції в тому ж документі за допомогою GitHub-style якорів:

[Feature Catalog](#-feature-catalog)
[Best Practices](#best-practices)

Патерн пов'язаних гайдів

Завершуйте уроки секцією пов'язаних гайдів:

## Related Guides

- [Slash Commands](../01-slash-commands/) - Quick shortcuts
- [Memory](../02-memory/) - Persistent context
- [Skills](../03-skills/) - Reusable capabilities

Діаграми

Mermaid

Використовуйте Mermaid для всіх діаграм. Підтримувані типи:

• graph TB / graph LR — архітектура, ієрархія, потік
• sequenceDiagram — потоки взаємодії
• timeline — хронологічні послідовності

Стильові конвенції

Застосовуйте консистентні кольори за допомогою блоків стилів:

graph TB
    A["Component A"] --> B["Component B"]
    B --> C["Component C"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#fce4ec,stroke:#333,color:#333
    style C fill:#e8f5e9,stroke:#333,color:#333

Палітра кольорів:

Правила

• Використовуйте ["Label text"] для міток вузлів (дозволяє спеціальні символи)
• Використовуйте <br/> для переносу рядків у мітках
• Тримайте діаграми простими (максимум 10-12 вузлів)
• Додавайте короткий текстовий опис під діаграмою для доступності
• Використовуйте зверху вниз (TB) для ієрархій, зліва направо (LR) для робочих процесів

Використання емодзі

Де використовуються емодзі

Емодзі використовуються рідко та цілеспрямовано — тільки в певних контекстах:

Стандартний набір емодзі

Правила

• Ніколи не використовуйте емодзі в основному тексті або абзацах
• Використовуйте емодзі в заголовках тільки в кореневому README (не в README уроків)
• Не додавайте декоративних емодзі — кожне емодзі повинно нести значення
• Тримайте використання емодзі консистентним з таблицею вище

YAML Frontmatter

Файли функцій (навички, команди, агенти)

---
name: unique-identifier
description: What this feature does and when to use it
allowed-tools: Bash, Read, Grep
---

Опціональні поля

---
name: my-feature
description: Brief description
argument-hint: "[file-path] [options]"
allowed-tools: Bash, Read, Grep, Write, Edit
model: opus                        # opus, sonnet, or haiku
disable-model-invocation: true     # User-only invocation
user-invocable: false              # Hidden from user menu
context: fork                      # Run in isolated subagent
agent: Explore                     # Agent type for context: fork
---

Правила

• Розміщуйте frontmatter на самому початку файлу
• Використовуйте kebab-case для поля name
• Тримайте description в одне речення
• Включайте тільки необхідні поля

Зображення та медіа

Патерн логотипу

Усі документи, що починаються з логотипу, використовують елемент <picture> для підтримки dark/light режимів:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="resources/logos/claude-howto-logo-dark.svg">
  <img alt="Claude How To" src="resources/logos/claude-howto-logo.svg">
</picture>

Скріншоти

• Зберігайте у відповідному каталозі уроку (напр., 01-slash-commands/pr-slash-command.png)
• Використовуйте kebab-case імена файлів
• Включайте описовий alt-текст
• Віддавайте перевагу SVG для діаграм, PNG для скріншотів

Правила

• Завжди вказуйте alt-текст для зображень
• Тримайте розмір файлів зображень розумним (< 500KB для PNG)
• Використовуйте відносні шляхи для посилань на зображення
• Зберігайте зображення в тому ж каталозі, що й документ, який на них посилається, або в assets/ для спільних зображень

Тон та голос

Стиль написання

• Професійний, але доступний — технічна точність без перевантаження жаргоном
• Активний стан — "Create a file", а не "A file should be created"
• Прямі інструкції — "Run this command", а не "You might want to run this command"
• Дружній до початківців — припускаємо, що читач новий у Claude Code, але не новий у програмуванні

Принципи контенту

Словник

• Використовуйте "Claude Code" (не "Claude CLI" або "the tool")
• Використовуйте "skill" (не "custom command" — застарілий термін)
• Використовуйте "lesson" або "guide" для нумерованих секцій
• Використовуйте "example" для окремих файлів функцій

Повідомлення комітів

Дотримуйтесь Conventional Commits:

type(scope): description

Типи

Скоупи

Використовуйте назву уроку або області файлу як скоуп:

feat(slash-commands): Add API documentation generator
docs(memory): Improve personal preferences example
fix(README): Correct table of contents link
docs(skills): Add comprehensive code review skill

Метадані документа у футері

README уроків завершуються блоком метаданих:

---
**Last Updated**: March 2026
**Claude Code Version**: 2.1.97
**Compatible Models**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5

• Використовуйте формат місяць + рік (напр., "March 2026")
• Оновлюйте версію при зміні функцій
• Перелічуйте всі сумісні моделі

Чеклист для авторів

Перед відправкою контенту перевірте:

• Імена файлів/каталогів використовують kebab-case
• Документ починається з заголовку H1 (один на файл)
• Ієрархія заголовків коректна (без пропущених рівнів)
• Усі блоки коду мають теги мов
• Приклади коду готові до копіювання та вставки
• Внутрішні посилання використовують відносні шляхи
• Зовнішні посилання мають описовий текст якоря
• Таблиці правильно відформатовані
• Емодзі відповідають стандартному набору (якщо використовуються)
• Mermaid-діаграми використовують стандартну палітру кольорів
• Немає чутливої інформації (API-ключі, облікові дані)
• YAML frontmatter валідний (якщо використовується)
• Зображення мають alt-текст
• Абзаци короткі та зосереджені
• Секція пов'язаних гайдів посилається на відповідні уроки
• Повідомлення коміту відповідає формату conventional commits

Останнє оновлення: Квітень 2026