claude-howto/uk/CONTRIBUTING.md

<!-- i18n-source: CONTRIBUTING.md -->
<!-- i18n-source-sha: 63a1416 -->
<!-- i18n-date: 2026-04-09 -->

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

# Внесок у Claude How To

Дякуємо за ваш інтерес до участі в цьому проєкті! Цей довідник допоможе вам зрозуміти, як ефективно зробити внесок.

## Про цей проєкт

Claude How To — це візуальний, заснований на прикладах довідник з Claude Code. Ми надаємо:
- **Mermaid-діаграми**, що пояснюють як працюють функції
- **Готові до продакшену шаблони**, які можна використовувати одразу
- **Реальні приклади** з контекстом та найкращими практиками
- **Прогресивні шляхи навчання** від початківця до просунутого

## Типи внесків

### 1. Нові приклади або шаблони
Додавайте приклади для існуючих функцій (слеш-команди, навички, хуки тощо):
- Код, готовий до копіювання та вставки
- Чіткі пояснення як це працює
- Сценарії використання та переваги
- Поради з усунення проблем

### 2. Покращення документації
- Уточнення заплутаних розділів
- Виправлення помилок та граматики
- Додавання відсутньої інформації
- Покращення прикладів коду

### 3. Гайди з функцій
Створюйте гайди для нових функцій Claude Code:
- Покрокові туторіали
- Архітектурні діаграми
- Поширені патерни та анти-патерни
- Реальні робочі процеси

### 4. Звіти про помилки
Повідомляйте про проблеми:
- Опишіть, що ви очікували
- Опишіть, що сталося насправді
- Вкажіть кроки для відтворення
- Додайте версію Claude Code та ОС

### 5. Відгуки та пропозиції
Допоможіть покращити довідник:
- Запропонуйте кращі пояснення
- Вкажіть на прогалини в покритті
- Порекомендуйте нові розділи або реорганізацію

## Початок роботи

### 1. Форк та клонування
```bash
git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto
```

### 2. Створення гілки
Використовуйте описову назву гілки:
```bash
git checkout -b add/feature-name
git checkout -b fix/issue-description
git checkout -b docs/improvement-area
```

### 3. Налаштування середовища

Pre-commit хуки запускають ті ж перевірки, що й CI, локально перед кожним комітом. Усі чотири перевірки повинні пройти перед прийняттям PR.

**Необхідні залежності:**

```bash
# Python tooling (uv is the package manager for this project)
pip install uv
uv venv
source .venv/bin/activate
uv pip install -r scripts/requirements-dev.txt

# Markdown linter (Node.js)
npm install -g markdownlint-cli

# Mermaid diagram validator (Node.js)
npm install -g @mermaid-js/mermaid-cli

# Install pre-commit and activate hooks
uv pip install pre-commit
pre-commit install
```

**Перевірка налаштування:**

```bash
pre-commit run --all-files
```

Хуки, що запускаються при кожному коміті:

