# Внесок у 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