claude-howto/uk/CONTRIBUTING.md

Внесок у Claude How To

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

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

Claude How To — це візуальний, заснований на прикладах довідник з Claude Code. Ми надаємо:

• Mermaid-діаграми, що пояснюють як працюють функції
• Готові до продакшену шаблони, які можна використовувати одразу
• Реальні приклади з контекстом та найкращими практиками
• Прогресивні шляхи навчання від початківця до просунутого

Типи внесків

1. Нові приклади або шаблони

Додавайте приклади для існуючих функцій (слеш-команди, навички, хуки тощо):

• Код, готовий до копіювання та вставки
• Чіткі пояснення як це працює
• Сценарії використання та переваги
• Поради з усунення проблем

2. Покращення документації

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

3. Гайди з функцій

Створюйте гайди для нових функцій Claude Code:

• Покрокові туторіали
• Архітектурні діаграми
• Поширені патерни та анти-патерни
• Реальні робочі процеси

4. Звіти про помилки

Повідомляйте про проблеми:

• Опишіть, що ви очікували
• Опишіть, що сталося насправді
• Вкажіть кроки для відтворення
• Додайте версію Claude Code та ОС

5. Відгуки та пропозиції

Допоможіть покращити довідник:

• Запропонуйте кращі пояснення
• Вкажіть на прогалини в покритті
• Порекомендуйте нові розділи або реорганізацію

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

1. Форк та клонування

git clone https://github.com/luongnv89/claude-howto.git
cd claude-howto

2. Створення гілки

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

git checkout -b add/feature-name
git checkout -b fix/issue-description
git checkout -b docs/improvement-area

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

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

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

# 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

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

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-ключі, облікові дані)
• Приклади протестовані та працюють
• Посилання перевірені та коректні
• Файли мають правильні дозволи (скрипти виконувані)
• Повідомлення коміту чітке та описове

Локальне тестування

# 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 для нашого процесу повідомлення про вразливості.

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

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

Коротко:

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

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

Ліцензія

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

Запитання?

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

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

---

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