| Хук | Що перевіряє |
|-----|-------------|
| `markdown-lint` | Форматування та структуру Markdown |
| `cross-references` | Відносні посилання, якорі, блоки коду |
| `mermaid-syntax` | Усі блоки ` ```mermaid ` коректно парсяться |
| `link-check` | Зовнішні URL-адреси доступні |
| `build-epub` | EPUB генерується без помилок (при змінах `.md`) |

## Структура каталогів

```
├── 01-slash-commands/      # Ярлики, ініційовані користувачем
├── 02-memory/              # Приклади постійного контексту
├── 03-skills/              # Повторно використовувані можливості
├── 04-subagents/           # Спеціалізовані AI-асистенти
├── 05-mcp/                 # Приклади Model Context Protocol
├── 06-hooks/               # Автоматизація на основі подій
├── 07-plugins/             # Пакетні функції
├── 08-checkpoints/         # Знімки сесій
├── 09-advanced-features/   # Планування, мислення, фони
├── 10-cli/                 # Довідник CLI
├── scripts/                # Скрипти збірки та утиліт
└── README.md               # Основний довідник
```

## Як зробити внесок прикладів

### Додавання слеш-команди
1. Створіть файл `.md` в `01-slash-commands/`
2. Включіть:
   - Чіткий опис що вона робить
   - Сценарії використання
   - Інструкції з встановлення
   - Приклади використання
   - Поради з налаштування
3. Оновіть `01-slash-commands/README.md`

### Додавання навички
1. Створіть каталог в `03-skills/`
2. Включіть:
   - `SKILL.md` — основна документація
   - `scripts/` — допоміжні скрипти за потреби
   - `templates/` — шаблони промптів
   - Приклади використання в README
3. Оновіть `03-skills/README.md`

### Додавання субагента
1. Створіть файл `.md` в `04-subagents/`
2. Включіть:
   - Призначення та можливості агента
   - Структуру системного промпту
   - Приклади використання
   - Приклади інтеграції
3. Оновіть `04-subagents/README.md`

### Додавання конфігурації MCP
1. Створіть файл `.json` в `05-mcp/`
2. Включіть:
   - Пояснення конфігурації
   - Необхідні змінні оточення
   - Інструкції з налаштування
   - Приклади використання
3. Оновіть `05-mcp/README.md`

### Додавання хука
1. Створіть файл `.sh` в `06-hooks/`
2. Включіть:
   - Shebang та опис
   - Чіткі коментарі, що пояснюють логіку
   - Обробку помилок
   - Міркування безпеки
3. Оновіть `06-hooks/README.md`

## Настанови з написання

### Стиль Markdown
- Використовуйте чіткі заголовки (H2 для секцій, H3 для підсекцій)
- Тримайте абзаци короткими та зосередженими
- Використовуйте маркеровані списки
- Включайте блоки коду з вказівкою мови
- Додавайте порожні рядки між секціями

### Приклади коду
- Робіть приклади готовими до копіювання та вставки
- Коментуйте неочевидну логіку
- Включайте і прості, і просунуті версії
- Показуйте реальні сценарії використання
- Виділяйте потенційні проблеми

### Документація
- Пояснюйте «чому», а не тільки «що»
- Вказуйте передумови
- Додавайте розділи з усунення проблем
- Посилайтесь на пов'язані теми
- Зберігайте дружність до початківців

### JSON/YAML
- Використовуйте правильні відступи (2 або 4 пробіли послідовно)
- Додавайте коментарі, що пояснюють конфігурацію
- Включайте приклади валідації

### Діаграми
- Використовуйте Mermaid коли можливо
- Тримайте діаграми простими та читабельними
- Додавайте текстовий опис під діаграмами для доступності
- Посилайтесь на відповідні розділи

## Настанови для комітів

Дотримуйтесь формату conventional commits:
```
type(scope): description

[optional body]
```

Типи:
- `feat`: Нова функція або приклад
- `fix`: Виправлення помилки
- `docs`: Зміни документації
- `refactor`: Реструктуризація коду
- `style`: Зміни форматування
- `test`: Додавання або зміни тестів
- `chore`: Збірка, залежності тощо

Приклади:
```
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 файли оновлені (локальний та кореневий)
- [ ] Немає чутливої інформації (API-ключі, облікові дані)
- [ ] Приклади протестовані та працюють
- [ ] Посилання перевірені та коректні
- [ ] Файли мають правильні дозволи (скрипти виконувані)
- [ ] Повідомлення коміту чітке та описове

### Локальне тестування
```bash
# Run all pre-commit checks (same checks as CI)
pre-commit run --all-files

# Review your changes
git diff
```

## Процес Pull Request

1. **Створіть PR з чітким описом**:
   - Що додає/виправляє?
   - Чому це потрібно?
   - Пов'язані issues (якщо є)

2. **Включіть відповідні деталі**:
   - Нова функція? Включіть сценарії використання
   - Документація? Поясніть покращення
   - Приклади? Покажіть до/після

3. **Посилайтесь на issues**:
   - Використовуйте `Closes #123` для автоматичного закриття пов'язаних issues

4. **Будьте терплячими з рев'ю**:
   - Мейнтейнери можуть запропонувати покращення
   - Ітеруйте на основі зворотного зв'язку
   - Остаточне рішення за мейнтейнерами

## Процес код-рев'ю

Рецензенти перевірять:
- **Точність**: Чи працює як описано?
- **Якість**: Чи готово до продакшену?
- **Консистентність**: Чи відповідає патернам проєкту?
- **Документація**: Чи чітко та повно?
- **Безпека**: Чи є вразливості?

## Повідомлення про проблеми

### Звіти про помилки
Включіть:
- Версію Claude Code
- Операційну систему
- Кроки для відтворення
- Очікувану поведінку
- Фактичну поведінку
- Скріншоти (за потреби)

### Запити на функції
Включіть:
- Сценарій використання або проблему, що вирішується
- Запропоноване рішення
- Альтернативи, які ви розглядали
- Додатковий контекст

### Проблеми з документацією
Включіть:
- Що незрозуміло або відсутнє
- Запропоновані покращення
- Приклади або посилання

## Політики проєкту

### Чутлива інформація
- Ніколи не комітьте API-ключі, токени або облікові дані
- Використовуйте значення-заповнювачі в прикладах
- Включайте `.env.example` для конфігураційних файлів
- Документуйте необхідні змінні оточення

### Якість коду
- Тримайте приклади зосередженими та читабельними
- Уникайте надмірного ускладнення рішень
- Включайте коментарі для неочевидної логіки
- Тестуйте ретельно перед відправкою

### Інтелектуальна власність
- Оригінальний контент належить автору
- Проєкт використовує освітню ліцензію
- Поважайте існуючі авторські права
- Вказуйте атрибуцію за потреби

## Отримання допомоги

- **Запитання**: Відкрийте обговорення в GitHub Issues
- **Загальна допомога**: Перевірте існуючу документацію
- **Допомога з розробки**: Перегляньте подібні приклади
- **Код-рев'ю**: Позначте мейнтейнерів у PR

## Визнання

Контриб'юторів відзначають у:
- Секції контриб'юторів README.md
- Сторінці контриб'юторів GitHub
- Історії комітів

## Безпека

При внесенні прикладів та документації, будь ласка, дотримуйтесь безпечних практик кодування:

- **Ніколи не захардкоджуйте секрети або API-ключі** — використовуйте змінні оточення
- **Попереджайте про наслідки безпеки** — виділяйте потенційні ризики
- **Використовуйте безпечні значення за замовчуванням** — увімкніть функції безпеки за замовчуванням
- **Валідуйте введення** — показуйте правильну валідацію та санітизацію введення
- **Включайте нотатки безпеки** — документуйте міркування безпеки

Щодо проблем безпеки, див. [SECURITY.md](SECURITY.md) для нашого процесу повідомлення про вразливості.

## Кодекс поведінки

Ми зобов'язуємося забезпечити привітну та інклюзивну спільноту. Будь ласка, прочитайте [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) для повних стандартів спільноти.

Коротко:
- Будьте поважними та інклюзивними
- Приймайте зворотний зв'язок з гідністю
- Допомагайте іншим вчитися та зростати
- Уникайте переслідувань або дискримінації
- Повідомляйте про проблеми мейнтейнерам

Усі контриб'ютори повинні дотримуватися цього кодексу та ставитися одне до одного з добротою та повагою.

## Ліцензія

Роблячи внесок у цей проєкт, ви погоджуєтесь, що ваші внески будуть ліцензовані за ліцензією MIT. Деталі див. у файлі [LICENSE](LICENSE).

## Запитання?

- Перевірте [README](README.md)
- Перегляньте [LEARNING-ROADMAP.md](LEARNING-ROADMAP.md)
- Подивіться існуючі приклади
- Відкрийте issue для обговорення

Дякуємо за ваш внесок! 🙏

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