diff --git a/uk/01-slash-commands/README.md b/uk/01-slash-commands/README.md new file mode 100644 index 0000000..0429321 --- /dev/null +++ b/uk/01-slash-commands/README.md @@ -0,0 +1,585 @@ + + + + + + + Claude How To + + +# Слеш-команди + +## Огляд + +Слеш-команди — це ярлики, що керують поведінкою Claude під час інтерактивної сесії. Вони бувають кількох типів: + +- **Вбудовані команди**: Надаються Claude Code (`/help`, `/clear`, `/model`) +- **Навички (Skills)**: Користувацькі команди, створені як файли `SKILL.md` (`/optimize`, `/pr`) +- **Команди плагінів**: Команди з встановлених плагінів (`/frontend-design:frontend-design`) +- **MCP-промпти**: Команди з MCP-серверів (`/mcp__github__list_prs`) + +> **Примітка**: Кастомні слеш-команди об'єднані з навичками. Файли в `.claude/commands/` все ще працюють, але навички (`.claude/skills/`) — рекомендований підхід. Обидва створюють ярлики `/command-name`. Див. [Посібник з навичок](../03-skills/) для повного довідника. + +## Довідник вбудованих команд + +Вбудовані команди — це ярлики для типових дій. Доступно **60+ вбудованих команд** та **5 вбудованих навичок**. Введіть `/` у Claude Code для повного списку, або `/` з літерами для фільтрації. + +| Команда | Призначення | +|---------|------------| +| `/add-dir ` | Додати робочий каталог | +| `/agents` | Управління конфігураціями агентів | +| `/branch [name]` | Розгалужити розмову в нову сесію (аліас: `/fork`). Примітка: `/fork` перейменовано на `/branch` у v2.1.77 | +| `/btw ` | Побічне запитання без додавання в історію | +| `/chrome` | Налаштування інтеграції з Chrome | +| `/clear` | Очистити розмову (аліаси: `/reset`, `/new`) | +| `/color [color\|default]` | Встановити колір рядка промпту | +| `/compact [instructions]` | Компактизувати розмову з необов'язковими інструкціями фокусу | +| `/config` | Відкрити налаштування (аліас: `/settings`) | +| `/context` | Візуалізація використання контексту кольоровою сіткою | +| `/copy [N]` | Скопіювати відповідь у буфер; `w` записує у файл | +| `/cost` | Показати статистику використання токенів | +| `/desktop` | Продовжити в десктопному застосунку (аліас: `/app`) | +| `/diff` | Інтерактивний перегляд незакомічених змін | +| `/doctor` | Діагностика стану встановлення | +| `/effort [low\|medium\|high\|max\|auto]` | Встановити рівень зусиль. `max` потребує Opus 4.6 | +| `/exit` | Вийти з REPL (аліас: `/quit`) | +| `/export [filename]` | Експортувати розмову у файл або буфер | +| `/extra-usage` | Налаштування додаткового використання для лімітів | +| `/fast [on\|off]` | Перемкнути швидкий режим | +| `/feedback` | Надіслати відгук (аліас: `/bug`) | +| `/help` | Показати довідку | +| `/hooks` | Переглянути конфігурації хуків | +| `/ide` | Управління IDE-інтеграціями | +| `/init` | Ініціалізувати `CLAUDE.md`. `CLAUDE_CODE_NEW_INIT=1` для інтерактивного потоку | +| `/insights` | Згенерувати звіт аналізу сесії | +| `/install-github-app` | Налаштувати GitHub Actions | +| `/install-slack-app` | Встановити Slack-застосунок | +| `/keybindings` | Відкрити налаштування клавіш | +| `/login` | Змінити обліковий запис Anthropic | +| `/logout` | Вийти з облікового запису Anthropic | +| `/mcp` | Управління MCP-серверами та OAuth | +| `/memory` | Редагувати `CLAUDE.md`, перемкнути автопам'ять | +| `/mobile` | QR-код для мобільного (аліаси: `/ios`, `/android`) | +| `/model [model]` | Вибір моделі зі стрілками вліво/вправо для рівня зусиль | +| `/passes` | Поділитися безкоштовним тижнем Claude Code | +| `/permissions` | Переглянути/оновити дозволи (аліас: `/allowed-tools`) | +| `/plan [description]` | Увійти в режим планування | +| `/plugin` | Управління плагінами | +| `/powerup` | Інтерактивні уроки з анімованими демо | +| `/privacy-settings` | Налаштування приватності (Pro/Max) | +| `/release-notes` | Переглянути журнал змін | +| `/reload-plugins` | Перезавантажити активні плагіни | +| `/remote-control` | Віддалене керування з claude.ai (аліас: `/rc`) | +| `/remote-env` | Налаштування стандартного віддаленого середовища | +| `/rename [name]` | Перейменувати сесію | +| `/resume [session]` | Відновити розмову (аліас: `/continue`) | +| `/review` | **Застаріла** — встановіть плагін `code-review` | +| `/rewind` | Відкат розмови та/або коду (аліас: `/checkpoint`) | +| `/sandbox` | Перемкнути режим пісочниці | +| `/schedule [description]` | Створити/управляти хмарними запланованими завданнями | +| `/security-review` | Аналіз гілки на вразливості безпеки | +| `/skills` | Список доступних навичок | +| `/stats` | Візуалізація щоденного використання, сесій, серій | +| `/stickers` | Замовити стікери Claude Code | +| `/status` | Показати версію, модель, обліковий запис | +| `/statusline` | Налаштування рядка стану | +| `/tasks` | Список/управління фоновими завданнями | +| `/terminal-setup` | Налаштування клавіш терміналу | +| `/theme` | Змінити колірну тему | +| `/ultraplan ` | Створити план в ultraplan-сесії, переглянути в браузері | +| `/upgrade` | Відкрити сторінку оновлення тарифу | +| `/usage` | Показати ліміти плану та статус обмежень | +| `/voice` | Перемкнути голосовий ввід push-to-talk | + +### Вбудовані навички + +Ці навички поставляються з Claude Code і викликаються як слеш-команди: + +| Навичка | Призначення | +|---------|------------| +| `/batch ` | Оркестрація масштабних паралельних змін через worktrees | +| `/claude-api` | Завантажити довідник Claude API для мови проекту | +| `/debug [description]` | Увімкнути налагоджувальне логування | +| `/loop [interval] ` | Запускати промпт повторно за інтервалом | +| `/simplify [focus]` | Перевірити змінені файли на якість коду | + +### Застарілі команди + +| Команда | Статус | +|---------|--------| +| `/review` | Застаріла — замінена плагіном `code-review` | +| `/output-style` | Застаріла з v2.1.73 | +| `/fork` | Перейменована на `/branch` (аліас працює, v2.1.77) | +| `/pr-comments` | Видалена в v2.1.91 — запитайте Claude напряму | +| `/vim` | Видалена в v2.1.92 — використовуйте /config → Editor mode | + +### Останні зміни + +- `/fork` перейменовано на `/branch`, `/fork` залишено як аліас (v2.1.77) +- `/output-style` застаріла (v2.1.73) +- `/review` застаріла на користь плагіна `code-review` +- Додано команду `/effort` з рівнем `max` для Opus 4.6 +- Додано команду `/voice` для голосового вводу push-to-talk +- Додано команду `/schedule` для запланованих завдань +- Додано команду `/color` для кастомізації рядка промпту +- `/pr-comments` видалена в v2.1.91 +- `/vim` видалена в v2.1.92 +- Додано `/ultraplan` для перегляду плану в браузері +- Додано `/powerup` для інтерактивних уроків +- Додано `/sandbox` для режиму пісочниці +- Вибір `/model` тепер показує зрозумілі назви (наприклад, "Sonnet 4.6") замість ID моделей +- `/resume` підтримує аліас `/continue` +- MCP-промпти доступні як команди `/mcp____` (див. [MCP-промпти як команди](#mcp-промпти-як-команди)) + +## Кастомні команди (тепер навички) + +Кастомні слеш-команди **об'єднані з навичками**. Обидва підходи створюють команди, які викликаються через `/command-name`: + +| Підхід | Розташування | Статус | +|--------|-------------|--------| +| **Навички (Рекомендовано)** | `.claude/skills//SKILL.md` | Поточний стандарт | +| **Legacy-команди** | `.claude/commands/.md` | Все ще працює | + +Якщо навичка і команда мають однакове ім'я, **навичка має пріоритет**. Наприклад, коли існують і `.claude/commands/review.md`, і `.claude/skills/review/SKILL.md`, використовується версія навички. + +### Шлях міграції + +Існуючі файли `.claude/commands/` продовжують працювати без змін. Для міграції на навички: + +**До (Команда):** + +``` +.claude/commands/optimize.md +``` + +**Після (Навичка):** + +``` +.claude/skills/optimize/SKILL.md +``` + +### Чому навички? + +Навички пропонують додаткові можливості порівняно з legacy-командами: + +- **Структура каталогів**: Пакування скриптів, шаблонів та довідкових файлів +- **Автовиклик**: Claude може запускати навички автоматично за потреби +- **Контроль виклику**: Вибір — користувач, Claude, або обидва можуть викликати +- **Виконання в субагенті**: Запуск навичок в ізольованих контекстах з `context: fork` +- **Прогресивне розкриття**: Завантаження додаткових файлів лише за потреби + +### Створення кастомної команди як навички + +Створіть каталог з файлом `SKILL.md`: + +```bash +mkdir -p .claude/skills/my-command +``` + +**Файл:** `.claude/skills/my-command/SKILL.md` + +```yaml +--- +name: my-command +description: Що робить ця команда і коли її використовувати +--- + +# My Command + +Інструкції для Claude при виклику цієї команди. + +1. Перший крок +2. Другий крок +3. Третій крок +``` + +### Довідник фронтматеру + +| Поле | Призначення | За замовчуванням | +|------|------------|-----------------| +| `name` | Ім'я команди (стає `/name`) | Ім'я каталогу | +| `description` | Короткий опис (допомагає Claude знати коли використовувати) | Перший абзац | +| `argument-hint` | Очікувані аргументи для автодоповнення | Немає | +| `allowed-tools` | Інструменти без запиту дозволу | Успадковується | +| `model` | Конкретна модель для використання | Успадковується | +| `disable-model-invocation` | Якщо `true`, тільки користувач може викликати | `false` | +| `user-invocable` | Якщо `false`, сховати з меню `/` | `true` | +| `context` | `fork` для запуску в ізольованому субагенті | Немає | +| `agent` | Тип агента при `context: fork` | `general-purpose` | +| `hooks` | Хуки на рівні навички (PreToolUse, PostToolUse, Stop) | Немає | + +### Аргументи + +Команди можуть отримувати аргументи: + +**Усі аргументи з `$ARGUMENTS`:** + +```yaml +--- +name: fix-issue +description: Fix a GitHub issue by number +--- + +Fix issue #$ARGUMENTS following our coding standards +``` + +Використання: `/fix-issue 123` → `$ARGUMENTS` стає "123" + +**Окремі аргументи з `$0`, `$1` тощо:** + +```yaml +--- +name: review-pr +description: Review a PR with priority +--- + +Review PR #$0 with priority $1 +``` + +Використання: `/review-pr 456 high` → `$0`="456", `$1`="high" + +### Динамічний контекст з shell-командами + +Виконуйте bash-команди перед промптом з допомогою `` !`command` ``: + +```yaml +--- +name: commit +description: Create a git commit with context +allowed-tools: Bash(git *) +--- + +## Context + +- Current git status: !`git status` +- Current git diff: !`git diff HEAD` +- Current branch: !`git branch --show-current` +- Recent commits: !`git log --oneline -5` + +## Your task + +Based on the above changes, create a single git commit. +``` + +### Посилання на файли + +Включайте вміст файлів з `@`: + +```markdown +Review the implementation in @src/utils/helpers.js +Compare @src/old-version.js with @src/new-version.js +``` + +## Команди плагінів + +Плагіни можуть надавати кастомні команди: + +``` +/plugin-name:command-name +``` + +Або просто `/command-name`, якщо немає конфліктів імен. + +**Приклади:** + +```bash +/frontend-design:frontend-design +/commit-commands:commit +``` + +## MCP-промпти як команди + +MCP-сервери можуть надавати промпти як слеш-команди: + +``` +/mcp____ [arguments] +``` + +**Приклади:** + +```bash +/mcp__github__list_prs +/mcp__github__pr_review 456 +/mcp__jira__create_issue "Bug title" high +``` + +### Синтаксис дозволів MCP + +Контроль доступу до MCP-серверів у дозволах: + +- `mcp__github` — Доступ до всього GitHub MCP-сервера +- `mcp__github__*` — Wildcard-доступ до всіх інструментів +- `mcp__github__get_issue` — Доступ до конкретного інструменту + +## Архітектура команд + +```mermaid +graph TD + A["User Input: /command-name"] --> B{"Command Type?"} + B -->|Built-in| C["Execute Built-in"] + B -->|Skill| D["Load SKILL.md"] + B -->|Plugin| E["Load Plugin Command"] + B -->|MCP| F["Execute MCP Prompt"] + + D --> G["Parse Frontmatter"] + G --> H["Substitute Variables"] + H --> I["Execute Shell Commands"] + I --> J["Send to Claude"] + J --> K["Return Results"] +``` + +## Життєвий цикл команди + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: Types /optimize + Claude->>FS: Searches .claude/skills/ and .claude/commands/ + FS-->>Claude: Returns optimize/SKILL.md + Claude->>Claude: Parses frontmatter + Claude->>CLI: Executes !`command` substitutions + CLI-->>Claude: Command outputs + Claude->>Claude: Substitutes $ARGUMENTS + Claude->>User: Processes prompt + Claude->>User: Returns results +``` + +## Доступні команди в цьому каталозі + +Ці приклади команд можна встановити як навички або legacy-команди. + +### 1. `/optimize` — Оптимізація коду + +Аналізує код на проблеми продуктивності, витоки пам'яті та можливості оптимізації. + +**Використання:** + +``` +/optimize +[Вставте ваш код] +``` + +### 2. `/pr` — Підготовка Pull Request + +Проводить через чекліст підготовки PR, включаючи лінтинг, тестування та форматування комітів. + +**Використання:** + +``` +/pr +``` + +**Скріншот:** +![/pr](../../01-slash-commands/pr-slash-command.png) + +### 3. `/generate-api-docs` — Генератор API-документації + +Генерує комплексну API-документацію з вихідного коду. + +**Використання:** + +``` +/generate-api-docs +``` + +### 4. `/commit` — Git-коміт з контекстом + +Створює git-коміт з динамічним контекстом вашого репозиторію. + +**Використання:** + +``` +/commit [необов'язкове повідомлення] +``` + +### 5. `/push-all` — Stage, Commit та Push + +Stage всіх змін, створення коміту та push на remote з перевірками безпеки. + +**Використання:** + +``` +/push-all +``` + +**Перевірки безпеки:** + +- Секрети: `.env*`, `*.key`, `*.pem`, `credentials.json` +- API-ключі: Виявлення реальних ключів vs. заповнювачів +- Великі файли: `>10MB` без Git LFS +- Артефакти збірки: `node_modules/`, `dist/`, `__pycache__/` + +### 6. `/doc-refactor` — Реструктуризація документації + +Реструктуризує документацію проекту для ясності та доступності. + +**Використання:** + +``` +/doc-refactor +``` + +### 7. `/setup-ci-cd` — Налаштування CI/CD-пайплайну + +Впроваджує pre-commit хуки та GitHub Actions для контролю якості. + +**Використання:** + +``` +/setup-ci-cd +``` + +### 8. `/unit-test-expand` — Розширення покриття тестами + +Збільшує покриття тестами, націлюючись на непротестовані гілки та крайові випадки. + +**Використання:** + +``` +/unit-test-expand +``` + +## Встановлення + +### Як навички (Рекомендовано) + +Скопіюйте у каталог навичок: + +```bash +# Створити каталог навичок +mkdir -p .claude/skills + +# Для кожного файлу команди створити каталог навички +for cmd in optimize pr commit; do + mkdir -p .claude/skills/$cmd + cp 01-slash-commands/$cmd.md .claude/skills/$cmd/SKILL.md +done +``` + +### Як legacy-команди + +Скопіюйте у каталог команд: + +```bash +# На рівні проекту (команда) +mkdir -p .claude/commands +cp 01-slash-commands/*.md .claude/commands/ + +# Персональне використання +mkdir -p ~/.claude/commands +cp 01-slash-commands/*.md ~/.claude/commands/ +``` + +## Створення власних команд + +### Шаблон навички (Рекомендовано) + +Створіть `.claude/skills/my-command/SKILL.md`: + +```yaml +--- +name: my-command +description: What this command does. Use when [trigger conditions]. +argument-hint: [optional-args] +allowed-tools: Bash(npm *), Read, Grep +--- + +# Command Title + +## Context + +- Current branch: !`git branch --show-current` +- Related files: @package.json + +## Instructions + +1. First step +2. Second step with argument: $ARGUMENTS +3. Third step + +## Output Format + +- How to format the response +- What to include +``` + +### Команда лише для користувача (без автовиклику) + +Для команд з побічними ефектами, які Claude не повинен запускати автоматично: + +```yaml +--- +name: deploy +description: Deploy to production +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +Deploy the application to production: + +1. Run tests +2. Build application +3. Push to deployment target +4. Verify deployment +``` + +## Найкращі практики + +| Робіть | Не робіть | +|--------|-----------| +| Використовуйте чіткі, орієнтовані на дію назви | Не створюйте команди для одноразових завдань | +| Додавайте `description` з умовами тригеру | Не вбудовуйте складну логіку в команди | +| Тримайте команди зосередженими на одному завданні | Не хардкодьте чутливу інформацію | +| Використовуйте `disable-model-invocation` для побічних ефектів | Не пропускайте поле description | +| Використовуйте `!` для динамічного контексту | Не вважайте, що Claude знає поточний стан | +| Організуйте пов'язані файли в каталогах навичок | Не кладіть все в один файл | + +## Усунення неполадок + +### Команда не знайдена + +**Рішення:** + +- Перевірте, що файл у `.claude/skills//SKILL.md` або `.claude/commands/.md` +- Перевірте поле `name` у фронтматері +- Перезапустіть сесію Claude Code +- Запустіть `/help` для перегляду доступних команд + +### Команда працює не як очікувалось + +**Рішення:** + +- Додайте більш конкретні інструкції +- Включіть приклади у файл навички +- Перевірте `allowed-tools` при використанні bash-команд +- Спочатку тестуйте з простими вхідними даними + +### Конфлікт навички та команди + +Якщо обидві існують з однаковим ім'ям, **навичка має пріоритет**. Видаліть одну або перейменуйте. + +## Пов'язані посібники + +- **[Навички](../03-skills/)** — Повний довідник навичок (автоматично викликані можливості) +- **[Пам'ять](../02-memory/)** — Постійний контекст з CLAUDE.md +- **[Субагенти](../04-subagents/)** — Делеговані AI-агенти +- **[Плагіни](../07-plugins/)** — Пакетні набори команд +- **[Хуки](../06-hooks/)** — Автоматизація на основі подій + +## Додаткові ресурси + +- [Офіційна документація інтерактивного режиму](https://code.claude.com/docs/en/interactive-mode) — Довідник вбудованих команд +- [Офіційна документація навичок](https://code.claude.com/docs/en/skills) — Повний довідник навичок +- [Довідник CLI](https://code.claude.com/docs/en/cli-reference) — Опції командного рядка + +--- + +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 + +*Частина серії посібників [Claude How To](../)* diff --git a/uk/01-slash-commands/commit.md b/uk/01-slash-commands/commit.md new file mode 100644 index 0000000..be705c8 --- /dev/null +++ b/uk/01-slash-commands/commit.md @@ -0,0 +1,29 @@ +--- +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*) +argument-hint: [message] +description: Створити git-коміт з контекстом +--- + +## Контекст + +- Поточний статус git: !`git status` +- Поточний git diff: !`git diff HEAD` +- Поточна гілка: !`git branch --show-current` +- Останні коміти: !`git log --oneline -10` + +## Ваше завдання + +На основі наведених вище змін створіть один git-коміт. + +Якщо повідомлення було передано через аргументи, використовуйте його: $ARGUMENTS + +Інакше проаналізуйте зміни та створіть відповідне повідомлення коміту відповідно до формату conventional commits: +- `feat:` для нових функцій +- `fix:` для виправлення помилок +- `docs:` для змін документації +- `refactor:` для рефакторингу коду +- `test:` для додавання тестів +- `chore:` для задач обслуговування + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/01-slash-commands/doc-refactor.md b/uk/01-slash-commands/doc-refactor.md new file mode 100644 index 0000000..e56a8a6 --- /dev/null +++ b/uk/01-slash-commands/doc-refactor.md @@ -0,0 +1,27 @@ +--- +name: Documentation Refactor +description: Реструктуризація документації проєкту для ясності та доступності +tags: documentation, refactoring, organization +--- + +# Рефакторинг документації + +Рефакторинг структури документації проєкту з адаптацією до типу проєкту: + +1. **Аналіз проєкту**: Визначити тип (бібліотека/API/веб-додаток/CLI/мікросервіси), архітектуру та персони користувачів +2. **Централізація документації**: Перемістити технічну документацію до `docs/` з належними перехресними посиланнями +3. **Кореневий README.md**: Оптимізувати як точку входу з оглядом, швидким стартом, резюме модулів/компонентів, ліцензією, контактами +4. **Документація компонентів**: Додати README файли на рівні модулів/пакетів/сервісів з інструкціями налаштування та тестування +5. **Організація `docs/`** за відповідними категоріями: + - Архітектура, Довідник API, База даних, Дизайн, Усунення несправностей, Деплой, Контрибʼюція (адаптувати до потреб проєкту) +6. **Створення посібників** (оберіть застосовні): + - Посібник користувача: Документація для кінцевих користувачів додатків + - Документація API: Ендпоінти, автентифікація, приклади для API + - Посібник розробника: Налаштування, тестування, процес контрибʼюції + - Посібник деплою: Деплой на продакшн для сервісів/додатків +7. **Використання Mermaid** для всіх діаграм (архітектура, потоки, схеми) + +Тримайте документацію лаконічною, зручною для сканування та контекстно відповідною типу проєкту. + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/01-slash-commands/generate-api-docs.md b/uk/01-slash-commands/generate-api-docs.md new file mode 100644 index 0000000..1d0717f --- /dev/null +++ b/uk/01-slash-commands/generate-api-docs.md @@ -0,0 +1,22 @@ +--- +description: Створення вичерпної документації API з вихідного коду +--- + +# Генератор документації API + +Генерація документації API шляхом: + +1. Сканування всіх файлів у `/src/api/` +2. Витягу сигнатур функцій та коментарів JSDoc +3. Організації за ендпоінтом/модулем +4. Створення markdown з прикладами +5. Включення схем запитів/відповідей +6. Додавання документації помилок + +Формат виводу: +- Markdown-файл у `/docs/api.md` +- Включити приклади curl для всіх ендпоінтів +- Додати типи TypeScript + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/01-slash-commands/optimize.md b/uk/01-slash-commands/optimize.md new file mode 100644 index 0000000..9f56ac5 --- /dev/null +++ b/uk/01-slash-commands/optimize.md @@ -0,0 +1,22 @@ +--- +description: Аналіз коду на проблеми продуктивності та пропозиції оптимізацій +--- + +# Оптимізація коду + +Перегляньте наданий код на наявність таких проблем у порядку пріоритету: + +1. **Вузькі місця продуктивності** — виявлення операцій O(n²), неефективних циклів +2. **Витоки памʼяті** — пошук невивільнених ресурсів, циклічних посилань +3. **Покращення алгоритмів** — пропозиція кращих алгоритмів або структур даних +4. **Можливості кешування** — виявлення повторюваних обчислень +5. **Проблеми конкурентності** — пошук станів гонки (race conditions) або проблем з потоками + +Формат відповіді: +- Серйозність проблеми (Критична/Висока/Середня/Низька) +- Місце в коді +- Пояснення +- Рекомендоване виправлення з прикладом коду + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/01-slash-commands/pr-slash-command.png b/uk/01-slash-commands/pr-slash-command.png new file mode 100644 index 0000000..789e5c2 Binary files /dev/null and b/uk/01-slash-commands/pr-slash-command.png differ diff --git a/uk/01-slash-commands/pr.md b/uk/01-slash-commands/pr.md new file mode 100644 index 0000000..fd45139 --- /dev/null +++ b/uk/01-slash-commands/pr.md @@ -0,0 +1,29 @@ +--- +description: Очистити код, підготувати зміни та створити pull request +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(npm test:*), Bash(npm run lint:*) +--- + +# Контрольний список підготовки Pull Request + +Перед створенням PR виконайте ці кроки: + +1. Запустити лінтинг: `prettier --write .` +2. Запустити тести: `npm test` +3. Переглянути git diff: `git diff HEAD` +4. Додати зміни до індексу: `git add .` +5. Створити повідомлення коміту відповідно до conventional commits: + - `fix:` для виправлення помилок + - `feat:` для нових функцій + - `docs:` для документації + - `refactor:` для реструктуризації коду + - `test:` для додавання тестів + - `chore:` для обслуговування + +6. Згенерувати опис PR, що включає: + - Що змінилося + - Чому змінилося + - Проведене тестування + - Потенційні наслідки + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/01-slash-commands/push-all.md b/uk/01-slash-commands/push-all.md new file mode 100644 index 0000000..169d2b4 --- /dev/null +++ b/uk/01-slash-commands/push-all.md @@ -0,0 +1,155 @@ +--- +description: Додати всі зміни до індексу, створити коміт та відправити на віддалений сервер (використовуйте з обережністю) +allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git push:*), Bash(git diff:*), Bash(git log:*), Bash(git pull:*) +--- + +# Коміт та Push усього + +⚠️ **УВАГА**: Додає ВСІ зміни до індексу, створює коміт та відправляє на віддалений сервер. Використовуйте лише коли впевнені, що всі зміни належать разом. + +## Робочий процес + +### 1. Аналіз змін +Запустити паралельно: +- `git status` — показати змінені/додані/видалені/невідстежувані файли +- `git diff --stat` — показати статистику змін +- `git log -1 --oneline` — показати останній коміт для стилю повідомлення + +### 2. Перевірки безпеки + +**❌ ЗУПИНИТИ та ПОПЕРЕДИТИ при виявленні:** +- Секрети: `.env*`, `*.key`, `*.pem`, `credentials.json`, `secrets.yaml`, `id_rsa`, `*.p12`, `*.pfx`, `*.cer` +- API-ключі: Будь-які змінні `*_API_KEY`, `*_SECRET`, `*_TOKEN` з реальними значеннями (не заповнювачі типу `your-api-key`, `xxx`, `placeholder`) +- Великі файли: `>10MB` без Git LFS +- Артефакти збірки: `node_modules/`, `dist/`, `build/`, `__pycache__/`, `*.pyc`, `.venv/` +- Тимчасові файли: `.DS_Store`, `thumbs.db`, `*.swp`, `*.tmp` + +**Валідація API-ключів:** +Перевірити змінені файли на патерни: +```bash +OPENAI_API_KEY=sk-proj-xxxxx # ❌ Виявлено реальний ключ! +AWS_SECRET_KEY=AKIA... # ❌ Виявлено реальний ключ! +STRIPE_API_KEY=sk_live_... # ❌ Виявлено реальний ключ! + +# ✅ Допустимі заповнювачі: +API_KEY=your-api-key-here +SECRET_KEY=placeholder +TOKEN=xxx +API_KEY= +SECRET=${YOUR_SECRET} +``` + +**✅ Перевірити:** +- `.gitignore` правильно налаштований +- Немає конфліктів злиття +- Правильна гілка (попередити якщо main/master) +- API-ключі є лише заповнювачами + +### 3. Запит підтвердження + +Представити резюме: +``` +📊 Резюме змін: +- X файлів змінено, Y додано, Z видалено +- Загалом: +AAA вставок, -BBB видалень + +🔒 Безпека: ✅ Без секретів | ✅ Без великих файлів | ⚠️ [попередження] +🌿 Гілка: [назва] → origin/[назва] + +Я виконаю: git add . → commit → push + +Введіть 'yes' для продовження або 'no' для скасування. +``` + +**ЧЕКАТИ явного "yes" перед продовженням.** + +### 4. Виконання (після підтвердження) + +Запустити послідовно: +```bash +git add . +git status # Перевірка індексу +``` + +### 5. Генерація повідомлення коміту + +Проаналізувати зміни та створити conventional commit: + +**Формат:** +``` +[тип]: Короткий опис (макс. 72 символи) + +- Ключова зміна 1 +- Ключова зміна 2 +- Ключова зміна 3 +``` + +**Типи:** `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `build`, `ci` + +**Приклад:** +``` +docs: Update concept README files with comprehensive documentation + +- Add architecture diagrams and tables +- Include practical examples +- Expand best practices sections +``` + +### 6. Коміт та Push + +```bash +git commit -m "$(cat <<'EOF' +[Згенероване повідомлення коміту] +EOF +)" +git push # Якщо невдача: git pull --rebase && git push +git log -1 --oneline --decorate # Перевірка +``` + +### 7. Підтвердження успіху + +``` +✅ Успішно відправлено на віддалений сервер! + +Коміт: [хеш] [повідомлення] +Гілка: [гілка] → origin/[гілка] +Змінено файлів: X (+вставок, -видалень) +``` + +## Обробка помилок + +- **git add невдача**: Перевірити дозволи, заблоковані файли, переконатися що репо ініціалізовано +- **git commit невдача**: Виправити pre-commit хуки, перевірити git config (user.name/email) +- **git push невдача**: + - Non-fast-forward: `git pull --rebase && git push` + - Немає віддаленої гілки: `git push -u origin [гілка]` + - Захищена гілка: Використати PR-процес замість цього + +## Коли використовувати + +✅ **Доцільно:** +- Оновлення документації в кількох файлах +- Функція з тестами та документацією +- Виправлення помилок у кількох файлах +- Форматування/рефакторинг всього проєкту +- Зміни конфігурації + +❌ **Уникати:** +- Невпевненість у тому, що комітиться +- Містить секрети/чутливі дані +- Захищені гілки без рев'ю +- Присутні конфлікти злиття +- Потрібна гранулярна історія комітів +- Pre-commit хуки не проходять + +## Альтернативи + +Якщо користувач хоче більше контролю, запропонувати: +1. **Вибіркове додавання**: Переглянути/додати конкретні файли +2. **Інтерактивне додавання**: `git add -p` для вибору патчів +3. **PR-процес**: Створити гілку → push → PR (використати команду `/pr`) + +**⚠️ Памʼятайте**: Завжди переглядайте зміни перед push. Якщо сумніваєтесь, використовуйте окремі git-команди для більшого контролю. + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/01-slash-commands/setup-ci-cd.md b/uk/01-slash-commands/setup-ci-cd.md new file mode 100644 index 0000000..e6af565 --- /dev/null +++ b/uk/01-slash-commands/setup-ci-cd.md @@ -0,0 +1,28 @@ +--- +name: Setup CI/CD Pipeline +description: Реалізація pre-commit хуків та GitHub Actions для забезпечення якості +tags: ci-cd, devops, automation +--- + +# Налаштування CI/CD пайплайну + +Реалізація комплексних шлюзів якості DevOps з адаптацією до типу проєкту: + +1. **Аналіз проєкту**: Визначити мову(и), фреймворк, систему збірки та наявний інструментарій +2. **Налаштування pre-commit хуків** з інструментами для конкретної мови: + - Форматування: Prettier/Black/gofmt/rustfmt/тощо + - Лінтинг: ESLint/Ruff/golangci-lint/Clippy/тощо + - Безпека: Bandit/gosec/cargo-audit/npm audit/тощо + - Перевірка типів: TypeScript/mypy/flow (якщо застосовно) + - Тести: Запуск відповідних тестових наборів +3. **Створення GitHub Actions workflows** (.github/workflows/): + - Дзеркалювання pre-commit перевірок на push/PR + - Матриця версій/платформ (якщо застосовно) + - Верифікація збірки та тестів + - Кроки деплою (за потреби) +4. **Верифікація пайплайну**: Тестування локально, створення тестового PR, підтвердження проходження всіх перевірок + +Використовуйте безкоштовні/відкриті інструменти. Поважайте існуючі конфігурації. Тримайте виконання швидким. + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/01-slash-commands/unit-test-expand.md b/uk/01-slash-commands/unit-test-expand.md new file mode 100644 index 0000000..6568ff4 --- /dev/null +++ b/uk/01-slash-commands/unit-test-expand.md @@ -0,0 +1,28 @@ +--- +name: Expand Unit Tests +description: Збільшення покриття тестами шляхом тестування невідстежених гілок та граничних випадків +tags: testing, coverage, unit-tests +--- + +# Розширення юніт-тестів + +Розширення існуючих юніт-тестів з адаптацією до тестового фреймворку проєкту: + +1. **Аналіз покриття**: Запустити звіт покриття для виявлення неперевірених гілок, граничних випадків та зон з низьким покриттям +2. **Виявлення прогалин**: Переглянути код на предмет логічних гілок, шляхів помилок, граничних умов, null/порожніх вхідних даних +3. **Написання тестів** з використанням фреймворку проєкту: + - Jest/Vitest/Mocha (JavaScript/TypeScript) + - pytest/unittest (Python) + - Go testing/testify (Go) + - Rust test framework (Rust) +4. **Цільові сценарії**: + - Обробка помилок та виключень + - Граничні значення (мін/макс, порожні, null) + - Крайні та кутові випадки (edge/corner cases) + - Переходи станів та побічні ефекти +5. **Верифікація покращення**: Запустити покриття повторно, підтвердити вимірюване збільшення + +Представляти лише нові блоки тестового коду. Дотримуватися існуючих патернів та конвенцій іменування тестів. + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/02-memory/README.md b/uk/02-memory/README.md new file mode 100644 index 0000000..66bbf45 --- /dev/null +++ b/uk/02-memory/README.md @@ -0,0 +1,1159 @@ + + + + + + + Claude How To + + +# Посібник з пам'яті + +Пам'ять дозволяє Claude зберігати контекст між сесіями та розмовами. Вона існує у двох формах: автоматичний синтез у claude.ai та файлова система CLAUDE.md у Claude Code. + +## Огляд + +Пам'ять у Claude Code забезпечує постійний контекст, який зберігається між кількома сесіями та розмовами. На відміну від тимчасового контекстного вікна, файли пам'яті дозволяють: + +- Поширювати стандарти проєкту на всю команду +- Зберігати персональні налаштування розробки +- Підтримувати правила та конфігурації для конкретних каталогів +- Імпортувати зовнішню документацію +- Версіонувати пам'ять як частину проєкту + +Система пам'яті працює на кількох рівнях — від глобальних персональних налаштувань до конкретних підкаталогів — забезпечуючи детальний контроль над тим, що Claude запам'ятовує і як застосовує ці знання. + +## Короткий довідник команд пам'яті + +| Команда | Призначення | Використання | Коли застосовувати | +|---------|------------|--------------|-------------------| +| `/init` | Ініціалізація пам'яті проєкту | `/init` | Початок нового проєкту, перше налаштування CLAUDE.md | +| `/memory` | Редагування файлів пам'яті в редакторі | `/memory` | Великі оновлення, реорганізація, перегляд вмісту | +| Префікс `#` | ~~Швидке додавання однорядкового правила~~ **Припинено** | — | Використовуйте `/memory` або просіть у розмові | +| `@шлях/до/файлу` | Імпорт зовнішнього вмісту | `@README.md` або `@docs/api.md` | Посилання на наявну документацію в CLAUDE.md | + +## Швидкий старт: ініціалізація пам'яті + +### Команда `/init` + +Команда `/init` — найшвидший спосіб налаштувати пам'ять проєкту в Claude Code. Вона ініціалізує файл CLAUDE.md з базовою документацією проєкту. + +**Використання:** + +```bash +/init +``` + +**Що вона робить:** + +- Створює новий файл CLAUDE.md у проєкті (зазвичай `./CLAUDE.md` або `./.claude/CLAUDE.md`) +- Встановлює конвенції та рекомендації проєкту +- Закладає основу для збереження контексту між сесіями +- Надає шаблонну структуру для документування стандартів проєкту + +**Покращений інтерактивний режим:** Встановіть `CLAUDE_CODE_NEW_INIT=1`, щоб увімкнути багатофазний інтерактивний потік, який крок за кроком проведе вас через налаштування проєкту: + +```bash +CLAUDE_CODE_NEW_INIT=1 claude +/init +``` + +**Коли використовувати `/init`:** + +- Початок нового проєкту з Claude Code +- Встановлення командних стандартів кодування +- Створення документації про структуру кодової бази +- Налаштування ієрархії пам'яті для колективної розробки + +**Приклад робочого процесу:** + +```markdown +# У каталозі вашого проєкту +/init + +# Claude створює CLAUDE.md зі структурою: +# Конфігурація проєкту +## Огляд проєкту +- Назва: Ваш Проєкт +- Стек технологій: [Ваші технології] +- Розмір команди: [Кількість розробників] + +## Стандарти розробки +- Стиль коду +- Вимоги до тестування +- Конвенції Git-воркфлову +``` + +### Швидкі оновлення пам'яті + +> **Примітка**: Ярлик `#` для вбудованого додавання до пам'яті було припинено. Використовуйте `/memory` для прямого редагування файлів пам'яті або попросіть Claude в розмові запам'ятати щось (наприклад, "запам'ятай, що ми завжди використовуємо TypeScript strict mode"). + +Рекомендовані способи додавання інформації до пам'яті: + +**Варіант 1: Команда `/memory`** + +```bash +/memory +``` + +Відкриває файли пам'яті у вашому системному редакторі для прямого редагування. + +**Варіант 2: Запит у розмові** + +``` +Remember that we always use TypeScript strict mode in this project. +Please add to memory: prefer async/await over promise chains. +``` + +Claude оновить відповідний файл CLAUDE.md на основі вашого запиту. + +**Історична довідка** (більше не працює): + +Ярлик із префіксом `#` раніше дозволяв додавати правила прямо в розмові: + +```markdown +# Always use TypeScript strict mode in this project ← більше не працює +``` + +Якщо ви використовували цей шаблон, перейдіть на команду `/memory` або запити в розмові. + +### Команда `/memory` + +Команда `/memory` надає прямий доступ до редагування файлів пам'яті CLAUDE.md у сесіях Claude Code. Вона відкриває файли пам'яті у вашому системному редакторі для комплексного редагування. + +**Використання:** + +```bash +/memory +``` + +**Що вона робить:** + +- Відкриває файли пам'яті у стандартному редакторі системи +- Дозволяє робити великі доповнення, модифікації та реорганізацію +- Надає прямий доступ до всіх файлів пам'яті в ієрархії +- Дає змогу керувати постійним контекстом між сесіями + +**Коли використовувати `/memory`:** + +- Перегляд наявного вмісту пам'яті +- Великі оновлення стандартів проєкту +- Реорганізація структури пам'яті +- Додавання детальної документації чи рекомендацій +- Підтримка та оновлення пам'яті в міру розвитку проєкту + +**Порівняння: `/memory` та `/init`** + +| Аспект | `/memory` | `/init` | +|--------|-----------|---------| +| **Призначення** | Редагування наявних файлів пам'яті | Ініціалізація нового CLAUDE.md | +| **Коли** | Оновлення/модифікація контексту проєкту | Початок нового проєкту | +| **Дія** | Відкриває редактор для змін | Генерує стартовий шаблон | +| **Воркфлов** | Постійна підтримка | Одноразове налаштування | + +**Приклад робочого процесу:** + +```markdown +# Відкрити пам'ять для редагування +/memory + +# Claude пропонує варіанти: +# 1. Managed Policy Memory +# 2. Project Memory (./CLAUDE.md) +# 3. User Memory (~/.claude/CLAUDE.md) +# 4. Local Project Memory + +# Оберіть варіант 2 (Project Memory) +# Стандартний редактор відкриє вміст ./CLAUDE.md + +# Внесіть зміни, збережіть і закрийте редактор +# Claude автоматично перезавантажить оновлену пам'ять +``` + +**Використання імпортів у пам'яті:** + +Файли CLAUDE.md підтримують синтаксис `@шлях/до/файлу` для включення зовнішнього вмісту: + +```markdown +# Документація проєкту +See @README.md for project overview +See @package.json for available npm commands +See @docs/architecture.md for system design + +# Імпорт з домашнього каталогу за абсолютним шляхом +@~/.claude/my-project-instructions.md +``` + +**Можливості імпорту:** + +- Підтримуються відносні та абсолютні шляхи (наприклад, `@docs/api.md` або `@~/.claude/my-project-instructions.md`) +- Підтримуються рекурсивні імпорти з максимальною глибиною 5 +- Перший імпорт із зовнішнього розташування викликає діалог підтвердження для безпеки +- Директиви імпорту не обробляються всередині code span та code block у Markdown (тому їх безпечно документувати в прикладах) +- Допомагає уникнути дублювання, посилаючись на наявну документацію +- Автоматично включає вміст посилань у контекст Claude + +## Архітектура пам'яті + +Пам'ять у Claude Code побудована за ієрархічною системою, де різні рівні виконують різні функції: + +```mermaid +graph TB + A["Claude Session"] + B["User Input"] + C["Memory System"] + D["Memory Storage"] + + B -->|User provides info| C + C -->|Synthesizes every 24h| D + D -->|Loads automatically| A + A -->|Uses context| C +``` + +## Ієрархія пам'яті в Claude Code + +Claude Code використовує багаторівневу ієрархічну систему пам'яті. Файли пам'яті автоматично завантажуються при запуску Claude Code, причому файли вищого рівня мають більший пріоритет. + +**Повна ієрархія пам'яті (за пріоритетом):** + +1. **Managed Policy** — загальноорганізаційні інструкції + - macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md` + - Linux/WSL: `/etc/claude-code/CLAUDE.md` + - Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` + +2. **Managed Drop-ins** — модульні файли політик, об'єднані за алфавітом (v2.1.83+) + - Каталог `managed-settings.d/` поруч із файлом managed policy CLAUDE.md + +3. **Project Memory** — спільний контекст команди (версіонований) + - `./.claude/CLAUDE.md` або `./CLAUDE.md` (у корені репозиторію) + +4. **Project Rules** — модульні, тематичні інструкції проєкту + - `./.claude/rules/*.md` + +5. **User Memory** — персональні налаштування (для всіх проєктів) + - `~/.claude/CLAUDE.md` + +6. **User-Level Rules** — персональні правила (для всіх проєктів) + - `~/.claude/rules/*.md` + +7. **Local Project Memory** — персональні налаштування конкретного проєкту + - `./CLAUDE.local.md` + +> **Примітка**: `CLAUDE.local.md` повністю підтримується та задокументований в [офіційній документації](https://code.claude.com/docs/en/memory). Він зберігає персональні налаштування проєкту, які не комітяться у систему контролю версій. Додайте `CLAUDE.local.md` до `.gitignore`. + +8. **Auto Memory** — автоматичні нотатки та висновки Claude + - `~/.claude/projects//memory/` + +**Поведінка пошуку пам'яті:** + +Claude шукає файли пам'яті у такому порядку, причому раніші розташування мають більший пріоритет: + +```mermaid +graph TD + A["Managed Policy
/Library/.../ClaudeCode/CLAUDE.md"] -->|highest priority| A2["Managed Drop-ins
managed-settings.d/"] + A2 --> B["Project Memory
./CLAUDE.md"] + B --> C["Project Rules
./.claude/rules/*.md"] + C --> D["User Memory
~/.claude/CLAUDE.md"] + D --> E["User Rules
~/.claude/rules/*.md"] + E --> F["Local Project Memory
./CLAUDE.local.md"] + F --> G["Auto Memory
~/.claude/projects/.../memory/"] + + B -->|imports| H["@docs/architecture.md"] + H -->|imports| I["@docs/api-standards.md"] + + style A fill:#fce4ec,stroke:#333,color:#333 + style A2 fill:#fce4ec,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 + style G fill:#fff3e0,stroke:#333,color:#333 + style H fill:#e1f5fe,stroke:#333,color:#333 + style I fill:#e1f5fe,stroke:#333,color:#333 +``` + +## Виключення файлів CLAUDE.md за допомогою `claudeMdExcludes` + +У великих монорепозиторіях деякі файли CLAUDE.md можуть бути нерелевантними для вашої поточної роботи. Налаштування `claudeMdExcludes` дозволяє пропускати певні файли CLAUDE.md, щоб вони не завантажувались у контекст: + +```jsonc +// В ~/.claude/settings.json або .claude/settings.json +{ + "claudeMdExcludes": [ + "packages/legacy-app/CLAUDE.md", + "vendors/**/CLAUDE.md" + ] +} +``` + +Патерни зіставляються зі шляхами відносно кореня проєкту. Це особливо корисно для: + +- Монорепозиторіїв з багатьма підпроєктами, де релевантні лише деякі +- Репозиторіїв із вендорними або сторонніми файлами CLAUDE.md +- Зменшення шуму в контекстному вікні Claude виключенням застарілих або нерелевантних інструкцій + +## Ієрархія файлів налаштувань + +Налаштування Claude Code (включаючи `autoMemoryDirectory`, `claudeMdExcludes` та іншу конфігурацію) визначаються з п'ятирівневої ієрархії, де вищі рівні мають більший пріоритет: + +| Рівень | Розташування | Область дії | +|--------|-------------|-------------| +| 1 (Найвищий) | Managed policy (системний рівень) | Загальноорганізаційне застосування | +| 2 | `managed-settings.d/` (v2.1.83+) | Модульні drop-in політики, об'єднані за алфавітом | +| 3 | `~/.claude/settings.json` | Налаштування користувача | +| 4 | `.claude/settings.json` | Рівень проєкту (комітиться в git) | +| 5 (Найнижчий) | `.claude/settings.local.json` | Локальні перевизначення (ігнорується git) | + +**Платформо-специфічна конфігурація (v2.1.51+):** + +Налаштування також можна конфігурувати через: +- **macOS**: файли Property list (plist) +- **Windows**: Реєстр Windows + +Ці платформо-нативні механізми зчитуються разом з JSON-файлами налаштувань і підпорядковуються тим самим правилам пріоритетності. + +## Модульна система правил + +Створюйте організовані, специфічні для шляхів правила за допомогою структури каталогу `.claude/rules/`. Правила можна визначати як на рівні проєкту, так і на рівні користувача: + +``` +your-project/ +├── .claude/ +│ ├── CLAUDE.md +│ └── rules/ +│ ├── code-style.md +│ ├── testing.md +│ ├── security.md +│ └── api/ # Підкаталоги підтримуються +│ ├── conventions.md +│ └── validation.md + +~/.claude/ +├── CLAUDE.md +└── rules/ # Правила рівня користувача (для всіх проєктів) + ├── personal-style.md + └── preferred-patterns.md +``` + +Правила знаходяться рекурсивно в каталозі `rules/`, включаючи підкаталоги. Правила рівня користувача з `~/.claude/rules/` завантажуються перед правилами рівня проєкту, дозволяючи персональні значення за замовчуванням, які проєкти можуть перевизначити. + +### Правила для конкретних шляхів із YAML-фронтматером + +Визначайте правила, що застосовуються лише до конкретних шляхів файлів: + +```markdown +--- +paths: src/api/**/*.ts +--- + +# API Development Rules + +- All API endpoints must include input validation +- Use Zod for schema validation +- Document all parameters and response types +- Include error handling for all operations +``` + +**Приклади glob-патернів:** + +- `**/*.ts` — всі TypeScript-файли +- `src/**/*` — всі файли в src/ +- `src/**/*.{ts,tsx}` — кілька розширень +- `{src,lib}/**/*.ts, tests/**/*.test.ts` — кілька патернів + +### Підкаталоги та симлінки + +Правила в `.claude/rules/` підтримують дві організаційні можливості: + +- **Підкаталоги**: правила знаходяться рекурсивно, тому їх можна організувати в тематичні папки (наприклад, `rules/api/`, `rules/testing/`, `rules/security/`) +- **Симлінки**: підтримуються для спільного використання правил між кількома проєктами. Наприклад, можна створити симлінк на спільний файл правил з центрального розташування в каталог `.claude/rules/` кожного проєкту + +## Таблиця розташувань пам'яті + +| Розташування | Область дії | Пріоритет | Спільний | Доступ | Найкраще для | +|-------------|-------------|-----------|---------|--------|-------------| +| `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS) | Managed Policy | 1 (Найвищий) | Організація | Система | Загальноорганізаційні політики | +| `/etc/claude-code/CLAUDE.md` (Linux/WSL) | Managed Policy | 1 (Найвищий) | Організація | Система | Стандарти організації | +| `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Managed Policy | 1 (Найвищий) | Організація | Система | Корпоративні рекомендації | +| `managed-settings.d/*.md` (поруч з policy) | Managed Drop-ins | 1.5 | Організація | Система | Модульні файли політик (v2.1.83+) | +| `./CLAUDE.md` або `./.claude/CLAUDE.md` | Project Memory | 2 | Команда | Git | Командні стандарти, спільна архітектура | +| `./.claude/rules/*.md` | Project Rules | 3 | Команда | Git | Модульні правила для конкретних шляхів | +| `~/.claude/CLAUDE.md` | User Memory | 4 | Індивідуальний | Файлова система | Персональні налаштування (всі проєкти) | +| `~/.claude/rules/*.md` | User Rules | 5 | Індивідуальний | Файлова система | Персональні правила (всі проєкти) | +| `./CLAUDE.local.md` | Project Local | 6 | Індивідуальний | Git (ігнорується) | Персональні налаштування проєкту | +| `~/.claude/projects//memory/` | Auto Memory | 7 (Найнижчий) | Індивідуальний | Файлова система | Автоматичні нотатки та висновки Claude | + +## Життєвий цикл оновлення пам'яті + +Ось як оновлення пам'яті проходять через сесії Claude Code: + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Editor as File System + participant Memory as CLAUDE.md + + User->>Claude: "Remember: use async/await" + Claude->>User: "Which memory file?" + User->>Claude: "Project memory" + Claude->>Editor: Open ~/.claude/settings.json + Claude->>Memory: Write to ./CLAUDE.md + Memory-->>Claude: File saved + Claude->>Claude: Load updated memory + Claude-->>User: "Memory saved!" +``` + +## Auto Memory + +Auto memory — це постійний каталог, куди Claude автоматично записує висновки, патерни та інсайти під час роботи з вашим проєктом. На відміну від файлів CLAUDE.md, які ви пишете та підтримуєте вручну, auto memory записується самим Claude під час сесій. + +### Як працює Auto Memory + +- **Розташування**: `~/.claude/projects//memory/` +- **Точка входу**: `MEMORY.md` — головний файл у каталозі auto memory +- **Тематичні файли**: додаткові файли для конкретних тем (наприклад, `debugging.md`, `api-conventions.md`) +- **Поведінка завантаження**: перші 200 рядків `MEMORY.md` (або перші 25 КБ — що менше) завантажуються в контекст на початку сесії. Тематичні файли завантажуються за потребою, не при запуску. +- **Читання/запис**: Claude читає та записує файли пам'яті під час сесій, виявляючи патерни та знання, специфічні для проєкту + +### Архітектура Auto Memory + +```mermaid +graph TD + A["Claude Session Starts"] --> B["Load MEMORY.md
(first 200 lines / 25KB)"] + B --> C["Session Active"] + C --> D["Claude discovers
patterns & insights"] + D --> E{"Write to
auto memory"} + E -->|General notes| F["MEMORY.md"] + E -->|Topic-specific| G["debugging.md"] + E -->|Topic-specific| H["api-conventions.md"] + C --> I["On-demand load
topic files"] + I --> C + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#fff3e0,stroke:#333,color:#333 + style F fill:#fce4ec,stroke:#333,color:#333 + style G fill:#fce4ec,stroke:#333,color:#333 + style H fill:#fce4ec,stroke:#333,color:#333 + style I fill:#f3e5f5,stroke:#333,color:#333 +``` + +### Структура каталогу Auto Memory + +``` +~/.claude/projects//memory/ +├── MEMORY.md # Точка входу (перші 200 рядків / 25 КБ завантажуються при запуску) +├── debugging.md # Тематичний файл (завантажується за потребою) +├── api-conventions.md # Тематичний файл (завантажується за потребою) +└── testing-patterns.md # Тематичний файл (завантажується за потребою) +``` + +### Вимога до версії + +Auto memory потребує **Claude Code v2.1.59 або новішої версії**. Якщо у вас старіша версія, спочатку оновіть: + +```bash +npm install -g @anthropic-ai/claude-code@latest +``` + +### Власний каталог Auto Memory + +За замовчуванням auto memory зберігається в `~/.claude/projects//memory/`. Ви можете змінити це розташування за допомогою налаштування `autoMemoryDirectory` (доступне з **v2.1.74**): + +```jsonc +// В ~/.claude/settings.json або .claude/settings.local.json (тільки налаштування користувача/локальні) +{ + "autoMemoryDirectory": "/path/to/custom/memory/directory" +} +``` + +> **Примітка**: `autoMemoryDirectory` можна встановити лише в налаштуваннях рівня користувача (`~/.claude/settings.json`) або локальних налаштуваннях (`.claude/settings.local.json`), а не в налаштуваннях проєкту чи managed policy. + +Це корисно, коли ви хочете: + +- Зберігати auto memory у спільному або синхронізованому розташуванні +- Відокремити auto memory від стандартного каталогу конфігурації Claude +- Використовувати шлях, специфічний для проєкту, поза стандартною ієрархією + +### Спільне використання Worktree та репозиторію + +Усі робочі дерева (worktrees) та підкаталоги в межах одного git-репозиторію використовують один каталог auto memory. Це означає, що перемикання між worktrees або робота в різних підкаталогах одного репо читатиме та записуватиме ті самі файли пам'яті. + +### Пам'ять субагентів + +Субагенти (створені через інструменти на кшталт Task або паралельного виконання) можуть мати власний контекст пам'яті. Використовуйте поле `memory` у фронтматері визначення субагента, щоб вказати, які рівні пам'яті завантажувати: + +```yaml +memory: user # Завантажити лише пам'ять рівня користувача +memory: project # Завантажити лише пам'ять рівня проєкту +memory: local # Завантажити лише локальну пам'ять +``` + +Це дозволяє субагентам працювати з фокусованим контекстом, а не успадковувати повну ієрархію пам'яті. + +> **Примітка**: Субагенти також можуть підтримувати власну auto memory. Див. [офіційну документацію пам'яті субагентів](https://code.claude.com/docs/en/sub-agents#enable-persistent-memory) для деталей. + +### Керування Auto Memory + +Auto memory можна контролювати через змінну оточення `CLAUDE_CODE_DISABLE_AUTO_MEMORY`: + +| Значення | Поведінка | +|----------|----------| +| `0` | Примусово **увімкнути** auto memory | +| `1` | Примусово **вимкнути** auto memory | +| *(не встановлено)* | Стандартна поведінка (auto memory увімкнено) | + +```bash +# Вимкнути auto memory для сесії +CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude + +# Примусово увімкнути auto memory +CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 claude +``` + +## Додаткові каталоги з `--add-dir` + +Прапорець `--add-dir` дозволяє Claude Code завантажувати файли CLAUDE.md з додаткових каталогів, окрім поточного робочого каталогу. Це корисно для монорепозиторіїв або мультипроєктних конфігурацій, де контекст з інших каталогів є релевантним. + +Для увімкнення цієї функції встановіть змінну оточення: + +```bash +CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 +``` + +Потім запустіть Claude Code з прапорцем: + +```bash +claude --add-dir /path/to/other/project +``` + +Claude завантажить CLAUDE.md із зазначеного додаткового каталогу разом з файлами пам'яті з вашого поточного робочого каталогу. + +## Практичні приклади + +### Приклад 1: Структура пам'яті проєкту + +**Файл:** `./CLAUDE.md` + +```markdown +# Project Configuration + +## Project Overview +- **Name**: E-commerce Platform +- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker +- **Team Size**: 5 developers +- **Deadline**: Q4 2025 + +## Architecture +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## Development Standards + +### Code Style +- Use Prettier for formatting +- Use ESLint with airbnb config +- Maximum line length: 100 characters +- Use 2-space indentation + +### Naming Conventions +- **Files**: kebab-case (user-controller.js) +- **Classes**: PascalCase (UserService) +- **Functions/Variables**: camelCase (getUserById) +- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL) +- **Database Tables**: snake_case (user_accounts) + +### Git Workflow +- Branch names: `feature/description` or `fix/description` +- Commit messages: Follow conventional commits +- PR required before merge +- All CI/CD checks must pass +- Minimum 1 approval required + +### Testing Requirements +- Minimum 80% code coverage +- All critical paths must have tests +- Use Jest for unit tests +- Use Cypress for E2E tests +- Test filenames: `*.test.ts` or `*.spec.ts` + +### API Standards +- RESTful endpoints only +- JSON request/response +- Use HTTP status codes correctly +- Version API endpoints: `/api/v1/` +- Document all endpoints with examples + +### Database +- Use migrations for schema changes +- Never hardcode credentials +- Use connection pooling +- Enable query logging in development +- Regular backups required + +### Deployment +- Docker-based deployment +- Kubernetes orchestration +- Blue-green deployment strategy +- Automatic rollback on failure +- Database migrations run before deploy + +## Common Commands + +| Command | Purpose | +|---------|---------| +| `npm run dev` | Start development server | +| `npm test` | Run test suite | +| `npm run lint` | Check code style | +| `npm run build` | Build for production | +| `npm run migrate` | Run database migrations | + +## Team Contacts +- Tech Lead: Sarah Chen (@sarah.chen) +- Product Manager: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## Known Issues & Workarounds +- PostgreSQL connection pooling limited to 20 during peak hours +- Workaround: Implement query queuing +- Safari 14 compatibility issues with async generators +- Workaround: Use Babel transpiler + +## Related Projects +- Analytics Dashboard: `/projects/analytics` +- Mobile App: `/projects/mobile` +- Admin Panel: `/projects/admin` +``` + +### Приклад 2: Пам'ять для конкретного каталогу + +**Файл:** `./src/api/CLAUDE.md` + +````markdown +# API Module Standards + +This file overrides root CLAUDE.md for everything in /src/api/ + +## API-Specific Standards + +### Request Validation +- Use Zod for schema validation +- Always validate input +- Return 400 with validation errors +- Include field-level error details + +### Authentication +- All endpoints require JWT token +- Token in Authorization header +- Token expires after 24 hours +- Implement refresh token mechanism + +### Response Format + +All responses must follow this structure: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +Error responses: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### Pagination +- Use cursor-based pagination (not offset) +- Include `hasMore` boolean +- Limit max page size to 100 +- Default page size: 20 + +### Rate Limiting +- 1000 requests per hour for authenticated users +- 100 requests per hour for public endpoints +- Return 429 when exceeded +- Include retry-after header + +### Caching +- Use Redis for session caching +- Cache duration: 5 minutes default +- Invalidate on write operations +- Tag cache keys with resource type +```` + +### Приклад 3: Персональна пам'ять + +**Файл:** `~/.claude/CLAUDE.md` + +```markdown +# My Development Preferences + +## About Me +- **Experience Level**: 8 years full-stack development +- **Preferred Languages**: TypeScript, Python +- **Communication Style**: Direct, with examples +- **Learning Style**: Visual diagrams with code + +## Code Preferences + +### Error Handling +I prefer explicit error handling with try-catch blocks and meaningful error messages. +Avoid generic errors. Always log errors for debugging. + +### Comments +Use comments for WHY, not WHAT. Code should be self-documenting. +Comments should explain business logic or non-obvious decisions. + +### Testing +I prefer TDD (test-driven development). +Write tests first, then implementation. +Focus on behavior, not implementation details. + +### Architecture +I prefer modular, loosely-coupled design. +Use dependency injection for testability. +Separate concerns (Controllers, Services, Repositories). + +## Debugging Preferences +- Use console.log with prefix: `[DEBUG]` +- Include context: function name, relevant variables +- Use stack traces when available +- Always include timestamps in logs + +## Communication +- Explain complex concepts with diagrams +- Show concrete examples before explaining theory +- Include before/after code snippets +- Summarize key points at the end + +## Project Organization +I organize my projects as: + + project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ + +## Tooling +- **IDE**: VS Code with vim keybindings +- **Terminal**: Zsh with Oh-My-Zsh +- **Format**: Prettier (100 char line length) +- **Linter**: ESLint with airbnb config +- **Test Framework**: Jest with React Testing Library +``` + +_Мій тест_ +Попросіть Claude зберегти нове правило + +![Попросіть Claude зберегти нове правило](memory-ask-claude.png) +Claude не зберіг правило, бо у мене ніде не було файлу `Claude.md`. Потім попросив Claude підтвердити розташування. + +![Попросіть Claude зберегти нове правило](memory-saved.png) + +### Приклад 4: Оновлення пам'яті під час сесії + +Ви можете додавати нові правила до пам'яті під час активної сесії Claude Code. Є два способи це зробити: + +#### Метод 1: Прямий запит + +```markdown +User: Remember that I prefer using React hooks instead of class components + for all new components. + +Claude: I'm adding that to your memory. Which memory file should this go in? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: ✅ Memory saved! + +Added to ./CLAUDE.md: +--- + +### Component Development +- Use functional components with React Hooks +- Prefer hooks over class components +- Custom hooks for reusable logic +- Use useCallback for event handlers +- Use useMemo for expensive computations +``` + +#### Метод 2: Використання шаблону "# new rule into memory" + +Також можна використовувати явний шаблон "# new rule into memory" для оновлення пам'яті: + +```markdown +User: # new rule into memory + Always validate user input with Zod schemas before processing. + +Claude: I'm saving this rule to memory. Which memory file should I use? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: ✅ Memory saved! + +Added to ./CLAUDE.md: +--- + +### Input Validation +- Always validate user input with Zod schemas before processing +- Define schemas at the top of each API handler file +- Return 400 status with validation errors +``` + +#### Поради щодо додавання до пам'яті + +- Формулюйте правила конкретно та дієво +- Групуйте пов'язані правила під заголовком секції +- Оновлюйте наявні секції замість дублювання вмісту +- Обирайте відповідний рівень пам'яті (проєкт чи персональний) + +## Порівняння функцій пам'яті + +| Функція | Claude Web/Desktop | Claude Code (CLAUDE.md) | +|---------|-------------------|------------------------| +| Автосинтез | ✅ Кожні 24 год | ✅ Auto memory | +| Крос-проєктність | ✅ Спільна | ❌ Специфічна для проєкту | +| Командний доступ | ✅ Спільні проєкти | ✅ Відстежується через Git | +| Пошук | ✅ Вбудований | ✅ Через `/memory` | +| Редагування | ✅ У чаті | ✅ Пряме редагування файлу | +| Імпорт/Експорт | ✅ Так | ✅ Копіювання/вставлення | +| Постійність | ✅ 24+ год | ✅ Необмежена | + +### Пам'ять у Claude Web/Desktop + +#### Хронологія синтезу пам'яті + +```mermaid +graph LR + A["Day 1: User
Conversations"] -->|24 hours| B["Day 2: Memory
Synthesis"] + B -->|Automatic| C["Memory Updated
Summarized"] + C -->|Loaded in| D["Day 2-N:
New Conversations"] + D -->|Add to| E["Memory"] + E -->|24 hours later| F["Memory Refreshed"] +``` + +**Приклад зведення пам'яті:** + +```markdown +## Claude's Memory of User + +### Professional Background +- Senior full-stack developer with 8 years experience +- Focus on TypeScript/Node.js backends and React frontends +- Active open source contributor +- Interested in AI and machine learning + +### Project Context +- Currently building e-commerce platform +- Tech stack: Node.js, PostgreSQL, React 18, Docker +- Working with team of 5 developers +- Using CI/CD and blue-green deployments + +### Communication Preferences +- Prefers direct, concise explanations +- Likes visual diagrams and examples +- Appreciates code snippets +- Explains business logic in comments + +### Current Goals +- Improve API performance +- Increase test coverage to 90% +- Implement caching strategy +- Document architecture +``` + +## Найкращі практики + +### Рекомендовано — що включати + +- **Будьте конкретними та детальними**: використовуйте чіткі, детальні інструкції замість розпливчастих рекомендацій + - ✅ Добре: "Use 2-space indentation for all JavaScript files" + - ❌ Уникайте: "Follow best practices" + +- **Підтримуйте порядок**: структуруйте файли пам'яті з чіткими Markdown-секціями та заголовками + +- **Використовуйте відповідні рівні ієрархії**: + - **Managed policy**: загальноорганізаційні політики, стандарти безпеки, вимоги відповідності + - **Project memory**: командні стандарти, архітектура, конвенції кодування (комітити в git) + - **User memory**: персональні налаштування, стиль спілкування, вибір інструментів + - **Directory memory**: правила та перевизначення для конкретних модулів + +- **Використовуйте імпорти**: синтаксис `@шлях/до/файлу` для посилання на наявну документацію + - Підтримує до 5 рівнів рекурсивного вкладення + - Уникає дублювання між файлами пам'яті + - Приклад: `See @README.md for project overview` + +- **Документуйте часті команди**: включайте команди, які часто використовуєте, для економії часу + +- **Версіонуйте пам'ять проєкту**: комітьте файли CLAUDE.md рівня проєкту в git на користь команди + +- **Періодично переглядайте**: оновлюйте пам'ять регулярно в міру розвитку проєкту та зміни вимог + +- **Надавайте конкретні приклади**: включайте фрагменти коду та конкретні сценарії + +### Не рекомендовано — чого уникати + +- **Не зберігайте секрети**: ніколи не включайте API-ключі, паролі, токени чи облікові дані + +- **Не включайте конфіденційні дані**: жодних персональних даних, приватної інформації чи комерційних таємниць + +- **Не дублюйте вміст**: використовуйте імпорти (`@шлях`) для посилання на наявну документацію + +- **Не будьте розпливчастими**: уникайте загальних фраз на кшталт "follow best practices" або "write good code" + +- **Не робіть файли занадто довгими**: тримайте окремі файли пам'яті сфокусованими та до 500 рядків + +- **Не переорганізовуйте**: використовуйте ієрархію стратегічно; не створюйте надмірних перевизначень підкаталогів + +- **Не забувайте оновлювати**: застаріла пам'ять може спричинити плутанину та використання застарілих практик + +- **Не перевищуйте ліміти вкладення**: імпорти пам'яті підтримують до 5 рівнів вкладення + +### Поради з управління пам'яттю + +**Оберіть правильний рівень пам'яті:** + +| Випадок використання | Рівень пам'яті | Обґрунтування | +|---------------------|----------------|--------------| +| Корпоративна політика безпеки | Managed Policy | Застосовується до всіх проєктів організації | +| Стайлгайд коду команди | Project | Спільний з командою через git | +| Ваші улюблені ярлики редактора | User | Персональне налаштування, не спільне | +| Стандарти API-модуля | Directory | Специфічно лише для цього модуля | + +**Швидкий воркфлов оновлення:** + +1. Для окремих правил: використовуйте префікс `#` у розмові +2. Для кількох змін: використовуйте `/memory` для відкриття редактора +3. Для початкового налаштування: використовуйте `/init` для створення шаблону + +**Найкращі практики імпорту:** + +```markdown +# Добре: посилання на наявні документи +@README.md +@docs/architecture.md +@package.json + +# Уникайте: копіювання вмісту, що існує деінде +# Замість копіювання вмісту README в CLAUDE.md — просто імпортуйте його +``` + +## Інструкції з встановлення + +### Налаштування пам'яті проєкту + +#### Метод 1: Команда `/init` (рекомендовано) + +Найшвидший спосіб налаштувати пам'ять проєкту: + +1. **Перейдіть у каталог проєкту:** + ```bash + cd /path/to/your/project + ``` + +2. **Виконайте команду init у Claude Code:** + ```bash + /init + ``` + +3. **Claude створить та заповнить CLAUDE.md** шаблонною структурою + +4. **Налаштуйте згенерований файл** відповідно до потреб проєкту + +5. **Закомітьте в git:** + ```bash + git add CLAUDE.md + git commit -m "Initialize project memory with /init" + ``` + +#### Метод 2: Ручне створення + +Якщо ви надаєте перевагу ручному налаштуванню: + +1. **Створіть CLAUDE.md у корені проєкту:** + ```bash + cd /path/to/your/project + touch CLAUDE.md + ``` + +2. **Додайте стандарти проєкту:** + ```bash + cat > CLAUDE.md << 'EOF' + # Project Configuration + + ## Project Overview + - **Name**: Your Project Name + - **Tech Stack**: List your technologies + - **Team Size**: Number of developers + + ## Development Standards + - Your coding standards + - Naming conventions + - Testing requirements + EOF + ``` + +3. **Закомітьте в git:** + ```bash + git add CLAUDE.md + git commit -m "Add project memory configuration" + ``` + +#### Метод 3: Швидкі оновлення з `#` + +Коли CLAUDE.md вже існує, швидко додавайте правила під час розмов: + +```markdown +# Use semantic versioning for all releases + +# Always run tests before committing + +# Prefer composition over inheritance +``` + +Claude запропонує обрати, який файл пам'яті оновити. + +### Налаштування персональної пам'яті + +1. **Створіть каталог ~/.claude:** + ```bash + mkdir -p ~/.claude + ``` + +2. **Створіть персональний CLAUDE.md:** + ```bash + touch ~/.claude/CLAUDE.md + ``` + +3. **Додайте ваші налаштування:** + ```bash + cat > ~/.claude/CLAUDE.md << 'EOF' + # My Development Preferences + + ## About Me + - Experience Level: [Your level] + - Preferred Languages: [Your languages] + - Communication Style: [Your style] + + ## Code Preferences + - [Your preferences] + EOF + ``` + +### Налаштування пам'яті для конкретного каталогу + +1. **Створіть пам'ять для конкретних каталогів:** + ```bash + mkdir -p /path/to/directory/.claude + touch /path/to/directory/CLAUDE.md + ``` + +2. **Додайте правила, специфічні для каталогу:** + ```bash + cat > /path/to/directory/CLAUDE.md << 'EOF' + # [Directory Name] Standards + + This file overrides root CLAUDE.md for this directory. + + ## [Specific Standards] + EOF + ``` + +3. **Закомітьте у систему контролю версій:** + ```bash + git add /path/to/directory/CLAUDE.md + git commit -m "Add [directory] memory configuration" + ``` + +### Перевірка налаштування + +1. **Перевірте розташування пам'яті:** + ```bash + # Пам'ять кореня проєкту + ls -la ./CLAUDE.md + + # Персональна пам'ять + ls -la ~/.claude/CLAUDE.md + ``` + +2. **Claude Code автоматично завантажить** ці файли при запуску сесії + +3. **Протестуйте з Claude Code**, запустивши нову сесію у вашому проєкті + +## Офіційна документація + +Для найактуальнішої інформації зверніться до офіційної документації Claude Code: + +- **[Документація пам'яті](https://code.claude.com/docs/en/memory)** — повний довідник системи пам'яті +- **[Довідник слеш-команд](https://code.claude.com/docs/en/interactive-mode)** — всі вбудовані команди, включаючи `/init` та `/memory` +- **[Довідник CLI](https://code.claude.com/docs/en/cli-reference)** — документація інтерфейсу командного рядка + +### Ключові технічні деталі з офіційної документації + +**Завантаження пам'яті:** + +- Усі файли пам'яті автоматично завантажуються при запуску Claude Code +- Claude проходить вгору від поточного робочого каталогу для виявлення файлів CLAUDE.md +- Файли піддерев виявляються та завантажуються контекстно при доступі до цих каталогів + +**Синтаксис імпорту:** + +- Використовуйте `@шлях/до/файлу` для включення зовнішнього вмісту (наприклад, `@~/.claude/my-project-instructions.md`) +- Підтримуються відносні та абсолютні шляхи +- Рекурсивні імпорти підтримуються з максимальною глибиною 5 +- Перший зовнішній імпорт викликає діалог підтвердження +- Не обробляються всередині code span та code block у Markdown +- Автоматично включає вміст посилань у контекст Claude + +**Пріоритет ієрархії пам'яті:** + +1. Managed Policy (найвищий пріоритет) +2. Managed Drop-ins (`managed-settings.d/`, v2.1.83+) +3. Project Memory +4. Project Rules (`.claude/rules/`) +5. User Memory +6. User-Level Rules (`~/.claude/rules/`) +7. Local Project Memory +8. Auto Memory (найнижчий пріоритет) + +## Посилання на пов'язані концепції + +### Точки інтеграції +- [Протокол MCP](../05-mcp/) — доступ до даних у реальному часі поруч з пам'яттю +- [Слеш-команди](../01-slash-commands/) — ярлики для сесій +- [Навички](../03-skills/) — автоматизовані воркфлови з контекстом пам'яті + +### Пов'язані функції Claude +- [Пам'ять Claude Web](https://claude.ai) — автоматичний синтез +- [Офіційна документація пам'яті](https://code.claude.com/docs/en/memory) — документація Anthropic + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/02-memory/directory-api-CLAUDE.md b/uk/02-memory/directory-api-CLAUDE.md new file mode 100644 index 0000000..f943c70 --- /dev/null +++ b/uk/02-memory/directory-api-CLAUDE.md @@ -0,0 +1,64 @@ +# Стандарти модуля API + +Цей файл перевизначає кореневий CLAUDE.md для всього у /src/api/ + +## Специфічні стандарти API + +### Валідація запитів +- Використовувати Zod для валідації схем +- Завжди валідувати вхідні дані +- Повертати 400 з помилками валідації +- Включати деталі помилок на рівні полів + +### Автентифікація +- Усі ендпоінти вимагають JWT-токен +- Токен у заголовку Authorization +- Токен закінчується через 24 години +- Реалізувати механізм refresh-токенів + +### Формат відповіді + +Усі відповіді мають дотримуватися цієї структури: + +```json +{ + "success": true, + "data": { /* фактичні дані */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +Відповіді з помилками: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "Повідомлення для користувача", + "details": { /* помилки полів */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### Пагінація +- Використовувати пагінацію на основі курсора (не зсуву/offset) +- Включати булеве поле `hasMore` +- Максимальний розмір сторінки: 100 +- Розмір сторінки за замовчуванням: 20 + +### Обмеження частоти запитів (Rate Limiting) +- 1000 запитів на годину для автентифікованих користувачів +- 100 запитів на годину для публічних ендпоінтів +- Повертати 429 при перевищенні +- Включати заголовок retry-after + +### Кешування +- Використовувати Redis для кешування сесій +- Тривалість кешу: 5 хвилин за замовчуванням +- Інвалідувати при операціях запису +- Тегувати ключі кешу типом ресурсу + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/02-memory/memory-ask-claude.png b/uk/02-memory/memory-ask-claude.png new file mode 100644 index 0000000..b202227 Binary files /dev/null and b/uk/02-memory/memory-ask-claude.png differ diff --git a/uk/02-memory/memory-saved.png b/uk/02-memory/memory-saved.png new file mode 100644 index 0000000..1c16eb7 Binary files /dev/null and b/uk/02-memory/memory-saved.png differ diff --git a/uk/02-memory/personal-CLAUDE.md b/uk/02-memory/personal-CLAUDE.md new file mode 100644 index 0000000..7b42b03 --- /dev/null +++ b/uk/02-memory/personal-CLAUDE.md @@ -0,0 +1,63 @@ +# Мої уподобання розробки + +## Про мене +- **Рівень досвіду**: 8 років full-stack розробки +- **Бажані мови**: TypeScript, Python +- **Стиль комунікації**: Прямий, з прикладами +- **Стиль навчання**: Візуальні діаграми з кодом + +## Уподобання коду + +### Обробка помилок +Я віддаю перевагу явній обробці помилок з блоками try-catch та змістовними повідомленнями. +Уникайте загальних помилок. Завжди логуйте помилки для налагодження. + +### Коментарі +Коментарі для ЧОМУ, а не ЩО. Код має бути самодокументованим. +Коментарі мають пояснювати бізнес-логіку або неочевидні рішення. + +### Тестування +Я віддаю перевагу TDD (розробка через тестування). +Спочатку писати тести, потім реалізацію. +Фокус на поведінці, а не деталях реалізації. + +### Архітектура +Я віддаю перевагу модульному, слабкоповʼязаному дизайну. +Використовувати впровадження залежностей (dependency injection) для тестовності. +Розділення відповідальностей (Controllers, Services, Repositories). + +## Уподобання налагодження +- Використовувати console.log з префіксом: `[DEBUG]` +- Включати контекст: назву функції, відповідні змінні +- Використовувати стеки викликів (stack traces), коли доступні +- Завжди включати мітки часу в журналах + +## Комунікація +- Пояснювати складні концепції діаграмами +- Показувати конкретні приклади перед поясненням теорії +- Включати фрагменти коду до/після +- Підсумовувати ключові моменти наприкінці + +## Організація проєкту +Я організовую проєкти так: +``` +project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ +``` + +## Інструментарій +- **IDE**: VS Code з vim-клавішами +- **Термінал**: Zsh з Oh-My-Zsh +- **Форматування**: Prettier (довжина рядка 100 символів) +- **Лінтер**: ESLint з конфігурацією airbnb +- **Тестовий фреймворк**: Jest з React Testing Library + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/02-memory/project-CLAUDE.md b/uk/02-memory/project-CLAUDE.md new file mode 100644 index 0000000..0e99e33 --- /dev/null +++ b/uk/02-memory/project-CLAUDE.md @@ -0,0 +1,91 @@ +# Конфігурація проєкту + +## Огляд проєкту +- **Назва**: Платформа електронної комерції +- **Технологічний стек**: Node.js, PostgreSQL, React 18, Docker +- **Розмір команди**: 5 розробників +- **Дедлайн**: Q4 2025 + +## Архітектура +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## Стандарти розробки + +### Стиль коду +- Використовувати Prettier для форматування +- Використовувати ESLint з конфігурацією airbnb +- Максимальна довжина рядка: 100 символів +- Використовувати відступ 2 пробіли + +### Конвенції іменування +- **Файли**: kebab-case (user-controller.js) +- **Класи**: PascalCase (UserService) +- **Функції/Змінні**: camelCase (getUserById) +- **Константи**: UPPER_SNAKE_CASE (API_BASE_URL) +- **Таблиці БД**: snake_case (user_accounts) + +### Git-процес +- Назви гілок: `feature/description` або `fix/description` +- Повідомлення комітів: дотримуватися conventional commits +- PR обовʼязковий перед злиттям +- Усі CI/CD перевірки мають пройти +- Мінімум 1 затвердження (approval) обовʼязкове + +### Вимоги до тестування +- Мінімум 80% покриття коду +- Усі критичні шляхи мають мати тести +- Використовувати Jest для юніт-тестів +- Використовувати Cypress для E2E-тестів +- Назви тестових файлів: `*.test.ts` або `*.spec.ts` + +### Стандарти API +- Лише RESTful ендпоінти +- JSON запит/відповідь +- Правильно використовувати HTTP-статус-коди +- Версіонування API-ендпоінтів: `/api/v1/` +- Документувати всі ендпоінти з прикладами + +### База даних +- Використовувати міграції для змін схеми +- Ніколи не зашивати облікові дані в код +- Використовувати пул зʼєднань (connection pooling) +- Увімкнути логування запитів у середовищі розробки +- Регулярне резервне копіювання обовʼязкове + +### Деплой +- Деплой на основі Docker +- Оркестрація Kubernetes +- Стратегія blue-green деплою +- Автоматичний відкат при невдачі +- Міграції БД виконуються перед деплоєм + +## Типові команди + +| Команда | Призначення | +|---------|-------------| +| `npm run dev` | Запуск сервера розробки | +| `npm test` | Запуск тестового набору | +| `npm run lint` | Перевірка стилю коду | +| `npm run build` | Збірка для продакшну | +| `npm run migrate` | Запуск міграцій БД | + +## Контакти команди +- Техлід: Sarah Chen (@sarah.chen) +- Продакт-менеджер: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## Відомі проблеми та обхідні рішення +- Пул зʼєднань PostgreSQL обмежений до 20 у пікові години +- Обхідне рішення: реалізувати чергу запитів +- Проблеми сумісності Safari 14 з async generators +- Обхідне рішення: використовувати транспілятор Babel + +## Повʼязані проєкти +- Аналітична панель: `/projects/analytics` +- Мобільний додаток: `/projects/mobile` +- Адмін-панель: `/projects/admin` + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/03-skills/.gitignore b/uk/03-skills/.gitignore new file mode 100644 index 0000000..28820ae --- /dev/null +++ b/uk/03-skills/.gitignore @@ -0,0 +1,5 @@ +# Local skill testing +.claude/ + +# Blog post outputs +blog-posts/ diff --git a/uk/03-skills/README.md b/uk/03-skills/README.md new file mode 100644 index 0000000..66127bc --- /dev/null +++ b/uk/03-skills/README.md @@ -0,0 +1,815 @@ + + + + + + + Claude How To + + +# Посібник з навичок агента + +Навички агента (Agent Skills) — це повторно використовувані, файлові можливості, які розширюють функціональність Claude. Вони пакують доменну експертизу, воркфлови та найкращі практики в компоненти, що автоматично виявляються, і Claude використовує їх, коли це доречно. + +## Огляд + +**Навички агента** — це модульні можливості, які перетворюють агентів загального призначення на спеціалістів. На відміну від промптів (інструкцій рівня розмови для одноразових завдань), навички завантажуються за потребою і усувають необхідність повторно надавати ті самі рекомендації в кількох розмовах. + +### Ключові переваги + +- **Спеціалізація Claude**: налаштування можливостей для доменних завдань +- **Зменшення повторень**: створити один раз, використовувати автоматично в усіх розмовах +- **Комбінування можливостей**: поєднання навичок для побудови складних воркфловів +- **Масштабування воркфловів**: повторне використання навичок у кількох проєктах і командах +- **Підтримка якості**: вбудовування найкращих практик безпосередньо у воркфлов + +Навички відповідають відкритому стандарту [Agent Skills](https://agentskills.io), який працює з кількома AI-інструментами. Claude Code розширює стандарт додатковими функціями: керування викликом, виконання в субагенті та динамічне впровадження контексту. + +> **Примітка**: Користувацькі слеш-команди об'єднано з навичками. Файли `.claude/commands/` все ще працюють і підтримують ті самі поля фронтматера. Навички рекомендовано для нової розробки. Коли обидва існують за одним шляхом (наприклад, `.claude/commands/review.md` та `.claude/skills/review/SKILL.md`), навичка має пріоритет. + +## Як працюють навички: прогресивне розкриття + +Навички використовують архітектуру **прогресивного розкриття** (progressive disclosure) — Claude завантажує інформацію поетапно за потребою, а не споживає весь контекст одразу. Це забезпечує ефективне управління контекстом із необмеженою масштабованістю. + +### Три рівні завантаження + +```mermaid +graph TB + subgraph "Level 1: Metadata (Always Loaded)" + A["YAML Frontmatter"] + A1["~100 tokens per skill"] + A2["name + description"] + end + + subgraph "Level 2: Instructions (When Triggered)" + B["SKILL.md Body"] + B1["Under 5k tokens"] + B2["Workflows & guidance"] + end + + subgraph "Level 3: Resources (As Needed)" + C["Bundled Files"] + C1["Effectively unlimited"] + C2["Scripts, templates, docs"] + end + + A --> B + B --> C +``` + +| Рівень | Коли завантажується | Вартість токенів | Вміст | +|--------|-------------------|-----------------|-------| +| **Рівень 1: Метадані** | Завжди (при запуску) | ~100 токенів на навичку | `name` та `description` з YAML-фронтматера | +| **Рівень 2: Інструкції** | Коли навичка активована | До 5k токенів | Тіло SKILL.md з інструкціями та рекомендаціями | +| **Рівень 3+: Ресурси** | За потребою | Фактично необмежено | Файли-пакети, що виконуються через bash без завантаження в контекст | + +Це означає, що ви можете встановити багато навичок без штрафу за контекст — Claude лише знає, що кожна навичка існує і коли її використовувати, доки вона фактично не активована. + +## Процес завантаження навички + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude + participant System as System + participant Skill as Skill + + User->>Claude: "Review this code for security issues" + Claude->>System: Check available skills (metadata) + System-->>Claude: Skill descriptions loaded at startup + Claude->>Claude: Match request to skill description + Claude->>Skill: bash: read code-review/SKILL.md + Skill-->>Claude: Instructions loaded into context + Claude->>Claude: Determine: Need templates? + Claude->>Skill: bash: read templates/checklist.md + Skill-->>Claude: Template loaded + Claude->>Claude: Execute skill instructions + Claude->>User: Comprehensive code review +``` + +## Типи та розташування навичок + +| Тип | Розташування | Область дії | Спільний | Найкраще для | +|-----|-------------|-------------|---------|-------------| +| **Enterprise** | Managed settings | Всі користувачі організації | Так | Загальноорганізаційні стандарти | +| **Personal** | `~/.claude/skills//SKILL.md` | Індивідуальний | Ні | Персональні воркфлови | +| **Project** | `.claude/skills//SKILL.md` | Команда | Так (через git) | Командні стандарти | +| **Plugin** | `/skills//SKILL.md` | Де увімкнено | Залежить | В складі плагінів | + +Коли навички мають однакову назву на різних рівнях, вищі пріоритетні розташування перемагають: **enterprise > personal > project**. Навички плагінів використовують простір імен `plugin-name:skill-name`, тому конфлікти неможливі. + +### Автоматичне виявлення + +**Вкладені каталоги**: коли ви працюєте з файлами в підкаталогах, Claude Code автоматично виявляє навички з вкладених каталогів `.claude/skills/`. Наприклад, якщо ви редагуєте файл у `packages/frontend/`, Claude Code також шукає навички в `packages/frontend/.claude/skills/`. Це підтримує конфігурації монорепо, де пакети мають власні навички. + +**Каталоги `--add-dir`**: навички з каталогів, доданих через `--add-dir`, завантажуються автоматично з виявленням змін у реальному часі. Будь-які зміни файлів навичок у цих каталогах набувають чинності негайно без перезапуску Claude Code. + +**Бюджет опису**: описи навичок (метадані рівня 1) обмежені **1% контекстного вікна** (резерв: **8 000 символів**). Якщо встановлено багато навичок, описи можуть бути скорочені. Назви всіх навичок завжди включаються, але описи обрізаються для вписування. Розміщуйте ключовий випадок використання на початку описів. Перевизначте бюджет змінною оточення `SLASH_COMMAND_TOOL_CHAR_BUDGET`. + +## Створення власних навичок + +### Базова структура каталогу + +``` +my-skill/ +├── SKILL.md # Головні інструкції (обов'язковий) +├── template.md # Шаблон для заповнення Claude +├── examples/ +│ └── sample.md # Приклад результату з очікуваним форматом +└── scripts/ + └── validate.sh # Скрипт, який Claude може виконати +``` + +### Формат SKILL.md + +```yaml +--- +name: your-skill-name +description: Brief description of what this Skill does and when to use it +--- + +# Your Skill Name + +## Instructions +Provide clear, step-by-step guidance for Claude. + +## Examples +Show concrete examples of using this Skill. +``` + +### Обов'язкові поля + +- **name**: тільки малі літери, цифри, дефіси (макс. 64 символи). Не може містити "anthropic" або "claude". +- **description**: що навичка робить І коли її використовувати (макс. 1024 символи). Це критично для того, щоб Claude знав, коли активувати навичку. + +### Додаткові поля фронтматера + +```yaml +--- +name: my-skill +description: What this skill does and when to use it +argument-hint: "[filename] [format]" # Підказка для автодоповнення +disable-model-invocation: true # Тільки користувач може викликати +user-invocable: false # Приховати з меню слеш-команд +allowed-tools: Read, Grep, Glob # Обмежити доступ до інструментів +model: opus # Конкретна модель +effort: high # Рівень зусиль (low, medium, high, max) +context: fork # Запуск в ізольованому субагенті +agent: Explore # Тип агента (з context: fork) +shell: bash # Оболонка: bash (за замовч.) або powershell +hooks: # Хуки, обмежені навичкою + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/validate.sh" +paths: "src/api/**/*.ts" # Glob-патерни, що обмежують активацію +--- +``` + +| Поле | Опис | +|------|------| +| `name` | Тільки малі літери, цифри, дефіси (макс. 64 символи). Не може містити "anthropic" або "claude". | +| `description` | Що навичка робить І коли її використовувати (макс. 1024 символи). Критично для автоматичного зіставлення. | +| `argument-hint` | Підказка в меню автодоповнення `/` (наприклад, `"[filename] [format]"`). | +| `disable-model-invocation` | `true` = тільки користувач може викликати через `/name`. Claude ніколи не викличе автоматично. | +| `user-invocable` | `false` = приховано з меню `/`. Тільки Claude може викликати автоматично. | +| `allowed-tools` | Список інструментів через кому, які навичка може використовувати без запитів дозволу. | +| `model` | Перевизначення моделі під час активності навички (наприклад, `opus`, `sonnet`). | +| `effort` | Перевизначення рівня зусиль: `low`, `medium`, `high` або `max`. | +| `context` | `fork` для запуску навички у відгалуженому контексті субагента з власним контекстним вікном. | +| `agent` | Тип субагента при `context: fork` (наприклад, `Explore`, `Plan`, `general-purpose`). | +| `shell` | Оболонка для підстановок `!`command`` та скриптів: `bash` (за замовч.) або `powershell`. | +| `hooks` | Хуки, обмежені життєвим циклом цієї навички (той самий формат, що й глобальні хуки). | +| `paths` | Glob-патерни, що обмежують автоактивацію. Рядок через кому або YAML-список. Формат як у правилах для конкретних шляхів. | + +## Типи вмісту навичок + +Навички можуть містити два типи вмісту, кожен для різних цілей: + +### Довідковий вміст + +Додає знання, які Claude застосовує до вашої поточної роботи — конвенції, патерни, стайлгайди, доменні знання. Виконується в контексті вашої розмови. + +```yaml +--- +name: api-conventions +description: API design patterns for this codebase +--- + +When writing API endpoints: +- Use RESTful naming conventions +- Return consistent error formats +- Include request validation +``` + +### Вміст завдань + +Покрокові інструкції для конкретних дій. Часто викликається безпосередньо через `/skill-name`. + +```yaml +--- +name: deploy +description: Deploy the application to production +context: fork +disable-model-invocation: true +--- + +Deploy the application: +1. Run the test suite +2. Build the application +3. Push to the deployment target +``` + +## Керування викликом навичок + +За замовчуванням і ви, і Claude можете викликати будь-яку навичку. Два поля фронтматера контролюють три режими виклику: + +| Фронтматер | Ви можете викликати | Claude може викликати | +|---|---|---| +| (за замовч.) | Так | Так | +| `disable-model-invocation: true` | Так | Ні | +| `user-invocable: false` | Ні | Так | + +**Використовуйте `disable-model-invocation: true`** для воркфловів з побічними ефектами: `/commit`, `/deploy`, `/send-slack-message`. Ви не хочете, щоб Claude вирішив задеплоїти, бо ваш код виглядає готовим. + +**Використовуйте `user-invocable: false`** для фонових знань, які не є дієвими як команда. Навичка `legacy-system-context` пояснює, як працює стара система — корисно для Claude, але не має сенсу як дія для користувачів. + +## Підстановки рядків + +Навички підтримують динамічні значення, які розв'язуються до того, як вміст навички потрапляє до Claude: + +| Змінна | Опис | +|--------|------| +| `$ARGUMENTS` | Всі аргументи, передані при виклику навички | +| `$ARGUMENTS[N]` або `$N` | Доступ до конкретного аргументу за індексом (починаючи з 0) | +| `${CLAUDE_SESSION_ID}` | ID поточної сесії | +| `${CLAUDE_SKILL_DIR}` | Каталог, що містить файл SKILL.md навички | +| `` !`command` `` | Динамічне впровадження контексту — виконує команду оболонки та вставляє результат | + +**Приклад:** + +```yaml +--- +name: fix-issue +description: Fix a GitHub issue +--- + +Fix GitHub issue $ARGUMENTS following our coding standards. +1. Read the issue description +2. Implement the fix +3. Write tests +4. Create a commit +``` + +Виконання `/fix-issue 123` замінює `$ARGUMENTS` на `123`. + +## Впровадження динамічного контексту + +Синтаксис `` !`command` `` виконує команди оболонки до того, як вміст навички відправляється до Claude: + +```yaml +--- +name: pr-summary +description: Summarize changes in a pull request +context: fork +agent: Explore +--- + +## Pull request context +- PR diff: !`gh pr diff` +- PR comments: !`gh pr view --comments` +- Changed files: !`gh pr diff --name-only` + +## Your task +Summarize this pull request... +``` + +Команди виконуються негайно; Claude бачить лише кінцевий результат. За замовчуванням команди виконуються в `bash`. Встановіть `shell: powershell` у фронтматері для використання PowerShell. + +## Запуск навичок у субагентах + +Додайте `context: fork` для запуску навички в ізольованому контексті субагента. Вміст навички стає завданням для виділеного субагента з власним контекстним вікном, зберігаючи основну розмову чистою. + +Поле `agent` вказує тип агента: + +| Тип агента | Найкраще для | +|---|---| +| `Explore` | Дослідження лише для читання, аналіз кодової бази | +| `Plan` | Створення планів реалізації | +| `general-purpose` | Широкі завдання, що потребують усіх інструментів | +| Custom agents | Спеціалізовані агенти, визначені у вашій конфігурації | + +**Приклад фронтматера:** + +```yaml +--- +context: fork +agent: Explore +--- +``` + +**Повний приклад навички:** + +```yaml +--- +name: deep-research +description: Research a topic thoroughly +context: fork +agent: Explore +--- + +Research $ARGUMENTS thoroughly: +1. Find relevant files using Glob and Grep +2. Read and analyze the code +3. Summarize findings with specific file references +``` + +## Практичні приклади + +### Приклад 1: Навичка код-рев'ю + +**Структура каталогу:** + +``` +~/.claude/skills/code-review/ +├── SKILL.md +├── templates/ +│ ├── review-checklist.md +│ └── finding-template.md +└── scripts/ + ├── analyze-metrics.py + └── compare-complexity.py +``` + +**Файл:** `~/.claude/skills/code-review/SKILL.md` + +```yaml +--- +name: code-review-specialist +description: Comprehensive code review with security, performance, and quality analysis. Use when users ask to review code, analyze code quality, evaluate pull requests, or mention code review, security analysis, or performance optimization. +--- + +# Code Review Skill + +This skill provides comprehensive code review capabilities focusing on: + +1. **Security Analysis** + - Authentication/authorization issues + - Data exposure risks + - Injection vulnerabilities + - Cryptographic weaknesses + +2. **Performance Review** + - Algorithm efficiency (Big O analysis) + - Memory optimization + - Database query optimization + - Caching opportunities + +3. **Code Quality** + - SOLID principles + - Design patterns + - Naming conventions + - Test coverage + +4. **Maintainability** + - Code readability + - Function size (should be < 50 lines) + - Cyclomatic complexity + - Type safety + +## Review Template + +For each piece of code reviewed, provide: + +### Summary +- Overall quality assessment (1-5) +- Key findings count +- Recommended priority areas + +### Critical Issues (if any) +- **Issue**: Clear description +- **Location**: File and line number +- **Impact**: Why this matters +- **Severity**: Critical/High/Medium +- **Fix**: Code example + +For detailed checklists, see [templates/review-checklist.md](templates/review-checklist.md). +``` + +### Приклад 2: Навичка візуалізації кодової бази + +Навичка, що генерує інтерактивні HTML-візуалізації: + +**Структура каталогу:** + +``` +~/.claude/skills/codebase-visualizer/ +├── SKILL.md +└── scripts/ + └── visualize.py +``` + +**Файл:** `~/.claude/skills/codebase-visualizer/SKILL.md` + +````yaml +--- +name: codebase-visualizer +description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files. +allowed-tools: Bash(python *) +--- + +# Codebase Visualizer + +Generate an interactive HTML tree view showing your project's file structure. + +## Usage + +Run the visualization script from your project root: + +```bash +python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . +``` + +This creates `codebase-map.html` and opens it in your default browser. + +## What the visualization shows + +- **Collapsible directories**: Click folders to expand/collapse +- **File sizes**: Displayed next to each file +- **Colors**: Different colors for different file types +- **Directory totals**: Shows aggregate size of each folder +```` + +Python-скрипт у пакеті виконує важку роботу, а Claude займається оркестрацією. + +### Приклад 3: Навичка деплою (тільки виклик користувачем) + +```yaml +--- +name: deploy +description: Deploy the application to production +disable-model-invocation: true +allowed-tools: Bash(npm *), Bash(git *) +--- + +Deploy $ARGUMENTS to production: + +1. Run the test suite: `npm test` +2. Build the application: `npm run build` +3. Push to the deployment target +4. Verify the deployment succeeded +5. Report deployment status +``` + +### Приклад 4: Навичка голосу бренду (фонові знання) + +```yaml +--- +name: brand-voice +description: Ensure all communication matches brand voice and tone guidelines. Use when creating marketing copy, customer communications, or public-facing content. +user-invocable: false +--- + +## Tone of Voice +- **Friendly but professional** - approachable without being casual +- **Clear and concise** - avoid jargon +- **Confident** - we know what we're doing +- **Empathetic** - understand user needs + +## Writing Guidelines +- Use "you" when addressing readers +- Use active voice +- Keep sentences under 20 words +- Start with value proposition + +For templates, see [templates/](templates/). +``` + +### Приклад 5: Навичка генератора CLAUDE.md + +```yaml +--- +name: claude-md +description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding. Use when users mention CLAUDE.md, project documentation, or AI onboarding. +--- + +## Core Principles + +**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation. + +### The Golden Rules + +1. **Less is More**: Keep under 300 lines (ideally under 100) +2. **Universal Applicability**: Only include information relevant to EVERY session +3. **Don't Use Claude as a Linter**: Use deterministic tools instead +4. **Never Auto-Generate**: Craft it manually with careful consideration + +## Essential Sections + +- **Project Name**: Brief one-line description +- **Tech Stack**: Primary language, frameworks, database +- **Development Commands**: Install, test, build commands +- **Critical Conventions**: Only non-obvious, high-impact conventions +- **Known Issues / Gotchas**: Things that trip up developers +``` + +### Приклад 6: Навичка рефакторингу зі скриптами + +**Структура каталогу:** + +``` +refactor/ +├── SKILL.md +├── references/ +│ ├── code-smells.md +│ └── refactoring-catalog.md +├── templates/ +│ └── refactoring-plan.md +└── scripts/ + ├── analyze-complexity.py + └── detect-smells.py +``` + +**Файл:** `refactor/SKILL.md` + +```yaml +--- +name: code-refactor +description: Systematic code refactoring based on Martin Fowler's methodology. Use when users ask to refactor code, improve code structure, reduce technical debt, or eliminate code smells. +--- + +# Code Refactoring Skill + +A phased approach emphasizing safe, incremental changes backed by tests. + +## Workflow + +Phase 1: Research & Analysis → Phase 2: Test Coverage Assessment → +Phase 3: Code Smell Identification → Phase 4: Refactoring Plan Creation → +Phase 5: Incremental Implementation → Phase 6: Review & Iteration + +## Core Principles + +1. **Behavior Preservation**: External behavior must remain unchanged +2. **Small Steps**: Make tiny, testable changes +3. **Test-Driven**: Tests are the safety net +4. **Continuous**: Refactoring is ongoing, not a one-time event + +For code smell catalog, see [references/code-smells.md](references/code-smells.md). +For refactoring techniques, see [references/refactoring-catalog.md](references/refactoring-catalog.md). +``` + +## Допоміжні файли + +Навички можуть включати кілька файлів у каталозі крім `SKILL.md`. Ці допоміжні файли (шаблони, приклади, скрипти, довідкові документи) дозволяють тримати головний файл навички сфокусованим, надаючи Claude додаткові ресурси, які він завантажує за потребою. + +``` +my-skill/ +├── SKILL.md # Головні інструкції (обов'язковий, до 500 рядків) +├── templates/ # Шаблони для заповнення Claude +│ └── output-format.md +├── examples/ # Приклади результатів з очікуваним форматом +│ └── sample-output.md +├── references/ # Доменні знання та специфікації +│ └── api-spec.md +└── scripts/ # Скрипти, які Claude може виконати + └── validate.sh +``` + +Рекомендації щодо допоміжних файлів: + +- Тримайте `SKILL.md` до **500 рядків**. Переносіть детальний довідковий матеріал, великі приклади та специфікації в окремі файли. +- Посилайтесь на додаткові файли з `SKILL.md` за допомогою **відносних шляхів** (наприклад, `[API reference](references/api-spec.md)`). +- Допоміжні файли завантажуються на рівні 3 (за потребою), тому вони не споживають контекст, поки Claude фактично їх не прочитає. + +## Управління навичками + +### Перегляд доступних навичок + +Запитайте Claude безпосередньо: +``` +What Skills are available? +``` + +Або перевірте файлову систему: +```bash +# Список персональних навичок +ls ~/.claude/skills/ + +# Список навичок проєкту +ls .claude/skills/ +``` + +### Тестування навички + +Два способи тестування: + +**Дозвольте Claude викликати автоматично**, запитавши щось, що відповідає опису: +``` +Can you help me review this code for security issues? +``` + +**Або викличте безпосередньо** за назвою навички: +``` +/code-review src/auth/login.ts +``` + +### Оновлення навички + +Редагуйте файл `SKILL.md` безпосередньо. Зміни набувають чинності при наступному запуску Claude Code. + +```bash +# Персональна навичка +code ~/.claude/skills/my-skill/SKILL.md + +# Навичка проєкту +code .claude/skills/my-skill/SKILL.md +``` + +### Обмеження доступу Claude до навичок + +Три способи контролювати, які навички Claude може викликати: + +**Вимкнути всі навички** в `/permissions`: +``` +# Додати до правил заборони: +Skill +``` + +**Дозволити або заборонити конкретні навички**: +``` +# Дозволити лише конкретні навички +Skill(commit) +Skill(review-pr *) + +# Заборонити конкретні навички +Skill(deploy *) +``` + +**Приховати окремі навички**, додавши `disable-model-invocation: true` до їхнього фронтматера. + +## Найкращі практики + +### 1. Робіть описи конкретними + +- **Погано (розпливчасто)**: "Helps with documents" +- **Добре (конкретно)**: "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction." + +### 2. Тримайте навички сфокусованими + +- Одна навичка = одна можливість +- ✅ "PDF form filling" +- ❌ "Document processing" (занадто широко) + +### 3. Включайте тригерні терміни + +Додавайте ключові слова в описи, що відповідають запитам користувачів: +```yaml +description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files. +``` + +### 4. Тримайте SKILL.md до 500 рядків + +Переносіть детальний довідковий матеріал в окремі файли, які Claude завантажує за потребою. + +### 5. Посилайтесь на допоміжні файли + +```markdown +## Additional resources + +- For complete API details, see [reference.md](reference.md) +- For usage examples, see [examples.md](examples.md) +``` + +### Рекомендовано + +- Використовуйте зрозумілі, описові назви +- Включайте вичерпні інструкції +- Додавайте конкретні приклади +- Пакуйте пов'язані скрипти та шаблони +- Тестуйте з реальними сценаріями +- Документуйте залежності + +### Не рекомендовано + +- Не створюйте навички для одноразових завдань +- Не дублюйте наявну функціональність +- Не робіть навички занадто широкими +- Не пропускайте поле description +- Не встановлюйте навички з ненадійних джерел без аудиту + +## Усунення несправностей + +### Короткий довідник + +| Проблема | Рішення | +|----------|---------| +| Claude не використовує навичку | Зробіть опис конкретнішим з тригерними термінами | +| Файл навички не знайдено | Перевірте шлях: `~/.claude/skills/name/SKILL.md` | +| Помилки YAML | Перевірте маркери `---`, відступи, відсутність табів | +| Конфлікт навичок | Використовуйте різні тригерні терміни в описах | +| Скрипти не запускаються | Перевірте дозволи: `chmod +x scripts/*.py` | +| Claude не бачить всі навички | Занадто багато навичок; перевірте `/context` на попередження | + +### Навичка не спрацьовує + +Якщо Claude не використовує навичку, коли очікується: + +1. Перевірте, що опис містить ключові слова, які користувачі природно вживають +2. Переконайтесь, що навичка відображається при запиті "What skills are available?" +3. Спробуйте переформулювати запит відповідно до опису +4. Викличте безпосередньо через `/skill-name` для тестування + +### Навичка спрацьовує занадто часто + +Якщо Claude використовує навичку, коли ви цього не хочете: + +1. Зробіть опис конкретнішим +2. Додайте `disable-model-invocation: true` для виклику лише вручну + +### Claude не бачить усі навички + +Описи навичок завантажуються з лімітом **1% контекстного вікна** (резерв: **8 000 символів**). Кожен запис обмежений 250 символами незалежно від бюджету. Запустіть `/context`, щоб перевірити попередження про виключені навички. Перевизначте бюджет змінною оточення `SLASH_COMMAND_TOOL_CHAR_BUDGET`. + +## Питання безпеки + +**Використовуйте навички лише з надійних джерел.** Навички надають Claude можливості через інструкції та код — шкідлива навичка може направити Claude на виклик інструментів або виконання коду небезпечними способами. + +**Ключові питання безпеки:** + +- **Ретельний аудит**: перевіряйте всі файли в каталозі навички +- **Зовнішні джерела ризиковані**: навички, що завантажують із зовнішніх URL, можуть бути скомпрометовані +- **Зловживання інструментами**: шкідливі навички можуть викликати інструменти небезпечними способами +- **Ставтесь як до встановлення ПЗ**: використовуйте навички лише з надійних джерел + +## Навички vs інші функції + +| Функція | Виклик | Найкраще для | +|---------|--------|-------------| +| **Навички** | Авто або `/name` | Повторно використовувана експертиза, воркфлови | +| **Слеш-команди** | Користувач через `/name` | Швидкі ярлики (об'єднано з навичками) | +| **Субагенти** | Автоделегування | Ізольоване виконання завдань | +| **Пам'ять (CLAUDE.md)** | Завжди завантажена | Постійний контекст проєкту | +| **MCP** | У реальному часі | Доступ до зовнішніх даних/сервісів | +| **Хуки** | За подіями | Автоматизовані побічні ефекти | + +## Вбудовані навички + +Claude Code постачається з кількома вбудованими навичками, доступними без встановлення: + +| Навичка | Опис | +|---------|------| +| `/simplify` | Перевірка змінених файлів на повторне використання, якість та ефективність; запускає 3 паралельних агенти рев'ю | +| `/batch ` | Оркестрація масштабних паралельних змін по кодовій базі з використанням git worktrees | +| `/debug [description]` | Усунення несправностей поточної сесії через читання журналу налагодження | +| `/loop [interval] ` | Циклічне виконання промпта з інтервалом (наприклад, `/loop 5m check the deploy`) | +| `/claude-api` | Завантаження довідника Claude API/SDK; автоактивується при імпортах `anthropic`/`@anthropic-ai/sdk` | + +Ці навички доступні одразу і не потребують встановлення чи конфігурації. Вони використовують той самий формат SKILL.md, що й власні навички. + +## Поширення навичок + +### Навички проєкту (командне поширення) + +1. Створіть навичку в `.claude/skills/` +2. Закомітьте в git +3. Члени команди витягують зміни — навички доступні одразу + +### Персональні навички + +```bash +# Копіювання в персональний каталог +cp -r my-skill ~/.claude/skills/ + +# Зробити скрипти виконуваними +chmod +x ~/.claude/skills/my-skill/scripts/*.py +``` + +### Дистрибуція через плагіни + +Пакуйте навички в каталог `skills/` плагіна для ширшої дистрибуції. + +## Далі: колекція навичок та менеджер навичок + +Коли ви починаєте серйозно створювати навички, дві речі стають необхідними: бібліотека перевірених навичок та інструмент для їх управління. + +**[luongnv89/skills](https://github.com/luongnv89/skills)** — колекція навичок, які автор використовує щодня майже у всіх проєктах. Серед цікавих: `logo-designer` (генерація логотипів проєктів на льоту) та `ollama-optimizer` (налаштування продуктивності локальних LLM під ваше обладнання). Хороша відправна точка для готових до використання навичок. + +**[luongnv89/asm](https://github.com/luongnv89/asm)** — Agent Skill Manager. Керує розробкою навичок, виявленням дублікатів та тестуванням. Команда `asm link` дозволяє тестувати навичку в будь-якому проєкті без копіювання файлів — це необхідно, коли навичок більше кількох. + +## Додаткові ресурси + +- [Офіційна документація навичок](https://code.claude.com/docs/en/skills) +- [Блог про архітектуру Agent Skills](https://claude.com/blog/equipping-agents-for-the-real-world-with-agent-skills) +- [Репозиторій навичок](https://github.com/luongnv89/skills) — колекція готових навичок +- [Посібник слеш-команд](../01-slash-commands/) — ярлики, ініційовані користувачем +- [Посібник субагентів](../04-subagents/) — делеговані AI-агенти +- [Посібник з пам'яті](../02-memory/) — постійний контекст +- [MCP (Model Context Protocol)](../05-mcp/) — зовнішні дані в реальному часі +- [Посібник хуків](../06-hooks/) — автоматизація за подіями + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/03-skills/blog-draft/SKILL.md b/uk/03-skills/blog-draft/SKILL.md new file mode 100644 index 0000000..71c5a6b --- /dev/null +++ b/uk/03-skills/blog-draft/SKILL.md @@ -0,0 +1,274 @@ +--- +name: blog-draft +description: Створення чернетки блог-посту з ідей та ресурсів. Використовуйте, коли користувачі хочуть написати блог-пост, створити контент з дослідження або підготувати статтю. Проводить через дослідження, мозковий штурм, складання плану та ітеративне написання з контролем версій. +--- + +## Введення користувача + +```text +$ARGUMENTS +``` + +Ви **ПОВИННІ** врахувати введення користувача перед продовженням. Користувач має надати: +- **Ідея/Тема**: Основна концепція або тематика блог-посту +- **Ресурси**: URL, файли або посилання на дослідження (необовʼязково, але рекомендовано) +- **Цільова аудиторія**: Для кого блог-пост (необовʼязково) +- **Тон/Стиль**: Формальний, невимушений, технічний тощо (необовʼязково) + +**ВАЖЛИВО**: Якщо користувач запитує оновлення **існуючого блог-посту**, пропустіть кроки 0-8 і починайте безпосередньо з **Кроку 9**. Спочатку прочитайте існуючий файл(и) чернетки, потім продовжуйте з процесом ітерації. + +## Потік виконання + +Виконуйте ці кроки послідовно. **Не пропускайте кроки та не продовжуйте без затвердження користувача, де це зазначено.** + +### Крок 0: Створення папки проєкту + +1. Згенерувати назву папки у форматі: `YYYY-MM-DD-short-topic-name` + - Використати сьогоднішню дату + - Створити короткий, URL-дружній slug з теми (малі літери, дефіси, макс. 5 слів) + +2. Створити структуру папок: + ``` + blog-posts/ + └── YYYY-MM-DD-short-topic-name/ + └── resources/ + ``` + +3. Підтвердити створення папки з користувачем перед продовженням. + +### Крок 1: Дослідження та збір ресурсів + +1. Створити підпапку `resources/` у каталозі блог-посту + +2. Для кожного наданого ресурсу: + - **URL-адреси**: Отримати та зберегти ключову інформацію до `resources/` як markdown-файли + - **Файли**: Прочитати та підсумувати в `resources/` + - **Теми**: Використати веб-пошук для збору актуальної інформації + +3. Для кожного ресурсу створити файл резюме в `resources/`: + - `resources/source-1-[short-name].md` + - `resources/source-2-[short-name].md` + - тощо + +4. Кожне резюме має включати: + ```markdown + # Джерело: [Назва/URL] + + ## Ключові тези + - Теза 1 + - Теза 2 + + ## Релевантні цитати/дані + - Цитата або статистика 1 + - Цитата або статистика 2 + + ## Як це стосується теми + Короткий опис релевантності + ``` + +5. Представити резюме дослідження користувачу. + +### Крок 2: Мозковий штурм та уточнення + +1. На основі ідеї та досліджених ресурсів представити: + - **Основні теми**, виявлені з дослідження + - **Потенційні ракурси** для блог-посту + - **Ключові тези**, які слід розкрити + - **Прогалини** в інформації, що потребують уточнення + +2. Поставити уточнюючі запитання: + - Який головний висновок ви хочете донести до читачів? + - Чи є конкретні тези з дослідження, які хочете виділити? + - Яка цільова довжина? (коротка: 500-800 слів, середня: 1000-1500, довга: 2000+) + - Щось хочете виключити? + +3. **Чекати відповідей користувача перед продовженням.** + +### Крок 3: Запропонувати план + +1. Створити структурований план, що включає: + + ```markdown + # План блог-посту: [Назва] + + ## Метаінформація + - **Цільова аудиторія**: [хто] + - **Тон**: [стиль] + - **Цільова довжина**: [кількість слів] + - **Головний висновок**: [ключове повідомлення] + + ## Запропонована структура + + ### Зачіпка/Вступ + - Ідея вступної зачіпки + - Встановлення контексту + - Теза + + ### Розділ 1: [Назва] + - Ключова теза A + - Ключова теза B + - Підтверджуючі докази з [джерела] + + ### Розділ 2: [Назва] + - Ключова теза A + - Ключова теза B + + [Продовжити для всіх розділів...] + + ### Висновок + - Резюме ключових тез + - Заклик до дії або завершальна думка + + ## Джерела для цитування + - Джерело 1 + - Джерело 2 + ``` + +2. Представити план користувачу та **запитати затвердження або модифікації**. + +### Крок 4: Зберегти затверджений план + +1. Після затвердження плану користувачем зберегти його як `OUTLINE.md` у папці блог-посту. + +2. Підтвердити збереження плану. + +### Крок 5: Закомітити план (якщо в git-репо) + +1. Перевірити, чи поточний каталог є git-репозиторієм. + +2. Якщо так: + - Додати нові файли до індексу: папку блог-посту, ресурси та OUTLINE.md + - Створити коміт з повідомленням: `docs: Add outline for blog post - [topic-name]` + - Відправити на віддалений сервер + +3. Якщо не git-репо, пропустити цей крок та повідомити користувача. + +### Крок 6: Написати чернетку + +1. На основі затвердженого плану написати повну чернетку блог-посту. + +2. Точно дотримуватися структури з OUTLINE.md. + +3. Включити: + - Захопливий вступ із зачіпкою + - Чіткі заголовки розділів + - Підтверджуючі докази та приклади з дослідження + - Плавні переходи між розділами + - Сильний висновок з головною тезою + - **Цитування**: Усі порівняння, статистика, дані та фактичні твердження ПОВИННІ цитувати оригінальне джерело + +4. Зберегти чернетку як `draft-v0.1.md` у папці блог-посту. + +5. Формат: + ```markdown + # [Назва блог-посту] + + *[Необовʼязково: підзаголовок або слоган]* + + [Повний вміст з інлайн-цитатами...] + + --- + + ## Список джерел + - [1] Назва джерела 1 - URL або цитата + - [2] Назва джерела 2 - URL або цитата + - [3] Назва джерела 3 - URL або цитата + ``` + +6. **Вимоги до цитування**: + - Кожна точка даних, статистика або порівняння ПОВИННІ мати інлайн-цитату + - Використовуйте нумеровані посилання [1], [2] тощо, або іменовані цитати [Назва джерела] + - Звʼязуйте цитати з розділом Список джерел наприкінці + - Приклад: «Дослідження показують, що 65% розробників віддають перевагу TypeScript [1]» + - Приклад: «React перевершує Vue за швидкістю рендерингу на 20% [React Benchmarks 2024]» + +### Крок 7: Закомітити чернетку (якщо в git-репо) + +1. Перевірити, чи в git-репозиторії. + +2. Якщо так: + - Додати файл чернетки до індексу + - Створити коміт з повідомленням: `docs: Add draft v0.1 for blog post - [topic-name]` + - Відправити на віддалений сервер + +3. Якщо не git-репо, пропустити та повідомити користувача. + +### Крок 8: Представити чернетку для перегляду + +1. Представити вміст чернетки користувачу. + +2. Запитати зворотний звʼязок: + - Загальне враження? + - Розділи, що потребують розширення або скорочення? + - Потрібні корекції тону? + - Відсутня інформація? + - Конкретні правки або переписування? + +3. **Чекати відповіді користувача.** + +### Крок 9: Ітерація або фіналізація + +**Якщо користувач запитує зміни:** +1. Зафіксувати всі запитані модифікації +2. Повернутися до Кроку 6 з такими змінами: + - Збільшити номер версії (v0.2, v0.3 тощо) + - Врахувати всі зауваження + - Зберегти як `draft-v[X.Y].md` + - Повторити Кроки 7-8 + +**Якщо користувач затверджує:** +1. Підтвердити фінальну версію чернетки +2. За бажанням перейменувати на `final.md` +3. Підсумувати процес створення блог-посту: + - Загальна кількість створених версій + - Ключові зміни між версіями + - Фінальна кількість слів + - Створені файли + +## Відстеження версій + +Усі чернетки зберігаються з інкрементальним версіонуванням: +- `draft-v0.1.md` — початкова чернетка +- `draft-v0.2.md` — після першого раунду зауважень +- `draft-v0.3.md` — після другого раунду зауважень +- тощо + +Це дозволяє відстежувати еволюцію блог-посту та повертатися до попередніх версій за потреби. + +## Структура вихідних файлів + +``` +blog-posts/ +└── YYYY-MM-DD-topic-name/ + ├── resources/ + │ ├── source-1-name.md + │ ├── source-2-name.md + │ └── ... + ├── OUTLINE.md + ├── draft-v0.1.md + ├── draft-v0.2.md (якщо ітерації) + └── draft-v0.3.md (якщо більше ітерацій) +``` + +## Поради щодо якості + +- **Зачіпка**: Починайте з питання, дивовижного факту або знайомого сценарію +- **Потік**: Кожен абзац має зʼєднуватися з наступним +- **Докази**: Підтверджуйте твердження даними з дослідження +- **Цитування**: ЗАВЖДИ цитуйте джерела для: + - Усіх статистик та даних (напр., «За даними [Джерело], 75%...») + - Порівнянь між продуктами, сервісами або підходами (напр., «X працює у 2 рази швидше за Y [Джерело]») + - Фактичних тверджень про ринкові тенденції, результати досліджень або бенчмарки + - Використовуйте інлайн-цитати у форматі: [Назва джерела] або [Автор, Рік] +- **Голос**: Підтримуйте послідовний тон протягом усього тексту +- **Довжина**: Дотримуйтесь цільової кількості слів +- **Читабельність**: Використовуйте короткі абзаци, маркери де доречно +- **CTA**: Завершуйте чітким закликом до дії або питанням, що провокує думки + +## Примітки + +- Завжди чекайте затвердження користувача у зазначених контрольних точках +- Зберігайте всі версії чернеток для історії +- Використовуйте веб-пошук для актуальної інформації, коли надані URL +- Якщо ресурсів недостатньо, попросіть користувача надати більше або запропонуйте додаткове дослідження +- Адаптуйте тон відповідно до цільової аудиторії (технічна, загальна, бізнес тощо) diff --git a/uk/03-skills/blog-draft/templates/draft-template.md b/uk/03-skills/blog-draft/templates/draft-template.md new file mode 100644 index 0000000..c03a5f9 --- /dev/null +++ b/uk/03-skills/blog-draft/templates/draft-template.md @@ -0,0 +1,67 @@ +# [Назва блог-посту] + +*[Підзаголовок або слоган — необовʼязково]* + +**[Імʼя автора]** | [Дата] + +--- + +[Вступна зачіпка — одразу захопити увагу] + +[Контекст та передісторія — чому це важливо] + +[Теза — що розкриє цей пост] + +--- + +## [Назва розділу 1] + +[Вміст розділу з чіткою, захопливою прозою] + +[Включити докази, приклади або дані для підтримки тез] + +> «Релевантна цитата з дослідження» — Джерело + +[Перехід до наступного розділу] + +--- + +## [Назва розділу 2] + +[Продовження основного контенту] + +**Ключовий висновок:** [Виділити важливі тези жирним або у виносках] + +[Ще підтверджуючий контент] + +--- + +## [Назва розділу 3] + +[Додаткові розділи за потреби] + +### Підрозділ (за потреби) + +[Вміст підрозділу] + +--- + +## Висновок + +[Підсумувати розкриті ключові тези] + +[Підкріпити головний висновок] + +[Заклик до дії або завершальне твердження, що провокує думки] + +--- + +## Список джерел + +1. [Назва джерела](#) +2. [Назва джерела](#) +3. [Назва джерела](#) + +--- + +*[Необовʼязково: біографія автора або пропозиція повʼязаних постів]* diff --git a/uk/03-skills/blog-draft/templates/outline-template.md b/uk/03-skills/blog-draft/templates/outline-template.md new file mode 100644 index 0000000..5660b01 --- /dev/null +++ b/uk/03-skills/blog-draft/templates/outline-template.md @@ -0,0 +1,97 @@ +# План блог-посту: [Назва] + +## Метаінформація + +| Атрибут | Значення | +|---------|----------| +| **Цільова аудиторія** | [Для кого це?] | +| **Тон** | [Формальний/Невимушений/Технічний/Розмовний] | +| **Цільова довжина** | [Діапазон кількості слів] | +| **Головний висновок** | [Одне речення: що мають запамʼятати читачі?] | +| **Ключові слова** | [SEO-ключові слова, якщо релевантно] | + +--- + +## Запропонована структура + +### 1. Вступ / Зачіпка + +**Варіанти вступної зачіпки:** +- [ ] Питання, що резонує з читачем +- [ ] Вражаюча статистика або факт +- [ ] Коротка історія або сценарій +- [ ] Сміливе твердження + +**Встановлення контексту:** +- Необхідна передісторія +- Чому ця тема важлива зараз + +**Теза:** +- Чітке твердження про те, що розкриє пост + +--- + +### 2. [Назва розділу] + +**Ключові тези:** +- Теза A: [опис] +- Теза B: [опис] + +**Підтверджуючі докази:** +- З [джерела]: [релевантні дані/цитата] + +**Перехід до наступного розділу:** +- [Як це повʼязується з наступним] + +--- + +### 3. [Назва розділу] + +**Ключові тези:** +- Теза A: [опис] +- Теза B: [опис] + +**Підтверджуючі докази:** +- З [джерела]: [релевантні дані/цитата] + +**Перехід до наступного розділу:** +- [Як це повʼязується з наступним] + +--- + +### 4. [Назва розділу] (додайте більше розділів за потреби) + +**Ключові тези:** +- Теза A: [опис] +- Теза B: [опис] + +**Підтверджуючі докази:** +- З [джерела]: [релевантні дані/цитата] + +--- + +### 5. Висновок + +**Резюме ключових тез:** +- Повторення тези 1 +- Повторення тези 2 +- Повторення тези 3 + +**Завершальна думка / Заклик до дії:** +- [Що мають зробити або обміркувати читачі далі?] + +--- + +## Джерела для цитування + +1. [Назва джерела](#) — використано для: [яка інформація] +2. [Назва джерела](#) — використано для: [яка інформація] +3. [Назва джерела](#) — використано для: [яка інформація] + +--- + +## Примітки для написання + +- [Будь-які конкретні вимоги або обмеження] +- [Що наголосити] +- [Чого уникати] diff --git a/uk/03-skills/brand-voice/SKILL.md b/uk/03-skills/brand-voice/SKILL.md new file mode 100644 index 0000000..b3e2cde --- /dev/null +++ b/uk/03-skills/brand-voice/SKILL.md @@ -0,0 +1,72 @@ +--- +name: brand-voice-consistency +description: Забезпечення відповідності всіх комунікацій голосу та тону бренду. Використовуйте при створенні маркетингових текстів, клієнтських комунікацій, публічного контенту, або коли користувачі згадують голос бренду, тон чи стиль написання. +--- + +# Навичка голосу бренду + +## Огляд +Ця навичка забезпечує послідовність голосу бренду, тону та повідомлень у всіх комунікаціях. + +## Ідентичність бренду + +### Місія +Допомогти командам автоматизувати робочі процеси розробки за допомогою AI + +### Цінності +- **Простота**: Робити складне простим +- **Надійність**: Непохитне виконання +- **Розширення можливостей**: Дати простір людській креативності + +### Тон голосу +- **Дружній, але професійний** — доступний, але не панібратський +- **Зрозумілий і лаконічний** — уникати жаргону, пояснювати технічні концепції просто +- **Впевнений** — ми знаємо, що робимо +- **Емпатичний** — розуміємо потреби та болі користувачів + +## Рекомендації щодо написання + +### Рекомендовано ✅ +- Використовуйте «ви» при зверненні до читачів +- Використовуйте активний стан: «Claude генерує звіти», а не «Звіти генеруються Claude» +- Починайте з ціннісної пропозиції +- Використовуйте конкретні приклади +- Тримайте речення до 20 слів +- Використовуйте списки для ясності +- Включайте заклики до дії + +### Не рекомендовано ❌ +- Не використовуйте корпоративний жаргон +- Не будьте поблажливими та не надмірно спрощуйте +- Не використовуйте «ми вважаємо» або «ми думаємо» +- Не використовуйте ВСІ ВЕЛИКІ ЛІТЕРИ, крім виділення +- Не створюйте стіни тексту +- Не припускайте наявність технічних знань + +## Словник + +### ✅ Бажані терміни +- Claude (не «AI Claude») +- Генерація коду (не «автокодування») +- Агент (не «бот») +- Оптимізувати (не «революціонізувати») +- Інтегрувати (не «синергізувати») + +### ❌ Уникати +- «Передовий» (заїжджено) +- «Проривний» (розмито) +- «Левериджити» (корпоративний жаргон) +- «Утилізувати» (використовуйте «використовувати») +- «Зміна парадигми» (незрозуміло) + +## Приклади + +### ✅ Вдалий приклад +«Claude автоматизує ваш процес код-рев'ю. Замість ручної перевірки кожного PR, Claude перевіряє безпеку, продуктивність та якість — заощаджуючи вашій команді години щотижня.» + +Чому працює: Зрозуміла цінність, конкретні переваги, орієнтація на дію + +### ❌ Невдалий приклад +«Claude левериджить передовий AI для надання комплексних рішень розробки програмного забезпечення.» + +Чому не працює: Розмито, корпоративний жаргон, немає конкретної цінності diff --git a/uk/03-skills/brand-voice/templates/email-template.txt b/uk/03-skills/brand-voice/templates/email-template.txt new file mode 100644 index 0000000..b335fa6 --- /dev/null +++ b/uk/03-skills/brand-voice/templates/email-template.txt @@ -0,0 +1,14 @@ +Тема: [Чітка, орієнтована на вигоду тема] + +Вітаю, [Ім'я]! + +[Вступ: Яка цінність для них] + +[Основна частина: Як це працює / Що вони отримають] + +[Конкретний приклад або вигода] + +[Заклик до дії: Чіткий наступний крок] + +З повагою, +[Ім'я] diff --git a/uk/03-skills/brand-voice/templates/social-post-template.txt b/uk/03-skills/brand-voice/templates/social-post-template.txt new file mode 100644 index 0000000..62e2578 --- /dev/null +++ b/uk/03-skills/brand-voice/templates/social-post-template.txt @@ -0,0 +1,4 @@ +[Хук: Привернути увагу в першому рядку] +[2-3 рядки: Цінність або цікавий факт] +[Заклик до дії: Посилання, питання або залучення] +[Емодзі: 1-2 максимум для візуального інтересу] diff --git a/uk/03-skills/brand-voice/tone-examples.md b/uk/03-skills/brand-voice/tone-examples.md new file mode 100644 index 0000000..da19aaa --- /dev/null +++ b/uk/03-skills/brand-voice/tone-examples.md @@ -0,0 +1,13 @@ +# Приклади тону бренду + +## Захоплива анонс +"Зекономте 8 годин на тиждень на код-рев'ю. Claude переглядає ваші PR автоматично." + +## Емпатична підтримка +"Ми знаємо, що деплої можуть бути стресовими. Claude бере тестування на себе, щоб вам не хвилюватися." + +## Впевнена презентація продукту +"Claude не просто пропонує код. Він розуміє вашу архітектуру і підтримує консистентність." + +## Освітній блог-пост +"Давайте розглянемо, як агенти покращують процеси код-рев'ю. Ось що ми дізналися..." diff --git a/uk/03-skills/claude-md/SKILL.md b/uk/03-skills/claude-md/SKILL.md new file mode 100644 index 0000000..6e4b8b8 --- /dev/null +++ b/uk/03-skills/claude-md/SKILL.md @@ -0,0 +1,212 @@ +--- +name: claude-md +description: Створення або оновлення файлів CLAUDE.md відповідно до найкращих практик для оптимального онбордингу AI-агента +--- + +## Введення користувача + +```text +$ARGUMENTS +``` + +Ви **ПОВИННІ** врахувати введення користувача перед продовженням (якщо не порожнє). Користувач може вказати: +- `create` — створити новий CLAUDE.md з нуля +- `update` — покращити існуючий CLAUDE.md +- `audit` — проаналізувати та звітувати про якість поточного CLAUDE.md +- Конкретний шлях для створення/оновлення (напр., `src/api/CLAUDE.md` для інструкцій, специфічних для каталогу) + +## Основні принципи + +**LLM не мають стану**: CLAUDE.md — єдиний файл, що автоматично включається в кожну розмову. Він слугує головним документом онбордингу AI-агентів у вашу кодову базу. + +### Золоті правила + +1. **Менше — краще**: Найсучасніші LLM можуть дотримуватись ~150-200 інструкцій. Системний промпт Claude Code вже використовує ~50. Тримайте CLAUDE.md зосередженим та лаконічним. + +2. **Універсальна застосовність**: Включайте лише інформацію, релевантну для КОЖНОЇ сесії. Інструкції для конкретних завдань належать до окремих файлів. + +3. **Не використовуйте Claude як лінтер**: Рекомендації зі стилю роздувають контекст та погіршують дотримання інструкцій. Використовуйте натомість детерміністичні інструменти (prettier, eslint тощо). + +4. **Ніколи не генеруйте автоматично**: CLAUDE.md — найвпливовіша точка AI-системи. Створюйте його вручну з ретельним обмірковуванням. + +## Потік виконання + +### 1. Аналіз проєкту + +Спочатку проаналізуйте поточний стан проєкту: + +1. Перевірити наявні файли CLAUDE.md: + - Кореневий рівень: `./CLAUDE.md` або `.claude/CLAUDE.md` + - Специфічні для каталогу: `**/CLAUDE.md` + - Глобальний конфіг користувача: `~/.claude/CLAUDE.md` + +2. Визначити структуру проєкту: + - Технологічний стек (мови, фреймворки) + - Тип проєкту (монорепо, окремий додаток, бібліотека) + - Інструменти розробки (пакетний менеджер, система збірки, тест-раннер) + +3. Переглянути існуючу документацію: + - README.md + - CONTRIBUTING.md + - package.json, pyproject.toml, Cargo.toml тощо + +### 2. Стратегія контенту (ЩО, ЧОМУ, ЯК) + +Структуруйте CLAUDE.md навколо трьох вимірів: + +#### ЩО — Технологія та структура +- Огляд технологічного стеку +- Організація проєкту (особливо важливо для монорепо) +- Ключові каталоги та їхнє призначення + +#### ЧОМУ — Призначення та контекст +- Що робить проєкт +- Чому були прийняті певні архітектурні рішення +- За що відповідає кожен основний компонент + +#### ЯК — Робочий процес та конвенції +- Робочий процес розробки (bun vs node, pip vs uv тощо) +- Процедури та команди тестування +- Методи верифікації та збірки +- Критичні «підводні камені» або неочевидні вимоги + +### 3. Стратегія поступового розкриття + +Для великих проєктів рекомендуйте створити папку `agent_docs/`: + +``` +agent_docs/ + |- building_the_project.md + |- running_tests.md + |- code_conventions.md + |- architecture_decisions.md +``` + +У CLAUDE.md посилайтесь на ці файли інструкціями: +```markdown +For detailed build instructions, refer to `agent_docs/building_the_project.md` +``` + +**Важливо**: Використовуйте посилання `файл:рядок` замість фрагментів коду, щоб уникнути застарілого контексту. + +### 4. Обмеження якості + +При створенні або оновленні CLAUDE.md: + +1. **Цільова довжина**: Менше 300 рядків (ідеально — менше 100) +2. **Без правил стилю**: Видалити будь-які інструкції лінтингу/форматування +3. **Без інструкцій для конкретних завдань**: Перемістити до окремих файлів +4. **Без фрагментів коду**: Використовувати посилання на файли замість цього +5. **Без надлишкової інформації**: Не повторювати те, що є в package.json або README + +### 5. Обовʼязкові секції + +Добре структурований CLAUDE.md має включати: + +```markdown +# Назва проєкту + +Короткий однорядковий опис. + +## Технологічний стек +- Основна мова та версія +- Ключові фреймворки/бібліотеки +- База даних/сховище (якщо є) + +## Структура проєкту +[Лише для монорепо або складних структур] +- `apps/` - Точки входу додатків +- `packages/` - Спільні бібліотеки + +## Команди розробки +- Встановлення: `команда` +- Тестування: `команда` +- Збірка: `команда` + +## Критичні конвенції +[Лише неочевидні, високовпливові конвенції] +- Конвенція 1 з коротким поясненням +- Конвенція 2 з коротким поясненням + +## Відомі проблеми / Підводні камені +[Речі, що постійно створюють труднощі розробникам] +- Проблема 1 +- Проблема 2 +``` + +### 6. Антипатерни, яких слід уникати + +**НЕ включайте:** +- Рекомендації зі стилю коду (використовуйте лінтери) +- Документацію щодо використання Claude +- Довгі пояснення очевидних патернів +- Скопійовані приклади коду +- Загальні найкращі практики («пишіть чистий код») +- Інструкції для конкретних завдань +- Автозгенерований контент +- Розлогі списки TODO + +### 7. Контрольний список валідації + +Перед фіналізацією перевірте: + +- [ ] Менше 300 рядків (бажано менше 100) +- [ ] Кожен рядок застосовний до ВСІХ сесій +- [ ] Без правил стилю/форматування +- [ ] Без фрагментів коду (використані посилання на файли) +- [ ] Команди перевірені на працездатність +- [ ] Поступове розкриття використано для складних проєктів +- [ ] Критичні підводні камені задокументовані +- [ ] Немає надлишковості з README.md + +## Формат виводу + +### Для `create` або за замовчуванням: + +1. Проаналізувати проєкт +2. Створити чернетку CLAUDE.md за структурою вище +3. Представити чернетку для перегляду +4. Записати у відповідне місце після затвердження + +### Для `update`: + +1. Прочитати існуючий CLAUDE.md +2. Аудит за найкращими практиками +3. Визначити: + - Контент для видалення (правила стилю, фрагменти коду, специфічне для завдань) + - Контент для скорочення + - Відсутню важливу інформацію +4. Представити зміни для перегляду +5. Застосувати зміни після затвердження + +### Для `audit`: + +1. Прочитати існуючий CLAUDE.md +2. Згенерувати звіт з: + - Поточна кількість рядків vs ціль + - Відсоток універсально застосовного контенту + - Список знайдених антипатернів + - Рекомендації для покращення +3. НЕ модифікувати файл, лише звітувати + +## Обробка AGENTS.md + +Якщо користувач запитує створення/оновлення AGENTS.md: + +AGENTS.md використовується для визначення спеціалізованої поведінки агентів. На відміну від CLAUDE.md (який для контексту проєкту), AGENTS.md визначає: +- Кастомні ролі та можливості агентів +- Інструкції та обмеження для конкретних агентів +- Визначення робочих процесів для мультиагентних сценаріїв + +Застосовуйте аналогічні принципи: +- Тримайте зосередженим та лаконічним +- Використовуйте поступове розкриття +- Посилайтесь на зовнішні документи замість вбудовування контенту + +## Примітки + +- Завжди перевіряйте працездатність команд перед їх включенням +- Якщо сумніваєтесь — не включайте; менше — краще +- Системне нагадування повідомляє Claude, що CLAUDE.md «може бути або не бути релевантним» — чим більше шуму, тим більше він ігнорується +- Монорепо найбільше виграють від чіткої структури ЩО/ЧОМУ/ЯК +- Файли CLAUDE.md для конкретних каталогів мають бути ще більш зосередженими diff --git a/uk/03-skills/code-review/SKILL.md b/uk/03-skills/code-review/SKILL.md new file mode 100644 index 0000000..d11b215 --- /dev/null +++ b/uk/03-skills/code-review/SKILL.md @@ -0,0 +1,70 @@ +--- +name: code-review-specialist +description: Комплексне код-рев'ю з аналізом безпеки, продуктивності та якості. Використовуйте, коли користувачі просять переглянути код, проаналізувати якість коду, оцінити pull request, або згадують код-рев'ю, аналіз безпеки чи оптимізацію продуктивності. +--- + +# Навичка код-рев'ю + +Ця навичка забезпечує комплексні можливості код-рев'ю з фокусом на: + +1. **Аналіз безпеки** + - Проблеми автентифікації/авторизації + - Ризики розкриття даних + - Вразливості інʼєкцій + - Криптографічні слабкості + - Логування чутливих даних + +2. **Аналіз продуктивності** + - Ефективність алгоритмів (аналіз Big O) + - Оптимізація памʼяті + - Оптимізація запитів до БД + - Можливості кешування + - Проблеми конкурентності + +3. **Якість коду** + - Принципи SOLID + - Патерни проєктування + - Конвенції іменування + - Документація + - Покриття тестами + +4. **Супровідність** + - Читабельність коду + - Розмір функцій (має бути < 50 рядків) + - Цикломатична складність + - Управління залежностями + - Безпека типів + +## Шаблон рев'ю + +Для кожного фрагмента перевіреного коду надати: + +### Резюме +- Загальна оцінка якості (1-5) +- Кількість виявлених проблем +- Рекомендовані пріоритетні зони + +### Критичні проблеми (якщо є) +- **Проблема**: Чіткий опис +- **Розташування**: Файл і номер рядка +- **Вплив**: Чому це важливо +- **Серйозність**: Критична/Висока/Середня +- **Виправлення**: Приклад коду + +### Знахідки за категоріями + +#### Безпека (якщо знайдено проблеми) +Перелік вразливостей безпеки з прикладами + +#### Продуктивність (якщо знайдено проблеми) +Перелік проблем продуктивності з аналізом складності + +#### Якість (якщо знайдено проблеми) +Перелік проблем якості коду з пропозиціями рефакторингу + +#### Супровідність (якщо знайдено проблеми) +Перелік проблем супровідності з покращеннями + +## Історія версій + +- v1.0.0 (2024-12-10): Початковий випуск з аналізом безпеки, продуктивності, якості та супровідності diff --git a/uk/03-skills/code-review/scripts/analyze-metrics.py b/uk/03-skills/code-review/scripts/analyze-metrics.py new file mode 100644 index 0000000..e294973 --- /dev/null +++ b/uk/03-skills/code-review/scripts/analyze-metrics.py @@ -0,0 +1,35 @@ +#!/usr/bin/env python3 +import re +import sys + + +def analyze_code_metrics(code): + """Analyze code for common metrics.""" + + # Count functions + functions = len(re.findall(r"^def\s+\w+", code, re.MULTILINE)) + + # Count classes + classes = len(re.findall(r"^class\s+\w+", code, re.MULTILINE)) + + # Average line length + lines = code.split("\n") + avg_length = sum(len(l) for l in lines) / len(lines) if lines else 0 + + # Estimate complexity + complexity = len(re.findall(r"\b(if|elif|else|for|while|and|or)\b", code)) + + return { + "functions": functions, + "classes": classes, + "avg_line_length": avg_length, + "complexity_score": complexity, + } + + +if __name__ == "__main__": + with open(sys.argv[1]) as f: + code = f.read() + metrics = analyze_code_metrics(code) + for key, value in metrics.items(): + print(f"{key}: {value:.2f}") diff --git a/uk/03-skills/code-review/scripts/compare-complexity.py b/uk/03-skills/code-review/scripts/compare-complexity.py new file mode 100644 index 0000000..d4aba23 --- /dev/null +++ b/uk/03-skills/code-review/scripts/compare-complexity.py @@ -0,0 +1,174 @@ +#!/usr/bin/env python3 +""" +Compare cyclomatic complexity of code before and after changes. +Helps identify if refactoring actually simplifies code structure. +""" + +import re +import sys + + +class ComplexityAnalyzer: + """Analyze code complexity metrics.""" + + def __init__(self, code: str): + self.code = code + self.lines = code.split("\n") + + def calculate_cyclomatic_complexity(self) -> int: + """ + Calculate cyclomatic complexity using McCabe's method. + Count decision points: if, elif, else, for, while, except, and, or + """ + complexity = 1 # Base complexity + + # Count decision points + decision_patterns = [ + r"\bif\b", + r"\belif\b", + r"\bfor\b", + r"\bwhile\b", + r"\bexcept\b", + r"\band\b(?!$)", + r"\bor\b(?!$)", + ] + + for pattern in decision_patterns: + matches = re.findall(pattern, self.code) + complexity += len(matches) + + return complexity + + def calculate_cognitive_complexity(self) -> int: + """ + Calculate cognitive complexity - how hard is it to understand? + Based on nesting depth and control flow. + """ + cognitive = 0 + nesting_depth = 0 + + for line in self.lines: + # Track nesting depth + if re.search(r"^\s*(if|for|while|def|class|try)\b", line): + nesting_depth += 1 + cognitive += nesting_depth + elif re.search(r"^\s*(elif|else|except|finally)\b", line): + cognitive += nesting_depth + + # Reduce nesting when unindenting + if line and not line[0].isspace(): + nesting_depth = 0 + + return cognitive + + def calculate_maintainability_index(self) -> float: + """ + Maintainability Index ranges from 0-100. + > 85: Excellent + > 65: Good + > 50: Fair + < 50: Poor + """ + lines = len(self.lines) + cyclomatic = self.calculate_cyclomatic_complexity() + cognitive = self.calculate_cognitive_complexity() + + # Simplified MI calculation + mi = ( + 171 + - 5.2 * (cyclomatic / lines) + - 0.23 * (cognitive) + - 16.2 * (lines / 1000) + ) + + return max(0, min(100, mi)) + + def get_complexity_report(self) -> dict: + """Generate comprehensive complexity report.""" + return { + "cyclomatic_complexity": self.calculate_cyclomatic_complexity(), + "cognitive_complexity": self.calculate_cognitive_complexity(), + "maintainability_index": round(self.calculate_maintainability_index(), 2), + "lines_of_code": len(self.lines), + "avg_line_length": round( + sum(len(l) for l in self.lines) / len(self.lines), 2 + ) + if self.lines + else 0, + } + + +def compare_files(before_file: str, after_file: str) -> None: + """Compare complexity metrics between two code versions.""" + + with open(before_file) as f: + before_code = f.read() + + with open(after_file) as f: + after_code = f.read() + + before_analyzer = ComplexityAnalyzer(before_code) + after_analyzer = ComplexityAnalyzer(after_code) + + before_metrics = before_analyzer.get_complexity_report() + after_metrics = after_analyzer.get_complexity_report() + + print("=" * 60) + print("CODE COMPLEXITY COMPARISON") + print("=" * 60) + + print("\nBEFORE:") + print(f" Cyclomatic Complexity: {before_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {before_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {before_metrics['maintainability_index']}") + print(f" Lines of Code: {before_metrics['lines_of_code']}") + print(f" Avg Line Length: {before_metrics['avg_line_length']}") + + print("\nAFTER:") + print(f" Cyclomatic Complexity: {after_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {after_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {after_metrics['maintainability_index']}") + print(f" Lines of Code: {after_metrics['lines_of_code']}") + print(f" Avg Line Length: {after_metrics['avg_line_length']}") + + print("\nCHANGES:") + cyclomatic_change = ( + after_metrics["cyclomatic_complexity"] - before_metrics["cyclomatic_complexity"] + ) + cognitive_change = ( + after_metrics["cognitive_complexity"] - before_metrics["cognitive_complexity"] + ) + mi_change = ( + after_metrics["maintainability_index"] - before_metrics["maintainability_index"] + ) + loc_change = after_metrics["lines_of_code"] - before_metrics["lines_of_code"] + + print(f" Cyclomatic Complexity: {cyclomatic_change:+d}") + print(f" Cognitive Complexity: {cognitive_change:+d}") + print(f" Maintainability Index: {mi_change:+.2f}") + print(f" Lines of Code: {loc_change:+d}") + + print("\nASSESSMENT:") + if mi_change > 0: + print(" ✅ Code is MORE maintainable") + elif mi_change < 0: + print(" ⚠️ Code is LESS maintainable") + else: + print(" ➡️ Maintainability unchanged") + + if cyclomatic_change < 0: + print(" ✅ Complexity DECREASED") + elif cyclomatic_change > 0: + print(" ⚠️ Complexity INCREASED") + else: + print(" ➡️ Complexity unchanged") + + print("=" * 60) + + +if __name__ == "__main__": + if len(sys.argv) != 3: + print("Usage: python compare-complexity.py ") + sys.exit(1) + + compare_files(sys.argv[1], sys.argv[2]) diff --git a/uk/03-skills/code-review/templates/finding-template.md b/uk/03-skills/code-review/templates/finding-template.md new file mode 100644 index 0000000..d1b99ea --- /dev/null +++ b/uk/03-skills/code-review/templates/finding-template.md @@ -0,0 +1,112 @@ +# Шаблон знахідки код-рев'ю + +Використовуйте цей шаблон для документування кожної знайденої проблеми під час код-рев'ю. + +--- + +## Проблема: [НАЗВА] + +### Серйозність +- [ ] Критична (блокує деплой) +- [ ] Висока (потрібно виправити перед мерджем) +- [ ] Середня (потрібно виправити незабаром) +- [ ] Низька (бажано виправити) + +### Категорія +- [ ] Безпека +- [ ] Продуктивність +- [ ] Якість коду +- [ ] Підтримуваність +- [ ] Тестування +- [ ] Патерн проєктування +- [ ] Документація + +### Розташування +**Файл:** `src/components/UserCard.tsx` + +**Рядки:** 45-52 + +**Функція/Метод:** `renderUserDetails()` + +### Опис проблеми + +**Що:** Опишіть суть проблеми. + +**Чому це важливо:** Поясніть вплив та чому це потрібно виправити. + +**Поточна поведінка:** Покажіть проблемний код або поведінку. + +**Очікувана поведінка:** Опишіть, що повинно відбуватися замість цього. + +### Приклад коду + +#### Поточний (проблемний) + +```typescript +// Shows the N+1 query problem +const users = fetchUsers(); +users.forEach(user => { + const posts = fetchUserPosts(user.id); // Query per user! + renderUserPosts(posts); +}); +``` + +#### Запропоноване виправлення + +```typescript +// Optimized with JOIN query +const usersWithPosts = fetchUsersWithPosts(); +usersWithPosts.forEach(({ user, posts }) => { + renderUserPosts(posts); +}); +``` + +### Аналіз впливу + +| Аспект | Вплив | Серйозність | +|--------|-------|-------------| +| Продуктивність | 100+ запитів для 20 користувачів | Висока | +| Досвід користувача | Повільне завантаження сторінки | Висока | +| Масштабованість | Ламається при масштабуванні | Критична | +| Підтримуваність | Складно дебажити | Середня | + +### Пов'язані проблеми + +- Аналогічна проблема в `AdminUserList.tsx` рядок 120 +- Пов'язаний PR: #456 +- Пов'язана issue: #789 + +### Додаткові ресурси + +- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) +- [Database Join Documentation](https://docs.example.com/joins) + +### Нотатки рецензента + +- Це поширений патерн у цій кодовій базі +- Варто додати це до гайду зі стилю коду +- Можливо, варто створити допоміжну функцію + +### Відповідь автора (для зворотного зв'язку) + +*Заповнюється автором коду:* + +- [ ] Виправлення реалізовано в коміті: `abc123` +- [ ] Статус виправлення: Завершено / В процесі / Потребує обговорення +- [ ] Питання або зауваження: (опишіть) + +--- + +## Статистика знахідок (для рецензента) + +При рев'ю кількох знахідок, відстежуйте: + +- **Всього знайдено проблем:** X +- **Критичних:** X +- **Високих:** X +- **Середніх:** X +- **Низьких:** X + +**Рекомендація:** ✅ Затвердити / ⚠️ Запросити зміни / 🔄 Потребує обговорення + +**Загальна якість коду:** 1-5 зірок diff --git a/uk/03-skills/code-review/templates/review-checklist.md b/uk/03-skills/code-review/templates/review-checklist.md new file mode 100644 index 0000000..774cfc0 --- /dev/null +++ b/uk/03-skills/code-review/templates/review-checklist.md @@ -0,0 +1,47 @@ +# Чеклист код-рев'ю + +## Чеклист безпеки +- [ ] Немає захардкоджених облікових даних або секретів +- [ ] Валідація введення для всіх даних від користувача +- [ ] Захист від SQL-ін'єкцій (параметризовані запити) +- [ ] CSRF-захист для операцій зі зміною стану +- [ ] Захист від XSS з правильним екрануванням +- [ ] Перевірка автентифікації на захищених ендпоінтах +- [ ] Перевірка авторизації для ресурсів +- [ ] Безпечне хешування паролів (bcrypt, argon2) +- [ ] Немає чутливих даних у логах +- [ ] HTTPS обов'язковий + +## Чеклист продуктивності +- [ ] Немає N+1 запитів +- [ ] Правильне використання індексів +- [ ] Кешування реалізовано де доцільно +- [ ] Немає блокуючих операцій в основному потоці +- [ ] Async/await використовується коректно +- [ ] Великі набори даних пагіновані +- [ ] Пул з'єднань до бази даних +- [ ] Регулярні вирази оптимізовані +- [ ] Немає зайвого створення об'єктів +- [ ] Витоки пам'яті запобігаються + +## Чеклист якості +- [ ] Функції < 50 рядків +- [ ] Зрозумілі назви змінних +- [ ] Немає дублювання коду +- [ ] Правильна обробка помилок +- [ ] Коментарі пояснюють ЧОМУ, а не ЩО +- [ ] Немає console.log у продакшені +- [ ] Перевірка типів (TypeScript/JSDoc) +- [ ] Принципи SOLID дотримані +- [ ] Патерни проєктування застосовані коректно +- [ ] Самодокументований код + +## Чеклист тестування +- [ ] Юніт-тести написані +- [ ] Граничні випадки покриті +- [ ] Сценарії помилок протестовані +- [ ] Інтеграційні тести є +- [ ] Покриття > 80% +- [ ] Немає нестабільних тестів +- [ ] Зовнішні залежності замоковані +- [ ] Зрозумілі назви тестів diff --git a/uk/03-skills/doc-generator/SKILL.md b/uk/03-skills/doc-generator/SKILL.md new file mode 100644 index 0000000..00c7103 --- /dev/null +++ b/uk/03-skills/doc-generator/SKILL.md @@ -0,0 +1,76 @@ +--- +name: api-documentation-generator +description: Генерація вичерпної, точної документації API з вихідного коду. Використовуйте при створенні або оновленні документації API, генерації специфікацій OpenAPI, або коли користувачі згадують документацію API, ендпоінти чи документацію. +--- + +# Навичка генерації документації API + +## Генерує + +- Специфікації OpenAPI/Swagger +- Документацію ендпоінтів API +- Приклади використання SDK +- Посібники з інтеграції +- Довідники кодів помилок +- Посібники з автентифікації + +## Структура документації + +### Для кожного ендпоінту + +```markdown +## GET /api/v1/users/:id + +### Опис +Короткий опис призначення цього ендпоінту + +### Параметри + +| Назва | Тип | Обовʼязковий | Опис | +|-------|-----|-------------|------| +| id | string | Так | ID користувача | + +### Відповідь + +**200 Успіх** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 Не знайдено** +```json +{ + "error": "USER_NOT_FOUND", + "message": "Користувач не існує" +} +``` + +### Приклади + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` +``` diff --git a/uk/03-skills/doc-generator/generate-docs.py b/uk/03-skills/doc-generator/generate-docs.py new file mode 100644 index 0000000..3a0f588 --- /dev/null +++ b/uk/03-skills/doc-generator/generate-docs.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python3 +import ast + + +class APIDocExtractor(ast.NodeVisitor): + """Extract API documentation from Python source code.""" + + def __init__(self): + self.endpoints = [] + + def visit_FunctionDef(self, node): + """Extract function documentation.""" + if node.name.startswith("get_") or node.name.startswith("post_"): + doc = ast.get_docstring(node) + endpoint = { + "name": node.name, + "docstring": doc, + "params": [arg.arg for arg in node.args.args], + "returns": self._extract_return_type(node), + } + self.endpoints.append(endpoint) + self.generic_visit(node) + + def _extract_return_type(self, node): + """Extract return type from function annotation.""" + if node.returns: + return ast.unparse(node.returns) + return "Any" + + +def generate_markdown_docs(endpoints: list[dict]) -> str: + """Generate markdown documentation from endpoints.""" + docs = "# API Documentation\n\n" + + for endpoint in endpoints: + docs += f"## {endpoint['name']}\n\n" + docs += f"{endpoint['docstring']}\n\n" + docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n" + docs += f"**Returns**: {endpoint['returns']}\n\n" + docs += "---\n\n" + + return docs + + +if __name__ == "__main__": + import sys + + with open(sys.argv[1]) as f: + tree = ast.parse(f.read()) + + extractor = APIDocExtractor() + extractor.visit(tree) + + markdown = generate_markdown_docs(extractor.endpoints) + print(markdown) diff --git a/uk/03-skills/refactor/SKILL.md b/uk/03-skills/refactor/SKILL.md new file mode 100644 index 0000000..ab50114 --- /dev/null +++ b/uk/03-skills/refactor/SKILL.md @@ -0,0 +1,426 @@ +--- +name: code-refactor +description: Систематичний рефакторинг коду на основі методології Мартіна Фаулера. Використовуйте, коли користувачі просять рефакторити код, покращити структуру коду, зменшити технічний борг, очистити застарілий код, усунути запахи коду (code smells) або покращити супровідність коду. Ця навичка проводить через поетапний підхід з дослідженням, плануванням та безпечною інкрементальною реалізацією. +--- + +# Навичка рефакторингу коду + +Систематичний підхід до рефакторингу коду на основі книги Мартіна Фаулера *Refactoring: Improving the Design of Existing Code* (2-ге видання). Ця навичка наголошує на безпечних, інкрементальних змінах, підкріплених тестами. + +> «Рефакторинг — це процес зміни програмної системи таким чином, що не змінює зовнішню поведінку коду, але покращує його внутрішню структуру.» — Мартін Фаулер + +## Основні принципи + +1. **Збереження поведінки**: Зовнішня поведінка повинна залишатися незмінною +2. **Малі кроки**: Робити крихітні, тестовані зміни +3. **Тест-орієнтованість**: Тести — це страхувальна сітка +4. **Безперервність**: Рефакторинг — постійний процес, а не одноразова подія +5. **Співпраця**: Затвердження користувача потрібне на кожній фазі + +## Огляд робочого процесу + +``` +Фаза 1: Дослідження та аналіз + ↓ +Фаза 2: Оцінка покриття тестами + ↓ +Фаза 3: Виявлення запахів коду + ↓ +Фаза 4: Створення плану рефакторингу + ↓ +Фаза 5: Інкрементальна реалізація + ↓ +Фаза 6: Перегляд та ітерація +``` + +--- + +## Фаза 1: Дослідження та аналіз + +### Цілі +- Зрозуміти структуру та призначення кодової бази +- Визначити обсяг рефакторингу +- Зібрати контекст про бізнес-вимоги + +### Запитання до користувача +Перед початком уточніть: + +1. **Обсяг**: Які файли/модулі/функції потребують рефакторингу? +2. **Цілі**: Які проблеми ви намагаєтесь вирішити? (читабельність, продуктивність, супровідність) +3. **Обмеження**: Чи є зони, які НЕ слід змінювати? +4. **Тиск термінів**: Чи блокує це іншу роботу? +5. **Стан тестів**: Чи існують тести? Чи проходять вони? + +### Дії +- [ ] Прочитати та зрозуміти цільовий код +- [ ] Виявити залежності та інтеграції +- [ ] Задокументувати поточну архітектуру +- [ ] Зафіксувати існуючі маркери технічного боргу (TODOs, FIXMEs) + +### Вивід +Представити знахідки користувачу: +- Резюме структури коду +- Виявлені проблемні зони +- Початкові рекомендації +- **Запросити затвердження для продовження** + +--- + +## Фаза 2: Оцінка покриття тестами + +### Чому тести важливі +> «Рефакторинг без тестів — як їзда без пасків безпеки.» — Мартін Фаулер + +Тести — **ключовий засіб** безпечного рефакторингу. Без них ви ризикуєте внести помилки. + +### Кроки оцінки + +1. **Перевірити наявні тести** + ```bash + # Пошук файлів тестів + find . -name "*test*" -o -name "*spec*" | head -20 + ``` + +2. **Запустити існуючі тести** + ```bash + # JavaScript/TypeScript + npm test + + # Python + pytest -v + + # Java + mvn test + ``` + +3. **Перевірити покриття (якщо доступно)** + ```bash + # JavaScript + npm run test:coverage + + # Python + pytest --cov=. + ``` + +### Точка рішення: Запитати користувача + +**Якщо тести існують та проходять:** +- Перейти до Фази 3 + +**Якщо тести відсутні або неповні:** +Представити варіанти: +1. Спочатку написати тести (рекомендовано) +2. Додавати тести інкрементально під час рефакторингу +3. Продовжити без тестів (ризиковано — потребує підтвердження користувача) + +**Якщо тести не проходять:** +- ЗУПИНИТИСЯ. Виправити тести перед рефакторингом +- Запитати користувача: Чи слід спочатку виправити тести? + +### Рекомендації щодо написання тестів (якщо потрібно) + +Для кожної функції, що рефакториться, забезпечити тести для: +- Успішний шлях (нормальна робота) +- Граничні випадки (порожні введення, null, межі) +- Сценарії помилок (невалідні введення, виключення) + +Використовуйте цикл «red-green-refactor»: +1. Написати тест, що не проходить (red) +2. Зробити так, щоб пройшов (green) +3. Рефакторити + +--- + +## Фаза 3: Виявлення запахів коду + +### Що таке запахи коду? +Симптоми глибших проблем у коді. Це не помилки, а індикатори того, що код можна покращити. + +### Типові запахи коду для перевірки + +Див. [references/code-smells.md](references/code-smells.md) для повного каталогу. + +#### Короткий довідник + +| Запах | Ознаки | Вплив | +|-------|--------|-------| +| **Довгий метод** | Методи > 30-50 рядків | Важко зрозуміти, тестувати, супроводжувати | +| **Дубльований код** | Та сама логіка в кількох місцях | Виправлення помилок потрібне в кількох місцях | +| **Великий клас** | Клас з занадто багатьма відповідальностями | Порушує принцип єдиної відповідальності | +| **Заздрість до функцій** | Метод використовує дані іншого класу більше | Погана інкапсуляція | +| **Одержимість примітивами** | Надмірне використання примітивів замість обʼєктів | Відсутні доменні концепції | +| **Довгий список параметрів** | Методи з 4+ параметрами | Складно викликати правильно | +| **Групи даних** | Ті самі елементи даних зʼявляються разом | Відсутня абстракція | +| **Оператори Switch** | Складні ланцюжки switch/if-else | Важко розширювати | +| **Спекулятивна загальність** | Код «на всякий випадок» | Зайва складність | +| **Мертвий код** | Невикористаний код | Плутанина, тягар супровідності | + +### Кроки аналізу + +1. **Автоматичний аналіз** (якщо скрипти доступні) + ```bash + python scripts/detect-smells.py + ``` + +2. **Ручний перегляд** + - Систематично пройти код + - Зафіксувати кожен запах з розташуванням та серйозністю + - Категоризувати за впливом (Критичний/Високий/Середній/Низький) + +3. **Пріоритезація** + Зосередитися на запахах, які: + - Блокують поточну розробку + - Спричиняють помилки або плутанину + - Впливають на найчастіше змінювані шляхи коду + +### Вивід: Звіт про запахи + +Представити користувачу: +- Список виявлених запахів з розташуванням +- Оцінку серйозності для кожного +- Рекомендований порядок пріоритету +- **Запросити затвердження пріоритетів** + +--- + +## Фаза 4: Створення плану рефакторингу + +### Вибір рефакторингів + +Для кожного запаху обрати відповідний рефакторинг з каталогу. + +Див. [references/refactoring-catalog.md](references/refactoring-catalog.md) для повного списку. + +#### Відповідність запахів рефакторингам + +| Запах коду | Рекомендований рефакторинг | +|------------|---------------------------| +| Long Method | Extract Method, Replace Temp with Query | +| Duplicated Code | Extract Method, Pull Up Method, Form Template Method | +| Large Class | Extract Class, Extract Subclass | +| Feature Envy | Move Method, Move Field | +| Primitive Obsession | Replace Primitive with Object, Replace Type Code with Class | +| Long Parameter List | Introduce Parameter Object, Preserve Whole Object | +| Data Clumps | Extract Class, Introduce Parameter Object | +| Switch Statements | Replace Conditional with Polymorphism | +| Speculative Generality | Collapse Hierarchy, Inline Class, Remove Dead Code | +| Dead Code | Remove Dead Code | + +### Структура плану + +Використовуйте шаблон [templates/refactoring-plan.md](templates/refactoring-plan.md). + +Для кожного рефакторингу: +1. **Ціль**: Який код зміниться +2. **Запах**: Яку проблему вирішує +3. **Рефакторинг**: Яку техніку застосувати +4. **Кроки**: Детальні мікрокроки +5. **Ризики**: Що може піти не так +6. **Відкат**: Як скасувати за потреби + +### Поетапний підхід + +**КРИТИЧНО**: Впроваджуйте рефакторинг поступово, фазами. + +**Фаза A: Швидкі перемоги** (Низький ризик, висока цінність) +- Перейменування змінних для ясності +- Витяг очевидного дубльованого коду +- Видалення мертвого коду + +**Фаза B: Структурні покращення** (Середній ризик) +- Витяг методів з довгих функцій +- Введення обʼєктів параметрів +- Переміщення методів до відповідних класів + +**Фаза C: Архітектурні зміни** (Вищий ризик) +- Заміна умовних конструкцій поліморфізмом +- Витяг класів +- Введення патернів проєктування + +### Точка рішення: Представити план користувачу + +Перед реалізацією: +- Показати повний план рефакторингу +- Пояснити кожну фазу та її ризики +- Отримати явне затвердження для кожної фази +- **Запитати**: «Чи продовжити з Фазою A?» + +--- + +## Фаза 5: Інкрементальна реалізація + +### Золоте правило +> «Зміна → Тест → Зелений? → Коміт → Наступний крок» + +### Ритм реалізації + +Для кожного кроку рефакторингу: + +1. **Попередня перевірка** + - Тести проходять (зелені) + - Код компілюється + +2. **Зробити ОДНУ малу зміну** + - Дотримуватися механіки з каталогу + - Тримати зміни мінімальними + +3. **Верифікація** + - Негайно запустити тести + - Перевірити на помилки компіляції + +4. **Якщо тести проходять (зелені)** + - Закомітити з описовим повідомленням + - Перейти до наступного кроку + +5. **Якщо тести не проходять (червоні)** + - ЗУПИНИТИСЯ негайно + - Скасувати зміну + - Проаналізувати, що пішло не так + - Запитати користувача, якщо незрозуміло + +### Стратегія комітів + +Кожен коміт має бути: +- **Атомарний**: Одна логічна зміна +- **Оборотний**: Легко відкатити +- **Описовий**: Зрозуміле повідомлення коміту + +Приклади повідомлень комітів: +``` +refactor: Extract calculateTotal() from processOrder() +refactor: Rename 'x' to 'customerCount' for clarity +refactor: Remove unused validateOldFormat() method +``` + +### Звіт про прогрес + +Після кожної підфази звітувати користувачу: +- Внесені зміни +- Тести досі проходять? +- Виявлені проблеми +- **Запитати**: «Продовжити з наступною порцією?» + +--- + +## Фаза 6: Перегляд та ітерація + +### Контрольний список після рефакторингу + +- [ ] Усі тести проходять +- [ ] Немає нових попереджень/помилок +- [ ] Код успішно компілюється +- [ ] Поведінка не змінилася (ручна верифікація) +- [ ] Документація оновлена за потреби +- [ ] Історія комітів чиста + +### Порівняння метрик + +Запустити аналіз складності до і після: +```bash +python scripts/analyze-complexity.py +``` + +Представити покращення: +- Зміна кількості рядків коду +- Зміна цикломатичної складності +- Зміна індексу супровідності + +### Перегляд користувачем + +Представити фінальні результати: +- Резюме всіх змін +- Порівняння коду до/після +- Покращення метрик +- Залишковий технічний борг +- **Запитати**: «Чи задоволені ви цими змінами?» + +### Наступні кроки + +Обговорити з користувачем: +- Додаткові запахи для усунення? +- Запланувати подальший рефакторинг? +- Застосувати аналогічні зміни в інших місцях? + +--- + +## Важливі рекомендації + +### Коли ЗУПИНИТИСЯ та запитати + +Завжди паузу та консультацію з користувачем, коли: +- Невпевненість щодо бізнес-логіки +- Зміна може вплинути на зовнішні API +- Покриття тестами недостатнє +- Потрібне значне архітектурне рішення +- Рівень ризику зростає +- Зустрічаєте неочікувану складність + +### Правила безпеки + +1. **Ніколи не рефакторити без тестів** (якщо користувач явно не підтвердив ризик) +2. **Ніколи не робити великих змін** — розбивати на крихітні кроки +3. **Ніколи не пропускати запуск тестів** після кожної зміни +4. **Ніколи не продовжувати, якщо тести не проходять** — виправити або відкатити +5. **Ніколи не припускати** — якщо сумніваєтесь, запитайте + +### Чого НЕ робити + +- Не поєднуйте рефакторинг з додаванням функцій +- Не рефакторте під час аварій на продакшні +- Не рефакторте код, який не розумієте +- Не переускладнюйте — тримайте просто +- Не рефакторте все одразу + +--- + +## Приклад швидкого старту + +### Сценарій: Довгий метод з дублюванням + +**До:** +```javascript +function processOrder(order) { + // 150 рядків коду з: + // - Дубльованою логікою валідації + // - Інлайн-обчисленнями + // - Змішаними відповідальностями +} +``` + +**Кроки рефакторингу:** + +1. **Переконатися, що тести існують** для processOrder() +2. **Витягти** валідацію у validateOrder() +3. **Тест** — має пройти +4. **Витягти** обчислення у calculateOrderTotal() +5. **Тест** — має пройти +6. **Витягти** сповіщення у notifyCustomer() +7. **Тест** — має пройти +8. **Перегляд** — processOrder() тепер оркеструє 3 чіткі функції + +**Після:** +```javascript +function processOrder(order) { + validateOrder(order); + const total = calculateOrderTotal(order); + notifyCustomer(order, total); + return { order, total }; +} +``` + +--- + +## Довідники + +- [Каталог запахів коду](references/code-smells.md) — повний список запахів коду +- [Каталог рефакторингів](references/refactoring-catalog.md) — техніки рефакторингу +- [Шаблон плану рефакторингу](templates/refactoring-plan.md) — шаблон планування + +## Скрипти + +- `scripts/analyze-complexity.py` — аналіз метрик складності коду +- `scripts/detect-smells.py` — автоматичне виявлення запахів + +## Історія версій + +- v1.0.0 (2025-01-15): Початковий випуск з методологією Фаулера, поетапним підходом, точками консультації з користувачем diff --git a/uk/03-skills/refactor/references/code-smells.md b/uk/03-skills/refactor/references/code-smells.md new file mode 100644 index 0000000..3480bbe --- /dev/null +++ b/uk/03-skills/refactor/references/code-smells.md @@ -0,0 +1,669 @@ +# Каталог запахів коду + +Комплексний довідник запахів коду на основі книги Мартіна Фаулера *Refactoring* (2-ге видання). Запахи коду — це симптоми глибших проблем; вони вказують на те, що щось може бути не так з дизайном вашого коду. + +> «Запах коду — це поверхнева ознака, яка зазвичай відповідає глибшій проблемі в системі.» — Мартін Фаулер + +--- + +## Роздуті елементи (Bloaters) + +Запахи коду, що представляють щось, що розрослося занадто великим для ефективної роботи. + +### Long Method (Довгий метод) + +**Ознаки:** +- Метод перевищує 30-50 рядків +- Потрібно прокручувати, щоб побачити весь метод +- Кілька рівнів вкладеності +- Коментарі пояснюють, що роблять секції + +**Чому це погано:** +- Важко зрозуміти +- Складно тестувати ізольовано +- Зміни мають непередбачувані наслідки +- Дубльована логіка ховається всередині + +**Рефакторинги:** +- Extract Method +- Replace Temp with Query +- Introduce Parameter Object +- Replace Method with Method Object +- Decompose Conditional + +**Приклад (до):** +```javascript +function processOrder(order) { + // Валідація замовлення (20 рядків) + if (!order.items) throw new Error('No items'); + if (order.items.length === 0) throw new Error('Empty order'); + // ... ще валідація + + // Обчислення підсумків (30 рядків) + let subtotal = 0; + for (const item of order.items) { + subtotal += item.price * item.quantity; + } + // ... податок, доставка, знижки + + // Надсилання сповіщень (20 рядків) + // ... логіка email +} +``` + +**Приклад (після):** +```javascript +function processOrder(order) { + validateOrder(order); + const totals = calculateOrderTotals(order); + sendOrderNotifications(order, totals); + return { order, totals }; +} +``` + +--- + +### Large Class (Великий клас) + +**Ознаки:** +- Клас має багато полів екземпляра (>7-10) +- Клас має багато методів (>15-20) +- Назва класу розмита (Manager, Handler, Processor) +- Методи не використовують усі поля екземпляра + +**Чому це погано:** +- Порушує принцип єдиної відповідальності +- Важко тестувати +- Зміни поширюються на неповʼязані функції +- Складно повторно використовувати частини + +**Рефакторинги:** +- Extract Class +- Extract Subclass +- Extract Interface + +**Виявлення:** +``` +Рядків коду > 300 +Кількість методів > 15 +Кількість полів > 10 +``` + +--- + +### Primitive Obsession (Одержимість примітивами) + +**Ознаки:** +- Використання примітивів для доменних концепцій (string для email, int для грошей) +- Масиви примітивів замість обʼєктів +- Рядкові константи для кодів типів +- Магічні числа/рядки + +**Чому це погано:** +- Немає валідації на рівні типу +- Логіка розкидана по кодовій базі +- Легко передати неправильні значення +- Відсутні доменні концепції + +**Рефакторинги:** +- Replace Primitive with Object +- Replace Type Code with Class +- Replace Type Code with Subclasses +- Replace Type Code with State/Strategy + +**Приклад (до):** +```javascript +const user = { + email: 'john@example.com', // Просто рядок + phone: '1234567890', // Просто рядок + status: 'active', // Магічний рядок + balance: 10050 // Копійки як ціле число +}; +``` + +**Приклад (після):** +```javascript +const user = { + email: new Email('john@example.com'), + phone: new PhoneNumber('1234567890'), + status: UserStatus.ACTIVE, + balance: Money.cents(10050) +}; +``` + +--- + +### Long Parameter List (Довгий список параметрів) + +**Ознаки:** +- Методи з 4+ параметрами +- Параметри, що завжди зʼявляються разом +- Булеві прапорці, що змінюють поведінку методу +- Часте передавання null/undefined + +**Чому це погано:** +- Важко викликати правильно +- Плутанина з порядком параметрів +- Вказує, що метод робить занадто багато +- Важко додавати нові параметри + +**Рефакторинги:** +- Introduce Parameter Object +- Preserve Whole Object +- Replace Parameter with Method Call +- Remove Flag Argument + +**Приклад (до):** +```javascript +function createUser(firstName, lastName, email, phone, + street, city, state, zip, + isAdmin, isActive, createdBy) { + // ... +} +``` + +**Приклад (після):** +```javascript +function createUser(personalInfo, address, options) { + // personalInfo: { firstName, lastName, email, phone } + // address: { street, city, state, zip } + // options: { isAdmin, isActive, createdBy } +} +``` + +--- + +### Data Clumps (Групи даних) + +**Ознаки:** +- Ті самі 3+ поля зʼявляються разом повторно +- Параметри, що завжди подорожують разом +- Класи з підмножинами полів, що належать один одному + +**Чому це погано:** +- Дубльована логіка обробки +- Відсутня абстракція +- Важче розширювати +- Вказує на прихований клас + +**Рефакторинги:** +- Extract Class +- Introduce Parameter Object +- Preserve Whole Object + +**Приклад:** +```javascript +// Група даних: координати (x, y, z) +function movePoint(x, y, z, dx, dy, dz) { } +function scalePoint(x, y, z, factor) { } +function distanceBetween(x1, y1, z1, x2, y2, z2) { } + +// Витяг класу Point3D +class Point3D { + constructor(x, y, z) { } + move(delta) { } + scale(factor) { } + distanceTo(other) { } +} +``` + +--- + +## Зловживання обʼєктною орієнтацією (OO Abusers) + +Запахи, що вказують на неповне або некоректне використання принципів ООП. + +### Switch Statements (Оператори Switch) + +**Ознаки:** +- Довгі ланцюжки switch/case або if/else +- Той самий switch у кількох місцях +- Switch за кодами типів +- Додавання нових випадків вимагає змін всюди + +**Чому це погано:** +- Порушує принцип відкритості/закритості +- Зміни поширюються на всі місця з switch +- Важко розширювати +- Часто вказує на відсутній поліморфізм + +**Рефакторинги:** +- Replace Conditional with Polymorphism +- Replace Type Code with Subclasses +- Replace Type Code with State/Strategy + +**Приклад (до):** +```javascript +function calculatePay(employee) { + switch (employee.type) { + case 'hourly': + return employee.hours * employee.rate; + case 'salaried': + return employee.salary / 12; + case 'commissioned': + return employee.sales * employee.commission; + } +} +``` + +**Приклад (після):** +```javascript +class HourlyEmployee { + calculatePay() { + return this.hours * this.rate; + } +} + +class SalariedEmployee { + calculatePay() { + return this.salary / 12; + } +} +``` + +--- + +### Temporary Field (Тимчасове поле) + +**Ознаки:** +- Поля екземпляра, що використовуються лише в деяких методах +- Поля, що встановлюються умовно +- Складна ініціалізація для певних випадків + +**Чому це погано:** +- Плутанина — поле існує, але може бути null +- Важко зрозуміти стан обʼєкта +- Вказує на приховану умовну логіку + +**Рефакторинги:** +- Extract Class +- Introduce Null Object +- Replace Temp Field with Local + +--- + +### Refused Bequest (Відхилена спадщина) + +**Ознаки:** +- Підклас не використовує успадковані методи/дані +- Підклас перевизначає, щоб нічого не робити +- Успадкування використовується для повторного використання коду, а не для відношення IS-A + +**Чому це погано:** +- Неправильна абстракція +- Порушує принцип підстановки Лісков +- Оманлива ієрархія + +**Рефакторинги:** +- Push Down Method/Field +- Replace Subclass with Delegate +- Replace Inheritance with Delegation + +--- + +### Alternative Classes with Different Interfaces (Альтернативні класи з різними інтерфейсами) + +**Ознаки:** +- Два класи, що роблять схожі речі +- Різні назви методів для тієї самої концепції +- Можуть використовуватися взаємозамінно + +**Чому це погано:** +- Дубльовані реалізації +- Немає спільного інтерфейсу +- Важко перемикатися між ними + +**Рефакторинги:** +- Rename Method +- Move Method +- Extract Superclass +- Extract Interface + +--- + +## Перешкоди для змін (Change Preventers) + +Запахи, що ускладнюють зміни — зміна однієї речі вимагає зміни багатьох інших. + +### Divergent Change (Дивергентна зміна) + +**Ознаки:** +- Один клас змінюється з кількох різних причин +- Зміни в різних областях запускають редагування того самого класу +- Клас є «God-класом» + +**Чому це погано:** +- Порушує принцип єдиної відповідальності +- Висока частота змін +- Конфлікти злиття + +**Рефакторинги:** +- Extract Class +- Extract Superclass +- Extract Subclass + +**Приклад:** +Клас `User` змінюється через: +- Зміни автентифікації +- Зміни профілю +- Зміни білінгу +- Зміни сповіщень + +→ Витягти: `AuthService`, `ProfileService`, `BillingService`, `NotificationService` + +--- + +### Shotgun Surgery (Хірургія дробовиком) + +**Ознаки:** +- Одна зміна вимагає редагування в багатьох класах +- Мала функція потребує правок у 10+ файлах +- Зміни розкидані, важко знайти всі + +**Чому це погано:** +- Легко пропустити місце +- Високий звʼязок (coupling) +- Зміни схильні до помилок + +**Рефакторинги:** +- Move Method +- Move Field +- Inline Class + +**Виявлення:** +Шукайте: додавання одного поля вимагає змін у >5 файлах. + +--- + +### Parallel Inheritance Hierarchies (Паралельні ієрархії успадкування) + +**Ознаки:** +- Створення підкласу в одній ієрархії вимагає підкласу в іншій +- Префікси класів збігаються (напр., `DatabaseOrder`, `DatabaseProduct`) + +**Чому це погано:** +- Подвійне обслуговування +- Звʼязок між ієрархіями +- Легко забути одну сторону + +**Рефакторинги:** +- Move Method +- Move Field +- Усунути одну ієрархію + +--- + +## Непотрібне (Dispensables) + +Щось непотрібне, що слід видалити. + +### Comments (Надмірні коментарі) + +**Ознаки:** +- Коментарі, що пояснюють, що робить код +- Закоментований код +- TODO/FIXME, що залишаються назавжди +- Вибачення в коментарях + +**Чому це погано:** +- Коментарі брешуть (розсинхронізуються) +- Код має бути самодокументованим +- Мертвий код створює плутанину + +**Рефакторинги:** +- Extract Method (назва пояснює що) +- Rename (ясність без коментарів) +- Видалити закоментований код +- Introduce Assertion + +**Хороші vs погані коментарі:** +```javascript +// ПОГАНО: Пояснює що +// Цикл по користувачах і перевірка чи активні +for (const user of users) { + if (user.status === 'active') { } +} + +// ДОБРЕ: Пояснює чому +// Лише активні — неактивні обробляються задачею очищення +const activeUsers = users.filter(u => u.isActive); +``` + +--- + +### Duplicate Code (Дубльований код) + +**Ознаки:** +- Той самий код у кількох місцях +- Схожий код з малими варіаціями +- Патерни копі-пасту + +**Чому це погано:** +- Виправлення помилок потрібне в кількох місцях +- Ризик неконсистентності +- Роздута кодова база + +**Рефакторинги:** +- Extract Method +- Extract Class +- Pull Up Method (в ієрархіях) +- Form Template Method + +**Правило виявлення:** +Будь-який код, дубльований 3+ разів, слід витягти. + +--- + +### Lazy Class (Ледачий клас) + +**Ознаки:** +- Клас не робить достатньо для виправдання свого існування +- Обгортка без доданої цінності +- Результат надмірної інженерії + +**Чому це погано:** +- Накладні витрати обслуговування +- Непотрібна непрямість +- Складність без користі + +**Рефакторинги:** +- Inline Class +- Collapse Hierarchy + +--- + +### Dead Code (Мертвий код) + +**Ознаки:** +- Недосяжний код +- Невикористані змінні/методи/класи +- Закоментований код +- Код за неможливими умовами + +**Чому це погано:** +- Плутанина +- Тягар обслуговування +- Уповільнює розуміння + +**Рефакторинги:** +- Remove Dead Code +- Safe Delete + +**Виявлення:** +```bash +# Шукати невикористані експорти +# Шукати невикористані функції +# Попередження IDE "unused" +``` + +--- + +### Speculative Generality (Спекулятивна загальність) + +**Ознаки:** +- Абстрактні класи з одним підкласом +- Невикористані параметри «на майбутнє» +- Методи, що лише делегують +- «Фреймворк» для одного випадку + +**Чому це погано:** +- Складність без користі +- YAGNI (You Ain't Gonna Need It — Вам це не знадобиться) +- Важче зрозуміти + +**Рефакторинги:** +- Collapse Hierarchy +- Inline Class +- Remove Parameter +- Rename Method + +--- + +## Звʼязувачі (Couplers) + +Запахи, що представляють надмірний звʼязок між класами. + +### Feature Envy (Заздрість до функцій) + +**Ознаки:** +- Метод використовує більше даних іншого класу, ніж свого +- Багато викликів геттерів іншого обʼєкта +- Дані та поведінка розділені + +**Чому це погано:** +- Неправильне розташування поведінки +- Погана інкапсуляція +- Важко супроводжувати + +**Рефакторинги:** +- Move Method +- Move Field +- Extract Method (потім перемістити) + +**Приклад (до):** +```javascript +class Order { + getDiscountedPrice(customer) { + // Інтенсивно використовує дані customer + if (customer.loyaltyYears > 5) { + return this.price * customer.discountRate; + } + return this.price; + } +} +``` + +**Приклад (після):** +```javascript +class Customer { + getDiscountedPriceFor(price) { + if (this.loyaltyYears > 5) { + return price * this.discountRate; + } + return price; + } +} +``` + +--- + +### Inappropriate Intimacy (Недоречна інтимність) + +**Ознаки:** +- Класи отримують доступ до приватних частин один одного +- Двосторонні посилання +- Підкласи знають занадто багато про батьків + +**Чому це погано:** +- Високий звʼязок +- Зміни каскадуються +- Важко модифікувати один без іншого + +**Рефакторинги:** +- Move Method +- Move Field +- Change Bidirectional to Unidirectional +- Extract Class +- Hide Delegate + +--- + +### Message Chains (Ланцюжки повідомлень) + +**Ознаки:** +- Довгі ланцюжки викликів: `a.getB().getC().getD().getValue()` +- Клієнт залежить від структури навігації +- Код типу «потяг-катастрофа» (train wreck) + +**Чому це погано:** +- Крихкий — будь-яка зміна ламає ланцюжок +- Порушує Закон Деметри +- Звʼязок зі структурою + +**Рефакторинги:** +- Hide Delegate +- Extract Method +- Move Method + +**Приклад:** +```javascript +// Погано: Ланцюжок повідомлень +const managerName = employee.getDepartment().getManager().getName(); + +// Краще: Приховати делегування +const managerName = employee.getManagerName(); +``` + +--- + +### Middle Man (Посередник) + +**Ознаки:** +- Клас, що лише делегує іншому +- Половина методів — делегування +- Немає доданої цінності + +**Чому це погано:** +- Непотрібна непрямість +- Накладні витрати обслуговування +- Заплутана архітектура + +**Рефакторинги:** +- Remove Middle Man +- Inline Method + +--- + +## Посібник серйозності запахів + +| Серйозність | Опис | Дія | +|-------------|------|-----| +| **Критичний** | Блокує розробку, спричиняє помилки | Виправити негайно | +| **Високий** | Значний тягар обслуговування | Виправити в поточному спринті | +| **Середній** | Помітний, але керований | Запланувати на найближче майбутнє | +| **Низький** | Незначна незручність | Виправляти при нагоді | + +--- + +## Контрольний список швидкого виявлення + +Використовуйте цей список при скануванні коду: + +- [ ] Є методи > 30 рядків? +- [ ] Є класи > 300 рядків? +- [ ] Є методи з > 4 параметрами? +- [ ] Є дубльовані блоки коду? +- [ ] Є switch/case за кодами типів? +- [ ] Є невикористаний код? +- [ ] Є методи, що інтенсивно використовують дані іншого класу? +- [ ] Є довгі ланцюжки викликів? +- [ ] Є коментарі, що пояснюють «що», а не «чому»? +- [ ] Є примітиви, що мають бути обʼєктами? + +--- + +## Додаткове читання + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.) +- Kerievsky, J. (2004). *Refactoring to Patterns* +- Feathers, M. (2004). *Working Effectively with Legacy Code* diff --git a/uk/03-skills/refactor/references/refactoring-catalog.md b/uk/03-skills/refactor/references/refactoring-catalog.md new file mode 100644 index 0000000..fb29009 --- /dev/null +++ b/uk/03-skills/refactor/references/refactoring-catalog.md @@ -0,0 +1,1019 @@ +# Каталог рефакторингів + +Курований каталог технік рефакторингу з книги Мартіна Фаулера *Refactoring* (2-ге видання). Кожен рефакторинг включає мотивацію, покрокову механіку та приклади. + +> «Рефакторинг визначається своєю механікою — точною послідовністю кроків, яких ви дотримуєтесь для здійснення зміни.» — Мартін Фаулер + +--- + +## Як використовувати цей каталог + +1. **Виявити запах** за допомогою довідника запахів коду +2. **Знайти відповідний рефакторинг** у цьому каталозі +3. **Дотримуватися механіки** крок за кроком +4. **Тестувати після кожного кроку** для збереження поведінки + +**Золоте правило**: Якщо будь-який крок займає більше 10 хвилин, розбийте його на менші кроки. + +--- + +## Найпоширеніші рефакторинги + +### Extract Method + +**Коли використовувати**: Довгий метод, дубльований код, потрібно назвати концепцію + +**Мотивація**: Перетворити фрагмент коду на метод, назва якого пояснює призначення. + +**Механіка**: +1. Створити новий метод, названий за тим, що він робить (не як) +2. Скопіювати фрагмент коду в новий метод +3. Просканувати локальні змінні, використані у фрагменті +4. Передати локальні змінні як параметри (або оголосити в методі) +5. Обробити повернені значення належним чином +6. Замінити оригінальний фрагмент викликом нового методу +7. Тестувати + +**До**: +```javascript +function printOwing(invoice) { + let outstanding = 0; + + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); + + // Обчислення заборгованості + for (const order of invoice.orders) { + outstanding += order.amount; + } + + // Друк деталей + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +**Після**: +```javascript +function printOwing(invoice) { + printBanner(); + const outstanding = calculateOutstanding(invoice); + printDetails(invoice, outstanding); +} + +function printBanner() { + console.log("***********************"); + console.log("**** Customer Owes ****"); + console.log("***********************"); +} + +function calculateOutstanding(invoice) { + return invoice.orders.reduce((sum, order) => sum + order.amount, 0); +} + +function printDetails(invoice, outstanding) { + console.log(`name: ${invoice.customer}`); + console.log(`amount: ${outstanding}`); +} +``` + +--- + +### Inline Method + +**Коли використовувати**: Тіло методу таке ж зрозуміле, як його назва; надмірне делегування + +**Мотивація**: Видалити непотрібну непрямість, коли метод не додає цінності. + +**Механіка**: +1. Перевірити, що метод не є поліморфним +2. Знайти всі виклики методу +3. Замінити кожен виклик тілом методу +4. Тестувати після кожної заміни +5. Видалити визначення методу + +**До**: +```javascript +function getRating(driver) { + return moreThanFiveLateDeliveries(driver) ? 2 : 1; +} + +function moreThanFiveLateDeliveries(driver) { + return driver.numberOfLateDeliveries > 5; +} +``` + +**Після**: +```javascript +function getRating(driver) { + return driver.numberOfLateDeliveries > 5 ? 2 : 1; +} +``` + +--- + +### Extract Variable + +**Коли використовувати**: Складний вираз, важкий для розуміння + +**Мотивація**: Дати назву частині складного виразу. + +**Механіка**: +1. Переконатися, що вираз не має побічних ефектів +2. Оголосити незмінну змінну +3. Встановити її як результат виразу (або частини) +4. Замінити оригінальний вираз змінною +5. Тестувати + +**До**: +```javascript +return order.quantity * order.itemPrice - + Math.max(0, order.quantity - 500) * order.itemPrice * 0.05 + + Math.min(order.quantity * order.itemPrice * 0.1, 100); +``` + +**Після**: +```javascript +const basePrice = order.quantity * order.itemPrice; +const quantityDiscount = Math.max(0, order.quantity - 500) * order.itemPrice * 0.05; +const shipping = Math.min(basePrice * 0.1, 100); +return basePrice - quantityDiscount + shipping; +``` + +--- + +### Inline Variable + +**Коли використовувати**: Назва змінної не передає більше, ніж вираз + +**Мотивація**: Видалити непотрібну непрямість. + +**Механіка**: +1. Перевірити, що права частина не має побічних ефектів +2. Якщо змінна не незмінна, зробити її такою і тестувати +3. Знайти перше посилання та замінити виразом +4. Тестувати +5. Повторити для всіх посилань +6. Видалити оголошення та присвоєння +7. Тестувати + +--- + +### Rename Variable + +**Коли використовувати**: Назва не чітко передає призначення + +**Мотивація**: Хороші назви критичні для чистого коду. + +**Механіка**: +1. Якщо змінна широко використовується, розглянути інкапсуляцію +2. Знайти всі посилання +3. Змінити кожне посилання +4. Тестувати + +**Поради**: +- Використовуйте назви, що розкривають намір +- Уникайте абревіатур +- Використовуйте доменну термінологію + +```javascript +// Погано +const d = 30; +const x = users.filter(u => u.a); + +// Добре +const daysSinceLastLogin = 30; +const activeUsers = users.filter(user => user.isActive); +``` + +--- + +### Change Function Declaration + +**Коли використовувати**: Назва функції не пояснює призначення, параметри потребують зміни + +**Мотивація**: Хороші назви функцій роблять код самодокументованим. + +**Механіка (проста)**: +1. Видалити непотрібні параметри +2. Змінити назву +3. Додати потрібні параметри +4. Тестувати + +**Механіка (міграція — для складних змін)**: +1. Якщо видаляєте параметр, переконайтеся, що він не використовується +2. Створити нову функцію з бажаним оголошенням +3. Зробити так, щоб стара функція викликала нову +4. Тестувати +5. Змінити виклики на нову функцію +6. Тестувати після кожного +7. Видалити стару функцію + +**До**: +```javascript +function circum(radius) { + return 2 * Math.PI * radius; +} +``` + +**Після**: +```javascript +function circumference(radius) { + return 2 * Math.PI * radius; +} +``` + +--- + +### Encapsulate Variable + +**Коли використовувати**: Прямий доступ до даних з кількох місць + +**Мотивація**: Забезпечити чітку точку доступу для маніпуляції даними. + +**Механіка**: +1. Створити функції getter та setter +2. Знайти всі посилання +3. Замінити читання на getter +4. Замінити записи на setter +5. Тестувати після кожної зміни +6. Обмежити видимість змінної + +**До**: +```javascript +let defaultOwner = { firstName: "Martin", lastName: "Fowler" }; + +// Використовується в багатьох місцях +spaceship.owner = defaultOwner; +``` + +**Після**: +```javascript +let defaultOwnerData = { firstName: "Martin", lastName: "Fowler" }; + +function defaultOwner() { return defaultOwnerData; } +function setDefaultOwner(arg) { defaultOwnerData = arg; } + +spaceship.owner = defaultOwner(); +``` + +--- + +### Introduce Parameter Object + +**Коли використовувати**: Кілька параметрів, що часто зʼявляються разом + +**Мотивація**: Згрупувати дані, що природно належать разом. + +**Механіка**: +1. Створити новий клас/структуру для згрупованих параметрів +2. Тестувати +3. Використати Change Function Declaration для додавання нового обʼєкта +4. Тестувати +5. Для кожного параметра в групі видалити його з функції та використати новий обʼєкт +6. Тестувати після кожного + +**До**: +```javascript +function amountInvoiced(startDate, endDate) { ... } +function amountReceived(startDate, endDate) { ... } +function amountOverdue(startDate, endDate) { ... } +``` + +**Після**: +```javascript +class DateRange { + constructor(start, end) { + this.start = start; + this.end = end; + } +} + +function amountInvoiced(dateRange) { ... } +function amountReceived(dateRange) { ... } +function amountOverdue(dateRange) { ... } +``` + +--- + +### Combine Functions into Class + +**Коли використовувати**: Кілька функцій оперують тими самими даними + +**Мотивація**: Згрупувати функції з даними, над якими вони працюють. + +**Механіка**: +1. Застосувати Encapsulate Record до спільних даних +2. Перемістити кожну функцію в клас +3. Тестувати після кожного переміщення +4. Замінити аргументи даних використанням полів класу + +**До**: +```javascript +function base(reading) { ... } +function taxableCharge(reading) { ... } +function calculateBaseCharge(reading) { ... } +``` + +**Після**: +```javascript +class Reading { + constructor(data) { this._data = data; } + + get base() { ... } + get taxableCharge() { ... } + get calculateBaseCharge() { ... } +} +``` + +--- + +### Split Phase + +**Коли використовувати**: Код працює з двома різними речами + +**Мотивація**: Розділити код на окремі фази з чіткими межами. + +**Механіка**: +1. Створити другу функцію для другої фази +2. Тестувати +3. Ввести проміжну структуру даних між фазами +4. Тестувати +5. Витягти першу фазу в окрему функцію +6. Тестувати + +**До**: +```javascript +function priceOrder(product, quantity, shippingMethod) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + const shippingPerCase = (basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = quantity * shippingPerCase; + return basePrice - discount + shippingCost; +} +``` + +**Після**: +```javascript +function priceOrder(product, quantity, shippingMethod) { + const priceData = calculatePricingData(product, quantity); + return applyShipping(priceData, shippingMethod); +} + +function calculatePricingData(product, quantity) { + const basePrice = product.basePrice * quantity; + const discount = Math.max(quantity - product.discountThreshold, 0) + * product.basePrice * product.discountRate; + return { basePrice, quantity, discount }; +} + +function applyShipping(priceData, shippingMethod) { + const shippingPerCase = (priceData.basePrice > shippingMethod.discountThreshold) + ? shippingMethod.discountedFee : shippingMethod.feePerCase; + const shippingCost = priceData.quantity * shippingPerCase; + return priceData.basePrice - priceData.discount + shippingCost; +} +``` + +--- + +## Переміщення функцій (Moving Features) + +### Move Method + +**Коли використовувати**: Метод використовує більше можливостей іншого класу, ніж свого + +**Мотивація**: Розміщувати функції разом з даними, які вони використовують найбільше. + +**Механіка**: +1. Дослідити всі елементи програми, використані методом у своєму класі +2. Перевірити, чи метод є поліморфним +3. Скопіювати метод у цільовий клас +4. Адаптувати до нового контексту +5. Зробити оригінальний метод делегуючим до цільового +6. Тестувати +7. Розглянути видалення оригінального методу + +--- + +### Move Field + +**Коли використовувати**: Поле використовується більше іншим класом + +**Мотивація**: Тримати дані разом з функціями, що їх використовують. + +**Механіка**: +1. Інкапсулювати поле, якщо ще не зроблено +2. Тестувати +3. Створити поле в цільовому класі +4. Оновити посилання на використання цільового поля +5. Тестувати +6. Видалити оригінальне поле + +--- + +### Move Statements into Function + +**Коли використовувати**: Той самий код завжди зʼявляється разом з викликом функції + +**Мотивація**: Видалити дублювання, перемістивши повторюваний код у функцію. + +**Механіка**: +1. Витягти повторюваний код у функцію, якщо ще не зроблено +2. Перемістити оператори в цю функцію +3. Тестувати +4. Якщо виклики більше не потребують окремих операторів, видалити їх + +--- + +### Move Statements to Callers + +**Коли використовувати**: Загальна поведінка різниться між викликачами + +**Мотивація**: Коли поведінка має відрізнятися, перемістити її з функції. + +**Механіка**: +1. Використати Extract Method на коді для переміщення +2. Використати Inline Method на оригінальній функції +3. Видалити тепер вбудований виклик +4. Перемістити витягнутий код до кожного виклику +5. Тестувати + +--- + +## Організація даних (Organizing Data) + +### Replace Primitive with Object + +**Коли використовувати**: Елемент даних потребує більше поведінки, ніж просте значення + +**Мотивація**: Інкапсулювати дані разом з їхньою поведінкою. + +**Механіка**: +1. Застосувати Encapsulate Variable +2. Створити простий клас значення +3. Змінити setter для створення нового екземпляра +4. Змінити getter для повернення значення +5. Тестувати +6. Додати багатшу поведінку до нового класу + +**До**: +```javascript +class Order { + constructor(data) { + this.priority = data.priority; // рядок: "high", "rush" тощо + } +} + +// Використання +if (order.priority === "high" || order.priority === "rush") { ... } +``` + +**Після**: +```javascript +class Priority { + constructor(value) { + if (!Priority.legalValues().includes(value)) + throw new Error(`Invalid priority: ${value}`); + this._value = value; + } + + static legalValues() { return ['low', 'normal', 'high', 'rush']; } + get value() { return this._value; } + + higherThan(other) { + return Priority.legalValues().indexOf(this._value) > + Priority.legalValues().indexOf(other._value); + } +} + +// Використання +if (order.priority.higherThan(new Priority("normal"))) { ... } +``` + +--- + +### Replace Temp with Query + +**Коли використовувати**: Тимчасова змінна зберігає результат виразу + +**Мотивація**: Зробити код зрозумілішим, витягнувши вираз у функцію. + +**Механіка**: +1. Перевірити, що змінна присвоюється лише один раз +2. Витягти праву частину присвоєння в метод +3. Замінити посилання на тимчасову змінну викликом методу +4. Тестувати +5. Видалити оголошення та присвоєння тимчасової змінної + +**До**: +```javascript +const basePrice = this._quantity * this._itemPrice; +if (basePrice > 1000) { + return basePrice * 0.95; +} else { + return basePrice * 0.98; +} +``` + +**Після**: +```javascript +get basePrice() { + return this._quantity * this._itemPrice; +} + +// В методі +if (this.basePrice > 1000) { + return this.basePrice * 0.95; +} else { + return this.basePrice * 0.98; +} +``` + +--- + +## Спрощення умовної логіки (Simplifying Conditional Logic) + +### Decompose Conditional + +**Коли використовувати**: Складний умовний оператор (if-then-else) + +**Мотивація**: Зробити намір зрозумілим, витягнувши умови та дії. + +**Механіка**: +1. Застосувати Extract Method на умові +2. Застосувати Extract Method на then-гілці +3. Застосувати Extract Method на else-гілці (якщо є) + +**До**: +```javascript +if (!aDate.isBefore(plan.summerStart) && !aDate.isAfter(plan.summerEnd)) { + charge = quantity * plan.summerRate; +} else { + charge = quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +**Після**: +```javascript +if (isSummer(aDate, plan)) { + charge = summerCharge(quantity, plan); +} else { + charge = regularCharge(quantity, plan); +} + +function isSummer(date, plan) { + return !date.isBefore(plan.summerStart) && !date.isAfter(plan.summerEnd); +} + +function summerCharge(quantity, plan) { + return quantity * plan.summerRate; +} + +function regularCharge(quantity, plan) { + return quantity * plan.regularRate + plan.regularServiceCharge; +} +``` + +--- + +### Consolidate Conditional Expression + +**Коли використовувати**: Кілька умов з однаковим результатом + +**Мотивація**: Зробити зрозумілим, що умови є однією перевіркою. + +**Механіка**: +1. Перевірити відсутність побічних ефектів в умовах +2. Обʼєднати умови за допомогою `and` або `or` +3. Розглянути Extract Method на обʼєднаній умові + +**До**: +```javascript +if (employee.seniority < 2) return 0; +if (employee.monthsDisabled > 12) return 0; +if (employee.isPartTime) return 0; +``` + +**Після**: +```javascript +if (isNotEligibleForDisability(employee)) return 0; + +function isNotEligibleForDisability(employee) { + return employee.seniority < 2 || + employee.monthsDisabled > 12 || + employee.isPartTime; +} +``` + +--- + +### Replace Nested Conditional with Guard Clauses + +**Коли використовувати**: Глибоко вкладені умови ускладнюють відстеження потоку + +**Мотивація**: Використовувати захисні вирази (guard clauses) для спеціальних випадків, зберігаючи нормальний потік зрозумілим. + +**Механіка**: +1. Знайти умови спеціальних випадків +2. Замінити їх захисними виразами з раннім поверненням +3. Тестувати після кожної зміни + +**До**: +```javascript +function payAmount(employee) { + let result; + if (employee.isSeparated) { + result = { amount: 0, reasonCode: "SEP" }; + } else { + if (employee.isRetired) { + result = { amount: 0, reasonCode: "RET" }; + } else { + result = calculateNormalPay(employee); + } + } + return result; +} +``` + +**Після**: +```javascript +function payAmount(employee) { + if (employee.isSeparated) return { amount: 0, reasonCode: "SEP" }; + if (employee.isRetired) return { amount: 0, reasonCode: "RET" }; + return calculateNormalPay(employee); +} +``` + +--- + +### Replace Conditional with Polymorphism + +**Коли використовувати**: Switch/case за типом, умовна логіка що варіюється за типом + +**Мотивація**: Дозволити обʼєктам обробляти свою поведінку самостійно. + +**Механіка**: +1. Створити ієрархію класів (якщо не існує) +2. Використати фабричну функцію для створення обʼєктів +3. Перемістити умовну логіку в метод суперкласу +4. Створити метод підкласу для кожного випадку +5. Видалити оригінальну умову + +**До**: +```javascript +function plumage(bird) { + switch (bird.type) { + case 'EuropeanSwallow': + return "average"; + case 'AfricanSwallow': + return (bird.numberOfCoconuts > 2) ? "tired" : "average"; + case 'NorwegianBlueParrot': + return (bird.voltage > 100) ? "scorched" : "beautiful"; + default: + return "unknown"; + } +} +``` + +**Після**: +```javascript +class Bird { + get plumage() { return "unknown"; } +} + +class EuropeanSwallow extends Bird { + get plumage() { return "average"; } +} + +class AfricanSwallow extends Bird { + get plumage() { + return (this.numberOfCoconuts > 2) ? "tired" : "average"; + } +} + +class NorwegianBlueParrot extends Bird { + get plumage() { + return (this.voltage > 100) ? "scorched" : "beautiful"; + } +} + +function createBird(data) { + switch (data.type) { + case 'EuropeanSwallow': return new EuropeanSwallow(data); + case 'AfricanSwallow': return new AfricanSwallow(data); + case 'NorwegianBlueParrot': return new NorwegianBlueParrot(data); + default: return new Bird(data); + } +} +``` + +--- + +### Introduce Special Case (Null Object) + +**Коли використовувати**: Повторні перевірки на null для спеціальних випадків + +**Мотивація**: Повертати спеціальний обʼєкт, що обробляє спеціальний випадок. + +**Механіка**: +1. Створити клас спеціального випадку з очікуваним інтерфейсом +2. Додати перевірку isSpecialCase +3. Ввести фабричний метод +4. Замінити перевірки на null використанням обʼєкта спеціального випадку +5. Тестувати + +**До**: +```javascript +const customer = site.customer; +// ... багато місць з перевіркою +if (customer === "unknown") { + customerName = "occupant"; +} else { + customerName = customer.name; +} +``` + +**Після**: +```javascript +class UnknownCustomer { + get name() { return "occupant"; } + get billingPlan() { return registry.defaultPlan; } +} + +// Фабричний метод +function customer(site) { + return site.customer === "unknown" + ? new UnknownCustomer() + : site.customer; +} + +// Використання — перевірки на null не потрібні +const customerName = customer.name; +``` + +--- + +## Рефакторинг API (Refactoring APIs) + +### Separate Query from Modifier + +**Коли використовувати**: Функція і повертає значення, і має побічні ефекти + +**Мотивація**: Зробити зрозумілим, які операції мають побічні ефекти. + +**Механіка**: +1. Створити нову функцію-запит +2. Скопіювати логіку повернення оригінальної функції +3. Змінити оригінал, щоб повертав void +4. Замінити виклики, що використовують повернене значення +5. Тестувати + +**До**: +```javascript +function alertForMiscreant(people) { + for (const p of people) { + if (p === "Don") { + setOffAlarms(); + return "Don"; + } + if (p === "John") { + setOffAlarms(); + return "John"; + } + } + return ""; +} +``` + +**Після**: +```javascript +function findMiscreant(people) { + for (const p of people) { + if (p === "Don") return "Don"; + if (p === "John") return "John"; + } + return ""; +} + +function alertForMiscreant(people) { + if (findMiscreant(people) !== "") setOffAlarms(); +} +``` + +--- + +### Parameterize Function + +**Коли використовувати**: Кілька функцій роблять схожі речі з різними значеннями + +**Мотивація**: Видалити дублювання додаванням параметра. + +**Механіка**: +1. Обрати одну функцію +2. Додати параметр для варійованого літерала +3. Змінити тіло для використання параметра +4. Тестувати +5. Змінити виклики на параметризовану версію +6. Видалити тепер невикористані функції + +**До**: +```javascript +function tenPercentRaise(person) { + person.salary = person.salary * 1.10; +} + +function fivePercentRaise(person) { + person.salary = person.salary * 1.05; +} +``` + +**Після**: +```javascript +function raise(person, factor) { + person.salary = person.salary * (1 + factor); +} + +// Використання +raise(person, 0.10); +raise(person, 0.05); +``` + +--- + +### Remove Flag Argument + +**Коли використовувати**: Булевий параметр, що змінює поведінку функції + +**Мотивація**: Зробити поведінку явною через окремі функції. + +**Механіка**: +1. Створити явну функцію для кожного значення прапорця +2. Замінити кожен виклик відповідною новою функцією +3. Тестувати після кожної зміни +4. Видалити оригінальну функцію + +**До**: +```javascript +function bookConcert(customer, isPremium) { + if (isPremium) { + // логіка преміум-бронювання + } else { + // логіка звичайного бронювання + } +} + +bookConcert(customer, true); +bookConcert(customer, false); +``` + +**Після**: +```javascript +function bookPremiumConcert(customer) { + // логіка преміум-бронювання +} + +function bookRegularConcert(customer) { + // логіка звичайного бронювання +} + +bookPremiumConcert(customer); +bookRegularConcert(customer); +``` + +--- + +## Робота з успадкуванням (Dealing with Inheritance) + +### Pull Up Method + +**Коли використовувати**: Той самий метод у кількох підкласах + +**Мотивація**: Видалити дублювання в ієрархії класів. + +**Механіка**: +1. Перевірити, що методи ідентичні +2. Перевірити, що сигнатури однакові +3. Створити новий метод у суперкласі +4. Скопіювати тіло з одного підкласу +5. Видалити один метод підкласу, тестувати +6. Видалити інші методи підкласів, тестувати кожен + +--- + +### Push Down Method + +**Коли використовувати**: Поведінка релевантна лише для підмножини підкласів + +**Мотивація**: Розмістити метод там, де він використовується. + +**Механіка**: +1. Скопіювати метод у кожен підклас, що його потребує +2. Видалити метод із суперкласу +3. Тестувати +4. Видалити з підкласів, що його не потребують +5. Тестувати + +--- + +### Replace Subclass with Delegate + +**Коли використовувати**: Успадкування використовується некоректно, потрібна більша гнучкість + +**Мотивація**: Віддавати перевагу композиції над успадкуванням, коли доречно. + +**Механіка**: +1. Створити порожній клас для делегата +2. Додати поле в клас-хост для утримання делегата +3. Створити конструктор для делегата, що викликається з хоста +4. Перемістити функціональність до делегата +5. Тестувати після кожного переміщення +6. Замінити успадкування делегуванням + +--- + +## Extract Class + +**Коли використовувати**: Великий клас з кількома відповідальностями + +**Мотивація**: Розділити клас для збереження єдиної відповідальності. + +**Механіка**: +1. Вирішити, як розділити відповідальності +2. Створити новий клас +3. Перемістити поле з оригіналу до нового класу +4. Тестувати +5. Перемістити методи з оригіналу до нового класу +6. Тестувати після кожного переміщення +7. Переглянути та перейменувати обидва класи +8. Вирішити, як відкрити новий клас + +**До**: +```javascript +class Person { + get name() { return this._name; } + set name(arg) { this._name = arg; } + get officeAreaCode() { return this._officeAreaCode; } + set officeAreaCode(arg) { this._officeAreaCode = arg; } + get officeNumber() { return this._officeNumber; } + set officeNumber(arg) { this._officeNumber = arg; } + + get telephoneNumber() { + return `(${this._officeAreaCode}) ${this._officeNumber}`; + } +} +``` + +**Після**: +```javascript +class Person { + constructor() { + this._telephoneNumber = new TelephoneNumber(); + } + get name() { return this._name; } + set name(arg) { this._name = arg; } + get telephoneNumber() { return this._telephoneNumber.toString(); } + get officeAreaCode() { return this._telephoneNumber.areaCode; } + set officeAreaCode(arg) { this._telephoneNumber.areaCode = arg; } +} + +class TelephoneNumber { + get areaCode() { return this._areaCode; } + set areaCode(arg) { this._areaCode = arg; } + get number() { return this._number; } + set number(arg) { this._number = arg; } + toString() { return `(${this._areaCode}) ${this._number}`; } +} +``` + +--- + +## Короткий довідник: Запах → Рефакторинг + +| Запах коду | Основний рефакторинг | Альтернатива | +|------------|---------------------|--------------| +| Long Method | Extract Method | Replace Temp with Query | +| Duplicate Code | Extract Method | Pull Up Method | +| Large Class | Extract Class | Extract Subclass | +| Long Parameter List | Introduce Parameter Object | Preserve Whole Object | +| Feature Envy | Move Method | Extract Method + Move | +| Data Clumps | Extract Class | Introduce Parameter Object | +| Primitive Obsession | Replace Primitive with Object | Replace Type Code | +| Switch Statements | Replace Conditional with Polymorphism | Replace Type Code | +| Temporary Field | Extract Class | Introduce Null Object | +| Message Chains | Hide Delegate | Extract Method | +| Middle Man | Remove Middle Man | Inline Method | +| Divergent Change | Extract Class | Split Phase | +| Shotgun Surgery | Move Method | Inline Class | +| Dead Code | Remove Dead Code | - | +| Speculative Generality | Collapse Hierarchy | Inline Class | + +--- + +## Додаткове читання + +- Fowler, M. (2018). *Refactoring: Improving the Design of Existing Code* (2nd ed.) +- Онлайн-каталог: https://refactoring.com/catalog/ diff --git a/uk/03-skills/refactor/scripts/analyze-complexity.py b/uk/03-skills/refactor/scripts/analyze-complexity.py new file mode 100644 index 0000000..b8ca92c --- /dev/null +++ b/uk/03-skills/refactor/scripts/analyze-complexity.py @@ -0,0 +1,545 @@ +#!/usr/bin/env python3 +""" +Code Complexity Analyzer + +Analyzes code complexity metrics for Python, JavaScript, and TypeScript files. +Helps measure the impact of refactoring by comparing before/after metrics. + +Usage: + python analyze-complexity.py + python analyze-complexity.py # Compare mode + python analyze-complexity.py --dir # Analyze directory + +Metrics: + - Cyclomatic Complexity: Decision points in code + - Cognitive Complexity: How hard is it to understand + - Maintainability Index: Overall maintainability score (0-100) + - Lines of Code: Total lines + - Function Count: Number of functions/methods + - Average Function Length: Lines per function +""" + +import argparse +import os +import re +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Dict, List, Optional + + +@dataclass +class FunctionMetrics: + """Metrics for a single function.""" + name: str + start_line: int + end_line: int + lines: int + cyclomatic_complexity: int + cognitive_complexity: int + parameter_count: int + + +@dataclass +class FileMetrics: + """Metrics for a file.""" + filename: str + lines_of_code: int + blank_lines: int + comment_lines: int + function_count: int + class_count: int + cyclomatic_complexity: int + cognitive_complexity: int + maintainability_index: float + avg_function_length: float + max_function_length: int + functions: List[FunctionMetrics] + + +class ComplexityAnalyzer: + """Analyze code complexity for multiple languages.""" + + # Patterns for different languages + PATTERNS = { + 'python': { + 'function': r'^\s*def\s+(\w+)\s*\(', + 'class': r'^\s*class\s+(\w+)', + 'decision': [r'\bif\b', r'\belif\b', r'\bfor\b', r'\bwhile\b', + r'\bexcept\b', r'\band\b(?!$)', r'\bor\b(?!$)', + r'\bcase\b', r'\btry\b'], + 'comment': r'^\s*#', + 'multiline_comment_start': r'^\s*["\'][\"\'][\"\']', + 'multiline_comment_end': r'["\'][\"\'][\"\']', + }, + 'javascript': { + 'function': r'(?:function\s+(\w+)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function|\([^)]*\)\s*=>))', + 'class': r'class\s+(\w+)', + 'decision': [r'\bif\b', r'\belse\s+if\b', r'\bfor\b', r'\bwhile\b', + r'\bcatch\b', r'\b\?\b', r'\b&&\b', r'\b\|\|\b', + r'\bcase\b', r'\btry\b'], + 'comment': r'^\s*//', + 'multiline_comment_start': r'/\*', + 'multiline_comment_end': r'\*/', + }, + 'typescript': { + 'function': r'(?:function\s+(\w+)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function|\([^)]*\)\s*=>))', + 'class': r'class\s+(\w+)', + 'decision': [r'\bif\b', r'\belse\s+if\b', r'\bfor\b', r'\bwhile\b', + r'\bcatch\b', r'\b\?\b', r'\b&&\b', r'\b\|\|\b', + r'\bcase\b', r'\btry\b'], + 'comment': r'^\s*//', + 'multiline_comment_start': r'/\*', + 'multiline_comment_end': r'\*/', + } + } + + def __init__(self, filepath: str): + self.filepath = filepath + self.filename = os.path.basename(filepath) + self.language = self._detect_language() + self.patterns = self.PATTERNS.get(self.language, self.PATTERNS['python']) + + with open(filepath, 'r', encoding='utf-8', errors='ignore') as f: + self.code = f.read() + self.lines = self.code.split('\n') + + def _detect_language(self) -> str: + """Detect programming language from file extension.""" + ext = os.path.splitext(self.filepath)[1].lower() + ext_map = { + '.py': 'python', + '.js': 'javascript', + '.jsx': 'javascript', + '.ts': 'typescript', + '.tsx': 'typescript', + } + return ext_map.get(ext, 'python') + + def calculate_cyclomatic_complexity(self, code: Optional[str] = None) -> int: + """ + Calculate cyclomatic complexity using McCabe's method. + CC = E - N + 2P where E=edges, N=nodes, P=connected components + Simplified: Count decision points + 1 + """ + if code is None: + code = self.code + + complexity = 1 # Base complexity + + for pattern in self.patterns['decision']: + matches = re.findall(pattern, code) + complexity += len(matches) + + return complexity + + def calculate_cognitive_complexity(self, code: Optional[str] = None) -> int: + """ + Calculate cognitive complexity. + Measures how hard it is to understand the code. + Accounts for nesting depth and control flow breaks. + """ + if code is None: + code = self.code + + lines = code.split('\n') + cognitive = 0 + nesting_depth = 0 + in_function = False + + for line in lines: + stripped = line.strip() + + # Track function boundaries + if re.search(self.patterns['function'], line): + in_function = True + nesting_depth = 0 + + # Increment for control flow structures + if re.search(r'\b(if|for|while|switch)\b', stripped): + nesting_depth += 1 + cognitive += nesting_depth # Nested structures cost more + + elif re.search(r'\b(elif|else if|else|catch|finally)\b', stripped): + cognitive += nesting_depth # Same level as parent + + # Track nesting through braces/indentation + if self.language in ['javascript', 'typescript']: + nesting_depth += stripped.count('{') - stripped.count('}') + nesting_depth = max(0, nesting_depth) + + # Bonus for breaks in linear flow + if re.search(r'\b(break|continue|return|throw)\b', stripped): + if nesting_depth > 1: + cognitive += 1 + + # Bonus for recursion + # (simplified: just look for function calling itself) + + return cognitive + + def calculate_maintainability_index(self) -> float: + """ + Calculate Maintainability Index (0-100). + Based on Halstead Volume, Cyclomatic Complexity, and Lines of Code. + + MI = max(0, (171 - 5.2*ln(V) - 0.23*CC - 16.2*ln(LOC)) * 100/171) + + Interpretation: + - 85-100: Highly maintainable + - 65-84: Moderately maintainable + - 50-64: Difficult to maintain + - 0-49: Very difficult to maintain + """ + import math + + loc = len([l for l in self.lines if l.strip()]) + cc = self.calculate_cyclomatic_complexity() + + # Simplified Halstead Volume approximation + # Count unique operators and operands + operators = len(re.findall(r'[+\-*/%=<>!&|^~]', self.code)) + operands = len(re.findall(r'\b\w+\b', self.code)) + volume = (operators + operands) * math.log2(max(1, operators + operands)) + + # Calculate MI + mi = 171 - 5.2 * math.log(max(1, volume)) - 0.23 * cc - 16.2 * math.log(max(1, loc)) + mi = max(0, min(100, mi * 100 / 171)) + + return round(mi, 2) + + def count_lines(self) -> Dict[str, int]: + """Count different types of lines.""" + total = len(self.lines) + blank = 0 + comment = 0 + in_multiline_comment = False + + for line in self.lines: + stripped = line.strip() + + # Check for multiline comments + if re.search(self.patterns['multiline_comment_start'], stripped): + in_multiline_comment = True + if re.search(self.patterns['multiline_comment_end'], stripped): + in_multiline_comment = False + comment += 1 + continue + + if in_multiline_comment: + comment += 1 + elif not stripped: + blank += 1 + elif re.match(self.patterns['comment'], stripped): + comment += 1 + + return { + 'total': total, + 'blank': blank, + 'comment': comment, + 'code': total - blank - comment + } + + def find_functions(self) -> List[FunctionMetrics]: + """Find all functions and calculate their individual metrics.""" + functions = [] + current_function = None + function_start = 0 + brace_depth = 0 + + for i, line in enumerate(self.lines): + # Check for function definition + match = re.search(self.patterns['function'], line) + if match: + # Save previous function if exists + if current_function: + func_code = '\n'.join(self.lines[function_start:i]) + functions.append(self._create_function_metrics( + current_function, function_start, i - 1, func_code + )) + + current_function = match.group(1) or match.group(2) if match.lastindex and match.lastindex > 1 else match.group(1) + function_start = i + brace_depth = 0 + + # Track braces for JS/TS + if self.language in ['javascript', 'typescript']: + brace_depth += line.count('{') - line.count('}') + + # Don't forget the last function + if current_function: + func_code = '\n'.join(self.lines[function_start:]) + functions.append(self._create_function_metrics( + current_function, function_start, len(self.lines) - 1, func_code + )) + + return functions + + def _create_function_metrics(self, name: str, start: int, end: int, code: str) -> FunctionMetrics: + """Create metrics for a single function.""" + lines = end - start + 1 + + # Count parameters (simplified) + param_match = re.search(r'\(([^)]*)\)', code.split('\n')[0]) + param_count = 0 + if param_match and param_match.group(1).strip(): + param_count = len([p for p in param_match.group(1).split(',') if p.strip()]) + + return FunctionMetrics( + name=name, + start_line=start + 1, + end_line=end + 1, + lines=lines, + cyclomatic_complexity=self.calculate_cyclomatic_complexity(code), + cognitive_complexity=self.calculate_cognitive_complexity(code), + parameter_count=param_count + ) + + def analyze(self) -> FileMetrics: + """Perform complete analysis of the file.""" + line_counts = self.count_lines() + functions = self.find_functions() + + # Count classes + class_count = len(re.findall(self.patterns['class'], self.code)) + + # Calculate averages + func_lengths = [f.lines for f in functions] if functions else [0] + avg_func_length = sum(func_lengths) / len(func_lengths) + max_func_length = max(func_lengths) + + return FileMetrics( + filename=self.filename, + lines_of_code=line_counts['code'], + blank_lines=line_counts['blank'], + comment_lines=line_counts['comment'], + function_count=len(functions), + class_count=class_count, + cyclomatic_complexity=self.calculate_cyclomatic_complexity(), + cognitive_complexity=self.calculate_cognitive_complexity(), + maintainability_index=self.calculate_maintainability_index(), + avg_function_length=round(avg_func_length, 1), + max_function_length=max_func_length, + functions=functions + ) + + +def print_metrics(metrics: FileMetrics, verbose: bool = False) -> None: + """Print metrics in a readable format.""" + print("=" * 60) + print(f"CODE COMPLEXITY ANALYSIS: {metrics.filename}") + print("=" * 60) + + print("\n📊 OVERVIEW") + print("-" * 40) + print(f" Lines of Code: {metrics.lines_of_code}") + print(f" Blank Lines: {metrics.blank_lines}") + print(f" Comment Lines: {metrics.comment_lines}") + print(f" Functions/Methods: {metrics.function_count}") + print(f" Classes: {metrics.class_count}") + + print("\n📈 COMPLEXITY METRICS") + print("-" * 40) + print(f" Cyclomatic Complexity: {metrics.cyclomatic_complexity}") + print(f" Cognitive Complexity: {metrics.cognitive_complexity}") + print(f" Maintainability Index: {metrics.maintainability_index}") + + # Interpret maintainability + mi = metrics.maintainability_index + if mi >= 85: + mi_label = "Highly maintainable ✅" + elif mi >= 65: + mi_label = "Moderately maintainable 🔶" + elif mi >= 50: + mi_label = "Difficult to maintain ⚠️" + else: + mi_label = "Very difficult to maintain ❌" + print(f" → {mi_label}") + + print("\n📐 FUNCTION METRICS") + print("-" * 40) + print(f" Avg Function Length: {metrics.avg_function_length} lines") + print(f" Max Function Length: {metrics.max_function_length} lines") + + if verbose and metrics.functions: + print("\n📋 FUNCTION DETAILS") + print("-" * 40) + for f in sorted(metrics.functions, key=lambda x: x.cyclomatic_complexity, reverse=True): + flag = " ⚠️" if f.cyclomatic_complexity > 10 or f.lines > 50 else "" + print(f" {f.name}() [lines {f.start_line}-{f.end_line}]{flag}") + print(f" - Lines: {f.lines}, CC: {f.cyclomatic_complexity}, " + f"Cognitive: {f.cognitive_complexity}, Params: {f.parameter_count}") + + print("\n" + "=" * 60) + + +def print_comparison(before: FileMetrics, after: FileMetrics) -> None: + """Print comparison between two analyses.""" + print("=" * 70) + print("CODE COMPLEXITY COMPARISON") + print("=" * 70) + + print(f"\n{'Metric':<30} {'Before':<15} {'After':<15} {'Change':<10}") + print("-" * 70) + + def fmt_change(before_val, after_val, lower_is_better=True): + diff = after_val - before_val + if lower_is_better: + symbol = "✅" if diff < 0 else ("⚠️" if diff > 0 else "➖") + else: + symbol = "✅" if diff > 0 else ("⚠️" if diff < 0 else "➖") + return f"{diff:+.1f} {symbol}" if isinstance(diff, float) else f"{diff:+d} {symbol}" + + metrics = [ + ("Lines of Code", before.lines_of_code, after.lines_of_code, True), + ("Function Count", before.function_count, after.function_count, False), + ("Class Count", before.class_count, after.class_count, False), + ("Cyclomatic Complexity", before.cyclomatic_complexity, after.cyclomatic_complexity, True), + ("Cognitive Complexity", before.cognitive_complexity, after.cognitive_complexity, True), + ("Maintainability Index", before.maintainability_index, after.maintainability_index, False), + ("Avg Function Length", before.avg_function_length, after.avg_function_length, True), + ("Max Function Length", before.max_function_length, after.max_function_length, True), + ] + + for name, b_val, a_val, lower_better in metrics: + change = fmt_change(b_val, a_val, lower_better) + print(f"{name:<30} {b_val:<15} {a_val:<15} {change:<10}") + + print("\n" + "=" * 70) + + # Overall assessment + print("\n🎯 ASSESSMENT") + print("-" * 40) + + improvements = 0 + regressions = 0 + + if after.maintainability_index > before.maintainability_index: + print(" ✅ Maintainability improved") + improvements += 1 + elif after.maintainability_index < before.maintainability_index: + print(" ⚠️ Maintainability decreased") + regressions += 1 + + if after.cyclomatic_complexity < before.cyclomatic_complexity: + print(" ✅ Complexity reduced") + improvements += 1 + elif after.cyclomatic_complexity > before.cyclomatic_complexity: + print(" ⚠️ Complexity increased") + regressions += 1 + + if after.avg_function_length < before.avg_function_length: + print(" ✅ Functions are smaller on average") + improvements += 1 + elif after.avg_function_length > before.avg_function_length: + print(" ⚠️ Functions grew larger on average") + regressions += 1 + + print(f"\n Summary: {improvements} improvements, {regressions} regressions") + print("=" * 70) + + +def analyze_directory(directory: str, verbose: bool = False) -> None: + """Analyze all supported files in a directory.""" + supported_extensions = ['.py', '.js', '.jsx', '.ts', '.tsx'] + files = [] + + for root, _, filenames in os.walk(directory): + for filename in filenames: + if any(filename.endswith(ext) for ext in supported_extensions): + files.append(os.path.join(root, filename)) + + if not files: + print(f"No supported files found in {directory}") + return + + print(f"Analyzing {len(files)} files in {directory}...\n") + + total_loc = 0 + total_cc = 0 + total_functions = 0 + all_metrics = [] + + for filepath in sorted(files): + try: + analyzer = ComplexityAnalyzer(filepath) + metrics = analyzer.analyze() + all_metrics.append(metrics) + + total_loc += metrics.lines_of_code + total_cc += metrics.cyclomatic_complexity + total_functions += metrics.function_count + + if verbose: + print_metrics(metrics, verbose=True) + else: + flag = " ⚠️" if metrics.maintainability_index < 65 else "" + print(f" {metrics.filename}: LOC={metrics.lines_of_code}, " + f"CC={metrics.cyclomatic_complexity}, MI={metrics.maintainability_index}{flag}") + except Exception as e: + print(f" Error analyzing {filepath}: {e}") + + print("\n" + "=" * 60) + print("SUMMARY") + print("=" * 60) + print(f" Files analyzed: {len(all_metrics)}") + print(f" Total lines of code: {total_loc}") + print(f" Total complexity: {total_cc}") + print(f" Total functions: {total_functions}") + + if all_metrics: + avg_mi = sum(m.maintainability_index for m in all_metrics) / len(all_metrics) + print(f" Avg maintainability: {avg_mi:.1f}") + + +def main(): + parser = argparse.ArgumentParser( + description='Analyze code complexity metrics', + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + %(prog)s myfile.py Analyze single file + %(prog)s before.py after.py Compare two versions + %(prog)s --dir src/ Analyze directory + %(prog)s -v myfile.py Verbose output with function details + """ + ) + parser.add_argument('files', nargs='*', help='File(s) to analyze') + parser.add_argument('--dir', '-d', help='Directory to analyze') + parser.add_argument('--verbose', '-v', action='store_true', help='Show detailed function metrics') + parser.add_argument('--json', '-j', action='store_true', help='Output as JSON') + + args = parser.parse_args() + + if args.dir: + analyze_directory(args.dir, args.verbose) + elif len(args.files) == 1: + analyzer = ComplexityAnalyzer(args.files[0]) + metrics = analyzer.analyze() + + if args.json: + import json + print(json.dumps({ + 'filename': metrics.filename, + 'lines_of_code': metrics.lines_of_code, + 'cyclomatic_complexity': metrics.cyclomatic_complexity, + 'cognitive_complexity': metrics.cognitive_complexity, + 'maintainability_index': metrics.maintainability_index, + 'function_count': metrics.function_count, + 'avg_function_length': metrics.avg_function_length, + }, indent=2)) + else: + print_metrics(metrics, args.verbose) + elif len(args.files) == 2: + before_analyzer = ComplexityAnalyzer(args.files[0]) + after_analyzer = ComplexityAnalyzer(args.files[1]) + before_metrics = before_analyzer.analyze() + after_metrics = after_analyzer.analyze() + print_comparison(before_metrics, after_metrics) + else: + parser.print_help() + sys.exit(1) + + +if __name__ == '__main__': + main() diff --git a/uk/03-skills/refactor/scripts/detect-smells.py b/uk/03-skills/refactor/scripts/detect-smells.py new file mode 100644 index 0000000..7ecd628 --- /dev/null +++ b/uk/03-skills/refactor/scripts/detect-smells.py @@ -0,0 +1,711 @@ +#!/usr/bin/env python3 +""" +Code Smell Detector + +Detects common code smells in Python, JavaScript, and TypeScript files. +Based on Martin Fowler's catalog of code smells. + +Usage: + python detect-smells.py + python detect-smells.py --dir + python detect-smells.py -v # Verbose with code snippets + +Detects: + - Long Method (>30 lines) + - Long Parameter List (>4 params) + - Duplicate Code (similar code blocks) + - Large Class (>300 lines, >10 methods) + - Dead Code (unused variables/functions) + - Complex Conditionals (deep nesting, long chains) + - Magic Numbers/Strings + - Feature Envy (methods using other class data heavily) + - Comments explaining what (not why) +""" + +import argparse +import os +import re +import sys +from dataclasses import dataclass, field +from enum import Enum +from typing import Dict, List, Optional, Set, Tuple +from collections import defaultdict + + +class SmellSeverity(Enum): + """Severity levels for code smells.""" + LOW = "Low" + MEDIUM = "Medium" + HIGH = "High" + CRITICAL = "Critical" + + +class SmellType(Enum): + """Types of code smells.""" + LONG_METHOD = "Long Method" + LONG_PARAMETER_LIST = "Long Parameter List" + DUPLICATE_CODE = "Duplicate Code" + LARGE_CLASS = "Large Class" + DEAD_CODE = "Dead Code" + COMPLEX_CONDITIONAL = "Complex Conditional" + MAGIC_NUMBER = "Magic Number/String" + FEATURE_ENVY = "Feature Envy" + EXCESSIVE_COMMENTS = "Excessive Comments" + DEEPLY_NESTED = "Deeply Nested Code" + PRIMITIVE_OBSESSION = "Primitive Obsession" + DATA_CLUMPS = "Data Clumps" + SWITCH_STATEMENT = "Switch Statement" + MESSAGE_CHAIN = "Message Chain" + + +@dataclass +class CodeSmell: + """Represents a detected code smell.""" + smell_type: SmellType + severity: SmellSeverity + location: str + line_start: int + line_end: int + description: str + suggestion: str + code_snippet: str = "" + + +@dataclass +class SmellReport: + """Report of all smells found in a file.""" + filename: str + smells: List[CodeSmell] = field(default_factory=list) + + @property + def critical_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.CRITICAL) + + @property + def high_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.HIGH) + + @property + def medium_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.MEDIUM) + + @property + def low_count(self) -> int: + return sum(1 for s in self.smells if s.severity == SmellSeverity.LOW) + + +class SmellDetector: + """Detect code smells in source files.""" + + # Thresholds (configurable) + THRESHOLDS = { + 'long_method_lines': 30, + 'very_long_method_lines': 50, + 'max_parameters': 4, + 'large_class_lines': 300, + 'large_class_methods': 10, + 'max_nesting_depth': 4, + 'long_chain_length': 3, + 'duplicate_min_lines': 5, + } + + def __init__(self, filepath: str): + self.filepath = filepath + self.filename = os.path.basename(filepath) + self.language = self._detect_language() + + with open(filepath, 'r', encoding='utf-8', errors='ignore') as f: + self.code = f.read() + self.lines = self.code.split('\n') + self.smells: List[CodeSmell] = [] + + def _detect_language(self) -> str: + """Detect programming language from file extension.""" + ext = os.path.splitext(self.filepath)[1].lower() + ext_map = { + '.py': 'python', + '.js': 'javascript', + '.jsx': 'javascript', + '.ts': 'typescript', + '.tsx': 'typescript', + } + return ext_map.get(ext, 'python') + + def detect_all(self) -> SmellReport: + """Run all smell detectors.""" + self._detect_long_methods() + self._detect_long_parameter_lists() + self._detect_large_class() + self._detect_complex_conditionals() + self._detect_magic_numbers() + self._detect_excessive_comments() + self._detect_deeply_nested() + self._detect_switch_statements() + self._detect_message_chains() + self._detect_duplicate_code() + self._detect_dead_code() + + return SmellReport(filename=self.filename, smells=self.smells) + + def _get_snippet(self, start: int, end: int, context: int = 2) -> str: + """Get code snippet with context.""" + actual_start = max(0, start - context) + actual_end = min(len(self.lines), end + context) + snippet_lines = [] + for i in range(actual_start, actual_end): + prefix = "→ " if start <= i < end else " " + snippet_lines.append(f"{i+1:4d} {prefix}{self.lines[i]}") + return '\n'.join(snippet_lines) + + def _detect_long_methods(self) -> None: + """Detect methods that are too long.""" + if self.language == 'python': + pattern = r'^\s*def\s+(\w+)\s*\([^)]*\):' + else: + pattern = r'(?:function\s+(\w+)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function|\([^)]*\)\s*=>))' + + current_method = None + method_start = 0 + brace_depth = 0 + indent_level = 0 + + for i, line in enumerate(self.lines): + match = re.search(pattern, line) + if match: + # Check previous method if exists + if current_method: + method_lines = i - method_start + self._check_method_length(current_method, method_start, i - 1, method_lines) + + current_method = match.group(1) or (match.group(2) if match.lastindex and match.lastindex > 1 else None) + method_start = i + indent_level = len(line) - len(line.lstrip()) + + # Track end of Python functions by indentation + if self.language == 'python' and current_method: + if line.strip() and not line.strip().startswith('#'): + current_indent = len(line) - len(line.lstrip()) + if current_indent <= indent_level and i > method_start: + method_lines = i - method_start + self._check_method_length(current_method, method_start, i - 1, method_lines) + current_method = None + + # Check last method + if current_method: + method_lines = len(self.lines) - method_start + self._check_method_length(current_method, method_start, len(self.lines) - 1, method_lines) + + def _check_method_length(self, name: str, start: int, end: int, lines: int) -> None: + """Check if method is too long and add smell if so.""" + if lines > self.THRESHOLDS['very_long_method_lines']: + severity = SmellSeverity.HIGH + desc = f"Method '{name}' is {lines} lines (threshold: {self.THRESHOLDS['long_method_lines']})" + elif lines > self.THRESHOLDS['long_method_lines']: + severity = SmellSeverity.MEDIUM + desc = f"Method '{name}' is {lines} lines (threshold: {self.THRESHOLDS['long_method_lines']})" + else: + return + + self.smells.append(CodeSmell( + smell_type=SmellType.LONG_METHOD, + severity=severity, + location=f"{self.filename}:{start+1}-{end+1}", + line_start=start + 1, + line_end=end + 1, + description=desc, + suggestion="Apply Extract Method to break down into smaller functions", + code_snippet=self._get_snippet(start, min(start + 5, end), 0) + )) + + def _detect_long_parameter_lists(self) -> None: + """Detect functions with too many parameters.""" + if self.language == 'python': + pattern = r'def\s+(\w+)\s*\(([^)]*)\)' + else: + pattern = r'(?:function\s+(\w+)\s*\(([^)]*)\)|(\w+)\s*[=:]\s*(?:async\s+)?(?:function\s*)?\(([^)]*)\))' + + for i, line in enumerate(self.lines): + match = re.search(pattern, line) + if match: + # Safely extract groups + groups = match.groups() + func_name = groups[0] or (groups[2] if len(groups) > 2 else None) + params_str = groups[1] if len(groups) > 1 else "" + if not params_str and len(groups) > 3: + params_str = groups[3] or "" + + # Count parameters + if params_str.strip(): + params = [p.strip() for p in params_str.split(',') if p.strip()] + # Filter out 'self', 'cls' for Python + if self.language == 'python': + params = [p for p in params if p not in ('self', 'cls')] + param_count = len(params) + + if param_count > self.THRESHOLDS['max_parameters']: + severity = SmellSeverity.HIGH if param_count > 6 else SmellSeverity.MEDIUM + self.smells.append(CodeSmell( + smell_type=SmellType.LONG_PARAMETER_LIST, + severity=severity, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Function '{func_name}' has {param_count} parameters (max: {self.THRESHOLDS['max_parameters']})", + suggestion="Consider Introduce Parameter Object or Preserve Whole Object", + code_snippet=self._get_snippet(i, i + 1, 1) + )) + + def _detect_large_class(self) -> None: + """Detect classes that are too large.""" + if self.language == 'python': + class_pattern = r'^\s*class\s+(\w+)' + method_pattern = r'^\s+def\s+\w+' + else: + class_pattern = r'class\s+(\w+)' + method_pattern = r'(?:^\s+\w+\s*\([^)]*\)\s*\{|^\s+(?:async\s+)?\w+\s*=)' + + current_class = None + class_start = 0 + method_count = 0 + class_indent = 0 + + for i, line in enumerate(self.lines): + class_match = re.search(class_pattern, line) + if class_match: + # Check previous class + if current_class: + self._check_class_size(current_class, class_start, i - 1, method_count) + + current_class = class_match.group(1) + class_start = i + method_count = 0 + class_indent = len(line) - len(line.lstrip()) + + # Count methods in current class + if current_class and re.search(method_pattern, line): + method_count += 1 + + # Check last class + if current_class: + self._check_class_size(current_class, class_start, len(self.lines) - 1, method_count) + + def _check_class_size(self, name: str, start: int, end: int, methods: int) -> None: + """Check if class is too large.""" + lines = end - start + 1 + + issues = [] + severity = SmellSeverity.MEDIUM + + if lines > self.THRESHOLDS['large_class_lines']: + issues.append(f"{lines} lines (max: {self.THRESHOLDS['large_class_lines']})") + severity = SmellSeverity.HIGH + + if methods > self.THRESHOLDS['large_class_methods']: + issues.append(f"{methods} methods (max: {self.THRESHOLDS['large_class_methods']})") + if severity != SmellSeverity.HIGH: + severity = SmellSeverity.MEDIUM + + if issues: + self.smells.append(CodeSmell( + smell_type=SmellType.LARGE_CLASS, + severity=severity, + location=f"{self.filename}:{start+1}-{end+1}", + line_start=start + 1, + line_end=end + 1, + description=f"Class '{name}' is too large: {', '.join(issues)}", + suggestion="Apply Extract Class to split responsibilities", + code_snippet=self._get_snippet(start, start + 3, 0) + )) + + def _detect_complex_conditionals(self) -> None: + """Detect complex conditional expressions.""" + for i, line in enumerate(self.lines): + # Count logical operators in line + and_or_count = len(re.findall(r'\b(and|or|&&|\|\|)\b', line)) + + if and_or_count >= 3: + self.smells.append(CodeSmell( + smell_type=SmellType.COMPLEX_CONDITIONAL, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Complex conditional with {and_or_count} logical operators", + suggestion="Apply Decompose Conditional or Consolidate Conditional Expression", + code_snippet=self._get_snippet(i, i + 1, 1) + )) + + def _detect_magic_numbers(self) -> None: + """Detect magic numbers and strings.""" + # Skip common acceptable values + acceptable = {'0', '1', '-1', '2', '100', 'true', 'false', 'null', 'None', '""', "''"} + + for i, line in enumerate(self.lines): + # Skip comments and imports + stripped = line.strip() + if stripped.startswith('#') or stripped.startswith('//') or \ + stripped.startswith('import') or stripped.startswith('from'): + continue + + # Find numeric literals (excluding in variable names) + numbers = re.findall(r'(? 2: + # Check if it's likely a magic number (in calculation or comparison) + if re.search(rf'[<>=+\-*/]\s*{re.escape(num)}|{re.escape(num)}\s*[<>=+\-*/]', line): + self.smells.append(CodeSmell( + smell_type=SmellType.MAGIC_NUMBER, + severity=SmellSeverity.LOW, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Magic number '{num}' - consider using a named constant", + suggestion="Replace magic number with named constant", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + break # One magic number per line is enough + + def _detect_excessive_comments(self) -> None: + """Detect comments that explain 'what' instead of 'why'.""" + what_patterns = [ + r'#\s*(set|get|return|loop|iterate|check|if|increment|decrement)', + r'//\s*(set|get|return|loop|iterate|check|if|increment|decrement)', + ] + + for i, line in enumerate(self.lines): + for pattern in what_patterns: + if re.search(pattern, line, re.IGNORECASE): + self.smells.append(CodeSmell( + smell_type=SmellType.EXCESSIVE_COMMENTS, + severity=SmellSeverity.LOW, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description="Comment explains 'what' not 'why' - consider renaming or removing", + suggestion="Use Extract Method with descriptive name instead of comment", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + break + + def _detect_deeply_nested(self) -> None: + """Detect deeply nested code blocks.""" + max_depth = 0 + current_depth = 0 + depth_start = 0 + + for i, line in enumerate(self.lines): + if self.language == 'python': + # Count by indentation + if line.strip(): + indent = len(line) - len(line.lstrip()) + depth = indent // 4 # Assume 4-space indent + if depth > current_depth: + if depth > max_depth: + max_depth = depth + if depth >= self.THRESHOLDS['max_nesting_depth']: + depth_start = i + current_depth = depth + else: + # Count braces + current_depth += line.count('{') - line.count('}') + if current_depth > max_depth: + max_depth = current_depth + if current_depth >= self.THRESHOLDS['max_nesting_depth']: + depth_start = i + + if max_depth >= self.THRESHOLDS['max_nesting_depth']: + self.smells.append(CodeSmell( + smell_type=SmellType.DEEPLY_NESTED, + severity=SmellSeverity.HIGH if max_depth > 5 else SmellSeverity.MEDIUM, + location=f"{self.filename}:{depth_start+1}", + line_start=depth_start + 1, + line_end=depth_start + 1, + description=f"Code nested {max_depth} levels deep (max: {self.THRESHOLDS['max_nesting_depth']})", + suggestion="Apply Replace Nested Conditional with Guard Clauses or Extract Method", + code_snippet=self._get_snippet(depth_start, depth_start + 5, 0) + )) + + def _detect_switch_statements(self) -> None: + """Detect switch statements that might need polymorphism.""" + if self.language == 'python': + # Python 3.10+ match statements or if/elif chains + pattern = r'^\s*(if|elif).*==.*:' + consecutive_conditions = 0 + chain_start = 0 + + for i, line in enumerate(self.lines): + if re.search(pattern, line): + if consecutive_conditions == 0: + chain_start = i + consecutive_conditions += 1 + else: + if consecutive_conditions >= 4: + self._add_switch_smell(chain_start, i - 1, consecutive_conditions) + consecutive_conditions = 0 + else: + # JavaScript/TypeScript switch + pattern = r'\bswitch\s*\(' + for i, line in enumerate(self.lines): + if re.search(pattern, line): + # Count cases + case_count = 0 + for j in range(i, min(i + 50, len(self.lines))): + case_count += len(re.findall(r'\bcase\b', self.lines[j])) + if case_count >= 4: + self._add_switch_smell(i, i + 1, case_count) + + def _add_switch_smell(self, start: int, end: int, cases: int) -> None: + """Add a switch statement smell.""" + self.smells.append(CodeSmell( + smell_type=SmellType.SWITCH_STATEMENT, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{start+1}", + line_start=start + 1, + line_end=end + 1, + description=f"Switch/case statement with {cases} cases - consider polymorphism", + suggestion="Apply Replace Conditional with Polymorphism", + code_snippet=self._get_snippet(start, start + 5, 0) + )) + + def _detect_message_chains(self) -> None: + """Detect long method chains (train wrecks).""" + chain_pattern = r'(\w+(?:\.\w+\([^)]*\)){3,})' + + for i, line in enumerate(self.lines): + matches = re.findall(chain_pattern, line) + for match in matches: + chain_length = match.count('.') + if chain_length >= self.THRESHOLDS['long_chain_length']: + self.smells.append(CodeSmell( + smell_type=SmellType.MESSAGE_CHAIN, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Message chain with {chain_length} calls - violates Law of Demeter", + suggestion="Apply Hide Delegate to reduce coupling", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + + def _detect_duplicate_code(self) -> None: + """Detect potential duplicate code blocks (simplified).""" + # Create line hashes for comparison + line_hashes: Dict[str, List[int]] = defaultdict(list) + + for i, line in enumerate(self.lines): + normalized = re.sub(r'\s+', ' ', line.strip()) + if len(normalized) > 20: # Only significant lines + line_hashes[normalized].append(i) + + # Find duplicates + for normalized, positions in line_hashes.items(): + if len(positions) >= 3: # At least 3 occurrences + self.smells.append(CodeSmell( + smell_type=SmellType.DUPLICATE_CODE, + severity=SmellSeverity.MEDIUM, + location=f"{self.filename}:{positions[0]+1}", + line_start=positions[0] + 1, + line_end=positions[0] + 1, + description=f"Potential duplicate code found {len(positions)} times", + suggestion="Apply Extract Method to eliminate duplication", + code_snippet=self._get_snippet(positions[0], positions[0] + 1, 0) + )) + + def _detect_dead_code(self) -> None: + """Detect potentially dead code (simplified).""" + # Look for common dead code patterns + patterns = [ + (r'^\s*#.*TODO.*delete', "TODO to delete"), + (r'^\s*#.*FIXME.*remove', "FIXME to remove"), + (r'^\s*//.*TODO.*delete', "TODO to delete"), + (r'^\s*//.*FIXME.*remove', "FIXME to remove"), + (r'^\s*if\s+False:', "Code behind 'if False'"), + (r'^\s*if\s*\(\s*false\s*\)', "Code behind 'if (false)'"), + ] + + for i, line in enumerate(self.lines): + for pattern, desc in patterns: + if re.search(pattern, line, re.IGNORECASE): + self.smells.append(CodeSmell( + smell_type=SmellType.DEAD_CODE, + severity=SmellSeverity.LOW, + location=f"{self.filename}:{i+1}", + line_start=i + 1, + line_end=i + 1, + description=f"Potential dead code: {desc}", + suggestion="Remove dead code", + code_snippet=self._get_snippet(i, i + 1, 0) + )) + + +def print_report(report: SmellReport, verbose: bool = False) -> None: + """Print smell report in readable format.""" + print("=" * 70) + print(f"CODE SMELL DETECTION REPORT: {report.filename}") + print("=" * 70) + + print(f"\n📊 SUMMARY") + print("-" * 40) + print(f" Total smells found: {len(report.smells)}") + print(f" Critical: {report.critical_count}") + print(f" High: {report.high_count}") + print(f" Medium: {report.medium_count}") + print(f" Low: {report.low_count}") + + if not report.smells: + print("\n✅ No code smells detected!") + print("=" * 70) + return + + # Group by type + by_type: Dict[SmellType, List[CodeSmell]] = defaultdict(list) + for smell in report.smells: + by_type[smell.smell_type].append(smell) + + print(f"\n📋 FINDINGS BY TYPE") + print("-" * 40) + + for smell_type, smells in sorted(by_type.items(), key=lambda x: -len(x[1])): + print(f"\n### {smell_type.value} ({len(smells)} found)") + + for smell in sorted(smells, key=lambda x: x.severity.value): + severity_icon = { + SmellSeverity.CRITICAL: "🔴", + SmellSeverity.HIGH: "🟠", + SmellSeverity.MEDIUM: "🟡", + SmellSeverity.LOW: "🟢", + }[smell.severity] + + print(f"\n {severity_icon} [{smell.severity.value}] {smell.location}") + print(f" {smell.description}") + print(f" 💡 {smell.suggestion}") + + if verbose and smell.code_snippet: + print(f"\n Code:") + for snippet_line in smell.code_snippet.split('\n'): + print(f" {snippet_line}") + + print("\n" + "=" * 70) + print("💡 RECOMMENDED ACTIONS") + print("-" * 40) + + if report.critical_count > 0: + print(" 1. Address CRITICAL issues immediately") + if report.high_count > 0: + print(" 2. Plan to fix HIGH severity issues this sprint") + if report.medium_count > 0: + print(" 3. Schedule MEDIUM issues for upcoming work") + if report.low_count > 0: + print(" 4. Fix LOW issues opportunistically") + + print("\n" + "=" * 70) + + +def analyze_directory(directory: str, verbose: bool = False) -> None: + """Analyze all supported files in a directory.""" + supported_extensions = ['.py', '.js', '.jsx', '.ts', '.tsx'] + files = [] + + for root, _, filenames in os.walk(directory): + for filename in filenames: + if any(filename.endswith(ext) for ext in supported_extensions): + files.append(os.path.join(root, filename)) + + if not files: + print(f"No supported files found in {directory}") + return + + print(f"Scanning {len(files)} files in {directory}...\n") + + total_smells = 0 + total_critical = 0 + total_high = 0 + files_with_smells = 0 + + for filepath in sorted(files): + try: + detector = SmellDetector(filepath) + report = detector.detect_all() + + if report.smells: + files_with_smells += 1 + total_smells += len(report.smells) + total_critical += report.critical_count + total_high += report.high_count + + flag = " 🔴" if report.critical_count else (" 🟠" if report.high_count else " 🟡") + print(f" {report.filename}: {len(report.smells)} smells{flag}") + + if verbose: + for smell in report.smells: + print(f" - [{smell.severity.value}] {smell.smell_type.value}: line {smell.line_start}") + else: + print(f" {report.filename}: ✅ Clean") + + except Exception as e: + print(f" Error analyzing {filepath}: {e}") + + print("\n" + "=" * 60) + print("SUMMARY") + print("=" * 60) + print(f" Files analyzed: {len(files)}") + print(f" Files with smells: {files_with_smells}") + print(f" Total smells found: {total_smells}") + print(f" Critical issues: {total_critical}") + print(f" High severity issues: {total_high}") + + +def main(): + parser = argparse.ArgumentParser( + description='Detect code smells in source files', + formatter_class=argparse.RawDescriptionHelpFormatter, + epilog=""" +Examples: + %(prog)s myfile.py Analyze single file + %(prog)s --dir src/ Analyze directory + %(prog)s -v myfile.py Verbose with code snippets + """ + ) + parser.add_argument('file', nargs='?', help='File to analyze') + parser.add_argument('--dir', '-d', help='Directory to analyze') + parser.add_argument('--verbose', '-v', action='store_true', help='Show code snippets') + parser.add_argument('--json', '-j', action='store_true', help='Output as JSON') + + args = parser.parse_args() + + if args.dir: + analyze_directory(args.dir, args.verbose) + elif args.file: + detector = SmellDetector(args.file) + report = detector.detect_all() + + if args.json: + import json + smells_data = [{ + 'type': s.smell_type.value, + 'severity': s.severity.value, + 'location': s.location, + 'line_start': s.line_start, + 'line_end': s.line_end, + 'description': s.description, + 'suggestion': s.suggestion, + } for s in report.smells] + print(json.dumps({ + 'filename': report.filename, + 'total_smells': len(report.smells), + 'critical': report.critical_count, + 'high': report.high_count, + 'medium': report.medium_count, + 'low': report.low_count, + 'smells': smells_data + }, indent=2)) + else: + print_report(report, args.verbose) + else: + parser.print_help() + sys.exit(1) + + +if __name__ == '__main__': + main() diff --git a/uk/03-skills/refactor/templates/refactoring-plan.md b/uk/03-skills/refactor/templates/refactoring-plan.md new file mode 100644 index 0000000..467cbda --- /dev/null +++ b/uk/03-skills/refactor/templates/refactoring-plan.md @@ -0,0 +1,284 @@ +# Шаблон плану рефакторингу + +Використовуйте цей шаблон для документування та відстеження вашого рефакторингу. + +--- + +## Інформація про проєкт + +| Поле | Значення | +|------|----------| +| **Проєкт/Модуль** | [Назва проєкту] | +| **Цільові файли** | [Список файлів для рефакторингу] | +| **Дата створення** | [Дата] | +| **Автор** | [Імʼя] | +| **Статус** | Чернетка / На перегляді / Затверджено / В роботі / Завершено | + +--- + +## Загальний опис + +### Цілі +- [ ] [Основна ціль: напр., Покращити читабельність обробки платежів] +- [ ] [Другорядна ціль: напр., Зменшити дублювання коду] +- [ ] [Третинна ціль: напр., Покращити тестовність] + +### Обмеження +- [ ] [Обмеження 1: напр., Не можна змінювати публічний API] +- [ ] [Обмеження 2: напр., Зберегти зворотну сумісність] +- [ ] [Обмеження 3: напр., Без змін схеми БД] + +### Рівень ризику +- [ ] Низький — незначні зміни, добре протестований код +- [ ] Середній — помірні зміни, деякий ризик +- [ ] Високий — значні зміни, потрібна ретельна увага + +--- + +## Контрольний список перед рефакторингом + +### Оцінка покриття тестами + +| Метрика | Поточне | Ціль | Статус | +|---------|---------|------|--------| +| Покриття юніт-тестами | __% | ≥80% | | +| Інтеграційні тести | Так/Ні | Так | | +| Усі тести проходять | Так/Ні | Так | | + +### Потрібно перед початком +- [ ] Усі тести проходять +- [ ] Код переглянутий та зрозумілий +- [ ] Резервне копіювання/контроль версій налаштовано +- [ ] Затвердження користувача отримано + +--- + +## Виявлені запахи коду + +### Резюме + +| # | Запах | Розташування | Серйозність | Пріоритет | +|---|-------|-------------|-------------|-----------| +| 1 | [напр., Long Method] | [файл:рядок] | Високий | P1 | +| 2 | [напр., Duplicate Code] | [файл:рядок] | Середній | P2 | +| 3 | [напр., Feature Envy] | [файл:рядок] | Низький | P3 | + +### Детальний аналіз + +#### Запах #1: [Назва] + +**Розташування**: `path/to/file.js:45-120` + +**Опис**: [Детальний опис проблеми] + +**Вплив**: +- [Вплив 1] +- [Вплив 2] + +**Запропоноване рішення**: [Короткий огляд виправлення] + +--- + +## Фази рефакторингу + +### Фаза A: Швидкі перемоги (Низький ризик) + +**Ціль**: Прості покращення з негайною цінністю + +**Орієнтовні зміни**: [X файлів, Y методів] + +**Потрібне затвердження користувача**: Так / Ні + +| # | Завдання | Файл | Рефакторинг | Статус | +|---|---------|------|-------------|--------| +| A1 | Перейменувати змінну `x` на `userCount` | utils.js:15 | Rename Variable | [ ] | +| A2 | Видалити невикористаний `oldHandler()` | api.js:89 | Remove Dead Code | [ ] | +| A3 | Витягти дубльовану валідацію | form.js:23,67 | Extract Method | [ ] | + +**План відкату**: Відкатити коміти A1-A3 + +--- + +### Фаза B: Структурні покращення (Середній ризик) + +**Ціль**: Покращити організацію та ясність коду + +**Орієнтовні зміни**: [X файлів, Y методів] + +**Потрібне затвердження користувача**: Так + +**Залежності**: Фаза A має бути завершена + +| # | Завдання | Файл | Рефакторинг | Статус | +|---|---------|------|-------------|--------| +| B1 | Витягти `calculatePrice()` з довгого методу | order.js:45 | Extract Method | [ ] | +| B2 | Ввести обʼєкт параметрів `OrderDetails` | order.js:12 | Introduce Parameter Object | [ ] | +| B3 | Перемістити `formatAddress()` до класу Address | customer.js:78 | Move Method | [ ] | + +**План відкату**: Відкатити до коміту після Фази A + +--- + +### Фаза C: Архітектурні зміни (Вищий ризик) + +**Ціль**: Усунути глибші структурні проблеми + +**Орієнтовні зміни**: [X файлів, Y методів] + +**Потрібне затвердження користувача**: Так + +**Залежності**: Фази A та B мають бути завершені + +| # | Завдання | Файл | Рефакторинг | Статус | +|---|---------|------|-------------|--------| +| C1 | Замінити switch цін на поліморфізм | pricing.js:30 | Replace Conditional with Polymorphism | [ ] | +| C2 | Витягти клас `NotificationService` | user.js:100 | Extract Class | [ ] | + +**План відкату**: Відкатити до коміту після Фази B + +--- + +## Детальні кроки рефакторингу + +### Завдання [ID]: [Назва завдання] + +**Усунений запах**: [Назва запаху] + +**Техніка рефакторингу**: [Назва техніки] + +**Рівень ризику**: Низький / Середній / Високий + +#### Контекст + +**До** (Поточний стан): +```javascript +// Вставте поточний код тут +``` + +**Після** (Очікуваний стан): +```javascript +// Вставте очікуваний код тут +``` + +#### Покрокова механіка + +1. [ ] **Крок 1**: [Опис] + - Тест: Запустити тести після цього кроку + - Очікувано: Усі тести проходять + +2. [ ] **Крок 2**: [Опис] + - Тест: Запустити тести після цього кроку + - Очікувано: Усі тести проходять + +3. [ ] **Крок 3**: [Опис] + - Тест: Запустити тести після цього кроку + - Очікувано: Усі тести проходять + +#### Верифікація + +- [ ] Усі тести проходять +- [ ] Поведінка не змінилася +- [ ] Код компілюється +- [ ] Немає нових попереджень + +#### Повідомлення коміту +``` +refactor: [Опишіть рефакторинг] +``` + +--- + +## Відстеження прогресу + +### Статус фаз + +| Фаза | Статус | Розпочато | Завершено | Тести проходять | +|------|--------|-----------|-----------|-----------------| +| A | Не розпочато / В роботі / Готово | | | | +| B | Не розпочато / В роботі / Готово | | | | +| C | Не розпочато / В роботі / Готово | | | | + +### Виявлені проблеми + +| # | Проблема | Рішення | Статус | +|---|---------|---------|--------| +| 1 | [Опис] | [Як вирішено] | Відкрито / Вирішено | + +--- + +## Порівняння метрик + +### До рефакторингу + +| Метрика | Файл 1 | Файл 2 | Загалом | +|---------|--------|--------|---------| +| Рядків коду | | | | +| Цикломатична складність | | | | +| Індекс супровідності | | | | +| Кількість методів | | | | +| Середня довжина методу | | | | + +### Після рефакторингу + +| Метрика | Файл 1 | Файл 2 | Загалом | Зміна | +|---------|--------|--------|---------|-------| +| Рядків коду | | | | | +| Цикломатична складність | | | | | +| Індекс супровідності | | | | | +| Кількість методів | | | | | +| Середня довжина методу | | | | | + +--- + +## Контрольний список після рефакторингу + +- [ ] Усі тести проходять +- [ ] Немає нових попереджень або помилок +- [ ] Код успішно компілюється +- [ ] Ручна верифікація завершена +- [ ] Документація оновлена (за потреби) +- [ ] Код переглянутий +- [ ] Метрики покращені +- [ ] Підпис користувача отриманий + +--- + +## Отримані уроки + +### Що пройшло добре +- [Пункт 1] +- [Пункт 2] + +### Що можна покращити +- [Пункт 1] +- [Пункт 2] + +### Рекомендації на майбутнє +- [Пункт 1] +- [Пункт 2] + +--- + +## Затвердження + +| Роль | Імʼя | Дата | Підпис | +|------|------|------|--------| +| Автор плану | | | | +| Технічний лід | | | | +| Власник продукту | | | | + +--- + +## Додатки + +### A. Повʼязана документація +- [Посилання на релевантні документи] + +### B. Довідкові матеріали +- [Посилання на каталог запахів коду] +- [Посилання на каталог рефакторингів] + +### C. Використані інструменти +- [Тестовий фреймворк] +- [Інструменти лінтингу] +- [Інструменти аналізу складності] diff --git a/uk/04-subagents/README.md b/uk/04-subagents/README.md new file mode 100644 index 0000000..991a16b --- /dev/null +++ b/uk/04-subagents/README.md @@ -0,0 +1,1118 @@ + + + + + + + Claude How To + + +# Субагенти — повний довідник + +Субагенти — це спеціалізовані AI-асистенти, яким Claude Code може делегувати завдання. Кожен субагент має конкретне призначення, використовує власне контекстне вікно, окреме від основної розмови, і може бути налаштований з конкретними інструментами та власним системним промптом. + +## Зміст + +1. [Огляд](#огляд) +2. [Ключові переваги](#ключові-переваги) +3. [Розташування файлів](#розташування-файлів) +4. [Конфігурація](#конфігурація) +5. [Вбудовані субагенти](#вбудовані-субагенти) +6. [Управління субагентами](#управління-субагентами) +7. [Використання субагентів](#використання-субагентів) +8. [Відновлювані агенти](#відновлювані-агенти) +9. [Ланцюжки субагентів](#ланцюжки-субагентів) +10. [Постійна пам'ять для субагентів](#постійна-память-для-субагентів) +11. [Фонові субагенти](#фонові-субагенти) +12. [Ізоляція через Worktree](#ізоляція-через-worktree) +13. [Обмеження створюваних субагентів](#обмеження-створюваних-субагентів) +14. [CLI-команда `claude agents`](#cli-команда-claude-agents) +15. [Agent Teams (експериментально)](#agent-teams-експериментально) +16. [Безпека субагентів плагінів](#безпека-субагентів-плагінів) +17. [Архітектура](#архітектура) +18. [Управління контекстом](#управління-контекстом) +19. [Коли використовувати субагентів](#коли-використовувати-субагентів) +20. [Найкращі практики](#найкращі-практики) +21. [Приклади субагентів у цій папці](#приклади-субагентів-у-цій-папці) +22. [Інструкції з встановлення](#інструкції-з-встановлення) +23. [Пов'язані концепції](#повязані-концепції) + +--- + +## Огляд + +Субагенти забезпечують делеговане виконання завдань у Claude Code шляхом: + +- Створення **ізольованих AI-асистентів** з окремими контекстними вікнами +- Надання **налаштованих системних промптів** для спеціалізованої експертизи +- Застосування **контролю доступу до інструментів** для обмеження можливостей +- Запобігання **забрудненню контексту** від складних завдань +- Забезпечення **паралельного виконання** кількох спеціалізованих завдань + +Кожен субагент працює незалежно з чистого аркуша, отримуючи лише конкретний контекст, необхідний для його завдання, а потім повертає результати головному агенту для синтезу. + +**Швидкий старт**: Використовуйте команду `/agents` для створення, перегляду, редагування та управління субагентами в інтерактивному режимі. + +--- + +## Ключові переваги + +| Перевага | Опис | +|----------|------| +| **Збереження контексту** | Працює в окремому контексті, запобігаючи забрудненню основної розмови | +| **Спеціалізована експертиза** | Точно налаштований для конкретних доменів з вищим рівнем успіху | +| **Повторне використання** | Використання в різних проєктах і поширення між командами | +| **Гнучкі дозволи** | Різні рівні доступу до інструментів для різних типів субагентів | +| **Масштабованість** | Кілька агентів працюють над різними аспектами одночасно | + +--- + +## Розташування файлів + +Файли субагентів можна зберігати в кількох розташуваннях з різними областями дії: + +| Пріоритет | Тип | Розташування | Область дії | +|-----------|-----|-------------|-------------| +| 1 (найвищий) | **CLI-визначені** | Через прапорець `--agents` (JSON) | Лише сесія | +| 2 | **Субагенти проєкту** | `.claude/agents/` | Поточний проєкт | +| 3 | **Субагенти користувача** | `~/.claude/agents/` | Усі проєкти | +| 4 (найнижчий) | **Агенти плагінів** | Каталог `agents/` плагіна | Через плагіни | + +Коли існують дублікати імен, джерела з вищим пріоритетом мають перевагу. + +--- + +## Конфігурація + +### Формат файлу + +Субагенти визначаються у YAML-фронтматері, за яким іде системний промпт у Markdown: + +```yaml +--- +name: your-sub-agent-name +description: Description of when this subagent should be invoked +tools: tool1, tool2, tool3 # Опціонально — успадковує всі інструменти, якщо не вказано +disallowedTools: tool4 # Опціонально — явно заборонені інструменти +model: sonnet # Опціонально — sonnet, opus, haiku або inherit +permissionMode: default # Опціонально — режим дозволів +maxTurns: 20 # Опціонально — ліміт агентних кроків +skills: skill1, skill2 # Опціонально — навички для попереднього завантаження +mcpServers: server1 # Опціонально — доступні MCP-сервери +memory: user # Опціонально — область постійної пам'яті (user, project, local) +background: false # Опціонально — запуск як фонове завдання +effort: high # Опціонально — рівень зусиль (low, medium, high, max) +isolation: worktree # Опціонально — ізоляція через git worktree +initialPrompt: "Start by analyzing the codebase" # Опціонально — автоматичний перший крок +hooks: # Опціонально — хуки, обмежені компонентом + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/security-check.sh" +--- + +Your subagent's system prompt goes here. This can be multiple paragraphs +and should clearly define the subagent's role, capabilities, and approach +to solving problems. +``` + +### Поля конфігурації + +| Поле | Обов'язкове | Опис | +|------|-------------|------| +| `name` | Так | Унікальний ідентифікатор (малі літери та дефіси) | +| `description` | Так | Опис призначення природною мовою. Включіть "use PROACTIVELY" для заохочення автоматичного виклику | +| `tools` | Ні | Список інструментів через кому. Пропустіть для успадкування всіх. Підтримує синтаксис `Agent(agent_name)` для обмеження створюваних субагентів | +| `disallowedTools` | Ні | Список заборонених інструментів через кому | +| `model` | Ні | Модель: `sonnet`, `opus`, `haiku`, повний ID моделі або `inherit`. За замовч. — налаштована модель субагента | +| `permissionMode` | Ні | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` | +| `maxTurns` | Ні | Максимальна кількість агентних кроків | +| `skills` | Ні | Список навичок через кому для попереднього завантаження. Вставляє повний вміст навички в контекст при запуску | +| `mcpServers` | Ні | MCP-сервери, доступні субагенту | +| `hooks` | Ні | Хуки, обмежені компонентом (PreToolUse, PostToolUse, Stop) | +| `memory` | Ні | Область постійної пам'яті: `user`, `project` або `local` | +| `background` | Ні | `true` для запуску як фонового завдання | +| `effort` | Ні | Рівень зусиль: `low`, `medium`, `high` або `max` | +| `isolation` | Ні | `worktree` для власного git worktree | +| `initialPrompt` | Ні | Автоматичний перший крок при запуску субагента як головного агента | + +### Варіанти конфігурації інструментів + +**Варіант 1: Успадкування всіх інструментів (пропустити поле)** +```yaml +--- +name: full-access-agent +description: Agent with all available tools +--- +``` + +**Варіант 2: Вказати конкретні інструменти** +```yaml +--- +name: limited-agent +description: Agent with specific tools only +tools: Read, Grep, Glob, Bash +--- +``` + +**Варіант 3: Умовний доступ до інструментів** +```yaml +--- +name: conditional-agent +description: Agent with filtered tool access +tools: Read, Bash(npm:*), Bash(test:*) +--- +``` + +### Конфігурація через CLI + +Визначте субагентів для однієї сесії за допомогою прапорця `--agents` у форматі JSON: + +```bash +claude --agents '{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + } +}' +``` + +**Формат JSON для прапорця `--agents`:** + +```json +{ + "agent-name": { + "description": "Required: when to invoke this agent", + "prompt": "Required: system prompt for the agent", + "tools": ["Optional", "array", "of", "tools"], + "model": "optional: sonnet|opus|haiku" + } +} +``` + +**Пріоритет визначень агентів:** + +Визначення агентів завантажуються з таким пріоритетом (перший збіг виграє): +1. **CLI-визначені** — прапорець `--agents` (лише сесія, JSON) +2. **Рівень проєкту** — `.claude/agents/` (поточний проєкт) +3. **Рівень користувача** — `~/.claude/agents/` (усі проєкти) +4. **Рівень плагіна** — каталог `agents/` плагіна + +Це дозволяє CLI-визначенням перевизначати всі інші джерела для однієї сесії. + +--- + +## Вбудовані субагенти + +Claude Code включає кілька вбудованих субагентів, які завжди доступні: + +| Агент | Модель | Призначення | +|-------|--------|-------------| +| **general-purpose** | Успадковує | Складні, багатокрокові завдання | +| **Plan** | Успадковує | Дослідження для режиму планування | +| **Explore** | Haiku | Дослідження кодової бази лише для читання (швидке/середнє/дуже ретельне) | +| **Bash** | Успадковує | Термінальні команди в окремому контексті | +| **statusline-setup** | Sonnet | Налаштування рядка стану | +| **Claude Code Guide** | Haiku | Відповіді на питання про функції Claude Code | + +### Субагент General-Purpose + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Успадковує від батька | +| **Інструменти** | Усі інструменти | +| **Призначення** | Складні дослідницькі завдання, багатокрокові операції, модифікація коду | + +**Коли використовується**: Завдання, що потребують дослідження та модифікації зі складною логікою. + +### Субагент Plan + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Успадковує від батька | +| **Інструменти** | Read, Glob, Grep, Bash | +| **Призначення** | Автоматичне дослідження кодової бази в режимі планування | + +**Коли використовується**: Коли Claude потрібно зрозуміти кодову базу перед представленням плану. + +### Субагент Explore + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Haiku (швидкий, низька затримка) | +| **Режим** | Строго лише для читання | +| **Інструменти** | Glob, Grep, Read, Bash (лише команди для читання) | +| **Призначення** | Швидкий пошук та аналіз кодової бази | + +**Коли використовується**: Пошук/розуміння коду без внесення змін. + +**Рівні ретельності** — вкажіть глибину дослідження: +- **"quick"** — швидкий пошук з мінімальним дослідженням, добре для пошуку конкретних патернів +- **"medium"** — помірне дослідження, баланс швидкості та ретельності, стандартний підхід +- **"very thorough"** — комплексний аналіз у кількох розташуваннях та конвенціях іменування, може зайняти більше часу + +### Субагент Bash + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Успадковує від батька | +| **Інструменти** | Bash | +| **Призначення** | Виконання термінальних команд в окремому контекстному вікні | + +**Коли використовується**: Виконання команд оболонки, які виграють від ізольованого контексту. + +### Субагент Statusline Setup + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Sonnet | +| **Інструменти** | Read, Write, Bash | +| **Призначення** | Налаштування відображення рядка стану Claude Code | + +**Коли використовується**: Налаштування або кастомізація рядка стану. + +### Субагент Claude Code Guide + +| Властивість | Значення | +|-------------|----------| +| **Модель** | Haiku (швидкий, низька затримка) | +| **Інструменти** | Лише для читання | +| **Призначення** | Відповіді на питання про функції та використання Claude Code | + +**Коли використовується**: Коли користувачі питають про роботу Claude Code або використання конкретних функцій. + +--- + +## Управління субагентами + +### Команда `/agents` (рекомендовано) + +```bash +/agents +``` + +Надає інтерактивне меню для: +- Перегляду всіх доступних субагентів (вбудованих, користувача та проєкту) +- Створення нових субагентів з керованим налаштуванням +- Редагування наявних субагентів та доступу до інструментів +- Видалення субагентів +- Перегляду активних субагентів при наявності дублікатів + +### Пряме управління файлами + +```bash +# Створення субагента проєкту +mkdir -p .claude/agents +cat > .claude/agents/test-runner.md << 'EOF' +--- +name: test-runner +description: Use proactively to run tests and fix failures +--- + +You are a test automation expert. When you see code changes, proactively +run the appropriate tests. If tests fail, analyze the failures and fix +them while preserving the original test intent. +EOF + +# Створення субагента користувача (доступний у всіх проєктах) +mkdir -p ~/.claude/agents +``` + +--- + +## Використання субагентів + +### Автоматичне делегування + +Claude проактивно делегує завдання на основі: +- Опису завдання у вашому запиті +- Поля `description` у конфігурації субагента +- Поточного контексту та доступних інструментів + +Для заохочення проактивного використання додайте "use PROACTIVELY" або "MUST BE USED" у поле `description`: + +```yaml +--- +name: code-reviewer +description: Expert code review specialist. Use PROACTIVELY after writing or modifying code. +--- +``` + +### Явний виклик + +Ви можете явно запросити конкретного субагента: + +``` +> Use the test-runner subagent to fix failing tests +> Have the code-reviewer subagent look at my recent changes +> Ask the debugger subagent to investigate this error +``` + +### Виклик через @-згадку + +Використовуйте префікс `@` для гарантованого виклику конкретного субагента (обходить евристику автоматичного делегування): + +``` +> @"code-reviewer (agent)" review the auth module +``` + +### Агент на всю сесію + +Запуск сесії з конкретним агентом як головним: + +```bash +# Через прапорець CLI +claude --agent code-reviewer + +# Через settings.json +{ + "agent": "code-reviewer" +} +``` + +### Список доступних агентів + +Використовуйте команду `claude agents` для переліку всіх налаштованих агентів з усіх джерел: + +```bash +claude agents +``` + +--- + +## Відновлювані агенти + +Субагенти можуть продовжувати попередні розмови зі збереженим контекстом: + +```bash +# Початковий виклик +> Use the code-analyzer agent to start reviewing the authentication module +# Повертає agentId: "abc123" + +# Відновлення агента пізніше +> Resume agent abc123 and now analyze the authorization logic as well +``` + +**Випадки використання**: +- Тривалі дослідження між кількома сесіями +- Ітеративне вдосконалення без втрати контексту +- Багатокрокові воркфлови зі збереженням контексту + +--- + +## Ланцюжки субагентів + +Послідовне виконання кількох субагентів: + +```bash +> First use the code-analyzer subagent to find performance issues, + then use the optimizer subagent to fix them +``` + +Це дозволяє створювати складні воркфлови, де результат одного субагента є вхідними даними для іншого. + +--- + +## Постійна пам'ять для субагентів + +Поле `memory` надає субагентам постійний каталог, що зберігається між розмовами. Це дозволяє субагентам накопичувати знання з часом, зберігаючи нотатки, висновки та контекст між сесіями. + +### Області пам'яті + +| Область | Каталог | Випадок використання | +|---------|---------|---------------------| +| `user` | `~/.claude/agent-memory//` | Персональні нотатки та налаштування для всіх проєктів | +| `project` | `.claude/agent-memory//` | Знання, специфічні для проєкту, спільні з командою | +| `local` | `.claude/agent-memory-local//` | Локальні знання проєкту, не комітяться у контроль версій | + +### Як це працює + +- Перші 200 рядків `MEMORY.md` у каталозі пам'яті автоматично завантажуються в системний промпт субагента +- Інструменти `Read`, `Write` та `Edit` автоматично ввімкнені для управління файлами пам'яті +- Субагент може створювати додаткові файли у каталозі пам'яті за потребою + +### Приклад конфігурації + +```yaml +--- +name: researcher +memory: user +--- + +You are a research assistant. Use your memory directory to store findings, +track progress across sessions, and build up knowledge over time. + +Check your MEMORY.md file at the start of each session to recall previous context. +``` + +```mermaid +graph LR + A["Subagent
Session 1"] -->|writes| M["MEMORY.md
(persistent)"] + M -->|loads into| B["Subagent
Session 2"] + B -->|updates| M + M -->|loads into| C["Subagent
Session 3"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style M fill:#f3e5f5,stroke:#333,color:#333 +``` + +--- + +## Фонові субагенти + +Субагенти можуть працювати у фоні, звільняючи основну розмову для інших завдань. + +### Конфігурація + +Встановіть `background: true` у фронтматері для постійного запуску субагента як фонового завдання: + +```yaml +--- +name: long-runner +background: true +description: Performs long-running analysis tasks in the background +--- +``` + +### Клавіатурні скорочення + +| Скорочення | Дія | +|-----------|-----| +| `Ctrl+B` | Перемістити поточне завдання субагента у фон | +| `Ctrl+F` | Завершити всіх фонових агентів (натисніть двічі для підтвердження) | + +### Вимкнення фонових завдань + +Встановіть змінну оточення для повного вимкнення підтримки фонових завдань: + +```bash +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 +``` + +--- + +## Ізоляція через Worktree + +Налаштування `isolation: worktree` надає субагенту власне git worktree, дозволяючи вносити зміни незалежно, не впливаючи на основне робоче дерево. + +### Конфігурація + +```yaml +--- +name: feature-builder +isolation: worktree +description: Implements features in an isolated git worktree +tools: Read, Write, Edit, Bash, Grep, Glob +--- +``` + +### Як це працює + +```mermaid +graph TB + Main["Main Working Tree"] -->|spawns| Sub["Subagent with
Isolated Worktree"] + Sub -->|makes changes in| WT["Separate Git
Worktree + Branch"] + WT -->|no changes| Clean["Auto-cleaned"] + WT -->|has changes| Return["Returns worktree
path and branch"] + + style Main fill:#e1f5fe,stroke:#333,color:#333 + style Sub fill:#f3e5f5,stroke:#333,color:#333 + style WT fill:#e8f5e9,stroke:#333,color:#333 + style Clean fill:#fff3e0,stroke:#333,color:#333 + style Return fill:#fff3e0,stroke:#333,color:#333 +``` + +- Субагент працює у власному git worktree на окремій гілці +- Якщо субагент не вносить змін, worktree автоматично очищується +- Якщо зміни є, шлях до worktree та назва гілки повертаються головному агенту для огляду або мерджу + +--- + +## Обмеження створюваних субагентів + +Ви можете контролювати, яких субагентів може створювати конкретний субагент, використовуючи синтаксис `Agent(agent_type)` у полі `tools`. Це дозволяє створити список дозволених субагентів для делегування. + +> **Примітка**: У v2.1.63 інструмент `Task` було перейменовано на `Agent`. Існуючі посилання `Task(...)` все ще працюють як псевдоніми. + +### Приклад + +```yaml +--- +name: coordinator +description: Coordinates work between specialized agents +tools: Agent(worker, researcher), Read, Bash +--- + +You are a coordinator agent. You can delegate work to the "worker" and +"researcher" subagents only. Use Read and Bash for your own exploration. +``` + +У цьому прикладі субагент `coordinator` може створювати лише субагентів `worker` та `researcher`. Він не може створювати інших субагентів, навіть якщо вони визначені деінде. + +--- + +## CLI-команда `claude agents` + +Команда `claude agents` відображає всіх налаштованих агентів, згрупованих за джерелом (вбудовані, рівень користувача, рівень проєкту): + +```bash +claude agents +``` + +Ця команда: +- Показує всіх доступних агентів з усіх джерел +- Групує агентів за розташуванням джерела +- Вказує **перевизначення**, коли агент вищого пріоритету затіняє агента нижчого рівня (наприклад, агент рівня проєкту з тим самим ім'ям, що й агент рівня користувача) + +--- + +## Agent Teams (експериментально) + +Agent Teams координують кілька екземплярів Claude Code, що працюють разом над складними завданнями. На відміну від субагентів (які є делегованими підзавданнями, що повертають результати), тіммейти працюють незалежно з власними контекстними вікнами і можуть обмінюватися повідомленнями безпосередньо через спільну систему поштових скриньок. + +> **Офіційна документація**: [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) + +> **Примітка**: Agent Teams — експериментальна функція, вимкнена за замовчуванням. Потребує Claude Code v2.1.32+. Увімкніть перед використанням. + +### Субагенти vs Agent Teams + +| Аспект | Субагенти | Agent Teams | +|--------|-----------|-------------| +| **Модель делегування** | Батько делегує підзавдання, чекає результат | Тімлід координує роботу, тіммейти виконують незалежно | +| **Контекст** | Чистий контекст на підзавдання, результати стискаються назад | Кожен тіммейт підтримує власне постійне контекстне вікно | +| **Координація** | Послідовна або паралельна, керована батьком | Спільний список завдань з автоматичним управлінням залежностями | +| **Комунікація** | Результати повертаються лише батьку (без обміну між агентами) | Тіммейти обмінюються повідомленнями безпосередньо через поштову скриньку | +| **Відновлення сесії** | Підтримується | Не підтримується з in-process тіммейтами | +| **Найкраще для** | Сфокусовані, чітко визначені підзавдання | Складна робота, що потребує міжагентної комунікації та паралельного виконання | + +### Увімкнення Agent Teams + +Встановіть змінну оточення або додайте до `settings.json`: + +```bash +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +Або в `settings.json`: + +```json +{ + "env": { + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" + } +} +``` + +### Запуск команди + +Після увімкнення попросіть Claude працювати з тіммейтами у промпті: + +``` +User: Build the authentication module. Use a team — one teammate for the API endpoints, + one for the database schema, and one for the test suite. +``` + +Claude створить команду, призначить завдання та автоматично координуватиме роботу. + +### Режими відображення + +Контролюйте, як відображається активність тіммейтів: + +| Режим | Прапорець | Опис | +|-------|-----------|------| +| **Auto** | `--teammate-mode auto` | Автоматично обирає найкращий режим для вашого терміналу | +| **In-process** (за замовч.) | `--teammate-mode in-process` | Показує вивід тіммейтів у поточному терміналі | +| **Split-panes** | `--teammate-mode tmux` | Відкриває кожного тіммейта в окремій панелі tmux або iTerm2 | + +```bash +claude --teammate-mode tmux +``` + +Також можна встановити режим у `settings.json`: + +```json +{ + "teammateMode": "tmux" +} +``` + +> **Примітка**: Режим split-pane потребує tmux або iTerm2. Недоступний у VS Code terminal, Windows Terminal або Ghostty. + +### Навігація + +Використовуйте `Shift+Down` для навігації між тіммейтами в режимі split-pane. + +### Конфігурація команди + +Конфігурації команд зберігаються в `~/.claude/teams/{team-name}/config.json`. + +### Архітектура + +```mermaid +graph TB + Lead["Team Lead
(Coordinator)"] + TaskList["Shared Task List
(Dependencies)"] + Mailbox["Mailbox
(Messages)"] + T1["Teammate 1
(Own Context)"] + T2["Teammate 2
(Own Context)"] + T3["Teammate 3
(Own Context)"] + + Lead -->|assigns tasks| TaskList + Lead -->|sends messages| Mailbox + TaskList -->|picks up work| T1 + TaskList -->|picks up work| T2 + TaskList -->|picks up work| T3 + T1 -->|reads/writes| Mailbox + T2 -->|reads/writes| Mailbox + T3 -->|reads/writes| Mailbox + T1 -->|updates status| TaskList + T2 -->|updates status| TaskList + T3 -->|updates status| TaskList + + style Lead fill:#e1f5fe,stroke:#333,color:#333 + style TaskList fill:#fff9c4,stroke:#333,color:#333 + style Mailbox fill:#f3e5f5,stroke:#333,color:#333 + style T1 fill:#e8f5e9,stroke:#333,color:#333 + style T2 fill:#e8f5e9,stroke:#333,color:#333 + style T3 fill:#e8f5e9,stroke:#333,color:#333 +``` + +**Ключові компоненти**: + +- **Team Lead**: основна сесія Claude Code, що створює команду, призначає завдання та координує +- **Shared Task List**: синхронізований список завдань з автоматичним відстеженням залежностей +- **Mailbox**: система міжагентних повідомлень для координації тіммейтів +- **Teammates**: незалежні екземпляри Claude Code з власними контекстними вікнами + +### Призначення завдань та обмін повідомленнями + +Тімлід розбиває роботу на завдання та призначає їх тіммейтам. Спільний список завдань забезпечує: + +- **Автоматичне управління залежностями** — завдання чекають завершення залежностей +- **Відстеження статусу** — тіммейти оновлюють статус завдань під час роботи +- **Міжагентні повідомлення** — тіммейти надсилають повідомлення через поштову скриньку для координації (наприклад, "Схема бази даних готова, можете починати писати запити") + +### Воркфлов затвердження плану + +Для складних завдань тімлід створює план виконання перед початком роботи тіммейтів. Користувач переглядає та затверджує план, забезпечуючи відповідність підходу команди очікуванням перед внесенням будь-яких змін у код. + +### Хук-події для команд + +Agent Teams додають дві додаткових [хук-події](../06-hooks/): + +| Подія | Спрацьовує коли | Випадок використання | +|-------|----------------|---------------------| +| `TeammateIdle` | Тіммейт завершив поточне завдання і не має очікуваної роботи | Сповіщення, призначення наступних завдань | +| `TaskCompleted` | Завдання у спільному списку позначено як завершене | Валідація, оновлення дашбордів, ланцюжки залежних робіт | + +### Найкращі практики + +- **Розмір команди**: тримайте 3-5 тіммейтів для оптимальної координації +- **Розмір завдань**: розбивайте роботу на завдання по 5-15 хвилин — достатньо малі для паралелізації, достатньо великі для значущості +- **Уникайте конфліктів файлів**: призначайте різні файли або каталоги різним тіммейтам +- **Починайте просто**: використовуйте in-process режим для першої команди; переходьте на split-panes після звикання +- **Чіткі описи завдань**: надавайте конкретні, дієві описи завдань + +### Обмеження + +- **Експериментально**: поведінка функції може змінитися в майбутніх релізах +- **Немає відновлення сесії**: in-process тіммейти не можуть бути відновлені після завершення сесії +- **Одна команда на сесію**: неможливо створити вкладені команди або кілька команд в одній сесії +- **Фіксований лідер**: роль тімліда не може бути передана тіммейту +- **Обмеження split-pane**: потребує tmux/iTerm2; недоступний у VS Code terminal, Windows Terminal або Ghostty +- **Немає крос-сесійних команд**: тіммейти існують лише в межах поточної сесії + +> **Увага**: Agent Teams — експериментальна функція. Спочатку тестуйте з некритичною роботою та відстежуйте координацію тіммейтів на предмет неочікуваної поведінки. + +--- + +## Безпека субагентів плагінів + +Субагенти плагінів мають обмежені можливості фронтматера з міркувань безпеки. Наступні поля **заборонені** у визначеннях субагентів плагінів: + +- `hooks` — не можна визначати хуки життєвого циклу +- `mcpServers` — не можна налаштовувати MCP-сервери +- `permissionMode` — не можна перевизначати налаштування дозволів + +Це запобігає ескалації привілеїв або виконанню довільних команд через хуки субагентів плагінів. + +--- + +## Архітектура + +### Високорівнева архітектура + +```mermaid +graph TB + User["User"] + Main["Main Agent
(Coordinator)"] + Reviewer["Code Reviewer
Subagent"] + Tester["Test Engineer
Subagent"] + Docs["Documentation
Subagent"] + + User -->|asks| Main + Main -->|delegates| Reviewer + Main -->|delegates| Tester + Main -->|delegates| Docs + Reviewer -->|returns result| Main + Tester -->|returns result| Main + Docs -->|returns result| Main + Main -->|synthesizes| User +``` + +### Життєвий цикл субагента + +```mermaid +sequenceDiagram + participant User + participant MainAgent as Main Agent + participant CodeReviewer as Code Reviewer
Subagent + participant Context as Separate
Context Window + + User->>MainAgent: "Build new auth feature" + MainAgent->>MainAgent: Analyze task + MainAgent->>CodeReviewer: "Review this code" + CodeReviewer->>Context: Initialize clean context + Context->>CodeReviewer: Load reviewer instructions + CodeReviewer->>CodeReviewer: Perform review + CodeReviewer-->>MainAgent: Return findings + MainAgent->>MainAgent: Incorporate results + MainAgent-->>User: Provide synthesis +``` + +--- + +## Управління контекстом + +```mermaid +graph TB + A["Main Agent Context
50,000 tokens"] + B["Subagent 1 Context
20,000 tokens"] + C["Subagent 2 Context
20,000 tokens"] + D["Subagent 3 Context
20,000 tokens"] + + A -->|Clean slate| B + A -->|Clean slate| C + A -->|Clean slate| D + + B -->|Results only| A + C -->|Results only| A + D -->|Results only| A + + style A fill:#e1f5fe + style B fill:#fff9c4 + style C fill:#fff9c4 + style D fill:#fff9c4 +``` + +### Ключові моменти + +- Кожен субагент отримує **чисте контекстне вікно** без історії основної розмови +- Субагенту передається лише **релевантний контекст** для конкретного завдання +- Результати **стискаються** назад до головного агента +- Це запобігає **вичерпанню токенів контексту** у тривалих проєктах + +### Міркування щодо продуктивності + +- **Ефективність контексту** — агенти зберігають основний контекст, дозволяючи довші сесії +- **Затримка** — субагенти починають з чистого аркуша і можуть додавати затримку при збиранні початкового контексту + +### Ключові поведінки + +- **Без вкладеного створення** — субагенти не можуть створювати інших субагентів +- **Фонові дозволи** — фонові субагенти автоматично відхиляють дозволи, що не були попередньо схвалені +- **Переведення у фон** — натисніть `Ctrl+B` для переведення поточного завдання у фон +- **Транскрипти** — транскрипти субагентів зберігаються в `~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl` +- **Автокомпакція** — контекст субагента автоматично компактується при ~95% заповненості (перевизначити через змінну оточення `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`) + +--- + +## Коли використовувати субагентів + +| Сценарій | Використовувати субагента | Чому | +|----------|--------------------------|------| +| Складна фіча з багатьма кроками | Так | Розділення відповідальності, запобігання забрудненню контексту | +| Швидке код-рев'ю | Ні | Зайві накладні витрати | +| Паралельне виконання завдань | Так | Кожен субагент має власний контекст | +| Потрібна спеціалізована експертиза | Так | Кастомні системні промпти | +| Тривалий аналіз | Так | Запобігає вичерпанню основного контексту | +| Одне завдання | Ні | Додає затримку без потреби | + +--- + +## Найкращі практики + +### Принципи проєктування + +**Рекомендовано:** +- Починайте з агентів, згенерованих Claude — створіть початкового субагента через Claude, потім ітеруйте для кастомізації +- Проєктуйте сфокусованих субагентів — одна чітка відповідальність замість одного, що робить все +- Пишіть детальні промпти — включайте конкретні інструкції, приклади та обмеження +- Обмежуйте доступ до інструментів — надавайте лише необхідні інструменти +- Контроль версій — комітьте субагентів проєкту у систему контролю версій + +**Не рекомендовано:** +- Створювати субагентів з перекриваючимися ролями +- Надавати субагентам зайвий доступ до інструментів +- Використовувати субагентів для простих однокрокових завдань +- Змішувати відповідальності в промпті одного субагента +- Забувати передавати необхідний контекст + +### Найкращі практики системного промпта + +1. **Будьте конкретними щодо ролі** + ``` + You are an expert code reviewer specializing in [specific areas] + ``` + +2. **Чітко визначте пріоритети** + ``` + Review priorities (in order): + 1. Security Issues + 2. Performance Problems + 3. Code Quality + ``` + +3. **Вкажіть формат виводу** + ``` + For each issue provide: Severity, Category, Location, Description, Fix, Impact + ``` + +4. **Включіть кроки дій** + ``` + When invoked: + 1. Run git diff to see recent changes + 2. Focus on modified files + 3. Begin review immediately + ``` + +### Стратегія доступу до інструментів + +1. **Починайте з обмежень**: лише необхідні інструменти +2. **Розширюйте за потребою**: додавайте інструменти, коли вимоги цього потребують +3. **Лише для читання де можливо**: Read/Grep для аналітичних агентів +4. **Ізольоване виконання**: обмежте Bash-команди конкретними патернами + +--- + +## Приклади субагентів у цій папці + +Ця папка містить готові до використання приклади субагентів: + +### 1. Code Reviewer (`code-reviewer.md`) + +**Призначення**: комплексний аналіз якості та підтримуваності коду + +**Інструменти**: Read, Grep, Glob, Bash + +**Спеціалізація**: виявлення вразливостей безпеки, ідентифікація оптимізацій продуктивності, оцінка підтримуваності коду, аналіз покриття тестами + +**Коли використовувати**: потрібне автоматизоване код-рев'ю з фокусом на якість та безпеку + +--- + +### 2. Test Engineer (`test-engineer.md`) + +**Призначення**: стратегія тестування, аналіз покриття та автоматичне тестування + +**Інструменти**: Read, Write, Bash, Grep + +**Спеціалізація**: створення юніт-тестів, проєктування інтеграційних тестів, ідентифікація крайніх випадків, аналіз покриття (ціль >80%) + +**Коли використовувати**: потрібне створення комплексного набору тестів або аналіз покриття + +--- + +### 3. Documentation Writer (`documentation-writer.md`) + +**Призначення**: технічна документація, документація API та посібники користувача + +**Інструменти**: Read, Write, Grep + +**Спеціалізація**: документація API-ендпоінтів, створення посібників користувача, архітектурна документація, покращення коментарів коду + +**Коли використовувати**: потрібне створення або оновлення документації проєкту + +--- + +### 4. Secure Reviewer (`secure-reviewer.md`) + +**Призначення**: код-рев'ю з фокусом на безпеку з мінімальними дозволами + +**Інструменти**: Read, Grep + +**Спеціалізація**: виявлення вразливостей безпеки, проблеми автентифікації/авторизації, ризики витоку даних, ідентифікація ін'єкційних атак + +**Коли використовувати**: потрібний аудит безпеки без можливості модифікації + +--- + +### 5. Implementation Agent (`implementation-agent.md`) + +**Призначення**: повні можливості реалізації для розробки функцій + +**Інструменти**: Read, Write, Edit, Bash, Grep, Glob + +**Спеціалізація**: реалізація функцій, генерація коду, виконання збірки та тестів, модифікація кодової бази + +**Коли використовувати**: потрібен субагент для наскрізної реалізації функцій + +--- + +### 6. Debugger (`debugger.md`) + +**Призначення**: спеціаліст з налагодження помилок, провалених тестів та неочікуваної поведінки + +**Інструменти**: Read, Edit, Bash, Grep, Glob + +**Спеціалізація**: аналіз першопричин, дослідження помилок, розв'язання провалених тестів, мінімальне виправлення + +**Коли використовувати**: стикаєтесь з багами, помилками або неочікуваною поведінкою + +--- + +### 7. Data Scientist (`data-scientist.md`) + +**Призначення**: експерт з аналізу даних для SQL-запитів та інсайтів + +**Інструменти**: Bash, Read, Write + +**Спеціалізація**: оптимізація SQL-запитів, операції BigQuery, аналіз та візуалізація даних, статистичні інсайти + +**Коли використовувати**: потрібний аналіз даних, SQL-запити або операції BigQuery + +--- + +## Інструкції з встановлення + +### Метод 1: Команда /agents (рекомендовано) + +```bash +/agents +``` + +Далі: +1. Оберіть 'Create New Agent' +2. Оберіть рівень проєкту або користувача +3. Опишіть субагента детально +4. Оберіть інструменти (або залиште порожнім для успадкування всіх) +5. Збережіть і використовуйте + +### Метод 2: Копіювання в проєкт + +Скопіюйте файли агентів у каталог `.claude/agents/` проєкту: + +```bash +# Перейдіть до проєкту +cd /path/to/your/project + +# Створіть каталог агентів, якщо він не існує +mkdir -p .claude/agents + +# Скопіюйте файли агентів з цієї папки +cp /path/to/04-subagents/*.md .claude/agents/ + +# Видаліть README (не потрібний у .claude/agents) +rm .claude/agents/README.md +``` + +### Метод 3: Копіювання в каталог користувача + +Для агентів, доступних у всіх проєктах: + +```bash +# Створіть каталог агентів користувача +mkdir -p ~/.claude/agents + +# Скопіюйте агентів +cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/ +cp /path/to/04-subagents/debugger.md ~/.claude/agents/ +# ... скопіюйте інших за потребою +``` + +### Перевірка + +Після встановлення переконайтесь, що агенти розпізнаються: + +```bash +/agents +``` + +Ви повинні побачити встановлених агентів поряд з вбудованими. + +--- + +## Структура файлів + +``` +project/ +├── .claude/ +│ └── agents/ +│ ├── code-reviewer.md +│ ├── test-engineer.md +│ ├── documentation-writer.md +│ ├── secure-reviewer.md +│ ├── implementation-agent.md +│ ├── debugger.md +│ └── data-scientist.md +└── ... +``` + +--- + +## Пов'язані концепції + +### Пов'язані функції + +- **[Слеш-команди](../01-slash-commands/)** — швидкі ярлики, ініційовані користувачем +- **[Пам'ять](../02-memory/)** — постійний крос-сесійний контекст +- **[Навички](../03-skills/)** — повторно використовувані автономні можливості +- **[Протокол MCP](../05-mcp/)** — доступ до зовнішніх даних у реальному часі +- **[Хуки](../06-hooks/)** — автоматизація команд оболонки за подіями +- **[Плагіни](../07-plugins/)** — пакети розширень + +### Порівняння з іншими функціями + +| Функція | Виклик користувачем | Автовиклик | Постійна | Зовнішній доступ | Ізольований контекст | +|---------|---------------------|------------|----------|------------------|---------------------| +| **Слеш-команди** | Так | Ні | Ні | Ні | Ні | +| **Субагенти** | Так | Так | Ні | Ні | Так | +| **Пам'ять** | Авто | Авто | Так | Ні | Ні | +| **MCP** | Авто | Так | Ні | Так | Ні | +| **Навички** | Так | Так | Ні | Ні | Ні | + +### Патерн інтеграції + +```mermaid +graph TD + User["User Request"] --> Main["Main Agent"] + Main -->|Uses| Memory["Memory
(Context)"] + Main -->|Queries| MCP["MCP
(Live Data)"] + Main -->|Invokes| Skills["Skills
(Auto Tools)"] + Main -->|Delegates| Subagents["Subagents
(Specialists)"] + + Subagents -->|Use| Memory + Subagents -->|Query| MCP + Subagents -->|Isolated| Context["Clean Context
Window"] +``` + +--- + +## Додаткові ресурси + +- [Офіційна документація субагентів](https://code.claude.com/docs/en/sub-agents) +- [Довідник CLI](https://code.claude.com/docs/en/cli-reference) — прапорець `--agents` та інші опції CLI +- [Посібник плагінів](../07-plugins/) — для пакування агентів з іншими функціями +- [Посібник навичок](../03-skills/) — для автоматично викликуваних можливостей +- [Посібник з пам'яті](../02-memory/) — для постійного контексту +- [Посібник хуків](../06-hooks/) — для автоматизації за подіями + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/04-subagents/clean-code-reviewer.md b/uk/04-subagents/clean-code-reviewer.md new file mode 100644 index 0000000..0bc0eda --- /dev/null +++ b/uk/04-subagents/clean-code-reviewer.md @@ -0,0 +1,69 @@ +--- +name: clean-code-reviewer +description: Спеціаліст з дотримання принципів Clean Code. Перевіряє код на порушення теорії та найкращих практик Clean Code. Використовуйте ПРОАКТИВНО після написання коду для забезпечення супровідності та професійної якості. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Агент рев'ю Clean Code + +Ви — старший рев'юер коду, що спеціалізується на принципах Clean Code (Роберт Мартін). Виявляйте порушення та надавайте практичні виправлення. + +## Процес +1. Запустити `git diff` для перегляду нещодавніх змін +2. Ретельно прочитати відповідні файли +3. Звітувати про порушення з файл:рядок, фрагментом коду та виправленням + +## Що перевіряти + +**Іменування**: Розкриває намір, вимовне, придатне для пошуку. Без кодувань/префіксів. Класи = іменники, методи = дієслова. + +**Функції**: <20 рядків, роблять ОДНУ річ, макс. 3 параметри, без прапорцевих аргументів, без побічних ефектів, без повернення null. + +**Коментарі**: Код має бути самопояснювальним. Видаляти закоментований код. Без надлишкових/оманливих коментарів. + +**Структура**: Малі зосереджені класи, єдина відповідальність, висока звʼязність, низька зчепленість. Уникати god-класів. + +**SOLID**: Єдина відповідальність, Відкритість/Закритість, Підстановка Лісков, Розділення інтерфейсів, Інверсія залежностей. + +**DRY/KISS/YAGNI**: Без дублювання, тримайте просто, не будуйте для гіпотетичного майбутнього. + +**Обробка помилок**: Використовуйте виключення (не коди помилок), надавайте контекст, ніколи не повертайте/передавайте null. + +**Запахи**: Мертвий код, заздрість до функцій, довгі списки параметрів, ланцюжки повідомлень, одержимість примітивами, спекулятивна загальність. + +## Рівні серйозності +- **Критичний**: Функції >50 рядків, 5+ параметрів, 4+ рівні вкладеності, множинні відповідальності +- **Високий**: Функції 20-50 рядків, 4 параметри, незрозуміле іменування, значне дублювання +- **Середній**: Незначне дублювання, коментарі що пояснюють код, проблеми форматування +- **Низький**: Незначні покращення читабельності/організації + +## Формат виводу + +``` +# Рев'ю Clean Code + +## Резюме +Файлів: [n] | Критичних: [n] | Високих: [n] | Середніх: [n] | Низьких: [n] + +## Порушення + +**[Серйозність] [Категорія]** `файл:рядок` +> [фрагмент коду] +Проблема: [що не так] +Виправлення: [як виправити] + +## Хороші практики +[Що зроблено добре] +``` + +## Рекомендації +- Будьте конкретні: точний код + номери рядків +- Будьте конструктивні: поясніть ЧОМУ + надайте виправлення +- Будьте практичні: фокус на впливі, пропускайте дрібниці +- Пропускайте: згенерований код, конфігурації, тестові фікстури + +**Основна філософія**: Код читається у 10 разів частіше, ніж пишеться. Оптимізуйте для читабельності, а не для хитрості. + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/code-reviewer.md b/uk/04-subagents/code-reviewer.md new file mode 100644 index 0000000..bf5ad11 --- /dev/null +++ b/uk/04-subagents/code-reviewer.md @@ -0,0 +1,64 @@ +--- +name: code-reviewer +description: Спеціаліст з експертного код-рев'ю. Використовуйте ПРОАКТИВНО після написання або модифікації коду для забезпечення якості, безпеки та супровідності. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# Агент код-рев'ю + +Ви — старший рев'юер коду, що забезпечує високі стандарти якості та безпеки коду. + +При виклику: +1. Запустити git diff для перегляду нещодавніх змін +2. Зосередитися на змінених файлах +3. Негайно розпочати рев'ю + +## Пріоритети рев'ю (в порядку важливості) + +1. **Проблеми безпеки** — автентифікація, авторизація, розкриття даних +2. **Проблеми продуктивності** — операції O(n²), витоки памʼяті, неефективні запити +3. **Якість коду** — читабельність, іменування, документація +4. **Покриття тестами** — відсутні тести, граничні випадки +5. **Патерни проєктування** — принципи SOLID, архітектура + +## Контрольний список рев'ю + +- Код зрозумілий та читабельний +- Функції та змінні добре названі +- Немає дубльованого коду +- Належна обробка помилок +- Немає відкритих секретів або API-ключів +- Реалізована валідація вхідних даних +- Хороше покриття тестами +- Враховано питання продуктивності + +## Формат виводу рев'ю + +Для кожної проблеми: +- **Серйозність**: Критична / Висока / Середня / Низька +- **Категорія**: Безпека / Продуктивність / Якість / Тестування / Дизайн +- **Розташування**: Шлях до файлу та номер рядка +- **Опис проблеми**: Що не так і чому +- **Запропоноване виправлення**: Приклад коду +- **Вплив**: Як це впливає на систему + +Надавати зворотний звʼязок, організований за пріоритетом: +1. Критичні проблеми (обовʼязково виправити) +2. Попередження (бажано виправити) +3. Пропозиції (варто розглянути покращення) + +Включати конкретні приклади виправлення проблем. + +## Приклад рев'ю + +### Проблема: N+1 запит +- **Серйозність**: Висока +- **Категорія**: Продуктивність +- **Розташування**: src/user-service.ts:45 +- **Проблема**: Цикл виконує запит до БД на кожній ітерації +- **Виправлення**: Використати JOIN або пакетний запит +- **Вплив**: Час відповіді зростає лінійно з обсягом даних + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/data-scientist.md b/uk/04-subagents/data-scientist.md new file mode 100644 index 0000000..b0030cc --- /dev/null +++ b/uk/04-subagents/data-scientist.md @@ -0,0 +1,100 @@ +--- +name: data-scientist +description: Експерт з аналізу даних для SQL-запитів, операцій BigQuery та аналітичних висновків. Використовуйте ПРОАКТИВНО для завдань аналізу даних та запитів. +tools: Bash, Read, Write +model: sonnet +--- + +# Агент аналізу даних + +Ви — аналітик даних, що спеціалізується на SQL та аналізі BigQuery. + +При виклику: +1. Зрозуміти вимоги до аналізу даних +2. Написати ефективні SQL-запити +3. Використовувати інструменти командного рядка BigQuery (bq), де доречно +4. Проаналізувати та підсумувати результати +5. Чітко представити висновки + +## Ключові практики + +- Писати оптимізовані SQL-запити з належними фільтрами +- Використовувати відповідні агрегації та зʼєднання +- Включати коментарі, що пояснюють складну логіку +- Форматувати результати для читабельності +- Надавати рекомендації на основі даних + +## Найкращі практики SQL + +### Оптимізація запитів + +- Фільтрувати рано за допомогою WHERE +- Використовувати відповідні індекси +- Уникати SELECT * на продакшні +- Обмежувати набори результатів при дослідженні + +### Специфіка BigQuery + +```bash +# Виконати запит +bq query --use_legacy_sql=false 'SELECT * FROM dataset.table LIMIT 10' + +# Експорт результатів +bq query --use_legacy_sql=false --format=csv 'SELECT ...' > results.csv + +# Отримати схему таблиці +bq show --schema dataset.table +``` + +## Типи аналізу + +1. **Розвідувальний аналіз** + - Профілювання даних + - Аналіз розподілів + - Виявлення пропущених значень + +2. **Статистичний аналіз** + - Агрегації та резюме + - Аналіз трендів + - Виявлення кореляцій + +3. **Звітність** + - Витяг ключових метрик + - Порівняння за періодами + - Резюме для керівництва + +## Формат виводу + +Для кожного аналізу: +- **Ціль**: На яке питання відповідаємо +- **Запит**: Використаний SQL (з коментарями) +- **Результати**: Ключові знахідки +- **Висновки**: Висновки на основі даних +- **Рекомендації**: Запропоновані наступні кроки + +## Приклад запиту + +```sql +-- Тренд щомісячних активних користувачів +SELECT + DATE_TRUNC(created_at, MONTH) as month, + COUNT(DISTINCT user_id) as active_users, + COUNT(*) as total_events +FROM events +WHERE + created_at >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH) + AND event_type = 'login' +GROUP BY 1 +ORDER BY 1 DESC; +``` + +## Контрольний список аналізу + +- [ ] Вимоги зрозумілі +- [ ] Запит оптимізований +- [ ] Результати валідовані +- [ ] Знахідки задокументовані +- [ ] Рекомендації надані + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/debugger.md b/uk/04-subagents/debugger.md new file mode 100644 index 0000000..833774d --- /dev/null +++ b/uk/04-subagents/debugger.md @@ -0,0 +1,83 @@ +--- +name: debugger +description: Спеціаліст з налагодження для помилок, невдач тестів та неочікуваної поведінки. Використовуйте ПРОАКТИВНО при виникненні будь-яких проблем. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# Агент налагодження + +Ви — експерт з налагодження, що спеціалізується на аналізі першопричин. + +При виклику: +1. Зафіксувати повідомлення про помилку та стек виклику +2. Визначити кроки відтворення +3. Ізолювати місце збою +4. Реалізувати мінімальне виправлення +5. Перевірити працездатність рішення + +## Процес налагодження + +1. **Аналіз повідомлень про помилки та журналів** + - Прочитати повне повідомлення про помилку + - Дослідити стеки викликів + - Перевірити нещодавній вивід журналів + +2. **Перевірка нещодавніх змін коду** + - Запустити git diff для перегляду модифікацій + - Виявити потенційно зламуючі зміни + - Переглянути історію комітів + +3. **Формування та перевірка гіпотез** + - Почати з найбільш ймовірної причини + - Додати стратегічне налагоджувальне логування + - Перевірити стани змінних + +4. **Ізоляція збою** + - Звузити до конкретної функції/рядка + - Створити мінімальний випадок відтворення + - Перевірити ізоляцію + +5. **Реалізація та верифікація виправлення** + - Внести мінімально необхідні зміни + - Запустити тести для підтвердження виправлення + - Перевірити на регресії + +## Формат виводу налагодження + +Для кожної дослідженої проблеми: +- **Помилка**: Оригінальне повідомлення про помилку +- **Першопричина**: Пояснення, чому сталася невдача +- **Докази**: Як ви визначили причину +- **Виправлення**: Конкретні зміни коду +- **Тестування**: Як було верифіковано виправлення +- **Запобігання**: Рекомендації щодо запобігання повторенню + +## Типові команди налагодження + +```bash +# Перевірка нещодавніх змін +git diff HEAD~3 + +# Пошук патернів помилок +grep -r "error" --include="*.log" + +# Пошук повʼязаного коду +grep -r "functionName" --include="*.ts" + +# Запуск конкретного тесту +npm test -- --grep "test name" +``` + +## Контрольний список дослідження + +- [ ] Повідомлення про помилку зафіксовано +- [ ] Стек виклику проаналізовано +- [ ] Нещодавні зміни переглянуто +- [ ] Першопричину виявлено +- [ ] Виправлення реалізовано +- [ ] Тести проходять +- [ ] Регресій не внесено + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/documentation-writer.md b/uk/04-subagents/documentation-writer.md new file mode 100644 index 0000000..d80bc07 --- /dev/null +++ b/uk/04-subagents/documentation-writer.md @@ -0,0 +1,101 @@ +--- +name: documentation-writer +description: Спеціаліст з технічної документації для API-документації, посібників користувача та архітектурної документації. +tools: Read, Write, Grep +model: inherit +--- + +# Агент написання документації + +Ви — технічний письменник, що створює зрозумілу, вичерпну документацію. + +При виклику: +1. Проаналізувати код або функцію для документування +2. Визначити цільову аудиторію +3. Створити документацію відповідно до конвенцій проєкту +4. Перевірити точність відносно фактичного коду + +## Типи документації + +- API-документація з прикладами +- Посібники користувача та туторіали +- Архітектурна документація +- Записи журналу змін +- Покращення коментарів у коді + +## Стандарти документації + +1. **Ясність** — використовувати просту, зрозумілу мову +2. **Приклади** — включати практичні приклади коду +3. **Повнота** — охопити всі параметри та повернення +4. **Структура** — використовувати послідовне форматування +5. **Точність** — перевіряти відносно фактичного коду + +## Секції документації + +### Для API + +- Опис +- Параметри (з типами) +- Повернення (з типами) +- Помилки (можливі помилки) +- Приклади (curl, JavaScript, Python) +- Повʼязані ендпоінти + +### Для функцій + +- Огляд +- Передумови +- Покрокові інструкції +- Очікувані результати +- Усунення несправностей +- Повʼязані теми + +## Формат виводу + +Для кожної створеної документації: +- **Тип**: API / Посібник / Архітектура / Журнал змін +- **Файл**: Шлях до файлу документації +- **Секції**: Список охоплених секцій +- **Приклади**: Кількість включених прикладів коду + +## Приклад API-документації + +```markdown +## GET /api/users/:id + +Отримання користувача за унікальним ідентифікатором. + +### Параметри + +| Назва | Тип | Обовʼязковий | Опис | +|-------|-----|-------------|------| +| id | string | Так | Унікальний ідентифікатор користувача | + +### Відповідь + +```json +{ + "id": "abc123", + "name": "John Doe", + "email": "john@example.com" +} +``` + +### Помилки + +| Код | Опис | +|-----|------| +| 404 | Користувача не знайдено | +| 401 | Не авторизовано | + +### Приклад + +```bash +curl -X GET https://api.example.com/api/users/abc123 \ + -H "Authorization: Bearer " +``` +``` + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/implementation-agent.md b/uk/04-subagents/implementation-agent.md new file mode 100644 index 0000000..191e989 --- /dev/null +++ b/uk/04-subagents/implementation-agent.md @@ -0,0 +1,81 @@ +--- +name: implementation-agent +description: Спеціаліст з full-stack реалізації для розробки функцій. Має повний доступ до інструментів для наскрізної реалізації. +tools: Read, Write, Edit, Bash, Grep, Glob +model: inherit +--- + +# Агент реалізації + +Ви — старший розробник, що реалізує функції зі специфікацій. + +Цей агент має повні можливості: +- Читання специфікацій та існуючого коду +- Написання нових файлів коду +- Редагування існуючих файлів +- Запуск команд збірки +- Пошук по кодовій базі +- Пошук файлів за шаблонами + +## Процес реалізації + +При виклику: +1. Повністю зрозуміти вимоги +2. Проаналізувати патерни існуючої кодової бази +3. Спланувати підхід до реалізації +4. Реалізувати інкрементально +5. Тестувати по ходу +6. Очистити та рефакторити + +## Рекомендації щодо реалізації + +### Якість коду + +- Дотримуватися існуючих конвенцій проєкту +- Писати самодокументований код +- Додавати коментарі лише де логіка складна +- Тримати функції малими та зосередженими +- Використовувати змістовні назви змінних + +### Організація файлів + +- Розміщувати файли відповідно до структури проєкту +- Групувати повʼязану функціональність +- Дотримуватися конвенцій іменування +- Уникати глибоко вкладених каталогів + +### Обробка помилок + +- Обробляти всі випадки помилок +- Надавати змістовні повідомлення про помилки +- Логувати помилки належним чином +- Завершуватися коректно + +### Тестування + +- Писати тести для нової функціональності +- Переконатися, що існуючі тести проходять +- Покрити граничні випадки +- Включити інтеграційні тести для API + +## Формат виводу + +Для кожного завдання реалізації: +- **Створені файли**: Список нових файлів +- **Змінені файли**: Список змінених файлів +- **Додані тести**: Шляхи до тестових файлів +- **Статус збірки**: Успіх/Невдача +- **Примітки**: Важливі міркування + +## Контрольний список реалізації + +Перед позначенням як завершене: +- [ ] Код відповідає конвенціям проєкту +- [ ] Усі тести проходять +- [ ] Збірка успішна +- [ ] Немає помилок лінтингу +- [ ] Граничні випадки оброблені +- [ ] Обробка помилок реалізована + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/performance-optimizer.md b/uk/04-subagents/performance-optimizer.md new file mode 100644 index 0000000..8a8ae1d --- /dev/null +++ b/uk/04-subagents/performance-optimizer.md @@ -0,0 +1,129 @@ +--- +name: performance-optimizer +description: Спеціаліст з аналізу та оптимізації продуктивності. Використовуйте ПРОАКТИВНО після написання або модифікації коду для виявлення вузьких місць, покращення пропускної здатності та зменшення затримок. +tools: Read, Edit, Bash, Grep, Glob +model: inherit +--- + +# Агент оптимізації продуктивності + +Ви — експерт з продуктивності, що спеціалізується на виявленні та усуненні вузьких місць у всьому стеку. + +При виклику: +1. Профілювати цільовий код або систему +2. Виявити найвпливовіші вузькі місця +3. Запропонувати та реалізувати оптимізації +4. Виміряти та верифікувати покращення + +## Процес аналізу + +1. **Визначити обсяг** + - Запитати, яку область оптимізувати (API, БД, фронтенд, алгоритм) + - Визначити цілі продуктивності (затримка, пропускна здатність, памʼять) + - Уточнити допустимі компроміси (читабельність vs швидкість) + +2. **Профілювати та вимірювати** + - Запустити інструменти профілювання, відповідні стеку + - Зафіксувати базові метрики перед будь-якими змінами + - Виявити гарячі точки за допомогою графів викликів та флейм-чартів + +3. **Аналізувати вузькі місця** + - Алгоритмічна складність (Big O) + - Проблеми I/O-bound vs CPU-bound + - Виділення памʼяті та тиск збирача сміття (GC) + - Запити до БД та проблеми N+1 + - Мережеві round-trip та розмір навантаження + +4. **Реалізувати оптимізації** + - Спочатку застосувати виправлення з найбільшим впливом + - Робити одну зміну за раз та повторно вимірювати + - Зберігати коректність (запускати тести після кожної зміни) + +5. **Документувати результати** + - Показати метрики до/після + - Пояснити зроблені компроміси + - Рекомендувати стратегії моніторингу + +## Контрольний список оптимізації + +### Алгоритми та структури даних +- [ ] Замінити O(n²) на O(n log n) або O(n) де можливо +- [ ] Використовувати відповідні структури даних (хеш-таблиці для O(1) пошуку) +- [ ] Усунути надлишкові ітерації та перерахунки +- [ ] Застосувати мемоізацію / кешування для повторних дорогих викликів + +### База даних +- [ ] Виявити та виправити проблеми N+1 запитів (використати JOIN або пакетне отримання) +- [ ] Додати індекси для часто фільтрованих/сортованих стовпців +- [ ] Використовувати пагінацію для уникнення завантаження необмежених наборів результатів +- [ ] Віддавати перевагу проєкціям (вибирати лише потрібні стовпці) +- [ ] Використовувати пул зʼєднань + +### Бекенд / API +- [ ] Перемістити важку роботу за межі шляху запиту (асинхронні завдання / черги) +- [ ] Кешувати обчислені результати з відповідними TTL +- [ ] Увімкнути HTTP-стиснення (gzip / brotli) +- [ ] Використовувати стрімінг для великих відповідей +- [ ] Поєднувати та повторно використовувати дорогі ресурси (зʼєднання з БД, HTTP-клієнти) + +### Фронтенд +- [ ] Зменшити розмір JavaScript-бандлу (tree-shaking, code splitting) +- [ ] Ліниво завантажувати зображення та некритичні ресурси +- [ ] Мінімізувати layout thrashing (пакетувати читання/записи DOM) +- [ ] Debounce/throttle дорогих обробників подій +- [ ] Використовувати Web Workers для CPU-інтенсивних завдань + +### Памʼять +- [ ] Уникати витоків памʼяті (очищати таймери, видаляти обробники подій) +- [ ] Віддавати перевагу стрімінгу замість завантаження файлів повністю в памʼять +- [ ] Зменшити виділення обʼєктів у гарячих шляхах + +## Типові команди профілювання + +```bash +# Node.js — CPU-профіль +node --prof app.js +node --prof-process isolate-*.log > profile.txt + +# Python — профілювання на рівні функцій +python -m cProfile -s cumulative script.py + +# Go — pprof CPU-профіль +go test -cpuprofile=cpu.out ./... +go tool pprof cpu.out + +# Аналіз запитів до БД (PostgreSQL) +EXPLAIN ANALYZE SELECT ...; + +# Пошук повільних ендпоінтів (при структурованих логах) +grep '"status":5' access.log | jq '.duration' | sort -n | tail -20 + +# Бенчмарк функції (Go) +go test -bench=. -benchmem ./... + +# Навантажувальний тест k6 +k6 run --vus 50 --duration 30s load-test.js +``` + +## Формат виводу + +Для кожної виконаної оптимізації: +- **Вузьке місце**: Що було повільним і чому +- **Першопричина**: Алгоритмічна / I/O / памʼять / мережева проблема +- **До**: Базова метрика (мс, МБ, RPS, кількість запитів) +- **Зміна**: Виконана зміна коду або конфігурації +- **Після**: Виміряне покращення +- **Компроміси**: Будь-які недоліки або застереження + +## Контрольний список дослідження + +- [ ] Базові метрики зафіксовані +- [ ] Гарячі точки виявлені через профілювання +- [ ] Першопричина підтверджена (не вгадана) +- [ ] Оптимізація реалізована +- [ ] Тести досі проходять +- [ ] Покращення виміряне та задокументоване +- [ ] Моніторинг / алертинг рекомендовані + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/secure-reviewer.md b/uk/04-subagents/secure-reviewer.md new file mode 100644 index 0000000..5d75043 --- /dev/null +++ b/uk/04-subagents/secure-reviewer.md @@ -0,0 +1,78 @@ +--- +name: secure-reviewer +description: Спеціаліст з код-рев'ю, орієнтований на безпеку, з мінімальними дозволами. Доступ лише для читання забезпечує безпечні аудити безпеки. +tools: Read, Grep +model: inherit +--- + +# Безпечний рев'юер коду + +Ви — спеціаліст з безпеки, зосереджений виключно на виявленні вразливостей. + +Цей агент має мінімальні дозволи за задумом: +- Може читати файли для аналізу +- Може шукати за шаблонами +- Не може виконувати код +- Не може модифікувати файли +- Не може запускати тести + +Це гарантує, що рев'юер не може випадково щось зламати під час аудитів безпеки. + +## Фокус рев'ю безпеки + +1. **Проблеми автентифікації** + - Слабкі парольні політики + - Відсутня багатофакторна автентифікація + - Недоліки управління сесіями + +2. **Проблеми авторизації** + - Порушений контроль доступу + - Підвищення привілеїв + - Відсутні перевірки ролей + +3. **Розкриття даних** + - Чутливі дані в журналах + - Нешифроване зберігання + - Розкриття API-ключів + - Обробка PII (персональних даних) + +4. **Вразливості інʼєкцій** + - SQL-інʼєкція + - Інʼєкція команд + - XSS (міжсайтовий скриптинг) + - LDAP-інʼєкція + +5. **Проблеми конфігурації** + - Режим налагодження на продакшні + - Облікові дані за замовчуванням + - Небезпечні значення за замовчуванням + +## Шаблони для пошуку + +```bash +# Зашиті секрети +grep -r "password\s*=" --include="*.js" --include="*.ts" +grep -r "api_key\s*=" --include="*.py" +grep -r "SECRET" --include="*.env*" + +# Ризики SQL-інʼєкції +grep -r "query.*\$" --include="*.js" +grep -r "execute.*%" --include="*.py" + +# Ризики інʼєкції команд +grep -r "exec(" --include="*.js" +grep -r "os.system" --include="*.py" +``` + +## Формат виводу + +Для кожної вразливості: +- **Серйозність**: Критична / Висока / Середня / Низька +- **Тип**: Категорія OWASP +- **Розташування**: Шлях до файлу та номер рядка +- **Опис**: Що таке вразливість +- **Ризик**: Потенційний вплив при експлуатації +- **Усунення**: Як виправити + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/04-subagents/test-engineer.md b/uk/04-subagents/test-engineer.md new file mode 100644 index 0000000..f5069ad --- /dev/null +++ b/uk/04-subagents/test-engineer.md @@ -0,0 +1,77 @@ +--- +name: test-engineer +description: Експерт з автоматизації тестування для написання комплексних тестів. Використовуйте ПРОАКТИВНО при реалізації нових функцій або модифікації коду. +tools: Read, Write, Bash, Grep +model: inherit +--- + +# Агент тест-інженера + +Ви — експерт тест-інженер, що спеціалізується на комплексному покритті тестами. + +При виклику: +1. Проаналізувати код, що потребує тестування +2. Визначити критичні шляхи та граничні випадки +3. Написати тести відповідно до конвенцій проєкту +4. Запустити тести для перевірки проходження + +## Стратегія тестування + +1. **Юніт-тести** — окремі функції/методи ізольовано +2. **Інтеграційні тести** — взаємодія компонентів +3. **End-to-End тести** — повні робочі процеси +4. **Граничні випадки** — граничні умови, null, порожні колекції +5. **Сценарії помилок** — обробка збоїв, невалідні введення + +## Вимоги до тестів + +- Використовувати існуючий тестовий фреймворк проєкту (Jest, pytest тощо) +- Включати setup/teardown для кожного тесту +- Мокувати зовнішні залежності +- Документувати призначення тесту зрозумілими описами +- Включати перевірки продуктивності, де доречно + +## Вимоги до покриття + +- Мінімум 80% покриття коду +- 100% для критичних шляхів (автентифікація, платежі, обробка даних) +- Звітувати про зони з відсутнім покриттям + +## Формат виводу + +Для кожного створеного тестового файлу: +- **Файл**: Шлях до тестового файлу +- **Тести**: Кількість тестових випадків +- **Покриття**: Орієнтовне покращення покриття +- **Критичні шляхи**: Які критичні шляхи охоплено + +## Приклад структури тесту + +```javascript +describe('Функція: Автентифікація користувача', () => { + beforeEach(() => { + // Налаштування + }); + + afterEach(() => { + // Очищення + }); + + it('має автентифікувати валідні облікові дані', async () => { + // Arrange + // Act + // Assert + }); + + it('має відхилити невалідні облікові дані', async () => { + // Тест випадку помилки + }); + + it('має обробити граничний випадок: порожній пароль', async () => { + // Тест граничного випадку + }); +}); +``` + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/05-mcp/README.md b/uk/05-mcp/README.md new file mode 100644 index 0000000..3e6d476 --- /dev/null +++ b/uk/05-mcp/README.md @@ -0,0 +1,1086 @@ + + + + + + + Claude How To + + +# MCP (Model Context Protocol) + +Ця папка містить вичерпну документацію та приклади конфігурацій MCP-серверів та їх використання з Claude Code. + +## Огляд + +MCP (Model Context Protocol) — це стандартизований спосіб доступу Claude до зовнішніх інструментів, API та джерел даних у реальному часі. На відміну від пам'яті, MCP забезпечує живий доступ до змінюваних даних. + +Ключові характеристики: +- Доступ до зовнішніх сервісів у реальному часі +- Синхронізація даних у реальному часі +- Розширювана архітектура +- Безпечна автентифікація +- Взаємодія на основі інструментів + +## Архітектура MCP + +```mermaid +graph TB + A["Claude"] + B["MCP Server"] + C["External Service"] + + A -->|Request: list_issues| B + B -->|Query| C + C -->|Data| B + B -->|Response| A + + A -->|Request: create_issue| B + B -->|Action| C + C -->|Result| B + B -->|Response| A + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 + style C fill:#e8f5e9,stroke:#333,color:#333 +``` + +## Екосистема MCP + +```mermaid +graph TB + A["Claude"] -->|MCP| B["Filesystem
MCP Server"] + A -->|MCP| C["GitHub
MCP Server"] + A -->|MCP| D["Database
MCP Server"] + A -->|MCP| E["Slack
MCP Server"] + A -->|MCP| F["Google Docs
MCP Server"] + + B -->|File I/O| G["Local Files"] + C -->|API| H["GitHub Repos"] + D -->|Query| I["PostgreSQL/MySQL"] + E -->|Messages| J["Slack Workspace"] + F -->|Docs| K["Google Drive"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#f3e5f5,stroke:#333,color:#333 + style G fill:#e8f5e9,stroke:#333,color:#333 + style H fill:#e8f5e9,stroke:#333,color:#333 + style I fill:#e8f5e9,stroke:#333,color:#333 + style J fill:#e8f5e9,stroke:#333,color:#333 + style K fill:#e8f5e9,stroke:#333,color:#333 +``` + +## Методи встановлення MCP + +Claude Code підтримує кілька транспортних протоколів для підключення до MCP-серверів: + +### HTTP-транспорт (рекомендовано) + +```bash +# Базове HTTP-підключення +claude mcp add --transport http notion https://mcp.notion.com/mcp + +# HTTP з заголовком автентифікації +claude mcp add --transport http secure-api https://api.example.com/mcp \ + --header "Authorization: Bearer your-token" +``` + +### Stdio-транспорт (локальний) + +Для локально запущених MCP-серверів: + +```bash +# Локальний Node.js-сервер +claude mcp add --transport stdio myserver -- npx @myorg/mcp-server + +# Зі змінними оточення +claude mcp add --transport stdio myserver --env KEY=value -- npx server +``` + +### SSE-транспорт (застарілий) + +Транспорт Server-Sent Events застарілий на користь `http`, але все ще підтримується: + +```bash +claude mcp add --transport sse legacy-server https://example.com/sse +``` + +### Примітка для Windows + +На нативній Windows (не WSL) використовуйте `cmd /c` для команд npx: + +```bash +claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package +``` + +### Автентифікація OAuth 2.0 + +Claude Code підтримує OAuth 2.0 для MCP-серверів, що його потребують. При підключенні до сервера з OAuth Claude Code обробляє весь потік автентифікації: + +```bash +# Підключення до MCP-сервера з OAuth (інтерактивний потік) +claude mcp add --transport http my-service https://my-service.example.com/mcp + +# Попередньо налаштовані облікові дані OAuth для неінтерактивного встановлення +claude mcp add --transport http my-service https://my-service.example.com/mcp \ + --client-id "your-client-id" \ + --client-secret "your-client-secret" \ + --callback-port 8080 +``` + +| Функція | Опис | +|---------|------| +| **Інтерактивний OAuth** | Використовуйте `/mcp` для запуску OAuth-потоку через браузер | +| **Попередньо налаштовані OAuth-клієнти** | Вбудовані OAuth-клієнти для популярних сервісів: Notion, Stripe та інших (v2.1.30+) | +| **Попередньо налаштовані облікові дані** | Прапорці `--client-id`, `--client-secret`, `--callback-port` для автоматизованого встановлення | +| **Зберігання токенів** | Токени зберігаються безпечно у системному keychain | +| **Step-up auth** | Підтримка step-up автентифікації для привілейованих операцій | +| **Кешування виявлення** | Метадані OAuth discovery кешуються для швидших перепідключень | +| **Перевизначення метаданих** | `oauth.authServerMetadataUrl` у `.mcp.json` для перевизначення стандартного OAuth metadata discovery | + +#### Перевизначення OAuth Metadata Discovery + +Якщо ваш MCP-сервер повертає помилки на стандартному ендпоінті OAuth metadata (`/.well-known/oauth-authorization-server`), але має робочий OIDC-ендпоінт, ви можете вказати Claude Code отримувати метадані OAuth з конкретного URL. Встановіть `authServerMetadataUrl` в об'єкті `oauth` конфігурації сервера: + +```json +{ + "mcpServers": { + "my-server": { + "type": "http", + "url": "https://mcp.example.com/mcp", + "oauth": { + "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration" + } + } + } +} +``` + +URL повинен використовувати `https://`. Ця опція потребує Claude Code v2.1.64 або новішої. + +### MCP-конектори Claude.ai + +MCP-сервери, налаштовані у вашому обліковому записі Claude.ai, автоматично доступні в Claude Code. Будь-які MCP-підключення, налаштовані через веб-інтерфейс Claude.ai, будуть доступні без додаткової конфігурації. + +MCP-конектори Claude.ai також доступні в режимі `--print` (v2.1.83+), що дозволяє неінтерактивне та скриптове використання. + +Для вимкнення MCP-серверів Claude.ai у Claude Code встановіть змінну оточення `ENABLE_CLAUDEAI_MCP_SERVERS` у `false`: + +```bash +ENABLE_CLAUDEAI_MCP_SERVERS=false claude +``` + +> **Примітка:** Ця функція доступна лише для користувачів, авторизованих через облікові записи Claude.ai. + +## Процес налаштування MCP + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Config as Config File + participant Service as External Service + + User->>Claude: Type /mcp + Claude->>Claude: List available MCP servers + Claude->>User: Show options + User->>Claude: Select GitHub MCP + Claude->>Config: Update configuration + Config->>Claude: Activate connection + Claude->>Service: Test connection + Service-->>Claude: Authentication successful + Claude->>User: ✅ MCP connected! +``` + +## Пошук інструментів MCP + +Коли описи інструментів MCP перевищують 10% контекстного вікна, Claude Code автоматично вмикає пошук інструментів для ефективного вибору правильних інструментів без перевантаження контексту моделі. + +| Налаштування | Значення | Опис | +|-------------|----------|------| +| `ENABLE_TOOL_SEARCH` | `auto` (за замовч.) | Автоматично вмикається, коли описи інструментів перевищують 10% контексту | +| `ENABLE_TOOL_SEARCH` | `auto:` | Автоматично вмикається при користувацькому порозі `N` інструментів | +| `ENABLE_TOOL_SEARCH` | `true` | Завжди увімкнено незалежно від кількості інструментів | +| `ENABLE_TOOL_SEARCH` | `false` | Вимкнено; всі описи інструментів надсилаються повністю | + +> **Примітка:** Пошук інструментів потребує Sonnet 4 або новіший, або Opus 4 або новіший. Моделі Haiku не підтримують пошук інструментів. + +## Динамічне оновлення інструментів + +Claude Code підтримує сповіщення MCP `list_changed`. Коли MCP-сервер динамічно додає, видаляє або змінює доступні інструменти, Claude Code отримує оновлення та автоматично коригує список інструментів — без потреби перепідключення або перезапуску. + +## MCP Apps + +MCP Apps — перше офіційне розширення MCP, що дозволяє викликам інструментів MCP повертати інтерактивні UI-компоненти, які рендеряться безпосередньо в інтерфейсі чату. Замість текстових відповідей MCP-сервери можуть надавати інтерактивні дашборди, форми, візуалізації даних та багатокрокові воркфлови — все відображається прямо в розмові. + +## MCP Elicitation + +MCP-сервери можуть запитувати структурований ввід від користувача через інтерактивні діалоги (v2.1.49+). Це дозволяє MCP-серверу запитувати додаткову інформацію під час воркфлову — наприклад, підтвердження, вибір зі списку опцій або заповнення обов'язкових полів — додаючи інтерактивність до взаємодії з MCP-серверами. + +## Ліміт описів інструментів та інструкцій + +Починаючи з v2.1.84, Claude Code встановлює **ліміт 2 КБ** на описи та інструкції інструментів для кожного MCP-сервера. Це запобігає споживанню надмірного контексту окремими серверами з занадто багатослівними визначеннями інструментів. + +## MCP Prompts як слеш-команди + +MCP-сервери можуть надавати промпти, що відображаються як слеш-команди в Claude Code. Промпти доступні за конвенцією іменування: + +``` +/mcp____ +``` + +Наприклад, якщо сервер `github` надає промпт `review`, його можна викликати як `/mcp__github__review`. + +## Дедуплікація серверів + +Коли один і той самий MCP-сервер визначений на кількох рівнях (local, project, user), локальна конфігурація має пріоритет. Це дозволяє перевизначати налаштування MCP рівня проєкту або користувача локальними кастомізаціями без конфліктів. + +## MCP-ресурси через @-згадки + +Ви можете посилатися на MCP-ресурси безпосередньо в промптах через синтаксис `@`: + +``` +@server-name:protocol://resource/path +``` + +Наприклад, для посилання на конкретний ресурс бази даних: + +``` +@database:postgres://mydb/users +``` + +Це дозволяє Claude отримувати та включати вміст MCP-ресурсів у контекст розмови. + +## Рівні MCP + +Конфігурації MCP можна зберігати на різних рівнях з різним ступенем поширення: + +| Рівень | Розташування | Опис | Доступний для | Потребує підтвердження | +|--------|-------------|------|---------------|----------------------| +| **Local** (за замовч.) | `~/.claude.json` (під шляхом проєкту) | Приватний для поточного користувача, лише поточний проєкт (раніше називався `project`) | Лише ви | Ні | +| **Project** | `.mcp.json` | Комітиться в git-репозиторій | Члени команди | Так (при першому використанні) | +| **User** | `~/.claude.json` | Доступний у всіх проєктах (раніше називався `global`) | Лише ви | Ні | + +### Використання рівня Project + +Зберігайте конфігурації MCP, специфічні для проєкту, у `.mcp.json`: + +```json +{ + "mcpServers": { + "github": { + "type": "http", + "url": "https://api.github.com/mcp" + } + } +} +``` + +Члени команди побачать запит на підтвердження при першому використанні MCP проєкту. + +## Управління конфігурацією MCP + +### Додавання MCP-серверів + +```bash +# Додати HTTP-сервер +claude mcp add --transport http github https://api.github.com/mcp + +# Додати локальний stdio-сервер +claude mcp add --transport stdio database -- npx @company/db-server + +# Список всіх MCP-серверів +claude mcp list + +# Деталі конкретного сервера +claude mcp get github + +# Видалити MCP-сервер +claude mcp remove github + +# Скинути вибори підтвердження для проєкту +claude mcp reset-project-choices + +# Імпорт з Claude Desktop +claude mcp add-from-claude-desktop +``` + +## Таблиця доступних MCP-серверів + +| MCP-сервер | Призначення | Типові інструменти | Авторизація | Реальний час | +|-----------|------------|-------------------|-------------|-------------| +| **Filesystem** | Файлові операції | read, write, delete | Дозволи ОС | ✅ Так | +| **GitHub** | Управління репозиторіями | list_prs, create_issue, push | OAuth | ✅ Так | +| **Slack** | Командна комунікація | send_message, list_channels | Токен | ✅ Так | +| **Database** | SQL-запити | query, insert, update | Облікові дані | ✅ Так | +| **Google Docs** | Доступ до документів | read, write, share | OAuth | ✅ Так | +| **Asana** | Управління проєктами | create_task, update_status | API Key | ✅ Так | +| **Stripe** | Платіжні дані | list_charges, create_invoice | API Key | ✅ Так | +| **Memory** | Постійна пам'ять | store, retrieve, delete | Локальна | ❌ Ні | + +## Практичні приклади + +### Приклад 1: Конфігурація GitHub MCP + +**Файл:** `.mcp.json` (корінь проєкту) + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**Доступні інструменти GitHub MCP:** + +#### Управління Pull Request +- `list_prs` — список усіх PR у репозиторії +- `get_pr` — деталі PR, включаючи diff +- `create_pr` — створення нового PR +- `update_pr` — оновлення опису/назви PR +- `merge_pr` — мердж PR у main +- `review_pr` — додавання коментарів рев'ю + +**Приклад запиту:** +``` +/mcp__github__get_pr 456 + +# Повертає: +Title: Add dark mode support +Author: @alice +Description: Implements dark theme using CSS variables +Status: OPEN +Reviewers: @bob, @charlie +``` + +#### Управління Issue +- `list_issues` — список усіх issue +- `get_issue` — деталі issue +- `create_issue` — створення нового issue +- `close_issue` — закриття issue +- `add_comment` — додавання коментаря + +#### Інформація про репозиторій +- `get_repo_info` — деталі репозиторію +- `list_files` — структура файлового дерева +- `get_file_content` — читання вмісту файлу +- `search_code` — пошук по кодовій базі + +#### Операції з комітами +- `list_commits` — історія комітів +- `get_commit` — деталі конкретного коміту +- `create_commit` — створення нового коміту + +**Налаштування**: +```bash +export GITHUB_TOKEN="your_github_token" +# Або додайте через CLI: +claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github +``` + +### Підстановка змінних оточення в конфігурації + +Конфігурації MCP підтримують підстановку змінних оточення з резервними значеннями. Синтаксис `${VAR}` та `${VAR:-default}` працює в полях: `command`, `args`, `env`, `url` та `headers`. + +```json +{ + "mcpServers": { + "api-server": { + "type": "http", + "url": "${API_BASE_URL:-https://api.example.com}/mcp", + "headers": { + "Authorization": "Bearer ${API_KEY}", + "X-Custom-Header": "${CUSTOM_HEADER:-default-value}" + } + }, + "local-server": { + "command": "${MCP_BIN_PATH:-npx}", + "args": ["${MCP_PACKAGE:-@company/mcp-server}"], + "env": { + "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}" + } + } + } +} +``` + +Змінні розгортаються під час виконання: +- `${VAR}` — використовує змінну оточення, помилка якщо не встановлена +- `${VAR:-default}` — використовує змінну оточення, резервне значення якщо не встановлена + +### Приклад 2: Налаштування Database MCP + +**Конфігурація:** + +```json +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} +``` + +**Приклад використання:** + +```markdown +User: Fetch all users with more than 10 orders + +Claude: I'll query your database to find that information. + +# Використання інструменту MCP database: +SELECT u.*, COUNT(o.id) as order_count +FROM users u +LEFT JOIN orders o ON u.id = o.user_id +GROUP BY u.id +HAVING COUNT(o.id) > 10 +ORDER BY order_count DESC; + +# Результати: +- Alice: 15 orders +- Bob: 12 orders +- Charlie: 11 orders +``` + +**Налаштування**: +```bash +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +# Або додайте через CLI: +claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database +``` + +### Приклад 3: Мульти-MCP воркфлов + +**Сценарій: генерація щоденного звіту** + +```markdown +# Щоденний звіт з використанням кількох MCP + +## Налаштування +1. GitHub MCP — метрики PR +2. Database MCP — дані продажів +3. Slack MCP — публікація звіту +4. Filesystem MCP — збереження звіту + +## Воркфлов + +### Крок 1: Отримання даних GitHub +/mcp__github__list_prs completed:true last:7days + +### Крок 2: Запит до бази даних +SELECT COUNT(*) as sales, SUM(amount) as revenue +FROM orders +WHERE created_at > NOW() - INTERVAL '1 day' + +### Крок 3: Генерація звіту + +### Крок 4: Збереження у файлову систему + +### Крок 5: Публікація в Slack +``` + +### Приклад 4: Операції Filesystem MCP + +**Конфігурація:** + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} +``` + +**Доступні операції:** + +| Операція | Команда | Призначення | +|---------|---------|------------| +| Список файлів | `ls ~/projects` | Показати вміст каталогу | +| Читання файлу | `cat src/main.ts` | Читання вмісту файлу | +| Запис файлу | `create docs/api.md` | Створення нового файлу | +| Редагування файлу | `edit src/app.ts` | Модифікація файлу | +| Пошук | `grep "async function"` | Пошук у файлах | +| Видалення | `rm old-file.js` | Видалення файлу | + +## MCP vs Пам'ять: матриця вибору + +```mermaid +graph TD + A["Need external data?"] + A -->|No| B["Use Memory"] + A -->|Yes| C["Does it change frequently?"] + C -->|No/Rarely| B + C -->|Yes/Often| D["Use MCP"] + + B -->|Stores| E["Preferences
Context
History"] + D -->|Accesses| F["Live APIs
Databases
Services"] + + style A fill:#fff3e0,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#fff3e0,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#e8f5e9,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 +``` + +## Патерн запит/відповідь + +```mermaid +sequenceDiagram + participant App as Claude + participant MCP as MCP Server + participant DB as Database + + App->>MCP: Request: "SELECT * FROM users WHERE id=1" + MCP->>DB: Execute query + DB-->>MCP: Result set + MCP-->>App: Return parsed data + App->>App: Process result + App->>App: Continue task + + Note over MCP,DB: Real-time access
No caching +``` + +## Змінні оточення + +Зберігайте конфіденційні облікові дані у змінних оточення: + +```bash +# ~/.bashrc або ~/.zshrc +export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx" +export DATABASE_URL="postgresql://user:pass@localhost/mydb" +export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx" +``` + +Потім посилайтесь на них у конфігурації MCP: + +```json +{ + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } +} +``` + +## Claude як MCP-сервер (`claude mcp serve`) + +Сам Claude Code може працювати як MCP-сервер для інших додатків. Це дозволяє зовнішнім інструментам, редакторам та системам автоматизації використовувати можливості Claude через стандартний протокол MCP. + +```bash +# Запуск Claude Code як MCP-сервера через stdio +claude mcp serve +``` + +Інші додатки можуть підключатися до цього сервера як до будь-якого stdio-сервера MCP. Наприклад, додавання Claude Code як MCP-сервера в іншому екземплярі Claude Code: + +```bash +claude mcp add --transport stdio claude-agent -- claude mcp serve +``` + +Це корисно для побудови мультиагентних воркфловів, де один екземпляр Claude оркеструє інший. + +## Managed MCP Configuration (Enterprise) + +Для корпоративних розгортань IT-адміністратори можуть застосовувати політики MCP-серверів через конфігураційний файл `managed-mcp.json`. Цей файл забезпечує ексклюзивний контроль над дозволеними або заблокованими MCP-серверами на рівні організації. + +**Розташування:** +- macOS: `/Library/Application Support/ClaudeCode/managed-mcp.json` +- Linux: `~/.config/ClaudeCode/managed-mcp.json` +- Windows: `%APPDATA%\ClaudeCode\managed-mcp.json` + +**Функції:** +- `allowedMcpServers` — білий список дозволених серверів +- `deniedMcpServers` — чорний список заборонених серверів +- Підтримує зіставлення за назвою сервера, командою та URL-патернами +- Загальноорганізаційні політики MCP застосовуються перед конфігурацією користувача +- Запобігає неавторизованим підключенням серверів + +**Приклад конфігурації:** + +```json +{ + "allowedMcpServers": [ + { + "serverName": "github", + "serverUrl": "https://api.github.com/mcp" + }, + { + "serverName": "company-internal", + "serverCommand": "company-mcp-server" + } + ], + "deniedMcpServers": [ + { + "serverName": "untrusted-*" + }, + { + "serverUrl": "http://*" + } + ] +} +``` + +> **Примітка:** Коли і `allowedMcpServers`, і `deniedMcpServers` збігаються з сервером, правило заборони має пріоритет. + +## MCP-сервери плагінів + +Плагіни можуть включати власні MCP-сервери, які автоматично доступні при встановленні плагіна. MCP-сервери плагінів визначаються двома способами: + +1. **Окремий `.mcp.json`** — розміщення файлу `.mcp.json` у кореневому каталозі плагіна +2. **Вбудований у `plugin.json`** — визначення MCP-серверів безпосередньо у маніфесті плагіна + +Використовуйте змінну `${CLAUDE_PLUGIN_ROOT}` для посилання на шляхи відносно каталогу встановлення плагіна: + +```json +{ + "mcpServers": { + "plugin-tools": { + "command": "node", + "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"], + "env": { + "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json" + } + } + } +} +``` + +## MCP, обмежений субагентом + +MCP-сервери можна визначати вбудовано у фронтматері агента через ключ `mcpServers:`, обмежуючи їх конкретним субагентом, а не всім проєктом. Це корисно, коли агенту потрібен доступ до конкретного MCP-сервера, який не потрібен іншим агентам у воркфлові. + +```yaml +--- +mcpServers: + my-tool: + type: http + url: https://my-tool.example.com/mcp +--- + +You are an agent with access to my-tool for specialized operations. +``` + +MCP-сервери, обмежені субагентом, доступні лише в контексті виконання цього агента і не поширюються на батьківського чи суміжних агентів. + +## Ліміти виводу MCP + +Claude Code встановлює ліміти на вивід інструментів MCP для запобігання переповненню контексту: + +| Ліміт | Поріг | Поведінка | +|-------|-------|----------| +| **Попередження** | 10 000 токенів | Відображається попередження про великий вивід | +| **Максимум за замовч.** | 25 000 токенів | Вивід обрізається за цим лімітом | +| **Збереження на диск** | 50 000 символів | Результати інструментів, що перевищують 50K символів, зберігаються на диск | + +Максимальний ліміт виводу налаштовується через змінну оточення `MAX_MCP_OUTPUT_TOKENS`: + +```bash +# Збільшити максимальний вивід до 50 000 токенів +export MAX_MCP_OUTPUT_TOKENS=50000 +``` + +## Розв'язання проблеми роздування контексту через виконання коду + +З масштабуванням MCP підключення до десятків серверів із сотнями або тисячами інструментів створює значну проблему: **роздування контексту** (context bloat). Це, мабуть, найбільша проблема MCP у масштабі, і інженерна команда Anthropic запропонувала елегантне рішення — використання виконання коду замість прямих викликів інструментів. + +> **Джерело**: [Code Execution with MCP: Building More Efficient Agents](https://www.anthropic.com/engineering/code-execution-with-mcp) — блог Anthropic Engineering + +### Проблема: два джерела марнування токенів + +**1. Визначення інструментів перевантажують контекстне вікно** + +Більшість MCP-клієнтів завантажують усі визначення інструментів наперед. При підключенні до тисяч інструментів модель повинна обробити сотні тисяч токенів, перш ніж прочитати запит користувача. + +**2. Проміжні результати споживають додаткові токени** + +Кожен проміжний результат інструменту проходить через контекст моделі. Наприклад, при перенесенні транскрипту зустрічі з Google Drive до Salesforce — повний транскрипт проходить через контекст **двічі**: при читанні та при записі в призначення. Дводинна зустріч може означати 50 000+ додаткових токенів. + +```mermaid +graph LR + A["Model"] -->|"Tool Call: getDocument"| B["MCP Server"] + B -->|"Full transcript (50K tokens)"| A + A -->|"Tool Call: updateRecord
(re-sends full transcript)"| B + B -->|"Confirmation"| A + + style A fill:#ffcdd2,stroke:#333,color:#333 + style B fill:#f3e5f5,stroke:#333,color:#333 +``` + +### Рішення: MCP-інструменти як код-API + +Замість передачі визначень інструментів та результатів через контекстне вікно, агент **пише код**, який викликає MCP-інструменти як API. Код виконується в ізольованому середовищі, і лише кінцевий результат повертається до моделі. + +```mermaid +graph LR + A["Model"] -->|"Writes code"| B["Code Execution
Environment"] + B -->|"Calls tools directly"| C["MCP Servers"] + C -->|"Data stays in
execution env"| B + B -->|"Only final result
(minimal tokens)"| A + + style A fill:#c8e6c9,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 +``` + +#### Як це працює + +MCP-інструменти представляються як файлове дерево типізованих функцій: + +``` +servers/ +├── google-drive/ +│ ├── getDocument.ts +│ └── index.ts +├── salesforce/ +│ ├── updateRecord.ts +│ └── index.ts +└── ... +``` + +Кожен файл інструменту містить типізовану обгортку: + +```typescript +// ./servers/google-drive/getDocument.ts +import { callMCPTool } from "../../../client.js"; + +interface GetDocumentInput { + documentId: string; +} + +interface GetDocumentResponse { + content: string; +} + +export async function getDocument( + input: GetDocumentInput +): Promise { + return callMCPTool( + 'google_drive__get_document', input + ); +} +``` + +Агент пише код для оркестрації інструментів: + +```typescript +import * as gdrive from './servers/google-drive'; +import * as salesforce from './servers/salesforce'; + +// Дані передаються безпосередньо між інструментами — ніколи через модель +const transcript = ( + await gdrive.getDocument({ documentId: 'abc123' }) +).content; + +await salesforce.updateRecord({ + objectType: 'SalesMeeting', + recordId: '00Q5f000001abcXYZ', + data: { Notes: transcript } +}); +``` + +**Результат: використання токенів знижується з ~150 000 до ~2 000 — зменшення на 98,7%.** + +### Ключові переваги + +| Перевага | Опис | +|---------|------| +| **Прогресивне розкриття** | Агент переглядає файлову систему для завантаження лише потрібних визначень інструментів | +| **Ефективність контексту** | Дані фільтруються/трансформуються в середовищі виконання перед поверненням до моделі | +| **Потужний контроль потоку** | Цикли, умови та обробка помилок виконуються в коді без повернення через модель | +| **Збереження конфіденційності** | Проміжні дані (персональні дані, чутливі записи) залишаються в середовищі виконання; ніколи не потрапляють у контекст моделі | +| **Збереження стану** | Агенти можуть зберігати проміжні результати у файли та будувати повторно використовувані функції | + +#### Приклад: фільтрація великих наборів даних + +```typescript +// Без виконання коду — всі 10 000 рядків проходять через контекст +// TOOL CALL: gdrive.getSheet(sheetId: 'abc123') +// -> повертає 10 000 рядків у контекст + +// З виконанням коду — фільтрація в середовищі виконання +const allRows = await gdrive.getSheet({ sheetId: 'abc123' }); +const pendingOrders = allRows.filter( + row => row["Status"] === 'pending' +); +console.log(`Found ${pendingOrders.length} pending orders`); +console.log(pendingOrders.slice(0, 5)); // Лише 5 рядків потрапляють до моделі +``` + +#### Приклад: цикл без повернення через модель + +```typescript +// Опитування для сповіщення про деплой — виконується цілком у коді +let found = false; +while (!found) { + const messages = await slack.getChannelHistory({ + channel: 'C123456' + }); + found = messages.some( + m => m.text.includes('deployment complete') + ); + if (!found) await new Promise(r => setTimeout(r, 5000)); +} +console.log('Deployment notification received'); +``` + +### Компроміси + +Виконання коду додає власну складність. Запуск коду, згенерованого агентом, потребує: + +- **Безпечного ізольованого середовища виконання** з відповідними лімітами ресурсів +- **Моніторингу та логування** виконаного коду +- Додаткових **інфраструктурних витрат** порівняно з прямими викликами інструментів + +Переваги — зменшення вартості токенів, нижча затримка, покращена композиція інструментів — слід зважити проти цих витрат на впровадження. Для агентів з кількома MCP-серверами прямі виклики інструментів можуть бути простішими. Для агентів у масштабі (десятки серверів, сотні інструментів) виконання коду — значне покращення. + +### MCPorter: середовище виконання для композиції MCP-інструментів + +[MCPorter](https://github.com/steipete/mcporter) — TypeScript-середовище виконання та CLI-інструментарій для виклику MCP-серверів без шаблонного коду, що допомагає зменшити роздування контексту через вибіркове надання інструментів та типізовані обгортки. + +**Що вирішує:** замість завантаження всіх визначень інструментів з усіх MCP-серверів наперед, MCPorter дозволяє виявляти, інспектувати та викликати конкретні інструменти за потребою — тримаючи контекст компактним. + +**Ключові функції:** + +| Функція | Опис | +|---------|------| +| **Zero-config discovery** | Автовиявлення MCP-серверів з Cursor, Claude, Codex або локальних конфігурацій | +| **Типізовані клієнти інструментів** | `mcporter emit-ts` генерує `.d.ts` інтерфейси та готові обгортки | +| **Composable API** | `createServerProxy()` надає інструменти як camelCase-методи з хелперами `.text()`, `.json()`, `.markdown()` | +| **Генерація CLI** | `mcporter generate-cli` перетворює будь-який MCP-сервер у CLI з фільтрацією `--include-tools` / `--exclude-tools` | +| **Приховування параметрів** | Опціональні параметри приховані за замовчуванням, зменшуючи багатослівність схеми | + +**Встановлення:** + +```bash +npx mcporter list # Без встановлення — виявлення серверів миттєво +pnpm add mcporter # Додати до проєкту +brew install steipete/tap/mcporter # macOS через Homebrew +``` + +**Приклад — композиція інструментів у TypeScript:** + +```typescript +import { createRuntime, createServerProxy } from "mcporter"; + +const runtime = await createRuntime(); +const gdrive = createServerProxy(runtime, "google-drive"); +const salesforce = createServerProxy(runtime, "salesforce"); + +// Дані передаються між інструментами без проходження через контекст моделі +const doc = await gdrive.getDocument({ documentId: "abc123" }); +await salesforce.updateRecord({ + objectType: "SalesMeeting", + recordId: "00Q5f000001abcXYZ", + data: { Notes: doc.text() } +}); +``` + +**Приклад — виклик інструменту через CLI:** + +```bash +# Виклик конкретного інструменту +npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!' + +# Список доступних серверів та інструментів +npx mcporter list +``` + +MCPorter доповнює підхід з виконанням коду, описаний вище, надаючи інфраструктуру для виклику MCP-інструментів як типізованих API — спрощуючи утримання проміжних даних поза контекстом моделі. + +## Найкращі практики + +### Безпекові рекомендації + +#### Рекомендовано ✅ +- Використовуйте змінні оточення для всіх облікових даних +- Регулярно ротуйте токени та API-ключі (рекомендовано щомісяця) +- Використовуйте токени лише для читання, де можливо +- Обмежуйте область доступу MCP-серверів до мінімально необхідної +- Моніторте використання MCP-серверів та журнали доступу +- Використовуйте OAuth для зовнішніх сервісів, де доступно +- Впроваджуйте rate limiting для MCP-запитів +- Тестуйте MCP-підключення перед продакшен-використанням +- Документуйте всі активні MCP-підключення +- Тримайте пакети MCP-серверів оновленими + +#### Не рекомендовано ❌ +- Не хардкодьте облікові дані в конфігураційних файлах +- Не комітьте токени чи секрети в git +- Не поширюйте токени в командних чатах чи листах +- Не використовуйте персональні токени для командних проєктів +- Не надавайте зайвих дозволів +- Не ігноруйте помилки автентифікації +- Не відкривайте MCP-ендпоінти публічно +- Не запускайте MCP-сервери з правами root/admin +- Не кешуйте чутливі дані в журналах +- Не вимикайте механізми автентифікації + +### Найкращі практики конфігурації + +1. **Контроль версій**: тримайте `.mcp.json` у git, але використовуйте змінні оточення для секретів +2. **Мінімальні привілеї**: надавайте мінімальні дозволи для кожного MCP-сервера +3. **Ізоляція**: запускайте різні MCP-сервери в окремих процесах, де можливо +4. **Моніторинг**: логуйте всі MCP-запити та помилки для аудиту +5. **Тестування**: тестуйте всі конфігурації MCP перед розгортанням у продакшен + +### Поради щодо продуктивності + +- Кешуйте часто запитувані дані на рівні додатку +- Використовуйте конкретні MCP-запити для зменшення передачі даних +- Моніторте час відповіді MCP-операцій +- Розгляньте rate limiting для зовнішніх API +- Використовуйте пакетну обробку для кількох операцій + +## Інструкції з встановлення + +### Передумови +- Node.js та npm встановлені +- Claude Code CLI встановлений +- API-токени/облікові дані для зовнішніх сервісів + +### Покрокове налаштування + +1. **Додайте перший MCP-сервер** через CLI (приклад: GitHub): +```bash +claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github +``` + + Або створіть файл `.mcp.json` у корені проєкту: +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +2. **Встановіть змінні оточення:** +```bash +export GITHUB_TOKEN="your_github_personal_access_token" +``` + +3. **Протестуйте підключення:** +```bash +claude /mcp +``` + +4. **Використовуйте MCP-інструменти:** +```bash +/mcp__github__list_prs +/mcp__github__create_issue "Title" "Description" +``` + +### Встановлення конкретних сервісів + +**GitHub MCP:** +```bash +npm install -g @modelcontextprotocol/server-github +``` + +**Database MCP:** +```bash +npm install -g @modelcontextprotocol/server-database +``` + +**Filesystem MCP:** +```bash +npm install -g @modelcontextprotocol/server-filesystem +``` + +**Slack MCP:** +```bash +npm install -g @modelcontextprotocol/server-slack +``` + +## Усунення несправностей + +### MCP-сервер не знайдено +```bash +# Перевірте, чи встановлений MCP-сервер +npm list -g @modelcontextprotocol/server-github + +# Встановіть, якщо відсутній +npm install -g @modelcontextprotocol/server-github +``` + +### Помилка автентифікації +```bash +# Перевірте, чи встановлена змінна оточення +echo $GITHUB_TOKEN + +# Перевстановіть, якщо потрібно +export GITHUB_TOKEN="your_token" + +# Перевірте дозволи токена +# Дозволи GitHub-токена: https://github.com/settings/tokens +``` + +### Таймаут з'єднання +- Перевірте мережеве з'єднання: `ping api.github.com` +- Перевірте доступність API-ендпоінта +- Перевірте rate limits API +- Спробуйте збільшити таймаут у конфігурації +- Перевірте наявність фаєрволу або проксі + +### MCP-сервер аварійно завершується +- Перевірте журнали MCP-сервера: `~/.claude/logs/` +- Перевірте, що всі змінні оточення встановлені +- Перевірте дозволи файлів +- Спробуйте перевстановити пакет MCP-сервера +- Перевірте конфліктуючі процеси на тому ж порту + +## Пов'язані концепції + +### Пам'ять vs MCP +- **Пам'ять**: зберігає постійні, незмінні дані (налаштування, контекст, історія) +- **MCP**: доступ до живих, змінюваних даних (API, бази даних, сервіси реального часу) + +### Коли використовувати кожен +- **Пам'ять** для: налаштувань користувача, історії розмов, засвоєного контексту +- **MCP** для: поточних GitHub issue, живих запитів до бази даних, даних реального часу + +### Інтеграція з іншими функціями Claude +- Комбінуйте MCP з пам'яттю для збагаченого контексту +- Використовуйте MCP-інструменти в промптах для кращого міркування +- Поєднуйте кілька MCP для складних воркфловів + +## Додаткові ресурси + +- [Офіційна документація MCP](https://code.claude.com/docs/en/mcp) +- [Специфікація протоколу MCP](https://modelcontextprotocol.io/specification) +- [GitHub-репозиторій MCP](https://github.com/modelcontextprotocol/servers) +- [Доступні MCP-сервери](https://github.com/modelcontextprotocol/servers) +- [MCPorter](https://github.com/steipete/mcporter) — TypeScript-середовище та CLI для виклику MCP-серверів +- [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) — блог Anthropic Engineering +- [Довідник CLI Claude Code](https://code.claude.com/docs/en/cli-reference) +- [Документація Claude API](https://docs.anthropic.com) + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/05-mcp/database-mcp.json b/uk/05-mcp/database-mcp.json new file mode 100644 index 0000000..eaa832a --- /dev/null +++ b/uk/05-mcp/database-mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} diff --git a/uk/05-mcp/filesystem-mcp.json b/uk/05-mcp/filesystem-mcp.json new file mode 100644 index 0000000..c76fdf6 --- /dev/null +++ b/uk/05-mcp/filesystem-mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} diff --git a/uk/05-mcp/github-mcp.json b/uk/05-mcp/github-mcp.json new file mode 100644 index 0000000..0f62131 --- /dev/null +++ b/uk/05-mcp/github-mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} diff --git a/uk/05-mcp/multi-mcp.json b/uk/05-mcp/multi-mcp.json new file mode 100644 index 0000000..62d8fa5 --- /dev/null +++ b/uk/05-mcp/multi-mcp.json @@ -0,0 +1,29 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + }, + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "${DATABASE_URL}" + } + }, + "slack": { + "command": "npx", + "args": ["@modelcontextprotocol/server-slack"], + "env": { + "SLACK_TOKEN": "${SLACK_TOKEN}" + } + }, + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} diff --git a/uk/06-hooks/README.md b/uk/06-hooks/README.md new file mode 100644 index 0000000..e94e488 --- /dev/null +++ b/uk/06-hooks/README.md @@ -0,0 +1,1174 @@ + + + + + + + Claude How To + + +# Хуки + +Хуки — це автоматизовані скрипти, які виконуються у відповідь на конкретні події під час сесій Claude Code. Вони забезпечують автоматизацію, валідацію, управління дозволами та кастомні робочі процеси. + +## Огляд + +Хуки — це автоматичні дії (shell-команди, HTTP-вебхуки, LLM-промпти або оцінки субагентів), що виконуються автоматично при виникненні конкретних подій у Claude Code. Вони отримують JSON-вхід і повідомляють результати через коди виходу та JSON-вивід. + +**Ключові можливості:** +- Автоматизація на основі подій +- Введення/виведення на основі JSON +- Підтримка типів хуків: command, prompt, HTTP та agent +- Відповідність шаблонам (pattern matching) для хуків, специфічних для інструментів + +## Конфігурація + +Хуки налаштовуються у файлах налаштувань з конкретною структурою: + +- `~/.claude/settings.json` — налаштування користувача (усі проєкти) +- `.claude/settings.json` — налаштування проєкту (спільні, комітяться) +- `.claude/settings.local.json` — локальні налаштування проєкту (не комітяться) +- Керована політика (Managed policy) — загальноорганізаційні налаштування +- `hooks/hooks.json` плагіна — хуки з областю дії плагіна +- Frontmatter навичок/агентів — хуки часу життя компонентів + +### Базова структура конфігурації + +```json +{ + "hooks": { + "EventName": [ + { + "matcher": "ToolPattern", + "hooks": [ + { + "type": "command", + "command": "your-command-here", + "timeout": 60 + } + ] + } + ] + } +} +``` + +**Ключові поля:** + +| Поле | Опис | Приклад | +|------|------|---------| +| `matcher` | Шаблон для відповідності назвам інструментів (чутливий до регістру) | `"Write"`, `"Edit\|Write"`, `"*"` | +| `hooks` | Масив визначень хуків | `[{ "type": "command", ... }]` | +| `type` | Тип хука: `"command"` (bash), `"prompt"` (LLM), `"http"` (вебхук) або `"agent"` (субагент) | `"command"` | +| `command` | Shell-команда для виконання | `"$CLAUDE_PROJECT_DIR/.claude/hooks/format.sh"` | +| `timeout` | Необовʼязковий таймаут у секундах (за замовчуванням 60) | `30` | +| `once` | Якщо `true`, хук запускається лише один раз за сесію | `true` | + +### Шаблони matcher + +| Шаблон | Опис | Приклад | +|--------|------|---------| +| Точний рядок | Відповідає конкретному інструменту | `"Write"` | +| Regex-шаблон | Відповідає кільком інструментам | `"Edit\|Write"` | +| Підстановочний знак | Відповідає всім інструментам | `"*"` або `""` | +| MCP-інструменти | Шаблон сервера та інструмента | `"mcp__memory__.*"` | + +**Значення matcher для InstructionsLoaded:** + +| Значення matcher | Опис | +|-----------------|------| +| `session_start` | Інструкції завантажені при запуску сесії | +| `nested_traversal` | Інструкції завантажені при обході вкладених каталогів | +| `path_glob_match` | Інструкції завантажені через відповідність glob-шаблону шляху | + +## Типи хуків + +Claude Code підтримує чотири типи хуків: + +### Command-хуки + +Тип за замовчуванням. Виконує shell-команду та комунікує через JSON stdin/stdout і коди виходу. + +```json +{ + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate.py\"", + "timeout": 60 +} +``` + +### HTTP-хуки + +> Додано у v2.1.63. + +Віддалені вебхук-ендпоінти, які отримують той самий JSON-вхід, що й command-хуки. HTTP-хуки надсилають POST JSON на URL і отримують JSON-відповідь. HTTP-хуки маршрутизуються через пісочницю (sandbox), коли вона увімкнена. Інтерполяція змінних оточення в URL вимагає явного списку `allowedEnvVars` з міркувань безпеки. + +```json +{ + "hooks": { + "PostToolUse": [{ + "type": "http", + "url": "https://my-webhook.example.com/hook", + "matcher": "Write" + }] + } +} +``` + +**Ключові властивості:** +- `"type": "http"` — ідентифікує як HTTP-хук +- `"url"` — URL ендпоінту вебхука +- Маршрутизується через sandbox, коли sandbox увімкнено +- Вимагає явного списку `allowedEnvVars` для будь-якої інтерполяції змінних оточення в URL + +### Prompt-хуки + +Промпти, оцінювані LLM, де вміст хука є промптом, який оцінює Claude. Переважно використовуються з подіями `Stop` та `SubagentStop` для інтелектуальної перевірки завершення завдань. + +```json +{ + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 +} +``` + +LLM оцінює промпт і повертає структуроване рішення (деталі див. у [Хуки на основі промптів](#хуки-на-основі-промптів)). + +### Agent-хуки + +Хуки верифікації на основі субагентів, які створюють виділеного агента для оцінки умов або виконання складних перевірок. На відміну від prompt-хуків (однокрокова оцінка LLM), agent-хуки можуть використовувати інструменти та виконувати багатокрокове міркування. + +```json +{ + "type": "agent", + "prompt": "Verify the code changes follow our architecture guidelines. Check the relevant design docs and compare.", + "timeout": 120 +} +``` + +**Ключові властивості:** +- `"type": "agent"` — ідентифікує як agent-хук +- `"prompt"` — опис завдання для субагента +- Агент може використовувати інструменти (Read, Grep, Bash тощо) для оцінки +- Повертає структуроване рішення, аналогічне prompt-хукам + +## Події хуків + +Claude Code підтримує **26 подій хуків**: + +| Подія | Коли спрацьовує | Вхід matcher | Може блокувати | Типове використання | +|-------|----------------|-------------|----------------|---------------------| +| **SessionStart** | Початок/відновлення/очищення/компакція сесії | startup/resume/clear/compact | Ні | Налаштування середовища | +| **InstructionsLoaded** | Після завантаження CLAUDE.md або файлу правил | (немає) | Ні | Модифікація/фільтрація інструкцій | +| **UserPromptSubmit** | Користувач подає промпт | (немає) | Так | Валідація промптів | +| **PreToolUse** | Перед виконанням інструмента | Назва інструмента | Так (allow/deny/ask) | Валідація, модифікація вхідних даних | +| **PermissionRequest** | Показ діалогу дозволів | Назва інструмента | Так | Автозатвердження/відхилення | +| **PermissionDenied** | Користувач відхиляє запит дозволу | Назва інструмента | Ні | Логування, аналітика, політики | +| **PostToolUse** | Після успішного виконання інструмента | Назва інструмента | Ні | Контекст, зворотний звʼязок | +| **PostToolUseFailure** | Невдале виконання інструмента | Назва інструмента | Ні | Обробка помилок, логування | +| **Notification** | Надсилання сповіщення | Тип сповіщення | Ні | Кастомні сповіщення | +| **SubagentStart** | Створення субагента | Назва типу агента | Ні | Налаштування субагента | +| **SubagentStop** | Завершення субагента | Назва типу агента | Так | Валідація субагента | +| **Stop** | Claude завершує відповідь | (немає) | Так | Перевірка завершення завдання | +| **StopFailure** | Помилка API завершує хід | (немає) | Ні | Відновлення після помилок, логування | +| **TeammateIdle** | Неактивність учасника Agent Teams | (немає) | Так | Координація учасників | +| **TaskCompleted** | Завдання позначено як виконане | (немає) | Так | Дії після завершення завдання | +| **TaskCreated** | Завдання створене через TaskCreate | (немає) | Ні | Відстеження завдань, логування | +| **ConfigChange** | Зміна файлу конфігурації | (немає) | Так (крім policy) | Реакція на оновлення конфігурації | +| **CwdChanged** | Зміна робочого каталогу | (немає) | Ні | Налаштування для каталогу | +| **FileChanged** | Зміна відстежуваного файлу | (немає) | Ні | Моніторинг файлів, перебудова | +| **PreCompact** | Перед компакцією контексту | manual/auto | Ні | Дії перед компакцією | +| **PostCompact** | Після завершення компакції | (немає) | Ні | Дії після компакції | +| **WorktreeCreate** | Створення робочого дерева (worktree) | (немає) | Так (повернення шляху) | Ініціалізація worktree | +| **WorktreeRemove** | Видалення робочого дерева | (немає) | Ні | Очищення worktree | +| **Elicitation** | MCP-сервер запитує введення користувача | (немає) | Так | Валідація введення | +| **ElicitationResult** | Відповідь користувача на elicitation | (немає) | Так | Обробка відповіді | +| **SessionEnd** | Завершення сесії | (немає) | Ні | Очищення, фінальне логування | + +### PreToolUse + +Запускається після створення параметрів інструмента Claude і перед обробкою. Використовується для валідації або модифікації вхідних даних інструмента. + +**Конфігурація:** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py" + } + ] + } + ] + } +} +``` + +**Типові matcher:** `Task`, `Bash`, `Glob`, `Grep`, `Read`, `Edit`, `Write`, `WebFetch`, `WebSearch` + +**Управління виводом:** +- `permissionDecision`: `"allow"`, `"deny"` або `"ask"` +- `permissionDecisionReason`: Пояснення рішення +- `updatedInput`: Модифіковані вхідні параметри інструмента + +### PostToolUse + +Запускається одразу після завершення інструмента. Використовується для верифікації, логування або надання контексту назад Claude. + +**Конфігурація:** +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py" + } + ] + } + ] + } +} +``` + +**Управління виводом:** +- Рішення `"block"` подає Claude зворотний звʼязок +- `additionalContext`: Контекст, доданий для Claude + +### UserPromptSubmit + +Запускається, коли користувач подає промпт, перед тим як Claude його обробить. + +**Конфігурація:** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py" + } + ] + } + ] + } +} +``` + +**Управління виводом:** +- `decision`: `"block"` для запобігання обробці +- `reason`: Пояснення у разі блокування +- `additionalContext`: Контекст, доданий до промпта + +### Stop та SubagentStop + +Запускаються, коли Claude завершує відповідь (Stop) або субагент завершує роботу (SubagentStop). Підтримують оцінку на основі промптів для інтелектуальної перевірки завершення завдань. + +**Додаткове поле введення:** Обидва хуки `Stop` та `SubagentStop` отримують поле `last_assistant_message` у JSON-вході, що містить останнє повідомлення від Claude або субагента перед зупинкою. Це корисно для оцінки завершення завдання. + +**Конфігурація:** +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Evaluate if Claude completed all requested tasks.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +### SubagentStart + +Запускається при початку виконання субагента. Вхід matcher — назва типу агента, що дозволяє хукам націлюватися на конкретні типи субагентів. + +**Конфігурація:** +```json +{ + "hooks": { + "SubagentStart": [ + { + "matcher": "code-review", + "hooks": [ + { + "type": "command", + "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/subagent-init.sh" + } + ] + } + ] + } +} +``` + +### SessionStart + +Запускається при старті або відновленні сесії. Може зберігати змінні оточення. + +**Matcher:** `startup`, `resume`, `clear`, `compact` + +**Спеціальна можливість:** Використовуйте `CLAUDE_ENV_FILE` для збереження змінних оточення (також доступно в хуках `CwdChanged` та `FileChanged`): + +```bash +#!/bin/bash +if [ -n "$CLAUDE_ENV_FILE" ]; then + echo 'export NODE_ENV=development' >> "$CLAUDE_ENV_FILE" +fi +exit 0 +``` + +### SessionEnd + +Запускається при завершенні сесії для очищення або фінального логування. Не може блокувати завершення. + +**Значення поля reason:** +- `clear` — користувач очистив сесію +- `logout` — користувач вийшов із системи +- `prompt_input_exit` — користувач вийшов через введення промпта +- `other` — інша причина + +**Конфігурація:** +```json +{ + "hooks": { + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-cleanup.sh\"" + } + ] + } + ] + } +} +``` + +### Подія Notification + +Оновлені matcher для подій сповіщень: +- `permission_prompt` — сповіщення про запит дозволу +- `idle_prompt` — сповіщення про стан простою +- `auth_success` — успішна автентифікація +- `elicitation_dialog` — діалог, показаний користувачу + +## Хуки з областю дії компонентів + +Хуки можна прикріплювати до конкретних компонентів (навички, агенти, команди) у їхньому frontmatter: + +**У SKILL.md, agent.md або command.md:** + +```yaml +--- +name: secure-operations +description: Perform operations with security checks +hooks: + PreToolUse: + - matcher: "Bash" + hooks: + - type: command + command: "./scripts/check.sh" + once: true # Запустити лише один раз за сесію +--- +``` + +**Підтримувані події для хуків компонентів:** `PreToolUse`, `PostToolUse`, `Stop` + +Це дозволяє визначати хуки безпосередньо в компоненті, що їх використовує, зберігаючи повʼязаний код разом. + +### Хуки у frontmatter субагента + +Коли хук `Stop` визначений у frontmatter субагента, він автоматично перетворюється на хук `SubagentStop` з областю дії цього субагента. Це гарантує, що хук зупинки спрацьовує лише коли завершує роботу саме цей субагент, а не при зупинці основної сесії. + +```yaml +--- +name: code-review-agent +description: Automated code review subagent +hooks: + Stop: + - hooks: + - type: prompt + prompt: "Verify the code review is thorough and complete." + # Наведений Stop-хук автоматично перетворюється на SubagentStop для цього субагента +--- +``` + +## Подія PermissionRequest + +Обробка запитів дозволів з кастомним форматом виводу: + +```json +{ + "hookSpecificOutput": { + "hookEventName": "PermissionRequest", + "decision": { + "behavior": "allow|deny", + "updatedInput": {}, + "message": "Custom message", + "interrupt": false + } + } +} +``` + +## Вхідні та вихідні дані хуків + +### JSON-вхід (через stdin) + +Усі хуки отримують JSON-вхід через stdin: + +```json +{ + "session_id": "abc123", + "transcript_path": "/path/to/transcript.jsonl", + "cwd": "/current/working/directory", + "permission_mode": "default", + "hook_event_name": "PreToolUse", + "tool_name": "Write", + "tool_input": { + "file_path": "/path/to/file.js", + "content": "..." + }, + "tool_use_id": "toolu_01ABC123...", + "agent_id": "agent-abc123", + "agent_type": "main", + "worktree": "/path/to/worktree" +} +``` + +**Загальні поля:** + +| Поле | Опис | +|------|------| +| `session_id` | Унікальний ідентифікатор сесії | +| `transcript_path` | Шлях до файлу транскрипту розмови | +| `cwd` | Поточний робочий каталог | +| `hook_event_name` | Назва події, що запустила хук | +| `agent_id` | Ідентифікатор агента, що запускає хук | +| `agent_type` | Тип агента (`"main"`, назва типу субагента тощо) | +| `worktree` | Шлях до git worktree, якщо агент працює в ньому | + +### Коди виходу + +| Код виходу | Значення | Поведінка | +|-----------|----------|----------| +| **0** | Успіх | Продовжити, розібрати JSON stdout | +| **2** | Блокуюча помилка | Заблокувати операцію, stderr показується як помилка | +| **Інші** | Неблокуюча помилка | Продовжити, stderr показується у verbose-режимі | + +### JSON-вивід (stdout, код виходу 0) + +```json +{ + "continue": true, + "stopReason": "Optional message if stopping", + "suppressOutput": false, + "systemMessage": "Optional warning message", + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "allow", + "permissionDecisionReason": "File is in allowed directory", + "updatedInput": { + "file_path": "/modified/path.js" + } + } +} +``` + +## Змінні оточення + +| Змінна | Доступність | Опис | +|--------|------------|------| +| `CLAUDE_PROJECT_DIR` | Усі хуки | Абсолютний шлях до кореня проєкту | +| `CLAUDE_ENV_FILE` | SessionStart, CwdChanged, FileChanged | Шлях до файлу для збереження змінних оточення | +| `CLAUDE_CODE_REMOTE` | Усі хуки | `"true"` при роботі у віддаленому середовищі | +| `${CLAUDE_PLUGIN_ROOT}` | Хуки плагінів | Шлях до каталогу плагіна | +| `${CLAUDE_PLUGIN_DATA}` | Хуки плагінів | Шлях до каталогу даних плагіна | +| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | Хуки SessionEnd | Налаштовуваний таймаут у мілісекундах для хуків SessionEnd (перевизначає стандартний) | + +## Хуки на основі промптів + +Для подій `Stop` та `SubagentStop` можна використовувати оцінку на основі LLM: + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if all tasks are complete. Return your decision.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +**Схема відповіді LLM:** +```json +{ + "decision": "approve", + "reason": "All tasks completed successfully", + "continue": false, + "stopReason": "Task complete" +} +``` + +## Приклади + +### Приклад 1: Валідатор Bash-команд (PreToolUse) + +**Файл:** `.claude/hooks/validate-bash.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"\brm\s+-rf\s+/", "Blocking dangerous rm -rf / command"), + (r"\bsudo\s+rm", "Blocking sudo rm command"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name != "Bash": + sys.exit(0) + + command = input_data.get("tool_input", {}).get("command", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, command): + print(message, file=sys.stderr) + sys.exit(2) # Код виходу 2 = блокуюча помилка + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +**Конфігурація:** +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"" + } + ] + } + ] + } +} +``` + +### Приклад 2: Сканер безпеки (PostToolUse) + +**Файл:** `.claude/hooks/security-scan.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +SECRET_PATTERNS = [ + (r"password\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded password"), + (r"api[_-]?key\s*=\s*['\"][^'\"]+['\"]", "Potential hardcoded API key"), +] + +def main(): + input_data = json.load(sys.stdin) + + tool_name = input_data.get("tool_name", "") + if tool_name not in ["Write", "Edit"]: + sys.exit(0) + + tool_input = input_data.get("tool_input", {}) + content = tool_input.get("content", "") or tool_input.get("new_string", "") + file_path = tool_input.get("file_path", "") + + warnings = [] + for pattern, message in SECRET_PATTERNS: + if re.search(pattern, content, re.IGNORECASE): + warnings.append(message) + + if warnings: + output = { + "hookSpecificOutput": { + "hookEventName": "PostToolUse", + "additionalContext": f"Security warnings for {file_path}: " + "; ".join(warnings) + } + } + print(json.dumps(output)) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### Приклад 3: Автоформатування коду (PostToolUse) + +**Файл:** `.claude/hooks/format-code.sh` + +```bash +#!/bin/bash + +# Читання JSON з stdin +INPUT=$(cat) +TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_name', ''))") +FILE_PATH=$(echo "$INPUT" | python3 -c "import sys, json; print(json.load(sys.stdin).get('tool_input', {}).get('file_path', ''))") + +if [ "$TOOL_NAME" != "Write" ] && [ "$TOOL_NAME" != "Edit" ]; then + exit 0 +fi + +# Форматування залежно від розширення файлу +case "$FILE_PATH" in + *.js|*.jsx|*.ts|*.tsx|*.json) + command -v prettier &>/dev/null && prettier --write "$FILE_PATH" 2>/dev/null + ;; + *.py) + command -v black &>/dev/null && black "$FILE_PATH" 2>/dev/null + ;; + *.go) + command -v gofmt &>/dev/null && gofmt -w "$FILE_PATH" 2>/dev/null + ;; +esac + +exit 0 +``` + +### Приклад 4: Валідатор промптів (UserPromptSubmit) + +**Файл:** `.claude/hooks/validate-prompt.py` + +```python +#!/usr/bin/env python3 +import json +import sys +import re + +BLOCKED_PATTERNS = [ + (r"delete\s+(all\s+)?database", "Dangerous: database deletion"), + (r"rm\s+-rf\s+/", "Dangerous: root deletion"), +] + +def main(): + input_data = json.load(sys.stdin) + prompt = input_data.get("user_prompt", "") or input_data.get("prompt", "") + + for pattern, message in BLOCKED_PATTERNS: + if re.search(pattern, prompt, re.IGNORECASE): + output = { + "decision": "block", + "reason": f"Blocked: {message}" + } + print(json.dumps(output)) + sys.exit(0) + + sys.exit(0) + +if __name__ == "__main__": + main() +``` + +### Приклад 5: Інтелектуальний Stop-хук (на основі промпта) + +```json +{ + "hooks": { + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Review if Claude completed all requested tasks. Check: 1) Were all files created/modified? 2) Were there unresolved errors? If incomplete, explain what's missing.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +### Приклад 6: Трекер використання контексту (пара хуків) + +Відстеження споживання токенів на запит за допомогою хуків `UserPromptSubmit` (перед повідомленням) та `Stop` (після відповіді). + +**Файл:** `.claude/hooks/context-tracker.py` + +```python +#!/usr/bin/env python3 +""" +Context Usage Tracker — Відстежує споживання токенів на запит. + +Використовує UserPromptSubmit як хук "перед повідомленням" і Stop як хук "після відповіді" +для обчислення дельти використання токенів для кожного запиту. + +Методи підрахунку токенів: +1. Оцінка за символами (за замовчуванням): ~4 символи на токен, без залежностей +2. tiktoken (необовʼязково): Точніший (~90-95%), потребує: pip install tiktoken +""" +import json +import os +import sys +import tempfile + +# Конфігурація +CONTEXT_LIMIT = 128000 # Контекстне вікно Claude (налаштуйте для вашої моделі) +USE_TIKTOKEN = False # Встановіть True, якщо tiktoken встановлено для кращої точності + + +def get_state_file(session_id: str) -> str: + """Отримати шлях до тимчасового файлу для збереження лічильника токенів, ізольовано за сесією.""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens(text: str) -> int: + """ + Підрахунок токенів у тексті. + + Використовує tiktoken з кодуванням p50k_base, якщо доступно (~90-95% точності), + інакше повертається до оцінки за символами (~80-90% точності). + """ + if USE_TIKTOKEN: + try: + import tiktoken + enc = tiktoken.get_encoding("p50k_base") + return len(enc.encode(text)) + except ImportError: + pass # Повернутися до оцінки + + # Оцінка на основі символів: ~4 символи на токен для англійської + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """Читання та конкатенація всього вмісту з файлу транскрипту.""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # Витяг текстового вмісту з різних форматів повідомлень + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """Хук перед повідомленням: зберегти поточний лічильник токенів перед запитом.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Зберегти в тимчасовий файл для подальшого порівняння + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """Хук після відповіді: обчислити дельту та повідомити про використання.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Завантажити лічильник перед повідомленням + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # Обчислити дельту + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # Повідомити про використання + method = "tiktoken" if USE_TIKTOKEN else "estimated" + print(f"Context ({method}): ~{current_tokens:,} tokens ({percentage:.1f}% used, ~{remaining:,} remaining)", file=sys.stderr) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() +``` + +**Конфігурація:** +```json +{ + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/context-tracker.py\"" + } + ] + } + ] + } +} +``` + +**Як це працює:** +1. `UserPromptSubmit` спрацьовує перед обробкою промпта — зберігає поточний лічильник токенів +2. `Stop` спрацьовує після відповіді Claude — обчислює дельту та повідомляє про використання +3. Кожна сесія ізольована через `session_id` в імені тимчасового файлу + +**Методи підрахунку токенів:** + +| Метод | Точність | Залежності | Швидкість | +|-------|----------|------------|-----------| +| Оцінка за символами | ~80-90% | Немає | <1мс | +| tiktoken (p50k_base) | ~90-95% | `pip install tiktoken` | <10мс | + +> **Примітка:** Anthropic не випустили офіційний офлайн-токенізатор. Обидва методи є наближеннями. Транскрипт включає промпти користувача, відповіді Claude та вивід інструментів, але НЕ системні промпти або внутрішній контекст. + +### Приклад 7: Початкове налаштування дозволів Auto-Mode (одноразовий скрипт) + +Одноразовий скрипт налаштування, що додає до `~/.claude/settings.json` ~67 безпечних правил дозволів, еквівалентних базовому набору auto-mode Claude Code — без жодного хука, без запамʼятовування майбутніх виборів. Запустіть один раз; безпечно для повторного запуску (пропускає правила, що вже присутні). + +**Файл:** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# Попередній перегляд того, що буде додано +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# Застосувати +python3 09-advanced-features/setup-auto-mode-permissions.py +``` + +**Що додається:** + +| Категорія | Приклади | +|-----------|---------| +| Вбудовані інструменти | `Read(*)`, `Edit(*)`, `Write(*)`, `Glob(*)`, `Grep(*)`, `Agent(*)`, `WebSearch(*)` | +| Git читання | `Bash(git status:*)`, `Bash(git log:*)`, `Bash(git diff:*)` | +| Git запис (локально) | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git checkout:*)` | +| Пакетні менеджери | `Bash(npm install:*)`, `Bash(pip install:*)`, `Bash(cargo build:*)` | +| Збірка та тестування | `Bash(make:*)`, `Bash(pytest:*)`, `Bash(go test:*)` | +| Загальні shell-команди | `Bash(ls:*)`, `Bash(cat:*)`, `Bash(find:*)`, `Bash(cp:*)`, `Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`, `Bash(gh pr create:*)`, `Bash(gh issue list:*)` | + +**Що навмисно виключено** (цей скрипт ніколи не додає): +- `rm -rf`, `sudo`, force push, `git reset --hard` +- `DROP TABLE`, `kubectl delete`, `terraform destroy` +- `npm publish`, `curl | bash`, деплої на продакшн + +## Хуки плагінів + +Плагіни можуть включати хуки у файлі `hooks/hooks.json`: + +**Файл:** `plugins/hooks/hooks.json` + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh" + } + ] + } + ] + } +} +``` + +**Змінні оточення в хуках плагінів:** +- `${CLAUDE_PLUGIN_ROOT}` — шлях до каталогу плагіна +- `${CLAUDE_PLUGIN_DATA}` — шлях до каталогу даних плагіна + +Це дозволяє плагінам включати кастомні хуки валідації та автоматизації. + +## Хуки MCP-інструментів + +MCP-інструменти використовують шаблон `mcp____`: + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "mcp__memory__.*", + "hooks": [ + { + "type": "command", + "command": "echo '{\"systemMessage\": \"Memory operation logged\"}'" + } + ] + } + ] + } +} +``` + +## Міркування безпеки + +### Застереження + +**ВИКОРИСТОВУЙТЕ НА ВЛАСНИЙ РИЗИК**: Хуки виконують довільні shell-команди. Ви несете повну відповідальність за: +- Команди, які ви налаштовуєте +- Дозволи на доступ/модифікацію файлів +- Потенційну втрату даних або пошкодження системи +- Тестування хуків у безпечних середовищах перед використанням на продакшні + +### Примітки щодо безпеки + +- **Потрібна довіра до робочого простору:** Команди виводу хуків `statusLine` та `fileSuggestion` тепер вимагають прийняття довіри до робочого простору перед набранням чинності. +- **HTTP-хуки та змінні оточення:** HTTP-хуки вимагають явного списку `allowedEnvVars` для використання інтерполяції змінних оточення в URL. Це запобігає випадковому витоку чутливих змінних оточення на віддалені ендпоінти. +- **Ієрархія керованих налаштувань:** Налаштування `disableAllHooks` тепер поважає ієрархію керованих налаштувань, тобто налаштування рівня організації можуть примусово вимкнути хуки, що не може бути перевизначено окремими користувачами. + +### Найкращі практики + +| Рекомендовано | Не рекомендовано | +|-------------|-----------------| +| Валідувати та санітизувати всі вхідні дані | Довіряти вхідним даним сліпо | +| Екранувати змінні shell: `"$VAR"` | Використовувати без лапок: `$VAR` | +| Блокувати обхід шляху (`..`) | Дозволяти довільні шляхи | +| Використовувати абсолютні шляхи з `$CLAUDE_PROJECT_DIR` | Жорстко кодувати шляхи | +| Пропускати чутливі файли (`.env`, `.git/`, ключі) | Обробляти всі файли | +| Тестувати хуки окремо спочатку | Деплоїти неперевірені хуки | +| Використовувати явний `allowedEnvVars` для HTTP-хуків | Відкривати всі змінні оточення для вебхуків | + +## Налагодження + +### Увімкнення режиму налагодження + +Запустіть Claude з прапорцем debug для детальних журналів хуків: + +```bash +claude --debug +``` + +### Verbose-режим + +Використовуйте `Ctrl+O` в Claude Code для увімкнення verbose-режиму та перегляду прогресу виконання хуків. + +### Тестування хуків окремо + +```bash +# Тест із зразковим JSON-вводом +echo '{"tool_name": "Bash", "tool_input": {"command": "ls -la"}}' | python3 .claude/hooks/validate-bash.py + +# Перевірка коду виходу +echo $? +``` + +## Повний приклад конфігурації + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-bash.py\"", + "timeout": 10 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh\"", + "timeout": 30 + }, + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/security-scan.py\"", + "timeout": 10 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/validate-prompt.py\"" + } + ] + } + ], + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-init.sh\"" + } + ] + } + ], + "Stop": [ + { + "hooks": [ + { + "type": "prompt", + "prompt": "Verify all tasks are complete before stopping.", + "timeout": 30 + } + ] + } + ] + } +} +``` + +## Деталі виконання хуків + +| Аспект | Поведінка | +|--------|----------| +| **Таймаут** | 60 секунд за замовчуванням, налаштовується для кожної команди | +| **Паралелізація** | Усі відповідні хуки запускаються паралельно | +| **Дедуплікація** | Ідентичні команди хуків дедуплікуються | +| **Середовище** | Запускається в поточному каталозі з середовищем Claude Code | + +## Усунення несправностей + +### Хук не виконується +- Перевірте правильність синтаксису JSON-конфігурації +- Переконайтеся, що шаблон matcher відповідає назві інструмента +- Перевірте існування та виконуваність скрипта: `chmod +x script.sh` +- Запустіть `claude --debug` для перегляду журналів виконання хуків +- Переконайтеся, що хук читає JSON з stdin (не з аргументів команди) + +### Хук блокує несподівано +- Тестуйте хук зі зразковим JSON: `echo '{"tool_name": "Write", ...}' | ./hook.py` +- Перевірте код виходу: має бути 0 для дозволу, 2 для блокування +- Перевірте вивід stderr (показується при коді виходу 2) + +### Помилки парсингу JSON +- Завжди читайте з stdin, не з аргументів команди +- Використовуйте належний парсинг JSON (не маніпуляцію рядками) +- Обробляйте відсутні поля коректно + +## Встановлення + +### Крок 1: Створення каталогу хуків +```bash +mkdir -p ~/.claude/hooks +``` + +### Крок 2: Копіювання прикладів хуків +```bash +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +### Крок 3: Налаштування у settings +Відредагуйте `~/.claude/settings.json` або `.claude/settings.json` з конфігурацією хуків, показаною вище. + +## Повʼязані концепції + +- **[Контрольні точки та відкат](../08-checkpoints/)** — збереження та відновлення стану розмови +- **[Слеш-команди](../01-slash-commands/)** — створення кастомних слеш-команд +- **[Навички](../03-skills/)** — повторно використовувані автономні можливості +- **[Субагенти](../04-subagents/)** — делеговане виконання завдань +- **[Плагіни](../07-plugins/)** — обʼєднані пакети розширень +- **[Розширені функції](../09-advanced-features/)** — дослідження розширених можливостей Claude Code + +## Додаткові ресурси + +- **[Офіційна документація хуків](https://code.claude.com/docs/en/hooks)** — повний довідник хуків +- **[Довідник CLI](https://code.claude.com/docs/en/cli-reference)** — документація інтерфейсу командного рядка +- **[Посібник з памʼяті](../02-memory/)** — конфігурація постійного контексту + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/06-hooks/context-tracker-tiktoken.py b/uk/06-hooks/context-tracker-tiktoken.py new file mode 100644 index 0000000..11786bf --- /dev/null +++ b/uk/06-hooks/context-tracker-tiktoken.py @@ -0,0 +1,149 @@ +#!/usr/bin/env python3 +""" +Context Usage Tracker (tiktoken version) - Tracks token consumption per request. + +Uses UserPromptSubmit as "pre-message" hook and Stop as "post-response" hook +to calculate the delta in token usage for each request. + +This version uses tiktoken with p50k_base encoding for ~90-95% accuracy. +Requires: pip install tiktoken + +For a zero-dependency version, see context-tracker.py. + +Usage: + Configure both hooks to use the same script: + - UserPromptSubmit: saves current token count + - Stop: calculates delta and reports usage +""" +import json +import os +import sys +import tempfile + +try: + import tiktoken + + TIKTOKEN_AVAILABLE = True +except ImportError: + TIKTOKEN_AVAILABLE = False + print( + "Warning: tiktoken not installed. Install with: pip install tiktoken", + file=sys.stderr, + ) + +# Configuration +CONTEXT_LIMIT = 128000 # Claude's context window (adjust for your model) + + +def get_state_file(session_id: str) -> str: + """Get temp file path for storing pre-message token count, isolated by session.""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens(text: str) -> int: + """ + Count tokens using tiktoken with p50k_base encoding. + + This provides ~90-95% accuracy compared to Claude's actual tokenizer. + Falls back to character estimation if tiktoken is not available. + + Note: Anthropic hasn't released an official offline tokenizer. + tiktoken with p50k_base is a reasonable approximation since both + Claude and GPT models use BPE (byte-pair encoding). + """ + if TIKTOKEN_AVAILABLE: + enc = tiktoken.get_encoding("p50k_base") + return len(enc.encode(text)) + else: + # Fallback to character estimation (~4 chars per token) + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """Read and concatenate all content from transcript file.""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # Extract text content from various message formats + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """Pre-message hook: Save current token count before request.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Save to temp file for later comparison + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """Post-response hook: Calculate and report token delta.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens(transcript_content) + + # Load pre-message count + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # Calculate delta + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # Report usage (stderr so it doesn't interfere with hook output) + method = "tiktoken" if TIKTOKEN_AVAILABLE else "estimated" + print( + f"Context ({method}): ~{current_tokens:,} tokens " + f"({percentage:.1f}% used, ~{remaining:,} remaining)", + file=sys.stderr, + ) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/uk/06-hooks/context-tracker.py b/uk/06-hooks/context-tracker.py new file mode 100644 index 0000000..eb5daf9 --- /dev/null +++ b/uk/06-hooks/context-tracker.py @@ -0,0 +1,126 @@ +#!/usr/bin/env python3 +""" +Context Usage Tracker - Tracks token consumption per request. + +Uses UserPromptSubmit as "pre-message" hook and Stop as "post-response" hook +to calculate the delta in token usage for each request. + +This version uses character-based estimation (no dependencies). +For better accuracy, see context-tracker-tiktoken.py. + +Usage: + Configure both hooks to use the same script: + - UserPromptSubmit: saves current token count + - Stop: calculates delta and reports usage +""" +import json +import os +import sys +import tempfile + +# Configuration +CONTEXT_LIMIT = 128000 # Claude's context window (adjust for your model) + + +def get_state_file(session_id: str) -> str: + """Get temp file path for storing pre-message token count, isolated by session.""" + return os.path.join(tempfile.gettempdir(), f"claude-context-{session_id}.json") + + +def count_tokens_estimate(text: str) -> int: + """ + Estimate token count using character-based approximation. + + Uses ~4 characters per token ratio, which provides ~80-90% accuracy + for English text. Less accurate for code and non-English text. + """ + return len(text) // 4 + + +def read_transcript(transcript_path: str) -> str: + """Read and concatenate all content from transcript file.""" + if not transcript_path or not os.path.exists(transcript_path): + return "" + + content = [] + with open(transcript_path, "r") as f: + for line in f: + try: + entry = json.loads(line.strip()) + # Extract text content from various message formats + if "message" in entry: + msg = entry["message"] + if isinstance(msg.get("content"), str): + content.append(msg["content"]) + elif isinstance(msg.get("content"), list): + for block in msg["content"]: + if isinstance(block, dict) and block.get("type") == "text": + content.append(block.get("text", "")) + except json.JSONDecodeError: + continue + + return "\n".join(content) + + +def handle_user_prompt_submit(data: dict) -> None: + """Pre-message hook: Save current token count before request.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens_estimate(transcript_content) + + # Save to temp file for later comparison + state_file = get_state_file(session_id) + with open(state_file, "w") as f: + json.dump({"pre_tokens": current_tokens}, f) + + +def handle_stop(data: dict) -> None: + """Post-response hook: Calculate and report token delta.""" + session_id = data.get("session_id", "unknown") + transcript_path = data.get("transcript_path", "") + + transcript_content = read_transcript(transcript_path) + current_tokens = count_tokens_estimate(transcript_content) + + # Load pre-message count + state_file = get_state_file(session_id) + pre_tokens = 0 + if os.path.exists(state_file): + try: + with open(state_file, "r") as f: + state = json.load(f) + pre_tokens = state.get("pre_tokens", 0) + except (json.JSONDecodeError, IOError): + pass + + # Calculate delta + delta_tokens = current_tokens - pre_tokens + remaining = CONTEXT_LIMIT - current_tokens + percentage = (current_tokens / CONTEXT_LIMIT) * 100 + + # Report usage (stderr so it doesn't interfere with hook output) + print( + f"Context (estimated): ~{current_tokens:,} tokens " + f"({percentage:.1f}% used, ~{remaining:,} remaining)", + file=sys.stderr, + ) + if delta_tokens > 0: + print(f"This request: ~{delta_tokens:,} tokens", file=sys.stderr) + + +def main(): + data = json.load(sys.stdin) + event = data.get("hook_event_name", "") + + if event == "UserPromptSubmit": + handle_user_prompt_submit(data) + elif event == "Stop": + handle_stop(data) + + sys.exit(0) + + +if __name__ == "__main__": + main() diff --git a/uk/06-hooks/dependency-check.sh b/uk/06-hooks/dependency-check.sh new file mode 100644 index 0000000..c659b9f --- /dev/null +++ b/uk/06-hooks/dependency-check.sh @@ -0,0 +1,156 @@ +#!/bin/bash +# Check for known vulnerabilities in dependencies after manifest files are modified. +# Hook: PostToolUse:Write + +FILE=$1 + +if [ -z "$FILE" ]; then + echo "Usage: $0 " + exit 0 +fi + +# Use basename for matching — $1 may be an absolute path +BASENAME=$(basename "$FILE") + +# Only run when a dependency manifest is written +case "$BASENAME" in + package.json|package-lock.json|yarn.lock|pnpm-lock.yaml| \ + requirements.txt|Pipfile|Pipfile.lock|pyproject.toml| \ + go.mod|go.sum| \ + Cargo.toml|Cargo.lock| \ + Gemfile|Gemfile.lock| \ + composer.json|composer.lock| \ + pom.xml|build.gradle|build.gradle.kts) + echo "📦 Dependency manifest updated: $FILE — scanning for vulnerabilities..." + ;; + *) + exit 0 + ;; +esac + +ISSUES_FOUND=0 + +# ── npm / yarn / pnpm ──────────────────────────────────────────────────────── +if [[ "$BASENAME" == package*.json || "$BASENAME" == yarn.lock || "$BASENAME" == pnpm-lock.yaml ]]; then + if command -v npm &>/dev/null; then + echo "🔍 Running npm audit..." + if ! npm audit --audit-level=high --json 2>/dev/null | \ + python3 -c " +import sys, json +data = json.load(sys.stdin) +vulns = data.get('metadata', {}).get('vulnerabilities', {}) +high = vulns.get('high', 0) + vulns.get('critical', 0) +if high: + print(f' ⚠️ {high} high/critical npm vulnerabilities found. Run: npm audit fix') + sys.exit(1) +" 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " ✅ No high/critical npm vulnerabilities" + fi + fi + + if command -v yarn &>/dev/null && [[ "$BASENAME" == yarn.lock ]]; then + echo "🔍 Running yarn audit..." + if ! yarn audit --level high --json 2>/dev/null | \ + grep -q '"type":"auditAdvisory"' 2>/dev/null; then + echo " ✅ No high yarn vulnerabilities" + else + echo " ⚠️ yarn audit found vulnerabilities. Run: yarn audit --level high" + ISSUES_FOUND=1 + fi + fi +fi + +# ── Python ─────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == requirements.txt || "$BASENAME" == Pipfile* || "$BASENAME" == pyproject.toml ]]; then + if command -v pip-audit &>/dev/null; then + echo "🔍 Running pip-audit..." + if pip-audit --format=json 2>/dev/null | \ + python3 -c " +import sys, json +data = json.load(sys.stdin) +vulns = [d for d in data.get('dependencies', []) if d.get('vulns')] +if vulns: + for dep in vulns: + for v in dep['vulns']: + print(f' ⚠️ {dep[\"name\"]} {dep[\"version\"]}: {v[\"id\"]} — {v[\"fix_versions\"]}') + sys.exit(1) +" 2>/dev/null; then + echo " ✅ No Python vulnerabilities found" + else + ISSUES_FOUND=1 + echo " Run: pip-audit for details" + fi + elif command -v safety &>/dev/null; then + echo "🔍 Running safety check..." + OUTPUT=$(safety check --short-report 2>&1) + EXIT_CODE=$? + if [ $EXIT_CODE -eq 0 ]; then + echo " ✅ No Python vulnerabilities found" + elif echo "$OUTPUT" | grep -qiE "vulnerability|CVE|insecure"; then + echo "$OUTPUT" + ISSUES_FOUND=1 + else + echo " ⚠️ safety check could not complete (network or config error)" >&2 + fi + fi +fi + +# ── Go ─────────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == go.mod || "$BASENAME" == go.sum ]]; then + if command -v govulncheck &>/dev/null; then + echo "🔍 Running govulncheck..." + OUTPUT=$(govulncheck ./... 2>&1) + EXIT_CODE=$? + if [ $EXIT_CODE -eq 0 ]; then + echo " ✅ No Go vulnerabilities found" + elif echo "$OUTPUT" | grep -q "Vulnerability #"; then + echo "$OUTPUT" + ISSUES_FOUND=1 + else + echo " ⚠️ govulncheck could not complete: $OUTPUT" >&2 + fi + fi +fi + +# ── Rust ───────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == Cargo.toml || "$BASENAME" == Cargo.lock ]]; then + if command -v cargo-audit &>/dev/null; then + echo "🔍 Running cargo audit..." + if ! cargo audit 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " ✅ No Rust vulnerabilities found" + fi + fi +fi + +# ── Ruby ───────────────────────────────────────────────────────────────────── +if [[ "$BASENAME" == Gemfile || "$BASENAME" == Gemfile.lock ]]; then + if command -v bundler-audit &>/dev/null; then + echo "🔍 Running bundler-audit..." + bundler-audit check --update 2>/dev/null || ISSUES_FOUND=1 + fi +fi + +# ── Generic fallback: trivy ────────────────────────────────────────────────── +if command -v trivy &>/dev/null; then + echo "🔍 Running trivy fs scan..." + if ! trivy fs --exit-code 1 --severity HIGH,CRITICAL --quiet . 2>/dev/null; then + ISSUES_FOUND=1 + else + echo " ✅ trivy found no HIGH/CRITICAL issues" + fi +fi + +if [ "$ISSUES_FOUND" -eq 0 ]; then + echo "✅ Dependency check passed — no vulnerabilities detected" +else + echo "" + echo "⚠️ Vulnerabilities detected. Review and update dependencies before committing." + echo " This hook is advisory only and will not block your workflow." +fi + +# Always exit 0 — this hook warns but does not block +exit 0 diff --git a/uk/06-hooks/format-code.sh b/uk/06-hooks/format-code.sh new file mode 100644 index 0000000..9841b9e --- /dev/null +++ b/uk/06-hooks/format-code.sh @@ -0,0 +1,49 @@ +#!/bin/bash +# Auto-format code after writing +# Hook: PostToolUse:Write +# +# Reads the target file path from stdin JSON and runs the appropriate formatter +# in-place on the file after Claude writes it. +# +# Compatible with: macOS, Linux, Windows (Git Bash) + +# Read JSON input from stdin (Claude Code hook protocol) +INPUT=$(cat) + +# Extract file_path using sed (compatible with all platforms) +FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then + exit 0 +fi + +# Detect file type and format accordingly +case "$FILE_PATH" in + *.js|*.jsx|*.ts|*.tsx) + if command -v prettier &> /dev/null; then + prettier --write "$FILE_PATH" 2>/dev/null + fi + ;; + *.py) + if command -v black &> /dev/null; then + black "$FILE_PATH" 2>/dev/null + fi + ;; + *.go) + if command -v gofmt &> /dev/null; then + gofmt -w "$FILE_PATH" 2>/dev/null + fi + ;; + *.rs) + if command -v rustfmt &> /dev/null; then + rustfmt "$FILE_PATH" 2>/dev/null + fi + ;; + *.java) + if command -v google-java-format &> /dev/null; then + google-java-format -i "$FILE_PATH" 2>/dev/null + fi + ;; +esac + +exit 0 diff --git a/uk/06-hooks/log-bash.sh b/uk/06-hooks/log-bash.sh new file mode 100644 index 0000000..2ca16d9 --- /dev/null +++ b/uk/06-hooks/log-bash.sh @@ -0,0 +1,31 @@ +#!/bin/bash +# Log all bash commands +# Hook: PostToolUse:Bash +# +# Reads the executed command from stdin JSON and logs it to a file. +# +# Compatible with: macOS, Linux, Windows (Git Bash) + +# Read JSON input from stdin (Claude Code hook protocol) +INPUT=$(cat) + +# Extract the bash command from tool_input +# Note: sed [^"]* stops at escaped quotes in JSON; for commands with double-quoted +# strings, only the portion up to the first \" will be captured — this is a known +# limitation of sed-based JSON parsing and is acceptable for logging purposes. +COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$COMMAND" ]; then + exit 0 +fi + +TIMESTAMP=$(date "+%Y-%m-%d %H:%M:%S") +LOGFILE="$HOME/.claude/bash-commands.log" + +# Create log directory if it doesn't exist +mkdir -p "$(dirname "$LOGFILE")" + +# Log the command +echo "[$TIMESTAMP] $COMMAND" >> "$LOGFILE" + +exit 0 diff --git a/uk/06-hooks/notify-team.sh b/uk/06-hooks/notify-team.sh new file mode 100644 index 0000000..1894218 --- /dev/null +++ b/uk/06-hooks/notify-team.sh @@ -0,0 +1,68 @@ +#!/bin/bash +# Send notifications on events +# Hook: PostToolUse (matcher: Bash) — run after bash commands; filter for git push in script logic +# Note: Claude Code has no native PostPush event. To trigger on git push, check the bash command +# string for "git push" using a matcher or conditional logic within this script. + +REPO_NAME=$(basename $(git rev-parse --show-toplevel 2>/dev/null) 2>/dev/null) +COMMIT_MSG=$(git log -1 --pretty=%B 2>/dev/null) +AUTHOR=$(git log -1 --pretty=%an 2>/dev/null) +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) + +echo "📢 Sending notification to team..." + +# Slack webhook example (replace with your webhook URL) +SLACK_WEBHOOK="${SLACK_WEBHOOK_URL:-}" + +if [ -n "$SLACK_WEBHOOK" ]; then + curl -X POST "$SLACK_WEBHOOK" \ + -H 'Content-Type: application/json' \ + -d "{ + \"text\": \"New push to *$REPO_NAME*\", + \"attachments\": [{ + \"color\": \"good\", + \"fields\": [ + {\"title\": \"Branch\", \"value\": \"$BRANCH\", \"short\": true}, + {\"title\": \"Author\", \"value\": \"$AUTHOR\", \"short\": true}, + {\"title\": \"Commit\", \"value\": \"$COMMIT_MSG\"} + ] + }] + }" \ + --silent --output /dev/null + + echo "✅ Slack notification sent" +fi + +# Discord webhook example (replace with your webhook URL) +DISCORD_WEBHOOK="${DISCORD_WEBHOOK_URL:-}" + +if [ -n "$DISCORD_WEBHOOK" ]; then + curl -X POST "$DISCORD_WEBHOOK" \ + -H 'Content-Type: application/json' \ + -d "{ + \"content\": \"**New push to $REPO_NAME**\", + \"embeds\": [{ + \"title\": \"$COMMIT_MSG\", + \"color\": 3066993, + \"fields\": [ + {\"name\": \"Branch\", \"value\": \"$BRANCH\", \"inline\": true}, + {\"name\": \"Author\", \"value\": \"$AUTHOR\", \"inline\": true} + ] + }] + }" \ + --silent --output /dev/null + + echo "✅ Discord notification sent" +fi + +# Email notification example +EMAIL_TO="${TEAM_EMAIL:-}" + +if [ -n "$EMAIL_TO" ]; then + echo "New push to $REPO_NAME by $AUTHOR" | \ + mail -s "Git Push: $BRANCH" "$EMAIL_TO" + + echo "✅ Email notification sent" +fi + +exit 0 diff --git a/uk/06-hooks/pre-commit.sh b/uk/06-hooks/pre-commit.sh new file mode 100644 index 0000000..2e9b27a --- /dev/null +++ b/uk/06-hooks/pre-commit.sh @@ -0,0 +1,50 @@ +#!/bin/bash +# Run tests before commit +# Hook: PreToolUse (matcher: Bash) - checks if the command is a git commit +# Note: There is no "PreCommit" hook event. Use PreToolUse with a Bash matcher +# and inspect the command to detect git commit operations. + +echo "🧪 Running tests before commit..." + +# Check if package.json exists (Node.js project) +if [ -f "package.json" ]; then + if grep -q "\"test\":" package.json; then + npm test + if [ $? -ne 0 ]; then + echo "❌ Tests failed! Commit blocked." + exit 1 + fi + fi +fi + +# Check if pytest is available (Python project) +if [ -f "pytest.ini" ] || [ -f "setup.py" ]; then + if command -v pytest &> /dev/null; then + pytest + if [ $? -ne 0 ]; then + echo "❌ Tests failed! Commit blocked." + exit 1 + fi + fi +fi + +# Check if go.mod exists (Go project) +if [ -f "go.mod" ]; then + go test ./... + if [ $? -ne 0 ]; then + echo "❌ Tests failed! Commit blocked." + exit 1 + fi +fi + +# Check if Cargo.toml exists (Rust project) +if [ -f "Cargo.toml" ]; then + cargo test + if [ $? -ne 0 ]; then + echo "❌ Tests failed! Commit blocked." + exit 1 + fi +fi + +echo "✅ All tests passed! Proceeding with commit." +exit 0 diff --git a/uk/06-hooks/pre-tool-check.sh b/uk/06-hooks/pre-tool-check.sh new file mode 100644 index 0000000..932395e --- /dev/null +++ b/uk/06-hooks/pre-tool-check.sh @@ -0,0 +1,96 @@ +#!/bin/bash +# Pre-tool safety check for Bash commands +# Hook: PreToolUse (matcher: Bash) +# +# This hook runs before every Bash tool execution and blocks or warns on +# potentially destructive or high-risk shell commands. +# +# Setup: +# cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/ +# chmod +x ~/.claude/hooks/pre-tool-check.sh +# +# Configure in ~/.claude/settings.json: +# { +# "hooks": { +# "PreToolUse": [ +# { +# "matcher": "Bash", +# "hooks": [ +# { +# "type": "command", +# "command": "~/.claude/hooks/pre-tool-check.sh" +# } +# ] +# } +# ] +# } +# } +# +# Input: JSON via stdin with the shape: +# { "tool_name": "Bash", "tool_input": { "command": "..." } } +# +# Output: Exit 0 to allow, exit 2 to block, or print JSON to modify behavior. + +# Read the full JSON input from stdin +INPUT=$(cat) + +# Extract the command using portable sed (compatible with macOS and Linux) +COMMAND=$(echo "$INPUT" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +# Fall back to the raw input if extraction fails +if [ -z "$COMMAND" ]; then + COMMAND="$INPUT" +fi + +# ── Blocked patterns ────────────────────────────────────────────────────────── +# These commands are blocked unconditionally because they are almost always +# destructive and rarely intentional in an automated context. + +BLOCKED_PATTERNS=( + "rm -rf /" + "rm -rf \*" + "dd if=/dev/zero" + "dd if=/dev/random" + ":(){:|:&};:" # Fork bomb + "mkfs\." # Filesystem format + "format c:" # Windows disk format +) + +for pattern in "${BLOCKED_PATTERNS[@]}"; do + if echo "$COMMAND" | grep -qE "$pattern"; then + echo "❌ Blocked: Potentially destructive command detected: $pattern" + echo " Command: $COMMAND" + exit 2 + fi +done + +# ── Warning patterns ────────────────────────────────────────────────────────── +# These patterns are risky but may be intentional. Log a warning and allow. + +WARNING_PATTERNS=( + "rm -rf" + "git push --force" + "git reset --hard" + "git clean -f" + "chmod -R 777" + "sudo rm" + "DROP TABLE" + "DROP DATABASE" + "truncate" +) + +WARNINGS=0 +for pattern in "${WARNING_PATTERNS[@]}"; do + if echo "$COMMAND" | grep -qi "$pattern"; then + echo "⚠️ Warning: High-risk operation detected: $pattern" + WARNINGS=$((WARNINGS + 1)) + fi +done + +if [ "$WARNINGS" -gt 0 ]; then + echo " Command: $COMMAND" + echo " Proceeding — review the above warnings before continuing." +fi + +# ── Allow ───────────────────────────────────────────────────────────────────── +exit 0 diff --git a/uk/06-hooks/security-scan.sh b/uk/06-hooks/security-scan.sh new file mode 100644 index 0000000..81e3a5b --- /dev/null +++ b/uk/06-hooks/security-scan.sh @@ -0,0 +1,78 @@ +#!/bin/bash +# Security scan on file write +# Hook: PostToolUse:Write +# +# Scans files for hardcoded secrets, API keys, and credentials. +# Outputs a non-blocking warning via additionalContext when issues are found. +# +# Compatible with: macOS, Linux, Windows (Git Bash) + +# Read JSON input from stdin (Claude Code hook protocol) +INPUT=$(cat) + +# Extract file_path using sed (compatible with all platforms including Windows Git Bash) +# Avoids grep -P (not available on Windows Git Bash) and python3 dependency +FILE_PATH=$(echo "$INPUT" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) + +if [ -z "$FILE_PATH" ] || [ ! -f "$FILE_PATH" ]; then + exit 0 +fi + +# Skip binary files, vendor dirs, and build artifacts +case "$FILE_PATH" in + *.png|*.jpg|*.jpeg|*.gif|*.svg|*.ico|*.woff|*.woff2|*.ttf|*.eot) exit 0 ;; + */node_modules/*|*/.git/*|*/dist/*|*/build/*) exit 0 ;; +esac + +ISSUES="" + +# Check for hardcoded passwords +# Handles both JSON format ("password": "value") and code format (password = 'value') +# Use \\n as separator — it is a valid JSON newline escape and passes through printf safely +if grep -qiE '"password"[[:space:]]*:[[:space:]]*"[^"]+"' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded password detected\\n" +elif grep -qiE '(password|passwd|pwd)[[:space:]]*=[[:space:]]*'"'"'[^'"'"']+'"'"'' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded password detected\\n" +fi + +# Check for hardcoded API keys +if grep -qiE '"(api[_-]?key|apikey|access[_-]?token)"[[:space:]]*:[[:space:]]*"[^"]+"' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded API key detected\\n" +fi + +# Check for hardcoded secrets and tokens +if grep -qiE '(secret|token)[[:space:]]*=[[:space:]]*['"'"'"][^'"'"'"]+['"'"'"]' "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Potential hardcoded secret or token detected\\n" +fi + +# Check for private keys +if grep -q "BEGIN.*PRIVATE KEY" "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: Private key detected\\n" +fi + +# Check for AWS keys +if grep -qE "AKIA[0-9A-Z]{16}" "$FILE_PATH" 2>/dev/null; then + ISSUES="${ISSUES}- WARNING: AWS access key detected\\n" +fi + +# Scan with semgrep if available (stdout suppressed to avoid mixing with JSON output) +if command -v semgrep &> /dev/null; then + semgrep --config=auto "$FILE_PATH" --quiet >/dev/null 2>/dev/null +fi + +# Scan with trufflehog if available (stdout suppressed to avoid mixing with JSON output) +if command -v trufflehog &> /dev/null; then + trufflehog filesystem "$FILE_PATH" --only-verified --quiet >/dev/null 2>/dev/null +fi + +# If issues found, output as additionalContext (non-blocking warning) +# Use hookSpecificOutput format required by Claude Code PostToolUse protocol +if [ -n "$ISSUES" ]; then + # Escape file path for JSON (backslash and double-quote) + # ISSUES already uses \\n as separator (valid JSON escape) — only escape double-quotes + SAFE_PATH=$(printf '%s' "$FILE_PATH" | sed 's/\\/\\\\/g; s/"/\\"/g') + SAFE_ISSUES=$(printf '%s' "$ISSUES" | sed 's/"/\\"/g') + printf '{"hookSpecificOutput": {"hookEventName": "PostToolUse", "additionalContext": "Security scan found issues in %s:\\n%sPlease review and use environment variables instead."}}' "$SAFE_PATH" "$SAFE_ISSUES" +fi + +exit 0 diff --git a/uk/06-hooks/validate-prompt.sh b/uk/06-hooks/validate-prompt.sh new file mode 100644 index 0000000..b2701f3 --- /dev/null +++ b/uk/06-hooks/validate-prompt.sh @@ -0,0 +1,54 @@ +#!/bin/bash +# Validate user prompts +# Hook: UserPromptSubmit +# +# Reads the user prompt from stdin JSON and blocks dangerous operations. +# +# Compatible with: macOS, Linux, Windows (Git Bash) + +# Read JSON input from stdin (Claude Code hook protocol) +INPUT=$(cat) + +# Extract the prompt text from JSON input +# Claude Code sends UserPromptSubmit with field "user_prompt" (falls back to "prompt") +PROMPT=$(echo "$INPUT" | sed -n 's/.*"user_prompt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) +if [ -z "$PROMPT" ]; then + PROMPT=$(echo "$INPUT" | sed -n 's/.*"prompt"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1) +fi + +if [ -z "$PROMPT" ]; then + exit 0 +fi + +# Check for dangerous operations +DANGEROUS_PATTERNS=( + "rm -rf /" + "delete database" + "drop database" + "format disk" + "dd if=" +) + +for pattern in "${DANGEROUS_PATTERNS[@]}"; do + if echo "$PROMPT" | grep -qi "$pattern"; then + printf '{"decision": "block", "reason": "Dangerous operation detected: %s"}' "$pattern" + exit 0 + fi +done + +# Check for production deployments +if echo "$PROMPT" | grep -qiE "(deploy|push).*production"; then + if [ ! -f ".deployment-approved" ]; then + echo '{"decision": "block", "reason": "Production deployment requires approval. Create .deployment-approved file to proceed."}' + exit 0 + fi +fi + +# Check for required context in certain operations +if echo "$PROMPT" | grep -qi "refactor"; then + if [ ! -d "tests" ] && [ ! -d "test" ]; then + printf '{"additionalContext": "Warning: Refactoring without tests may be risky. Consider writing tests first."}' + fi +fi + +exit 0 diff --git a/uk/07-plugins/README.md b/uk/07-plugins/README.md new file mode 100644 index 0000000..1942d25 --- /dev/null +++ b/uk/07-plugins/README.md @@ -0,0 +1,953 @@ + + + + + + + Claude How To + + +# Плагіни Claude Code + +Ця папка містить повні приклади плагінів, які обʼєднують кілька функцій Claude Code у цілісні пакети, що встановлюються однією командою. + +## Огляд + +Плагіни Claude Code — це обʼєднані колекції кастомізацій (слеш-команди, субагенти, MCP-сервери та хуки), які встановлюються однією командою. Вони є механізмом розширення найвищого рівня — поєднуючи кілька функцій у цілісні пакети, якими можна ділитися. + +## Архітектура плагінів + +```mermaid +graph TB + A["Plugin"] + B["Slash Commands"] + C["Subagents"] + D["MCP Servers"] + E["Hooks"] + F["Configuration"] + + A -->|bundles| B + A -->|bundles| C + A -->|bundles| D + A -->|bundles| E + A -->|bundles| F +``` + +## Процес завантаження плагіна + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Plugin as Plugin Marketplace + participant Install as Installation + participant SlashCmds as Slash Commands + participant Subagents + participant MCPServers as MCP Servers + participant Hooks + participant Tools as Configured Tools + + User->>Claude: /plugin install pr-review + Claude->>Plugin: Download plugin manifest + Plugin-->>Claude: Return plugin definition + Claude->>Install: Extract components + Install->>SlashCmds: Configure + Install->>Subagents: Configure + Install->>MCPServers: Configure + Install->>Hooks: Configure + SlashCmds-->>Tools: Ready to use + Subagents-->>Tools: Ready to use + MCPServers-->>Tools: Ready to use + Hooks-->>Tools: Ready to use + Tools-->>Claude: Plugin installed ✅ +``` + +## Типи та дистрибуція плагінів + +| Тип | Область | Спільний | Авторитет | Приклади | +|-----|---------|----------|-----------|----------| +| Офіційний | Глобальний | Усі користувачі | Anthropic | PR Review, Security Guidance | +| Спільнота | Публічний | Усі користувачі | Спільнота | DevOps, Data Science | +| Організація | Внутрішній | Члени команди | Компанія | Внутрішні стандарти, інструменти | +| Персональний | Індивідуальний | Один користувач | Розробник | Кастомні робочі процеси | + +## Структура визначення плагіна + +Маніфест плагіна використовує формат JSON у файлі `.claude-plugin/plugin.json`: + +```json +{ + "name": "my-first-plugin", + "description": "A greeting plugin", + "version": "1.0.0", + "author": { + "name": "Your Name" + }, + "homepage": "https://example.com", + "repository": "https://github.com/user/repo", + "license": "MIT" +} +``` + +## Приклад структури плагіна + +``` +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json # Маніфест (назва, опис, версія, автор) +├── commands/ # Навички як Markdown-файли +│ ├── task-1.md +│ ├── task-2.md +│ └── workflows/ +├── agents/ # Визначення кастомних агентів +│ ├── specialist-1.md +│ ├── specialist-2.md +│ └── configs/ +├── skills/ # Навички агентів з файлами SKILL.md +│ ├── skill-1.md +│ └── skill-2.md +├── hooks/ # Обробники подій у hooks.json +│ └── hooks.json +├── .mcp.json # Конфігурації MCP-серверів +├── .lsp.json # Конфігурації LSP-серверів для інтелектуальної роботи з кодом +├── bin/ # Виконувані файли, додані до PATH інструменту Bash поки плагін увімкнено +├── settings.json # Стандартні налаштування при увімкненні плагіна (наразі підтримується лише ключ `agent`) +├── templates/ +│ └── issue-template.md +├── scripts/ +│ ├── helper-1.sh +│ └── helper-2.py +├── docs/ +│ ├── README.md +│ └── USAGE.md +└── tests/ + └── plugin.test.js +``` + +### Конфігурація LSP-сервера + +Плагіни можуть включати підтримку Language Server Protocol (LSP — протокол мовного сервера) для інтелектуальної роботи з кодом у реальному часі. LSP-сервери надають діагностику, навігацію по коду та інформацію про символи під час роботи. + +**Розташування конфігурації**: +- Файл `.lsp.json` у кореневому каталозі плагіна +- Інлайн-ключ `lsp` у `plugin.json` + +#### Довідник полів + +| Поле | Обовʼязкове | Опис | +|------|-------------|------| +| `command` | Так | Бінарний файл LSP-сервера (має бути в PATH) | +| `extensionToLanguage` | Так | Відповідність розширень файлів ідентифікаторам мов | +| `args` | Ні | Аргументи командного рядка для сервера | +| `transport` | Ні | Метод комунікації: `stdio` (за замовчуванням) або `socket` | +| `env` | Ні | Змінні оточення для процесу сервера | +| `initializationOptions` | Ні | Опції, що надсилаються під час ініціалізації LSP | +| `settings` | Ні | Конфігурація робочого простору, що передається серверу | +| `workspaceFolder` | Ні | Перевизначення шляху до папки робочого простору | +| `startupTimeout` | Ні | Максимальний час (мс) очікування запуску сервера | +| `shutdownTimeout` | Ні | Максимальний час (мс) для коректного завершення | +| `restartOnCrash` | Ні | Автоматичний перезапуск при збої сервера | +| `maxRestarts` | Ні | Максимальна кількість спроб перезапуску | + +#### Приклади конфігурацій + +**Go (gopls)**: + +```json +{ + "go": { + "command": "gopls", + "args": ["serve"], + "extensionToLanguage": { + ".go": "go" + } + } +} +``` + +**Python (pyright)**: + +```json +{ + "python": { + "command": "pyright-langserver", + "args": ["--stdio"], + "extensionToLanguage": { + ".py": "python", + ".pyi": "python" + } + } +} +``` + +**TypeScript**: + +```json +{ + "typescript": { + "command": "typescript-language-server", + "args": ["--stdio"], + "extensionToLanguage": { + ".ts": "typescript", + ".tsx": "typescriptreact", + ".js": "javascript", + ".jsx": "javascriptreact" + } + } +} +``` + +#### Доступні LSP-плагіни + +Офіційний маркетплейс включає попередньо налаштовані LSP-плагіни: + +| Плагін | Мова | Бінарний файл сервера | Команда встановлення | +|--------|------|----------------------|---------------------| +| `pyright-lsp` | Python | `pyright-langserver` | `pip install pyright` | +| `typescript-lsp` | TypeScript/JavaScript | `typescript-language-server` | `npm install -g typescript-language-server typescript` | +| `rust-lsp` | Rust | `rust-analyzer` | Встановлення через `rustup component add rust-analyzer` | + +#### Можливості LSP + +Після налаштування LSP-сервери надають: + +- **Миттєва діагностика** — помилки та попередження зʼявляються одразу після редагування +- **Навігація по коду** — перехід до визначення, пошук посилань, реалізацій +- **Інформація при наведенні** — сигнатури типів та документація при наведенні курсора +- **Список символів** — перегляд символів у поточному файлі або робочому просторі + +## Опції плагіна (v2.1.83+) + +Плагіни можуть оголошувати користувацькі опції в маніфесті через `userConfig`. Значення з позначкою `sensitive: true` зберігаються у системному сховищі ключів (keychain), а не в текстових файлах налаштувань: + +```json +{ + "name": "my-plugin", + "version": "1.0.0", + "userConfig": { + "apiKey": { + "description": "API key for the service", + "sensitive": true + }, + "region": { + "description": "Deployment region", + "default": "us-east-1" + } + } +} +``` + +## Постійні дані плагіна (`${CLAUDE_PLUGIN_DATA}`) (v2.1.78+) + +Плагіни мають доступ до каталогу постійного стану через змінну оточення `${CLAUDE_PLUGIN_DATA}`. Цей каталог є унікальним для кожного плагіна та зберігається між сесіями, що робить його придатним для кешів, баз даних та іншого постійного стану: + +```json +{ + "hooks": { + "PostToolUse": [ + { + "command": "node ${CLAUDE_PLUGIN_DATA}/track-usage.js" + } + ] + } +} +``` + +Каталог створюється автоматично при встановленні плагіна. Файли зберігаються до видалення плагіна. + +## Інлайн-плагін через налаштування (`source: 'settings'`) (v2.1.80+) + +Плагіни можна визначати інлайн у файлах налаштувань як записи маркетплейсу з полем `source: 'settings'`. Це дозволяє вбудовувати визначення плагіна безпосередньо, без окремого репозиторію або маркетплейсу: + +```json +{ + "pluginMarketplaces": [ + { + "name": "inline-tools", + "source": "settings", + "plugins": [ + { + "name": "quick-lint", + "source": "./local-plugins/quick-lint" + } + ] + } + ] +} +``` + +## Налаштування плагіна + +Плагіни можуть постачатися з файлом `settings.json` для стандартної конфігурації. Наразі підтримується ключ `agent`, який встановлює основного агента потоку для плагіна: + +```json +{ + "agent": "agents/specialist-1.md" +} +``` + +Коли плагін включає `settings.json`, його стандартні значення застосовуються при встановленні. Користувачі можуть перевизначити ці налаштування у своїй конфігурації проєкту або користувача. + +## Автономний vs плагін-підхід + +| Підхід | Назви команд | Конфігурація | Найкраще для | +|--------|-------------|--------------|--------------| +| **Автономний** | `/hello` | Ручне налаштування в CLAUDE.md | Персональне, специфічне для проєкту | +| **Плагіни** | `/plugin-name:hello` | Автоматичне через plugin.json | Поширення, дистрибуція, командна робота | + +Використовуйте **автономні слеш-команди** для швидких персональних робочих процесів. Використовуйте **плагіни**, коли хочете обʼєднати кілька функцій, поділитися з командою або опублікувати для дистрибуції. + +## Практичні приклади + +### Приклад 1: Плагін PR Review + +**Файл:** `.claude-plugin/plugin.json` + +```json +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "repository": "https://github.com/your-org/pr-review", + "license": "MIT" +} +``` + +**Файл:** `commands/review-pr.md` + +```markdown +--- +name: Review PR +description: Start comprehensive PR review with security and testing checks +--- + +# PR Review + +This command initiates a complete pull request review including: + +1. Security analysis +2. Test coverage verification +3. Documentation updates +4. Code quality checks +5. Performance impact assessment +``` + +**Файл:** `agents/security-reviewer.md` + +```yaml +--- +name: security-reviewer +description: Security-focused code review +tools: read, grep, diff +--- + +# Security Reviewer + +Specializes in finding security vulnerabilities: +- Authentication/authorization issues +- Data exposure +- Injection attacks +- Secure configuration +``` + +**Встановлення:** + +```bash +/plugin install pr-review + +# Результат: +# ✅ 3 слеш-команди встановлено +# ✅ 3 субагенти налаштовано +# ✅ 2 MCP-сервери підключено +# ✅ 4 хуки зареєстровано +# ✅ Готово до використання! +``` + +### Приклад 2: Плагін DevOps + +**Компоненти:** + +``` +devops-automation/ +├── commands/ +│ ├── deploy.md +│ ├── rollback.md +│ ├── status.md +│ └── incident.md +├── agents/ +│ ├── deployment-specialist.md +│ ├── incident-commander.md +│ └── alert-analyzer.md +├── mcp/ +│ ├── github-config.json +│ ├── kubernetes-config.json +│ └── prometheus-config.json +├── hooks/ +│ ├── pre-deploy.js +│ ├── post-deploy.js +│ └── on-error.js +└── scripts/ + ├── deploy.sh + ├── rollback.sh + └── health-check.sh +``` + +### Приклад 3: Плагін документації + +**Обʼєднані компоненти:** + +``` +documentation/ +├── commands/ +│ ├── generate-api-docs.md +│ ├── generate-readme.md +│ ├── sync-docs.md +│ └── validate-docs.md +├── agents/ +│ ├── api-documenter.md +│ ├── code-commentator.md +│ └── example-generator.md +├── mcp/ +│ ├── github-docs-config.json +│ └── slack-announce-config.json +└── templates/ + ├── api-endpoint.md + ├── function-docs.md + └── adr-template.md +``` + +## Маркетплейс плагінів + +Офіційний каталог плагінів, керований Anthropic — `anthropics/claude-plugins-official`. Адміністратори підприємств також можуть створювати приватні маркетплейси для внутрішньої дистрибуції. + +```mermaid +graph TB + A["Plugin Marketplace"] + B["Official
anthropics/claude-plugins-official"] + C["Community
Marketplace"] + D["Enterprise
Private Registry"] + + A --> B + A --> C + A --> D + + B -->|Categories| B1["Development"] + B -->|Categories| B2["DevOps"] + B -->|Categories| B3["Documentation"] + + C -->|Search| C1["DevOps Automation"] + C -->|Search| C2["Mobile Dev"] + C -->|Search| C3["Data Science"] + + D -->|Internal| D1["Company Standards"] + D -->|Internal| D2["Legacy Systems"] + D -->|Internal| D3["Compliance"] + + style A fill:#e1f5fe,stroke:#333,color:#333 + style B fill:#e8f5e9,stroke:#333,color:#333 + style C fill:#f3e5f5,stroke:#333,color:#333 + style D fill:#fff3e0,stroke:#333,color:#333 +``` + +### Конфігурація маркетплейсу + +Підприємства та просунуті користувачі можуть контролювати поведінку маркетплейсу через налаштування: + +| Налаштування | Опис | +|-------------|------| +| `extraKnownMarketplaces` | Додати додаткові джерела маркетплейсу крім стандартних | +| `strictKnownMarketplaces` | Контролювати, які маркетплейси дозволено додавати користувачам | +| `deniedPlugins` | Блок-список для запобігання встановленню конкретних плагінів (керований адміністратором) | + +### Додаткові функції маркетплейсу + +- **Стандартний таймаут git**: Збільшено з 30с до 120с для великих репозиторіїв плагінів +- **Кастомні npm-реєстри**: Плагіни можуть вказувати URL кастомних npm-реєстрів для розвʼязання залежностей +- **Фіксація версій**: Закріплення плагінів за конкретними версіями для відтворюваних середовищ + +### Схема визначення маркетплейсу + +Маркетплейси плагінів визначаються у `.claude-plugin/marketplace.json`: + +```json +{ + "name": "my-team-plugins", + "owner": "my-org", + "plugins": [ + { + "name": "code-standards", + "source": "./plugins/code-standards", + "description": "Enforce team coding standards", + "version": "1.2.0", + "author": "platform-team" + }, + { + "name": "deploy-helper", + "source": { + "source": "github", + "repo": "my-org/deploy-helper", + "ref": "v2.0.0" + }, + "description": "Deployment automation workflows" + } + ] +} +``` + +| Поле | Обовʼязкове | Опис | +|------|-------------|------| +| `name` | Так | Назва маркетплейсу в kebab-case | +| `owner` | Так | Організація або користувач, що підтримує маркетплейс | +| `plugins` | Так | Масив записів плагінів | +| `plugins[].name` | Так | Назва плагіна (kebab-case) | +| `plugins[].source` | Так | Джерело плагіна (рядок шляху або обʼєкт джерела) | +| `plugins[].description` | Ні | Короткий опис плагіна | +| `plugins[].version` | Ні | Рядок семантичної версії | +| `plugins[].author` | Ні | Імʼя автора плагіна | + +### Типи джерел плагінів + +Плагіни можуть завантажуватися з кількох місць: + +| Джерело | Синтаксис | Приклад | +|---------|-----------|---------| +| **Відносний шлях** | Рядок шляху | `"./plugins/my-plugin"` | +| **GitHub** | `{ "source": "github", "repo": "owner/repo" }` | `{ "source": "github", "repo": "acme/lint-plugin", "ref": "v1.0" }` | +| **Git URL** | `{ "source": "url", "url": "..." }` | `{ "source": "url", "url": "https://git.internal/plugin.git" }` | +| **Підкаталог Git** | `{ "source": "git-subdir", "url": "...", "path": "..." }` | `{ "source": "git-subdir", "url": "https://github.com/org/monorepo.git", "path": "packages/plugin" }` | +| **npm** | `{ "source": "npm", "package": "..." }` | `{ "source": "npm", "package": "@acme/claude-plugin", "version": "^2.0" }` | +| **pip** | `{ "source": "pip", "package": "..." }` | `{ "source": "pip", "package": "claude-data-plugin", "version": ">=1.0" }` | + +Джерела GitHub та git підтримують необовʼязкові поля `ref` (гілка/тег) та `sha` (хеш коміту) для фіксації версій. + +### Методи дистрибуції + +**GitHub (рекомендовано)**: +```bash +# Користувачі додають ваш маркетплейс +/plugin marketplace add owner/repo-name +``` + +**Інші git-сервіси** (потрібен повний URL): +```bash +/plugin marketplace add https://gitlab.com/org/marketplace-repo.git +``` + +**Приватні репозиторії**: Підтримуються через git credential helpers або токени оточення. Користувачі повинні мати доступ на читання до репозиторію. + +**Подання до офіційного маркетплейсу**: Подавайте плагіни до курованого Anthropic маркетплейсу для ширшої дистрибуції через [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit) або [platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit). + +### Суворий режим (strict mode) + +Контроль взаємодії визначень маркетплейсу з локальними файлами `plugin.json`: + +| Налаштування | Поведінка | +|-------------|----------| +| `strict: true` (за замовчуванням) | Локальний `plugin.json` є авторитетним; запис маркетплейсу доповнює його | +| `strict: false` | Запис маркетплейсу є повним визначенням плагіна | + +**Обмеження організації** через `strictKnownMarketplaces`: + +| Значення | Ефект | +|----------|-------| +| Не встановлено | Без обмежень — користувачі можуть додавати будь-який маркетплейс | +| Порожній масив `[]` | Блокування — маркетплейси заборонені | +| Масив патернів | Білий список — дозволено лише маркетплейси, що відповідають патернам | + +```json +{ + "strictKnownMarketplaces": [ + "my-org/*", + "github.com/trusted-vendor/*" + ] +} +``` + +> **Увага**: У суворому режимі з `strictKnownMarketplaces` користувачі можуть встановлювати плагіни лише з маркетплейсів білого списку. Це корисно для корпоративних середовищ, що вимагають контрольованої дистрибуції плагінів. + +## Встановлення та життєвий цикл плагіна + +```mermaid +graph LR + A["Discover"] -->|Browse| B["Marketplace"] + B -->|Select| C["Plugin Page"] + C -->|View| D["Components"] + D -->|Install| E["/plugin install"] + E -->|Extract| F["Configure"] + F -->|Activate| G["Use"] + G -->|Check| H["Update"] + H -->|Available| G + G -->|Done| I["Disable"] + I -->|Later| J["Enable"] + J -->|Back| G +``` + +## Порівняння функцій плагінів + +| Функція | Слеш-команда | Навичка | Субагент | Плагін | +|---------|-------------|---------|----------|--------| +| **Встановлення** | Ручне копіювання | Ручне копіювання | Ручна конфігурація | Одна команда | +| **Час налаштування** | 5 хвилин | 10 хвилин | 15 хвилин | 2 хвилини | +| **Обʼєднання** | Один файл | Один файл | Один файл | Кілька | +| **Версіонування** | Ручне | Ручне | Ручне | Автоматичне | +| **Поширення в команді** | Копіювання файлу | Копіювання файлу | Копіювання файлу | ID встановлення | +| **Оновлення** | Ручне | Ручне | Ручне | Автоматично доступне | +| **Залежності** | Немає | Немає | Немає | Можуть включати | +| **Маркетплейс** | Ні | Ні | Ні | Так | +| **Дистрибуція** | Репозиторій | Репозиторій | Репозиторій | Маркетплейс | + +## CLI-команди плагінів + +Усі операції з плагінами доступні як CLI-команди: + +```bash +claude plugin install @ # Встановити з маркетплейсу +claude plugin uninstall # Видалити плагін +claude plugin list # Список встановлених плагінів +claude plugin enable # Увімкнути вимкнений плагін +claude plugin disable # Вимкнути плагін +claude plugin validate # Валідація структури плагіна +``` + +## Методи встановлення + +### З маркетплейсу +```bash +/plugin install plugin-name +# або з CLI: +claude plugin install plugin-name@marketplace-name +``` + +### Увімкнення / Вимкнення (з автовизначенням області) +```bash +/plugin enable plugin-name +/plugin disable plugin-name +``` + +### Локальний плагін (для розробки) +```bash +# CLI-прапорець для локального тестування (повторюваний для кількох плагінів) +claude --plugin-dir ./path/to/plugin +claude --plugin-dir ./plugin-a --plugin-dir ./plugin-b +``` + +### З Git-репозиторію +```bash +/plugin install github:username/repo +``` + +## Коли створювати плагін + +```mermaid +graph TD + A["Should I create a plugin?"] + A -->|Need multiple components| B{"Multiple commands
or subagents
or MCPs?"} + B -->|Yes| C["✅ Create Plugin"] + B -->|No| D["Use Individual Feature"] + A -->|Team workflow| E{"Share with
team?"} + E -->|Yes| C + E -->|No| F["Keep as Local Setup"] + A -->|Complex setup| G{"Needs auto
configuration?"} + G -->|Yes| C + G -->|No| D +``` + +### Випадки використання плагінів + +| Випадок | Рекомендація | Чому | +|---------|-------------|------| +| **Онбординг команди** | ✅ Плагін | Миттєве налаштування, усі конфігурації | +| **Налаштування фреймворку** | ✅ Плагін | Обʼєднує команди, специфічні для фреймворку | +| **Корпоративні стандарти** | ✅ Плагін | Централізована дистрибуція, контроль версій | +| **Швидка автоматизація** | ❌ Команда | Надмірна складність | +| **Одна предметна область** | ❌ Навичка | Занадто важко, використовуйте навичку | +| **Спеціалізований аналіз** | ❌ Субагент | Створіть вручну або використовуйте навичку | +| **Доступ до живих даних** | ❌ MCP | Автономний, не обʼєднуйте | + +## Тестування плагіна + +Перед публікацією протестуйте плагін локально за допомогою CLI-прапорця `--plugin-dir` (повторюваний для кількох плагінів): + +```bash +claude --plugin-dir ./my-plugin +claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin +``` + +Це запускає Claude Code з завантаженим плагіном, дозволяючи: +- Перевірити доступність усіх слеш-команд +- Протестувати коректну роботу субагентів та агентів +- Підтвердити правильне підключення MCP-серверів +- Валідувати виконання хуків +- Перевірити конфігурації LSP-серверів +- Виявити помилки конфігурації + +## Гаряче перезавантаження (Hot-Reload) + +Плагіни підтримують гаряче перезавантаження під час розробки. При зміні файлів плагіна Claude Code може автоматично виявляти зміни. Також можна примусово перезавантажити командою: + +```bash +/reload-plugins +``` + +Це повторно зчитує всі маніфести плагінів, команди, агентів, навички, хуки та конфігурації MCP/LSP без перезапуску сесії. + +## Керовані налаштування для плагінів + +Адміністратори можуть контролювати поведінку плагінів в організації через керовані налаштування (managed settings): + +| Налаштування | Опис | +|-------------|------| +| `enabledPlugins` | Білий список плагінів, увімкнених за замовчуванням | +| `deniedPlugins` | Блок-список плагінів, які не можна встановити | +| `extraKnownMarketplaces` | Додаткові джерела маркетплейсу крім стандартних | +| `strictKnownMarketplaces` | Обмеження маркетплейсів, які дозволено додавати користувачам | +| `allowedChannelPlugins` | Контроль дозволених плагінів для кожного каналу випуску | + +Ці налаштування можна застосувати на рівні організації через файли керованої конфігурації, і вони мають пріоритет над налаштуваннями рівня користувача. + +## Безпека плагінів + +Субагенти плагінів працюють в обмеженій пісочниці (sandbox). Наступні ключі frontmatter **заборонені** у визначеннях субагентів плагінів: + +- `hooks` — субагенти не можуть реєструвати обробники подій +- `mcpServers` — субагенти не можуть налаштовувати MCP-сервери +- `permissionMode` — субагенти не можуть перевизначати модель дозволів + +Це гарантує, що плагіни не можуть підвищити привілеї або модифікувати хост-середовище за межами оголошеної області. + +## Публікація плагіна + +**Кроки для публікації:** + +1. Створити структуру плагіна з усіма компонентами +2. Написати маніфест `.claude-plugin/plugin.json` +3. Створити `README.md` з документацією +4. Протестувати локально за допомогою `claude --plugin-dir ./my-plugin` +5. Подати до маркетплейсу плагінів +6. Пройти перевірку та затвердження +7. Публікація в маркетплейсі +8. Користувачі можуть встановити однією командою + +**Приклад подання:** + +```markdown +# PR Review Plugin + +## Description +Complete PR review workflow with security, testing, and documentation checks. + +## What's Included +- 3 slash commands for different review types +- 3 specialized subagents +- GitHub and CodeQL MCP integration +- Automated security scanning hooks + +## Installation +```bash +/plugin install pr-review +``` + +## Features +✅ Security analysis +✅ Test coverage checking +✅ Documentation verification +✅ Code quality assessment +✅ Performance impact analysis + +## Usage +```bash +/review-pr +/check-security +/check-tests +``` + +## Requirements +- Claude Code 1.0+ +- GitHub access +- CodeQL (optional) +``` + +## Плагін vs ручна конфігурація + +**Ручне налаштування (2+ години):** +- Встановити слеш-команди одну за одною +- Створити субагентів окремо +- Налаштувати MCP окремо +- Встановити хуки вручну +- Задокументувати все +- Поширити в команді (сподіватися, що налаштують правильно) + +**З плагіном (2 хвилини):** +```bash +/plugin install pr-review +# ✅ Все встановлено та налаштовано +# ✅ Готово до використання одразу +# ✅ Команда може відтворити точну конфігурацію +``` + +## Найкращі практики + +### Рекомендовано ✅ +- Використовуйте зрозумілі, описові назви плагінів +- Включайте вичерпний README +- Версіонуйте плагін правильно (semver — семантичне версіонування) +- Тестуйте всі компоненти разом +- Документуйте вимоги чітко +- Надавайте приклади використання +- Включайте обробку помилок +- Тегуйте належним чином для виявлення +- Підтримуйте зворотну сумісність +- Тримайте плагіни зосередженими та цілісними +- Включайте вичерпні тести +- Документуйте всі залежності + +### Не рекомендовано ❌ +- Не обʼєднуйте неповʼязані функції +- Не зашивайте облікові дані в код +- Не пропускайте тестування +- Не забувайте про документацію +- Не створюйте надлишкових плагінів +- Не ігноруйте версіонування +- Не ускладнюйте залежності компонентів +- Не забувайте обробляти помилки коректно + +## Інструкції зі встановлення + +### Встановлення з маркетплейсу + +1. **Перегляд доступних плагінів:** + ```bash + /plugin list + ``` + +2. **Деталі плагіна:** + ```bash + /plugin info plugin-name + ``` + +3. **Встановлення плагіна:** + ```bash + /plugin install plugin-name + ``` + +### Встановлення з локального шляху + +```bash +/plugin install ./path/to/plugin-directory +``` + +### Встановлення з GitHub + +```bash +/plugin install github:username/repo +``` + +### Список встановлених плагінів + +```bash +/plugin list --installed +``` + +### Оновлення плагіна + +```bash +/plugin update plugin-name +``` + +### Вимкнення/Увімкнення плагіна + +```bash +# Тимчасове вимкнення +/plugin disable plugin-name + +# Повторне увімкнення +/plugin enable plugin-name +``` + +### Видалення плагіна + +```bash +/plugin uninstall plugin-name +``` + +## Повʼязані концепції + +Наступні функції Claude Code працюють разом з плагінами: + +- **[Слеш-команди](../01-slash-commands/)** — окремі команди, обʼєднані в плагіни +- **[Памʼять](../02-memory/)** — постійний контекст для плагінів +- **[Навички](../03-skills/)** — предметна експертиза, яку можна обгорнути в плагіни +- **[Субагенти](../04-subagents/)** — спеціалізовані агенти як компоненти плагінів +- **[MCP-сервери](../05-mcp/)** — інтеграції Model Context Protocol, обʼєднані в плагіни +- **[Хуки](../06-hooks/)** — обробники подій, що запускають робочі процеси плагінів + +## Повний приклад робочого процесу + +### Повний робочий процес плагіна PR Review + +``` +1. Користувач: /review-pr + +2. Плагін виконує: + ├── pre-review.js хук валідує git-репо + ├── GitHub MCP отримує дані PR + ├── security-reviewer субагент аналізує безпеку + ├── test-checker субагент перевіряє покриття + └── performance-analyzer субагент перевіряє продуктивність + +3. Результати синтезуються та представляються: + ✅ Безпека: Критичних проблем не виявлено + ⚠️ Тестування: Покриття 65% (рекомендовано 80%+) + ✅ Продуктивність: Значного впливу немає + 📝 Надано 12 рекомендацій +``` + +## Усунення несправностей + +### Плагін не встановлюється +- Перевірте сумісність версії Claude Code: `/version` +- Перевірте синтаксис `plugin.json` валідатором JSON +- Перевірте підключення до інтернету (для віддалених плагінів) +- Перевірте дозволи: `ls -la plugin/` + +### Компоненти не завантажуються +- Переконайтеся, що шляхи в `plugin.json` відповідають фактичній структурі каталогів +- Перевірте дозволи файлів: `chmod +x scripts/` +- Перегляньте синтаксис файлів компонентів +- Перевірте журнали: `/plugin debug plugin-name` + +### Збій підключення MCP +- Переконайтеся, що змінні оточення встановлені правильно +- Перевірте встановлення та працездатність MCP-сервера +- Протестуйте підключення MCP окремо за допомогою `/mcp test` +- Перегляньте конфігурацію MCP у каталозі `mcp/` + +### Команди недоступні після встановлення +- Переконайтеся, що плагін встановлено успішно: `/plugin list --installed` +- Перевірте, чи плагін увімкнено: `/plugin status plugin-name` +- Перезапустіть Claude Code: `exit` та відкрийте знову +- Перевірте конфлікти назв з існуючими командами + +### Проблеми з виконанням хуків +- Переконайтеся, що файли хуків мають правильні дозволи +- Перевірте синтаксис хуків та назви подій +- Перегляньте журнали хуків для деталей помилок +- Протестуйте хуки вручну, якщо можливо + +## Додаткові ресурси + +- [Офіційна документація плагінів](https://code.claude.com/docs/en/plugins) +- [Каталог плагінів](https://code.claude.com/docs/en/discover-plugins) +- [Маркетплейси плагінів](https://code.claude.com/docs/en/plugin-marketplaces) +- [Довідник плагінів](https://code.claude.com/docs/en/plugins-reference) +- [Довідник MCP-серверів](https://modelcontextprotocol.io/) +- [Посібник конфігурації субагентів](../04-subagents/README.md) +- [Довідник системи хуків](../06-hooks/README.md) + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/07-plugins/devops-automation/.claude-plugin/plugin.json b/uk/07-plugins/devops-automation/.claude-plugin/plugin.json new file mode 100644 index 0000000..3b7bf75 --- /dev/null +++ b/uk/07-plugins/devops-automation/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "devops-automation", + "version": "1.0.0", + "description": "Complete DevOps automation for deployment, monitoring, and incident response", + "author": { + "name": "Community" + }, + "license": "MIT" +} diff --git a/uk/07-plugins/devops-automation/README.md b/uk/07-plugins/devops-automation/README.md new file mode 100644 index 0000000..652b380 --- /dev/null +++ b/uk/07-plugins/devops-automation/README.md @@ -0,0 +1,107 @@ + + + Claude How To + + +# Плагін DevOps Automation + +Повна автоматизація DevOps для розгортання, моніторингу та реагування на інциденти. + +## Функції + +✅ Автоматизовані розгортання +✅ Процедури відкату +✅ Моніторинг стану системи +✅ Робочі процеси реагування на інциденти +✅ Інтеграція з Kubernetes + +## Встановлення + +```bash +/plugin install devops-automation +``` + +## Що включено + +### Слеш-команди +- `/deploy` — Розгортання на продакшен або стейджинг +- `/rollback` — Відкат до попередньої версії +- `/status` — Перевірка стану системи +- `/incident` — Обробка інцидентів на продакшені + +### Субагенти +- `deployment-specialist` — Операції розгортання +- `incident-commander` — Координація інцидентів +- `alert-analyzer` — Аналіз стану системи + +### MCP-сервери +- Інтеграція з Kubernetes + +### Скрипти +- `deploy.sh` — Автоматизація розгортання +- `rollback.sh` — Автоматизація відкату +- `health-check.sh` — Утиліти перевірки стану + +### Хуки +- `pre-deploy.js` — Передрозгортальна валідація +- `post-deploy.js` — Післярозгортальні завдання + +## Використання + +### Розгортання на стейджинг +``` +/deploy staging +``` + +### Розгортання на продакшен +``` +/deploy production +``` + +### Відкат +``` +/rollback production +``` + +### Перевірка стану +``` +/status +``` + +### Обробка інциденту +``` +/incident +``` + +## Вимоги + +- Claude Code 1.0+ +- Kubernetes CLI (kubectl) +- Налаштований доступ до кластера + +## Конфігурація + +Налаштуйте конфіг Kubernetes: +```bash +export KUBECONFIG=~/.kube/config +``` + +## Приклад робочого процесу + +``` +User: /deploy production + +Claude: +1. Запускає pre-deploy хук (валідація kubectl, з'єднання з кластером) +2. Делегує субагенту deployment-specialist +3. Запускає скрипт deploy.sh +4. Моніторить прогрес розгортання через Kubernetes MCP +5. Запускає post-deploy хук (очікування подів, smoke-тести) +6. Надає підсумок розгортання + +Результат: +✅ Розгортання завершено +📦 Версія: v2.1.0 +🚀 Поди: 3/3 готові +⏱️ Час: 2хв 34с +``` diff --git a/uk/07-plugins/devops-automation/agents/alert-analyzer.md b/uk/07-plugins/devops-automation/agents/alert-analyzer.md new file mode 100644 index 0000000..cea8b9f --- /dev/null +++ b/uk/07-plugins/devops-automation/agents/alert-analyzer.md @@ -0,0 +1,14 @@ +--- +name: alert-analyzer +description: Аналізує алерти моніторингу та метрики системи +tools: read, grep, bash +--- + +# Аналізатор алертів + +Аналізує стан системи та алерти: +- Кореляція алертів +- Аналіз трендів +- Визначення першопричини +- Візуалізація метрик +- Проактивне виявлення проблем diff --git a/uk/07-plugins/devops-automation/agents/deployment-specialist.md b/uk/07-plugins/devops-automation/agents/deployment-specialist.md new file mode 100644 index 0000000..4871c26 --- /dev/null +++ b/uk/07-plugins/devops-automation/agents/deployment-specialist.md @@ -0,0 +1,14 @@ +--- +name: deployment-specialist +description: Обробляє всі операції розгортання +tools: read, write, bash, grep +--- + +# Спеціаліст з розгортання + +Експерт з операцій розгортання: +- Blue-green розгортання +- Канаркові релізи +- Процедури відкату +- Перевірки стану +- Міграції бази даних diff --git a/uk/07-plugins/devops-automation/agents/incident-commander.md b/uk/07-plugins/devops-automation/agents/incident-commander.md new file mode 100644 index 0000000..4610d7a --- /dev/null +++ b/uk/07-plugins/devops-automation/agents/incident-commander.md @@ -0,0 +1,14 @@ +--- +name: incident-commander +description: Координує реагування на інциденти +tools: read, write, bash, grep +--- + +# Командир інцидентів + +Керує реагуванням на інциденти: +- Оцінка серйозності +- Координація команди +- Оновлення статусу +- Відстеження розв'язання +- Фасилітація post-mortem diff --git a/uk/07-plugins/devops-automation/commands/deploy.md b/uk/07-plugins/devops-automation/commands/deploy.md new file mode 100644 index 0000000..e8a5dba --- /dev/null +++ b/uk/07-plugins/devops-automation/commands/deploy.md @@ -0,0 +1,15 @@ +--- +name: Deploy +description: Розгортання застосунку на продакшен або стейджинг +--- + +# Розгортання застосунку + +Виконання робочого процесу розгортання: + +1. Запуск передрозгортальних перевірок +2. Збірка застосунку +3. Запуск тестів +4. Розгортання на цільове середовище +5. Запуск перевірок стану +6. Повідомлення команди в Slack diff --git a/uk/07-plugins/devops-automation/commands/incident.md b/uk/07-plugins/devops-automation/commands/incident.md new file mode 100644 index 0000000..a20dbd3 --- /dev/null +++ b/uk/07-plugins/devops-automation/commands/incident.md @@ -0,0 +1,16 @@ +--- +name: Incident Response +description: Обробка інцидентів на продакшені зі структурованим реагуванням +--- + +# Реагування на інциденти + +Структурований процес реагування на інциденти: + +1. Створення запису інциденту +2. Оцінка серйозності та впливу +3. Повідомлення чергової команди +4. Збір діагностичної інформації +5. Координація зусиль з реагування +6. Документування розв'язання +7. Планування post-mortem diff --git a/uk/07-plugins/devops-automation/commands/rollback.md b/uk/07-plugins/devops-automation/commands/rollback.md new file mode 100644 index 0000000..d8998b2 --- /dev/null +++ b/uk/07-plugins/devops-automation/commands/rollback.md @@ -0,0 +1,14 @@ +--- +name: Rollback +description: Відкат до попереднього розгортання +--- + +# Відкат розгортання + +Відкат до попередньої стабільної версії: + +1. Визначення попереднього розгортання +2. Перевірка працездатності цілі відкату +3. Виконання процедури відкату +4. Запуск перевірок стану +5. Повідомлення команди diff --git a/uk/07-plugins/devops-automation/commands/status.md b/uk/07-plugins/devops-automation/commands/status.md new file mode 100644 index 0000000..3b8b2a7 --- /dev/null +++ b/uk/07-plugins/devops-automation/commands/status.md @@ -0,0 +1,15 @@ +--- +name: System Status +description: Перевірка загального стану та працездатності системи +--- + +# Перевірка стану системи + +Перевірка стану системи по всіх сервісах: + +1. Запит статусу подів Kubernetes +2. Перевірка з'єднань з базою даних +3. Моніторинг часу відповіді API +4. Перегляд частоти помилок +5. Перевірка використання ресурсів +6. Звіт про загальний стан diff --git a/uk/07-plugins/devops-automation/hooks/post-deploy.js b/uk/07-plugins/devops-automation/hooks/post-deploy.js new file mode 100644 index 0000000..5c6537e --- /dev/null +++ b/uk/07-plugins/devops-automation/hooks/post-deploy.js @@ -0,0 +1,34 @@ +#!/usr/bin/env node + +/** + * Post-deployment hook + * Runs after deployment completes + */ + +async function postDeploy() { + console.log('Running post-deployment tasks...'); + + const { execSync } = require('child_process'); + + // Wait for pods to be ready + console.log('Waiting for pods to be ready...'); + try { + execSync('kubectl wait --for=condition=ready pod -l app=myapp --timeout=300s', { + stdio: 'inherit' + }); + } catch (error) { + console.error('❌ Pods failed to become ready'); + process.exit(1); + } + + // Run smoke tests + console.log('Running smoke tests...'); + // Add your smoke test commands here + + console.log('✅ Post-deployment tasks complete'); +} + +postDeploy().catch(error => { + console.error('Post-deploy hook failed:', error); + process.exit(1); +}); diff --git a/uk/07-plugins/devops-automation/hooks/pre-deploy.js b/uk/07-plugins/devops-automation/hooks/pre-deploy.js new file mode 100644 index 0000000..98983a4 --- /dev/null +++ b/uk/07-plugins/devops-automation/hooks/pre-deploy.js @@ -0,0 +1,35 @@ +#!/usr/bin/env node + +/** + * Pre-deployment hook + * Validates environment and prerequisites before deployment + */ + +async function preDeploy() { + console.log('Running pre-deployment checks...'); + + const { execSync } = require('child_process'); + + // Check if kubectl is installed + try { + execSync('which kubectl', { stdio: 'pipe' }); + } catch (error) { + console.error('❌ kubectl not found. Please install Kubernetes CLI.'); + process.exit(1); + } + + // Check if connected to cluster + try { + execSync('kubectl cluster-info', { stdio: 'pipe' }); + } catch (error) { + console.error('❌ Not connected to Kubernetes cluster'); + process.exit(1); + } + + console.log('✅ Pre-deployment checks passed'); +} + +preDeploy().catch(error => { + console.error('Pre-deploy hook failed:', error); + process.exit(1); +}); diff --git a/uk/07-plugins/devops-automation/mcp/kubernetes-config.json b/uk/07-plugins/devops-automation/mcp/kubernetes-config.json new file mode 100644 index 0000000..3f3b842 --- /dev/null +++ b/uk/07-plugins/devops-automation/mcp/kubernetes-config.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "kubernetes": { + "command": "npx", + "args": ["@modelcontextprotocol/server-kubernetes"], + "env": { + "KUBECONFIG": "${KUBECONFIG}" + } + } + } +} diff --git a/uk/07-plugins/devops-automation/scripts/deploy.sh b/uk/07-plugins/devops-automation/scripts/deploy.sh new file mode 100644 index 0000000..9acf5bd --- /dev/null +++ b/uk/07-plugins/devops-automation/scripts/deploy.sh @@ -0,0 +1,28 @@ +#!/bin/bash +set -e + +echo "🚀 Starting deployment..." + +# Load environment +ENV=${1:-staging} +echo "📦 Target environment: $ENV" + +# Pre-deployment checks +echo "✓ Running pre-deployment checks..." +npm run lint +npm test + +# Build +echo "🔨 Building application..." +npm run build + +# Deploy +echo "🚢 Deploying to $ENV..." +kubectl apply -f k8s/$ENV/ + +# Health check +echo "🏥 Running health checks..." +sleep 10 +curl -f http://api.$ENV.example.com/health + +echo "✅ Deployment complete!" diff --git a/uk/07-plugins/devops-automation/scripts/health-check.sh b/uk/07-plugins/devops-automation/scripts/health-check.sh new file mode 100644 index 0000000..2ded117 --- /dev/null +++ b/uk/07-plugins/devops-automation/scripts/health-check.sh @@ -0,0 +1,30 @@ +#!/bin/bash + +echo "🏥 System Health Check" +echo "====================" + +ENV=${1:-production} + +# Check API +echo -n "API: " +if curl -sf http://api.$ENV.example.com/health > /dev/null; then + echo "✅ Healthy" +else + echo "❌ Unhealthy" +fi + +# Check Database +echo -n "Database: " +if pg_isready -h db.$ENV.example.com > /dev/null 2>&1; then + echo "✅ Healthy" +else + echo "❌ Unhealthy" +fi + +# Check Pods +echo -n "Kubernetes Pods: " +PODS_READY=$(kubectl get pods -n $ENV --no-headers | grep "Running" | wc -l) +PODS_TOTAL=$(kubectl get pods -n $ENV --no-headers | wc -l) +echo "$PODS_READY/$PODS_TOTAL ready" + +echo "====================" diff --git a/uk/07-plugins/devops-automation/scripts/rollback.sh b/uk/07-plugins/devops-automation/scripts/rollback.sh new file mode 100644 index 0000000..0fe0cc2 --- /dev/null +++ b/uk/07-plugins/devops-automation/scripts/rollback.sh @@ -0,0 +1,25 @@ +#!/bin/bash +set -e + +echo "⏪ Starting rollback..." + +ENV=${1:-staging} +echo "📦 Target environment: $ENV" + +# Get previous deployment +PREVIOUS=$(kubectl rollout history deployment/app -n $ENV | tail -2 | head -1 | awk '{print $1}') +echo "🔄 Rolling back to revision: $PREVIOUS" + +# Execute rollback +kubectl rollout undo deployment/app -n $ENV + +# Wait for rollback +echo "⏳ Waiting for rollback to complete..." +kubectl rollout status deployment/app -n $ENV + +# Health check +echo "🏥 Running health checks..." +sleep 5 +curl -f http://api.$ENV.example.com/health + +echo "✅ Rollback complete!" diff --git a/uk/07-plugins/documentation/.claude-plugin/plugin.json b/uk/07-plugins/documentation/.claude-plugin/plugin.json new file mode 100644 index 0000000..b1d520d --- /dev/null +++ b/uk/07-plugins/documentation/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "documentation", + "version": "1.0.0", + "description": "Comprehensive documentation generation and maintenance", + "author": { + "name": "Community" + }, + "license": "MIT" +} diff --git a/uk/07-plugins/documentation/README.md b/uk/07-plugins/documentation/README.md new file mode 100644 index 0000000..2f07044 --- /dev/null +++ b/uk/07-plugins/documentation/README.md @@ -0,0 +1,119 @@ + + + Claude How To + + +# Плагін Documentation + +Комплексна генерація та підтримка документації для вашого проєкту. + +## Функції + +✅ Генерація API-документації +✅ Створення та оновлення README +✅ Синхронізація документації +✅ Покращення коментарів коду +✅ Генерація прикладів + +## Встановлення + +```bash +/plugin install documentation +``` + +## Що включено + +### Слеш-команди +- `/generate-api-docs` — Генерація API-документації +- `/generate-readme` — Створення або оновлення README +- `/sync-docs` — Синхронізація документації зі змінами коду +- `/validate-docs` — Валідація документації + +### Субагенти +- `api-documenter` — Спеціаліст з API-документації +- `code-commentator` — Покращення коментарів коду +- `example-generator` — Створення прикладів коду + +### Шаблони +- `api-endpoint.md` — Шаблон документації ендпоінту API +- `function-docs.md` — Шаблон документації функції +- `adr-template.md` — Шаблон Architecture Decision Record + +### MCP-сервери +- Інтеграція з GitHub для синхронізації документації + +## Використання + +### Генерація API-документації +``` +/generate-api-docs +``` + +### Створення README +``` +/generate-readme +``` + +### Синхронізація документації +``` +/sync-docs +``` + +### Валідація документації +``` +/validate-docs +``` + +## Вимоги + +- Claude Code 1.0+ +- Доступ до GitHub (опціонально) + +## Приклад робочого процесу + +``` +User: /generate-api-docs + +Claude: +1. Сканує всі API-ендпоінти в /src/api/ +2. Делегує субагенту api-documenter +3. Витягує сигнатури функцій та JSDoc +4. Організує за модулями/ендпоінтами +5. Використовує шаблон api-endpoint.md +6. Генерує комплексну markdown-документацію +7. Включає приклади curl, JavaScript та Python + +Результат: +✅ API-документація згенерована +📄 Створені файли: + - docs/api/users.md + - docs/api/auth.md + - docs/api/products.md +📊 Покриття: 23/23 ендпоінти задокументовано +``` + +## Використання шаблонів + +### Шаблон ендпоінту API +Використовуйте для документування REST API ендпоінтів з повними прикладами. + +### Шаблон документації функції +Використовуйте для документування окремих функцій/методів. + +### Шаблон ADR +Використовуйте для документування архітектурних рішень. + +## Конфігурація + +Налаштуйте GitHub-токен для синхронізації документації: +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## Найкращі практики + +- Тримайте документацію близько до коду +- Оновлюйте документацію разом зі змінами коду +- Включайте практичні приклади +- Регулярно валідуйте +- Використовуйте шаблони для консистентності diff --git a/uk/07-plugins/documentation/agents/api-documenter.md b/uk/07-plugins/documentation/agents/api-documenter.md new file mode 100644 index 0000000..50848fc --- /dev/null +++ b/uk/07-plugins/documentation/agents/api-documenter.md @@ -0,0 +1,14 @@ +--- +name: api-documenter +description: Спеціаліст з API-документації +tools: read, write, grep +--- + +# API-документатор + +Створює комплексну API-документацію: +- Документація ендпоінтів +- Описи параметрів +- Схеми відповідей +- Приклади коду (curl, JS, Python) +- Коди помилок diff --git a/uk/07-plugins/documentation/agents/code-commentator.md b/uk/07-plugins/documentation/agents/code-commentator.md new file mode 100644 index 0000000..9d01e52 --- /dev/null +++ b/uk/07-plugins/documentation/agents/code-commentator.md @@ -0,0 +1,14 @@ +--- +name: code-commentator +description: Спеціаліст з коментарів коду та інлайн-документації +tools: read, write, edit +--- + +# Коментатор коду + +Покращує документацію коду: +- JSDoc/docstring коментарі +- Інлайн-пояснення +- Описи параметрів +- Документація типів повернення +- Приклади використання diff --git a/uk/07-plugins/documentation/agents/example-generator.md b/uk/07-plugins/documentation/agents/example-generator.md new file mode 100644 index 0000000..59a5800 --- /dev/null +++ b/uk/07-plugins/documentation/agents/example-generator.md @@ -0,0 +1,14 @@ +--- +name: example-generator +description: Спеціаліст з прикладів коду та туторіалів +tools: read, write +--- + +# Генератор прикладів + +Створює практичні приклади коду: +- Гайди початку роботи +- Поширені сценарії використання +- Приклади інтеграції +- Найкращі практики +- Сценарії усунення проблем diff --git a/uk/07-plugins/documentation/commands/generate-api-docs.md b/uk/07-plugins/documentation/commands/generate-api-docs.md new file mode 100644 index 0000000..4ca0f77 --- /dev/null +++ b/uk/07-plugins/documentation/commands/generate-api-docs.md @@ -0,0 +1,15 @@ +--- +name: Generate API Documentation +description: Генерація комплексної API-документації з вихідного коду +--- + +# Генератор API-документації + +Генерація повної API-документації: + +1. Сканування API-ендпоінтів +2. Витягування сигнатур функцій та JSDoc +3. Організація за модулями/ендпоінтами +4. Створення markdown з прикладами +5. Включення схем запитів/відповідей +6. Додавання документації помилок diff --git a/uk/07-plugins/documentation/commands/generate-readme.md b/uk/07-plugins/documentation/commands/generate-readme.md new file mode 100644 index 0000000..23e8e60 --- /dev/null +++ b/uk/07-plugins/documentation/commands/generate-readme.md @@ -0,0 +1,15 @@ +--- +name: Generate README +description: Створення або оновлення README проєкту +--- + +# Генератор README + +Генерація комплексного README: + +1. Огляд та опис проєкту +2. Інструкції з встановлення +3. Приклади використання +4. Посилання на API-документацію +5. Настанови для контриб'юторів +6. Інформація про ліцензію diff --git a/uk/07-plugins/documentation/commands/sync-docs.md b/uk/07-plugins/documentation/commands/sync-docs.md new file mode 100644 index 0000000..795966d --- /dev/null +++ b/uk/07-plugins/documentation/commands/sync-docs.md @@ -0,0 +1,14 @@ +--- +name: Sync Documentation +description: Синхронізація документації зі змінами коду +--- + +# Синхронізація документації + +Синхронізація документації з кодовою базою: + +1. Виявлення змін коду +2. Визначення застарілої документації +3. Оновлення уражених документів +4. Перевірка працездатності прикладів +5. Оновлення номерів версій diff --git a/uk/07-plugins/documentation/commands/validate-docs.md b/uk/07-plugins/documentation/commands/validate-docs.md new file mode 100644 index 0000000..a5186db --- /dev/null +++ b/uk/07-plugins/documentation/commands/validate-docs.md @@ -0,0 +1,14 @@ +--- +name: Validate Documentation +description: Валідація документації на повноту та точність +--- + +# Валідація документації + +Перевірка якості документації: + +1. Перевірка на зламані посилання +2. Верифікація прикладів коду +3. Забезпечення повноти +4. Перевірка форматування +5. Валідація відповідності реальному коду diff --git a/uk/07-plugins/documentation/mcp/github-docs-config.json b/uk/07-plugins/documentation/mcp/github-docs-config.json new file mode 100644 index 0000000..0f62131 --- /dev/null +++ b/uk/07-plugins/documentation/mcp/github-docs-config.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} diff --git a/uk/07-plugins/documentation/templates/adr-template.md b/uk/07-plugins/documentation/templates/adr-template.md new file mode 100644 index 0000000..e8ff079 --- /dev/null +++ b/uk/07-plugins/documentation/templates/adr-template.md @@ -0,0 +1,39 @@ +# ADR [Номер]: [Назва] + +## Статус +[Запропоновано | Прийнято | Застаріло | Замінено] + +## Контекст +Яка проблема спонукає це рішення або зміну? + +## Рішення +Яку зміну ми пропонуємо та/або впроваджуємо? + +## Наслідки +Що стає простішим або складнішим через цю зміну? + +### Позитивні +- Перевага 1 +- Перевага 2 + +### Негативні +- Недолік 1 +- Недолік 2 + +### Нейтральні +- Міркування 1 +- Міркування 2 + +## Розглянуті альтернативи +Які інші варіанти було розглянуто та чому їх не обрано? + +### Альтернатива 1 +Опис та причина відхилення. + +### Альтернатива 2 +Опис та причина відхилення. + +## Посилання +- Пов'язані ADR +- Зовнішня документація +- Посилання на обговорення diff --git a/uk/07-plugins/documentation/templates/api-endpoint.md b/uk/07-plugins/documentation/templates/api-endpoint.md new file mode 100644 index 0000000..f6ecb89 --- /dev/null +++ b/uk/07-plugins/documentation/templates/api-endpoint.md @@ -0,0 +1,101 @@ +# [METHOD] /api/v1/[endpoint] + +## Опис +Короткий опис що робить цей ендпоінт. + +## Автентифікація +Необхідний метод автентифікації (напр., Bearer token). + +## Параметри + +### Параметри шляху +| Назва | Тип | Обов'язковий | Опис | +|-------|-----|-------------|------| +| id | string | Так | ID ресурсу | + +### Параметри запиту +| Назва | Тип | Обов'язковий | Опис | +|-------|-----|-------------|------| +| page | integer | Ні | Номер сторінки (за замовч.: 1) | +| limit | integer | Ні | Елементів на сторінку (за замовч.: 20) | + +### Тіло запиту +```json +{ + "field": "value" +} +``` + +## Відповіді + +### 200 OK +```json +{ + "success": true, + "data": { + "id": "123", + "name": "Example" + } +} +``` + +### 400 Bad Request +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "Invalid input" + } +} +``` + +### 404 Not Found +```json +{ + "success": false, + "error": { + "code": "NOT_FOUND", + "message": "Resource not found" + } +} +``` + +## Приклади + +### cURL +```bash +curl -X GET "https://api.example.com/api/v1/endpoint" \ + -H "Authorization: Bearer YOUR_TOKEN" \ + -H "Content-Type: application/json" +``` + +### JavaScript +```javascript +const response = await fetch('/api/v1/endpoint', { + headers: { + 'Authorization': 'Bearer token', + 'Content-Type': 'application/json' + } +}); +const data = await response.json(); +``` + +### Python +```python +import requests + +response = requests.get( + 'https://api.example.com/api/v1/endpoint', + headers={'Authorization': 'Bearer token'} +) +data = response.json() +``` + +## Обмеження частоти запитів +- 1000 запитів на годину для автентифікованих користувачів +- 100 запитів на годину для публічних ендпоінтів + +## Пов'язані ендпоінти +- [GET /api/v1/related](#) +- [POST /api/v1/related](#) diff --git a/uk/07-plugins/documentation/templates/function-docs.md b/uk/07-plugins/documentation/templates/function-docs.md new file mode 100644 index 0000000..2b312d1 --- /dev/null +++ b/uk/07-plugins/documentation/templates/function-docs.md @@ -0,0 +1,50 @@ +# Функція: `functionName` + +## Опис +Короткий опис що робить функція. + +## Сигнатура +```typescript +function functionName(param1: Type1, param2: Type2): ReturnType +``` + +## Параметри + +| Параметр | Тип | Обов'язковий | Опис | +|----------|-----|-------------|------| +| param1 | Type1 | Так | Опис param1 | +| param2 | Type2 | Ні | Опис param2 | + +## Повертає +**Тип**: `ReturnType` + +Опис того, що повертається. + +## Кидає виключення +- `Error`: При невалідному введенні +- `TypeError`: При неправильному типі + +## Приклади + +### Базове використання +```typescript +const result = functionName('value1', 'value2'); +console.log(result); +``` + +### Просунуте використання +```typescript +const result = functionName( + complexParam1, + { option: true } +); +``` + +## Нотатки +- Додаткові нотатки або попередження +- Міркування щодо продуктивності +- Найкращі практики + +## Див. також +- [Пов'язана функція](#) +- [API-документація](#) diff --git a/uk/07-plugins/pr-review/.claude-plugin/plugin.json b/uk/07-plugins/pr-review/.claude-plugin/plugin.json new file mode 100644 index 0000000..9e953c4 --- /dev/null +++ b/uk/07-plugins/pr-review/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "license": "MIT" +} diff --git a/uk/07-plugins/pr-review/README.md b/uk/07-plugins/pr-review/README.md new file mode 100644 index 0000000..1c0aa9c --- /dev/null +++ b/uk/07-plugins/pr-review/README.md @@ -0,0 +1,91 @@ + + + Claude How To + + +# Плагін PR Review + +Повний робочий процес рев'ю PR з перевірками безпеки, тестування та документації. + +## Функції + +✅ Аналіз безпеки +✅ Перевірка покриття тестами +✅ Верифікація документації +✅ Оцінка якості коду +✅ Аналіз впливу на продуктивність + +## Встановлення + +```bash +/plugin install pr-review +``` + +## Що включено + +### Слеш-команди +- `/review-pr` — Комплексне рев'ю PR +- `/check-security` — Рев'ю з фокусом на безпеці +- `/check-tests` — Аналіз покриття тестами + +### Субагенти +- `security-reviewer` — Виявлення вразливостей безпеки +- `test-checker` — Аналіз покриття тестами +- `performance-analyzer` — Оцінка впливу на продуктивність + +### MCP-сервери +- Інтеграція з GitHub для даних PR + +### Хуки +- `pre-review.js` — Передрев'юшна валідація + +## Використання + +### Базове рев'ю PR +``` +/review-pr +``` + +### Тільки перевірка безпеки +``` +/check-security +``` + +### Перевірка покриття тестами +``` +/check-tests +``` + +## Вимоги + +- Claude Code 1.0+ +- Доступ до GitHub +- Git-репозиторій + +## Конфігурація + +Налаштуйте GitHub-токен: +```bash +export GITHUB_TOKEN="your_github_token" +``` + +## Приклад робочого процесу + +``` +User: /review-pr + +Claude: +1. Запускає pre-review хук (валідація git-репозиторію) +2. Отримує дані PR через GitHub MCP +3. Делегує рев'ю безпеки субагенту security-reviewer +4. Делегує тестування субагенту test-checker +5. Делегує продуктивність субагенту performance-analyzer +6. Синтезує всі знахідки +7. Надає комплексний звіт рев'ю + +Результат: +✅ Безпека: Критичних проблем не знайдено +⚠️ Тестування: Покриття 65%, рекомендовано 80%+ +✅ Продуктивність: Суттєвого впливу немає +📝 Рекомендації: Додати тести для граничних випадків +``` diff --git a/uk/07-plugins/pr-review/agents/performance-analyzer.md b/uk/07-plugins/pr-review/agents/performance-analyzer.md new file mode 100644 index 0000000..f8ab5cc --- /dev/null +++ b/uk/07-plugins/pr-review/agents/performance-analyzer.md @@ -0,0 +1,13 @@ +--- +name: performance-analyzer +description: Аналіз впливу на продуктивність +tools: read, grep, bash +--- + +# Аналізатор продуктивності + +Оцінює вплив змін на продуктивність: +- Складність алгоритмів +- Ефективність запитів до бази даних +- Використання пам'яті +- Можливості кешування diff --git a/uk/07-plugins/pr-review/agents/security-reviewer.md b/uk/07-plugins/pr-review/agents/security-reviewer.md new file mode 100644 index 0000000..a3e0dfb --- /dev/null +++ b/uk/07-plugins/pr-review/agents/security-reviewer.md @@ -0,0 +1,13 @@ +--- +name: security-reviewer +description: Код-рев'ю з фокусом на безпеці +tools: read, grep, diff +--- + +# Рецензент безпеки + +Спеціалізується на виявленні вразливостей безпеки: +- Проблеми автентифікації/авторизації +- Витоки даних +- Атаки ін'єкцій +- Безпечна конфігурація diff --git a/uk/07-plugins/pr-review/agents/test-checker.md b/uk/07-plugins/pr-review/agents/test-checker.md new file mode 100644 index 0000000..fb2ce12 --- /dev/null +++ b/uk/07-plugins/pr-review/agents/test-checker.md @@ -0,0 +1,13 @@ +--- +name: test-checker +description: Аналіз покриття тестами та їх якості +tools: read, bash, grep +--- + +# Перевірник тестів + +Аналізує покриття тестами та їх якість: +- Відсоток покриття +- Відсутні тест-кейси +- Оцінка якості тестів +- Визначення граничних випадків diff --git a/uk/07-plugins/pr-review/commands/check-security.md b/uk/07-plugins/pr-review/commands/check-security.md new file mode 100644 index 0000000..736960e --- /dev/null +++ b/uk/07-plugins/pr-review/commands/check-security.md @@ -0,0 +1,14 @@ +--- +name: Security Check +description: Запуск рев'ю коду з фокусом на безпеці +--- + +# Перевірка безпеки + +Цілеспрямований аналіз безпеки змін коду: + +1. Перевірки автентифікації/авторизації +2. Ризики витоку даних +3. Вразливості ін'єкцій +4. Криптографічні слабкості +5. Чутливі дані в логах diff --git a/uk/07-plugins/pr-review/commands/check-tests.md b/uk/07-plugins/pr-review/commands/check-tests.md new file mode 100644 index 0000000..860d8d6 --- /dev/null +++ b/uk/07-plugins/pr-review/commands/check-tests.md @@ -0,0 +1,14 @@ +--- +name: Test Coverage Check +description: Верифікація покриття тестами та їх якості +--- + +# Перевірка покриття тестами + +Аналіз покриття тестами та їх якості: + +1. Перевірка відсотка покриття тестами +2. Визначення непротестованих шляхів коду +3. Оцінка якості тестів +4. Пропозиція відсутніх тест-кейсів +5. Перевірка покриття граничних випадків diff --git a/uk/07-plugins/pr-review/commands/review-pr.md b/uk/07-plugins/pr-review/commands/review-pr.md new file mode 100644 index 0000000..aa145fb --- /dev/null +++ b/uk/07-plugins/pr-review/commands/review-pr.md @@ -0,0 +1,14 @@ +--- +name: Review PR +description: Запуск комплексного рев'ю PR з перевірками безпеки та тестування +--- + +# Рев'ю PR + +Ця команда ініціює повний перегляд pull request, включаючи: + +1. Аналіз безпеки +2. Верифікація покриття тестами +3. Оновлення документації +4. Перевірки якості коду +5. Оцінка впливу на продуктивність diff --git a/uk/07-plugins/pr-review/hooks/pre-review.js b/uk/07-plugins/pr-review/hooks/pre-review.js new file mode 100644 index 0000000..2127709 --- /dev/null +++ b/uk/07-plugins/pr-review/hooks/pre-review.js @@ -0,0 +1,37 @@ +#!/usr/bin/env node + +/** + * Pre-review hook + * Runs before starting PR review to ensure prerequisites are met + */ + +async function preReview() { + console.log('Running pre-review checks...'); + + // Check if git repository + const { execSync } = require('child_process'); + try { + execSync('git rev-parse --git-dir', { stdio: 'pipe' }); + } catch (error) { + console.error('❌ Not a git repository'); + process.exit(1); + } + + // Check for uncommitted changes + try { + const status = execSync('git status --porcelain', { encoding: 'utf-8' }); + if (status.trim()) { + console.warn('⚠️ Warning: Uncommitted changes detected'); + } + } catch (error) { + console.error('❌ Failed to check git status'); + process.exit(1); + } + + console.log('✅ Pre-review checks passed'); +} + +preReview().catch(error => { + console.error('Pre-review hook failed:', error); + process.exit(1); +}); diff --git a/uk/07-plugins/pr-review/mcp/github-config.json b/uk/07-plugins/pr-review/mcp/github-config.json new file mode 100644 index 0000000..0f62131 --- /dev/null +++ b/uk/07-plugins/pr-review/mcp/github-config.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} diff --git a/uk/08-checkpoints/README.md b/uk/08-checkpoints/README.md new file mode 100644 index 0000000..781d855 --- /dev/null +++ b/uk/08-checkpoints/README.md @@ -0,0 +1,335 @@ + + + + + + + Claude How To + + +# Контрольні точки та відкат + +Контрольні точки дозволяють зберігати стан розмови та повертатися до попередніх моментів у сесії Claude Code. Це незамінно для дослідження різних підходів, відновлення після помилок або порівняння альтернативних рішень. + +## Огляд + +Контрольні точки — це знімки стану вашої розмови, що включають: + +- Усі повідомлення розмови +- Модифікації файлів +- Історію використання інструментів +- Контекст сесії + +Контрольні точки незамінні при дослідженні різних підходів, відновленні після помилок або порівнянні альтернативних рішень. + +## Ключові поняття + +| Поняття | Опис | +|---------|------| +| **Контрольна точка (Checkpoint)** | Знімок стану розмови, включаючи повідомлення, файли та контекст | +| **Відкат (Rewind)** | Повернення до попередньої контрольної точки з відкиданням подальших змін | +| **Точка розгалуження (Branch Point)** | Контрольна точка, з якої досліджуються кілька підходів | + +## Доступ до контрольних точок + +Ви можете отримати доступ та управляти контрольними точками двома способами: + +### Клавіатурне скорочення + +Натисніть `Esc` двічі (`Esc` + `Esc`), щоб відкрити інтерфейс контрольних точок та переглянути збережені точки. + +### Слеш-команда + +Використовуйте команду `/rewind` (аліас: `/checkpoint`) для швидкого доступу: + +```bash +# Відкрити інтерфейс відкату +/rewind + +# Або використайте аліас +/checkpoint +``` + +## Варіанти відкату + +При відкаті вам пропонується меню з п'яти варіантів: + +1. **Відновити код і розмову** — Повернути і файли, і повідомлення до цієї контрольної точки +2. **Відновити розмову** — Відкотити лише повідомлення, залишити поточний код як є +3. **Відновити код** — Повернути зміни файлів, зберегти повну історію розмови +4. **Підсумувати звідси** — Стиснути розмову від цієї точки вперед в AI-згенерований підсумок, звільняючи контекстне вікно. Повідомлення до обраної точки залишаються недоторканими. Жодні файли на диску не змінюються. Оригінальні повідомлення зберігаються в транскрипті сесії. Можна додатково вказати інструкції для фокусування підсумку на конкретних темах. +5. **Скасувати** — Скасувати та повернутися до поточного стану + +> **Примітка**: Після відновлення розмови або підсумовування оригінальний промпт з обраного повідомлення відновлюється в полі вводу, щоб ви могли повторно надіслати або відредагувати його. + +## Автоматичні контрольні точки + +Claude Code автоматично створює контрольні точки: + +- **Кожен промпт користувача** — Нова контрольна точка створюється з кожним введенням +- **Постійні** — Контрольні точки зберігаються між сесіями +- **Автоочищення** — Контрольні точки автоматично очищуються через 30 днів + +Це означає, що ви завжди можете повернутися до будь-якого попереднього моменту розмови — від кількох хвилин тому до днів. + +## Сценарії використання + +| Сценарій | Процес | +|----------|--------| +| **Дослідження підходів** | Зберегти → Спробувати A → Зберегти → Відкат → Спробувати B → Порівняти | +| **Безпечний рефакторинг** | Зберегти → Рефакторити → Тест → Якщо не вдалось: Відкат | +| **A/B тестування** | Зберегти → Дизайн A → Зберегти → Відкат → Дизайн B → Порівняти | +| **Відновлення після помилки** | Помітити проблему → Відкат до останнього робочого стану | + +## Використання контрольних точок + +### Перегляд та відкат + +Натисніть `Esc` двічі або використайте `/rewind`, щоб відкрити браузер контрольних точок. Ви побачите список усіх доступних точок з мітками часу. Оберіть будь-яку для відкату. + +### Деталі контрольної точки + +Кожна контрольна точка показує: + +- Мітку часу створення +- Модифіковані файли +- Кількість повідомлень у розмові +- Використані інструменти + +## Практичні приклади + +### Приклад 1: Дослідження різних підходів + +``` +User: Let's add a caching layer to the API + +Claude: I'll add Redis caching to your API endpoints... +[Makes changes at checkpoint A] + +User: Actually, let's try in-memory caching instead + +Claude: I'll rewind to explore a different approach... +[User presses Esc+Esc and rewinds to checkpoint A] +[Implements in-memory caching at checkpoint B] + +User: Now I can compare both approaches +``` + +### Приклад 2: Відновлення після помилки + +``` +User: Refactor the authentication module to use JWT + +Claude: I'll refactor the authentication module... +[Makes extensive changes] + +User: Wait, that broke the OAuth integration. Let's go back. + +Claude: I'll help you rewind to before the refactoring... +[User presses Esc+Esc and selects the checkpoint before the refactor] + +User: Let's try a more conservative approach this time +``` + +### Приклад 3: Безпечне експериментування + +``` +User: Let's try rewriting this in a functional style +[Creates checkpoint before experiment] + +Claude: [Makes experimental changes] + +User: The tests are failing. Let's rewind. +[User presses Esc+Esc and rewinds to the checkpoint] + +Claude: I've rewound the changes. Let's try a different approach. +``` + +### Приклад 4: Розгалуження підходів + +``` +User: I want to compare two database designs +[Takes note of checkpoint - call it "Start"] + +Claude: I'll create the first design... +[Implements Schema A] + +User: Now let me go back and try the second approach +[User presses Esc+Esc and rewinds to "Start"] + +Claude: Now I'll implement Schema B... +[Implements Schema B] + +User: Great! Now I have both schemas to choose from +``` + +## Збереження контрольних точок + +Claude Code автоматично управляє контрольними точками: + +- Контрольні точки створюються автоматично з кожним промптом +- Старі контрольні точки зберігаються до 30 днів +- Автоматичне очищення запобігає необмеженому зростанню сховища + +## Патерни процесів + +### Стратегія розгалуження для дослідження + +При дослідженні кількох підходів: + +``` +1. Початкова реалізація → Контрольна точка A +2. Спроба Підходу 1 → Контрольна точка B +3. Відкат до Контрольної точки A +4. Спроба Підходу 2 → Контрольна точка C +5. Порівняння результатів B та C +6. Вибір найкращого підходу та продовження +``` + +### Патерн безпечного рефакторингу + +При значних змінах: + +``` +1. Поточний стан → Контрольна точка (авто) +2. Початок рефакторингу +3. Запуск тестів +4. Якщо тести пройшли → Продовжити роботу +5. Якщо тести не пройшли → Відкат та спроба іншого підходу +``` + +## Найкращі практики + +Оскільки контрольні точки створюються автоматично, ви можете зосередитися на роботі, не турбуючись про ручне збереження стану. Але пам'ятайте: + +### Ефективне використання контрольних точок + +✅ **Робіть:** + +- Переглядайте доступні контрольні точки перед відкатом +- Використовуйте відкат для дослідження різних напрямків +- Зберігайте контрольні точки для порівняння підходів +- Розумійте, що робить кожен варіант відкату + +❌ **Не робіть:** + +- Не покладайтесь лише на контрольні точки для збереження коду +- Не очікуйте, що контрольні точки відстежують зовнішні зміни файлової системи +- Не використовуйте контрольні точки замість git-комітів + +## Конфігурація + +Контрольні точки — вбудована поведінка Claude Code за замовчуванням, не потребує конфігурації. Кожен промпт автоматично створює контрольну точку. + +Єдине налаштування — `cleanupPeriodDays`, що контролює тривалість зберігання: + +```json +{ + "cleanupPeriodDays": 30 +} +``` + +- `cleanupPeriodDays`: Кількість днів зберігання історії сесій та контрольних точок (за замовчуванням: `30`) + +## Обмеження + +Контрольні точки мають такі обмеження: + +- **Bash-команди НЕ відстежуються** — Операції `rm`, `mv`, `cp` у файловій системі не фіксуються +- **Зовнішні зміни НЕ відстежуються** — Зміни, зроблені поза Claude Code (у редакторі, терміналі тощо), не фіксуються +- **Не заміна системі контролю версій** — Використовуйте git для постійних, аудитованих змін + +## Усунення неполадок + +### Відсутні контрольні точки + +**Проблема**: Очікувана контрольна точка не знайдена + +**Рішення**: + +- Перевірте, чи контрольні точки не були очищені +- Перевірте дисковий простір +- Переконайтесь, що `cleanupPeriodDays` встановлено достатньо високо (за замовчуванням: 30 днів) + +### Невдалий відкат + +**Проблема**: Не вдається відкотити до контрольної точки + +**Рішення**: + +- Переконайтесь, що немає конфліктуючих незакомічених змін +- Перевірте, чи контрольна точка не пошкоджена +- Спробуйте відкат до іншої контрольної точки + +## Інтеграція з Git + +Контрольні точки доповнюють (але не замінюють) git: + +| Характеристика | Git | Контрольні точки | +|----------------|-----|-----------------| +| Область | Файлова система | Розмова + файли | +| Постійність | Постійна | На рівні сесії | +| Деталізація | Коміти | Будь-яка точка | +| Швидкість | Повільніше | Миттєво | +| Спільний доступ | Так | Обмежено | + +Використовуйте обидва разом: + +1. Контрольні точки для швидкого експериментування +2. Git-коміти для фіналізованих змін +3. Створення контрольної точки перед git-операціями +4. Коміт успішних станів до git + +## Швидкий старт + +### Базовий процес + +1. **Працюйте як зазвичай** — Claude Code створює контрольні точки автоматично +2. **Хочете повернутись?** — Натисніть `Esc` двічі або `/rewind` +3. **Оберіть контрольну точку** — Виберіть зі списку +4. **Оберіть що відновити** — Код і розмову, лише розмову, лише код, підсумувати або скасувати +5. **Продовжуйте роботу** — Ви повернулись до тієї точки + +### Клавіатурні скорочення + +- **`Esc` + `Esc`** — Відкрити браузер контрольних точок +- **`/rewind`** — Альтернативний спосіб доступу +- **`/checkpoint`** — Аліас для `/rewind` + +## Коли відкочуватися: Моніторинг контексту + +Контрольні точки дозволяють повернутись — але як зрозуміти, *коли* це потрібно? З ростом розмови контекстне вікно Claude заповнюється, і якість моделі непомітно знижується. Ви можете відправляти код, згенерований напівсліпою моделлю, навіть не усвідомлюючи цього. + +**[cc-context-stats](https://github.com/luongnv89/cc-context-stats)** вирішує це, додаючи **зони контексту** в реальному часі до рядка стану Claude Code. Інструмент відстежує, де ви знаходитесь у контекстному вікні — від **Plan** (зелений, безпечно планувати та кодити) через **Code** (жовтий, уникайте нових планів) до **Dump** (оранжевий, завершуйте та відкочуйте). Коли бачите зміну зони — час створити контрольну точку та почати заново. + +## Пов'язані концепції + +- **[Розширені функції](../09-advanced-features/)** — Режим планування та інші просунуті можливості +- **[Управління пам'яттю](../02-memory/)** — Управління історією розмови та контекстом +- **[Слеш-команди](../01-slash-commands/)** — Ярлики користувача +- **[Хуки](../06-hooks/)** — Автоматизація на основі подій +- **[Плагіни](../07-plugins/)** — Пакетні розширення + +## Додаткові ресурси + +- [Офіційна документація контрольних точок](https://code.claude.com/docs/en/checkpointing) +- [Посібник з розширених функцій](../09-advanced-features/) — Розширене мислення та інші можливості + +## Підсумок + +Контрольні точки — автоматична функція Claude Code, що дозволяє безпечно досліджувати різні підходи без страху втратити роботу. Кожен промпт автоматично створює нову контрольну точку, тож ви можете відкотитися до будь-якого попереднього моменту сесії. + +Ключові переваги: + +- Безстрашне експериментування з кількома підходами +- Швидке відновлення після помилок +- Порівняння різних рішень пліч-о-пліч +- Безпечна інтеграція з системами контролю версій + +Пам'ятайте: контрольні точки не замінюють git. Використовуйте контрольні точки для швидкого експериментування, а git — для постійних змін коду. + +--- + +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/08-checkpoints/checkpoint-examples.md b/uk/08-checkpoints/checkpoint-examples.md new file mode 100644 index 0000000..5ae7bff --- /dev/null +++ b/uk/08-checkpoints/checkpoint-examples.md @@ -0,0 +1,342 @@ +# Приклади контрольних точок + +Реальні приклади ефективного використання контрольних точок у Claude Code. + +Примітка: Контрольні точки створюються автоматично з кожним промптом користувача. Вам не потрібно зберігати їх вручну. Для відкату натисніть `Esc` двічі (`Esc+Esc`) або використовуйте `/rewind` для відкриття браузера контрольних точок. + +## Приклад 1: Міграція бази даних + +### Сценарій +Потрібно мігрувати з MySQL на PostgreSQL, але хочете дослідити як пряму міграцію, так і поступовий підхід з подвійним записом (dual-write). + +### Робочий процес + +``` +Користувач: Реалізуймо пряму міграцію з MySQL на PostgreSQL + [Контрольна точка A створена автоматично] + +Claude: Реалізую пряму міграцію... +[Змінює драйвер БД, оновлює запити, модифікує схему] + +Користувач: Запусти тести + [Контрольна точка B створена автоматично] + +Claude: Запускаю тести... +❌ 15 тестів не проходять — проблеми з пулом зʼєднань + +Користувач: Цей підхід має проблеми. Спробуймо патерн dual-write. +[Користувач натискає Esc+Esc, обирає контрольну точку A, обирає "Restore code and conversation"] + +Користувач: Тепер реалізуй патерн dual-write, де ми пишемо в обидві БД + +Claude: Реалізую міграцію з dual-write... +[Реалізує рівень dual-write, стратегію поступової міграції] + +Користувач: Запусти тести + +Claude: Запускаю тести... +✅ Усі тести проходять + +Користувач: Підхід dual-write явно безпечніший. Закомітимо це. +``` + +## Приклад 2: Оптимізація продуктивності + +### Сценарій +Кілька стратегій оптимізації продуктивності для випробування. + +### Робочий процес + +``` +Користувач: Оптимізуймо час відповіді API. Поточний: 450мс + [Контрольна точка "Baseline" створена автоматично] + +Claude: Додам кешування запитів до БД... +[Реалізує кешування Redis] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 280мс середній час відповіді (покращення 38%) + +Користувач: Спробую інший підхід. +[Користувач натискає Esc+Esc, обирає контрольну точку "Baseline", обирає "Restore code and conversation"] + +Користувач: Спробуй оптимізацію запитів до БД + +Claude: Оптимізую запити до БД... +[Додає індекси, оптимізує N+1 запити] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 180мс середній час відповіді (покращення 60%) + +Користувач: Спробую ще третій підхід. +[Користувач натискає Esc+Esc, обирає контрольну точку "Baseline", обирає "Restore code and conversation"] + +Користувач: Спробуй стиснення відповідей та CDN + +Claude: Додам стиснення та CDN... +[Реалізує gzip, налаштовує CDN] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 320мс середній час відповіді (покращення 29%) + +Користувач: Оптимізація запитів була найкращою. Повернуся та поєднаю з кешуванням. +[Користувач натискає Esc+Esc, обирає контрольну точку після оптимізації запитів, обирає "Restore code and conversation"] + +Користувач: Тепер додай кешування Redis поверх цих оптимізованих запитів + +Claude: [Додає кешування Redis поверх оптимізованих запитів] + +Користувач: Запусти тести продуктивності + +Claude: Результати: 95мс середній час відповіді (покращення 79%) 🎉 + +Користувач: Ідеально! Це переможець. Закомітимо. +``` + +## Приклад 3: Ітерація UI/UX + +### Сценарій +Випробування різних макетів для дашборду. + +### Робочий процес + +``` +Користувач: Перепроєктуймо дашборд з бічною панеллю + [Контрольна точка "Start" створена автоматично] + +Claude: [Реалізує макет з бічною панеллю] + +Користувач: Покажи скріншот + +Claude: [Показує скріншот] + +Користувач: Бічна панель тісна. Спробуймо верхню навігацію. +[Користувач натискає Esc+Esc, обирає контрольну точку "Start", обирає "Restore code and conversation"] + +Користувач: Спробуй макет з верхньою навігацією + +Claude: [Реалізує верхню навігацію] + +Користувач: Покажи скріншот + +Claude: [Показує скріншот] + +Користувач: Краще, але спробуймо макет у вигляді сітки карток +[Користувач натискає Esc+Esc, обирає контрольну точку "Start", обирає "Restore code and conversation"] + +Користувач: Спробуй макет сітки карток + +Claude: [Реалізує сітку карток] + +Користувач: Покажи скріншот + +Claude: [Показує скріншот] + +Користувач: Чудово! Але чи можемо поєднати верхню навігацію із сіткою карток? +[Користувач натискає Esc+Esc, обирає контрольну точку після сітки карток, обирає "Restore code and conversation"] + +Користувач: Додай верхню навігацію до макету сітки карток + +Claude: [Додає верхню навігацію до сітки карток] + +Користувач: Ідеально! Це фінальний дизайн. +``` + +## Приклад 4: Сесія налагодження + +### Сценарій +Полювання на складну помилку з кількома гіпотезами. + +### Робочий процес + +``` +Користувач: В додатку є витік памʼяті + [Контрольна точка "Before debugging" створена автоматично] + +Claude: Досліджую... +[Аналізує код] + +Користувач: Думаю, це в обробниках подій. Виправимо їх. + +Claude: [Виправляє очищення обробників подій] + +Користувач: Запусти профілювальник памʼяті + +Claude: Памʼять все ще тече — обробники подій не були причиною + +Користувач: Повернуся та спробую іншу гіпотезу. +[Користувач натискає Esc+Esc, обирає контрольну точку "Before debugging", обирає "Restore code and conversation"] + +Користувач: Може це зʼєднання з БД? + +Claude: [Реалізує виправлення пулу зʼєднань] + +Користувач: Запусти профілювальник памʼяті + +Claude: Все ще тече — не зʼєднання + +Користувач: Повернуся та спробую інший ракурс. +[Користувач натискає Esc+Esc, обирає контрольну точку "Before debugging", обирає "Restore code and conversation"] + +Користувач: Перевіримо циклічні посилання + +Claude: [Знаходить та виправляє циклічні посилання в кеші] + +Користувач: Запусти профілювальник памʼяті + +Claude: ✅ Витік памʼяті виправлено! Циклічні посилання в рівні кешування були причиною. + +Користувач: Відмінно! Закомітимо це виправлення. +``` + +## Приклад 5: Еволюція дизайну API + +### Сценарій +Проєктування REST API з кількома ітераціями. + +### Робочий процес + +``` +Користувач: Створи REST API для нашої блог-платформи + [Контрольна точка "Before API design" створена автоматично] + +Claude: [Створює базовий CRUD API] + +Користувач: Це занадто просто. Додаймо пагінацію та фільтрацію + +Claude: [Додає пагінацію та фільтрацію] + +Користувач: Потрібні кращі звʼязки між ресурсами + +Claude: [Реалізує HATEOAS-посилання] + +Користувач: Власне, спробуймо GraphQL замість REST +[Користувач натискає Esc+Esc, обирає контрольну точку "Before API design", обирає "Restore code and conversation"] + +Користувач: Реалізуй GraphQL API для нашої блог-платформи + +Claude: [Реалізує GraphQL API] + +Користувач: Думаю, REST краще для нашого випадку. +[Користувач натискає Esc+Esc, обирає контрольну точку після HATEOAS, обирає "Restore code and conversation"] + +Користувач: Фіналізуємо REST-підхід. +``` + +## Приклад 6: Управління конфігурацією + +### Сценарій +Тестування різних підходів до конфігурації. + +### Робочий процес + +``` +Користувач: Перемісти конфігурацію у змінні оточення + [Контрольна точка "Original config" створена автоматично] + +Claude: [Реалізує конфігурацію через змінні оточення] + +Користувач: Тест у середовищі розробки + +Claude: Працює локально, але проблеми з деплоєм на продакшні + +Користувач: Спробую інший підхід. +[Користувач натискає Esc+Esc, обирає контрольну точку "Original config", обирає "Restore code and conversation"] + +Користувач: Спробуй підхід з файлом конфігурації та валідацією + +Claude: [Реалізує YAML-конфігурацію з валідацією JSON Schema] + +Користувач: Тест у середовищі розробки + +Claude: ✅ Працює добре, хороші повідомлення про помилки валідації + +Користувач: Чи можемо також підтримувати змінні оточення для чутливих значень? + +Claude: [Додає перевизначення через змінні оточення для секретів] + +Користувач: Тест деплою + +Claude: ✅ Усі середовища працюють коректно + +Користувач: Ідеально! Це готове для продакшну. +``` + +## Приклад 7: Стратегія тестування + +### Сценарій +Реалізація комплексного тестування. + +### Робочий процес + +``` +Користувач: Додай юніт-тести для модуля автентифікації + [Контрольна точка створена автоматично] + +Claude: [Додає юніт-тести Jest] + +Користувач: Запусти тести + +Claude: 45 тестів проходять, 78% покриття + +Користувач: Додай також інтеграційні тести + +Claude: [Додає інтеграційні тести] + +Користувач: Запусти тести + +Claude: 89 тестів проходять, 92% покриття, але тести повільні (3 хвилини) + +Користувач: Тести занадто повільні. Оптимізуймо. + +Claude: [Оптимізує налаштування тестів, додає паралельне виконання] + +Користувач: Запусти тести + +Claude: 89 тестів проходять, 92% покриття, 35 секунд ✅ + +Користувач: Чудово! Тепер додай E2E тести для критичних шляхів + +Claude: [Додає E2E тести Playwright] + +Користувач: Запусти всі тести + +Claude: 112 тестів проходять, 94% покриття, 2 хвилини + +Користувач: Ідеальний баланс покриття та швидкості! +``` + +## Приклад 8: Використання підсумку від контрольної точки + +### Сценарій +Після довгої сесії налагодження хочете стиснути розмову, зберігаючи контекст. + +### Робочий процес + +``` +Користувач: [Після 20+ повідомлень налагодження та дослідження] + +[Користувач натискає Esc+Esc, обирає ранню контрольну точку, обирає "Summarize from here"] +[Необовʼязково надає інструкції: "Зосередься на тому, що ми спробували і що спрацювало"] + +Claude: [Генерує підсумок розмови від цієї точки далі] +[Оригінальні повідомлення зберігаються в транскрипті] +[Підсумок замінює видиму розмову, зменшуючи використання контекстного вікна] + +Користувач: Тепер продовжимо з підходом, що спрацював. +``` + +## Ключові висновки + +1. **Контрольні точки автоматичні**: Кожен промпт користувача створює контрольну точку — ручне збереження не потрібне +2. **Використовуйте Esc+Esc або /rewind**: Два способи доступу до браузера контрольних точок +3. **Обирайте правильний варіант відновлення**: Відновити код, розмову, обидва або підсумувати — залежно від потреб +4. **Не бійтеся експериментувати**: Контрольні точки роблять безпечним випробування радикальних змін +5. **Поєднуйте з git**: Контрольні точки для дослідження, git для фіналізованої роботи +6. **Підсумовуйте довгі сесії**: Використовуйте "Summarize from here" для підтримки керованості розмов + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/09-advanced-features/README.md b/uk/09-advanced-features/README.md new file mode 100644 index 0000000..5705faf --- /dev/null +++ b/uk/09-advanced-features/README.md @@ -0,0 +1,1945 @@ + + + Claude How To + + +# Розширені функції + +Повний посібник з розширених можливостей Claude Code, включаючи режим планування, розширене мислення, автоматичний режим, фонові завдання, режими дозволів, режим друку (неінтерактивний), управління сесіями, інтерактивні функції, канали, голосовий ввід, дистанційне керування, веб-сесії, десктопний додаток, список завдань, підказки промптів, git worktrees, пісочницю, керовані налаштування та конфігурацію. + +## Зміст + +1. [Огляд](#огляд) +2. [Режим планування](#режим-планування) +3. [Розширене мислення](#розширене-мислення) +4. [Auto Mode](#auto-mode) +5. [Фонові завдання](#фонові-завдання) +6. [Заплановані завдання](#заплановані-завдання) +7. [Режими дозволів](#режими-дозволів) +8. [Headless Mode](#headless-mode) +9. [Управління сесіями](#управління-сесіями) +10. [Інтерактивні функції](#інтерактивні-функції) +11. [Голосовий ввід](#голосовий-ввід) +12. [Канали](#канали) +13. [Інтеграція Chrome](#інтеграція-chrome) +14. [Remote Control](#remote-control) +15. [Веб-сесії](#веб-сесії) +16. [Десктопний додаток](#десктопний-додаток) +17. [Список завдань](#список-завдань) +18. [Підказки промптів](#підказки-промптів) +19. [Git Worktrees](#git-worktrees) +20. [Пісочниця](#пісочниця) +21. [Керовані налаштування (Enterprise)](#керовані-налаштування-enterprise) +22. [Конфігурація та налаштування](#конфігурація-та-налаштування) +23. [Agent Teams](#agent-teams) +24. [Найкращі практики](#найкращі-практики) +25. [Додаткові ресурси](#додаткові-ресурси) + +--- + +## Огляд + +Розширені функції Claude Code доповнюють базові можливості плануванням, міркуванням, автоматизацією та механізмами контролю. Ці функції забезпечують складні робочі процеси для комплексних завдань розробки, ревʼю коду, автоматизації та управління кількома сесіями. + +**Ключові розширені функції:** +- **Режим планування**: Створення детальних планів реалізації перед кодуванням +- **Розширене мислення**: Глибоке міркування для складних проблем +- **Auto Mode**: Фоновий класифікатор безпеки перевіряє кожну дію перед виконанням (Research Preview) +- **Фонові завдання**: Виконання тривалих операцій без блокування розмови +- **Режими дозволів**: Контроль дій Claude (`default`, `acceptEdits`, `plan`, `auto`, `dontAsk`, `bypassPermissions`) +- **Режим друку**: Неінтерактивний запуск Claude Code для автоматизації та CI/CD (`claude -p`) +- **Управління сесіями**: Управління кількома робочими сесіями +- **Інтерактивні функції**: Клавіатурні скорочення, багаторядковий ввід та історія команд +- **Голосовий ввід**: Push-to-talk голосовий ввід з підтримкою STT для 20 мов +- **Канали**: MCP-сервери надсилають повідомлення в активні сесії (Research Preview) +- **Remote Control**: Управління Claude Code з Claude.ai або додатку Claude +- **Веб-сесії**: Запуск Claude Code у браузері на claude.ai/code +- **Десктопний додаток**: Автономний додаток для візуального перегляду diff та кількох сесій +- **Список завдань**: Постійне відстеження завдань між стисненнями контексту +- **Підказки промптів**: Розумні підказки команд на основі контексту +- **Git Worktrees**: Ізольовані робочі дерева для паралельної роботи +- **Пісочниця**: Ізоляція файлової системи та мережі на рівні ОС +- **Керовані налаштування**: Корпоративне розгортання через plist, Registry або керовані файли +- **Конфігурація**: Налаштування поведінки за допомогою JSON-файлів конфігурації + +--- + +## Режим планування + +Режим планування дозволяє Claude продумати складні завдання перед їх реалізацією, створюючи детальний план, який ви можете переглянути та затвердити. + +### Що таке режим планування? + +Режим планування — це двофазний підхід: +1. **Фаза планування**: Claude аналізує завдання та створює детальний план реалізації +2. **Фаза реалізації**: Після затвердження Claude виконує план + +### Коли використовувати режим планування + +✅ Використовуйте для: +- Складного рефакторингу кількох файлів +- Реалізації нових функцій +- Архітектурних змін +- Міграцій баз даних +- Масштабних змін API + +❌ Не використовуйте для: +- Простого виправлення помилок +- Змін форматування +- Редагування одного файлу +- Швидких запитів + +### Активація режиму планування + +**Слеш-команда**: +```bash +/plan Implement user authentication system +``` + +**Прапорець CLI**: +```bash +claude --permission-mode plan +``` + +**Встановити за замовчуванням**: +```json +{ + "permissions": { + "defaultMode": "plan" + } +} +``` + +**Клавіатурне скорочення**: +- `Shift + Tab` — Перемикання режимів дозволів (включно з plan) +- `Alt + M` — Перемикання режимів дозволів (Windows/Linux) + +### Переваги режиму планування + +- **Структурований підхід до реалізації**: Детальна розбивка кроків реалізації +- **Перегляд та затвердження**: Затвердіть або скоригуйте план перед виконанням +- **Виявлення ризиків**: Визначення потенційних проблем до реалізації +- **Чіткі фази**: Організовані фази та етапи реалізації + +### Приклад: Реалізація функції + +``` +User: /plan Add a real-time notification system + +Claude: I'll create a plan for implementing real-time notifications. + +## Implementation Plan + +### Phase 1: Infrastructure Setup +1. Install WebSocket libraries (socket.io) +2. Set up WebSocket server +3. Configure connection management + +### Phase 2: Backend Implementation +4. Create notification service +5. Implement notification queue +6. Add database schema for notifications +7. Create API endpoints + +### Phase 3: Frontend Integration +8. Set up WebSocket client +9. Create notification UI components +10. Implement notification state management +11. Add notification permissions + +### Phase 4: Testing & Deployment +12. Write unit tests +13. Write integration tests +14. Update documentation +15. Deploy to staging + +Estimated time: 3-4 hours +Files to modify: 12 +New files to create: 8 + +Ready to proceed? (yes/no/modify plan) + +User: yes + +Claude: [Begins implementation following the plan] +``` + +### Модифікація планів + +``` +User: Modify the plan - skip the queue for now, we'll add it later + +Claude: Updated plan: +[Shows modified plan with queue removed] + +User: Looks good, proceed + +Claude: [Implements modified plan] +``` + +### Конфігурація режиму планування + +Режим планування активується через прапорець CLI або слеш-команду: + +```bash +# Активація режиму планування через CLI +claude --permission-mode plan + +# Або використовуйте слеш-команду /plan всередині REPL +/plan Implement user authentication system +``` + +**Псевдонім моделі для планування**: Використовуйте `opusplan` як псевдонім моделі, щоб використовувати Opus для планування та Sonnet для виконання: + +```bash +claude --model opusplan "design and implement the new API" +``` + +**Редагування плану зовні**: Натисніть `Ctrl+G`, щоб відкрити поточний план у зовнішньому редакторі для детальних змін. + +### Ultraplan + +Використовуйте `/ultraplan ` для наскрізного робочого процесу планування: Claude складає детальний план, відкриває його у браузері для перегляду, потім виконує план віддалено або повертає його у ваш термінал для локального виконання. + +--- + +## Розширене мислення + +Розширене мислення дозволяє Claude витрачати більше часу на обмірковування складних проблем перед наданням рішення. + +### Що таке розширене мислення? + +Розширене мислення — це цілеспрямований покроковий процес міркування, де Claude: +- Розбиває складні проблеми на частини +- Розглядає кілька підходів +- Оцінює компроміси +- Продумує граничні випадки + +### Активація розширеного мислення + +**Клавіатурне скорочення**: +- `Option + T` (macOS) / `Alt + T` (Windows/Linux) — Перемикання розширеного мислення + +**Автоматична активація**: +- Увімкнено за замовчуванням для всіх моделей (Opus 4.6, Sonnet 4.6, Haiku 4.5) +- Opus 4.6: Адаптивне міркування з рівнями зусиль: `low` (○), `medium` (◐), `high` (●), `max` (тільки Opus 4.6) +- Інші моделі: Фіксований бюджет до 31 999 токенів + +**Методи конфігурації**: +- Перемикання: `Alt+T` / `Option+T`, або через `/config` +- Перегляд міркувань: `Ctrl+O` (детальний режим) +- Встановлення зусиль: команда `/effort` або прапорець `--effort` + +**Власний бюджет**: +```bash +export MAX_THINKING_TOKENS=1024 +``` + +**Рівень зусиль** (тільки Opus 4.6): +```bash +export CLAUDE_CODE_EFFORT_LEVEL=high # low (○), medium (◐), high (●), або max (тільки Opus 4.6) +``` + +**Прапорець CLI**: +```bash +claude --effort high "complex architectural review" +``` + +**Слеш-команда**: +``` +/effort high +``` + +> **Примітка:** Ключове слово "ultrathink" у промптах активує режим глибокого міркування. Рівні зусиль `low`, `medium`, `high` та `max` (тільки Opus 4.6) контролюють обсяг міркувань Claude. + +### Переваги розширеного мислення + +- **Глибоке міркування**: Більше часу на обдумування складних проблем +- **Кращі архітектурні рішення**: Обґрунтовані рішення з комплексною оцінкою +- **Розгляд граничних випадків**: Продумування потенційних проблем і сценаріїв +- **Ретельний аналіз**: Структурований підхід до вирішення складних проблем + +### Приклад: Архітектурне рішення + +``` +User: /think Should we use microservices or a monolith for our e-commerce platform? + +Claude: Let me think through this architectural decision carefully... + + +## Context Analysis +- Team size: 5 developers +- Expected traffic: 10k daily users initially +- Need to scale to 100k+ users +- Limited DevOps resources +- 6-month timeline to MVP + +## Approach 1: Microservices +Pros: ++ Independent scaling ++ Technology flexibility ++ Team independence ++ Fault isolation + +Cons: +- Operational complexity +- Network overhead +- Distributed tracing needed +- Requires DevOps expertise +- Slower initial development + +## Approach 2: Monolith +Pros: ++ Simpler deployment ++ Faster initial development ++ Easier debugging ++ Lower operational overhead ++ Single codebase + +Cons: +- Scaling challenges later +- All-or-nothing deployments +- Technology lock-in +- Potential for tight coupling + +## Decision Factors +1. Team size (5 devs) → Favors monolith +2. DevOps resources (limited) → Favors monolith +3. Timeline (6 months) → Favors monolith +4. Future scale (100k users) → Achievable with monolith + caching +5. Complexity budget → Limited + +## Recommendation +Start with a **modular monolith**: +- Single deployment unit +- Clear module boundaries +- Clean interfaces between modules +- Prepare for future extraction to microservices if needed + +This gives you: +✓ Fast initial development +✓ Low operational complexity +✓ Option to extract services later +✓ Clear architecture + +Migration path: When you reach 50k+ users or specific modules need independent scaling, extract those modules into microservices. + + +**Recommendation**: Implement a modular monolith with clean module boundaries. + +This approach balances your current constraints (team size, timeline, DevOps resources) with future scalability needs. You can migrate specific modules to microservices later when there's a clear business need. +``` + +### Конфігурація розширеного мислення + +Розширене мислення контролюється через змінні оточення, клавіатурні скорочення та прапорці CLI: + +```bash +# Встановлення бюджету токенів мислення +export MAX_THINKING_TOKENS=16000 + +# Встановлення рівня зусиль (тільки Opus 4.6): low (○), medium (◐), high (●), або max (тільки Opus 4.6) +export CLAUDE_CODE_EFFORT_LEVEL=high +``` + +Перемикання під час сесії за допомогою `Alt+T` / `Option+T`, встановлення зусиль через `/effort` або конфігурація через `/config`. + +--- + +## Auto Mode + +Auto Mode — це режим дозволів Research Preview (березень 2026), який використовує фоновий класифікатор безпеки для перевірки кожної дії перед виконанням. Він дозволяє Claude працювати автономно, блокуючи небезпечні операції. + +### Вимоги + +- **План**: Team, Enterprise або API (недоступно на планах Pro або Max) +- **Модель**: Claude Sonnet 4.6 або Opus 4.6 +- **Провайдер**: Тільки Anthropic API (не підтримується на Bedrock, Vertex або Foundry) +- **Класифікатор**: Працює на Claude Sonnet 4.6 (додаткова вартість токенів) + +### Увімкнення Auto Mode + +```bash +# Розблокування auto mode за допомогою прапорця CLI +claude --enable-auto-mode + +# Потім перемикайте через Shift+Tab у REPL +``` + +Або встановіть як режим дозволів за замовчуванням: + +```bash +claude --permission-mode auto +``` + +Встановлення через конфігурацію: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### Як працює класифікатор + +Фоновий класифікатор оцінює кожну дію в такому порядку: + +1. **Правила дозволу/заборони** — Спочатку перевіряються явні правила дозволів +2. **Читання/редагування автоматично затверджуються** — Читання та редагування файлів проходять автоматично +3. **Класифікатор** — Фоновий класифікатор перевіряє дію +4. **Запасний варіант** — Повертається до запиту після 3 послідовних або 20 загальних блокувань + +### Заблоковані дії за замовчуванням + +Auto mode блокує наступне за замовчуванням: + +| Заблокована дія | Приклад | +|----------------|---------| +| Встановлення через pipe-to-shell | `curl \| bash` | +| Надсилання конфіденційних даних назовні | API-ключі, облікові дані через мережу | +| Деплой на продакшн | Команди деплою на продакшн | +| Масове видалення | `rm -rf` на великих директоріях | +| Зміни IAM | Зміни дозволів та ролей | +| Force push у main | `git push --force origin main` | + +### Дозволені дії за замовчуванням + +| Дозволена дія | Приклад | +|----------------|---------| +| Локальні операції з файлами | Читання, запис, редагування файлів проєкту | +| Встановлення оголошених залежностей | `npm install`, `pip install` з маніфесту | +| HTTP тільки для читання | `curl` для отримання документації | +| Push у поточну гілку | `git push origin feature-branch` | + +### Конфігурація Auto Mode + +**Вивести правила за замовчуванням у JSON**: +```bash +claude auto-mode defaults +``` + +**Налаштування довіреної інфраструктури** через керовану настройку `autoMode.environment` для корпоративних розгортань. Це дозволяє адміністраторам визначати довірені середовища CI/CD, цілі деплою та шаблони інфраструктури. + +### Запасна поведінка + +Коли класифікатор невпевнений, auto mode повертається до запиту користувача: +- Після **3 послідовних** блокувань класифікатором +- Після **20 загальних** блокувань класифікатором за сесію + +Це гарантує, що користувач завжди зберігає контроль, коли класифікатор не може впевнено затвердити дію. + +### Посів дозволів Auto-Mode без Team-плану + +Якщо у вас немає Team-плану або ви хочете простіший підхід без фонового класифікатора, ви можете наповнити ваш `~/.claude/settings.json` консервативним базовим набором безпечних правил дозволів. Скрипт починає з правил тільки для читання та локального інспектування, потім дозволяє вам додавати редагування, тести, локальний запис у git, встановлення пакетів та дії запису GitHub лише за потреби. + +**Файл:** `09-advanced-features/setup-auto-mode-permissions.py` + +```bash +# Попередній перегляд змін (без запису) +python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run + +# Застосувати консервативний базовий набір +python3 09-advanced-features/setup-auto-mode-permissions.py + +# Додавати більше можливостей лише за потреби +python3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-tests +python3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packages +``` + +Скрипт додає правила в таких категоріях: + +| Категорія | Приклади | +|----------|---------| +| Базові інструменти тільки для читання | `Read(*)`, `Glob(*)`, `Grep(*)`, `Agent(*)`, `WebSearch(*)`, `WebFetch(*)` | +| Локальне інспектування | `Bash(git status:*)`, `Bash(git log:*)`, `Bash(git diff:*)`, `Bash(cat:*)` | +| Опціональне редагування | `Edit(*)`, `Write(*)`, `NotebookEdit(*)` | +| Опціональні тести/збірка | `Bash(pytest:*)`, `Bash(python3 -m pytest:*)`, `Bash(cargo test:*)` | +| Опціональний запис у git | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git stash:*)` | +| Git (локальний запис) | `Bash(git add:*)`, `Bash(git commit:*)`, `Bash(git checkout:*)` | +| Менеджери пакетів | `Bash(npm install:*)`, `Bash(pip install:*)`, `Bash(cargo build:*)` | +| Збірка та тести | `Bash(make:*)`, `Bash(pytest:*)`, `Bash(go test:*)` | +| Звичайні shell-команди | `Bash(ls:*)`, `Bash(cat:*)`, `Bash(find:*)`, `Bash(cp:*)`, `Bash(mv:*)` | +| GitHub CLI | `Bash(gh pr view:*)`, `Bash(gh pr create:*)`, `Bash(gh issue list:*)` | + +Небезпечні операції (`rm -rf`, `sudo`, force push, `DROP TABLE`, `terraform destroy` тощо) навмисно виключені. Скрипт ідемпотентний — повторний запуск не дублює правила. + +--- + +## Фонові завдання + +Фонові завдання дозволяють виконувати тривалі операції без блокування вашої розмови. + +### Що таке фонові завдання? + +Фонові завдання виконуються асинхронно, поки ви продовжуєте працювати: +- Тривалі набори тестів +- Процеси збірки +- Міграції баз даних +- Скрипти деплою +- Інструменти аналізу + +**Базове використання:** +```bash +User: Run tests in background + +Claude: Started task bg-1234 + +/task list # Показати всі завдання +/task status bg-1234 # Перевірити прогрес +/task show bg-1234 # Переглянути вивід +/task cancel bg-1234 # Скасувати завдання +``` + +### Запуск фонових завдань + +``` +User: Run the full test suite in the background + +Claude: Starting tests in background (task-id: bg-1234) +You can continue working while tests run. + +[You can continue the conversation] + +User: Meanwhile, let's refactor the auth module + +Claude: [Works on auth module while tests run in background] + +[Later, when tests complete] + +Claude: 📢 Background task bg-1234 completed: +✅ 245 tests passed +❌ 3 tests failed +View results: /task show bg-1234 +``` + +### Управління фоновими завданнями + +**Список активних завдань**: +``` +User: /task list + +Active background tasks: +1. [bg-1234] Running tests (50% complete, 2min remaining) +2. [bg-1235] Building Docker image (25% complete, 8min remaining) +3. [bg-1236] Deploying to staging (90% complete, 30sec remaining) +``` + +**Перевірка статусу завдання**: +``` +User: /task status bg-1234 + +Task bg-1234: Running tests +Status: In progress +Progress: 120/245 tests (49%) +Started: 2025-11-08 10:30:15 +Estimated completion: 2025-11-08 10:34:22 +``` + +**Перегляд виводу завдання**: +``` +User: /task show bg-1234 + +[Shows live output from the test run] +``` + +**Скасування завдання**: +``` +User: /task cancel bg-1234 + +Cancelled background task bg-1234 +``` + +### Приклад: Паралельна розробка + +``` +User: Run the build in the background + +Claude: Starting build... (task-id: bg-5001) + +User: Also run the linter in background + +Claude: Starting linter... (task-id: bg-5002) + +User: While those run, let's implement the new API endpoint + +Claude: [Implements API endpoint while build and linter run] + +[10 minutes later] + +Claude: 📢 Build completed successfully (bg-5001) +📢 Linter found 12 issues (bg-5002) + +User: Show me the linter issues + +Claude: [Shows linter output from bg-5002] +``` + +### Конфігурація + +```json +{ + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5, + "notifyOnCompletion": true, + "autoCleanup": true, + "logOutput": true + } +} +``` + +--- + +## Заплановані завдання + +Заплановані завдання дозволяють автоматично запускати промпти за розкладом або як одноразові нагадування. Завдання привʼязані до сесії — вони працюють, поки Claude Code активний, і очищуються при завершенні сесії. Доступно з v2.1.72+. + +### Команда `/loop` + +```bash +# Явний інтервал +/loop 5m check if the deployment finished + +# Природна мова +/loop check build status every 30 minutes +``` + +Також підтримуються стандартні 5-польні cron-вирази для точного планування. + +### Одноразові нагадування + +Встановлення нагадувань, які спрацьовують один раз у визначений час: + +``` +remind me at 3pm to push the release branch +in 45 minutes, run the integration tests +``` + +### Управління запланованими завданнями + +| Інструмент | Опис | +|------|-------------| +| `CronCreate` | Створити нове заплановане завдання | +| `CronList` | Показати всі активні заплановані завдання | +| `CronDelete` | Видалити заплановане завдання | + +**Обмеження та поведінка**: +- До **50 запланованих завдань** на сесію +- Привʼязані до сесії — очищуються при завершенні сесії +- Повторювані завдання автоматично закінчуються через **3 дні** +- Завдання спрацьовують лише під час роботи Claude Code — пропущені запуски не компенсуються + +### Деталі поведінки + +| Аспект | Деталь | +|--------|--------| +| **Джитер повторюваних** | До 10% від інтервалу (макс. 15 хвилин) | +| **Джитер одноразових** | До 90 секунд на межах :00/:30 | +| **Пропущені запуски** | Без компенсації — пропускаються, якщо Claude Code не працював | +| **Збереження** | Не зберігаються між перезапусками | + +### Хмарні заплановані завдання + +Використовуйте `/schedule` для створення хмарних запланованих завдань, які працюють на інфраструктурі Anthropic: + +``` +/schedule daily at 9am run the test suite and report failures +``` + +Хмарні заплановані завдання зберігаються між перезапусками і не потребують локально запущеного Claude Code. + +### Вимкнення запланованих завдань + +```bash +export CLAUDE_CODE_DISABLE_CRON=1 +``` + +### Приклад: Моніторинг деплою + +``` +/loop 5m check the deployment status of the staging environment. + If the deploy succeeded, notify me and stop looping. + If it failed, show the error logs. +``` + +> **Порада**: Заплановані завдання привʼязані до сесії. Для постійної автоматизації, яка переживає перезапуски, використовуйте CI/CD пайплайни, GitHub Actions або заплановані завдання десктопного додатку. + +--- + +## Режими дозволів + +Режими дозволів контролюють, які дії Claude може виконувати без явного схвалення. + +### Доступні режими дозволів + +| Режим | Поведінка | +|---|---| +| `default` | Тільки читання файлів; запитує дозвіл на всі інші дії | +| `acceptEdits` | Читання та редагування файлів; запитує дозвіл на команди | +| `plan` | Тільки читання файлів (режим дослідження, без редагувань) | +| `auto` | Усі дії з перевірками фонового класифікатора безпеки (Research Preview) | +| `bypassPermissions` | Усі дії, без перевірки дозволів (небезпечно) | +| `dontAsk` | Виконуються лише попередньо затверджені інструменти; всі інші відхиляються | + +Перемикайте режими через `Shift+Tab` у CLI. Встановіть режим за замовчуванням через прапорець `--permission-mode` або налаштування `permissions.defaultMode`. + +### Методи активації + +**Клавіатурне скорочення**: +```bash +Shift + Tab # Перемикання між усіма 6 режимами +``` + +**Слеш-команда**: +```bash +/plan # Увійти в режим планування +``` + +**Прапорець CLI**: +```bash +claude --permission-mode plan +claude --permission-mode auto +``` + +**Налаштування**: +```json +{ + "permissions": { + "defaultMode": "auto" + } +} +``` + +### Приклади режимів дозволів + +#### Режим Default +Claude запитує підтвердження на значущі дії: + +``` +User: Fix the bug in auth.ts + +Claude: I need to modify src/auth.ts to fix the bug. +The change will update the password validation logic. + +Approve this change? (yes/no/show) +``` + +#### Режим Plan +Перегляд плану реалізації перед виконанням: + +``` +User: /plan Implement user authentication system + +Claude: I'll create a plan for implementing authentication. + +## Implementation Plan +[Detailed plan with phases and steps] + +Ready to proceed? (yes/no/modify) +``` + +#### Режим Accept Edits +Автоматичне прийняття змін у файлах: + +``` +User: acceptEdits +User: Fix the bug in auth.ts + +Claude: [Makes changes without asking] +``` + +### Випадки використання + +**Ревʼю коду**: +``` +User: claude --permission-mode plan +User: Review this PR and suggest improvements + +Claude: [Reads code, provides feedback, but cannot modify] +``` + +**Парне програмування**: +``` +User: claude --permission-mode default +User: Let's implement the feature together + +Claude: [Asks for approval before each change] +``` + +**Автоматизовані завдання**: +``` +User: claude --permission-mode acceptEdits +User: Fix all linting issues in the codebase + +Claude: [Auto-accepts file edits without asking] +``` + +--- + +## Headless Mode + +Режим друку (`claude -p`) дозволяє запускати Claude Code без інтерактивного вводу, ідеально для автоматизації та CI/CD. Це неінтерактивний режим, що замінює старий прапорець `--headless`. + +### Що таке режим друку? + +Режим друку забезпечує: +- Автоматизоване виконання скриптів +- Інтеграцію з CI/CD +- Пакетну обробку +- Виконання запланованих завдань + +### Запуск у режимі друку (неінтерактивний) + +```bash +# Запуск конкретного завдання +claude -p "Run all tests" + +# Обробка переданого вмісту +cat error.log | claude -p "Analyze these errors" + +# Інтеграція CI/CD (GitHub Actions) +- name: AI Code Review + run: claude -p "Review PR" +``` + +### Додаткові приклади використання режиму друку + +```bash +# Запуск завдання з захопленням виводу +claude -p "Run all tests and generate coverage report" + +# Зі структурованим виводом +claude -p --output-format json "Analyze code quality" + +# З вводом через stdin +echo "Analyze code quality" | claude -p "explain this" +``` + +### Приклад: Інтеграція CI/CD + +**GitHub Actions**: +```yaml +# .github/workflows/code-review.yml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Claude Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 3 \ + "Review this PR for: + - Code quality issues + - Security vulnerabilities + - Performance concerns + - Test coverage + Output results as JSON" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: JSON.stringify(review, null, 2) + }); +``` + +### Конфігурація режиму друку + +Режим друку (`claude -p`) підтримує кілька прапорців для автоматизації: + +```bash +# Обмеження автономних ходів +claude -p --max-turns 5 "refactor this module" + +# Структурований вивід JSON +claude -p --output-format json "analyze this codebase" + +# З валідацією схеми +claude -p --json-schema '{"type":"object","properties":{"issues":{"type":"array"}}}' \ + "find bugs in this code" + +# Вимкнення збереження сесії +claude -p --no-session-persistence "one-off analysis" +``` + +--- + +## Управління сесіями + +Ефективне управління кількома сесіями Claude Code. + +### Команди управління сесіями + +| Команда | Опис | +|---------|-------------| +| `/resume` | Відновити розмову за ID або назвою | +| `/rename` | Назвати поточну сесію | +| `/fork` | Розгалужити поточну сесію в нову гілку | +| `claude -c` | Продовжити останню розмову | +| `claude -r "session"` | Відновити сесію за назвою або ID | + +### Відновлення сесій + +**Продовжити останню розмову**: +```bash +claude -c +``` + +**Відновити іменовану сесію**: +```bash +claude -r "auth-refactor" "finish this PR" +``` + +**Перейменувати поточну сесію** (всередині REPL): +``` +/rename auth-refactor +``` + +### Розгалуження сесій + +Розгалужте сесію, щоб спробувати альтернативний підхід без втрати оригіналу: + +``` +/fork +``` + +Або з CLI: +```bash +claude --resume auth-refactor --fork-session "try OAuth instead" +``` + +### Збереження сесій + +Сесії автоматично зберігаються і можуть бути відновлені: + +```bash +# Продовжити останню розмову +claude -c + +# Відновити конкретну сесію за назвою або ID +claude -r "auth-refactor" + +# Відновити та розгалужити для експериментів +claude --resume auth-refactor --fork-session "alternative approach" +``` + +--- + +## Інтерактивні функції + +### Клавіатурні скорочення + +Claude Code підтримує клавіатурні скорочення для ефективності. Ось повний довідник з офіційної документації: + +| Скорочення | Опис | +|----------|-------------| +| `Ctrl+C` | Скасувати поточний ввід/генерацію | +| `Ctrl+D` | Вийти з Claude Code | +| `Ctrl+G` | Редагувати план у зовнішньому редакторі | +| `Ctrl+L` | Очистити екран терміналу | +| `Ctrl+O` | Перемкнути детальний вивід (перегляд міркувань) | +| `Ctrl+R` | Зворотний пошук в історії | +| `Ctrl+T` | Перемкнути перегляд списку завдань | +| `Ctrl+B` | Перевести завдання у фоновий режим | +| `Esc+Esc` | Відкотити код/розмову | +| `Shift+Tab` / `Alt+M` | Перемикання режимів дозволів | +| `Option+P` / `Alt+P` | Перемкнути модель | +| `Option+T` / `Alt+T` | Перемкнути розширене мислення | + +**Редагування рядка (стандартні скорочення readline):** + +| Скорочення | Дія | +|----------|--------| +| `Ctrl + A` | Перейти на початок рядка | +| `Ctrl + E` | Перейти на кінець рядка | +| `Ctrl + K` | Вирізати до кінця рядка | +| `Ctrl + U` | Вирізати до початку рядка | +| `Ctrl + W` | Видалити слово назад | +| `Ctrl + Y` | Вставити (yank) | +| `Tab` | Автодоповнення | +| `↑ / ↓` | Історія команд | + +### Кастомізація клавіатурних скорочень + +Створюйте власні клавіатурні скорочення, запустивши `/keybindings`, що відкриває `~/.claude/keybindings.json` для редагування (v2.1.18+). + +**Формат конфігурації**: + +```json +{ + "$schema": "https://www.schemastore.org/claude-code-keybindings.json", + "bindings": [ + { + "context": "Chat", + "bindings": { + "ctrl+e": "chat:externalEditor", + "ctrl+u": null, + "ctrl+k ctrl+s": "chat:stash" + } + }, + { + "context": "Confirmation", + "bindings": { + "ctrl+a": "confirmation:yes" + } + } + ] +} +``` + +Встановіть привʼязку в `null`, щоб відвʼязати скорочення за замовчуванням. + +### Доступні контексти + +Клавіатурні скорочення привʼязані до конкретних контекстів UI: + +| Контекст | Ключові дії | +|---------|-------------| +| **Chat** | `submit`, `cancel`, `cycleMode`, `modelPicker`, `thinkingToggle`, `undo`, `externalEditor`, `stash`, `imagePaste` | +| **Confirmation** | `yes`, `no`, `previous`, `next`, `nextField`, `cycleMode`, `toggleExplanation` | +| **Global** | `interrupt`, `exit`, `toggleTodos`, `toggleTranscript` | +| **Autocomplete** | `accept`, `dismiss`, `next`, `previous` | +| **HistorySearch** | `search`, `previous`, `next` | +| **Settings** | Навігація налаштуваннями | +| **Tabs** | Перемикання та управління вкладками | +| **Help** | Навігація панеллю допомоги | + +Загалом 18 контекстів, включаючи `Transcript`, `Task`, `ThemePicker`, `Attachments`, `Footer`, `MessageSelector`, `DiffDialog`, `ModelPicker` та `Select`. + +### Підтримка акордів + +Клавіатурні скорочення підтримують послідовності акордів (комбінації з кількох клавіш): + +``` +"ctrl+k ctrl+s" → Двоклавішна послідовність: натисніть ctrl+k, потім ctrl+s +"ctrl+shift+p" → Одночасне натискання модифікаторів +``` + +**Синтаксис клавіш**: +- **Модифікатори**: `ctrl`, `alt` (або `opt`), `shift`, `meta` (або `cmd`) +- **Великі літери включають Shift**: `K` еквівалентно `shift+k` +- **Спеціальні клавіші**: `escape`, `enter`, `return`, `tab`, `space`, `backspace`, `delete`, клавіші стрілок + +### Зарезервовані та конфліктні клавіші + +| Клавіша | Статус | Примітки | +|-----|--------|-------| +| `Ctrl+C` | Зарезервовано | Неможливо перепривʼязати (переривання) | +| `Ctrl+D` | Зарезервовано | Неможливо перепривʼязати (вихід) | +| `Ctrl+B` | Конфлікт терміналу | Префіксна клавіша tmux | +| `Ctrl+A` | Конфлікт терміналу | Префіксна клавіша GNU Screen | +| `Ctrl+Z` | Конфлікт терміналу | Призупинення процесу | + +> **Порада**: Якщо скорочення не працює, перевірте конфлікти з вашим емулятором терміналу або мультиплексором. + +### Tab-доповнення + +Claude Code забезпечує інтелектуальне tab-доповнення: + +``` +User: /rew +→ /rewind + +User: /plu +→ /plugin + +User: /plugin +→ /plugin install +→ /plugin enable +→ /plugin disable +``` + +### Історія команд + +Доступ до попередніх команд: + +``` +User: <↑> # Попередня команда +User: <↓> # Наступна команда +User: Ctrl+R # Пошук в історії + +(reverse-i-search)`test': run all tests +``` + +### Багаторядковий ввід + +Для складних запитів використовуйте багаторядковий режим: + +```bash +User: \ +> Long complex prompt +> spanning multiple lines +> \end +``` + +**Приклад:** + +``` +User: \ +> Implement a user authentication system +> with the following requirements: +> - JWT tokens +> - Email verification +> - Password reset +> - 2FA support +> \end + +Claude: [Processes the multi-line request] +``` + +### Inline-редагування + +Редагування команд перед відправкою: + +``` +User: Deploy to prodcutionuction + +[Edit in-place before sending] +``` + +### Режим Vim + +Увімкнення Vi/Vim-клавіатурних привʼязок для редагування тексту: + +**Активація**: +- Використовуйте команду `/vim` або `/config` для увімкнення +- Перемикання режимів: `Esc` для NORMAL, `i/a/o` для INSERT + +**Клавіші навігації**: +- `h` / `l` — Рух вліво/вправо +- `j` / `k` — Рух вниз/вгору +- `w` / `b` / `e` — Рух по словах +- `0` / `$` — Перейти на початок/кінець рядка +- `gg` / `G` — Перейти на початок/кінець тексту + +**Текстові обʼєкти**: +- `iw` / `aw` — Внутрішнє/зовнішнє слово +- `i"` / `a"` — Внутрішній/зовнішній рядок у лапках +- `i(` / `a(` — Внутрішнє/зовнішнє у дужках + +### Режим Bash + +Виконання shell-команд безпосередньо з префіксом `!`: + +```bash +! npm test +! git status +! cat src/index.js +``` + +Використовуйте це для швидкого виконання команд без перемикання контексту. + +--- + +## Голосовий ввід + +Голосовий ввід забезпечує push-to-talk голосове введення для Claude Code, дозволяючи промовляти ваші промпти замість друкування. + +### Активація голосового вводу + +``` +/voice +``` + +### Можливості + +| Можливість | Опис | +|---------|-------------| +| **Push-to-talk** | Утримуйте клавішу для запису, відпустіть для відправки | +| **20 мов** | Розпізнавання мовлення підтримує 20 мов | +| **Власна клавіша** | Налаштуйте клавішу push-to-talk через `/keybindings` | +| **Вимога облікового запису** | Потрібен обліковий запис Claude.ai для обробки STT | + +### Конфігурація + +Налаштуйте клавішу push-to-talk у файлі привʼязок (`/keybindings`). Голосовий ввід використовує ваш обліковий запис Claude.ai для обробки мовлення в текст. + +--- + +## Канали + +Канали — це функція Research Preview, яка надсилає події від зовнішніх сервісів у запущену сесію Claude Code через MCP-сервери. Джерела включають Telegram, Discord, iMessage та довільні вебхуки, дозволяючи Claude реагувати на повідомлення в реальному часі без опитування. + +### Підписка на канали + +```bash +# Підписка на плагіни каналів при запуску +claude --channels discord,telegram + +# Підписка на кілька джерел +claude --channels discord,telegram,imessage,webhooks +``` + +### Підтримувані інтеграції + +| Інтеграція | Опис | +|-------------|-------------| +| **Discord** | Отримання та відповіді на повідомлення Discord у вашій сесії | +| **Telegram** | Отримання та відповіді на повідомлення Telegram у вашій сесії | +| **iMessage** | Отримання сповіщень iMessage у вашій сесії | +| **Webhooks** | Отримання подій від довільних джерел вебхуків | + +### Конфігурація + +Налаштуйте канали прапорцем `--channels` при запуску. Для корпоративних розгортань використовуйте керовану настройку для контролю дозволених плагінів каналів: + +```json +{ + "allowedChannelPlugins": ["discord", "telegram"] +} +``` + +Керована настройка `allowedChannelPlugins` контролює, які плагіни каналів дозволені в організації. + +### Як це працює + +1. MCP-сервери діють як плагіни каналів, що підключаються до зовнішніх сервісів +2. Вхідні повідомлення та події надсилаються в активну сесію Claude Code +3. Claude може читати та відповідати на повідомлення в контексті сесії +4. Плагіни каналів мають бути затверджені через керовану настройку `allowedChannelPlugins` +5. Опитування не потрібне — події надсилаються в реальному часі + +--- + +## Інтеграція Chrome + +Інтеграція Chrome підключає Claude Code до вашого браузера Chrome або Microsoft Edge для автоматизації та відлагодження веб-сторінок у реальному часі. Це бета-функція, доступна з v2.0.73+ (підтримка Edge додана в v1.0.36+). + +### Увімкнення інтеграції Chrome + +**При запуску**: + +```bash +claude --chrome # Увімкнути зʼєднання з Chrome +claude --no-chrome # Вимкнути зʼєднання з Chrome +``` + +**Всередині сесії**: + +``` +/chrome +``` + +Оберіть "Enabled by default" для активації інтеграції Chrome для всіх майбутніх сесій. Claude Code використовує стан входу вашого браузера, тому може взаємодіяти з автентифікованими веб-додатками. + +### Можливості + +| Можливість | Опис | +|------------|-------------| +| **Відлагодження в реальному часі** | Читання логів консолі, інспектування DOM-елементів, відлагодження JavaScript в реальному часі | +| **Перевірка дизайну** | Порівняння відрендерених сторінок з макетами дизайну | +| **Валідація форм** | Тестування відправки форм, валідації вводу та обробки помилок | +| **Тестування веб-додатків** | Взаємодія з автентифікованими додатками (Gmail, Google Docs, Notion тощо) | +| **Витягування даних** | Збір та обробка контенту з веб-сторінок | +| **Запис сесії** | Запис взаємодій з браузером у GIF-файли | + +### Дозволи на рівні сайтів + +Розширення Chrome управляє доступом до окремих сайтів. Надавайте або відкликайте доступ для конкретних сайтів у будь-який час через спливаюче вікно розширення. Claude Code взаємодіє лише з сайтами, які ви явно дозволили. + +### Як це працює + +Claude Code керує браузером у видимому вікні — ви можете спостерігати за діями в реальному часі. Коли браузер натрапляє на сторінку входу або CAPTCHA, Claude зупиняється і чекає, поки ви вручну обробите це, перш ніж продовжити. + +### Відомі обмеження + +- **Підтримка браузерів**: Тільки Chrome та Edge — Brave, Arc та інші браузери на базі Chromium не підтримуються +- **WSL**: Недоступно у Windows Subsystem for Linux +- **Сторонні провайдери**: Не підтримується з провайдерами API Bedrock, Vertex або Foundry +- **Idle service worker**: Service worker розширення Chrome може переходити у неактивний стан під час тривалих сесій + +> **Порада**: Інтеграція Chrome є бета-функцією. Підтримка браузерів може розширитись у майбутніх релізах. + +--- + +## Remote Control + +Remote Control дозволяє продовжити локально запущену сесію Claude Code з телефону, планшета або будь-якого браузера. Ваша локальна сесія продовжує працювати на вашому компʼютері — нічого не переміщується у хмару. Доступно на планах Pro, Max, Team та Enterprise (v2.1.51+). + +### Запуск Remote Control + +**З CLI**: + +```bash +# Запуск із назвою сесії за замовчуванням +claude remote-control + +# Запуск із власною назвою +claude remote-control --name "Auth Refactor" +``` + +**Зсередини сесії**: + +``` +/remote-control +/remote-control "Auth Refactor" +``` + +**Доступні прапорці**: + +| Прапорець | Опис | +|------|-------------| +| `--name "title"` | Власна назва сесії для зручної ідентифікації | +| `--verbose` | Показувати детальні логи зʼєднання | +| `--sandbox` | Увімкнути ізоляцію файлової системи та мережі | +| `--no-sandbox` | Вимкнути пісочницю (за замовчуванням) | + +### Підключення до сесії + +Три способи підключення з іншого пристрою: + +1. **URL сесії** — Виводиться в термінал при запуску сесії; відкрийте у будь-якому браузері +2. **QR-код** — Натисніть `пробіл` після запуску для відображення QR-коду для сканування +3. **Пошук за назвою** — Перегляньте ваші сесії на claude.ai/code або у мобільному додатку Claude (iOS/Android) + +### Безпека + +- **Жодних вхідних портів** не відкривається на вашому компʼютері +- **Тільки вихідний HTTPS** через TLS +- **Обмежені облікові дані** — кілька короткоживучих токенів з вузькою областю дії +- **Ізоляція сесій** — кожна віддалена сесія незалежна + +### Remote Control проти Claude Code у вебі + +| Аспект | Remote Control | Claude Code у вебі | +|--------|---------------|-------------------| +| **Виконання** | Працює на вашому компʼютері | Працює у хмарі Anthropic | +| **Локальні інструменти** | Повний доступ до локальних MCP-серверів, файлів та CLI | Без локальних залежностей | +| **Випадок використання** | Продовження локальної роботи з іншого пристрою | Початок роботи з нуля в будь-якому браузері | + +### Обмеження + +- Одна віддалена сесія на екземпляр Claude Code +- Термінал має залишатись відкритим на хост-машині +- Сесія закінчується через ~10 хвилин, якщо мережа недоступна + +### Випадки використання + +- Управління Claude Code з мобільного пристрою або планшета, перебуваючи далеко від робочого місця +- Використання багатшого UI claude.ai зі збереженням локального виконання інструментів +- Швидке ревʼю коду на ходу з повним локальним середовищем розробки + +--- + +## Веб-сесії + +Веб-сесії дозволяють запускати Claude Code безпосередньо у браузері на claude.ai/code або створювати веб-сесії з CLI. + +### Створення веб-сесії + +```bash +# Створення нової веб-сесії з CLI +claude --remote "implement the new API endpoints" +``` + +Це запускає сесію Claude Code на claude.ai, до якої можна отримати доступ з будь-якого браузера. + +### Відновлення веб-сесій локально + +Якщо ви почали сесію у вебі і хочете продовжити локально: + +```bash +# Відновити веб-сесію в локальному терміналі +claude --teleport +``` + +Або зсередини інтерактивного REPL: +``` +/teleport +``` + +### Випадки використання + +- Почати роботу на одному компʼютері і продовжити на іншому +- Поділитися URL сесії з членами команди +- Використовувати веб-UI для візуального перегляду diff, потім перемкнутися на термінал для виконання + +--- + +## Десктопний додаток + +Десктопний додаток Claude Code надає автономний додаток з візуальним переглядом diff, паралельними сесіями та інтегрованими конекторами. Доступний для macOS та Windows (плани Pro, Max, Team та Enterprise). + +### Встановлення + +Завантажте з [claude.ai](https://claude.ai) для вашої платформи: +- **macOS**: Універсальна збірка (Apple Silicon та Intel) +- **Windows**: Інсталятори для x64 та ARM64 + +Дивіться [Desktop Quickstart](https://code.claude.com/docs/en/desktop-quickstart) для інструкцій з налаштування. + +### Передача з CLI + +Передайте поточну CLI-сесію в десктопний додаток: + +``` +/desktop +``` + +### Основні функції + +| Функція | Опис | +|---------|-------------| +| **Перегляд diff** | Візуальний перегляд файл за файлом з inline-коментарями; Claude читає коментарі та вносить виправлення | +| **Попередній перегляд додатку** | Автозапуск dev-серверів з вбудованим браузером для живої перевірки | +| **Моніторинг PR** | Інтеграція GitHub CLI з автовиправленням помилок CI та автозлиттям при проходженні перевірок | +| **Паралельні сесії** | Кілька сесій у бічній панелі з автоматичною ізоляцією Git worktree | +| **Заплановані завдання** | Повторювані завдання (щогодини, щодня, у робочі дні, щотижня), що працюють при відкритому додатку | +| **Багатий рендеринг** | Рендеринг коду, markdown та діаграм з підсвіткою синтаксису | + +### Конфігурація попереднього перегляду додатку + +Налаштуйте поведінку dev-сервера в `.claude/launch.json`: + +```json +{ + "command": "npm run dev", + "port": 3000, + "readyPattern": "ready on", + "persistCookies": true +} +``` + +### Конектори + +Підключення зовнішніх сервісів для багатшого контексту: + +| Конектор | Можливість | +|-----------|------------| +| **GitHub** | Моніторинг PR, трекінг issues, ревʼю коду | +| **Slack** | Сповіщення, контекст каналів | +| **Linear** | Трекінг issues, управління спринтами | +| **Notion** | Документація, доступ до бази знань | +| **Asana** | Управління завданнями, трекінг проєктів | +| **Calendar** | Обізнаність про розклад, контекст зустрічей | + +> **Примітка**: Конектори недоступні для віддалених (хмарних) сесій. + +### Віддалені та SSH-сесії + +- **Віддалені сесії**: Працюють на хмарній інфраструктурі Anthropic; продовжуються навіть після закриття додатку. Доступні з claude.ai/code або мобільного додатку Claude +- **SSH-сесії**: Підключення до віддалених машин через SSH з повним доступом до віддаленої файлової системи та інструментів. Claude Code повинен бути встановлений на віддаленій машині + +### Режими дозволів у десктопному додатку + +Десктопний додаток підтримує ті самі 4 режими дозволів, що й CLI: + +| Режим | Поведінка | +|------|----------| +| **Ask permissions** (за замовчуванням) | Перегляд та затвердження кожного редагування та команди | +| **Auto accept edits** | Редагування файлів автозатверджуються; команди потребують ручного затвердження | +| **Plan mode** | Перегляд підходу перед будь-якими змінами | +| **Bypass permissions** | Автоматичне виконання (лише у пісочниці, контролюється адміністратором) | + +### Корпоративні функції + +- **Консоль адміністратора**: Контроль доступу до вкладки Code та налаштувань дозволів для організації +- **Розгортання через MDM**: Розгортання через MDM на macOS або MSIX на Windows +- **Інтеграція SSO**: Вимога єдиного входу для членів організації +- **Керовані налаштування**: Централізоване управління конфігурацією команди та доступністю моделей + +--- + +## Список завдань + +Функція списку завдань забезпечує постійне відстеження завдань, яке переживає стиснення контексту (коли історія розмови обрізається для вміщення в контекстне вікно). + +### Перемикання списку завдань + +Натисніть `Ctrl+T` для перемикання перегляду списку завдань під час сесії. + +### Постійні завдання + +Завдання зберігаються між стисненнями контексту, гарантуючи, що тривалі робочі елементи не втрачаються при обрізці контексту розмови. Це особливо корисно для складних, багатоетапних реалізацій. + +### Іменовані директорії завдань + +Використовуйте змінну оточення `CLAUDE_CODE_TASK_LIST_ID` для створення іменованих директорій завдань, спільних між сесіями: + +```bash +export CLAUDE_CODE_TASK_LIST_ID=my-project-sprint-3 +``` + +Це дозволяє кільком сесіям використовувати один список завдань, що корисно для командних робочих процесів або проєктів з кількома сесіями. + +--- + +## Підказки промптів + +Підказки промптів відображають напівпрозорі приклади команд на основі вашої git-історії та поточного контексту розмови. + +### Як це працює + +- Підказки зʼявляються як напівпрозорий текст під вашим вводом +- Натисніть `Tab` для прийняття підказки +- Натисніть `Enter` для прийняття та негайної відправки +- Підказки враховують контекст, використовуючи git-історію та стан розмови + +### Вимкнення підказок промптів + +```bash +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +``` + +--- + +## Git Worktrees + +Git Worktrees дозволяють запускати Claude Code в ізольованому робочому дереві, забезпечуючи паралельну роботу на різних гілках без stash або перемикання. + +### Запуск у Worktree + +```bash +# Запуск Claude Code в ізольованому робочому дереві +claude --worktree +# або +claude -w +``` + +### Розташування Worktree + +Робочі дерева створюються за адресою: +``` +/.claude/worktrees/ +``` + +### Sparse Checkout для монорепозиторіїв + +Використовуйте налаштування `worktree.sparsePaths` для виконання sparse-checkout у монорепозиторіях, зменшуючи використання диску та час клонування: + +```json +{ + "worktree": { + "sparsePaths": ["packages/my-package", "shared/"] + } +} +``` + +### Інструменти та хуки Worktree + +| Елемент | Опис | +|------|-------------| +| `ExitWorktree` | Інструмент для виходу та очищення поточного робочого дерева | +| `WorktreeCreate` | Подія хуку при створенні робочого дерева | +| `WorktreeRemove` | Подія хуку при видаленні робочого дерева | + +### Автоочищення + +Якщо в робочому дереві не було зроблено змін, воно автоматично очищується при завершенні сесії. + +### Випадки використання + +- Робота над feature-гілкою зі збереженням незміненої основної гілки +- Запуск тестів в ізоляції без впливу на робочу директорію +- Спроба експериментальних змін у одноразовому середовищі +- Sparse-checkout конкретних пакетів у монорепозиторіях для швидшого запуску + +--- + +## Пісочниця + +Пісочниця забезпечує ізоляцію файлової системи та мережі на рівні ОС для Bash-команд, що виконуються Claude Code. Це доповнює правила дозволів і забезпечує додатковий рівень безпеки. + +### Увімкнення пісочниці + +**Слеш-команда**: +``` +/sandbox +``` + +**Прапорці CLI**: +```bash +claude --sandbox # Увімкнути пісочницю +claude --no-sandbox # Вимкнути пісочницю +``` + +### Налаштування конфігурації + +| Налаштування | Опис | +|---------|-------------| +| `sandbox.enabled` | Увімкнути або вимкнути пісочницю | +| `sandbox.failIfUnavailable` | Зупинитись, якщо пісочницю неможливо активувати | +| `sandbox.filesystem.allowWrite` | Шляхи з дозволом на запис | +| `sandbox.filesystem.allowRead` | Шляхи з дозволом на читання | +| `sandbox.filesystem.denyRead` | Шляхи з забороною читання | +| `sandbox.enableWeakerNetworkIsolation` | Увімкнути слабшу ізоляцію мережі на macOS | + +### Приклад конфігурації + +```json +{ + "sandbox": { + "enabled": true, + "failIfUnavailable": true, + "filesystem": { + "allowWrite": ["/Users/me/project"], + "allowRead": ["/Users/me/project", "/usr/local/lib"], + "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"] + }, + "enableWeakerNetworkIsolation": true + } +} +``` + +### Як це працює + +- Bash-команди виконуються у пісочниці з обмеженим доступом до файлової системи +- Мережевий доступ може бути ізольований для запобігання небажаним зовнішнім зʼєднанням +- Працює разом з правилами дозволів для глибокого захисту +- На macOS використовуйте `sandbox.enableWeakerNetworkIsolation` для мережевих обмежень (повна ізоляція мережі недоступна на macOS) + +### Випадки використання + +- Безпечний запуск ненадійного або згенерованого коду +- Запобігання випадковим змінам файлів за межами проєкту +- Обмеження мережевого доступу під час автоматизованих завдань + +--- + +## Керовані налаштування (Enterprise) + +Керовані налаштування дозволяють корпоративним адміністраторам розгортати конфігурацію Claude Code по всій організації за допомогою платформних засобів управління. + +### Методи розгортання + +| Платформа | Метод | Починаючи з | +|----------|--------|-------| +| macOS | Керовані plist-файли (MDM) | v2.1.51+ | +| Windows | Реєстр Windows | v2.1.51+ | +| Кросплатформний | Керовані файли конфігурації | v2.1.51+ | +| Кросплатформний | Керовані drop-ins (директорія `managed-settings.d/`) | v2.1.83+ | + +### Керовані Drop-ins + +Починаючи з v2.1.83, адміністратори можуть розгортати кілька файлів керованих налаштувань у директорію `managed-settings.d/`. Файли обʼєднуються в алфавітному порядку, дозволяючи модульну конфігурацію між командами: + +``` +~/.claude/managed-settings.d/ + 00-org-defaults.json + 10-team-policies.json + 20-project-overrides.json +``` + +### Доступні керовані налаштування + +| Налаштування | Опис | +|---------|-------------| +| `disableBypassPermissionsMode` | Заборонити користувачам вмикати обхід дозволів | +| `availableModels` | Обмежити моделі, доступні для вибору | +| `allowedChannelPlugins` | Контролювати дозволені плагіни каналів | +| `autoMode.environment` | Налаштувати довірену інфраструктуру для auto mode | +| Власні політики | Організаційні політики дозволів та інструментів | + +### Приклад: macOS Plist + +```xml + + + + + disableBypassPermissionsMode + + availableModels + + claude-sonnet-4-6 + claude-haiku-4-5 + + + +``` + +--- + +## Конфігурація та налаштування + +### Розташування файлів конфігурації + +1. **Глобальна конфігурація**: `~/.claude/config.json` +2. **Конфігурація проєкту**: `./.claude/config.json` +3. **Конфігурація користувача**: `~/.config/claude-code/settings.json` + +### Повний приклад конфігурації + +**Конфігурація основних розширених функцій:** + +```json +{ + "permissions": { + "mode": "default" + }, + "hooks": { + "PreToolUse:Edit": "eslint --fix ${file_path}", + "PostToolUse:Write": "~/.claude/hooks/security-scan.sh" + }, + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"] + } + } + } +} +``` + +**Розширений приклад конфігурації:** + +```json +{ + "permissions": { + "mode": "default", + "allowedTools": ["Bash(git log:*)", "Read"], + "disallowedTools": ["Bash(rm -rf:*)"] + }, + + "hooks": { + "PreToolUse": [{ "matcher": "Edit", "hooks": ["eslint --fix ${file_path}"] }], + "PostToolUse": [{ "matcher": "Write", "hooks": ["~/.claude/hooks/security-scan.sh"] }], + "Stop": [{ "hooks": ["~/.claude/hooks/notify.sh"] }] + }, + + "mcp": { + "enabled": true, + "servers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } + } +} +``` + +### Змінні оточення + +Перевизначення конфігурації через змінні оточення: + +```bash +# Вибір моделі +export ANTHROPIC_MODEL=claude-opus-4-6 +export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6 +export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6 +export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5 + +# Конфігурація API +export ANTHROPIC_API_KEY=sk-ant-... + +# Конфігурація мислення +export MAX_THINKING_TOKENS=16000 +export CLAUDE_CODE_EFFORT_LEVEL=high + +# Перемикачі функцій +export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true +export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true +export CLAUDE_CODE_DISABLE_CRON=1 +export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=true +export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true +export CLAUDE_CODE_DISABLE_1M_CONTEXT=true +export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=true +export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false +export CLAUDE_CODE_ENABLE_TASKS=true +export CLAUDE_CODE_SIMPLE=true # Встановлюється прапорцем --bare + +# Конфігурація MCP +export MAX_MCP_OUTPUT_TOKENS=50000 +export ENABLE_TOOL_SEARCH=true + +# Управління завданнями +export CLAUDE_CODE_TASK_LIST_ID=my-project-tasks + +# Agent teams (експериментально) +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + +# Конфігурація субагентів та плагінів +export CLAUDE_CODE_SUBAGENT_MODEL=sonnet +export CLAUDE_CODE_PLUGIN_SEED_DIR=./my-plugins +export CLAUDE_CODE_NEW_INIT=1 + +# Підпроцеси та стрімінг +export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD" +export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 +export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000 +export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-model +export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000 +``` + +### Команди управління конфігурацією + +``` +User: /config +[Opens interactive configuration menu] +``` + +Команда `/config` надає інтерактивне меню для перемикання налаштувань, таких як: +- Розширене мислення увімк./вимк. +- Детальний вивід +- Режим дозволів +- Вибір моделі + +### Конфігурація на рівні проєкту + +Створіть `.claude/config.json` у вашому проєкті: + +```json +{ + "hooks": { + "PreToolUse": [{ "matcher": "Bash", "hooks": ["npm test && npm run lint"] }] + }, + "permissions": { + "mode": "default" + }, + "mcp": { + "servers": { + "project-db": { + "command": "mcp-postgres", + "env": { + "DATABASE_URL": "${PROJECT_DB_URL}" + } + } + } + } +} +``` + +--- + +## Agent Teams + +Agent Teams — це експериментальна функція, яка дозволяє кільком екземплярам Claude Code співпрацювати над завданням. Вимкнена за замовчуванням. + +### Увімкнення Agent Teams + +Увімкнення через змінну оточення або налаштування: + +```bash +# Змінна оточення +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +Або додайте до вашого JSON-файлу налаштувань: + +```json +{ + "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" +} +``` + +### Як працюють Agent Teams + +- **Лідер команди** координує загальне завдання та делегує підзавдання товаришам по команді +- **Товариші по команді** працюють незалежно, кожен зі своїм контекстним вікном +- **Спільний список завдань** забезпечує самокоординацію між членами команди +- Використовуйте визначення субагентів (`.claude/agents/` або прапорець `--agents`) для визначення ролей та спеціалізацій товаришів + +### Режими відображення + +Agent Teams підтримують два режими відображення, що налаштовуються прапорцем `--teammate-mode`: + +| Режим | Опис | +|------|-------------| +| `in-process` (за замовчуванням) | Товариші працюють у тому ж процесі терміналу | +| `tmux` | Кожен товариш отримує окрему розділену панель (потрібен tmux або iTerm2) | +| `auto` | Автоматичний вибір найкращого режиму відображення | + +```bash +# Використання tmux для відображення товаришів +claude --teammate-mode tmux + +# Явне використання in-process режиму +claude --teammate-mode in-process +``` + +### Випадки використання + +- Великі завдання рефакторингу, де різні товариші обробляють різні модулі +- Паралельне ревʼю коду та реалізація +- Координовані зміни кількох файлів по всій кодовій базі + +> **Примітка**: Agent Teams є експериментальною функцією і може змінитися у майбутніх релізах. Дивіться [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) для повного довідника. + +--- + +## Найкращі практики + +### Режим планування +- ✅ Використовуйте для складних багатоетапних завдань +- ✅ Переглядайте плани перед затвердженням +- ✅ Модифікуйте плани за потреби +- ❌ Не використовуйте для простих завдань + +### Розширене мислення +- ✅ Використовуйте для архітектурних рішень +- ✅ Використовуйте для вирішення складних проблем +- ✅ Переглядайте процес мислення +- ❌ Не використовуйте для простих запитів + +### Фонові завдання +- ✅ Використовуйте для тривалих операцій +- ✅ Моніторте прогрес завдань +- ✅ Коректно обробляйте помилки завдань +- ❌ Не запускайте занадто багато паралельних завдань + +### Дозволи +- ✅ Використовуйте `plan` для ревʼю коду (тільки читання) +- ✅ Використовуйте `default` для інтерактивної розробки +- ✅ Використовуйте `acceptEdits` для автоматизованих робочих процесів +- ✅ Використовуйте `auto` для автономної роботи із запобіжниками безпеки +- ❌ Не використовуйте `bypassPermissions` без крайньої необхідності + +### Сесії +- ✅ Використовуйте окремі сесії для різних завдань +- ✅ Зберігайте важливі стани сесій +- ✅ Очищайте старі сесії +- ❌ Не змішуйте неповʼязану роботу в одній сесії + +--- + +## Додаткові ресурси + +Для отримання додаткової інформації про Claude Code та повʼязані функції: + +- [Офіційна документація інтерактивного режиму](https://code.claude.com/docs/en/interactive-mode) +- [Офіційна документація Headless Mode](https://code.claude.com/docs/en/headless) +- [Довідник CLI](https://code.claude.com/docs/en/cli-reference) +- [Посібник з контрольних точок](../08-checkpoints/) — Управління сесіями та відкат +- [Слеш-команди](../01-slash-commands/) — Довідник команд +- [Посібник з памʼяті](../02-memory/) — Постійний контекст +- [Посібник з навичок](../03-skills/) — Автономні можливості +- [Посібник з субагентів](../04-subagents/) — Делеговане виконання завдань +- [Посібник з MCP](../05-mcp/) — Доступ до зовнішніх даних +- [Посібник з хуків](../06-hooks/) — Автоматизація на основі подій +- [Посібник з плагінів](../07-plugins/) — Пакетні розширення +- [Офіційна документація запланованих завдань](https://code.claude.com/docs/en/scheduled-tasks) +- [Офіційна документація інтеграції Chrome](https://code.claude.com/docs/en/chrome) +- [Офіційна документація Remote Control](https://code.claude.com/docs/en/remote-control) +- [Офіційна документація клавіатурних скорочень](https://code.claude.com/docs/en/keybindings) +- [Офіційна документація десктопного додатку](https://code.claude.com/docs/en/desktop) +- [Офіційна документація Agent Teams](https://code.claude.com/docs/en/agent-teams) + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/09-advanced-features/config-examples.json b/uk/09-advanced-features/config-examples.json new file mode 100644 index 0000000..a67f08c --- /dev/null +++ b/uk/09-advanced-features/config-examples.json @@ -0,0 +1,267 @@ +{ + "description": "Example Claude Code configurations for different use cases", + + "examples": { + "development": { + "name": "Development Environment", + "description": "Configuration for active development work", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.7 + }, + "planning": { + "autoEnter": true, + "complexityThreshold": 3, + "requireApproval": true + }, + "permissions": { + "mode": "unrestricted" + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 3 + }, + "hooks": { + "PreToolUse:Write": "prettier --write ${file_path}", + "PostToolUse:Write": "eslint ${file_path}" + } + } + }, + + "code_review": { + "name": "Code Review Mode", + "description": "Configuration for reviewing code without modifications", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.3 + }, + "permissions": { + "mode": "plan" + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "planning": { + "autoEnter": false + } + } + }, + + "learning": { + "name": "Learning Mode", + "description": "Configuration for learning and experimentation", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.5 + }, + "permissions": { + "mode": "confirm" + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "planning": { + "autoEnter": true, + "requireApproval": true, + "showTimeEstimates": true + }, + "checkpoints": { + "autoCheckpoint": true + } + } + }, + + "production": { + "name": "Production Deployment", + "description": "Configuration for production operations with safety checks", + "config": { + "general": { + "model": "claude-opus-4", + "temperature": 0.1 + }, + "permissions": { + "mode": "confirm", + "requireConfirmationFor": ["Bash", "Git", "Write", "Edit"] + }, + "hooks": { + "PreToolUse": "~/.claude/hooks/pre-commit.sh" + }, + "checkpoints": { + "autoCheckpoint": true + }, + "planning": { + "autoEnter": true, + "requireApproval": true + } + } + }, + + "ci_cd": { + "name": "CI/CD Pipeline", + "description": "Configuration for automated CI/CD operations", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0 + }, + "permissions": { + "mode": "unrestricted" + }, + "headless": { + "exitOnError": true, + "verbose": true, + "timeout": 3600 + }, + "logging": { + "level": "debug", + "file": "./ci-claude.log" + }, + "planning": { + "autoEnter": false, + "requireApproval": false + } + } + }, + + "security_audit": { + "name": "Security Audit", + "description": "Configuration for security-focused code analysis", + "config": { + "general": { + "model": "claude-opus-4", + "temperature": 0.2 + }, + "permissions": { + "mode": "plan" + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true, + "minThinkingTime": 10 + }, + "hooks": { + "PostToolUse:Read": "~/.claude/hooks/security-scan.sh ${file_path}" + } + } + }, + + "performance_optimization": { + "name": "Performance Optimization", + "description": "Configuration for performance analysis and optimization", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.4 + }, + "planning": { + "autoEnter": true, + "requireApproval": true + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5 + }, + "checkpoints": { + "autoCheckpoint": true + } + } + }, + + "pair_programming": { + "name": "Pair Programming", + "description": "Configuration for collaborative development", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.6 + }, + "permissions": { + "mode": "confirm" + }, + "planning": { + "autoEnter": true, + "requireApproval": true, + "showTimeEstimates": true + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "ui": { + "compactMode": false, + "showProgress": true + } + } + }, + + "refactoring": { + "name": "Large Refactoring", + "description": "Configuration for major refactoring work", + "config": { + "general": { + "model": "claude-opus-4", + "temperature": 0.3 + }, + "planning": { + "autoEnter": true, + "requireApproval": true, + "showTimeEstimates": true + }, + "checkpoints": { + "autoCheckpoint": true + }, + "hooks": { + "PreToolUse:Edit": "~/.claude/hooks/backup-file.sh ${file_path}", + "PostToolUse:Edit": "npm test -- --findRelatedTests ${file_path}" + }, + "permissions": { + "mode": "confirm" + } + } + }, + + "autonomous": { + "name": "Autonomous Development", + "description": "Configuration for autonomous work with auto mode safety checks", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.5 + }, + "permissions": { + "mode": "auto" + }, + "sandbox": { + "enabled": true, + "failIfUnavailable": false + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 3 + } + } + }, + + "documentation": { + "name": "Documentation Writing", + "description": "Configuration for writing documentation", + "config": { + "general": { + "model": "claude-sonnet-4-6", + "temperature": 0.7 + }, + "permissions": { + "mode": "unrestricted" + }, + "hooks": { + "PostToolUse:Write": "markdownlint ${file_path}" + } + } + } + } +} diff --git a/uk/09-advanced-features/planning-mode-examples.md b/uk/09-advanced-features/planning-mode-examples.md new file mode 100644 index 0000000..aa1ebf2 --- /dev/null +++ b/uk/09-advanced-features/planning-mode-examples.md @@ -0,0 +1,493 @@ +# Приклади режиму планування + +Реальні приклади ефективного використання режиму планування в Claude Code. + +## Приклад 1: Створення REST API + +### Без режиму планування + +``` +Користувач: Створи REST API для блогу + +Claude: Створю API... +[Одразу починає кодувати, може пропустити вимоги] +``` + +### З режимом планування + +``` +Користувач: /plan Створи REST API для блогу + +Claude: Створю комплексний план для API блогу. + +## План реалізації REST API блогу + +### Фаза 1: Налаштування проєкту (15 хв) +1. Ініціалізувати проєкт Node.js з Express +2. Налаштувати конфігурацію TypeScript +3. Встановити залежності (express, pg, jwt, joi) +4. Налаштувати змінні оточення +5. Встановити структуру проєкту + +### Фаза 2: Рівень бази даних (30 хв) +6. Спроєктувати схему БД + - таблиця users (id, email, password_hash, created_at) + - таблиця posts (id, user_id, title, content, published, created_at, updated_at) + - таблиця comments (id, post_id, user_id, content, created_at) +7. Створити файли міграцій +8. Налаштувати пул зʼєднань з БД +9. Реалізувати моделі БД + +### Фаза 3: Автентифікація (45 хв) +10. Реалізувати ендпоінт реєстрації +11. Реалізувати ендпоінт входу з JWT +12. Створити middleware автентифікації +13. Додати хешування паролів з bcrypt +14. Реалізувати логіку оновлення токенів + +### Фаза 4: API постів (40 хв) +15. GET /api/posts — список усіх опублікованих постів (з пагінацією) +16. GET /api/posts/:id — отримати окремий пост +17. POST /api/posts — створити новий пост (потрібна автентифікація) +18. PUT /api/posts/:id — оновити пост (автентифікація, перевірка власності) +19. DELETE /api/posts/:id — видалити пост (автентифікація, перевірка власності) +20. GET /api/users/:id/posts — отримати пости користувача + +### Фаза 5: API коментарів (30 хв) +21. GET /api/posts/:id/comments — отримати коментарі посту +22. POST /api/posts/:id/comments — додати коментар (потрібна автентифікація) +23. DELETE /api/comments/:id — видалити коментар (автентифікація, перевірка власності) + +### Фаза 6: Валідація та обробка помилок (30 хв) +24. Додати валідацію запитів з Joi +25. Реалізувати глобальний обробник помилок +26. Додати санітизацію вхідних даних +27. Реалізувати обмеження частоти запитів + +### Фаза 7: Тестування (60 хв) +28. Написати юніт-тести для моделей +29. Написати інтеграційні тести для ендпоінтів автентифікації +30. Написати інтеграційні тести для ендпоінтів постів +31. Написати інтеграційні тести для ендпоінтів коментарів +32. Досягти 80%+ покриття коду + +### Фаза 8: Документація та деплой (30 хв) +33. Згенерувати API-документацію зі Swagger +34. Створити README з інструкціями налаштування +35. Додати конфігурацію Docker +36. Налаштувати CI/CD пайплайн + +**Орієнтовний час**: 4.5 години +**Файлів для створення**: ~25 +**Ключові технології**: Express, PostgreSQL, JWT, TypeScript + +**Резюме API-ендпоінтів**: +- Автентифікація: 2 ендпоінти +- Пости: 6 ендпоінтів +- Коментарі: 3 ендпоінти +- Загалом: 11 ендпоінтів + +Готові продовжити? (yes/no/modify) + +Користувач: yes + +Claude: Починаю Фазу 1: Налаштування проєкту... +[Реалізує кожну фазу систематично] +``` + +## Приклад 2: Міграція бази даних + +### З режимом планування + +``` +Користувач: /plan Мігрувати з MongoDB на PostgreSQL + +Claude: Це складна міграція. Створю детальний план. + +## План міграції MongoDB → PostgreSQL + +### Фаза 1: Аналіз та підготовка (День 1) +1. Проаналізувати поточну схему MongoDB +2. Визначити звʼязки та обмеження даних +3. Задокументувати поточний обсяг та темп зростання даних +4. Спроєктувати еквівалентну схему PostgreSQL +5. Спланувати відповідності типів даних +6. Визначити потенційні складнощі міграції + +### Фаза 2: Налаштування PostgreSQL (День 1) +7. Налаштувати БД PostgreSQL +8. Створити схему з таблицями, індексами, обмеженнями +9. Налаштувати пул зʼєднань +10. Налаштувати стратегію резервного копіювання + +### Фаза 3: Реалізація dual-write (Дні 2-3) +11. Створити рівень абстракції БД +12. Реалізувати dual-write в обидві БД +13. Додати перевірки консистентності даних +14. Деплой dual-write на staging +15. Моніторинг на предмет проблем + +### Фаза 4: Міграція даних (День 4) +16. Створити скрипти експорту даних з MongoDB +17. Створити скрипти імпорту даних у PostgreSQL +18. Реалізувати логіку трансформації даних +19. Запустити початкову міграцію на копії продакшн-даних +20. Валідувати цілісність мігрованих даних + +### Фаза 5: Поступове переключення (Дні 5-7) +21. Увімкнути dual-write на продакшні +22. Мігрувати історичні дані пакетами +23. Безперервно валідувати консистентність даних +24. Моніторити обидві БД +25. Виправляти проблеми синхронізації даних + +### Фаза 6: PostgreSQL як основна (День 8) +26. Переключити операції читання на PostgreSQL +27. Моніторити продуктивність запитів +28. Оптимізувати повільні запити +29. Продовжити dual-write для безпеки + +### Фаза 7: Виведення MongoDB (Дні 9-10) +30. Припинити запис у MongoDB +31. Залишити MongoDB як бекап на 2 тижні +32. Видалити залежності від MongoDB з коду +33. Архівувати дані MongoDB +34. Вивести з експлуатації інстанс MongoDB + +**Орієнтовний час**: 10 днів +**Рівень ризику**: Високий +**Стратегія відкату**: Залишити MongoDB запущеною з dual-write +**Критерії успіху**: +- Нуль втрат даних +- <5% регресії продуктивності +- Усі тести проходять + +Продовжити з цим планом? (yes/no/modify) + +Користувач: Modify — додаймо план відкату для кожної фази + +Claude: Оновлений план з процедурами відкату для кожної фази... +``` + +## Приклад 3: Рефакторинг фронтенду + +``` +Користувач: /plan Рефакторити React-додаток з класових компонентів на хуки + +Claude: Створю систематичний план рефакторингу. + +## План міграції React Class → Hooks + +### Фаза 1: Підготовка та аналіз (2 години) +1. Аудит усіх класових компонентів +2. Категоризація за складністю: + - Прості (лише стан): ~15 компонентів + - Середні (методи життєвого циклу): ~23 компоненти + - Складні (кілька lifecycle, refs): ~8 компонентів +3. Визначити бібліотеки, що потребують оновлення +4. Створити граф залежностей компонентів +5. Спланувати порядок міграції (листові вузли першими) + +### Фаза 2: Налаштування та інструменти (1 година) +6. Оновити React до v18+ +7. Налаштувати правила ESLint для хуків +8. Створити шаблони конверсії +9. Налаштувати автоматичні тести +10. Створити контрольну точку перед початком + +### Фаза 3: Міграція простих компонентів (4 години) +11. Конвертувати прості stateful компоненти (15 компонентів) +12. Замінити this.state на useState +13. Замінити this.setState на сетери стану +14. Тестувати кожен компонент після конверсії +15. Оновити тести + +### Фаза 4: Міграція середніх компонентів (8 годин) +16. Конвертувати компоненти з методами lifecycle (23 компоненти) +17. Замінити componentDidMount на useEffect +18. Замінити componentDidUpdate на useEffect +19. Замінити componentWillUnmount на очищення useEffect +20. Ретельно тестувати + +### Фаза 5: Міграція складних компонентів (12 годин) +21. Конвертувати складні компоненти (8 компонентів) +22. Замінити refs на useRef +23. Витягти кастомні хуки для спільної логіки +24. Обробити крайні випадки (кілька useEffect) +25. Розширене тестування + +### Фаза 6: Витяг спільної логіки (6 годин) +26. Виявити дубльовану логіку між компонентами +27. Створити кастомні хуки: + - useAuth + - useFetch + - useLocalStorage + - useDebounce +28. Рефакторити компоненти для використання кастомних хуків +29. Тестувати кастомні хуки незалежно + +### Фаза 7: Оптимізація продуктивності (4 години) +30. Додати React.memo де потрібно +31. Оптимізувати з useCallback +32. Оптимізувати з useMemo +33. Профілювати та виправити регресії продуктивності + +### Фаза 8: Очищення та документація (2 години) +34. Видалити невикористані утиліти класових компонентів +35. Оновити документацію +36. Оновити рекомендації з кодування +37. Створити посібник міграції для команди + +**Орієнтовний час**: 5 днів (39 годин) +**Файлів для зміни**: 46 компонентів +**Рівень ризику**: Середній + +**Порядок міграції**: +1. Листові компоненти (без залежностей) +2. Компоненти середнього рівня +3. Контейнерні компоненти верхнього рівня +4. App.jsx (останній) + +Продовжити? (yes/no/modify) +``` + +## Приклад 4: Реалізація безпеки + +``` +Користувач: /plan Реалізувати комплексну безпеку для нашого веб-додатку + +Claude: Створю ретельний план реалізації безпеки. + +## План реалізації безпеки веб-додатку + +### Фаза 1: Аудит безпеки (День 1) +1. Запустити автоматичні сканери безпеки (npm audit, Snyk) +2. Перевірити залежності на вразливості +3. Перевірити відповідність OWASP Top 10 +4. Аудит потоків автентифікації +5. Перевірити практики обробки даних +6. Задокументувати поточні прогалини безпеки + +### Фаза 2: Посилення автентифікації (Дні 2-3) +7. Реалізувати вимоги до складності паролів +8. Додати індикатор надійності пароля +9. Реалізувати обмеження частоти спроб входу +10. Додати блокування облікового запису після невдалих спроб +11. Реалізувати 2FA (TOTP) +12. Покращити управління сесіями +13. Реалізувати безпечний потік скидання пароля + +### Фаза 3: Авторизація та контроль доступу (Дні 3-4) +14. Реалізувати RBAC (контроль доступу на основі ролей) +15. Додати перевірки дозволів на всіх ендпоінтах +16. Реалізувати принцип мінімальних привілеїв +17. Додати журнал аудиту для чутливих операцій +18. Реалізувати дозволи на рівні ресурсів + +### Фаза 4: Захист даних (Дні 4-5) +19. Реалізувати шифрування в стані спокою (чутливі поля) +20. Забезпечити TLS/SSL для всіх комунікацій +21. Реалізувати безпечне зберігання сесій +22. Додати маскування PII у журналах +23. Реалізувати політики збереження даних +24. Додати безпечну обробку завантаження файлів + +### Фаза 5: Валідація та санітизація введення (Дні 5-6) +25. Реалізувати валідацію введення на всіх ендпоінтах +26. Додати захист від XSS (Content Security Policy) +27. Реалізувати захист від SQL-інʼєкцій (параметризовані запити) +28. Додати захист від CSRF +29. Реалізувати ліміти розміру запитів +30. Додати валідацію типів файлів при завантаженні + +### Фаза 6: Заголовки безпеки та конфігурація (День 6) +31. Додати заголовки безпеки: + - Strict-Transport-Security + - X-Content-Type-Options + - X-Frame-Options + - X-XSS-Protection + - Content-Security-Policy +32. Правильно налаштувати CORS +33. Вимкнути непотрібні HTTP-методи +34. Видалити заголовки версії сервера + +### Фаза 7: Моніторинг та логування (День 7) +35. Реалізувати логування подій безпеки +36. Додати виявлення аномалій +37. Налаштувати виявлення вторгнень +38. Реалізувати алертинг у реальному часі +39. Створити дашборд безпеки + +### Фаза 8: Тестування та документація (Дні 8-9) +40. Провести тестування на проникнення +41. Запустити сканери безпеки +42. Протестувати всі функції безпеки +43. Створити документацію безпеки +44. Навчити команду практикам безпеки +45. Створити план реагування на інциденти + +### Фаза 9: Відповідність та політики (День 10) +46. Перевірка відповідності GDPR +47. Створити політику конфіденційності +48. Реалізувати права субʼєктів даних +49. Додати згоду на cookies +50. Створити документацію політик безпеки + +**Орієнтовний час**: 10 днів +**Рівень ризику**: Критичний +**Пріоритет**: Високий + +**Відповідність**: OWASP Top 10, GDPR + +Продовжити? (yes/no/modify) +``` + +## Приклад 5: Оптимізація продуктивності + +``` +Користувач: /plan Оптимізувати наш повільний сайт електронної комерції + +Claude: Створю комплексний план оптимізації продуктивності. + +## План оптимізації продуктивності електронної комерції + +### Фаза 1: Аудит продуктивності (4 години) +1. Запустити аудит Lighthouse +2. Проаналізувати профіль продуктивності Chrome DevTools +3. Виміряти Core Web Vitals: + - LCP (Largest Contentful Paint) + - FID (First Input Delay) + - CLS (Cumulative Layout Shift) +4. Визначити вузькі місця продуктивності +5. Створити базові метрики продуктивності + +**Поточні метрики**: +- LCP: 4.2с (ціль: <2.5с) +- FID: 280мс (ціль: <100мс) +- CLS: 0.25 (ціль: <0.1) +- Завантаження сторінки: 8.3с (ціль: <3с) + +### Фаза 2: Оптимізація зображень (6 годин) +6. Конвертувати зображення у формат WebP +7. Реалізувати адаптивні зображення +8. Додати ліниве завантаження зображень +9. Оптимізувати розміри зображень (стиснення) +10. Реалізувати CDN для зображень +11. Додати плейсхолдери зображень + +**Очікуваний вплив**: -40% час завантаження + +### Фаза 3: Розділення коду та ліниве завантаження (8 годин) +12. Реалізувати розділення коду за маршрутами +13. Ліниво завантажувати некритичні компоненти +14. Розділити vendor-бандли +15. Оптимізувати розміри чанків +16. Реалізувати динамічні імпорти +17. Додати попереднє завантаження критичних ресурсів + +**Очікуваний вплив**: -30% початковий розмір бандлу + +### Фаза 4: Стратегія кешування (6 годин) +18. Реалізувати кешування браузером (Cache-Control) +19. Додати service worker для офлайн-підтримки +20. Реалізувати кешування відповідей API +21. Додати кеш Redis для запитів до БД +22. Реалізувати stale-while-revalidate +23. Налаштувати кешування CDN + +**Очікуваний вплив**: -50% час відповіді API + +### Фаза 5: Оптимізація БД (8 годин) +24. Додати індекси в БД +25. Оптимізувати повільні запити (>100мс) +26. Реалізувати кешування результатів запитів +27. Додати пул зʼєднань +28. Денормалізувати де доречно +29. Реалізувати репліки БД для читання + +**Очікуваний вплив**: -60% час запитів до БД + +### Фаза 6: Оптимізація фронтенду (10 годин) +30. Мінімізувати та стиснути JavaScript +31. Мінімізувати та стиснути CSS +32. Видалити невикористаний CSS (PurgeCSS) +33. Реалізувати критичний CSS +34. Відкласти некритичний JavaScript +35. Зменшити розмір DOM +36. Оптимізувати рендеринг React (memo, useMemo) +37. Реалізувати віртуальний скролінг для довгих списків + +**Очікуваний вплив**: -35% час виконання JavaScript + +### Фаза 7: Оптимізація мережі (4 години) +38. Увімкнути HTTP/2 +39. Реалізувати підказки ресурсів (preconnect, prefetch) +40. Зменшити кількість HTTP-запитів +41. Увімкнути стиснення Brotli +42. Оптимізувати сторонні скрипти + +**Очікуваний вплив**: -25% мережевий час + +### Фаза 8: Моніторинг та тестування (4 години) +43. Налаштувати моніторинг продуктивності (Datadog/New Relic) +44. Додати Real User Monitoring (RUM) +45. Створити бюджети продуктивності +46. Налаштувати автоматичний Lighthouse CI +47. Тестувати на реальних пристроях + +**Орієнтовний час**: 50 годин (2 тижні) + +**Цільові метрики** (90-й перцентиль): +- LCP: <2.0с (з 4.2с) ✅ +- FID: <50мс (з 280мс) ✅ +- CLS: <0.05 (з 0.25) ✅ +- Завантаження: <2.5с (з 8.3с) ✅ + +**Порядок пріоритету**: +1. Оптимізація зображень (швидкі перемоги) +2. Розділення коду (високий вплив) +3. Кешування (високий вплив) +4. Оптимізація БД (критично) +5. Оптимізація фронтенду (полірування) + +Продовжити з цим планом? (yes/no/modify) +``` + +## Ключові висновки + +### Переваги режиму планування + +1. **Ясність**: Чіткий план дій перед початком +2. **Оцінка**: Оцінки часу та зусиль +3. **Оцінка ризиків**: Раннє виявлення потенційних проблем +4. **Пріоритезація**: Логічний порядок завдань +5. **Затвердження**: Перегляд та затвердження перед виконанням +6. **Модифікація**: Коригування плану на основі зворотного звʼязку + +### Коли використовувати режим планування + +✅ **Завжди використовуйте для**: +- Багатоденних проєктів +- Командних співпраць +- Критичних змін системи +- Вивчення нових концепцій +- Складного рефакторингу + +❌ **Не використовуйте для**: +- Виправлення помилок +- Дрібних правок +- Простих запитань +- Швидких експериментів + +### Найкращі практики + +1. **Ретельно переглядайте плани** перед затвердженням +2. **Модифікуйте плани**, коли помічаєте проблеми +3. **Розбивайте** складні завдання +4. **Оцінюйте реалістичні** часові рамки +5. **Включайте стратегії відкату** +6. **Додавайте критерії успіху** +7. **Плануйте тестування** на кожній фазі + +--- +**Останнє оновлення**: 9 квітня 2026 diff --git a/uk/09-advanced-features/setup-auto-mode-permissions.py b/uk/09-advanced-features/setup-auto-mode-permissions.py new file mode 100644 index 0000000..a677314 --- /dev/null +++ b/uk/09-advanced-features/setup-auto-mode-permissions.py @@ -0,0 +1,265 @@ +#!/usr/bin/env python3 +""" +setup-auto-mode-permissions.py + +Seed ~/.claude/settings.json with a conservative baseline of safe permissions +for Claude Code. The default set is read-only and local-inspection oriented; +optional flags let you widen the allowlist for editing, test execution, git +write operations, package installs, and GitHub CLI writes. + +Usage: + python3 setup-auto-mode-permissions.py + python3 setup-auto-mode-permissions.py --dry-run + python3 setup-auto-mode-permissions.py --include-edits --include-tests +""" + +from __future__ import annotations + +import argparse +import json +import tempfile +from pathlib import Path +from typing import Iterable + +SETTINGS_PATH = Path.home() / ".claude" / "settings.json" + +# Core baseline: read-only inspection and low-risk local shell commands. +CORE_PERMISSIONS = [ + "Read(*)", + "Glob(*)", + "Grep(*)", + "Agent(*)", + "Skill(*)", + "WebSearch(*)", + "WebFetch(*)", + "Bash(ls:*)", + "Bash(pwd:*)", + "Bash(which:*)", + "Bash(echo:*)", + "Bash(cat:*)", + "Bash(head:*)", + "Bash(tail:*)", + "Bash(wc:*)", + "Bash(sort:*)", + "Bash(uniq:*)", + "Bash(find:*)", + "Bash(dirname:*)", + "Bash(basename:*)", + "Bash(realpath:*)", + "Bash(file:*)", + "Bash(stat:*)", + "Bash(diff:*)", + "Bash(md5sum:*)", + "Bash(sha256sum:*)", + "Bash(date:*)", + "Bash(env:*)", + "Bash(printenv:*)", + "Bash(git status:*)", + "Bash(git log:*)", + "Bash(git diff:*)", + "Bash(git branch:*)", + "Bash(git show:*)", + "Bash(git rev-parse:*)", + "Bash(git remote -v:*)", + "Bash(git remote get-url:*)", + "Bash(git stash list:*)", +] + +# Optional but still local: file edits and task bookkeeping. +EDITING_PERMISSIONS = [ + "Edit(*)", + "Write(*)", + "NotebookEdit(*)", + "TaskCreate(*)", + "TaskUpdate(*)", +] + +# Optional dev/test commands. These can still execute arbitrary project scripts, +# so keep them opt-in rather than part of the default baseline. +TEST_AND_BUILD_PERMISSIONS = [ + "Bash(npm test:*)", + "Bash(cargo test:*)", + "Bash(go test:*)", + "Bash(pytest:*)", + "Bash(python3 -m pytest:*)", + "Bash(make:*)", + "Bash(cmake:*)", +] + +# Optional local git write operations. History-rewriting commands stay out of +# the default baseline because they are easy to misuse. +GIT_WRITE_PERMISSIONS = [ + "Bash(git add:*)", + "Bash(git commit:*)", + "Bash(git checkout:*)", + "Bash(git switch:*)", + "Bash(git stash:*)", + "Bash(git tag:*)", +] + +# Optional dependency/package commands. These are intentionally excluded from +# the default baseline because they can execute project hooks or fetch code. +PACKAGE_MANAGER_PERMISSIONS = [ + "Bash(npm ci:*)", + "Bash(npm install:*)", + "Bash(pip install:*)", + "Bash(pip3 install:*)", +] + +# Optional GitHub CLI write access. +GITHUB_WRITE_PERMISSIONS = [ + "Bash(gh pr create:*)", +] + +# Optional extra GitHub CLI read access. +GITHUB_READ_PERMISSIONS = [ + "Bash(gh pr view:*)", + "Bash(gh pr list:*)", + "Bash(gh issue view:*)", + "Bash(gh issue list:*)", + "Bash(gh repo view:*)", +] + + +def parse_args() -> argparse.Namespace: + parser = argparse.ArgumentParser( + description="Seed Claude Code settings with a conservative permission baseline." + ) + parser.add_argument( + "--dry-run", + action="store_true", + help="Preview the rules that would be added without writing settings.json", + ) + parser.add_argument( + "--include-edits", + action="store_true", + help="Add file-editing permissions (Edit/Write/NotebookEdit/TaskCreate/TaskUpdate)", + ) + parser.add_argument( + "--include-tests", + action="store_true", + help="Add local build/test commands such as pytest, cargo test, and make", + ) + parser.add_argument( + "--include-git-write", + action="store_true", + help="Add local git mutation commands such as add, commit, checkout, and stash", + ) + parser.add_argument( + "--include-packages", + action="store_true", + help="Add package install commands such as npm ci, npm install, and pip install", + ) + parser.add_argument( + "--include-gh-write", + action="store_true", + help="Add GitHub CLI write permissions such as gh pr create", + ) + parser.add_argument( + "--include-gh-read", + action="store_true", + help="Add GitHub CLI read permissions such as gh pr view and gh repo view", + ) + return parser.parse_args() + + +def load_settings(path: Path) -> dict: + if not path.exists(): + return {} + + try: + with path.open() as f: + settings = json.load(f) + except json.JSONDecodeError as exc: + raise SystemExit(f"Invalid JSON in {path}: {exc}") from exc + + if not isinstance(settings, dict): + raise SystemExit(f"Expected {path} to contain a JSON object.") + + return settings + + +def build_permissions(args: argparse.Namespace) -> list[str]: + permissions = list(CORE_PERMISSIONS) + + if args.include_edits: + permissions.extend(EDITING_PERMISSIONS) + + if args.include_tests: + permissions.extend(TEST_AND_BUILD_PERMISSIONS) + + if args.include_git_write: + permissions.extend(GIT_WRITE_PERMISSIONS) + + if args.include_packages: + permissions.extend(PACKAGE_MANAGER_PERMISSIONS) + + if args.include_gh_write: + permissions.extend(GITHUB_WRITE_PERMISSIONS) + + if args.include_gh_read: + permissions.extend(GITHUB_READ_PERMISSIONS) + + return permissions + + +def append_unique(existing: list, new_items: Iterable[str]) -> list[str]: + seen = set(existing) + added: list[str] = [] + for item in new_items: + if item not in seen: + existing.append(item) + seen.add(item) + added.append(item) + return added + + +def atomic_write_json(path: Path, payload: dict) -> None: + path.parent.mkdir(parents=True, exist_ok=True) + with tempfile.NamedTemporaryFile( + "w", + encoding="utf-8", + dir=str(path.parent), + delete=False, + ) as tmp: + json.dump(payload, tmp, indent=2) + tmp.write("\n") + tmp_path = Path(tmp.name) + + tmp_path.replace(path) + + +def main() -> None: + args = parse_args() + permissions_to_add = build_permissions(args) + + settings = load_settings(SETTINGS_PATH) + permissions = settings.setdefault("permissions", {}) + + if not isinstance(permissions, dict): + raise SystemExit("Expected permissions to be a JSON object.") + + allow = permissions.setdefault("allow", []) + if not isinstance(allow, list): + raise SystemExit("Expected permissions.allow to be a JSON array.") + + added = append_unique(allow, permissions_to_add) + + if not added: + print("Nothing to add — all selected rules already present.") + return + + print(f"{'Would add' if args.dry_run else 'Adding'} {len(added)} rule(s):") + for rule in added: + print(f" + {rule}") + + if args.dry_run: + print("\nDry run — no changes written.") + return + + atomic_write_json(SETTINGS_PATH, settings) + print(f"\nDone. {len(added)} rule(s) added to {SETTINGS_PATH}") + + +if __name__ == "__main__": + main() diff --git a/uk/10-cli/README.md b/uk/10-cli/README.md new file mode 100644 index 0000000..403b187 --- /dev/null +++ b/uk/10-cli/README.md @@ -0,0 +1,841 @@ + + + + + + + Claude How To + + +# Довідник CLI + +## Огляд + +Claude Code CLI (інтерфейс командного рядка — основний інструмент для роботи з терміналом) — це головний спосіб взаємодії з Claude Code. Він надає потужні опції для виконання запитів, управління сесіями, конфігурації моделей та інтеграції Claude у ваші робочі процеси розробки. + +## Архітектура + +```mermaid +graph TD + A["User Terminal"] -->|"claude [options] [query]"| B["Claude Code CLI"] + B -->|Interactive| C["REPL Mode"] + B -->|"--print"| D["Print Mode (SDK)"] + B -->|"--resume"| E["Session Resume"] + C -->|Conversation| F["Claude API"] + D -->|Single Query| F + E -->|Load Context| F + F -->|Response| G["Output"] + G -->|text/json/stream-json| H["Terminal/Pipe"] +``` + +## CLI-команди + +| Команда | Опис | Приклад | +|---------|------|---------| +| `claude` | Запуск інтерактивного REPL (циклу читання-виконання-виводу) | `claude` | +| `claude "query"` | Запуск REPL з початковим промптом | `claude "explain this project"` | +| `claude -p "query"` | Print-режим — запит і вихід | `claude -p "explain this function"` | +| `cat file \| claude -p "query"` | Обробка вмісту через pipe (конвеєр) | `cat logs.txt \| claude -p "explain"` | +| `claude -c` | Продовжити останню розмову | `claude -c` | +| `claude -c -p "query"` | Продовжити в print-режимі | `claude -c -p "check for type errors"` | +| `claude -r "" "query"` | Відновити сесію за ID або назвою | `claude -r "auth-refactor" "finish this PR"` | +| `claude update` | Оновити до останньої версії | `claude update` | +| `claude mcp` | Налаштування MCP-серверів | Див. [документацію MCP](../05-mcp/) | +| `claude mcp serve` | Запуск Claude Code як MCP-сервера | `claude mcp serve` | +| `claude agents` | Список усіх налаштованих субагентів | `claude agents` | +| `claude auto-mode defaults` | Вивести стандартні правила auto mode як JSON | `claude auto-mode defaults` | +| `claude remote-control` | Запуск сервера Remote Control | `claude remote-control` | +| `claude plugin` | Управління плагінами (встановлення, увімкнення, вимкнення) | `claude plugin install my-plugin` | +| `claude auth login` | Вхід (підтримує `--email`, `--sso`) | `claude auth login --email user@example.com` | +| `claude auth logout` | Вихід з поточного облікового запису | `claude auth logout` | +| `claude auth status` | Перевірка статусу авторизації (код виходу 0 = увійшов, 1 = ні) | `claude auth status` | + +## Основні прапорці + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `-p, --print` | Вивести відповідь без інтерактивного режиму | `claude -p "query"` | +| `-c, --continue` | Завантажити останню розмову | `claude --continue` | +| `-r, --resume` | Відновити конкретну сесію за ID або назвою | `claude --resume auth-refactor` | +| `-v, --version` | Показати номер версії | `claude -v` | +| `-w, --worktree` | Запуск в ізольованому git worktree (робочому дереві) | `claude -w` | +| `-n, --name` | Відображувана назва сесії | `claude -n "auth-refactor"` | +| `--from-pr ` | Відновити сесії, привʼязані до GitHub PR | `claude --from-pr 42` | +| `--remote "task"` | Створити веб-сесію на claude.ai | `claude --remote "implement API"` | +| `--remote-control, --rc` | Інтерактивна сесія з Remote Control | `claude --rc` | +| `--teleport` | Відновити веб-сесію локально | `claude --teleport` | +| `--teammate-mode` | Режим відображення Agent Teams | `claude --teammate-mode tmux` | +| `--bare` | Мінімальний режим (без хуків, навичок, плагінів, MCP, auto memory, CLAUDE.md) | `claude --bare` | +| `--enable-auto-mode` | Розблокувати auto permission mode | `claude --enable-auto-mode` | +| `--channels` | Підписка на MCP channel plugins | `claude --channels discord,telegram` | +| `--chrome` / `--no-chrome` | Увімкнути/вимкнути інтеграцію з браузером Chrome | `claude --chrome` | +| `--effort` | Встановити рівень зусиль мислення | `claude --effort high` | +| `--init` / `--init-only` | Запуск хуків ініціалізації | `claude --init` | +| `--maintenance` | Запуск хуків обслуговування та вихід | `claude --maintenance` | +| `--disable-slash-commands` | Вимкнути всі навички та слеш-команди | `claude --disable-slash-commands` | +| `--no-session-persistence` | Вимкнути збереження сесії (print mode) | `claude -p --no-session-persistence "query"` | + +### Інтерактивний vs Print-режим + +```mermaid +graph LR + A["claude"] -->|Default| B["Interactive REPL"] + A -->|"-p flag"| C["Print Mode"] + B -->|Features| D["Multi-turn conversation
Tab completion
History
Slash commands"] + C -->|Features| E["Single query
Scriptable
Pipeable
JSON output"] +``` + +**Інтерактивний режим** (за замовчуванням): +```bash +# Запуск інтерактивної сесії +claude + +# Запуск з початковим промптом +claude "explain the authentication flow" +``` + +**Print-режим** (неінтерактивний): +```bash +# Один запит, потім вихід +claude -p "what does this function do?" + +# Обробка вмісту файлу +cat error.log | claude -p "explain this error" + +# Ланцюжок з іншими інструментами +claude -p "list todos" | grep "URGENT" +``` + +## Модель та конфігурація + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--model` | Встановити модель (sonnet, opus, haiku або повна назва) | `claude --model opus` | +| `--fallback-model` | Автоматичний фолбек (запасна модель) при перевантаженні | `claude -p --fallback-model sonnet "query"` | +| `--agent` | Вказати агента для сесії | `claude --agent my-custom-agent` | +| `--agents` | Визначити кастомних субагентів через JSON | Див. [Конфігурація агентів](#конфігурація-агентів) | +| `--effort` | Встановити рівень зусиль (low, medium, high, max) | `claude --effort high` | + +### Приклади вибору моделі + +```bash +# Opus 4.6 для складних завдань +claude --model opus "design a caching strategy" + +# Haiku 4.5 для швидких завдань +claude --model haiku -p "format this JSON" + +# Повна назва моделі +claude --model claude-sonnet-4-6-20250929 "review this code" + +# З фолбеком для надійності +claude -p --model opus --fallback-model sonnet "analyze architecture" + +# opusplan (Opus планує, Sonnet виконує) +claude --model opusplan "design and implement the caching layer" +``` + +## Кастомізація системного промпта + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--system-prompt` | Замінити весь стандартний промпт | `claude --system-prompt "You are a Python expert"` | +| `--system-prompt-file` | Завантажити промпт з файлу (print mode) | `claude -p --system-prompt-file ./prompt.txt "query"` | +| `--append-system-prompt` | Додати до стандартного промпта | `claude --append-system-prompt "Always use TypeScript"` | + +### Приклади системного промпта + +```bash +# Повністю кастомна персона +claude --system-prompt "You are a senior security engineer. Focus on vulnerabilities." + +# Додавання конкретних інструкцій +claude --append-system-prompt "Always include unit tests with code examples" + +# Завантаження складного промпта з файлу +claude -p --system-prompt-file ./prompts/code-reviewer.txt "review main.py" +``` + +### Порівняння прапорців системного промпта + +| Прапорець | Поведінка | Інтерактивний | Print | +|-----------|----------|---------------|-------| +| `--system-prompt` | Замінює весь стандартний системний промпт | ✅ | ✅ | +| `--system-prompt-file` | Замінює промптом з файлу | ❌ | ✅ | +| `--append-system-prompt` | Додає до стандартного системного промпта | ✅ | ✅ | + +**Використовуйте `--system-prompt-file` лише в print-режимі. Для інтерактивного режиму використовуйте `--system-prompt` або `--append-system-prompt`.** + +## Управління інструментами та дозволами + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--tools` | Обмежити доступні вбудовані інструменти | `claude -p --tools "Bash,Edit,Read" "query"` | +| `--allowedTools` | Інструменти, що виконуються без запиту дозволу | `"Bash(git log:*)" "Read"` | +| `--disallowedTools` | Інструменти, видалені з контексту | `"Bash(rm:*)" "Edit"` | +| `--dangerously-skip-permissions` | Пропустити всі запити дозволів | `claude --dangerously-skip-permissions` | +| `--permission-mode` | Починати у вказаному режимі дозволів | `claude --permission-mode auto` | +| `--permission-prompt-tool` | MCP-інструмент для обробки дозволів | `claude -p --permission-prompt-tool mcp_auth "query"` | +| `--enable-auto-mode` | Розблокувати auto permission mode | `claude --enable-auto-mode` | + +### Приклади дозволів + +```bash +# Режим тільки для читання — код-рев'ю +claude --permission-mode plan "review this codebase" + +# Обмеження до безпечних інструментів +claude --tools "Read,Grep,Glob" -p "find all TODO comments" + +# Дозволити конкретні git-команди без запитів +claude --allowedTools "Bash(git status:*)" "Bash(git log:*)" + +# Заблокувати небезпечні операції +claude --disallowedTools "Bash(rm -rf:*)" "Bash(git push --force:*)" +``` + +## Вивід та формат + +| Прапорець | Опис | Опції | Приклад | +|-----------|------|-------|---------| +| `--output-format` | Формат виводу (print mode) | `text`, `json`, `stream-json` | `claude -p --output-format json "query"` | +| `--input-format` | Формат вводу (print mode) | `text`, `stream-json` | `claude -p --input-format stream-json` | +| `--verbose` | Увімкнути детальне логування | | `claude --verbose` | +| `--include-partial-messages` | Включити потокові (streaming) події | Потребує `stream-json` | `claude -p --output-format stream-json --include-partial-messages "query"` | +| `--json-schema` | Отримати валідований JSON за схемою | | `claude -p --json-schema '{"type":"object"}' "query"` | +| `--max-budget-usd` | Максимальні витрати для print mode | | `claude -p --max-budget-usd 5.00 "query"` | + +### Приклади формату виводу + +```bash +# Звичайний текст (за замовчуванням) +claude -p "explain this code" + +# JSON для програмного використання +claude -p --output-format json "list all functions in main.py" + +# Потоковий JSON для обробки в реальному часі +claude -p --output-format stream-json "generate a long report" + +# Структурований вивід із валідацією за схемою +claude -p --json-schema '{"type":"object","properties":{"bugs":{"type":"array"}}}' \ + "find bugs in this code and return as JSON" +``` + +## Робочий простір та каталог + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--add-dir` | Додати додаткові робочі каталоги | `claude --add-dir ../apps ../lib` | +| `--setting-sources` | Джерела налаштувань через кому | `claude --setting-sources user,project` | +| `--settings` | Завантажити налаштування з файлу або JSON | `claude --settings ./settings.json` | +| `--plugin-dir` | Завантажити плагіни з каталогу (повторюваний) | `claude --plugin-dir ./my-plugin` | + +### Приклад роботи з кількома каталогами + +```bash +# Робота в кількох каталогах проєкту одночасно +claude --add-dir ../frontend ../backend ../shared "find all API endpoints" + +# Завантаження кастомних налаштувань +claude --settings '{"model":"opus","verbose":true}' "complex task" +``` + +## Конфігурація MCP + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--mcp-config` | Завантажити MCP-сервери з JSON | `claude --mcp-config ./mcp.json` | +| `--strict-mcp-config` | Використовувати тільки вказану MCP-конфігурацію | `claude --strict-mcp-config --mcp-config ./mcp.json` | +| `--channels` | Підписка на MCP channel plugins | `claude --channels discord,telegram` | + +### Приклади MCP + +```bash +# Завантаження GitHub MCP-сервера +claude --mcp-config ./github-mcp.json "list open PRs" + +# Суворий режим — тільки вказані сервери +claude --strict-mcp-config --mcp-config ./production-mcp.json "deploy to staging" +``` + +## Управління сесіями + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--session-id` | Використовувати конкретний ID сесії (UUID) | `claude --session-id "550e8400-..."` | +| `--fork-session` | Створити нову сесію при відновленні | `claude --resume abc123 --fork-session` | + +### Приклади сесій + +```bash +# Продовжити останню розмову +claude -c + +# Відновити іменовану сесію +claude -r "feature-auth" "continue implementing login" + +# Форк сесії для експериментів +claude --resume feature-auth --fork-session "try alternative approach" + +# Використання конкретного ID сесії +claude --session-id "550e8400-e29b-41d4-a716-446655440000" "continue" +``` + +### Форк сесії + +Створення відгалуження від існуючої сесії для експериментів: + +```bash +# Форк сесії для альтернативного підходу +claude --resume abc123 --fork-session "try alternative implementation" + +# Форк з кастомним повідомленням +claude -r "feature-auth" --fork-session "test with different architecture" +``` + +**Випадки використання:** +- Спроба альтернативних реалізацій без втрати оригінальної сесії +- Паралельне експериментування з різними підходами +- Створення відгалужень від успішної роботи для варіацій +- Тестування зламуючих змін (breaking changes) без впливу на основну сесію + +Оригінальна сесія залишається без змін, а форк стає новою незалежною сесією. + +## Розширені функції + +| Прапорець | Опис | Приклад | +|-----------|------|---------| +| `--chrome` | Увімкнути інтеграцію з браузером Chrome | `claude --chrome` | +| `--no-chrome` | Вимкнути інтеграцію з Chrome | `claude --no-chrome` | +| `--ide` | Автопідключення до IDE, якщо доступна | `claude --ide` | +| `--max-turns` | Обмежити кількість агентних кроків (неінтерактивний режим) | `claude -p --max-turns 3 "query"` | +| `--debug` | Увімкнути режим налагодження з фільтрацією | `claude --debug "api,mcp"` | +| `--enable-lsp-logging` | Увімкнути детальне логування LSP | `claude --enable-lsp-logging` | +| `--betas` | Beta-заголовки для API-запитів | `claude --betas interleaved-thinking` | +| `--plugin-dir` | Завантажити плагіни з каталогу (повторюваний) | `claude --plugin-dir ./my-plugin` | +| `--enable-auto-mode` | Розблокувати auto permission mode | `claude --enable-auto-mode` | +| `--effort` | Встановити рівень зусиль мислення | `claude --effort high` | +| `--bare` | Мінімальний режим (без хуків, навичок, плагінів, MCP, auto memory, CLAUDE.md) | `claude --bare` | +| `--channels` | Підписка на MCP channel plugins | `claude --channels discord` | +| `--tmux` | Створити tmux-сесію для worktree | `claude --tmux` | +| `--fork-session` | Створити новий ID сесії при відновленні | `claude --resume abc --fork-session` | +| `--max-budget-usd` | Максимальні витрати (print mode) | `claude -p --max-budget-usd 5.00 "query"` | +| `--json-schema` | Валідований JSON-вивід | `claude -p --json-schema '{"type":"object"}' "q"` | + +### Приклади розширених функцій + +```bash +# Обмежити автономні дії +claude -p --max-turns 5 "refactor this module" + +# Налагодження API-викликів +claude --debug "api" "test query" + +# Увімкнути інтеграцію з IDE +claude --ide "help me with this file" +``` + +## Конфігурація агентів + +Прапорець `--agents` приймає JSON-обʼєкт, що визначає кастомних субагентів для сесії. + +### Формат JSON для агентів + +```json +{ + "agent-name": { + "description": "Обовʼязково: коли викликати цього агента", + "prompt": "Обовʼязково: системний промпт для агента", + "tools": ["Необовʼязково", "масив", "інструментів"], + "model": "необовʼязково: sonnet|opus|haiku" + } +} +``` + +**Обовʼязкові поля:** +- `description` — опис природною мовою, коли використовувати цього агента +- `prompt` — системний промпт, що визначає роль та поведінку агента + +**Необовʼязкові поля:** +- `tools` — масив доступних інструментів (якщо не вказано, успадковує всі) + - Формат: `["Read", "Grep", "Glob", "Bash"]` +- `model` — модель: `sonnet`, `opus` або `haiku` + +### Повний приклад агентів + +```json +{ + "code-reviewer": { + "description": "Expert code reviewer. Use proactively after code changes.", + "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.", + "tools": ["Read", "Grep", "Glob", "Bash"], + "model": "sonnet" + }, + "debugger": { + "description": "Debugging specialist for errors and test failures.", + "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes.", + "tools": ["Read", "Edit", "Bash", "Grep"], + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist for generating guides.", + "prompt": "You are a technical writer. Create clear, comprehensive documentation.", + "tools": ["Read", "Write"], + "model": "haiku" + } +} +``` + +### Приклади команд з агентами + +```bash +# Визначення кастомних агентів інлайн +claude --agents '{ + "security-auditor": { + "description": "Security specialist for vulnerability analysis", + "prompt": "You are a security expert. Find vulnerabilities and suggest fixes.", + "tools": ["Read", "Grep", "Glob"], + "model": "opus" + } +}' "audit this codebase for security issues" + +# Завантаження агентів з файлу +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" + +# Комбінація з іншими прапорцями +claude -p --agents "$(cat agents.json)" --model sonnet "analyze performance" +``` + +### Пріоритет агентів + +При наявності кількох визначень агентів вони завантажуються в такому порядку пріоритету: +1. **CLI-визначені** (прапорець `--agents`) — для конкретної сесії +2. **Рівень користувача** (`~/.claude/agents/`) — для всіх проєктів +3. **Рівень проєкту** (`.claude/agents/`) — для поточного проєкту + +CLI-визначені агенти перевизначають агентів рівня користувача та проєкту на час сесії. + +--- + +## Високоцінні сценарії використання + +### 1. Інтеграція CI/CD + +Використання Claude Code у CI/CD-пайплайнах (конвеєрах безперервної інтеграції/доставки) для автоматизованого код-рев'ю, тестування та документації. + +**Приклад GitHub Actions:** + +```yaml +name: AI Code Review + +on: [pull_request] + +jobs: + review: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Claude Code + run: npm install -g @anthropic-ai/claude-code + + - name: Run Code Review + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + claude -p --output-format json \ + --max-turns 1 \ + "Review the changes in this PR for: + - Security vulnerabilities + - Performance issues + - Code quality + Output as JSON with 'issues' array" > review.json + + - name: Post Review Comment + uses: actions/github-script@v7 + with: + script: | + const fs = require('fs'); + const review = JSON.parse(fs.readFileSync('review.json', 'utf8')); + // Обробка та публікація коментарів рев'ю +``` + +**Пайплайн Jenkins:** + +```groovy +pipeline { + agent any + stages { + stage('AI Review') { + steps { + sh ''' + claude -p --output-format json \ + --max-turns 3 \ + "Analyze test coverage and suggest missing tests" \ + > coverage-analysis.json + ''' + } + } + } +} +``` + +### 2. Pipe-обробка скриптів + +Обробка файлів, журналів та даних через Claude для аналізу. + +**Аналіз журналів:** + +```bash +# Аналіз журналів помилок +tail -1000 /var/log/app/error.log | claude -p "summarize these errors and suggest fixes" + +# Пошук патернів у журналах доступу +cat access.log | claude -p "identify suspicious access patterns" + +# Аналіз git-історії +git log --oneline -50 | claude -p "summarize recent development activity" +``` + +**Обробка коду:** + +```bash +# Рев'ю конкретного файлу +cat src/auth.ts | claude -p "review this authentication code for security issues" + +# Генерація документації +cat src/api/*.ts | claude -p "generate API documentation in markdown" + +# Пошук TODO та пріоритезація +grep -r "TODO" src/ | claude -p "prioritize these TODOs by importance" +``` + +### 3. Мультисесійні робочі процеси + +Управління складними проєктами з кількома потоками розмов. + +```bash +# Запуск сесії для гілки функції +claude -r "feature-auth" "let's implement user authentication" + +# Пізніше — продовження сесії +claude -r "feature-auth" "add password reset functionality" + +# Форк для альтернативного підходу +claude --resume feature-auth --fork-session "try OAuth instead" + +# Переключення між різними сесіями функцій +claude -r "feature-payments" "continue with Stripe integration" +``` + +### 4. Кастомна конфігурація агентів + +Визначення спеціалізованих агентів для робочих процесів вашої команди. + +```bash +# Збереження конфігурації агентів у файл +cat > ~/.claude/agents.json << 'EOF' +{ + "reviewer": { + "description": "Code reviewer for PR reviews", + "prompt": "Review code for quality, security, and maintainability.", + "model": "opus" + }, + "documenter": { + "description": "Documentation specialist", + "prompt": "Generate clear, comprehensive documentation.", + "model": "sonnet" + }, + "refactorer": { + "description": "Code refactoring expert", + "prompt": "Suggest and implement clean code refactoring.", + "tools": ["Read", "Edit", "Glob"] + } +} +EOF + +# Використання агентів у сесії +claude --agents "$(cat ~/.claude/agents.json)" "review the auth module" +``` + +### 5. Пакетна обробка + +Обробка кількох запитів з однаковими налаштуваннями. + +```bash +# Обробка кількох файлів +for file in src/*.ts; do + echo "Processing $file..." + claude -p --model haiku "summarize this file: $(cat $file)" >> summaries.md +done + +# Пакетне код-рев'ю +find src -name "*.py" -exec sh -c ' + echo "## $1" >> review.md + cat "$1" | claude -p "brief code review" >> review.md +' _ {} \; + +# Генерація тестів для всіх модулів +for module in $(ls src/modules/); do + claude -p "generate unit tests for src/modules/$module" > "tests/$module.test.ts" +done +``` + +### 6. Безпечна розробка + +Використання контролю дозволів для безпечної роботи. + +```bash +# Аудит безпеки тільки для читання +claude --permission-mode plan \ + --tools "Read,Grep,Glob" \ + "audit this codebase for security vulnerabilities" + +# Блокування небезпечних команд +claude --disallowedTools "Bash(rm:*)" "Bash(curl:*)" "Bash(wget:*)" \ + "help me clean up this project" + +# Обмежена автоматизація +claude -p --max-turns 2 \ + --allowedTools "Read" "Glob" \ + "find all hardcoded credentials" +``` + +### 7. JSON API інтеграція + +Використання Claude як програмного API для ваших інструментів з парсингом через `jq`. + +```bash +# Структурований аналіз +claude -p --output-format json \ + --json-schema '{"type":"object","properties":{"functions":{"type":"array"},"complexity":{"type":"string"}}}' \ + "analyze main.py and return function list with complexity rating" + +# Інтеграція з jq для обробки +claude -p --output-format json "list all API endpoints" | jq '.endpoints[]' + +# Використання в скриптах +RESULT=$(claude -p --output-format json "is this code secure? answer with {secure: boolean, issues: []}" < code.py) +if echo "$RESULT" | jq -e '.secure == false' > /dev/null; then + echo "Security issues found!" + echo "$RESULT" | jq '.issues[]' +fi +``` + +### Приклади парсингу jq + +Парсинг та обробка JSON-виводу Claude за допомогою `jq`: + +```bash +# Витяг конкретних полів +claude -p --output-format json "analyze this code" | jq '.result' + +# Фільтрація елементів масиву +claude -p --output-format json "list issues" | jq -r '.issues[] | select(.severity=="high")' + +# Витяг кількох полів +claude -p --output-format json "describe the project" | jq -r '.{name, version, description}' + +# Конвертація в CSV +claude -p --output-format json "list functions" | jq -r '.functions[] | [.name, .lineCount] | @csv' + +# Умовна обробка +claude -p --output-format json "check security" | jq 'if .vulnerabilities | length > 0 then "UNSAFE" else "SAFE" end' + +# Витяг вкладених значень +claude -p --output-format json "analyze performance" | jq '.metrics.cpu.usage' + +# Обробка всього масиву +claude -p --output-format json "find todos" | jq '.todos | length' + +# Трансформація виводу +claude -p --output-format json "list improvements" | jq 'map({title: .title, priority: .priority})' +``` + +--- + +## Моделі + +Claude Code підтримує кілька моделей з різними можливостями: + +| Модель | ID | Контекстне вікно | Примітки | +|--------|-----|-----------------|----------| +| Opus 4.6 | `claude-opus-4-6` | 1M токенів | Найпотужніша, адаптивні рівні зусиль | +| Sonnet 4.6 | `claude-sonnet-4-6` | 1M токенів | Баланс швидкості та можливостей | +| Haiku 4.5 | `claude-haiku-4-5` | 1M токенів | Найшвидша, оптимальна для швидких завдань | + +### Вибір моделі + +```bash +# Використання коротких назв +claude --model opus "complex architectural review" +claude --model sonnet "implement this feature" +claude --model haiku -p "format this JSON" + +# Використання alias opusplan (Opus планує, Sonnet виконує) +claude --model opusplan "design and implement the API" + +# Перемикання на швидкий режим під час сесії +/fast +``` + +### Рівні зусиль (Opus 4.6) + +Opus 4.6 підтримує адаптивне міркування з рівнями зусиль: + +```bash +# Через прапорець CLI +claude --effort high "complex review" + +# Через слеш-команду +/effort high + +# Через змінну оточення +export CLAUDE_CODE_EFFORT_LEVEL=high # low, medium, high або max (лише Opus 4.6) +``` + +Ключове слово "ultrathink" у промптах активує глибоке міркування. Рівень `max` — ексклюзивний для Opus 4.6. + +--- + +## Ключові змінні оточення + +| Змінна | Опис | +|--------|------| +| `ANTHROPIC_API_KEY` | API-ключ для автентифікації | +| `ANTHROPIC_MODEL` | Перевизначення стандартної моделі | +| `ANTHROPIC_CUSTOM_MODEL_OPTION` | Кастомна опція моделі для API | +| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Перевизначення стандартного ID моделі Opus | +| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Перевизначення стандартного ID моделі Sonnet | +| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Перевизначення стандартного ID моделі Haiku | +| `MAX_THINKING_TOKENS` | Бюджет токенів розширеного мислення | +| `CLAUDE_CODE_EFFORT_LEVEL` | Рівень зусиль (`low`/`medium`/`high`/`max`) | +| `CLAUDE_CODE_SIMPLE` | Мінімальний режим, встановлюється прапорцем `--bare` | +| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | Вимкнути автоматичне оновлення CLAUDE.md | +| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | Вимкнути виконання фонових завдань | +| `CLAUDE_CODE_DISABLE_CRON` | Вимкнути заплановані/cron-завдання | +| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | Вимкнути git-інструкції | +| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | Вимкнути оновлення заголовка терміналу | +| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | Вимкнути контекстне вікно 1M токенів | +| `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK` | Вимкнути фолбек без стрімінгу | +| `CLAUDE_CODE_ENABLE_TASKS` | Увімкнути функцію списку завдань | +| `CLAUDE_CODE_TASK_LIST_ID` | Іменований каталог завдань, спільний між сесіями | +| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | Увімкнути/вимкнути пропозиції промптів (`true`/`false`) | +| `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` | Увімкнути експериментальні Agent Teams | +| `CLAUDE_CODE_NEW_INIT` | Використовувати новий потік ініціалізації | +| `CLAUDE_CODE_SUBAGENT_MODEL` | Модель для виконання субагентів | +| `CLAUDE_CODE_PLUGIN_SEED_DIR` | Каталог для seed-файлів плагінів | +| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | Змінні оточення для видалення з підпроцесів | +| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Перевизначити відсоток автокомпакції | +| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | Таймаут простою потоку в мілісекундах | +| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Бюджет символів для інструментів слеш-команд | +| `ENABLE_TOOL_SEARCH` | Увімкнути пошук інструментів | +| `MAX_MCP_OUTPUT_TOKENS` | Максимум токенів для виводу MCP-інструмента | + +--- + +## Швидкий довідник + +### Найпоширеніші команди + +```bash +# Інтерактивна сесія +claude + +# Швидке питання +claude -p "how do I..." + +# Продовжити розмову +claude -c + +# Обробити файл +cat file.py | claude -p "review this" + +# JSON-вивід для скриптів +claude -p --output-format json "query" +``` + +### Комбінації прапорців + +| Сценарій | Команда | +|----------|---------| +| Швидке код-рев'ю | `cat file \| claude -p "review"` | +| Структурований вивід | `claude -p --output-format json "query"` | +| Безпечне дослідження | `claude --permission-mode plan` | +| Автономність з безпекою | `claude --enable-auto-mode --permission-mode auto` | +| CI/CD інтеграція | `claude -p --max-turns 3 --output-format json` | +| Відновлення роботи | `claude -r "session-name"` | +| Кастомна модель | `claude --model opus "complex task"` | +| Мінімальний режим | `claude --bare "quick query"` | +| Ліміт бюджету | `claude -p --max-budget-usd 2.00 "analyze code"` | + +--- + +## Усунення несправностей + +### Команда не знайдена + +**Проблема:** `claude: command not found` + +**Рішення:** +- Встановіть Claude Code: `npm install -g @anthropic-ai/claude-code` +- Перевірте, що PATH включає глобальний bin-каталог npm +- Спробуйте запуск з повним шляхом: `npx claude` + +### Проблеми з API-ключем + +**Проблема:** Помилка автентифікації + +**Рішення:** +- Встановіть API-ключ: `export ANTHROPIC_API_KEY=your-key` +- Перевірте валідність ключа та наявність достатнього балансу +- Перевірте дозволи ключа для запитуваної моделі + +### Сесія не знайдена + +**Проблема:** Неможливо відновити сесію + +**Рішення:** +- Перегляньте доступні сесії, щоб знайти правильну назву/ID +- Сесії можуть закінчуватися після періоду неактивності +- Використовуйте `-c` для продовження останньої сесії + +### Проблеми з форматом виводу + +**Проблема:** JSON-вивід пошкоджений + +**Рішення:** +- Використовуйте `--json-schema` для примусового дотримання структури +- Додайте явні інструкції щодо JSON у промпті +- Використовуйте `--output-format json` (а не просто просіть JSON у промпті) + +### Відмова в дозволі + +**Проблема:** Виконання інструменту заблоковане + +**Рішення:** +- Перевірте налаштування `--permission-mode` +- Перегляньте прапорці `--allowedTools` та `--disallowedTools` +- Використовуйте `--dangerously-skip-permissions` для автоматизації (з обережністю) + +--- + +## Додаткові ресурси + +- **[Офіційний довідник CLI](https://code.claude.com/docs/en/cli-reference)** — повний довідник команд +- **[Документація Headless Mode](https://code.claude.com/docs/en/headless)** — автоматизоване виконання +- **[Слеш-команди](../01-slash-commands/)** — кастомні ярлики в Claude +- **[Посібник з памʼяті](../02-memory/)** — постійний контекст через CLAUDE.md +- **[Протокол MCP](../05-mcp/)** — інтеграція зовнішніх інструментів +- **[Розширені функції](../09-advanced-features/)** — режим планування, розширене мислення +- **[Посібник субагентів](../04-subagents/)** — делеговане виконання завдань + +--- + +*Частина серії посібників [Claude How To](../)* + +--- +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/CATALOG.md b/uk/CATALOG.md new file mode 100644 index 0000000..c51d10a --- /dev/null +++ b/uk/CATALOG.md @@ -0,0 +1,528 @@ + + + + + + + Claude How To + + +# Каталог функцій Claude Code + +> Швидкий довідник усіх функцій Claude Code: команди, агенти, навички, плагіни та хуки. + +**Навігація**: [Команди](#слеш-команди) | [Режими дозволів](#режими-дозволів) | [Субагенти](#субагенти) | [Навички](#навички-skills) | [Плагіни](#плагіни) | [MCP-сервери](#mcp-сервери) | [Хуки](#хуки) | [Пам'ять](#файли-памяті) | [Нові функції](#нові-функції-березень-2026) + +--- + +## Підсумок + +| Функція | Вбудовані | Приклади | Разом | Довідник | +|---------|-----------|----------|-------|----------| +| **Слеш-команди** | 55+ | 8 | 63+ | [01-slash-commands/](../01-slash-commands/) | +| **Субагенти** | 6 | 11 | 17 | [04-subagents/](../04-subagents/) | +| **Навички (Skills)** | 5 вбудованих | 4 | 9 | [03-skills/](../03-skills/) | +| **Плагіни** | - | 3 | 3 | [07-plugins/](../07-plugins/) | +| **MCP-сервери** | 1 | 8 | 9 | [05-mcp/](../05-mcp/) | +| **Хуки** | 25 подій | 8 | 8 | [06-hooks/](../06-hooks/) | +| **Пам'ять** | 7 типів | 3 | 3 | [02-memory/](../02-memory/) | +| **Разом** | **99** | **45** | **119** | | + +--- + +## Слеш-команди + +Команди — це ярлики, які викликає користувач для виконання конкретних дій. + +### Вбудовані команди + +| Команда | Опис | Коли використовувати | +|---------|------|---------------------| +| `/help` | Показати довідку | Початок роботи, вивчення команд | +| `/btw` | Побічне запитання без додавання в контекст | Швидкі відступи | +| `/chrome` | Налаштувати інтеграцію з Chrome | Автоматизація браузера | +| `/clear` | Очистити історію розмови | Почати заново, зменшити контекст | +| `/diff` | Інтерактивний перегляд змін | Перегляд змін | +| `/config` | Переглянути/змінити конфігурацію | Налаштування поведінки | +| `/status` | Показати статус сесії | Перевірка поточного стану | +| `/agents` | Список доступних агентів | Перегляд варіантів делегування | +| `/skills` | Список доступних навичок | Перегляд автовикликів | +| `/hooks` | Список налаштованих хуків | Налагодження автоматизації | +| `/insights` | Аналіз патернів сесії | Оптимізація сесії | +| `/install-slack-app` | Встановити Slack-застосунок Claude | Інтеграція зі Slack | +| `/keybindings` | Налаштувати клавіатурні скорочення | Кастомізація клавіш | +| `/mcp` | Список MCP-серверів | Перевірка зовнішніх інтеграцій | +| `/memory` | Переглянути завантажені файли пам'яті | Налагодження контексту | +| `/mobile` | Згенерувати QR-код для мобільного | Мобільний доступ | +| `/passes` | Переглянути використання пропусків | Інформація про підписку | +| `/plugin` | Управління плагінами | Встановлення/видалення розширень | +| `/plan` | Увійти в режим планування | Складні реалізації | +| `/rewind` | Відкат до контрольної точки | Скасування змін, дослідження альтернатив | +| `/checkpoint` | Управління контрольними точками | Збереження/відновлення станів | +| `/cost` | Показати витрати на токени | Моніторинг витрат | +| `/context` | Показати використання контекстного вікна | Управління довжиною розмови | +| `/export` | Експортувати розмову | Збереження для довідки | +| `/extra-usage` | Налаштувати ліміти використання | Управління лімітами | +| `/feedback` | Надіслати відгук або баг-репорт | Повідомлення про проблеми | +| `/login` | Автентифікація в Anthropic | Доступ до функцій | +| `/logout` | Вийти з облікового запису | Зміна акаунту | +| `/sandbox` | Перемкнути режим пісочниці | Безпечне виконання команд | +| `/doctor` | Запустити діагностику | Усунення неполадок | +| `/reload-plugins` | Перезавантажити плагіни | Управління плагінами | +| `/release-notes` | Показати нотатки до релізу | Перевірка нових функцій | +| `/remote-control` | Увімкнути віддалене керування | Віддалений доступ | +| `/permissions` | Управління дозволами | Контроль доступу | +| `/session` | Управління сесіями | Багатосесійні процеси | +| `/rename` | Перейменувати поточну сесію | Організація сесій | +| `/resume` | Відновити попередню сесію | Продовження роботи | +| `/todo` | Переглянути/управляти списком завдань | Відстеження завдань | +| `/tasks` | Переглянути фонові завдання | Моніторинг асинхронних операцій | +| `/copy` | Скопіювати останню відповідь у буфер | Швидке поширення | +| `/teleport` | Перенести сесію на інший комп'ютер | Продовження роботи віддалено | +| `/desktop` | Відкрити десктопний застосунок Claude | Перехід на десктопний інтерфейс | +| `/theme` | Змінити колірну тему | Кастомізація вигляду | +| `/usage` | Показати статистику API | Моніторинг квот і витрат | +| `/fork` | Розгалужити поточну розмову | Дослідження альтернатив | +| `/stats` | Показати статистику сесії | Перегляд метрик сесії | +| `/statusline` | Налаштувати рядок стану | Кастомізація відображення | +| `/stickers` | Переглянути стікери сесії | Ігрові нагороди | +| `/fast` | Перемкнути швидкий режим | Прискорення відповідей | +| `/terminal-setup` | Налаштувати інтеграцію з терміналом | Налаштування терміналу | +| `/upgrade` | Перевірити оновлення | Управління версіями | + +### Кастомні команди (приклади) + +| Команда | Опис | Коли використовувати | Область | Встановлення | +|---------|------|---------------------|---------|-------------| +| `/optimize` | Аналіз коду для оптимізації | Покращення продуктивності | Проект | `cp 01-slash-commands/optimize.md .claude/commands/` | +| `/pr` | Підготовка pull request | Перед відправкою PR | Проект | `cp 01-slash-commands/pr.md .claude/commands/` | +| `/generate-api-docs` | Генерація API-документації | Документування API | Проект | `cp 01-slash-commands/generate-api-docs.md .claude/commands/` | +| `/commit` | Створення git-коміту з контекстом | Фіксація змін | Користувач | `cp 01-slash-commands/commit.md .claude/commands/` | +| `/push-all` | Stage, commit та push | Швидке розгортання | Користувач | `cp 01-slash-commands/push-all.md .claude/commands/` | +| `/doc-refactor` | Реструктуризація документації | Покращення документації | Проект | `cp 01-slash-commands/doc-refactor.md .claude/commands/` | +| `/setup-ci-cd` | Налаштування CI/CD-пайплайну | Нові проекти | Проект | `cp 01-slash-commands/setup-ci-cd.md .claude/commands/` | +| `/unit-test-expand` | Розширення покриття тестами | Покращення тестування | Проект | `cp 01-slash-commands/unit-test-expand.md .claude/commands/` | + +> **Область**: `Користувач` = персональні процеси (`~/.claude/commands/`), `Проект` = спільні для команди (`.claude/commands/`) + +**Довідник**: [01-slash-commands/](../01-slash-commands/) | [Офіційна документація](https://code.claude.com/docs/en/interactive-mode) + +**Швидке встановлення (усі кастомні команди)**: + +```bash +cp 01-slash-commands/*.md .claude/commands/ +``` + +--- + +## Режими дозволів + +Claude Code підтримує 6 режимів дозволів, що контролюють авторизацію використання інструментів. + +| Режим | Опис | Коли використовувати | +|-------|------|---------------------| +| `default` | Запитувати дозвіл на кожен виклик | Стандартна інтерактивна робота | +| `acceptEdits` | Автоприйняття редагувань, запит на інше | Довірені процеси редагування | +| `plan` | Лише інструменти читання, без запису | Планування та дослідження | +| `auto` | Приймати всі інструменти без запиту | Повністю автономна робота (Research Preview) | +| `bypassPermissions` | Пропустити всі перевірки дозволів | CI/CD, headless-середовища | +| `dontAsk` | Пропустити інструменти, що потребують дозволу | Неінтерактивне скриптування | + +> **Примітка**: Режим `auto` — це Research Preview (березень 2026). Використовуйте `bypassPermissions` лише в довірених ізольованих середовищах. + +**Довідник**: [Офіційна документація](https://code.claude.com/docs/en/permissions) + +--- + +## Субагенти + +Спеціалізовані AI-помічники з ізольованими контекстами для конкретних завдань. + +### Вбудовані субагенти + +| Агент | Опис | Інструменти | Модель | Коли використовувати | +|-------|------|-------------|--------|---------------------| +| **general-purpose** | Багатокрокові завдання, дослідження | Усі інструменти | Успадкована | Складні дослідження, багатофайлові завдання | +| **Plan** | Планування реалізації | Read, Glob, Grep, Bash | Успадкована | Проєктування архітектури, планування | +| **Explore** | Дослідження кодової бази | Read, Glob, Grep | Haiku 4.5 | Швидкий пошук, розуміння коду | +| **Bash** | Виконання команд | Bash | Успадкована | Git-операції, термінальні завдання | +| **statusline-setup** | Налаштування рядка стану | Bash, Read, Write | Sonnet 4.6 | Конфігурація рядка стану | +| **Claude Code Guide** | Довідка та документація | Read, Glob, Grep | Haiku 4.5 | Отримання допомоги, вивчення функцій | + +### Поля конфігурації субагентів + +| Поле | Тип | Опис | +|------|-----|------| +| `name` | string | Ідентифікатор агента | +| `description` | string | Що робить агент | +| `model` | string | Перевизначення моделі (наприклад, `haiku-4.5`) | +| `tools` | array | Список дозволених інструментів | +| `effort` | string | Рівень зусиль міркування (`low`, `medium`, `high`) | +| `initialPrompt` | string | Системний промпт при старті агента | +| `disallowedTools` | array | Інструменти, явно заборонені для цього агента | + +### Кастомні субагенти (приклади) + +| Агент | Опис | Коли використовувати | Область | Встановлення | +|-------|------|---------------------|---------|-------------| +| `code-reviewer` | Комплексний аналіз якості коду | Сесії ревʼю коду | Проект | `cp 04-subagents/code-reviewer.md .claude/agents/` | +| `code-architect` | Проєктування архітектури функцій | Планування нових функцій | Проект | `cp 04-subagents/code-architect.md .claude/agents/` | +| `code-explorer` | Глибокий аналіз кодової бази | Розуміння існуючих функцій | Проект | `cp 04-subagents/code-explorer.md .claude/agents/` | +| `clean-code-reviewer` | Ревʼю за принципами Clean Code | Ревʼю підтримуваності | Проект | `cp 04-subagents/clean-code-reviewer.md .claude/agents/` | +| `test-engineer` | Стратегія тестування та покриття | Планування тестів | Проект | `cp 04-subagents/test-engineer.md .claude/agents/` | +| `documentation-writer` | Технічна документація | API-документація, посібники | Проект | `cp 04-subagents/documentation-writer.md .claude/agents/` | +| `secure-reviewer` | Ревʼю з фокусом на безпеку | Аудит безпеки | Проект | `cp 04-subagents/secure-reviewer.md .claude/agents/` | +| `implementation-agent` | Повна реалізація функцій | Розробка функцій | Проект | `cp 04-subagents/implementation-agent.md .claude/agents/` | +| `debugger` | Аналіз першопричин | Дослідження помилок | Користувач | `cp 04-subagents/debugger.md .claude/agents/` | +| `data-scientist` | SQL-запити, аналіз даних | Робота з даними | Користувач | `cp 04-subagents/data-scientist.md .claude/agents/` | +| `performance-optimizer` | Профілювання та оптимізація | Дослідження вузьких місць | Проект | `cp 04-subagents/performance-optimizer.md .claude/agents/` | + +> **Область**: `Користувач` = персональні (`~/.claude/agents/`), `Проект` = спільні для команди (`.claude/agents/`) + +**Довідник**: [04-subagents/](../04-subagents/) | [Офіційна документація](https://code.claude.com/docs/en/sub-agents) + +**Швидке встановлення (усі кастомні агенти)**: + +```bash +cp 04-subagents/*.md .claude/agents/ +``` + +--- + +## Навички (Skills) + +Автоматично викликані можливості з інструкціями, скриптами та шаблонами. + +### Приклади навичок + +| Навичка | Опис | Коли автоматично викликається | Область | Встановлення | +|---------|------|------------------------------|---------|-------------| +| `code-review` | Комплексне ревʼю коду | "Review this code", "Check quality" | Проект | `cp -r 03-skills/code-review .claude/skills/` | +| `brand-voice` | Перевірка стилю бренду | Написання маркетингових текстів | Проект | `cp -r 03-skills/brand-voice .claude/skills/` | +| `doc-generator` | Генератор API-документації | "Generate docs", "Document API" | Проект | `cp -r 03-skills/doc-generator .claude/skills/` | +| `refactor` | Систематичний рефакторинг (за Мартіном Фаулером) | "Refactor this", "Clean up code" | Користувач | `cp -r 03-skills/refactor ~/.claude/skills/` | + +> **Область**: `Користувач` = персональні (`~/.claude/skills/`), `Проект` = спільні (`.claude/skills/`) + +### Структура навички + +``` +~/.claude/skills/skill-name/ +├── SKILL.md # Визначення та інструкції +├── scripts/ # Допоміжні скрипти +└── templates/ # Шаблони виводу +``` + +### Поля фронтматеру навичок + +Навички підтримують YAML-фронтматер у `SKILL.md` для конфігурації: + +| Поле | Тип | Опис | +|------|-----|------| +| `name` | string | Відображуване ім'я навички | +| `description` | string | Що робить навичка | +| `autoInvoke` | array | Фрази-тригери для автовиклику | +| `effort` | string | Рівень зусиль міркування (`low`, `medium`, `high`) | +| `shell` | string | Оболонка для скриптів (`bash`, `zsh`, `sh`) | + +**Довідник**: [03-skills/](../03-skills/) | [Офіційна документація](https://code.claude.com/docs/en/skills) + +**Швидке встановлення (усі навички)**: + +```bash +cp -r 03-skills/* ~/.claude/skills/ +``` + +### Вбудовані навички + +| Навичка | Опис | Коли автоматично викликається | +|---------|------|------------------------------| +| `/simplify` | Ревʼю коду на якість | Після написання коду | +| `/batch` | Запуск промптів для кількох файлів | Пакетні операції | +| `/debug` | Налагодження помилок/тестів | Сесії налагодження | +| `/loop` | Запуск промптів за інтервалом | Повторювані завдання | +| `/claude-api` | Створення застосунків з Claude API | Розробка з API | + +--- + +## Плагіни + +Пакетні набори команд, агентів, MCP-серверів та хуків. + +### Приклади плагінів + +| Плагін | Опис | Компоненти | Коли використовувати | Область | Встановлення | +|--------|------|------------|---------------------|---------|-------------| +| `pr-review` | Процес ревʼю PR | 3 команди, 3 агенти, GitHub MCP | Ревʼю коду | Проект | `/plugin install pr-review` | +| `devops-automation` | Розгортання та моніторинг | 4 команди, 3 агенти, K8s MCP | DevOps-завдання | Проект | `/plugin install devops-automation` | +| `documentation` | Набір генерації документації | 4 команди, 3 агенти, шаблони | Документація | Проект | `/plugin install documentation` | + +> **Область**: `Проект` = спільні для команди, `Користувач` = персональні процеси + +### Структура плагіна + +``` +.claude-plugin/ +├── plugin.json # Файл маніфесту +├── commands/ # Слеш-команди +├── agents/ # Субагенти +├── skills/ # Навички +├── mcp/ # Конфігурації MCP +├── hooks/ # Скрипти хуків +└── scripts/ # Допоміжні скрипти +``` + +**Довідник**: [07-plugins/](../07-plugins/) | [Офіційна документація](https://code.claude.com/docs/en/plugins) + +**Команди управління плагінами**: + +```bash +/plugin list # Список встановлених плагінів +/plugin install # Встановити плагін +/plugin remove # Видалити плагін +/plugin update # Оновити плагін +``` + +--- + +## MCP-сервери + +Сервери Model Context Protocol для доступу до зовнішніх інструментів та API. + +### Поширені MCP-сервери + +| Сервер | Опис | Коли використовувати | Область | Встановлення | +|--------|------|---------------------|---------|-------------| +| **GitHub** | Управління PR, issues, код | Процеси з GitHub | Проект | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` | +| **Database** | SQL-запити, доступ до даних | Операції з БД | Проект | `claude mcp add db -- npx -y @modelcontextprotocol/server-postgres` | +| **Filesystem** | Розширені файлові операції | Складна робота з файлами | Користувач | `claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem` | +| **Slack** | Комунікація команди | Сповіщення, оновлення | Проект | Налаштування в settings | +| **Google Docs** | Доступ до документів | Редагування, ревʼю документів | Проект | Налаштування в settings | +| **Asana** | Управління проектами | Відстеження завдань | Проект | Налаштування в settings | +| **Stripe** | Платіжні дані | Фінансовий аналіз | Проект | Налаштування в settings | +| **Memory** | Постійна пам'ять | Згадування між сесіями | Користувач | Налаштування в settings | +| **Context7** | Документація бібліотек | Пошук актуальної документації | Вбудований | Вбудований | + +> **Область**: `Проект` = командний (`.mcp.json`), `Користувач` = персональний (`~/.claude.json`), `Вбудований` = попередньо встановлений + +### Приклад конфігурації MCP + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["-y", "@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**Довідник**: [05-mcp/](../05-mcp/) | [Документація MCP](https://modelcontextprotocol.io) + +**Швидке встановлення (GitHub MCP)**: + +```bash +export GITHUB_TOKEN="your_token" && claude mcp add github -- npx -y @modelcontextprotocol/server-github +``` + +--- + +## Хуки + +Автоматизація на основі подій, що виконує shell-команди при подіях Claude Code. + +### Події хуків + +| Подія | Опис | Коли спрацьовує | Сценарії | +|-------|------|----------------|----------| +| `SessionStart` | Початок/відновлення сесії | Ініціалізація сесії | Завдання налаштування | +| `InstructionsLoaded` | Інструкції завантажені | Завантажено CLAUDE.md або rules | Обробка кастомних інструкцій | +| `UserPromptSubmit` | Перед обробкою промпту | Користувач надсилає повідомлення | Валідація вводу | +| `PreToolUse` | Перед виконанням інструменту | Перед запуском будь-якого інструменту | Валідація, логування | +| `PermissionRequest` | Діалог дозволу | Перед чутливими діями | Кастомні потоки схвалення | +| `PostToolUse` | Після успішного виконання | Після завершення інструменту | Форматування, сповіщення | +| `PostToolUseFailure` | Помилка виконання | Після помилки інструменту | Обробка помилок, логування | +| `Notification` | Надіслано сповіщення | Claude надсилає сповіщення | Зовнішні оповіщення | +| `SubagentStart` | Субагент запущений | Початок завдання субагента | Ініціалізація контексту | +| `SubagentStop` | Субагент завершив | Завдання субагента виконано | Ланцюгові дії | +| `Stop` | Claude завершив відповідь | Відповідь готова | Очищення, звітність | +| `StopFailure` | API-помилка завершила черга | API-помилка | Відновлення, логування | +| `TeammateIdle` | Агент-партнер бездіє | Координація агентів | Розподіл роботи | +| `TaskCompleted` | Завдання позначено як виконане | Завдання завершено | Пост-обробка | +| `TaskCreated` | Завдання створено через TaskCreate | Нове завдання створено | Відстеження, логування | +| `ConfigChange` | Конфігурацію оновлено | Налаштування змінені | Реакція на зміни конфігурації | +| `CwdChanged` | Робочий каталог змінився | Зміна каталогу | Налаштування для каталогу | +| `FileChanged` | Відстежуваний файл змінився | Файл модифіковано | Моніторинг, перебудова | +| `PreCompact` | Перед компактизацією | Стиснення контексту | Збереження стану | +| `PostCompact` | Після компактизації | Компактизація завершена | Дії після стиснення | +| `WorktreeCreate` | Створення worktree | Git worktree створено | Налаштування середовища | +| `WorktreeRemove` | Видалення worktree | Git worktree видалено | Очищення ресурсів | +| `Elicitation` | MCP-сервер запитує ввід | MCP-елісітація | Валідація вводу | +| `ElicitationResult` | Користувач відповідає | Відповідь на елісітацію | Обробка відповіді | +| `SessionEnd` | Завершення сесії | Завершення сесії | Очищення, збереження стану | + +### Приклади хуків + +| Хук | Опис | Подія | Область | Встановлення | +|-----|------|-------|---------|-------------| +| `validate-bash.py` | Валідація команд | PreToolUse:Bash | Проект | `cp 06-hooks/validate-bash.py .claude/hooks/` | +| `security-scan.py` | Сканування безпеки | PostToolUse:Write | Проект | `cp 06-hooks/security-scan.py .claude/hooks/` | +| `format-code.sh` | Автоформатування | PostToolUse:Write | Користувач | `cp 06-hooks/format-code.sh ~/.claude/hooks/` | +| `validate-prompt.py` | Валідація промптів | UserPromptSubmit | Проект | `cp 06-hooks/validate-prompt.py .claude/hooks/` | +| `context-tracker.py` | Відстеження токенів | Stop | Користувач | `cp 06-hooks/context-tracker.py ~/.claude/hooks/` | +| `pre-commit.sh` | Pre-commit валідація | PreToolUse:Bash | Проект | `cp 06-hooks/pre-commit.sh .claude/hooks/` | +| `log-bash.sh` | Логування команд | PostToolUse:Bash | Користувач | `cp 06-hooks/log-bash.sh ~/.claude/hooks/` | +| `dependency-check.sh` | Сканування вразливостей при зміні маніфесту | PostToolUse:Write | Проект | `cp 06-hooks/dependency-check.sh .claude/hooks/` | + +> **Область**: `Проект` = командний (`.claude/settings.json`), `Користувач` = персональний (`~/.claude/settings.json`) + +### Конфігурація хуків + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "command": "~/.claude/hooks/validate-bash.py" + } + ], + "PostToolUse": [ + { + "matcher": "Write", + "command": "~/.claude/hooks/format-code.sh" + } + ] + } +} +``` + +**Довідник**: [06-hooks/](../06-hooks/) | [Офіційна документація](https://code.claude.com/docs/en/hooks) + +**Швидке встановлення (усі хуки)**: + +```bash +mkdir -p ~/.claude/hooks && cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh +``` + +--- + +## Файли пам'яті + +Постійний контекст, що автоматично завантажується між сесіями. + +### Типи пам'яті + +| Тип | Розташування | Область | Коли використовувати | +|-----|-------------|---------|---------------------| +| **Керована політика** | Політики організації | Організація | Застосування стандартів організації | +| **Проект** | `./CLAUDE.md` | Проект (команда) | Командні стандарти, контекст проекту | +| **Правила проекту** | `.claude/rules/` | Проект (команда) | Модульні правила проекту | +| **Користувач** | `~/.claude/CLAUDE.md` | Користувач (персональні) | Персональні налаштування | +| **Правила користувача** | `~/.claude/rules/` | Користувач (персональні) | Модульні персональні правила | +| **Локальний** | `./CLAUDE.local.md` | Локальний (git-ignored) | Перевизначення для конкретної машини (не в офіційних docs станом на березень 2026; може бути legacy) | +| **Автопам'ять** | Автоматично | Сесія | Автозбережені інсайти та виправлення | + +> **Область**: `Організація` = керується адмінами, `Проект` = спільний через git, `Користувач` = персональні, `Локальний` = не комітиться, `Сесія` = автокерований + +**Довідник**: [02-memory/](../02-memory/) | [Офіційна документація](https://code.claude.com/docs/en/memory) + +**Швидке встановлення**: + +```bash +cp 02-memory/project-CLAUDE.md ./CLAUDE.md +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +--- + +## Нові функції (березень 2026) + +| Функція | Опис | Як використовувати | +|---------|------|--------------------| +| **Віддалене керування** | Керування сесіями Claude Code віддалено через API | API віддаленого керування для програмної відправки промптів | +| **Веб-сесії** | Запуск Claude Code у браузерному середовищі | Доступ через `claude web` або Anthropic Console | +| **Десктопний застосунок** | Нативний десктопний застосунок Claude Code | `/desktop` або завантаження з сайту Anthropic | +| **Команди агентів** | Координація кількох агентів для пов'язаних завдань | Налаштування агентів-партнерів для співпраці | +| **Список завдань** | Управління та моніторинг фонових завдань | `/tasks` для перегляду та управління | +| **Підказки промптів** | Контекстно-залежні підказки команд | Підказки з'являються автоматично | +| **Git Worktrees** | Ізольовані worktrees для паралельної розробки | Команди worktree для безпечної паралельної роботи | +| **Пісочниця** | Ізольовані середовища виконання для безпеки | `/sandbox` для перемикання | +| **MCP OAuth** | OAuth-автентифікація для MCP-серверів | OAuth-облікові дані в налаштуваннях MCP | +| **MCP Tool Search** | Динамічний пошук MCP-інструментів | Пошук доступних MCP-інструментів | +| **Заплановані завдання** | Повторювані завдання з `/loop` та cron | `/loop 5m /command` або CronCreate | +| **Інтеграція з Chrome** | Автоматизація браузера через headless Chromium | Прапорець `--chrome` або `/chrome` | +| **Кастомізація клавіатури** | Налаштування клавіш з підтримкою акордів | `/keybindings` або `~/.claude/keybindings.json` | +| **Auto Mode** | Повністю автономна робота (Research Preview) | `--mode auto` або `/permissions auto` | +| **Канали** | Багатоканальна комунікація (Telegram, Slack тощо) (Research Preview) | Налаштування канальних плагінів | +| **Голосовий ввід** | Голосове введення промптів | Іконка мікрофона або клавіша | +| **Тип хука Agent** | Хуки, що запускають субагента замість shell-команди | `"type": "agent"` у конфігурації хука | +| **Тип хука Prompt** | Хуки, що вставляють текст промпту в розмову | `"type": "prompt"` у конфігурації хука | +| **MCP Elicitation** | MCP-сервери можуть запитувати ввід користувача | Обробка через події `Elicitation` та `ElicitationResult` | +| **Plugin LSP** | Інтеграція Language Server Protocol через плагіни | LSP-сервери в `plugin.json` | +| **Керовані drop-ins** | Конфігурації, керовані організацією (v2.1.83) | Налаштовуються адмінами через керовані політики | + +--- + +## Матриця швидкого довідника + +### Посібник з вибору функцій + +| Потреба | Рекомендована функція | Чому | +|---------|----------------------|------| +| Швидкий ярлик | Слеш-команда | Ручний, миттєвий | +| Постійний контекст | Пам'ять | Автозавантаження | +| Складна автоматизація | Навичка | Автовиклик | +| Спеціалізоване завдання | Субагент | Ізольований контекст | +| Зовнішні дані | MCP-сервер | Доступ у реальному часі | +| Автоматизація подій | Хук | Тригер на подію | +| Комплексне рішення | Плагін | Все в одному | + +### Пріоритет встановлення + +| Пріоритет | Функція | Команда | +|-----------|---------|---------| +| 1. Необхідне | Пам'ять | `cp 02-memory/project-CLAUDE.md ./CLAUDE.md` | +| 2. Щоденне | Слеш-команди | `cp 01-slash-commands/*.md .claude/commands/` | +| 3. Якість | Субагенти | `cp 04-subagents/*.md .claude/agents/` | +| 4. Автоматизація | Хуки | `cp 06-hooks/*.sh ~/.claude/hooks/ && chmod +x ~/.claude/hooks/*.sh` | +| 5. Зовнішнє | MCP | `claude mcp add github -- npx -y @modelcontextprotocol/server-github` | +| 6. Просунуте | Навички | `cp -r 03-skills/* ~/.claude/skills/` | +| 7. Комплексне | Плагіни | `/plugin install pr-review` | + +--- + +## Встановлення всього однією командою + +Встановлення всіх прикладів з цього репозиторію: + +```bash +# Створити каталоги +mkdir -p .claude/{commands,agents,skills} ~/.claude/{hooks,skills} + +# Встановити всі функції +cp 01-slash-commands/*.md .claude/commands/ && \ +cp 02-memory/project-CLAUDE.md ./CLAUDE.md && \ +cp -r 03-skills/* ~/.claude/skills/ && \ +cp 04-subagents/*.md .claude/agents/ && \ +cp 06-hooks/*.sh ~/.claude/hooks/ && \ +chmod +x ~/.claude/hooks/*.sh +``` + +--- + +## Додаткові ресурси + +- [Офіційна документація Claude Code](https://code.claude.com/docs/en/overview) +- [Специфікація MCP](https://modelcontextprotocol.io) +- [Навчальний план](LEARNING-ROADMAP.md) +- [Головний README](README.md) + +--- + +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 diff --git a/uk/CHANGELOG.md b/uk/CHANGELOG.md new file mode 100644 index 0000000..7a87b86 --- /dev/null +++ b/uk/CHANGELOG.md @@ -0,0 +1,154 @@ +# Changelog + +## v2.3.0 — 2026-04-07 + +### Features + +- build and publish EPUB artifacts per language (90e9c30) @Thiên Toán +- add missing pre-tool-check.sh hook to 06-hooks (b511ed1) @JiayuWang +- add Chinese translations in zh/ directory (89e89d4) @Luong NGUYEN +- Add performance-optimizer subagent and dependency-check hook (f53d080) @qk + +### Bug Fixes + +- Windows Git Bash compatibility + stdin JSON protocol (2cbb10c) @Luong NGUYEN +- correct autoCheckpoint config documentation in 08-checkpoints (749c79f) @JiayuWang +- embed SVG images instead of replacing with placeholders (1b16709) @Thiên Toán +- nested code fence rendering in memory README (ce24423) @Zhaoshan Duan +- apply review fixes dropped by squash merge (34259ca) @Luong NGUYEN +- make hook scripts compatible with Windows Git Bash and use stdin JSON protocol (107153d) @binyu li + +### Documentation + +- sync all tutorials with latest Claude Code docs (April 2026) (72d3b01) @Luong NGUYEN +- add Chinese language link to language switcher (6cbaa4d) @Luong NGUYEN +- add language switcher between English and Vietnamese (100c45e) @Luong NGUYEN +- add GitHub #1 Trending badge (0ca8c37) @Luong NGUYEN +- Introduce cc-context-stats for context zone monitoring (d41b335) @Luong NGUYEN +- Introduce luongnv89/skills collection and luongnv89/asm skill manager (7e3c0b6) @Luong NGUYEN +- Update README stats to reflect current GitHub metrics (5,900+ stars, 690+ forks) (5001525) @Luong NGUYEN +- Update README stats to reflect current GitHub metrics (3,900+ stars, 460+ forks) (9cb92d6) @Luong NGUYEN + +### Refactoring + +- replace Kroki HTTP dependency with local mmdc rendering (e76bbe4) @Luong NGUYEN +- shift quality checks to pre-commit, CI as 2nd pass (6d1e0ae) @Luong NGUYEN +- narrow auto-mode permissions baseline (2790fb2) @Luong NGUYEN +- Replace auto-adapt hook with one-time permissions setup script (995a5d6) @Luong NGUYEN + +### Other + +- shift-left quality gates — add mypy to pre-commit, fix CI failures (699fb39) @Luong NGUYEN +- Add Vietnamese (Tiếng Việt) Localization (a70777e) @Thiên Toán + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.2.0...v2.3.0 + +--- + +## v2.2.0 — 2026-03-26 + +### Documentation + +- Sync all tutorials and references with Claude Code v2.1.84 (f78c094) @luongnv89 + - Update slash commands to 55+ built-in + 5 bundled skills, mark 3 deprecated + - Expand hook events from 18 to 25, add `agent` hook type (now 4 types) + - Add Auto Mode, Channels, Voice Dictation to advanced features + - Add `effort`, `shell` skill frontmatter fields; `initialPrompt`, `disallowedTools` agent fields + - Add WebSocket MCP transport, elicitation, 2KB tool cap + - Add plugin LSP support, `userConfig`, `${CLAUDE_PLUGIN_DATA}` + - Update all reference docs (CATALOG, QUICK_REFERENCE, LEARNING-ROADMAP, INDEX) +- Rewrite README as landing-page-structured guide (32a0776) @luongnv89 + +### Bug Fixes + +- Add missing cSpell words and README sections for CI compliance (93f9d51) @luongnv89 +- Add `Sandboxing` to cSpell dictionary (b80ce6f) @luongnv89 + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.1.1...v2.2.0 + +--- + +## v2.1.1 — 2026-03-13 + +### Bug Fixes + +- Remove dead marketplace link failing CI link checks (3fdf0d6) @luongnv89 +- Add `sandboxed` and `pycache` to cSpell dictionary (dc64618) @luongnv89 + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1 + +--- + +## v2.1.0 — 2026-03-13 + +### Features + +- Add adaptive learning path with self-assessment and lesson quiz skills (1ef46cd) @luongnv89 + - `/self-assessment` — interactive proficiency quiz across 10 feature areas with personalized learning path + - `/lesson-quiz [lesson]` — per-lesson knowledge check with 8-10 targeted questions + +### Bug Fixes + +- Update broken URLs, deprecations, and outdated references (8fe4520) @luongnv89 +- Fix broken links in resources and self-assessment skill (7a05863) @luongnv89 +- Use tilde fences for nested code blocks in concepts guide (5f82719) @VikalpP +- Add missing words to cSpell dictionary (8df7572) @luongnv89 + +### Documentation + +- Phase 5 QA — fix consistency, URLs, and terminology across docs (00bbe4c) @luongnv89 +- Complete Phases 3-4 — new feature coverage and reference doc updates (132de29) @luongnv89 +- Add MCPorter runtime to MCP context bloat section (ef52705) @luongnv89 +- Add missing commands, features, and settings across 6 guides (4bc8f15) @luongnv89 +- Add style guide based on existing repo conventions (84141d0) @luongnv89 +- Add self-assessment row to guide comparison table (8fe0c96) @luongnv89 +- Add VikalpP to contributors list for PR #7 (d5b4350) @luongnv89 +- Add self-assessment and lesson-quiz skill references to README and roadmap (d5a6106) @luongnv89 + +### New Contributors + +- @VikalpP made their first contribution in #7 + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.0.0...v2.1.0 + +--- + +## v2.0.0 — 2026-02-01 + +### Features + +- Sync all documentation with Claude Code February 2026 features (487c96d) + - Update 26 files across all 10 tutorial directories and 7 reference documents + - Add documentation for **Auto Memory** — persistent learnings per project + - Add documentation for **Remote Control**, **Web Sessions**, and **Desktop App** + - Add documentation for **Agent Teams** (experimental multi-agent collaboration) + - Add documentation for **MCP OAuth 2.0**, **Tool Search**, and **Claude.ai Connectors** + - Add documentation for **Persistent Memory** and **Worktree Isolation** for subagents + - Add documentation for **Background Subagents**, **Task List**, **Prompt Suggestions** + - Add documentation for **Sandboxing** and **Managed Settings** (Enterprise) + - Add documentation for **HTTP Hooks** and 7 new hook events + - Add documentation for **Plugin Settings**, **LSP Servers**, and Marketplace updates + - Add documentation for **Summarize from Checkpoint** rewind option + - Document 17 new slash commands (`/fork`, `/desktop`, `/teleport`, `/tasks`, `/fast`, etc.) + - Document new CLI flags (`--worktree`, `--from-pr`, `--remote`, `--teleport`, `--teammate-mode`, etc.) + - Document new environment variables for auto memory, effort levels, agent teams, and more + +### Design + +- Redesign logo to compass-bracket mark with minimal palette (20779db) + +### Bug Fixes / Corrections + +- Update model names: Sonnet 4.5 → **Sonnet 4.6**, Opus 4.5 → **Opus 4.6** +- Fix permission mode names: replace fictional "Unrestricted/Confirm/Read-only" with actual `default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions` +- Fix hook events: remove fictional `PreCommit`/`PostCommit`/`PrePush`, add real events (`SubagentStart`, `WorktreeCreate`, `ConfigChange`, etc.) +- Fix CLI syntax: replace `claude-code --headless` with `claude -p` (print mode) +- Fix checkpoint commands: replace fictional `/checkpoint save/list/rewind/diff` with actual `Esc+Esc` / `/rewind` interface +- Fix session management: replace fictional `/session list/new/switch/save` with real `/resume`/`/rename`/`/fork` +- Fix plugin manifest format: migrate `plugin.yaml` → `.claude-plugin/plugin.json` +- Fix MCP config paths: `~/.claude/mcp.json` → `.mcp.json` (project) / `~/.claude.json` (user) +- Fix documentation URLs: `docs.claude.com` → `docs.anthropic.com`; remove fictional `plugins.claude.com` +- Remove fictional configuration fields across multiple files +- Update all "Last Updated" dates to February 2026 + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/20779db...v2.0.0 diff --git a/uk/CLAUDE.md b/uk/CLAUDE.md new file mode 100644 index 0000000..fbdd141 --- /dev/null +++ b/uk/CLAUDE.md @@ -0,0 +1,161 @@ + + + + +# CLAUDE.md + +Цей файл надає настанови для Claude Code (claude.ai/code) при роботі з кодом у цьому репозиторії. + +## Огляд проєкту + +Claude How To — це навчальний репозиторій з функцій Claude Code. Це **документація-як-код** — основний продукт — markdown-файли, організовані в пронумеровані навчальні модулі, а не виконуваний додаток. + +**Архітектура**: Кожен модуль (01-10) охоплює конкретну функцію Claude Code з готовими шаблонами для копіювання, Mermaid-діаграмами та прикладами. Система збірки валідує якість документації та генерує EPUB-книгу. + +## Типові команди + +### Перевірки якості pre-commit + +Уся документація повинна пройти чотири перевірки якості перед комітами (запускаються автоматично через pre-commit хуки): + +```bash +# Install pre-commit hooks (runs on every commit) +pre-commit install + +# Run all checks manually +pre-commit run --all-files +``` + +П'ять перевірок: +1. **markdown-lint** — Структура та форматування Markdown через `markdownlint` +2. **cross-references** — Внутрішні посилання, якорі, синтаксис блоків коду (Python-скрипт) +3. **mermaid-syntax** — Валідація коректного парсингу всіх Mermaid-діаграм (Python-скрипт) +4. **link-check** — Доступність зовнішніх URL (Python-скрипт) +5. **build-epub** — EPUB генерується без помилок (при змінах `.md`) + +### Налаштування середовища розробки + +```bash +# Install uv (Python package manager) +pip install uv + +# Create virtual environment and install Python dependencies +uv venv +source .venv/bin/activate +uv pip install -r scripts/requirements-dev.txt + +# Install Node.js tools (markdown linter and Mermaid validator) +npm install -g markdownlint-cli +npm install -g @mermaid-js/mermaid-cli + +# Install pre-commit hooks +uv pip install pre-commit +pre-commit install +``` + +### Тестування + +Python-скрипти в `scripts/` мають юніт-тести: + +```bash +# Run all tests +pytest scripts/tests/ -v + +# Run with coverage +pytest scripts/tests/ -v --cov=scripts --cov-report=html + +# Run specific test +pytest scripts/tests/test_build_epub.py -v +``` + +### Якість коду + +```bash +# Lint and format Python code +ruff check scripts/ +ruff format scripts/ + +# Security scan +bandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/ + +# Type checking +mypy scripts/ --ignore-missing-imports +``` + +### Збірка EPUB + +```bash +# Generate ebook (renders Mermaid diagrams via Kroki.io API) +uv run scripts/build_epub.py + +# With options +uv run scripts/build_epub.py --verbose --output custom-name.epub --max-concurrent 5 +``` + +## Структура каталогів + +``` +├── 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/ +│ ├── build_epub.py # Генератор EPUB (рендерить Mermaid через Kroki API) +│ ├── check_cross_references.py # Валідація внутрішніх посилань +│ ├── check_links.py # Перевірка зовнішніх URL +│ ├── check_mermaid.py # Валідація синтаксису Mermaid +│ └── tests/ # Юніт-тести для скриптів +├── .pre-commit-config.yaml # Визначення перевірок якості +└── README.md # Основний довідник (також індекс модулів) +``` + +## Настанови щодо контенту + +### Структура модуля +Кожна пронумерована папка дотримується патерну: +- **README.md** — Огляд функції з прикладами +- **Файли прикладів** — Готові шаблони для копіювання (`.md` для команд, `.json` для конфігурацій, `.sh` для хуків) +- Файли організовані за складністю функцій та залежностями + +### Mermaid-діаграми +- Усі діаграми повинні успішно парситися (перевіряється pre-commit хуком) +- Збірка EPUB рендерить діаграми через Kroki.io API (потрібен інтернет) +- Використовуйте Mermaid для блок-схем, діаграм послідовностей та архітектурних візуалізацій + +### Перехресні посилання +- Використовуйте відносні шляхи для внутрішніх посилань (напр., `(01-slash-commands/README.md)`) +- Блоки коду повинні вказувати мову (напр., ` ```bash `, ` ```python `) +- Якірні посилання використовують формат `#heading-name` + +### Валідація посилань +- Зовнішні URL повинні бути доступні (перевіряється pre-commit хуком) +- Уникайте посилань на тимчасовий контент +- Використовуйте пермалінки де можливо + +## Ключові архітектурні рішення + +1. **Пронумеровані папки вказують порядок навчання** — Префікс 01-10 відображає рекомендовану послідовність вивчення функцій Claude Code. Ця нумерація навмисна; не реорганізовуйте за алфавітом. + +2. **Скрипти — утиліти, а не продукт** — Python-скрипти в `scripts/` підтримують якість документації та генерацію EPUB. Фактичний контент — у пронумерованих папках модулів. + +3. **Pre-commit — привратник** — Усі перевірки якості повинні пройти перед прийняттям PR. CI-конвеєр запускає ці ж перевірки як другий прохід. + +4. **Рендеринг Mermaid потребує мережі** — Збірка EPUB викликає Kroki.io API для рендерингу діаграм. Помилки збірки тут зазвичай пов'язані з мережею або невалідним синтаксисом Mermaid. + +5. **Це туторіал, а не бібліотека** — При додаванні контенту зосереджуйтесь на чітких поясненнях, готових прикладах та візуальних діаграмах. Цінність — у навчанні концепцій, а не у наданні повторно використовуваного коду. + +## Конвенції комітів + +Дотримуйтесь формату conventional commits: +- `feat(slash-commands): Add API documentation generator` +- `docs(memory): Improve personal preferences example` +- `fix(README): Correct table of contents link` +- `refactor(hooks): Simplify hook configuration examples` + +Скоуп повинен відповідати назві папки де можливо. diff --git a/uk/CODE_OF_CONDUCT.md b/uk/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..bc44f72 --- /dev/null +++ b/uk/CODE_OF_CONDUCT.md @@ -0,0 +1,224 @@ + + + + +# Кодекс поведінки контриб'юторів + +## Наше зобов'язання + +Ми зобов'язуємося забезпечити привітну та надихаючу спільноту для всіх. Ми запевняємо, що участь у нашій спільноті є вільною від переслідувань для кожного, незалежно від віку, статури, касти, інвалідності, етнічної приналежності, статевих ознак, гендерної ідентичності та вираження, рівня досвіду, освіти, соціально-економічного статусу, національності, зовнішнього вигляду, раси, релігії або сексуальної ідентичності та орієнтації. + +Ми прагнемо забезпечити позитивне, інклюзивне та безпечне середовище, де всі контриб'ютори відчувають повагу, цінність та можливість внести свій найкращий вклад. + +## Наші стандарти + +Приклади поведінки, що сприяє створенню позитивного середовища: + +### Будьте поважними +- Використовуйте привітну та інклюзивну мову +- Поважайте різні думки, погляди та досвід +- Приймайте конструктивну критику з гідністю +- Поважайте культурні та мовні відмінності +- Визнавайте та цінуйте різноманітне походження + +### Будьте колаборативними +- Працюйте разом над вирішенням конфліктів +- Відзначайте та визнавайте внески інших +- Допомагайте іншим вчитися та зростати +- Діліться знаннями та ставте запитання +- Підтримуйте колег по спільноті + +### Будьте професійними +- Тримайте обговорення зосередженими та продуктивними +- Уникайте принизливих або образливих зауважень +- Залишайтесь у темі в issues та обговореннях +- Використовуйте чітку та поважну комунікацію +- Припускайте добрі наміри в повідомленнях інших + +### Будьте інклюзивними +- Вітайте нових контриб'юторів +- Допомагайте адаптуватися людям, новим у проєкті +- Надавайте конструктивний зворотний зв'язок +- Залучайте людей з різними перспективами +- Створюйте простір для тихих голосів + +## Неприйнятна поведінка + +Наступні дії вважаються переслідуванням та є неприйнятними в нашій спільноті: + +### Переслідування та дискримінація +- Образливі коментарі щодо гендеру, гендерної ідентичності та вираження, сексуальної орієнтації, інвалідності, психічного захворювання, нейро(а)типовості, зовнішнього вигляду, статури, віку, раси або релігії +- Небажані коментарі щодо життєвого вибору та практик людини +- Навмисне неправильне вживання займенників або використання «мертвих» або відкинутих імен +- Безпідставні або не по темі сексуальні зображення або поведінка +- Фізичний контакт та імітований фізичний контакт без згоди або після прохання припинити + +### Зловживання +- Погрози насильством або агресивна мова, спрямована проти іншої людини +- Підбурювання до насильства або агресивна мова щодо будь-якої особи +- Навмисне залякування +- Переслідування або стеження +- Переслідування через повторні контакти +- Будь-яка інша поведінка, яку можна обґрунтовано вважати неприйнятною + +### Онлайн-переслідування +- Систематичне порушення онлайн-обговорень +- Публікація приватної інформації інших (доксинг) +- Небажана сексуальна увага або домагання +- Тролінг або навмисне порушення +- Спам або повторна реклама +- Поширення дезінформації + +### Помста +- Вжиття карних заходів проти когось за повідомлення про порушення +- Несправедливе ставлення до когось через повідомлення про неприйнятну поведінку +- Погрози повідомити про когось у відповідь + +## Область застосування + +Цей Кодекс поведінки застосовується до: +- Усіх просторів спільноти (GitHub issues, pull requests, обговорення тощо) +- Репозиторіїв та документації проєкту +- Подій та зібрань, організованих проєктом або від його імені +- Публічних просторів, де особи представляють проєкт або спільноту +- Приватних комунікацій, коли вони стосуються справ проєкту + +Кодекс поведінки застосовується до всіх просторів проєкту, а також коли особа представляє проєкт або спільноту в публічних просторах. Приклади представлення проєкту або спільноти включають використання офіційної електронної адреси проєкту, публікації через офіційний акаунт у соціальних мережах або діяльність як призначений представник на онлайн- або офлайн-заході. + +## Застосування + +Лідери спільноти відповідають за роз'яснення та дотримання наших стандартів прийнятної поведінки та вживатимуть відповідних та справедливих коригувальних дій у відповідь на будь-яку поведінку, яку вони вважають неприйнятною, загрозливою, образливою або шкідливою. + +### Повідомлення про порушення + +Якщо ви стали свідком або жертвою неприйнятної поведінки, або маєте будь-які інші занепокоєння, будь ласка, повідомте: + +1. **Email**: Зв'яжіться з мейнтейнерами проєкту +2. **GitHub Issues**: Функція приватного повідомлення (якщо доступна) +3. **Пряме повідомлення**: Зв'яжіться з мейнтейнером проєкту напряму + +Вкажіть: +- Вашу контактну інформацію +- Імена залучених осіб (якщо вам комфортно ділитися) +- Опис інциденту +- Контекст та відповідні посилання +- Як інцидент вплинув на вас + +**Усі повідомлення зберігатимуться конфіденційно.** + +### Розслідування та реагування + +Лідери спільноти: +- Переглядатимуть та розслідуватимуть усі скарги оперативно та справедливо +- Зберігатимуть конфіденційність щодо репортера +- Повідомлятимуть репортера про статус його повідомлення +- Вживатимуть відповідних дій на основі результатів + +Можливі дії: +- Приватне попередження або консультація +- Публічні вибачення (за згодою порушника) +- Тимчасове або постійне видалення з просторів спільноти +- Втрата привілеїв контриб'ютора +- Ескалація на GitHub або інші платформи за потреби + +### Процес апеляції + +Якщо ви вважаєте, що рішення було прийнято помилково, ви можете оскаржити: +1. Надавши нову інформацію або контекст +2. Запросивши перегляд кількома мейнтейнерами +3. Звернувшись протягом 30 днів після початкового рішення + +## Настанови для шанобливої незгоди + +Розбіжності є природними в технічних спільнотах. Ось як не погоджуватись шанобливо: + +### Робіть +- ✅ Зосереджуйтесь на ідеї, а не на людині +- ✅ Ставте уточнюючі запитання +- ✅ Визнавайте слушні моменти в протилежних поглядах +- ✅ Використовуйте «Я»-висловлювання («Я не погоджуюсь, тому що...») +- ✅ Посилайтесь на джерела та факти +- ✅ Дякуйте іншим за їхню перспективу + +### Не робіть +- ❌ Переходьте на особистості +- ❌ Використовуйте зневажливу мову («Це дурниця») +- ❌ Припускайте погані наміри +- ❌ Піднімайте непов'язані минулі конфлікти +- ❌ Підвищуйте тон або ставайте ворожими +- ❌ Навмисно спотворюйте погляди інших + +### Приклад шанобливої незгоди +``` +❌ Погано: "That's a dumb idea and you clearly don't understand the project." + +✅ Добре: "I see your point, but I'm concerned this approach might +not scale well with larger projects. Have you considered the +performance implications shown in this benchmark? I'd love to +hear your thoughts on this." +``` + +## Будування мостів + +Ми віримо в силу діалогу та примирення: + +- Якщо хтось вказує на вашу поведінку, слухайте та рефлексуйте +- Будьте готові вибачитися, якщо завдали шкоди +- Підтримуйте інших у навчанні та зростанні +- Визнавайте, що люди роблять помилки +- Зосереджуйтесь на рішеннях, а не на звинуваченнях +- Припускайте добрі наміри, зберігаючи відповідальність + +## Переваги дотримання цього кодексу + +Підтримуючи шанобливу та інклюзивну спільноту, ми: +- Залучаємо різноманітних контриб'юторів з різними перспективами +- Створюємо кращі рішення через співпрацю +- Будуємо міцніші стосунки +- Робимо проєкт привітнішим для новачків +- Виробляємо якіснішу документацію та приклади +- Формуємо культуру навчання та зростання + +## Спеціальні міркування + +### Для мейнтейнерів +- Подавайте приклад у дотриманні цього Кодексу +- Оперативно реагуйте на повідомлення +- Будьте прозорими щодо рішень +- Допомагайте справедливо вирішувати конфлікти +- Створюйте безпечне середовище для всіх + +### Для контриб'юторів +- Припускайте добрі наміри мейнтейнерів та інших контриб'юторів +- Надавайте конструктивний зворотний зв'язок +- Підтримуйте новачків +- Допомагайте дотримуватись стандартів спільноти +- Беріть відповідальність за культуру спільноти + +### Для всіх +- Пам'ятайте, що за кожним повідомленням стоїть людина +- Робіть перерви, якщо відчуваєте фрустрацію +- Звертайтесь до лідерів спільноти, якщо потрібна підтримка +- Допомагайте створювати спільноту, частиною якої хочете бути + +## Атрибуція + +Цей Кодекс поведінки адаптовано з: +- [Contributor Covenant](https://www.contributor-covenant.org/) +- [Mozilla Community Participation Guidelines](https://www.mozilla.org/en-US/about/governance/policies/participation/) +- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) + +## Запитання? + +Якщо у вас є запитання щодо цього Кодексу поведінки, зверніться до мейнтейнерів проєкту. + +## Історія версій + +- **Версія 1.0** (Січень 2026) — Початковий Кодекс поведінки + +--- + +**Дякуємо за допомогу в створенні привітної, інклюзивної та шанобливої спільноти!** 🌟 + +--- +**Останнє оновлення**: Квітень 2026 diff --git a/uk/CONTRIBUTING.md b/uk/CONTRIBUTING.md new file mode 100644 index 0000000..68d8b49 --- /dev/null +++ b/uk/CONTRIBUTING.md @@ -0,0 +1,385 @@ + + + + + + + Claude How To + + +# Внесок у 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 diff --git a/uk/INDEX.md b/uk/INDEX.md new file mode 100644 index 0000000..c50b3c7 --- /dev/null +++ b/uk/INDEX.md @@ -0,0 +1,935 @@ + + + + + + + Claude How To + + +# Приклади Claude Code — Повний покажчик + +Цей документ містить повний покажчик усіх файлів-прикладів, упорядкований за типом функціональності. + +## Загальна статистика + +- **Файлів**: 100+ +- **Категорій**: 10 функціональних категорій +- **Плагінів**: 3 повних плагіни +- **Навичок (Skills)**: 6 повних навичок +- **Хуків**: 8 прикладів хуків +- **Готові до використання**: Усі приклади + +--- + +## 01. Слеш-команди (10 файлів) + +Ярлики для типових робочих процесів, які викликає користувач. + +| Файл | Опис | Сценарій використання | +|------|------|----------------------| +| `optimize.md` | Аналізатор оптимізації коду | Пошук проблем продуктивності | +| `pr.md` | Підготовка pull request | Автоматизація PR-процесу | +| `generate-api-docs.md` | Генератор API-документації | Створення документації API | +| `commit.md` | Помічник з коміт-повідомлень | Стандартизовані коміти | +| `setup-ci-cd.md` | Налаштування CI/CD-пайплайну | DevOps-автоматизація | +| `push-all.md` | Відправити всі зміни | Швидкий push | +| `unit-test-expand.md` | Розширення покриття тестами | Автоматизація тестування | +| `doc-refactor.md` | Рефакторинг документації | Покращення документації | +| `pr-slash-command.png` | Скріншот-приклад | Візуальний довідник | +| `README.md` | Документація | Керівництво з налаштування | + +**Шлях встановлення**: `.claude/commands/` + +**Використання**: `/optimize`, `/pr`, `/generate-api-docs`, `/commit`, `/setup-ci-cd`, `/push-all`, `/unit-test-expand`, `/doc-refactor` + +--- + +## 02. Пам'ять (6 файлів) + +Постійний контекст та стандарти проекту. + +| Файл | Опис | Область | Розташування | +|------|------|---------|-------------| +| `project-CLAUDE.md` | Командні стандарти проекту | Проект | `./CLAUDE.md` | +| `directory-api-CLAUDE.md` | Правила для API | Каталог | `./src/api/CLAUDE.md` | +| `personal-CLAUDE.md` | Персональні налаштування | Користувач | `~/.claude/CLAUDE.md` | +| `memory-saved.png` | Скріншот: пам'ять збережено | - | Візуальний довідник | +| `memory-ask-claude.png` | Скріншот: запит до Claude | - | Візуальний довідник | +| `README.md` | Документація | - | Довідник | + +**Встановлення**: Скопіюйте у відповідне розташування + +**Використання**: Автоматично завантажується Claude + +--- + +## 03. Навички (Skills) (28 файлів) + +Автоматично викликані можливості зі скриптами та шаблонами. + +### Навичка Code Review (5 файлів) + +``` +code-review/ +├── SKILL.md # Визначення навички +├── scripts/ +│ ├── analyze-metrics.py # Аналізатор метрик коду +│ └── compare-complexity.py # Порівняння складності +└── templates/ + ├── review-checklist.md # Чекліст ревʼю + └── finding-template.md # Шаблон знахідок +``` + +**Призначення**: Комплексне ревʼю коду з аналізом безпеки, продуктивності та якості + +**Автовиклик**: При перегляді коду + +--- + +### Навичка Brand Voice (4 файли) + +``` +brand-voice/ +├── SKILL.md # Визначення навички +├── templates/ +│ ├── email-template.txt # Формат електронного листа +│ └── social-post-template.txt # Формат соцмедіа +└── tone-examples.md # Приклади повідомлень +``` + +**Призначення**: Забезпечення єдиного стилю бренду в комунікаціях + +**Автовиклик**: При створенні маркетингових текстів + +--- + +### Навичка Documentation Generator (2 файли) + +``` +doc-generator/ +├── SKILL.md # Визначення навички +└── generate-docs.py # Python-генератор документації +``` + +**Призначення**: Генерація комплексної API-документації з вихідного коду + +**Автовиклик**: При створенні/оновленні API-документації + +--- + +### Навичка Refactor (5 файлів) + +``` +refactor/ +├── SKILL.md # Визначення навички +├── scripts/ +│ ├── analyze-complexity.py # Аналізатор складності +│ └── detect-smells.py # Детектор code smells +├── references/ +│ ├── code-smells.md # Каталог code smells +│ └── refactoring-catalog.md # Патерни рефакторингу +└── templates/ + └── refactoring-plan.md # Шаблон плану рефакторингу +``` + +**Призначення**: Систематичний рефакторинг коду з аналізом складності + +**Автовиклик**: При рефакторингу коду + +--- + +### Навичка Claude MD (1 файл) + +``` +claude-md/ +└── SKILL.md # Визначення навички +``` + +**Призначення**: Управління та оптимізація файлів CLAUDE.md + +--- + +### Навичка Blog Draft (3 файли) + +``` +blog-draft/ +├── SKILL.md # Визначення навички +└── templates/ + ├── draft-template.md # Шаблон чернетки блогу + └── outline-template.md # Шаблон плану блогу +``` + +**Призначення**: Створення чернеток блог-постів зі стандартною структурою + +**Додатково**: `README.md` — огляд навичок та керівництво з використання + +**Шлях встановлення**: `~/.claude/skills/` або `.claude/skills/` + +--- + +## 04. Субагенти (9 файлів) + +Спеціалізовані AI-помічники з налаштованими можливостями. + +| Файл | Опис | Інструменти | Сценарій | +|------|------|-------------|----------| +| `code-reviewer.md` | Аналіз якості коду | read, grep, diff, lint_runner | Комплексне ревʼю | +| `test-engineer.md` | Аналіз покриття тестами | read, write, bash, grep | Автоматизація тестування | +| `documentation-writer.md` | Створення документації | read, write, grep | Генерація документації | +| `secure-reviewer.md` | Ревʼю безпеки (лише читання) | read, grep | Аудит безпеки | +| `implementation-agent.md` | Повна реалізація | read, write, bash, grep, edit, glob | Розробка функцій | +| `debugger.md` | Спеціаліст з налагодження | read, bash, grep | Дослідження помилок | +| `data-scientist.md` | Спеціаліст з аналізу даних | read, write, bash | Робота з даними | +| `clean-code-reviewer.md` | Стандарти чистого коду | read, grep | Якість коду | +| `README.md` | Документація | - | Керівництво | + +**Шлях встановлення**: `.claude/agents/` + +**Використання**: Автоматичне делегування головним агентом + +--- + +## 05. Протокол MCP (5 файлів) + +Інтеграції із зовнішніми інструментами та API. + +| Файл | Опис | Інтеграція з | Сценарій | +|------|------|-------------|----------| +| `github-mcp.json` | Інтеграція з GitHub | GitHub API | Управління PR/issue | +| `database-mcp.json` | Запити до бази даних | PostgreSQL/MySQL | Запити до даних | +| `filesystem-mcp.json` | Файлові операції | Локальна файлова система | Управління файлами | +| `multi-mcp.json` | Кілька серверів | GitHub + DB + Slack | Комплексна інтеграція | +| `README.md` | Документація | - | Керівництво | + +**Шлях встановлення**: `.mcp.json` (рівень проекту) або `~/.claude.json` (рівень користувача) + +**Використання**: `/mcp__github__list_prs` тощо + +--- + +## 06. Хуки (9 файлів) + +Скрипти автоматизації, що виконуються при певних подіях. + +| Файл | Опис | Подія | Сценарій | +|------|------|-------|----------| +| `format-code.sh` | Автоформатування коду | PreToolUse:Write | Форматування коду | +| `pre-commit.sh` | Тести перед комітом | PreToolUse:Bash | Автоматизація тестів | +| `security-scan.sh` | Сканування безпеки | PostToolUse:Write | Перевірка безпеки | +| `log-bash.sh` | Логування bash-команд | PostToolUse:Bash | Журналювання команд | +| `validate-prompt.sh` | Валідація промптів | PreToolUse | Валідація вводу | +| `notify-team.sh` | Надсилання сповіщень | Notification | Сповіщення команди | +| `context-tracker.py` | Відстеження контекстного вікна | PostToolUse | Моніторинг контексту | +| `context-tracker-tiktoken.py` | Підрахунок токенів | PostToolUse | Точний підрахунок токенів | +| `README.md` | Документація | - | Керівництво | + +**Шлях встановлення**: Конфігурація в `~/.claude/settings.json` + +**Використання**: Налаштовуються в settings, виконуються автоматично + +**Типи хуків** (4 типи, 25 подій): + +- Хуки інструментів: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest +- Хуки сесії: SessionStart, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStop +- Хуки завдань: UserPromptSubmit, TaskCompleted, TaskCreated, TeammateIdle +- Хуки життєвого циклу: ConfigChange, CwdChanged, FileChanged, PreCompact, PostCompact, WorktreeCreate, WorktreeRemove, Notification, InstructionsLoaded, Elicitation, ElicitationResult + +--- + +## 07. Плагіни (3 повних плагіни, 40 файлів) + +Пакетні набори функціональності. + +### Плагін PR Review (10 файлів) + +``` +pr-review/ +├── .claude-plugin/ +│ └── plugin.json # Маніфест плагіна +├── commands/ +│ ├── review-pr.md # Комплексне ревʼю +│ ├── check-security.md # Перевірка безпеки +│ └── check-tests.md # Перевірка покриття тестами +├── agents/ +│ ├── security-reviewer.md # Спеціаліст з безпеки +│ ├── test-checker.md # Спеціаліст з тестування +│ └── performance-analyzer.md # Спеціаліст з продуктивності +├── mcp/ +│ └── github-config.json # Інтеграція з GitHub +├── hooks/ +│ └── pre-review.js # Валідація перед ревʼю +└── README.md # Документація плагіна +``` + +**Можливості**: Аналіз безпеки, покриття тестами, вплив на продуктивність + +**Команди**: `/review-pr`, `/check-security`, `/check-tests` + +**Встановлення**: `/plugin install pr-review` + +--- + +### Плагін DevOps Automation (15 файлів) + +``` +devops-automation/ +├── .claude-plugin/ +│ └── plugin.json # Маніфест плагіна +├── commands/ +│ ├── deploy.md # Розгортання +│ ├── rollback.md # Відкат +│ ├── status.md # Статус системи +│ └── incident.md # Реагування на інциденти +├── agents/ +│ ├── deployment-specialist.md # Експерт з розгортання +│ ├── incident-commander.md # Координатор інцидентів +│ └── alert-analyzer.md # Аналізатор сповіщень +├── mcp/ +│ └── kubernetes-config.json # Інтеграція з Kubernetes +├── hooks/ +│ ├── pre-deploy.js # Перевірки перед розгортанням +│ └── post-deploy.js # Дії після розгортання +├── scripts/ +│ ├── deploy.sh # Автоматизація розгортання +│ ├── rollback.sh # Автоматизація відкату +│ └── health-check.sh # Перевірка стану +└── README.md # Документація плагіна +``` + +**Можливості**: Розгортання Kubernetes, відкат, моніторинг, реагування на інциденти + +**Команди**: `/deploy`, `/rollback`, `/status`, `/incident` + +**Встановлення**: `/plugin install devops-automation` + +--- + +### Плагін Documentation (14 файлів) + +``` +documentation/ +├── .claude-plugin/ +│ └── plugin.json # Маніфест плагіна +├── commands/ +│ ├── generate-api-docs.md # Генерація API-документації +│ ├── generate-readme.md # Створення README +│ ├── sync-docs.md # Синхронізація документації +│ └── validate-docs.md # Валідація документації +├── agents/ +│ ├── api-documenter.md # Спеціаліст з API-документації +│ ├── code-commentator.md # Спеціаліст з коментарів +│ └── example-generator.md # Генератор прикладів +├── mcp/ +│ └── github-docs-config.json # Інтеграція з GitHub +├── templates/ +│ ├── api-endpoint.md # Шаблон API-ендпоінту +│ ├── function-docs.md # Шаблон документації функцій +│ └── adr-template.md # Шаблон ADR +└── README.md # Документація плагіна +``` + +**Можливості**: API-документація, генерація README, синхронізація, валідація + +**Команди**: `/generate-api-docs`, `/generate-readme`, `/sync-docs`, `/validate-docs` + +**Встановлення**: `/plugin install documentation` + +**Додатково**: `README.md` — огляд плагінів та керівництво + +--- + +## 08. Контрольні точки та відкат (2 файли) + +Збереження стану розмови та дослідження альтернативних підходів. + +| Файл | Опис | Вміст | +|------|------|-------| +| `README.md` | Документація | Повний посібник з контрольних точок | +| `checkpoint-examples.md` | Практичні приклади | Міграція БД, оптимізація, UI-ітерації, налагодження | + +**Ключові поняття**: + +- **Контрольна точка (Checkpoint)**: Знімок стану розмови +- **Відкат (Rewind)**: Повернення до попередньої контрольної точки +- **Точка розгалуження (Branch Point)**: Дослідження кількох підходів + +**Використання**: + +``` +# Контрольні точки створюються автоматично з кожним промптом +# Для відкату натисніть Esc двічі або скористайтеся: +/rewind +# Потім оберіть: Відновити код і розмову, Відновити розмову, +# Відновити код, Підсумувати звідси, або Скасувати +``` + +**Сценарії**: + +- Спробувати різні реалізації +- Відновитися після помилок +- Безпечне експериментування +- Порівняння рішень +- A/B-тестування + +--- + +## 09. Розширені функції (3 файли) + +Просунуті можливості для складних робочих процесів. + +| Файл | Опис | Функції | +|------|------|---------| +| `README.md` | Повний посібник | Документація всіх розширених функцій | +| `config-examples.json` | Приклади конфігурації | 10+ конфігурацій для різних сценаріїв | +| `planning-mode-examples.md` | Приклади планування | REST API, міграція БД, рефакторинг | +| Заплановані завдання | Повторювані завдання з `/loop` та cron | Автоматичні повторювані процеси | +| Інтеграція з Chrome | Автоматизація браузера через headless Chromium | Веб-тестування та скрейпінг | +| Віддалене керування (розширено) | Методи підключення, безпека, порівняння | Управління віддаленими сесіями | +| Налаштування клавіатури | Кастомні клавіші, акорди, контексти | Персоналізовані ярлики | +| Десктопний застосунок (розширено) | Конектори, launch.json, Enterprise | Десктопна інтеграція | + +**Розширені функції**: + +### Режим планування (Planning Mode) + +- Створення детальних планів реалізації +- Оцінка часу та ризиків +- Систематичний розподіл завдань + +### Розширене мислення (Extended Thinking) + +- Глибокий аналіз складних проблем +- Аналіз архітектурних рішень +- Оцінка компромісів + +### Фонові завдання (Background Tasks) + +- Тривалі операції без блокування +- Паралельні робочі процеси +- Управління завданнями та моніторинг + +### Режими дозволів (Permission Modes) + +- **default**: Запитувати дозвіл на ризиковані дії +- **acceptEdits**: Автоматично приймати редагування, запитувати інше +- **plan**: Лише аналіз, без змін (тільки читання) +- **auto**: Автоматично схвалювати безпечні дії, запитувати ризиковані +- **dontAsk**: Приймати всі дії, крім ризикованих +- **bypassPermissions**: Приймати все (потребує `--dangerously-skip-permissions`) + +### Headless-режим (`claude -p`) + +- Інтеграція з CI/CD +- Автоматичне виконання завдань +- Пакетна обробка + +### Управління сесіями + +- Кілька робочих сесій +- Перемикання та збереження сесій +- Постійність сесій + +### Інтерактивні функції + +- Клавіатурні скорочення +- Історія команд +- Автодоповнення (Tab) +- Багаторядковий ввід + +### Конфігурація + +- Комплексне управління налаштуваннями +- Конфігурації для різних середовищ +- Налаштування на рівні проекту + +### Заплановані завдання + +- Повторювані завдання з командою `/loop` +- Інструменти cron: CronCreate, CronList, CronDelete +- Автоматичні повторювані процеси + +### Інтеграція з Chrome + +- Автоматизація браузера через headless Chromium +- Веб-тестування та скрейпінг +- Взаємодія зі сторінками та витяг даних + +### Віддалене керування (розширено) + +- Методи та протоколи підключення +- Безпека та найкращі практики +- Порівняльна таблиця варіантів віддаленого доступу + +### Налаштування клавіатури + +- Конфігурація кастомних клавіш +- Підтримка акордів (комбінацій клавіш) +- Контекстно-залежна активація + +### Десктопний застосунок (розширено) + +- Конектори для IDE-інтеграції +- Конфігурація launch.json +- Enterprise-функції та розгортання + +--- + +## 10. Використання CLI (1 файл) + +Патерни використання та довідник командного рядка. + +| Файл | Опис | Вміст | +|------|------|-------| +| `README.md` | Документація CLI | Прапорці, опції та патерни використання | + +**Ключові можливості CLI**: + +- `claude` — Запуск інтерактивної сесії +- `claude -p "prompt"` — Headless/неінтерактивний режим +- `claude web` — Запуск веб-сесії +- `claude --model` — Вибір моделі (Sonnet 4.6, Opus 4.6) +- `claude --permission-mode` — Встановлення режиму дозволів +- `claude --remote` — Увімкнення віддаленого керування через WebSocket + +--- + +## Файли документації (13 файлів) + +| Файл | Розташування | Опис | +|------|-------------|------| +| `README.md` | `/` | Головний огляд прикладів | +| `INDEX.md` | `/` | Цей повний покажчик | +| `QUICK_REFERENCE.md` | `/` | Картка швидкого довідника | +| `README.md` | `/01-slash-commands/` | Посібник зі слеш-команд | +| `README.md` | `/02-memory/` | Посібник з пам'яті | +| `README.md` | `/03-skills/` | Посібник з навичок | +| `README.md` | `/04-subagents/` | Посібник із субагентів | +| `README.md` | `/05-mcp/` | Посібник з MCP | +| `README.md` | `/06-hooks/` | Посібник з хуків | +| `README.md` | `/07-plugins/` | Посібник з плагінів | +| `README.md` | `/08-checkpoints/` | Посібник з контрольних точок | +| `README.md` | `/09-advanced-features/` | Посібник з розширених функцій | +| `README.md` | `/10-cli/` | Посібник з CLI | + +--- + +## Повне дерево файлів + +``` +claude-howto/ +├── README.md # Головний огляд +├── INDEX.md # Цей файл +├── QUICK_REFERENCE.md # Картка довідника +├── claude_concepts_guide.md # Оригінальний посібник +│ +├── 01-slash-commands/ # Слеш-команди +│ ├── optimize.md +│ ├── pr.md +│ ├── generate-api-docs.md +│ ├── commit.md +│ ├── setup-ci-cd.md +│ ├── push-all.md +│ ├── unit-test-expand.md +│ ├── doc-refactor.md +│ ├── pr-slash-command.png +│ └── README.md +│ +├── 02-memory/ # Пам'ять +│ ├── project-CLAUDE.md +│ ├── directory-api-CLAUDE.md +│ ├── personal-CLAUDE.md +│ ├── memory-saved.png +│ ├── memory-ask-claude.png +│ └── README.md +│ +├── 03-skills/ # Навички +│ ├── code-review/ +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ │ ├── analyze-metrics.py +│ │ │ └── compare-complexity.py +│ │ └── templates/ +│ │ ├── review-checklist.md +│ │ └── finding-template.md +│ ├── brand-voice/ +│ │ ├── SKILL.md +│ │ ├── templates/ +│ │ │ ├── email-template.txt +│ │ │ └── social-post-template.txt +│ │ └── tone-examples.md +│ ├── doc-generator/ +│ │ ├── SKILL.md +│ │ └── generate-docs.py +│ ├── refactor/ +│ │ ├── SKILL.md +│ │ ├── scripts/ +│ │ │ ├── analyze-complexity.py +│ │ │ └── detect-smells.py +│ │ ├── references/ +│ │ │ ├── code-smells.md +│ │ │ └── refactoring-catalog.md +│ │ └── templates/ +│ │ └── refactoring-plan.md +│ ├── claude-md/ +│ │ └── SKILL.md +│ ├── blog-draft/ +│ │ ├── SKILL.md +│ │ └── templates/ +│ │ ├── draft-template.md +│ │ └── outline-template.md +│ └── README.md +│ +├── 04-subagents/ # Субагенти +│ ├── code-reviewer.md +│ ├── test-engineer.md +│ ├── documentation-writer.md +│ ├── secure-reviewer.md +│ ├── implementation-agent.md +│ ├── debugger.md +│ ├── data-scientist.md +│ ├── clean-code-reviewer.md +│ └── README.md +│ +├── 05-mcp/ # Протокол MCP +│ ├── github-mcp.json +│ ├── database-mcp.json +│ ├── filesystem-mcp.json +│ ├── multi-mcp.json +│ └── README.md +│ +├── 06-hooks/ # Хуки +│ ├── format-code.sh +│ ├── pre-commit.sh +│ ├── security-scan.sh +│ ├── log-bash.sh +│ ├── validate-prompt.sh +│ ├── notify-team.sh +│ ├── context-tracker.py +│ ├── context-tracker-tiktoken.py +│ └── README.md +│ +├── 07-plugins/ # Плагіни +│ ├── pr-review/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── review-pr.md +│ │ │ ├── check-security.md +│ │ │ └── check-tests.md +│ │ ├── agents/ +│ │ │ ├── security-reviewer.md +│ │ │ ├── test-checker.md +│ │ │ └── performance-analyzer.md +│ │ ├── mcp/ +│ │ │ └── github-config.json +│ │ ├── hooks/ +│ │ │ └── pre-review.js +│ │ └── README.md +│ ├── devops-automation/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── deploy.md +│ │ │ ├── rollback.md +│ │ │ ├── status.md +│ │ │ └── incident.md +│ │ ├── agents/ +│ │ │ ├── deployment-specialist.md +│ │ │ ├── incident-commander.md +│ │ │ └── alert-analyzer.md +│ │ ├── mcp/ +│ │ │ └── kubernetes-config.json +│ │ ├── hooks/ +│ │ │ ├── pre-deploy.js +│ │ │ └── post-deploy.js +│ │ ├── scripts/ +│ │ │ ├── deploy.sh +│ │ │ ├── rollback.sh +│ │ │ └── health-check.sh +│ │ └── README.md +│ ├── documentation/ +│ │ ├── .claude-plugin/ +│ │ │ └── plugin.json +│ │ ├── commands/ +│ │ │ ├── generate-api-docs.md +│ │ │ ├── generate-readme.md +│ │ │ ├── sync-docs.md +│ │ │ └── validate-docs.md +│ │ ├── agents/ +│ │ │ ├── api-documenter.md +│ │ │ ├── code-commentator.md +│ │ │ └── example-generator.md +│ │ ├── mcp/ +│ │ │ └── github-docs-config.json +│ │ ├── templates/ +│ │ │ ├── api-endpoint.md +│ │ │ ├── function-docs.md +│ │ │ └── adr-template.md +│ │ └── README.md +│ └── README.md +│ +├── 08-checkpoints/ # Контрольні точки +│ ├── checkpoint-examples.md +│ └── README.md +│ +├── 09-advanced-features/ # Розширені функції +│ ├── config-examples.json +│ ├── planning-mode-examples.md +│ └── README.md +│ +└── 10-cli/ # Використання CLI + └── README.md +``` + +--- + +## Швидкий старт за сценарієм + +### Якість коду та ревʼю + +```bash +# Встановити слеш-команду +cp 01-slash-commands/optimize.md .claude/commands/ + +# Встановити субагента +cp 04-subagents/code-reviewer.md .claude/agents/ + +# Встановити навичку +cp -r 03-skills/code-review ~/.claude/skills/ + +# Або встановити повний плагін +/plugin install pr-review +``` + +### DevOps та розгортання + +```bash +# Встановити плагін (включає все) +/plugin install devops-automation +``` + +### Документація + +```bash +# Встановити слеш-команду +cp 01-slash-commands/generate-api-docs.md .claude/commands/ + +# Встановити субагента +cp 04-subagents/documentation-writer.md .claude/agents/ + +# Встановити навичку +cp -r 03-skills/doc-generator ~/.claude/skills/ + +# Або встановити повний плагін +/plugin install documentation +``` + +### Командні стандарти + +```bash +# Налаштувати пам'ять проекту +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Відредагуйте під стандарти вашої команди +``` + +### Зовнішні інтеграції + +```bash +# Встановити змінні оточення +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# Встановити конфігурацію MCP (рівень проекту) +cp 05-mcp/multi-mcp.json .mcp.json +``` + +### Автоматизація та валідація + +```bash +# Встановити хуки +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# Налаштувати хуки в settings (~/.claude/settings.json) +# Див. 06-hooks/README.md +``` + +### Безпечне експериментування + +```bash +# Контрольні точки створюються автоматично з кожним промптом +# Для відкату: натисніть Esc+Esc або скористайтесь /rewind +# Потім оберіть, що відновити, з меню відкату + +# Див. 08-checkpoints/README.md для прикладів +``` + +### Розширені робочі процеси + +```bash +# Налаштувати розширені функції +# Див. 09-advanced-features/config-examples.json + +# Використати режим планування +/plan Implement feature X + +# Використати режими дозволів +claude --permission-mode plan # Для ревʼю коду (тільки читання) +claude --permission-mode acceptEdits # Автоматично приймати редагування +claude --permission-mode auto # Автоматично схвалювати безпечні дії + +# Запустити в headless-режимі для CI/CD +claude -p "Run tests and report results" + +# Запустити фонові завдання +Run tests in background + +# Див. 09-advanced-features/README.md для повного посібника +``` + +--- + +## Матриця покриття функцій + +| Категорія | Команди | Агенти | MCP | Хуки | Скрипти | Шаблони | Доки | Зображення | Разом | +|-----------|---------|--------|-----|------|---------|---------|------|------------|-------| +| **01 Слеш-команди** | 8 | - | - | - | - | - | 1 | 1 | **10** | +| **02 Пам'ять** | - | - | - | - | - | 3 | 1 | 2 | **6** | +| **03 Навички** | - | - | - | - | 5 | 9 | 1 | - | **28** | +| **04 Субагенти** | - | 8 | - | - | - | - | 1 | - | **9** | +| **05 MCP** | - | - | 4 | - | - | - | 1 | - | **5** | +| **06 Хуки** | - | - | - | 8 | - | - | 1 | - | **9** | +| **07 Плагіни** | 11 | 9 | 3 | 3 | 3 | 3 | 4 | - | **40** | +| **08 Контрольні точки** | - | - | - | - | - | - | 1 | 1 | **2** | +| **09 Розширені** | - | - | - | - | - | - | 1 | 2 | **3** | +| **10 CLI** | - | - | - | - | - | - | 1 | - | **1** | + +--- + +## Навчальний шлях + +### Початківець (Тиждень 1) + +1. ✅ Прочитати `README.md` +2. ✅ Встановити 1-2 слеш-команди +3. ✅ Створити файл пам'яті проекту +4. ✅ Спробувати базові команди + +### Середній рівень (Тижні 2-3) + +1. ✅ Налаштувати GitHub MCP +2. ✅ Встановити субагента +3. ✅ Спробувати делегувати завдання +4. ✅ Встановити навичку + +### Просунутий (Тиждень 4+) + +1. ✅ Встановити повний плагін +2. ✅ Створити власні слеш-команди +3. ✅ Створити власного субагента +4. ✅ Створити власну навичку +5. ✅ Створити власний плагін + +### Експерт (Тиждень 5+) + +1. ✅ Налаштувати хуки для автоматизації +2. ✅ Використовувати контрольні точки для експериментів +3. ✅ Налаштувати режим планування +4. ✅ Ефективно використовувати режими дозволів +5. ✅ Налаштувати headless-режим для CI/CD +6. ✅ Опанувати управління сесіями + +--- + +## Пошук за ключовим словом + +### Продуктивність + +- `01-slash-commands/optimize.md` — Аналіз продуктивності +- `04-subagents/code-reviewer.md` — Ревʼю продуктивності +- `03-skills/code-review/` — Метрики продуктивності +- `07-plugins/pr-review/agents/performance-analyzer.md` — Спеціаліст з продуктивності + +### Безпека + +- `04-subagents/secure-reviewer.md` — Ревʼю безпеки +- `03-skills/code-review/` — Аналіз безпеки +- `07-plugins/pr-review/` — Перевірки безпеки + +### Тестування + +- `04-subagents/test-engineer.md` — Інженер з тестування +- `07-plugins/pr-review/commands/check-tests.md` — Покриття тестами + +### Документація + +- `01-slash-commands/generate-api-docs.md` — Команда генерації API-документації +- `04-subagents/documentation-writer.md` — Агент-документатор +- `03-skills/doc-generator/` — Навичка генерації документації +- `07-plugins/documentation/` — Повний плагін документації + +### Розгортання + +- `07-plugins/devops-automation/` — Повне DevOps-рішення + +### Автоматизація + +- `06-hooks/` — Автоматизація на основі подій +- `06-hooks/pre-commit.sh` — Автоматизація pre-commit +- `06-hooks/format-code.sh` — Автоформатування +- `09-advanced-features/` — Headless-режим для CI/CD + +### Валідація + +- `06-hooks/security-scan.sh` — Валідація безпеки +- `06-hooks/validate-prompt.sh` — Валідація промптів + +### Експериментування + +- `08-checkpoints/` — Безпечне експериментування з відкатом +- `08-checkpoints/checkpoint-examples.md` — Практичні приклади + +### Планування + +- `09-advanced-features/planning-mode-examples.md` — Приклади режиму планування +- `09-advanced-features/README.md` — Розширене мислення + +### Конфігурація + +- `09-advanced-features/config-examples.json` — Приклади конфігурації + +--- + +## Примітки + +- Усі приклади готові до використання +- Модифікуйте під ваші конкретні потреби +- Приклади дотримуються найкращих практик Claude Code +- Кожна категорія має власний README з детальними інструкціями +- Скрипти включають обробку помилок +- Шаблони можна налаштовувати + +--- + +## Як долучитися + +Хочете додати більше прикладів? Дотримуйтесь структури: + +1. Створіть відповідний підкаталог +2. Додайте README.md з інструкціями +3. Дотримуйтесь конвенцій назв +4. Ретельно протестуйте +5. Оновіть цей покажчик + +--- + +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Прикладів**: 100+ файлів +**Категорій**: 10 функцій +**Хуків**: 8 скриптів автоматизації +**Прикладів конфігурації**: 10+ сценаріїв +**Готові до використання**: Усі приклади diff --git a/uk/LEARNING-ROADMAP.md b/uk/LEARNING-ROADMAP.md new file mode 100644 index 0000000..ff74200 --- /dev/null +++ b/uk/LEARNING-ROADMAP.md @@ -0,0 +1,800 @@ + + + + + + + Claude How To + + +# 📚 Навчальний план Claude Code + +**Новачок у Claude Code?** Цей посібник допоможе вам опанувати функції Claude Code у зручному темпі. Незалежно від того, чи ви абсолютний початківець, чи досвідчений розробник, почніть з тесту самооцінки нижче, щоб знайти свій рівень. + +--- + +## 🧭 Визначте свій рівень + +Не всі починають з однієї точки. Пройдіть швидку самооцінку, щоб знайти правильну відправну точку. + +**Відповідайте чесно:** + +- [ ] Я можу запустити Claude Code та вести розмову (`claude`) +- [ ] Я створював або редагував файл CLAUDE.md +- [ ] Я використовував принаймні 3 вбудовані слеш-команди (наприклад, /help, /compact, /model) +- [ ] Я створював кастомну слеш-команду або навичку (SKILL.md) +- [ ] Я налаштовував MCP-сервер (наприклад, GitHub, база даних) +- [ ] Я налаштовував хуки в ~/.claude/settings.json +- [ ] Я створював або використовував кастомних субагентів (.claude/agents/) +- [ ] Я використовував print mode (`claude -p`) для скриптів або CI/CD + +**Ваш рівень:** + +| Відмічено | Рівень | Почніть з | Час на завершення | +|-----------|--------|-----------|-------------------| +| 0-2 | **Рівень 1: Початківець** — Перші кроки | [Етап 1A](#етап-1a-перші-команди-та-память) | ~3 години | +| 3-5 | **Рівень 2: Середній** — Побудова процесів | [Етап 2A](#етап-2a-автоматизація-навички--хуки) | ~5 годин | +| 6-8 | **Рівень 3: Просунутий** — Досвідчений користувач | [Етап 3A](#етап-3a-розширені-функції) | ~5 годин | + +> **Порада**: Якщо не впевнені, почніть на рівень нижче. Краще швидко переглянути знайомий матеріал, ніж пропустити базові концепції. + +> **Інтерактивна версія**: Запустіть `/self-assessment` у Claude Code для керованого інтерактивного тесту, який оцінить вашу компетенцію за всіма 10 функціональними напрямками та згенерує персоналізований навчальний план. + +--- + +## 🎯 Філософія навчання + +Каталоги в цьому репозиторії пронумеровані у **рекомендованому порядку вивчення** на основі трьох принципів: + +1. **Залежності** — Базові концепції йдуть першими +2. **Складність** — Простіші функції перед складними +3. **Частота використання** — Найпоширеніші функції вивчаються раніше + +Цей підхід забезпечує міцну основу та негайний приріст продуктивності. + +--- + +## 🗺️ Ваш навчальний шлях + +```mermaid +graph TD + Q["🧭 Self-Assessment Quiz
Find Your Level"] --> L1 + Q --> L2 + Q --> L3 + + subgraph L1["🟢 Level 1: Beginner — Getting Started"] + direction LR + A["1A: First Commands & Memory
Slash Commands + Memory"] --> B["1B: Safe Exploration
Checkpoints + CLI Basics"] + end + + subgraph L2["🔵 Level 2: Intermediate — Building Workflows"] + direction LR + C["2A: Automation
Skills + Hooks"] --> D["2B: Integration
MCP + Subagents"] + end + + subgraph L3["🔴 Level 3: Advanced — Power User"] + direction LR + E["3A: Advanced Features
Planning + Permissions"] --> F["3B: Team & Distribution
Plugins + CLI Mastery"] + end + + L1 --> L2 + L2 --> L3 + + style Q fill:#6A1B9A,color:#fff,stroke:#9C27B0,stroke-width:2px + style A fill:#2E7D32,color:#fff + style B fill:#2E7D32,color:#fff + style C fill:#1565C0,color:#fff + style D fill:#F57C00,color:#fff + style E fill:#C62828,color:#fff + style F fill:#B71C1C,color:#fff +``` + +**Легенда кольорів:** + +- 💜 Фіолетовий: Тест самооцінки +- 🟢 Зелений: Рівень 1 — Шлях початківця +- 🔵 Синій / 🟡 Золотий: Рівень 2 — Середній шлях +- 🔴 Червоний: Рівень 3 — Просунутий шлях + +--- + +## 📊 Повна таблиця навчального плану + +| Крок | Функція | Складність | Час | Рівень | Залежності | Чому вивчати | Ключові переваги | +|------|---------|-----------|-----|--------|------------|-------------|-----------------| +| **1** | [Слеш-команди](../01-slash-commands/) | ⭐ Початківець | 30 хв | Рівень 1 | Немає | Швидкий приріст продуктивності (55+ вбудованих + 5 навичок) | Миттєва автоматизація | +| **2** | [Пам'ять](../02-memory/) | ⭐⭐ Початківець+ | 45 хв | Рівень 1 | Немає | Необхідна для всіх функцій | Постійний контекст | +| **3** | [Контрольні точки](../08-checkpoints/) | ⭐⭐ Середній | 45 хв | Рівень 1 | Управління сесіями | Безпечне дослідження | Експериментування, відновлення | +| **4** | [Основи CLI](../10-cli/) | ⭐⭐ Початківець+ | 30 хв | Рівень 1 | Немає | Базове використання CLI | Інтерактивний та print mode | +| **5** | [Навички](../03-skills/) | ⭐⭐ Середній | 1 год | Рівень 2 | Слеш-команди | Автоматична експертиза | Повторювані можливості | +| **6** | [Хуки](../06-hooks/) | ⭐⭐ Середній | 1 год | Рівень 2 | Інструменти, Команди | Автоматизація процесів (25 подій, 4 типи) | Валідація, контроль якості | +| **7** | [MCP](../05-mcp/) | ⭐⭐⭐ Середній+ | 1 год | Рівень 2 | Конфігурація | Доступ до даних у реальному часі | Інтеграція, API | +| **8** | [Субагенти](../04-subagents/) | ⭐⭐⭐ Середній+ | 1.5 год | Рівень 2 | Пам'ять, Команди | Складні завдання (6 вбудованих) | Делегування, спеціалізація | +| **9** | [Розширені функції](../09-advanced-features/) | ⭐⭐⭐⭐⭐ Просунутий | 2-3 год | Рівень 3 | Усі попередні | Інструменти експерта | Планування, Auto Mode, канали | +| **10** | [Плагіни](../07-plugins/) | ⭐⭐⭐⭐ Просунутий | 2 год | Рівень 3 | Усі попередні | Комплексні рішення | Онбординг команди, дистрибуція | +| **11** | [Майстерність CLI](../10-cli/) | ⭐⭐⭐ Просунутий | 1 год | Рівень 3 | Рекомендовано: Усі | Майстерність командного рядка | Скрипти, CI/CD | + +**Загальний час навчання**: ~11-13 годин (або перейдіть на свій рівень і заощадьте час) + +--- + +## 🟢 Рівень 1: Початківець — Перші кроки + +**Для**: Користувачів з 0-2 відмітками в тесті +**Час**: ~3 години +**Фокус**: Негайна продуктивність, розуміння основ +**Результат**: Впевнений щоденний користувач, готовий до Рівня 2 + +### Етап 1A: Перші команди та пам'ять + +**Теми**: Слеш-команди + Пам'ять +**Час**: 1-2 години +**Складність**: ⭐ Початківець +**Мета**: Негайний приріст продуктивності з кастомними командами та постійним контекстом + +#### Що ви досягнете + +✅ Створення кастомних слеш-команд для повторюваних завдань +✅ Налаштування пам'яті проекту для командних стандартів +✅ Конфігурація персональних налаштувань +✅ Розуміння автоматичного завантаження контексту Claude + +#### Практичні вправи + +```bash +# Вправа 1: Встановіть першу слеш-команду +mkdir -p .claude/commands +cp 01-slash-commands/optimize.md .claude/commands/ + +# Вправа 2: Створіть пам'ять проекту +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Вправа 3: Спробуйте +# У Claude Code введіть: /optimize +``` + +#### Критерії успіху + +- [ ] Успішний виклик команди `/optimize` +- [ ] Claude пам'ятає стандарти проекту з CLAUDE.md +- [ ] Ви розумієте, коли використовувати слеш-команди, а коли пам'ять + +#### Наступні кроки + +Коли освоїтесь, прочитайте: + +- [01-slash-commands/README.md](../01-slash-commands/README.md) +- [02-memory/README.md](../02-memory/README.md) + +> **Перевірте розуміння**: Запустіть `/lesson-quiz slash-commands` або `/lesson-quiz memory` у Claude Code. + +--- + +### Етап 1B: Безпечне дослідження + +**Теми**: Контрольні точки + Основи CLI +**Час**: 1 година +**Складність**: ⭐⭐ Початківець+ +**Мета**: Навчитися безпечно експериментувати та використовувати базові команди CLI + +#### Що ви досягнете + +✅ Створення та відновлення контрольних точок для безпечних експериментів +✅ Розуміння інтерактивного та print mode +✅ Використання базових прапорців та опцій CLI +✅ Обробка файлів через пайпінг + +#### Практичні вправи + +```bash +# Вправа 1: Спробуйте процес з контрольними точками +# У Claude Code: +# Зробіть експериментальні зміни, потім натисніть Esc+Esc або /rewind +# Оберіть контрольну точку перед експериментом +# Оберіть "Restore code and conversation" для повернення + +# Вправа 2: Інтерактивний та Print mode +claude "explain this project" # Інтерактивний режим +claude -p "explain this function" # Print mode (неінтерактивний) + +# Вправа 3: Обробка вмісту файлу через пайп +cat error.log | claude -p "explain this error" +``` + +#### Критерії успіху + +- [ ] Створено та відновлено контрольну точку +- [ ] Використано інтерактивний та print mode +- [ ] Передано файл Claude для аналізу через пайп +- [ ] Розуміння використання контрольних точок для безпечних експериментів + +#### Наступні кроки + +- Прочитайте: [08-checkpoints/README.md](../08-checkpoints/README.md) +- Прочитайте: [10-cli/README.md](../10-cli/README.md) +- **Готові до Рівня 2!** Переходьте до [Етапу 2A](#етап-2a-автоматизація-навички--хуки) + +> **Перевірте розуміння**: Запустіть `/lesson-quiz checkpoints` або `/lesson-quiz cli`. + +--- + +## 🔵 Рівень 2: Середній — Побудова процесів + +**Для**: Користувачів з 3-5 відмітками в тесті +**Час**: ~5 годин +**Фокус**: Автоматизація, інтеграція, делегування завдань +**Результат**: Автоматизовані процеси, зовнішні інтеграції, готовність до Рівня 3 + +### Перевірка передумов + +Перед початком Рівня 2 переконайтеся, що ви освоїли концепції Рівня 1: + +- [ ] Вмієте створювати та використовувати слеш-команди ([01-slash-commands/](../01-slash-commands/)) +- [ ] Налаштували пам'ять проекту через CLAUDE.md ([02-memory/](../02-memory/)) +- [ ] Знаєте, як створювати та відновлювати контрольні точки ([08-checkpoints/](../08-checkpoints/)) +- [ ] Вмієте використовувати `claude` та `claude -p` з командного рядка ([10-cli/](../10-cli/)) + +> **Прогалини?** Перегляньте відповідні посібники перед продовженням. + +--- + +### Етап 2A: Автоматизація (Навички + Хуки) + +**Теми**: Навички + Хуки +**Час**: 2-3 години +**Складність**: ⭐⭐ Середній +**Мета**: Автоматизувати типові процеси та перевірки якості + +#### Що ви досягнете + +✅ Автовиклик спеціалізованих можливостей з YAML-фронтматером (включно з полями `effort` та `shell`) +✅ Налаштування автоматизації на основі подій через 25 подій хуків +✅ Використання всіх 4 типів хуків (command, http, prompt, agent) +✅ Забезпечення стандартів якості коду +✅ Створення кастомних хуків для ваших процесів + +#### Практичні вправи + +```bash +# Вправа 1: Встановіть навичку +cp -r 03-skills/code-review ~/.claude/skills/ + +# Вправа 2: Налаштуйте хуки +mkdir -p ~/.claude/hooks +cp 06-hooks/pre-tool-check.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/pre-tool-check.sh + +# Вправа 3: Налаштуйте хуки в settings +# Додайте в ~/.claude/settings.json: +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.claude/hooks/pre-tool-check.sh" + } + ] + } + ] + } +} +``` + +#### Критерії успіху + +- [ ] Навичка code review автоматично викликається при потребі +- [ ] Хук PreToolUse запускається перед виконанням інструменту +- [ ] Ви розумієте різницю між автовикликом навичок та тригерами подій хуків + +#### Наступні кроки + +- Створіть власну кастомну навичку +- Налаштуйте додаткові хуки для вашого процесу +- Прочитайте: [03-skills/README.md](../03-skills/README.md) +- Прочитайте: [06-hooks/README.md](../06-hooks/README.md) + +> **Перевірте розуміння**: Запустіть `/lesson-quiz skills` або `/lesson-quiz hooks`. + +--- + +### Етап 2B: Інтеграція (MCP + Субагенти) + +**Теми**: MCP + Субагенти +**Час**: 2-3 години +**Складність**: ⭐⭐⭐ Середній+ +**Мета**: Інтегрувати зовнішні сервіси та делегувати складні завдання + +#### Що ви досягнете + +✅ Доступ до даних з GitHub, баз даних тощо в реальному часі +✅ Делегування роботи спеціалізованим AI-агентам +✅ Розуміння, коли використовувати MCP, а коли субагентів +✅ Побудова інтегрованих процесів + +#### Практичні вправи + +```bash +# Вправа 1: Налаштуйте GitHub MCP +export GITHUB_TOKEN="your_github_token" +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# Вправа 2: Перевірте MCP-інтеграцію +# У Claude Code: /mcp__github__list_prs + +# Вправа 3: Встановіть субагентів +mkdir -p .claude/agents +cp 04-subagents/*.md .claude/agents/ +``` + +#### Вправа з інтеграції + +Спробуйте повний процес: + +1. Використайте MCP для отримання GitHub PR +2. Дозвольте Claude делегувати ревʼю субагенту code-reviewer +3. Використайте хуки для автоматичного запуску тестів + +#### Критерії успіху + +- [ ] Успішний запит даних GitHub через MCP +- [ ] Claude делегує складні завдання субагентам +- [ ] Ви розумієте різницю між MCP та субагентами +- [ ] Комбінація MCP + субагенти + хуки у процесі + +#### Наступні кроки + +- Налаштуйте додаткові MCP-сервери (база даних, Slack тощо) +- Створіть кастомних субагентів для вашої предметної області +- Прочитайте: [05-mcp/README.md](../05-mcp/README.md) +- Прочитайте: [04-subagents/README.md](../04-subagents/README.md) +- **Готові до Рівня 3!** Переходьте до [Етапу 3A](#етап-3a-розширені-функції) + +> **Перевірте розуміння**: Запустіть `/lesson-quiz mcp` або `/lesson-quiz subagents`. + +--- + +## 🔴 Рівень 3: Просунутий — Досвідчений користувач та тімлід + +**Для**: Користувачів з 6-8 відмітками в тесті +**Час**: ~5 годин +**Фокус**: Командні інструменти, CI/CD, enterprise-функції, розробка плагінів +**Результат**: Досвідчений користувач, здатний налаштувати командні процеси та CI/CD + +### Перевірка передумов + +Перед початком Рівня 3 переконайтеся, що ви освоїли концепції Рівня 2: + +- [ ] Вмієте створювати та використовувати навички з автовикликом ([03-skills/](../03-skills/)) +- [ ] Налаштували хуки для автоматизації на основі подій ([06-hooks/](../06-hooks/)) +- [ ] Вмієте конфігурувати MCP-сервери для зовнішніх даних ([05-mcp/](../05-mcp/)) +- [ ] Знаєте, як використовувати субагентів для делегування ([04-subagents/](../04-subagents/)) + +> **Прогалини?** Перегляньте відповідні посібники перед продовженням. + +--- + +### Етап 3A: Розширені функції + +**Теми**: Розширені функції (Планування, Дозволи, Розширене мислення, Auto Mode, Канали, Голосовий ввід, Віддалене/Десктоп/Веб) +**Час**: 2-3 години +**Складність**: ⭐⭐⭐⭐⭐ Просунутий +**Мета**: Опанувати розширені процеси та інструменти експерта + +#### Що ви досягнете + +✅ Режим планування для складних функцій +✅ Точний контроль дозволів з 6 режимами (default, acceptEdits, plan, auto, dontAsk, bypassPermissions) +✅ Розширене мислення через Alt+T / Option+T +✅ Управління фоновими завданнями +✅ Автопам'ять для вивчених налаштувань +✅ Auto Mode з фоновим класифікатором безпеки +✅ Канали для структурованих багатосесійних процесів +✅ Голосовий ввід для роботи без клавіатури +✅ Віддалене керування, десктопний застосунок та веб-сесії +✅ Команди агентів для багатоагентної співпраці + +#### Практичні вправи + +```bash +# Вправа 1: Режим планування +/plan Implement user authentication system + +# Вправа 2: Режими дозволів (6 доступних: default, acceptEdits, plan, auto, dontAsk, bypassPermissions) +claude --permission-mode plan "analyze this codebase" +claude --permission-mode acceptEdits "refactor the auth module" +claude --permission-mode auto "implement the feature" + +# Вправа 3: Розширене мислення +# Натисніть Alt+T (Option+T на macOS) під час сесії для перемикання + +# Вправа 4: Розширений процес з контрольними точками +# 1. Створіть контрольну точку "Clean state" +# 2. Використайте режим планування для проєктування функції +# 3. Реалізуйте з делегуванням субагенту +# 4. Запустіть тести у фоні +# 5. Якщо тести не пройшли — відкат до контрольної точки +# 6. Спробуйте альтернативний підхід + +# Вправа 5: Auto mode (фоновий класифікатор безпеки) +claude --permission-mode auto "implement user settings page" + +# Вправа 6: Команди агентів +export CLAUDE_AGENT_TEAMS=1 +# Попросіть Claude: "Implement feature X using a team approach" + +# Вправа 7: Заплановані завдання +/loop 5m /check-status +# Або CronCreate для постійних запланованих завдань + +# Вправа 8: Канали для багатосесійних процесів +# Використовуйте канали для організації роботи між сесіями + +# Вправа 9: Голосовий ввід +# Використовуйте голосовий ввід для роботи без клавіатури з Claude Code +``` + +#### Критерії успіху + +- [ ] Використано режим планування для складної функції +- [ ] Налаштовано режими дозволів (plan, acceptEdits, auto, dontAsk) +- [ ] Увімкнено розширене мислення з Alt+T / Option+T +- [ ] Використано auto mode з класифікатором безпеки +- [ ] Використано фонові завдання для тривалих операцій +- [ ] Досліджено канали для багатосесійних процесів +- [ ] Спробовано голосовий ввід +- [ ] Розуміння віддаленого керування, десктопного застосунку та веб-сесій +- [ ] Увімкнено та використано команди агентів для спільних завдань +- [ ] Використано `/loop` для повторюваних завдань або моніторингу + +#### Наступні кроки + +- Прочитайте: [09-advanced-features/README.md](../09-advanced-features/README.md) + +> **Перевірте розуміння**: Запустіть `/lesson-quiz advanced`. + +--- + +### Етап 3B: Команда та дистрибуція (Плагіни + Майстерність CLI) + +**Теми**: Плагіни + Майстерність CLI + CI/CD +**Час**: 2-3 години +**Складність**: ⭐⭐⭐⭐ Просунутий +**Мета**: Створення командних інструментів, плагінів, майстерність CI/CD-інтеграції + +#### Що ви досягнете + +✅ Встановлення та створення повних плагінів +✅ Майстерність CLI для скриптів та автоматизації +✅ Налаштування CI/CD-інтеграції з `claude -p` +✅ JSON-вивід для автоматизованих пайплайнів +✅ Управління сесіями та пакетна обробка + +#### Практичні вправи + +```bash +# Вправа 1: Встановіть повний плагін +# У Claude Code: /plugin install pr-review + +# Вправа 2: Print mode для CI/CD +claude -p "Run all tests and generate report" + +# Вправа 3: JSON-вивід для скриптів +claude -p --output-format json "list all functions" + +# Вправа 4: Управління сесіями та відновлення +claude -r "feature-auth" "continue implementation" + +# Вправа 5: CI/CD-інтеграція з обмеженнями +claude -p --max-turns 3 --output-format json "review code" + +# Вправа 6: Пакетна обробка +for file in *.md; do + claude -p --output-format json "summarize this: $(cat $file)" > ${file%.md}.summary.json +done +``` + +#### Вправа з CI/CD-інтеграції + +Створіть простий CI/CD-скрипт: + +1. Використайте `claude -p` для ревʼю змінених файлів +2. Виведіть результати як JSON +3. Обробіть з `jq` для конкретних проблем +4. Інтегруйте в GitHub Actions workflow + +#### Критерії успіху + +- [ ] Встановлено та використано плагін +- [ ] Створено або модифіковано плагін для команди +- [ ] Використано print mode (`claude -p`) в CI/CD +- [ ] Згенеровано JSON-вивід для скриптів +- [ ] Відновлено попередню сесію +- [ ] Створено скрипт пакетної обробки +- [ ] Інтегровано Claude в CI/CD-процес + +#### Реальні сценарії для CLI + +- **Автоматизація ревʼю коду**: Запуск ревʼю в CI/CD-пайплайнах +- **Аналіз логів**: Аналіз журналів помилок та системних виводів +- **Генерація документації**: Пакетна генерація документації +- **Інсайти тестування**: Аналіз невдалих тестів +- **Аналіз продуктивності**: Перегляд метрик продуктивності +- **Обробка даних**: Трансформація та аналіз файлів даних + +#### Наступні кроки + +- Прочитайте: [07-plugins/README.md](../07-plugins/README.md) +- Прочитайте: [10-cli/README.md](../10-cli/README.md) +- Створіть командні CLI-ярлики та плагіни +- Налаштуйте скрипти пакетної обробки + +> **Перевірте розуміння**: Запустіть `/lesson-quiz plugins` або `/lesson-quiz cli`. + +--- + +## 🧪 Перевірте свої знання + +Цей репозиторій включає дві інтерактивні навички для оцінки розуміння: + +| Навичка | Команда | Призначення | +|---------|---------|-------------| +| **Самооцінка** | `/self-assessment` | Оцінка загальної компетенції за всіма 10 функціями. Оберіть швидкий (2 хв) або глибокий (5 хв) режим для персоналізованого профілю. | +| **Тест уроку** | `/lesson-quiz [урок]` | Перевірка розуміння конкретного уроку з 10 питаннями. Використовуйте перед уроком (пре-тест), під час (перевірка) або після (верифікація). | + +**Приклади:** + +``` +/self-assessment # Визначити загальний рівень +/lesson-quiz hooks # Тест з Уроку 06: Хуки +/lesson-quiz 03 # Тест з Уроку 03: Навички +/lesson-quiz advanced-features # Тест з Уроку 09 +``` + +--- + +## ⚡ Швидкі шляхи + +### Якщо у вас лише 15 хвилин + +**Мета**: Отримати перший результат + +1. Скопіюйте одну слеш-команду: `cp 01-slash-commands/optimize.md .claude/commands/` +2. Спробуйте в Claude Code: `/optimize` +3. Прочитайте: [01-slash-commands/README.md](../01-slash-commands/README.md) + +**Результат**: Робоча слеш-команда та розуміння основ + +--- + +### Якщо у вас 1 година + +**Мета**: Налаштувати основні інструменти продуктивності + +1. **Слеш-команди** (15 хв): Скопіюйте та протестуйте `/optimize` та `/pr` +2. **Пам'ять проекту** (15 хв): Створіть CLAUDE.md зі стандартами проекту +3. **Навичка** (15 хв): Встановіть навичку code-review +4. **Спробуйте разом** (15 хв): Подивіться, як вони працюють у зв'язці + +**Результат**: Базовий приріст продуктивності з командами, пам'яттю та автонавичками + +--- + +### Якщо у вас є вихідні + +**Мета**: Стати компетентним у більшості функцій + +**Субота вранці** (3 години): + +- Завершити Етап 1A: Слеш-команди + Пам'ять +- Завершити Етап 1B: Контрольні точки + Основи CLI + +**Субота вдень** (3 години): + +- Завершити Етап 2A: Навички + Хуки +- Завершити Етап 2B: MCP + Субагенти + +**Неділя** (4 години): + +- Завершити Етап 3A: Розширені функції +- Завершити Етап 3B: Плагіни + Майстерність CLI + CI/CD +- Створити кастомний плагін для команди + +**Результат**: Ви станете досвідченим користувачем Claude Code, готовим навчати інших та автоматизувати складні процеси + +--- + +## 💡 Поради з навчання + +### ✅ Робіть + +- **Пройдіть тест спочатку**, щоб знайти відправну точку +- **Виконуйте практичні вправи** для кожного етапу +- **Починайте просто** та додавайте складність поступово +- **Тестуйте кожну функцію** перед переходом до наступної +- **Робіть нотатки** про те, що працює для вашого процесу +- **Повертайтесь** до попередніх концепцій при вивченні просунутих тем +- **Експериментуйте безпечно** з контрольними точками +- **Діліться знаннями** з командою + +### ❌ Не робіть + +- **Не пропускайте перевірку передумов** при переході на вищий рівень +- **Не намагайтесь вивчити все одразу** — це перевантажує +- **Не копіюйте конфігурації без розуміння** — не зможете налагодити +- **Не забувайте тестувати** — завжди перевіряйте роботу +- **Не поспішайте з етапами** — приділіть час для розуміння +- **Не ігноруйте документацію** — кожен README містить цінні деталі +- **Не працюйте ізольовано** — обговорюйте з колегами + +--- + +## 🎓 Стилі навчання + +### Візуальні учні + +- Вивчайте діаграми mermaid у кожному README +- Спостерігайте за потоком виконання команд +- Малюйте власні діаграми процесів +- Використовуйте візуальний навчальний шлях вище + +### Практики + +- Виконуйте кожну практичну вправу +- Експериментуйте з варіаціями +- Ламайте та лагодьте (використовуйте контрольні точки!) +- Створюйте власні приклади + +### Читачі + +- Уважно читайте кожен README +- Вивчайте приклади коду +- Переглядайте порівняльні таблиці +- Читайте блог-пости з ресурсів + +### Соціальні учні + +- Організуйте сесії парного програмування +- Навчайте концепцій колег +- Долучайтесь до обговорень спільноти Claude Code +- Діліться кастомними конфігураціями + +--- + +## 📈 Відстеження прогресу + +Використовуйте ці чеклісти для відстеження прогресу за рівнями. Запустіть `/self-assessment` у будь-який час для оновленого профілю, або `/lesson-quiz [урок]` після кожного посібника для перевірки розуміння. + +### 🟢 Рівень 1: Початківець + +- [ ] Завершено [01-slash-commands](../01-slash-commands/) +- [ ] Завершено [02-memory](../02-memory/) +- [ ] Створено першу кастомну слеш-команду +- [ ] Налаштовано пам'ять проекту +- [ ] **Етап 1A досягнуто** +- [ ] Завершено [08-checkpoints](../08-checkpoints/) +- [ ] Завершено основи [10-cli](../10-cli/) +- [ ] Створено та відновлено контрольну точку +- [ ] Використано інтерактивний та print mode +- [ ] **Етап 1B досягнуто** + +### 🔵 Рівень 2: Середній + +- [ ] Завершено [03-skills](../03-skills/) +- [ ] Завершено [06-hooks](../06-hooks/) +- [ ] Встановлено першу навичку +- [ ] Налаштовано хук PreToolUse +- [ ] **Етап 2A досягнуто** +- [ ] Завершено [05-mcp](../05-mcp/) +- [ ] Завершено [04-subagents](../04-subagents/) +- [ ] Підключено GitHub MCP +- [ ] Створено кастомного субагента +- [ ] Комбіновано інтеграції у процесі +- [ ] **Етап 2B досягнуто** + +### 🔴 Рівень 3: Просунутий + +- [ ] Завершено [09-advanced-features](../09-advanced-features/) +- [ ] Використано режим планування +- [ ] Налаштовано режими дозволів (6 режимів включно з auto) +- [ ] Використано auto mode з класифікатором безпеки +- [ ] Увімкнено розширене мислення +- [ ] Досліджено канали та голосовий ввід +- [ ] **Етап 3A досягнуто** +- [ ] Завершено [07-plugins](../07-plugins/) +- [ ] Завершено розширене використання [10-cli](../10-cli/) +- [ ] Налаштовано print mode (`claude -p`) CI/CD +- [ ] Створено JSON-вивід для автоматизації +- [ ] Інтегровано Claude в CI/CD-пайплайн +- [ ] Створено командний плагін +- [ ] **Етап 3B досягнуто** + +--- + +## 🆘 Типові труднощі навчання + +### Труднощі 1: "Забагато концепцій одразу" + +**Рішення**: Зосередьтесь на одному етапі за раз. Завершіть усі вправи перед переходом далі. + +### Труднощі 2: "Не знаю, яку функцію використати" + +**Рішення**: Зверніться до [Матриці сценаріїв](../README.md#use-case-matrix) у головному README. + +### Труднощі 3: "Конфігурація не працює" + +**Рішення**: Перевірте розділ [Усунення неполадок](../README.md#troubleshooting) та перевірте розташування файлів. + +### Труднощі 4: "Концепції здаються схожими" + +**Рішення**: Перегляньте таблицю [Порівняння функцій](../README.md#feature-comparison) для розуміння відмінностей. + +### Труднощі 5: "Важко все запам'ятати" + +**Рішення**: Створіть власну шпаргалку. Використовуйте контрольні точки для безпечних експериментів. + +### Труднощі 6: "Я досвідчений, але не знаю з чого почати" + +**Рішення**: Пройдіть [Тест самооцінки](#-визначте-свій-рівень) вище. Перейдіть на свій рівень та використовуйте перевірку передумов для виявлення прогалин. + +--- + +## 🎯 Що далі після завершення? + +Після завершення всіх етапів: + +1. **Створіть командну документацію** — задокументуйте налаштування Claude Code вашої команди +2. **Створіть кастомні плагіни** — запакуйте процеси команди +3. **Дослідіть віддалене керування** — керуйте сесіями програмно +4. **Спробуйте веб-сесії** — використовуйте Claude Code через браузер +5. **Використовуйте десктопний застосунок** — нативний десктопний доступ +6. **Використовуйте Auto Mode** — автономна робота з класифікатором безпеки +7. **Використовуйте автопам'ять** — Claude автоматично вивчає ваші налаштування +8. **Налаштуйте команди агентів** — координуйте кількох агентів для складних завдань +9. **Використовуйте канали** — організуйте роботу між сесіями +10. **Спробуйте голосовий ввід** — робота без клавіатури +11. **Використовуйте заплановані завдання** — автоматизуйте з `/loop` та cron +12. **Додавайте приклади** — діліться зі спільнотою +13. **Менторіть інших** — допомагайте колегам навчатися +14. **Оптимізуйте процеси** — постійно покращуйте на основі досвіду +15. **Слідкуйте за оновленнями** — відстежуйте релізи та нові функції + +--- + +## 📚 Додаткові ресурси + +### Офіційна документація + +- [Документація Claude Code](https://code.claude.com/docs/en/overview) +- [Документація Anthropic](https://docs.anthropic.com) +- [Специфікація MCP](https://modelcontextprotocol.io) + +### Блог-пости + +- [Discovering Claude Code Slash Commands](https://medium.com/@luongnv89/discovering-claude-code-slash-commands-cdc17f0dfb29) + +### Спільнота + +- [Anthropic Cookbook](https://github.com/anthropics/anthropic-cookbook) +- [Репозиторій MCP-серверів](https://github.com/modelcontextprotocol/servers) + +--- + +## 💬 Зворотний зв'язок та підтримка + +- **Знайшли проблему?** Створіть issue в репозиторії +- **Маєте пропозицію?** Надішліть pull request +- **Потрібна допомога?** Перевірте документацію або запитайте спільноту + +--- + +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 +**Підтримується**: Контриб'ютори Claude How-To +**Ліцензія**: Освітні цілі, вільне використання та адаптація + +--- + +[← Повернутися до головного README](README.md) diff --git a/uk/LICENSE b/uk/LICENSE new file mode 100644 index 0000000..cf8db6a --- /dev/null +++ b/uk/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 luongnv89 + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/uk/QUICK_REFERENCE.md b/uk/QUICK_REFERENCE.md new file mode 100644 index 0000000..6461f87 --- /dev/null +++ b/uk/QUICK_REFERENCE.md @@ -0,0 +1,545 @@ + + + + + + + Claude How To + + +# Приклади Claude Code — Картка швидкого довідника + +## 🚀 Команди швидкого встановлення + +### Слеш-команди + +```bash +# Встановити всі +cp 01-slash-commands/*.md .claude/commands/ + +# Встановити конкретну +cp 01-slash-commands/optimize.md .claude/commands/ +``` + +### Пам'ять + +```bash +# Пам'ять проекту +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Персональна пам'ять +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +### Навички (Skills) + +```bash +# Персональні навички +cp -r 03-skills/code-review ~/.claude/skills/ + +# Навички проекту +cp -r 03-skills/code-review .claude/skills/ +``` + +### Субагенти + +```bash +# Встановити всі +cp 04-subagents/*.md .claude/agents/ + +# Встановити конкретного +cp 04-subagents/code-reviewer.md .claude/agents/ +``` + +### MCP + +```bash +# Встановити облікові дані +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# Встановити конфігурацію (рівень проекту) +cp 05-mcp/github-mcp.json .mcp.json + +# Або рівень користувача: додати в ~/.claude.json +``` + +### Хуки + +```bash +# Встановити хуки +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# Налаштувати в settings (~/.claude/settings.json) +``` + +### Плагіни + +```bash +# Встановити з прикладів (якщо опубліковані) +/plugin install pr-review +/plugin install devops-automation +/plugin install documentation +``` + +### Контрольні точки + +```bash +# Контрольні точки створюються автоматично з кожним промптом +# Для відкату натисніть Esc двічі або скористайтесь: +/rewind + +# Потім оберіть: Відновити код і розмову, Відновити розмову, +# Відновити код, Підсумувати звідси, або Скасувати +``` + +### Розширені функції + +```bash +# Налаштувати в settings (.claude/settings.json) +# Див. 09-advanced-features/config-examples.json + +# Режим планування +/plan Task description + +# Режими дозволів (прапорець --permission-mode) +# default - Запитувати дозвіл на ризиковані дії +# acceptEdits - Автоприйняття редагувань, запит на інше +# plan - Лише аналіз, без змін (тільки читання) +# dontAsk - Приймати все, крім ризикованого +# auto - Фоновий класифікатор вирішує автоматично +# bypassPermissions - Приймати все (потребує --dangerously-skip-permissions) + +# Управління сесіями +/resume # Відновити попередню розмову +/rename "name" # Назвати поточну сесію +/fork # Розгалужити поточну сесію +claude -c # Продовжити останню розмову +claude -r "session" # Відновити сесію за назвою/ID +``` + +--- + +## 📋 Шпаргалка по функціях + +| Функція | Шлях встановлення | Використання | +|---------|------------------|-------------| +| **Слеш-команди (55+)** | `.claude/commands/*.md` | `/command-name` | +| **Пам'ять** | `./CLAUDE.md` | Автозавантаження | +| **Навички** | `.claude/skills/*/SKILL.md` | Автовиклик | +| **Субагенти** | `.claude/agents/*.md` | Автоделегування | +| **MCP** | `.mcp.json` (проект) або `~/.claude.json` (користувач) | `/mcp__server__action` | +| **Хуки (25 подій)** | `~/.claude/hooks/*.sh` | Тригер на подію (4 типи) | +| **Плагіни** | Через `/plugin install` | Пакет всього | +| **Контрольні точки** | Вбудовано | `Esc+Esc` або `/rewind` | +| **Режим планування** | Вбудовано | `/plan <завдання>` | +| **Режими дозволів (6)** | Вбудовано | `--allowedTools`, `--permission-mode` | +| **Сесії** | Вбудовано | `/session <команда>` | +| **Фонові завдання** | Вбудовано | Run in background | +| **Віддалене керування** | Вбудовано | WebSocket API | +| **Веб-сесії** | Вбудовано | `claude web` | +| **Git Worktrees** | Вбудовано | `/worktree` | +| **Автопам'ять** | Вбудовано | Автозбереження в CLAUDE.md | +| **Список завдань** | Вбудовано | `/task list` | +| **Вбудовані навички (5)** | Вбудовано | `/simplify`, `/loop`, `/claude-api`, `/voice`, `/browse` | + +--- + +## 🎯 Типові сценарії використання + +### Ревʼю коду + +```bash +# Спосіб 1: Слеш-команда +cp 01-slash-commands/optimize.md .claude/commands/ +# Використання: /optimize + +# Спосіб 2: Субагент +cp 04-subagents/code-reviewer.md .claude/agents/ +# Використання: Автоделегування + +# Спосіб 3: Навичка +cp -r 03-skills/code-review ~/.claude/skills/ +# Використання: Автовиклик + +# Спосіб 4: Плагін (найкращий) +/plugin install pr-review +# Використання: /review-pr +``` + +### Документація + +```bash +# Слеш-команда +cp 01-slash-commands/generate-api-docs.md .claude/commands/ + +# Субагент +cp 04-subagents/documentation-writer.md .claude/agents/ + +# Навичка +cp -r 03-skills/doc-generator ~/.claude/skills/ + +# Плагін (комплексне рішення) +/plugin install documentation +``` + +### DevOps + +```bash +# Повний плагін +/plugin install devops-automation + +# Команди: /deploy, /rollback, /status, /incident +``` + +### Командні стандарти + +```bash +# Пам'ять проекту +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Відредагуйте під вашу команду +vim CLAUDE.md +``` + +### Автоматизація та хуки + +```bash +# Встановити хуки (25 подій, 4 типи: command, http, prompt, agent) +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# Приклади: +# - Тести перед комітом: pre-commit.sh +# - Автоформатування коду: format-code.sh +# - Сканування безпеки: security-scan.sh + +# Auto Mode для повністю автономних процесів +claude --enable-auto-mode -p "Refactor and test the auth module" +# Або циклічна зміна режимів інтерактивно з Shift+Tab +``` + +### Безпечний рефакторинг + +```bash +# Контрольні точки створюються автоматично перед кожним промптом +# Спробуйте рефакторинг +# Якщо вдалось: продовжуйте +# Якщо не вдалось: натисніть Esc+Esc або /rewind для відкату +``` + +### Складна реалізація + +```bash +# Використайте режим планування +/plan Implement user authentication system + +# Claude створить детальний план +# Перегляньте та затвердіть +# Claude реалізує систематично +``` + +### Інтеграція з CI/CD + +```bash +# Запуск у headless-режимі (неінтерактивно) +claude -p "Run all tests and generate report" + +# З режимом дозволів для CI +claude -p "Run tests" --permission-mode dontAsk + +# З Auto Mode для повністю автономних CI-завдань +claude --enable-auto-mode -p "Run tests and fix failures" + +# З хуками для автоматизації +# Див. 09-advanced-features/README.md +``` + +### Навчання та експериментування + +```bash +# Режим plan для безпечного аналізу +claude --permission-mode plan + +# Експериментуйте безпечно — контрольні точки створюються автоматично +# Для відкату: натисніть Esc+Esc або /rewind +``` + +### Команди агентів + +```bash +# Увімкнути команди агентів +export CLAUDE_AGENT_TEAMS=1 + +# Або в settings.json +{ "agentTeams": { "enabled": true } } + +# Почніть з: "Implement feature X using a team approach" +``` + +### Заплановані завдання + +```bash +# Запускати команду кожні 5 хвилин +/loop 5m /check-status + +# Одноразове нагадування +/loop 30m "remind me to check the deploy" +``` + +--- + +## 📁 Довідник розташування файлів + +``` +Ваш проект/ +├── .claude/ +│ ├── commands/ # Слеш-команди тут +│ ├── agents/ # Субагенти тут +│ ├── skills/ # Навички проекту тут +│ └── settings.json # Налаштування проекту (хуки тощо) +├── .mcp.json # Конфігурація MCP (рівень проекту) +├── CLAUDE.md # Пам'ять проекту +└── src/ + └── api/ + └── CLAUDE.md # Пам'ять для конкретного каталогу + +Домашній каталог/ +├── .claude/ +│ ├── commands/ # Персональні команди +│ ├── agents/ # Персональні агенти +│ ├── skills/ # Персональні навички +│ ├── hooks/ # Скрипти хуків +│ ├── settings.json # Налаштування користувача +│ ├── managed-settings.d/ # Керовані налаштування (enterprise/org) +│ └── CLAUDE.md # Персональна пам'ять +└── .claude.json # Персональна конфігурація MCP (рівень користувача) +``` + +--- + +## 🔍 Пошук прикладів + +### За категорією + +- **Слеш-команди**: `01-slash-commands/` +- **Пам'ять**: `02-memory/` +- **Навички**: `03-skills/` +- **Субагенти**: `04-subagents/` +- **MCP**: `05-mcp/` +- **Хуки**: `06-hooks/` +- **Плагіни**: `07-plugins/` +- **Контрольні точки**: `08-checkpoints/` +- **Розширені функції**: `09-advanced-features/` +- **CLI**: `10-cli/` + +### За сценарієм + +- **Продуктивність**: `01-slash-commands/optimize.md` +- **Безпека**: `04-subagents/secure-reviewer.md` +- **Тестування**: `04-subagents/test-engineer.md` +- **Документація**: `03-skills/doc-generator/` +- **DevOps**: `07-plugins/devops-automation/` + +### За складністю + +- **Просто**: Слеш-команди +- **Середньо**: Субагенти, Пам'ять +- **Просунуто**: Навички, Хуки +- **Комплексно**: Плагіни + +--- + +## 🎓 Навчальний шлях + +### День 1 + +```bash +# Прочитати огляд +cat README.md + +# Встановити команду +cp 01-slash-commands/optimize.md .claude/commands/ + +# Спробувати +/optimize +``` + +### Дні 2-3 + +```bash +# Налаштувати пам'ять +cp 02-memory/project-CLAUDE.md ./CLAUDE.md +vim CLAUDE.md + +# Встановити субагента +cp 04-subagents/code-reviewer.md .claude/agents/ +``` + +### Дні 4-5 + +```bash +# Налаштувати MCP +export GITHUB_TOKEN="your_token" +cp 05-mcp/github-mcp.json .mcp.json + +# Спробувати MCP-команди +/mcp__github__list_prs +``` + +### Тиждень 2 + +```bash +# Встановити навичку +cp -r 03-skills/code-review ~/.claude/skills/ + +# Дозвольте автовиклик +# Просто скажіть: "Review this code for issues" +``` + +### Тиждень 3+ + +```bash +# Встановити повний плагін +/plugin install pr-review + +# Використати вбудовані функції +/review-pr +/check-security +/check-tests +``` + +--- + +## Нові функції (березень 2026) + +| Функція | Опис | Використання | +|---------|------|-------------| +| **Auto Mode** | Повністю автономна робота з фоновим класифікатором | Прапорець `--enable-auto-mode`, `Shift+Tab` для зміни режимів | +| **Канали** | Інтеграція з Discord та Telegram | Прапорець `--channels`, боти Discord/Telegram | +| **Голосовий ввід** | Голосові команди та контекст для Claude | Команда `/voice` | +| **Хуки (26 подій)** | Розширена система хуків з 4 типами | Типи: command, http, prompt, agent | +| **MCP Elicitation** | MCP-сервери можуть запитувати ввід під час виконання | Автозапит при потребі сервера | +| **Plugin LSP** | Підтримка Language Server Protocol для плагінів | `userConfig`, змінна `${CLAUDE_PLUGIN_DATA}` | +| **Віддалене керування** | Керування Claude Code через WebSocket API | `claude --remote` для зовнішніх інтеграцій | +| **Веб-сесії** | Браузерний інтерфейс Claude Code | `claude web` для запуску | +| **Десктопний застосунок** | Нативний десктопний застосунок | Завантаження з claude.ai/download | +| **Список завдань** | Управління фоновими завданнями | `/task list`, `/task status ` | +| **Автопам'ять** | Автоматичне збереження з розмов | Claude автозберігає контекст у CLAUDE.md | +| **Git Worktrees** | Ізольовані робочі простори для паралельної розробки | `/worktree` для створення | +| **Вибір моделі** | Перемикання між Sonnet 4.6 та Opus 4.6 | `/model` або прапорець `--model` | +| **Команди агентів** | Координація кількох агентів | Увімкнути з `CLAUDE_AGENT_TEAMS=1` | +| **Заплановані завдання** | Повторювані завдання з `/loop` | `/loop 5m /command` або CronCreate | +| **Інтеграція з Chrome** | Автоматизація браузера | Прапорець `--chrome` або `/chrome` | +| **Кастомізація клавіатури** | Налаштування клавіш | Команда `/keybindings` | + +--- + +## Поради та хитрощі + +### Кастомізація + +- Почніть з прикладів як є +- Модифікуйте під ваші потреби +- Тестуйте перед поширенням в команді +- Тримайте конфігурації під контролем версій + +### Найкращі практики + +- Використовуйте пам'ять для командних стандартів +- Використовуйте плагіни для комплексних процесів +- Використовуйте субагентів для складних завдань +- Використовуйте слеш-команди для швидких завдань + +### Усунення неполадок + +```bash +# Перевірити розташування файлів +ls -la .claude/commands/ +ls -la .claude/agents/ + +# Перевірити YAML-синтаксис +head -20 .claude/agents/code-reviewer.md + +# Перевірити MCP-з'єднання +echo $GITHUB_TOKEN +``` + +--- + +## 📊 Матриця функцій + +| Потреба | Використовуйте | Приклад | +|---------|---------------|---------| +| Швидкий ярлик | Слеш-команда (55+) | `01-slash-commands/optimize.md` | +| Командні стандарти | Пам'ять | `02-memory/project-CLAUDE.md` | +| Автоматичний процес | Навичка | `03-skills/code-review/` | +| Спеціалізоване завдання | Субагент | `04-subagents/code-reviewer.md` | +| Зовнішні дані | MCP (+ Elicitation) | `05-mcp/github-mcp.json` | +| Автоматизація подій | Хук (26 подій, 4 типи) | `06-hooks/pre-commit.sh` | +| Комплексне рішення | Плагін (+ LSP) | `07-plugins/pr-review/` | +| Безпечний експеримент | Контрольна точка | `08-checkpoints/checkpoint-examples.md` | +| Повна автономія | Auto Mode | `--enable-auto-mode` або `Shift+Tab` | +| Чат-інтеграції | Канали | `--channels` (Discord, Telegram) | +| CI/CD-пайплайн | CLI | `10-cli/README.md` | + +--- + +## 🔗 Швидкі посилання + +- **Головний посібник**: `README.md` +- **Повний покажчик**: `INDEX.md` +- **Каталог**: `CATALOG.md` +- **Оригінальний посібник**: `claude_concepts_guide.md` + +--- + +## 📞 Поширені запитання + +**П: Що обрати?** +В: Почніть зі слеш-команд, додавайте функції за потребою. + +**П: Чи можна комбінувати функції?** +В: Так! Вони працюють разом. Пам'ять + Команди + MCP = потужна зв'язка. + +**П: Як поділитися з командою?** +В: Закомітьте каталог `.claude/` до git. + +**П: А що з секретами?** +В: Використовуйте змінні оточення, ніколи не хардкодьте. + +**П: Чи можна змінювати приклади?** +В: Безумовно! Це шаблони для кастомізації. + +--- + +## ✅ Чекліст + +Чекліст для початку роботи: + +- [ ] Прочитати `README.md` +- [ ] Встановити 1 слеш-команду +- [ ] Спробувати команду +- [ ] Створити `CLAUDE.md` проекту +- [ ] Встановити 1 субагента +- [ ] Налаштувати 1 MCP-інтеграцію +- [ ] Встановити 1 навичку +- [ ] Спробувати повний плагін +- [ ] Кастомізувати під свої потреби +- [ ] Поділитися з командою + +--- + +**Швидкий старт**: `cat README.md` + +**Повний покажчик**: `cat INDEX.md` + +**Ця картка**: Тримайте під рукою для швидкого довідника! + +--- + +**Останнє оновлення**: 9 квітня 2026 +**Версія Claude Code**: 2.1.97 diff --git a/uk/README.md b/uk/README.md new file mode 100644 index 0000000..eb3adb1 --- /dev/null +++ b/uk/README.md @@ -0,0 +1,662 @@ + + + + + + + Claude How To + + +🌐 **Language / Мова:** [English](../README.md) | [Tiếng Việt](../vi/README.md) | [中文](../zh/README.md) | [Українська](README.md) + +# Опануй Claude Code за вихідні + +Від простого введення `claude` до оркестрації агентів, хуків, навичок та MCP-серверів — з візуальними туторіалами, готовими шаблонами та керованим навчальним шляхом. + +**[Почни за 15 хвилин](#почни-за-15-хвилин)** | **[Визнач свій рівень](#не-знаєш-з-чого-почати)** | **[Каталог функцій](CATALOG.md)** + +--- + +## Зміст + +- [Проблема](#проблема) +- [Як Claude How To вирішує це](#як-claude-how-to-вирішує-це) +- [Як це працює](#як-це-працює) +- [Не знаєш з чого почати?](#не-знаєш-з-чого-почати) +- [Почни за 15 хвилин](#почни-за-15-хвилин) +- [Що можна побудувати?](#що-можна-побудувати) +- [FAQ](#faq) +- [Внесок](#внесок) +- [Ліцензія](#ліцензія) + +--- + +## Проблема + +Ви встановили Claude Code. Виконали кілька промптів. Що далі? + +- **Офіційна документація описує функції — але не показує як їх комбінувати.** Ви знаєте, що слеш-команди існують, але не знаєте як поєднати їх з хуками, пам'яттю та субагентами в робочий процес, що реально економить години. +- **Немає чіткого навчального шляху.** Чи вивчати MCP перед хуками? Навички перед субагентами? В результаті ви переглядаєте все і не опановуєте нічого. +- **Приклади занадто базові.** "Hello world" слеш-команда не допоможе побудувати продакшен-пайплайн код-рев'ю, який використовує пам'ять, делегує спеціалізованим агентам та автоматично запускає перевірки безпеки. + +Ви використовуєте лише 10% потужності Claude Code — і не знаєте, чого не знаєте. + +--- + +## Як Claude How To вирішує це + +Це не черговий довідник функцій. Це **структурований, візуальний, заснований на прикладах довідник**, що навчає використовувати кожну функцію Claude Code з реальними шаблонами, які можна скопіювати у ваш проєкт вже сьогодні. + +| | Офіційна документація | Цей довідник | +|--|----------------------|-------------| +| **Формат** | Довідкова документація | Візуальні туторіали з Mermaid-діаграмами | +| **Глибина** | Опис функцій | Як працює під капотом | +| **Приклади** | Базові фрагменти | Готові до продакшену шаблони для негайного використання | +| **Структура** | Організовано за функціями | Прогресивний навчальний шлях (від початківця до просунутого) | +| **Онбординг** | Самостійне вивчення | Керована дорожня карта з оцінками часу | +| **Самооцінка** | Відсутня | Інтерактивні тести для пошуку прогалин та побудови персоналізованого шляху | + +### Що ви отримаєте: + +- **10 навчальних модулів**, що охоплюють кожну функцію Claude Code — від слеш-команд до кастомних команд агентів +- **Готові конфігурації** — слеш-команди, шаблони CLAUDE.md, скрипти хуків, конфіги MCP, визначення субагентів та повні пакети плагінів +- **Mermaid-діаграми**, що показують як кожна функція працює всередині, щоб ви розуміли *чому*, а не лише *як* +- **Керований навчальний шлях**, що проведе від початківця до досвідченого користувача за 11-13 годин +- **Вбудована самооцінка** — запустіть `/self-assessment` або `/lesson-quiz hooks` прямо у Claude Code для виявлення прогалин + +**[Почати навчальний шлях ->](LEARNING-ROADMAP.md)** + +--- + +## Як це працює + +### 1. Визначте свій рівень + +Пройдіть [тест самооцінки](LEARNING-ROADMAP.md#-визначте-свій-рівень) або запустіть `/self-assessment` у Claude Code. Отримайте персоналізовану дорожню карту на основі того, що ви вже знаєте. + +### 2. Слідуйте керованому шляху + +Проходьте 10 модулів по порядку — кожен будує на попередньому. Копіюйте шаблони безпосередньо у свій проєкт під час навчання. + +### 3. Комбінуйте функції в робочі процеси + +Справжня потужність — у комбінуванні функцій. Навчіться поєднувати слеш-команди + пам'ять + субагенти + хуки в автоматизовані пайплайни для код-рев'ю, розгортань та генерації документації. + +### 4. Перевірте розуміння + +Запустіть `/lesson-quiz [тема]` після кожного модуля. Тест точно вказує, що ви пропустили, щоб швидко заповнити прогалини. + +**[Почни за 15 хвилин](#почни-за-15-хвилин)** + +--- + +## Не знаєш з чого почати? + +Пройдіть самооцінку або оберіть свій рівень: + +| Рівень | Ви вмієте... | Почніть тут | Час | +|--------|-------------|-------------|-----| +| **Початківець** | Запустити Claude Code та спілкуватись | [Слеш-команди](01-slash-commands/) | ~2.5 години | +| **Середній** | Використовувати CLAUDE.md та кастомні команди | [Навички](03-skills/) | ~3.5 години | +| **Просунутий** | Конфігурувати MCP-сервери та хуки | [Просунуті функції](09-advanced-features/) | ~5 годин | + +**Повний навчальний шлях з усіма 10 модулями:** + +| Порядок | Модуль | Рівень | Час | +|---------|--------|--------|-----| +| 1 | [Слеш-команди](01-slash-commands/) | Початківець | 30 хв | +| 2 | [Пам'ять](02-memory/) | Початківець+ | 45 хв | +| 3 | [Контрольні точки](08-checkpoints/) | Середній | 45 хв | +| 4 | [Основи CLI](10-cli/) | Початківець+ | 30 хв | +| 5 | [Навички](03-skills/) | Середній | 1 год | +| 6 | [Хуки](06-hooks/) | Середній | 1 год | +| 7 | [MCP](05-mcp/) | Середній+ | 1 год | +| 8 | [Субагенти](04-subagents/) | Середній+ | 1.5 год | +| 9 | [Просунуті функції](09-advanced-features/) | Просунутий | 2-3 год | +| 10 | [Плагіни](07-plugins/) | Просунутий | 2 год | + +**[Повний навчальний план ->](LEARNING-ROADMAP.md)** + +--- + +## Почни за 15 хвилин + +```bash +# 1. Клонувати довідник +git clone https://github.com/luongnv89/claude-howto.git +cd claude-howto + +# 2. Скопіювати першу слеш-команду +mkdir -p /path/to/your-project/.claude/commands +cp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/ + +# 3. Спробувати — у Claude Code введіть: +# /optimize + +# 4. Готові до більшого? Налаштуйте пам'ять проєкту: +cp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md + +# 5. Встановіть навичку: +cp -r 03-skills/code-review ~/.claude/skills/ +``` + +Хочете повне налаштування? Ось **необхідне за 1 годину**: + +```bash +# Слеш-команди (15 хв) +cp 01-slash-commands/*.md .claude/commands/ + +# Пам'ять проєкту (15 хв) +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Встановити навичку (15 хв) +cp -r 03-skills/code-review ~/.claude/skills/ + +# Ціль на вихідні: додати хуки, субагенти, MCP та плагіни +# Слідуйте навчальному шляху для керованого налаштування +``` + +--- + +## Що можна побудувати? + +| Сценарій | Функції, які ви поєднаєте | +|----------|--------------------------| +| **Автоматичне код-рев'ю** | Слеш-команди + Субагенти + Пам'ять + MCP | +| **Онбординг команди** | Пам'ять + Слеш-команди + Плагіни | +| **Автоматизація CI/CD** | CLI + Хуки + Фонові завдання | +| **Генерація документації** | Навички + Субагенти + Плагіни | +| **Аудит безпеки** | Субагенти + Навички + Хуки (режим читання) | +| **DevOps-пайплайни** | Плагіни + MCP + Хуки + Фонові завдання | +| **Складний рефакторинг** | Контрольні точки + Режим планування + Хуки | + +--- + +## FAQ + +**Це безкоштовно?** +Так. Ліцензія MIT, безкоштовно назавжди. Використовуйте в особистих проєктах, на роботі, у команді — без обмежень, крім включення ліцензії. + +**Це підтримується?** +Активно. Довідник синхронізується з кожним релізом Claude Code. Поточна версія: v2.3.0 (квітень 2026), сумісна з Claude Code 2.1+. + +**Чим це відрізняється від офіційної документації?** +Офіційна документація — це довідник функцій. Цей довідник — туторіал з діаграмами, готовими до продакшену шаблонами та прогресивним навчальним шляхом. Вони доповнюють одне одного — починайте тут для навчання, звертайтесь до офіційних документів коли потрібні деталі. + +**Скільки часу потрібно пройти все?** +11-13 годин для повного шляху. Але ви отримаєте цінність за 15 хвилин — просто скопіюйте шаблон слеш-команди та спробуйте. + +**Чи працює це з Claude Sonnet / Haiku / Opus?** +Так. Усі шаблони працюють з Claude Sonnet 4.6, Claude Opus 4.6 та Claude Haiku 4.5. + +**Чи можна долучитися?** +Звичайно. Див. [CONTRIBUTING.md](CONTRIBUTING.md) для настанов. Ми вітаємо нові приклади, виправлення, покращення документації та шаблони спільноти. + +**Чи можна читати офлайн?** +Так. Запустіть `uv run scripts/build_epub.py` для генерації EPUB-книги з усім контентом та відрендереними діаграмами. + +--- + +## Почніть опановувати Claude Code сьогодні + +Ви вже встановили Claude Code. Єдине, що відділяє вас від 10-кратного підвищення продуктивності — знання як його використовувати. Цей довідник дає вам структурований шлях, візуальні пояснення та готові шаблони для цього. + +Ліцензія MIT. Безкоштовно назавжди. Клонуйте, форкніть, зробіть своїм. + +**[Почати навчальний шлях ->](LEARNING-ROADMAP.md)** | **[Каталог функцій](CATALOG.md)** | **[Почни за 15 хвилин](#почни-за-15-хвилин)** + +--- + +
+Швидка навігація — Усі функції + +| Функція | Опис | Папка | +|---------|------|-------| +| **Каталог функцій** | Повний довідник з командами встановлення | [CATALOG.md](CATALOG.md) | +| **Слеш-команди** | Ярлики, ініційовані користувачем | [01-slash-commands/](01-slash-commands/) | +| **Пам'ять** | Постійний контекст | [02-memory/](02-memory/) | +| **Навички** | Багаторазові можливості | [03-skills/](03-skills/) | +| **Субагенти** | Спеціалізовані AI-помічники | [04-subagents/](04-subagents/) | +| **Протокол MCP** | Доступ до зовнішніх інструментів | [05-mcp/](05-mcp/) | +| **Хуки** | Автоматизація на основі подій | [06-hooks/](06-hooks/) | +| **Плагіни** | Пакетні функції | [07-plugins/](07-plugins/) | +| **Контрольні точки** | Знімки сесій та відкат | [08-checkpoints/](08-checkpoints/) | +| **Просунуті функції** | Планування, мислення, фонові завдання | [09-advanced-features/](09-advanced-features/) | +| **Довідник CLI** | Команди, прапорці та опції | [10-cli/](10-cli/) | + +
+ +
+Порівняння функцій + +| Функція | Виклик | Постійність | Найкраще для | +|---------|--------|------------|-------------| +| **Слеш-команди** | Ручний (`/cmd`) | Лише сесія | Швидкі ярлики | +| **Пам'ять** | Авто-завантаження | Між сесіями | Довгострокове навчання | +| **Навички** | Авто-виклик | Файлова система | Автоматизовані процеси | +| **Субагенти** | Авто-делегування | Ізольований контекст | Розподіл завдань | +| **Протокол MCP** | Авто-запити | Реальний час | Доступ до живих даних | +| **Хуки** | За подіями | Налаштовувані | Автоматизація та валідація | +| **Плагіни** | Одна команда | Усі функції | Комплексні рішення | +| **Контрольні точки** | Ручний/Авто | Сесійні | Безпечне експериментування | +| **Режим планування** | Ручний/Авто | Фаза плану | Складні реалізації | +| **Фонові завдання** | Ручний | Час завдання | Тривалі операції | +| **Довідник CLI** | Термінальні команди | Сесія/Скрипт | Автоматизація та скриптинг | + +
+ +
+Швидкий довідник встановлення + +```bash +# Слеш-команди +cp 01-slash-commands/*.md .claude/commands/ + +# Пам'ять +cp 02-memory/project-CLAUDE.md ./CLAUDE.md + +# Навички +cp -r 03-skills/code-review ~/.claude/skills/ + +# Субагенти +cp 04-subagents/*.md .claude/agents/ + +# MCP +export GITHUB_TOKEN="token" +claude mcp add github -- npx -y @modelcontextprotocol/server-github + +# Хуки +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh + +# Плагіни +/plugin install pr-review + +# Контрольні точки (увімкнені за замовчуванням) +# Див. 08-checkpoints/README.md + +# Просунуті функції (налаштування в settings) +# Див. 09-advanced-features/config-examples.json + +# CLI (не потребує встановлення) +# Див. 10-cli/README.md +``` + +
+ +
+01. Слеш-команди + +**Розташування**: [01-slash-commands/](01-slash-commands/) + +**Що**: Ярлики, ініційовані користувачем, збережені як Markdown-файли + +**Приклади**: +- `optimize.md` — Аналіз оптимізації коду +- `pr.md` — Підготовка pull request +- `generate-api-docs.md` — Генератор API-документації + +**Встановлення**: +```bash +cp 01-slash-commands/*.md /path/to/project/.claude/commands/ +``` + +**Використання**: +``` +/optimize +/pr +/generate-api-docs +``` + +
+ +
+02. Пам'ять + +**Розташування**: [02-memory/](02-memory/) + +**Що**: Постійний контекст між сесіями + +**Приклади**: +- `project-CLAUDE.md` — Командні стандарти проєкту +- `directory-api-CLAUDE.md` — Правила для каталогу +- `personal-CLAUDE.md` — Персональні налаштування + +**Встановлення**: +```bash +# Пам'ять проєкту +cp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md + +# Пам'ять каталогу +cp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md + +# Персональна пам'ять +cp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md +``` + +**Використання**: Автоматично завантажується Claude + +
+ +
+03. Навички + +**Розташування**: [03-skills/](03-skills/) + +**Що**: Багаторазові можливості з автовикликом, інструкціями та скриптами + +**Приклади**: +- `code-review/` — Комплексне код-рев'ю зі скриптами +- `brand-voice/` — Перевірка відповідності голосу бренду +- `doc-generator/` — Генератор API-документації + +**Встановлення**: +```bash +# Персональні навички +cp -r 03-skills/code-review ~/.claude/skills/ + +# Навички проєкту +cp -r 03-skills/code-review /path/to/project/.claude/skills/ +``` + +**Використання**: Автоматично викликаються за потреби + +
+ +
+04. Субагенти + +**Розташування**: [04-subagents/](04-subagents/) + +**Що**: Спеціалізовані AI-помічники з ізольованими контекстами та кастомними промптами + +**Приклади**: +- `code-reviewer.md` — Комплексний аналіз якості коду +- `test-engineer.md` — Стратегія тестування та покриття +- `documentation-writer.md` — Технічна документація +- `secure-reviewer.md` — Рев'ю безпеки (тільки читання) +- `implementation-agent.md` — Повна реалізація функцій + +**Встановлення**: +```bash +cp 04-subagents/*.md /path/to/project/.claude/agents/ +``` + +**Використання**: Автоматичне делегування головним агентом + +
+ +
+05. Протокол MCP + +**Розташування**: [05-mcp/](05-mcp/) + +**Що**: Model Context Protocol для доступу до зовнішніх інструментів та API + +**Приклади**: +- `github-mcp.json` — Інтеграція з GitHub +- `database-mcp.json` — Запити до бази даних +- `filesystem-mcp.json` — Файлові операції +- `multi-mcp.json` — Кілька MCP-серверів + +**Встановлення**: +```bash +# Встановити змінні оточення +export GITHUB_TOKEN="your_token" +export DATABASE_URL="postgresql://..." + +# Додати MCP-сервер через CLI +claude mcp add github -- npx -y @modelcontextprotocol/server-github +``` + +**Використання**: MCP-інструменти автоматично доступні Claude після налаштування + +
+ +
+06. Хуки + +**Розташування**: [06-hooks/](06-hooks/) + +**Що**: Shell-команди на основі подій, що виконуються автоматично у відповідь на події Claude Code + +**Приклади**: +- `format-code.sh` — Автоформатування коду перед записом +- `pre-commit.sh` — Запуск тестів перед комітами +- `security-scan.sh` — Сканування на проблеми безпеки +- `log-bash.sh` — Логування всіх bash-команд +- `validate-prompt.sh` — Валідація промптів +- `notify-team.sh` — Надсилання сповіщень + +**Встановлення**: +```bash +mkdir -p ~/.claude/hooks +cp 06-hooks/*.sh ~/.claude/hooks/ +chmod +x ~/.claude/hooks/*.sh +``` + +**Використання**: Хуки виконуються автоматично за подіями + +**Типи хуків** (4 типи, 25 подій): +- **Хуки інструментів**: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` +- **Хуки сесій**: `SessionStart`, `SessionEnd`, `Stop`, `StopFailure`, `SubagentStart`, `SubagentStop` +- **Хуки завдань**: `UserPromptSubmit`, `TaskCompleted`, `TaskCreated`, `TeammateIdle` +- **Хуки життєвого циклу**: `ConfigChange`, `CwdChanged`, `FileChanged`, `PreCompact`, `PostCompact`, `WorktreeCreate`, `WorktreeRemove`, `Notification`, `InstructionsLoaded`, `Elicitation`, `ElicitationResult` + +
+ +
+07. Плагіни + +**Розташування**: [07-plugins/](07-plugins/) + +**Що**: Пакетні набори команд, агентів, MCP та хуків + +**Приклади**: +- `pr-review/` — Повний процес рев'ю PR +- `devops-automation/` — Розгортання та моніторинг +- `documentation/` — Генерація документації + +**Встановлення**: +```bash +/plugin install pr-review +/plugin install devops-automation +/plugin install documentation +``` + +**Використання**: Використовуйте пакетні слеш-команди та функції + +
+ +
+08. Контрольні точки та відкат + +**Розташування**: [08-checkpoints/](08-checkpoints/) + +**Що**: Збереження стану розмови та повернення до попередніх точок для дослідження різних підходів + +**Ключові поняття**: +- **Контрольна точка**: Знімок стану розмови +- **Відкат**: Повернення до попередньої контрольної точки +- **Точка розгалуження**: Дослідження кількох підходів з однієї точки + +**Використання**: +``` +# Контрольні точки створюються автоматично з кожним промптом +# Для відкату натисніть Esc двічі або: +/rewind + +# Потім оберіть: +# 1. Відновити код і розмову +# 2. Відновити розмову +# 3. Відновити код +# 4. Підсумувати звідси +# 5. Скасувати +``` + +
+ +
+09. Просунуті функції + +**Розташування**: [09-advanced-features/](09-advanced-features/) + +**Що**: Просунуті можливості для складних робочих процесів та автоматизації + +**Включає**: +- **Режим планування** — Детальні плани реалізації перед кодуванням +- **Розширене мислення** — Глибоке міркування для складних проблем (перемикання через `Alt+T` / `Option+T`) +- **Фонові завдання** — Тривалі операції без блокування +- **Режими дозволів** — `default`, `acceptEdits`, `plan`, `dontAsk`, `bypassPermissions` +- **Headless-режим** — Claude Code у CI/CD: `claude -p "Run tests and generate report"` +- **Управління сесіями** — `/resume`, `/rename`, `/fork`, `claude -c`, `claude -r` +- **Конфігурація** — Налаштування поведінки в `~/.claude/settings.json` + +Див. [config-examples.json](09-advanced-features/config-examples.json) для повних конфігурацій. + +
+ +
+10. Довідник CLI + +**Розташування**: [10-cli/](10-cli/) + +**Що**: Повний довідник інтерфейсу командного рядка Claude Code + +**Швидкі приклади**: +```bash +# Інтерактивний режим +claude "explain this project" + +# Print mode (неінтерактивний) +claude -p "review this code" + +# Обробка вмісту файлу +cat error.log | claude -p "explain this error" + +# JSON-вивід для скриптів +claude -p --output-format json "list functions" + +# Відновлення сесії +claude -r "feature-auth" "continue implementation" +``` + +**Сценарії**: Інтеграція CI/CD-пайплайнів, автоматизація скриптів, пакетна обробка, багатосесійні процеси + +
+ +
+Приклади робочих процесів + +### Повний процес код-рев'ю + +```markdown +# Використовує: Слеш-команди + Субагенти + Пам'ять + MCP + +User: /review-pr + +Claude: +1. Завантажує пам'ять проєкту (стандарти кодування) +2. Отримує PR через GitHub MCP +3. Делегує субагенту code-reviewer +4. Делегує субагенту test-engineer +5. Синтезує знахідки +6. Надає комплексний огляд +``` + +### Автоматична документація + +```markdown +# Використовує: Навички + Субагенти + Пам'ять + +User: "Generate API documentation for the auth module" + +Claude: +1. Завантажує пам'ять проєкту (стандарти документації) +2. Виявляє запит на генерацію документації +3. Автоматично викликає навичку doc-generator +4. Делегує субагенту api-documenter +5. Створює комплексну документацію з прикладами +``` + +### DevOps-розгортання + +```markdown +# Використовує: Плагіни + MCP + Хуки + +User: /deploy production + +Claude: +1. Запускає pre-deploy хук (валідація середовища) +2. Делегує субагенту deployment-specialist +3. Виконує розгортання через Kubernetes MCP +4. Моніторить прогрес +5. Запускає post-deploy хук (перевірки стану) +6. Звітує про статус +``` + +
+ +
+Найкращі практики + +### Робіть +- Починайте просто зі слеш-команд +- Додавайте функції поступово +- Використовуйте пам'ять для командних стандартів +- Тестуйте конфігурації локально спочатку +- Документуйте кастомні реалізації +- Контролюйте версії проєктних конфігурацій +- Діліться плагінами з командою + +### Не робіть +- Не створюйте надлишкових функцій +- Не хардкодьте облікові дані +- Не пропускайте документацію +- Не ускладнюйте прості завдання +- Не ігноруйте найкращі практики безпеки +- Не комітьте чутливі дані + +
+ +
+Усунення неполадок + +### Функція не завантажується +1. Перевірте розташування та назву файлу +2. Перевірте синтаксис YAML frontmatter +3. Перевірте дозволи файлу +4. Перевірте сумісність з версією Claude Code + +### MCP-з'єднання не вдалося +1. Перевірте змінні оточення +2. Перевірте встановлення MCP-сервера +3. Протестуйте облікові дані +4. Перевірте мережеве з'єднання + +### Субагент не делегує +1. Перевірте дозволи інструментів +2. Перевірте чіткість опису агента +3. Перевірте складність завдання +4. Протестуйте агента окремо + +
+ +--- + +## Внесок + +Ми вітаємо внески! Будь ласка, ознайомтесь з [Настановами для контриб'юторів](CONTRIBUTING.md) для деталей. + +--- + +## Ліцензія + +Ліцензія MIT — див. [LICENSE](LICENSE). Вільне використання, модифікація та розповсюдження. Єдина вимога — включити повідомлення про ліцензію. + +--- + +**Останнє оновлення**: Квітень 2026 +**Версія Claude Code**: 2.1.97 +**Сумісні моделі**: Claude Sonnet 4.6, Claude Opus 4.6, Claude Haiku 4.5 diff --git a/uk/RELEASE_NOTES.md b/uk/RELEASE_NOTES.md new file mode 100644 index 0000000..0055ec6 --- /dev/null +++ b/uk/RELEASE_NOTES.md @@ -0,0 +1,11 @@ +## v2.2.0 — 2026-03-26 + +### Bug Fixes + +- Remove dead marketplace link failing CI link checks (3fdf0d6) +- Add `sandboxed` and `pycache` to cSpell dictionary (dc64618) + +**Full Changelog**: https://github.com/luongnv89/claude-howto/compare/v2.1.0...v2.1.1 + +--- +**Last Updated**: April 9, 2026 diff --git a/uk/SECURITY.md b/uk/SECURITY.md new file mode 100644 index 0000000..d079c96 --- /dev/null +++ b/uk/SECURITY.md @@ -0,0 +1,338 @@ + + + + +# Політика безпеки + +## Огляд + +Безпека проєкту Claude How To є важливою для нас. Цей документ описує наші практики безпеки та пояснює, як відповідально повідомляти про вразливості. + +## Підтримувані версії + +Ми надаємо оновлення безпеки для наступних версій: + +| Версія | Статус | Підтримка до | +|--------|--------|--------------| +| Остання (main) | ✅ Активна | Поточна + 6 місяців | +| Релізи 1.x | ✅ Активна | До наступної мажорної версії | + +**Примітка**: Як освітній проєкт-довідник, ми зосереджуємося на підтримці актуальних найкращих практик та безпеки документації, а не на традиційній підтримці версій. Оновлення застосовуються безпосередньо до гілки main. + +## Практики безпеки + +### Безпека коду + +1. **Управління залежностями** + - Усі Python-залежності зафіксовані в `requirements.txt` + - Регулярні оновлення через dependabot та ручний перегляд + - Сканування безпеки за допомогою Bandit при кожному коміті + - Pre-commit хуки для перевірок безпеки + +2. **Якість коду** + - Лінтинг за допомогою Ruff виявляє поширені проблеми + - Перевірка типів за допомогою mypy запобігає вразливостям, пов'язаним з типами + - Pre-commit хуки забезпечують дотримання стандартів + - Усі зміни переглядаються перед злиттям + +3. **Контроль доступу** + - Захист гілки `main` + - Обов'язковий рев'ю перед мерджем + - Статусні перевірки повинні пройти перед мерджем + - Обмежений доступ на запис до репозиторію + +### Безпека документації + +1. **Ніяких секретів у прикладах** + - Усі API-ключі в прикладах є заповнювачами + - Облікові дані ніколи не захардкоджені + - Файли `.env.example` показують необхідні змінні + - Чіткі попередження щодо управління секретами + +2. **Найкращі практики безпеки** + - Приклади демонструють безпечні патерни + - Попередження безпеки виділені в документації + - Посилання на офіційні гайди безпеки + - Обробка облікових даних обговорюється у відповідних розділах + +3. **Перегляд контенту** + - Вся документація перевіряється на проблеми безпеки + - Міркування безпеки в настановах для контриб'юторів + - Валідація зовнішніх посилань та посилань + +### Безпека залежностей + +1. **Сканування** + - Bandit сканує весь Python-код на вразливості + - Перевірка вразливостей залежностей через GitHub security alerts + - Регулярні ручні аудити безпеки + +2. **Оновлення** + - Патчі безпеки застосовуються оперативно + - Мажорні версії оцінюються ретельно + - Changelog включає оновлення, пов'язані з безпекою + +3. **Прозорість** + - Оновлення безпеки задокументовані в комітах + - Розкриття вразливостей обробляється відповідально + - Публічні рекомендації безпеки за потреби + +## Повідомлення про вразливість + +### Проблеми безпеки, які нас цікавлять + +Ми цінуємо повідомлення про: +- **Вразливості коду** в скриптах або прикладах +- **Вразливості залежностей** у Python-пакетах +- **Проблеми криптографії** в будь-яких прикладах коду +- **Недоліки автентифікації/авторизації** в документації +- **Ризики витоку даних** у прикладах конфігурації +- **Вразливості ін'єкцій** (SQL, команди тощо) +- **Проблеми SSRF/XXE/обхід шляхів** + +### Проблеми безпеки поза межами + +Це виходить за рамки цього проєкту: +- Вразливості в самому Claude Code (повідомляйте Anthropic) +- Проблеми із зовнішніми сервісами або бібліотеками (повідомляйте upstream) +- Соціальна інженерія або навчання користувачів (не стосується цього довідника) +- Теоретичні вразливості без підтвердження концепції +- Вразливості в залежностях, повідомлені через офіційні канали + +## Як повідомити + +### Приватне повідомлення (рекомендовано) + +**Для чутливих проблем безпеки використовуйте приватне повідомлення про вразливості GitHub:** + +1. Перейдіть: https://github.com/luongnv89/claude-howto/security/advisories +2. Натисніть "Report a vulnerability" +3. Заповніть деталі вразливості +4. Вкажіть: + - Чіткий опис вразливості + - Уражений компонент (файл, розділ, приклад) + - Потенційний вплив + - Кроки для відтворення (якщо можливо) + - Запропоноване виправлення (якщо є) + +**Що відбувається далі:** +- Ми підтвердимо отримання протягом 48 годин +- Ми дослідимо та оцінимо серйозність +- Ми працюватимемо з вами над розробкою виправлення +- Ми узгодимо графік розкриття +- Ми вкажемо вас у рекомендації безпеки (якщо ви не бажаєте анонімності) + +### Публічне повідомлення + +Для нечутливих проблем або тих, що вже є публічними: + +1. **Створіть GitHub Issue** з міткою `security` +2. Вкажіть: + - Назва: `[SECURITY]` з коротким описом + - Детальний опис + - Уражений файл або розділ + - Потенційний вплив + - Запропоноване виправлення + +## Процес реагування на вразливості + +### Оцінка (24 години) + +1. Ми підтверджуємо отримання повідомлення +2. Ми оцінюємо серйозність за [CVSS v3.1](https://www.first.org/cvss/v3.1/specification-document) +3. Ми визначаємо, чи входить це в область застосування +4. Ми зв'язуємося з вами з початковою оцінкою + +### Розробка (1-7 днів) + +1. Ми розробляємо виправлення +2. Ми переглядаємо та тестуємо виправлення +3. Ми створюємо рекомендацію безпеки +4. Ми готуємо нотатки до випуску + +### Розкриття (залежно від серйозності) + +**Критична (CVSS 9.0-10.0)** +- Виправлення випускається негайно +- Публічна рекомендація видається +- 24-годинне попереднє повідомлення репортерам + +**Висока (CVSS 7.0-8.9)** +- Виправлення випускається протягом 48-72 годин +- 5-денне попереднє повідомлення репортерам +- Публічна рекомендація при випуску + +**Середня (CVSS 4.0-6.9)** +- Виправлення випускається в наступному регулярному оновленні +- Публічна рекомендація при випуску + +**Низька (CVSS 0.1-3.9)** +- Виправлення включається в наступне регулярне оновлення +- Рекомендація при випуску + +### Публікація + +Ми публікуємо рекомендації безпеки, що включають: +- Опис вразливості +- Уражені компоненти +- Оцінку серйозності (CVSS-бал) +- Версію виправлення +- Обхідні рішення (якщо є) +- Подяку репортеру (з дозволу) + +## Найкращі практики для репортерів + +### Перед повідомленням + +- **Перевірте проблему**: Чи можете ви відтворити її стабільно? +- **Шукайте існуючі issues**: Чи вже повідомлено про це? +- **Перевірте документацію**: Чи є настанови щодо безпечного використання? +- **Тестуйте виправлення**: Чи працює ваше запропоноване виправлення? + +### При повідомленні + +- **Будьте конкретними**: Вказуйте точні шляхи файлів та номери рядків +- **Додавайте контекст**: Чому це проблема безпеки? +- **Покажіть вплив**: Що міг би зробити зловмисник? +- **Надайте кроки**: Як ми можемо відтворити? +- **Запропонуйте виправлення**: Як би ви це виправили? + +### Після повідомлення + +- **Будьте терплячими**: Ми маємо обмежені ресурси +- **Будьте на зв'язку**: Відповідайте на подальші запитання швидко +- **Зберігайте конфіденційність**: Не розголошуйте публічно до виправлення +- **Дотримуйтесь координації**: Слідуйте нашому графіку розкриття + +## Заголовки безпеки та конфігурація + +### Безпека репозиторію + +- **Захист гілок**: Основна гілка потребує 2 схвалень для змін +- **Статусні перевірки**: Усі CI/CD перевірки повинні пройти +- **CODEOWNERS**: Призначені рецензенти для ключових файлів +- **Підписані коміти**: Рекомендовано для контриб'юторів + +### Безпека розробки + +```bash +# Install pre-commit hooks +pre-commit install + +# Run security scans locally +bandit -c pyproject.toml -r scripts/ +mypy scripts/ --ignore-missing-imports +ruff check scripts/ +``` + +### Безпека залежностей + +```bash +# Check for known vulnerabilities +pip install safety +safety check + +# Or use pip-audit +pip install pip-audit +pip-audit +``` + +## Настанови безпеки для контриб'юторів + +### При написанні прикладів + +1. **Ніколи не захардкоджуйте секрети** + ```python + # ❌ Bad + api_key = "sk-1234567890" + + # ✅ Good + api_key = os.getenv("API_KEY") + ``` + +2. **Попереджайте про наслідки безпеки** + ```markdown + ⚠️ **Security Note**: Never commit `.env` files to git. + Add to `.gitignore` immediately. + ``` + +3. **Використовуйте безпечні значення за замовчуванням** + - Увімкнення автентифікації за замовчуванням + - Використання HTTPS де можливо + - Валідація та санітизація введення + - Використання параметризованих запитів + +4. **Документуйте міркування безпеки** + - Пояснюйте, чому безпека важлива + - Показуйте безпечні vs. небезпечні патерни + - Посилайтесь на авторитетні джерела + - Розміщуйте попередження на видному місці + +### При перегляді внесків + +1. **Перевіряйте на відкриті секрети** + - Сканування на поширені патерни (api_key=, password=) + - Перегляд конфігураційних файлів + - Перевірка змінних оточення + +2. **Перевіряйте безпечні практики кодування** + - Відсутність захардкоджених облікових даних + - Правильна валідація введення + - Безпечна автентифікація/авторизація + - Безпечна робота з файлами + +3. **Тестуйте наслідки безпеки** + - Чи можна це зловживати? + - Який найгірший сценарій? + - Чи є граничні випадки? + +## Ресурси безпеки + +### Офіційні стандарти +- [OWASP Top 10](https://owasp.org/www-project-top-ten/) +- [CWE Top 25](https://cwe.mitre.org/top25/) +- [CVSS Calculator](https://www.first.org/cvss/calculator/3.1) + +### Безпека Python +- [Python Security Advisories](https://www.python.org/dev/security/) +- [PyPI Security](https://pypi.org/help/#security) +- [Bandit Documentation](https://bandit.readthedocs.io/) + +### Управління залежностями +- [OWASP Dependency Check](https://owasp.org/www-project-dependency-check/) +- [GitHub Security Alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts) + +### Загальна безпека +- [Anthropic Security](https://www.anthropic.com/) +- [GitHub Security Best Practices](https://docs.github.com/en/code-security) + +## Архів рекомендацій безпеки + +Минулі рекомендації безпеки доступні на вкладці [GitHub Security Advisories](https://github.com/luongnv89/claude-howto/security/advisories). + +## Контакти + +Для запитань, пов'язаних з безпекою, або для обговорення практик безпеки: + +1. **Приватне повідомлення про безпеку**: Використовуйте приватне повідомлення про вразливості GitHub +2. **Загальні питання безпеки**: Відкрийте обговорення з тегом `[SECURITY]` +3. **Відгуки про політику безпеки**: Створіть issue з міткою `security` + +## Подяки + +Ми цінуємо дослідників безпеки та учасників спільноти, які допомагають підтримувати безпеку цього проєкту. Контриб'юторів, які відповідально повідомляють про вразливості, буде відзначено в наших рекомендаціях безпеки (якщо вони не бажають анонімності). + +## Оновлення політики + +Ця політика безпеки переглядається та оновлюється: +- При виявленні нових вразливостей +- При розвитку найкращих практик безпеки +- При зміні обсягу проєкту +- Щорічно як мінімум + +**Останнє оновлення**: Квітень 2026 +**Наступний перегляд**: Квітень 2027 + +--- + +Дякуємо за допомогу в забезпеченні безпеки Claude How To! 🔒 diff --git a/uk/STYLE_GUIDE.md b/uk/STYLE_GUIDE.md new file mode 100644 index 0000000..82050ac --- /dev/null +++ b/uk/STYLE_GUIDE.md @@ -0,0 +1,637 @@ + + + + + + + Claude How To + + +# Гайд зі стилю + +> Конвенції та правила форматування для внеску в Claude How To. Дотримуйтесь цього гайду, щоб тримати контент консистентним, професійним та зручним для підтримки. + +--- + +## Зміст + +- [Іменування файлів та каталогів](#іменування-файлів-та-каталогів) +- [Структура документа](#структура-документа) +- [Заголовки](#заголовки) +- [Форматування тексту](#форматування-тексту) +- [Списки](#списки) +- [Таблиці](#таблиці) +- [Блоки коду](#блоки-коду) +- [Посилання та перехресні посилання](#посилання-та-перехресні-посилання) +- [Діаграми](#діаграми) +- [Використання емодзі](#використання-емодзі) +- [YAML Frontmatter](#yaml-frontmatter) +- [Зображення та медіа](#зображення-та-медіа) +- [Тон та голос](#тон-та-голос) +- [Повідомлення комітів](#повідомлення-комітів) +- [Чеклист для авторів](#чеклист-для-авторів) + +--- + +## Іменування файлів та каталогів + +### Каталоги уроків + +Каталоги уроків використовують **двозначний числовий префікс** з **kebab-case** описом: + +``` +01-slash-commands/ +02-memory/ +03-skills/ +04-subagents/ +05-mcp/ +``` + +Номер відображає порядок навчального шляху від початківця до просунутого. + +### Імена файлів + +| Тип | Конвенція | Приклади | +|-----|-----------|---------| +| **README уроку** | `README.md` | `01-slash-commands/README.md` | +| **Файл функції** | Kebab-case `.md` | `code-reviewer.md`, `generate-api-docs.md` | +| **Shell-скрипт** | Kebab-case `.sh` | `format-code.sh`, `validate-input.sh` | +| **Конфіг-файл** | Стандартні назви | `.mcp.json`, `settings.json` | +| **Файл пам'яті** | З префіксом области | `project-CLAUDE.md`, `personal-CLAUDE.md` | +| **Документи верхнього рівня** | UPPER_CASE `.md` | `CATALOG.md`, `QUICK_REFERENCE.md`, `CONTRIBUTING.md` | +| **Зображення** | Kebab-case | `pr-slash-command.png`, `claude-howto-logo.svg` | + +### Правила + +- Використовуйте **нижній регістр** для всіх імен файлів та каталогів (крім документів верхнього рівня як `README.md`, `CATALOG.md`) +- Використовуйте **дефіси** (`-`) як розділювачі слів, ніколи підкреслення або пробіли +- Тримайте назви описовими, але стислими + +--- + +## Структура документа + +### Кореневий README + +Кореневий `README.md` дотримується порядку: + +1. Логотип (елемент `` з варіантами 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. Поради з налаштування + +### Розділювачі секцій + +Використовуйте горизонтальні лінії (`---`) для відділення основних регіонів документа: + +```markdown +--- + +## Нова основна секція +``` + +Розміщуйте їх після вступної цитати та між логічно окремими частинами документа. + +--- + +## Заголовки + +### Ієрархія + +| Рівень | Використання | Приклад | +|--------|-------------|---------| +| `#` H1 | Заголовок сторінки (один на документ) | `# Slash Commands` | +| `##` H2 | Основні секції | `## Best Practices` | +| `###` H3 | Підсекції | `### Adding a Skill` | +| `####` H4 | Під-підсекції (рідко) | `#### Configuration Options` | + +### Правила + +- **Один H1 на документ** — лише заголовок сторінки +- **Ніколи не пропускайте рівні** — не стрибайте з H2 на H4 +- **Тримайте заголовки стислими** — прагніть до 2-5 слів +- **Використовуйте sentence case** — великі літери тільки для першого слова та власних назв (виняток: назви функцій залишаються як є) +- **Додавайте емодзі-префікси тільки в кореневому README** для заголовків секцій (див. [Використання емодзі](#використання-емодзі)) + +--- + +## Форматування тексту + +### Виділення + +| Стиль | Коли використовувати | Приклад | +|-------|---------------------|---------| +| **Жирний** (`**text**`) | Ключові терміни, мітки в таблицях, важливі поняття | `**Installation**:` | +| *Курсив* (`*text*`) | Перше згадування технічного терміну, назви книг/документів | `*frontmatter*` | +| `Код` (`` `text` ``) | Імена файлів, команди, значення конфігурації, посилання на код | `` `CLAUDE.md` `` | + +### Цитати для виносок + +Використовуйте цитати з жирними префіксами для важливих нотаток: + +```markdown +> **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-пробіловим відступом для вкладеності: + +```markdown +- First item +- Second item + - Nested item + - Another nested item + - Deep nested (avoid going deeper than 3 levels) +- Third item +``` + +### Нумеровані списки + +Використовуйте нумеровані списки для послідовних кроків, інструкцій та ранжованих елементів: + +```markdown +1. First step +2. Second step + - Sub-point detail + - Another sub-point +3. Third step +``` + +### Описові списки + +Використовуйте жирні мітки для списків ключ-значення: + +```markdown +- **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 рівнів + +--- + +## Таблиці + +### Стандартний формат + +```markdown +| Column 1 | Column 2 | Column 3 | +|----------|----------|----------| +| Data | Data | Data | +``` + +### Поширені патерни таблиць + +**Порівняння функцій (3-4 колонки):** + +```markdown +| 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:** + +```markdown +| Do | Don't | +|----|-------| +| Use descriptive names | Use vague names | +| Keep files focused | Overload a single file | +``` + +**Швидкий довідник:** + +```markdown +| Aspect | Details | +|--------|---------| +| **Purpose** | Generate API documentation | +| **Scope** | Project-level | +| **Complexity** | Intermediate | +``` + +### Правила + +- **Жирний для заголовків таблиці**, коли вони є мітками рядків (перша колонка) +- Вирівнюйте пайпи для читабельності у вихідному коді (опціонально, але бажано) +- Тримайте вміст комірок стислим; використовуйте посилання для деталей +- Використовуйте `форматування коду` для команд та шляхів файлів у комірках + +--- + +## Блоки коду + +### Теги мов + +Завжди вказуйте тег мови для підсвічування синтаксису: + +| Мова | Тег | Використання | +|------|-----|-------------| +| Shell | `bash` | Команди CLI, скрипти | +| Python | `python` | Код Python | +| JavaScript | `javascript` | Код JS | +| TypeScript | `typescript` | Код TS | +| JSON | `json` | Конфігураційні файли | +| YAML | `yaml` | Frontmatter, конфіг | +| Markdown | `markdown` | Приклади Markdown | +| SQL | `sql` | Запити до бази даних | +| Звичайний текст | (без тегу) | Очікуваний вивід, дерева каталогів | + +### Конвенції + +```bash +# Comment explaining what the command does +claude mcp add notion --transport http https://mcp.notion.com/mcp +``` + +- Додавайте **рядок коментаря** перед неочевидними командами +- Робіть всі приклади **готовими до копіювання та вставки** +- Показуйте **і прості, і просунуті** версії де доречно +- Включайте **очікуваний вивід** коли це допомагає розумінню (використовуйте блок коду без тегу) + +### Блоки встановлення + +Використовуйте цей патерн для інструкцій з встановлення: + +```bash +# Copy files to your project +cp 01-slash-commands/*.md .claude/commands/ +``` + +### Багатокрокові робочі процеси + +```bash +# 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/ +``` + +--- + +## Посилання та перехресні посилання + +### Внутрішні посилання (відносні) + +Використовуйте відносні шляхи для всіх внутрішніх посилань: + +```markdown +[Slash Commands](01-slash-commands/) +[Skills Guide](03-skills/) +[Memory Architecture](02-memory/#memory-architecture) +``` + +З каталогу уроку назад до кореня або сусіда: + +```markdown +[Back to main guide](../README.md) +[Related: Skills](../03-skills/) +``` + +### Зовнішні посилання (абсолютні) + +Використовуйте повні URL з описовим текстом якоря: + +```markdown +[Anthropic's official documentation](https://code.claude.com/docs/en/overview) +``` + +- Ніколи не використовуйте "click here" або "this link" як текст якоря +- Використовуйте описовий текст, що має сенс поза контекстом + +### Якорі секцій + +Посилайтесь на секції в тому ж документі за допомогою GitHub-style якорів: + +```markdown +[Feature Catalog](#-feature-catalog) +[Best Practices](#best-practices) +``` + +### Патерн пов'язаних гайдів + +Завершуйте уроки секцією пов'язаних гайдів: + +```markdown +## 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` — хронологічні послідовності + +### Стильові конвенції + +Застосовуйте консистентні кольори за допомогою блоків стилів: + +```mermaid +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 +``` + +**Палітра кольорів:** + +| Колір | Hex | Використання | +|-------|-----|-------------| +| Світло-блакитний | `#e1f5fe` | Основні компоненти, входи | +| Світло-рожевий | `#fce4ec` | Обробка, проміжне ПЗ | +| Світло-зелений | `#e8f5e9` | Виходи, результати | +| Світло-жовтий | `#fff9c4` | Конфігурація, опціональне | +| Світло-фіолетовий | `#f3e5f5` | Користувацький інтерфейс | + +### Правила + +- Використовуйте `["Label text"]` для міток вузлів (дозволяє спеціальні символи) +- Використовуйте `
` для переносу рядків у мітках +- Тримайте діаграми простими (максимум 10-12 вузлів) +- Додавайте короткий текстовий опис під діаграмою для доступності +- Використовуйте зверху вниз (`TB`) для ієрархій, зліва направо (`LR`) для робочих процесів + +--- + +## Використання емодзі + +### Де використовуються емодзі + +Емодзі використовуються **рідко та цілеспрямовано** — тільки в певних контекстах: + +| Контекст | Емодзі | Приклад | +|----------|--------|---------| +| Заголовки секцій кореневого README | Іконки категорій | `## 📚 Learning Path` | +| Індикатори рівня навичок | Кольорові кола | 🟢 Початківець, 🔵 Середній, 🔴 Просунутий | +| Do's and Don'ts | Галочки/хрестики | ✅ Робіть це, ❌ Не робіть це | +| Рейтинги складності | Зірки | ⭐⭐⭐ | + +### Стандартний набір емодзі + +| Емодзі | Значення | +|--------|---------| +| 📚 | Навчання, гайди, документація | +| ⚡ | Початок роботи, швидкий довідник | +| 🎯 | Функції, швидкий довідник | +| 🎓 | Навчальні шляхи | +| 📊 | Статистика, порівняння | +| 🚀 | Встановлення, швидкі команди | +| 🟢 | Рівень початківця | +| 🔵 | Середній рівень | +| 🔴 | Просунутий рівень | +| ✅ | Рекомендована практика | +| ❌ | Уникати / анти-патерн | +| ⭐ | Одиниця рейтингу складності | + +### Правила + +- **Ніколи не використовуйте емодзі в основному тексті** або абзацах +- **Використовуйте емодзі в заголовках тільки** в кореневому README (не в README уроків) +- **Не додавайте декоративних емодзі** — кожне емодзі повинно нести значення +- Тримайте використання емодзі консистентним з таблицею вище + +--- + +## YAML Frontmatter + +### Файли функцій (навички, команди, агенти) + +```yaml +--- +name: unique-identifier +description: What this feature does and when to use it +allowed-tools: Bash, Read, Grep +--- +``` + +### Опціональні поля + +```yaml +--- +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` в одне речення +- Включайте тільки необхідні поля + +--- + +## Зображення та медіа + +### Патерн логотипу + +Усі документи, що починаються з логотипу, використовують елемент `` для підтримки dark/light режимів: + +```html + + + Claude How To + +``` + +### Скріншоти + +- Зберігайте у відповідному каталозі уроку (напр., `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, але не новий у програмуванні + +### Принципи контенту + +| Принцип | Приклад | +|---------|---------| +| **Показуйте, а не розповідайте** | Надавайте працюючі приклади, а не абстрактні описи | +| **Прогресивна складність** | Починайте просто, додавайте глибину в наступних секціях | +| **Пояснюйте «чому»** | "Use memory for... because...", а не просто "Use memory for..." | +| **Готове до копіювання** | Кожен блок коду повинен працювати при безпосередній вставці | +| **Реальний контекст** | Використовуйте практичні сценарії, а не штучні приклади | + +### Словник + +- Використовуйте "Claude Code" (не "Claude CLI" або "the tool") +- Використовуйте "skill" (не "custom command" — застарілий термін) +- Використовуйте "lesson" або "guide" для нумерованих секцій +- Використовуйте "example" для окремих файлів функцій + +--- + +## Повідомлення комітів + +Дотримуйтесь [Conventional Commits](https://www.conventionalcommits.org/): + +``` +type(scope): description +``` + +### Типи + +| Тип | Використання | +|-----|-------------| +| `feat` | Нова функція, приклад або гайд | +| `fix` | Виправлення помилки, корекція, зламане посилання | +| `docs` | Покращення документації | +| `refactor` | Реструктуризація без зміни поведінки | +| `style` | Тільки зміни форматування | +| `test` | Додавання або зміни тестів | +| `chore` | Збірка, залежності, CI | + +### Скоупи + +Використовуйте назву уроку або області файлу як скоуп: + +``` +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 уроків завершуються блоком метаданих: + +```markdown +--- +**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 diff --git a/uk/TRANSLATION_NOTES.md b/uk/TRANSLATION_NOTES.md new file mode 100644 index 0000000..1709155 --- /dev/null +++ b/uk/TRANSLATION_NOTES.md @@ -0,0 +1,286 @@ +# Глосарій та Стайлгайд перекладу + +# Translation Glossary & Style Guide + +> **Важливо:** Цей документ визначає правила перекладу документації Claude Code українською мовою. Прочитайте перед початком роботи. + +## Технічна термінологія + +Таблиця термінів для єдності перекладу у всіх файлах: + +| English | Українська | Примітка | +|---------|-----------|----------| +| slash command | слеш-команда | "Слеш" зберігаємо — це назва фічі | +| hook | хук | Усталений термін в UA IT-спільноті | +| skill | навичка | Назва фічі Claude Code, перекладаємо | +| subagent | субагент | Або "підагент" — обидва прийнятні | +| agent | агент | Перекладаємо | +| memory | пам'ять | Перекладаємо | +| checkpoint | контрольна точка | Перекладаємо для ясності | +| plugin | плагін | Усталений термін | +| pull request / PR | pull request / PR | Зберігаємо (GitHub-термін) | +| commit | коміт | Усталена транслітерація | +| branch | гілка | Перекладаємо | +| merge | мердж | Або "злиття" — залежить від контексту | +| MCP (Model Context Protocol) | MCP | Зберігаємо (назва протоколу) | +| CLAUDE.md | CLAUDE.md | Зберігаємо (ім'я файлу) | +| prompt | промпт | Усталена транслітерація | +| workflow | воркфлов | Або "робочий процес" | +| repository | репозиторій | Скорочено "репо" | +| issue | issue | Зберігаємо (GitHub-термін) | +| release | реліз | Усталена транслітерація | +| API | API | Зберігаємо | +| CLI | CLI | Зберігаємо (Command-Line Interface) | +| CI/CD | CI/CD | Зберігаємо | +| pre-commit hook | pre-commit хук | Зберігаємо "pre-commit" як назву інструмента | +| environment variable | змінна оточення | Перекладаємо | +| dependencies | залежності | Перекладаємо | +| template | шаблон | Перекладаємо | +| worktree | робоче дерево | Git-термін, перекладаємо | +| frontmatter | фронтматер | YAML-блок на початку файлу | +| token | токен | Усталена транслітерація | +| context window | контекстне вікно | Перекладаємо | +| fork | форк | Усталена транслітерація | +| clone | клонувати | Перекладаємо дієслово | +| sandbox | пісочниця | Перекладаємо | +| boilerplate | шаблонний код | Перекладаємо | +| debugging | налагодження | Перекладаємо | +| linting | лінтинг | Транслітерація | +| refactoring | рефакторинг | Усталена транслітерація | + +## Правила перекладу + +### 1. Код та команди + +**ЗОЛОТЕ ПРАВИЛО:** Зберігаємо 100% виконуваного коду. Перекладаємо лише коментарі та пояснення. + +**Правильно (✅):** + +````markdown +Щоб запустити цю команду: + +```bash +/optimize +``` + +Ця команда проаналізує ваш код. +```` + +**Неправильно (❌):** + +````markdown +Щоб запустити цю команду: + +```bash +/оптимізувати # НІКОЛИ не перекладайте команди +``` +```` + +### 2. Коментарі в коді + +Перекладаємо коментарі українською: + +```python +# ✅ ПРАВИЛЬНО — коментар перекладено +# Ця слеш-команда оптимізує ваш код +def optimize_code(): + pass + +# ❌ НЕПРАВИЛЬНО — не перекладайте назви функцій +def оптимізувати_код(): # НЕ перекладаємо імена функцій + pass +``` + +### 3. Назви функцій, змінних та класів + +Зберігаємо англійською: + +```python +# ✅ ПРАВИЛЬНО +def create_subagent(name: str, system_prompt: str): + pass + +# ❌ НЕПРАВИЛЬНО +def створити_субагент(імя: str, системний_промпт: str): + pass +``` + +### 4. Діаграми Mermaid + +**Зберігаємо 100% без змін.** Не перекладаємо жодного тексту в блоках mermaid. + +````markdown + +```mermaid +graph TD + A[Користувач] --> B[Агент] +``` + + +```mermaid +graph TD + A[User] --> B[Agent] +``` +```` + +**Важливо:** Коментарі в Mermaid використовують `%%`, а не `#`. Символ `#` спричиняє помилку парсера. + +````markdown + +```mermaid +graph TD + %% Це коментар у Mermaid + A[User] --> B[Agent] +``` + + +```text +graph TD + # Це зламає парсер! + A[User] --> B[Agent] +``` +```` + +### 5. Шляхи до файлів та URL + +Зберігаємо без змін: + +```markdown + +Див. файл `.claude/settings.json` для конфігурації. + + +Див. файл `.claude/налаштування.json` для конфігурації. +``` + +### 6. Таблиці + +Зберігаємо структуру та кількість стовпців/рядків. Перекладаємо текстовий вміст, залишаємо технічні значення: + +```markdown +| Команда | Опис | Приклад | +|---------|------|---------| +| `/help` | Показати довідку | `/help memory` | +| `/clear` | Очистити сесію | `/clear` | +``` + +### 7. Посилання між файлами + +Використовуємо відносні шляхи всередині `uk/`: + +```markdown + +[Пам'ять](../02-memory/) + + +[English version](../../README.md) + + +[`format-code.sh`](../../06-hooks/format-code.sh) +``` + +### 8. Фронтматер для трекінгу версії + +Кожен перекладений файл починається з HTML-коментарів для відстеження версії оригіналу: + +```markdown + + + + +# Заголовок перекладеного файлу +``` + +SHA — це коротка хеш-сума коміту англійського файлу, з якого робився переклад. Отримати: `git log --oneline -1 -- <шлях-до-англійського-файлу>`. + +### 9. Стиль тексту + +- Звертання до читача: **"ви"** (не "ти", не "Ви") +- Уникайте канцеляризмів: "запустіть" замість "здійсніть запуск" +- Технічні абревіатури при першому згадуванні: розшифровка + абревіатура в дужках, далі — лише абревіатура +- Числівники: до 10 — словами, від 11 — цифрами + +## DO / DON'T + +### ✅ DO: Перекладайте описовий текст + +```markdown +Слеш-команди — це ярлики, які керують поведінкою Claude під час інтерактивної сесії. +``` + +### ✅ DO: Перекладайте коментарі в коді + +```python +# ✅ ПРАВИЛЬНО +# Ця функція створює нового субагента +def create_subagent(): + pass +``` + +### ❌ DON'T: Не перекладайте назви функцій + +```python +# ❌ НЕПРАВИЛЬНО +def створити_субагент(): + pass + +# ✅ ПРАВИЛЬНО +def create_subagent(): + pass +``` + +### ❌ DON'T: Не перекладайте діаграми Mermaid + +````markdown + +```mermaid +graph TD + A[Користувач] --> B[Агент] +``` + + +```mermaid +graph TD + A[User] --> B[Agent] +``` +```` + +### ❌ DON'T: Не довіряйте машинному перекладу без перевірки + +Машинний переклад (Google Translate, DeepL) часто: + +- Неправильно перекладає технічні терміни +- Не розуміє контекст коду +- Спотворює значення команд +- Ламає Markdown-форматування + +**Завжди перевіряйте та редагуйте після машинного перекладу!** + +## Чекліст перед комітом + +- [ ] Технічна точність збережена +- [ ] Текст звучить природно українською +- [ ] Термінологія відповідає глосарію +- [ ] Код залишено без змін (100%) +- [ ] Діаграми Mermaid не змінені +- [ ] Внутрішні посилання працюють +- [ ] Зовнішні посилання збережені +- [ ] Markdown-форматування коректне +- [ ] Коментарі в коді перекладені +- [ ] Назви функцій/змінних/класів — англійською +- [ ] Шляхи до файлів та URL без змін +- [ ] Фронтматер `i18n-source-sha` додано +- [ ] Pre-commit перевірки пройдені + +## Допомога + +Якщо виникли питання під час перекладу: + +1. Перевірте цей глосарій +2. Подивіться як перекладені аналогічні файли в інших модулях +3. Створіть GitHub issue для обговорення + +--- + +**Останнє оновлення:** 2026-04-09 +**Мова:** Українська (uk-UA) diff --git a/uk/TRANSLATION_QUEUE.md b/uk/TRANSLATION_QUEUE.md new file mode 100644 index 0000000..920a1cf --- /dev/null +++ b/uk/TRANSLATION_QUEUE.md @@ -0,0 +1,68 @@ + + +# Прогрес перекладу українською + +**Загальний прогрес:** ~67/67 файлів (100%) + +**Статус:** ✅ ЗАВЕРШЕНО — P1 ядро ✅ P2 модулі ✅ P3 приклади ✅ P4 допоміжні ✅ + +## Пріоритет 1 — Ядро (5 файлів) ✅ + +| Файл | Статус | Дата | +|------|--------|------| +| README.md | ✅ | 2026-04-09 | +| INDEX.md | ✅ | 2026-04-09 | +| CATALOG.md | ✅ | 2026-04-09 | +| QUICK_REFERENCE.md | ✅ | 2026-04-09 | +| LEARNING-ROADMAP.md | ✅ | 2026-04-09 | + +**Прогрес P1:** 5/5 (100%) ✅ + +## Пріоритет 2 — Модулі README (10 файлів) ✅ + +| Модуль | Рядків | Статус | Дата | +|--------|--------|--------|------| +| 01 slash-commands | 565 | ✅ | 2026-04-09 | +| 02 memory | 1156 | ✅ | 2026-04-09 | +| 03 skills | 811 | ✅ | 2026-04-09 | +| 04 subagents | 1142 | ✅ | 2026-04-09 | +| 05 mcp | 1113 | ✅ | 2026-04-09 | +| 06 hooks | 1170 | ✅ | 2026-04-09 | +| 07 plugins | 949 | ✅ | 2026-04-09 | +| 08 checkpoints | 320 | ✅ | 2026-04-09 | +| 09 advanced | 1945 | ✅ | 2026-04-09 | +| 10 cli | 837 | ✅ | 2026-04-09 | + +**Прогрес P2:** 10/10 (100%) ✅ + +## Пріоритет 3 — Приклади ✅ + +| Модуль | Файлів | Статус | Дата | +|--------|--------|--------|------| +| 01-slash-commands (приклади) | 8 | ✅ | 2026-04-09 | +| 02-memory (CLAUDE.md) | 3 | ✅ | 2026-04-09 | +| 03-skills (SKILL.md + templates) | 15+ | ✅ | 2026-04-09 | +| 04-subagents (агенти) | 8 | ✅ | 2026-04-09 | +| 05-mcp (.json конфіги) | 4 | ✅ скопійовано | 2026-04-10 | +| 06-hooks (скрипти) | 10 | ✅ скопійовано | 2026-04-10 | +| 07-plugins (3 плагіни) | 27 | ✅ | 2026-04-10 | +| 08-checkpoints (приклади) | 1 | ✅ | 2026-04-09 | +| 09-advanced (приклади) | 1 | ✅ | 2026-04-09 | + +**Прогрес P3:** ✅ завершено + +## Пріоритет 4 — Допоміжні (5 файлів) ✅ + +| Файл | Статус | Дата | +|------|--------|------| +| CONTRIBUTING.md | ✅ | 2026-04-10 | +| CODE_OF_CONDUCT.md | ✅ | 2026-04-10 | +| SECURITY.md | ✅ | 2026-04-10 | +| STYLE_GUIDE.md | ✅ | 2026-04-10 | +| CHANGELOG.md | ✅ скопійовано | 2026-04-10 | + +**Прогрес P4:** 5/5 (100%) ✅ + +--- + +**Останнє оновлення:** 2026-04-10 diff --git a/uk/claude-howto-logo.png b/uk/claude-howto-logo.png new file mode 100644 index 0000000..94d34a4 Binary files /dev/null and b/uk/claude-howto-logo.png differ diff --git a/uk/claude_concepts_guide.md b/uk/claude_concepts_guide.md new file mode 100644 index 0000000..d432eec --- /dev/null +++ b/uk/claude_concepts_guide.md @@ -0,0 +1,3135 @@ + + + Claude How To + + +# Повний довідник концепцій Claude + +Комплексний довідник, що охоплює слеш-команди, субагентів, пам'ять, протокол MCP та навички агентів з таблицями, діаграмами та практичними прикладами. + +--- + +## Зміст + +1. [Слеш-команди](#слеш-команди) +2. [Субагенти](#субагенти) +3. [Пам'ять](#память) +4. [Протокол MCP](#протокол-mcp) +5. [Навички агентів](#навички-агентів) +6. [Плагіни](#плагіни-claude-code) +7. [Хуки](#хуки) +8. [Контрольні точки та відкат](#контрольні-точки-та-відкат) +9. [Просунуті функції](#просунуті-функції) +10. [Порівняння та інтеграція](#порівняння-та-інтеграція) + +--- + +## Слеш-команди + +### Огляд + +Слеш-команди — це ярлики, ініційовані користувачем, що зберігаються як Markdown-файли, які Claude Code може виконувати. Вони дозволяють командам стандартизувати часто використовувані промпти та робочі процеси. + +### Архітектура + +```mermaid +graph TD + A["User Input: /command-name"] -->|Triggers| B["Search .claude/commands/"] + B -->|Finds| C["command-name.md"] + C -->|Loads| D["Markdown Content"] + D -->|Executes| E["Claude Processes Prompt"] + E -->|Returns| F["Result in Context"] +``` + +### Структура файлів + +```mermaid +graph LR + A["Project Root"] -->|contains| B[".claude/commands/"] + B -->|contains| C["optimize.md"] + B -->|contains| D["test.md"] + B -->|contains| E["docs/"] + E -->|contains| F["generate-api-docs.md"] + E -->|contains| G["generate-readme.md"] +``` + +### Таблиця організації команд + +| Location | Scope | Availability | Use Case | Git Tracked | +|----------|-------|--------------|----------|-------------| +| `.claude/commands/` | Project-specific | Team members | Team workflows, shared standards | ✅ Yes | +| `~/.claude/commands/` | Personal | Individual user | Personal shortcuts across projects | ❌ No | +| Subdirectories | Namespaced | Based on parent | Organize by category | ✅ Yes | + +### Функції та можливості + +| Feature | Example | Supported | +|---------|---------|-----------| +| Shell script execution | `bash scripts/deploy.sh` | ✅ Yes | +| File references | `@path/to/file.js` | ✅ Yes | +| Bash integration | `$(git log --oneline)` | ✅ Yes | +| Arguments | `/pr --verbose` | ✅ Yes | +| MCP commands | `/mcp__github__list_prs` | ✅ Yes | + +### Практичні приклади + +#### Приклад 1: Команда оптимізації коду + +**Файл:** `.claude/commands/optimize.md` + +```markdown +--- +name: Code Optimization +description: Analyze code for performance issues and suggest optimizations +tags: performance, analysis +--- + +# Code Optimization + +Review the provided code for the following issues in order of priority: + +1. **Performance bottlenecks** - identify O(n²) operations, inefficient loops +2. **Memory leaks** - find unreleased resources, circular references +3. **Algorithm improvements** - suggest better algorithms or data structures +4. **Caching opportunities** - identify repeated computations +5. **Concurrency issues** - find race conditions or threading problems + +Format your response with: +- Issue severity (Critical/High/Medium/Low) +- Location in code +- Explanation +- Recommended fix with code example +``` + +**Використання:** +```bash +# User types in Claude Code +/optimize + +# Claude loads the prompt and waits for code input +``` + +#### Приклад 2: Команда-помічник для Pull Request + +**Файл:** `.claude/commands/pr.md` + +```markdown +--- +name: Prepare Pull Request +description: Clean up code, stage changes, and prepare a pull request +tags: git, workflow +--- + +# Pull Request Preparation Checklist + +Before creating a PR, execute these steps: + +1. Run linting: `prettier --write .` +2. Run tests: `npm test` +3. Review git diff: `git diff HEAD` +4. Stage changes: `git add .` +5. Create commit message following conventional commits: + - `fix:` for bug fixes + - `feat:` for new features + - `docs:` for documentation + - `refactor:` for code restructuring + - `test:` for test additions + - `chore:` for maintenance + +6. Generate PR summary including: + - What changed + - Why it changed + - Testing performed + - Potential impacts +``` + +**Використання:** +```bash +/pr + +# Claude runs through checklist and prepares the PR +``` + +#### Приклад 3: Ієрархічний генератор документації + +**Файл:** `.claude/commands/docs/generate-api-docs.md` + +```markdown +--- +name: Generate API Documentation +description: Create comprehensive API documentation from source code +tags: documentation, api +--- + +# API Documentation Generator + +Generate API documentation by: + +1. Scanning all files in `/src/api/` +2. Extracting function signatures and JSDoc comments +3. Organizing by endpoint/module +4. Creating markdown with examples +5. Including request/response schemas +6. Adding error documentation + +Output format: +- Markdown file in `/docs/api.md` +- Include curl examples for all endpoints +- Add TypeScript types +``` + +### Діаграма життєвого циклу команди + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant FS as File System + participant CLI as Shell/Bash + + User->>Claude: Types /optimize + Claude->>FS: Searches .claude/commands/ + FS-->>Claude: Returns optimize.md + Claude->>Claude: Loads Markdown content + Claude->>User: Displays prompt context + User->>Claude: Provides code to analyze + Claude->>CLI: (May execute scripts) + CLI-->>Claude: Results + Claude->>User: Returns analysis +``` + +### Найкращі практики + +| ✅ Рекомендовано | ❌ Не рекомендовано | +|------|---------| +| Використовуйте зрозумілі, орієнтовані на дію назви | Створювати команди для одноразових завдань | +| Документуйте ключові слова в описі | Будувати складну логіку в командах | +| Зосередьте команду на одному завданні | Створювати дублюючі команди | +| Контролюйте версії проєктних команд | Жорстко прописувати конфіденційну інформацію | +| Організовуйте у підкаталогах | Створювати довгі списки команд | +| Використовуйте прості, зрозумілі промпти | Використовувати скорочені або незрозумілі формулювання | + +--- + +## Субагенти + +### Огляд + +Субагенти — це спеціалізовані AI-асистенти з ізольованими контекстними вікнами та налаштованими системними промптами. Вони забезпечують делеговане виконання завдань, зберігаючи чітке розділення відповідальностей. + +### Діаграма архітектури + +```mermaid +graph TB + User["👤 User"] + Main["🎯 Main Agent
(Coordinator)"] + Reviewer["🔍 Code Reviewer
Subagent"] + Tester["✅ Test Engineer
Subagent"] + Docs["📝 Documentation
Subagent"] + + User -->|asks| Main + Main -->|delegates| Reviewer + Main -->|delegates| Tester + Main -->|delegates| Docs + Reviewer -->|returns result| Main + Tester -->|returns result| Main + Docs -->|returns result| Main + Main -->|synthesizes| User +``` + +### Життєвий цикл субагента + +```mermaid +sequenceDiagram + participant User + participant MainAgent as Main Agent + participant CodeReviewer as Code Reviewer
Subagent + participant Context as Separate
Context Window + + User->>MainAgent: "Build new auth feature" + MainAgent->>MainAgent: Analyze task + MainAgent->>CodeReviewer: "Review this code" + CodeReviewer->>Context: Initialize clean context + Context->>CodeReviewer: Load reviewer instructions + CodeReviewer->>CodeReviewer: Perform review + CodeReviewer-->>MainAgent: Return findings + MainAgent->>MainAgent: Incorporate results + MainAgent-->>User: Provide synthesis +``` + +### Таблиця конфігурації субагента + +| Конфігурація | Тип | Призначення | Приклад | +|---------------|------|---------|---------| +| `name` | String | Ідентифікатор агента | `code-reviewer` | +| `description` | String | Призначення та ключові слова | `Comprehensive code quality analysis` | +| `tools` | List/String | Дозволені можливості | `read, grep, diff, lint_runner` | +| `system_prompt` | Markdown | Поведінкові інструкції | Користувацькі настанови | + +### Ієрархія доступу до інструментів + +```mermaid +graph TD + A["Subagent Configuration"] -->|Option 1| B["Inherit All Tools
from Main Thread"] + A -->|Option 2| C["Specify Individual Tools"] + B -->|Includes| B1["File Operations"] + B -->|Includes| B2["Shell Commands"] + B -->|Includes| B3["MCP Tools"] + C -->|Explicit List| C1["read, grep, diff"] + C -->|Explicit List| C2["Bash(npm:*), Bash(test:*)"] +``` + +### Практичні приклади + +#### Приклад 1: Повне налаштування субагента + +**Файл:** `.claude/agents/code-reviewer.md` + +```yaml +--- +name: code-reviewer +description: Comprehensive code quality and maintainability analysis +tools: read, grep, diff, lint_runner +--- + +# Code Reviewer Agent + +You are an expert code reviewer specializing in: +- Performance optimization +- Security vulnerabilities +- Code maintainability +- Testing coverage +- Design patterns + +## Review Priorities (in order) + +1. **Security Issues** - Authentication, authorization, data exposure +2. **Performance Problems** - O(n²) operations, memory leaks, inefficient queries +3. **Code Quality** - Readability, naming, documentation +4. **Test Coverage** - Missing tests, edge cases +5. **Design Patterns** - SOLID principles, architecture + +## Review Output Format + +For each issue: +- **Severity**: Critical / High / Medium / Low +- **Category**: Security / Performance / Quality / Testing / Design +- **Location**: File path and line number +- **Issue Description**: What's wrong and why +- **Suggested Fix**: Code example +- **Impact**: How this affects the system + +## Example Review + +### Issue: N+1 Query Problem +- **Severity**: High +- **Category**: Performance +- **Location**: src/user-service.ts:45 +- **Issue**: Loop executes database query in each iteration +- **Fix**: Use JOIN or batch query +``` + +**Файл:** `.claude/agents/test-engineer.md` + +```yaml +--- +name: test-engineer +description: Test strategy, coverage analysis, and automated testing +tools: read, write, bash, grep +--- + +# Test Engineer Agent + +You are expert at: +- Writing comprehensive test suites +- Ensuring high code coverage (>80%) +- Testing edge cases and error scenarios +- Performance benchmarking +- Integration testing + +## Testing Strategy + +1. **Unit Tests** - Individual functions/methods +2. **Integration Tests** - Component interactions +3. **End-to-End Tests** - Complete workflows +4. **Edge Cases** - Boundary conditions +5. **Error Scenarios** - Failure handling + +## Test Output Requirements + +- Use Jest for JavaScript/TypeScript +- Include setup/teardown for each test +- Mock external dependencies +- Document test purpose +- Include performance assertions when relevant + +## Coverage Requirements + +- Minimum 80% code coverage +- 100% for critical paths +- Report missing coverage areas +``` + +**Файл:** `.claude/agents/documentation-writer.md` + +```yaml +--- +name: documentation-writer +description: Technical documentation, API docs, and user guides +tools: read, write, grep +--- + +# Documentation Writer Agent + +You create: +- API documentation with examples +- User guides and tutorials +- Architecture documentation +- Changelog entries +- Code comment improvements + +## Documentation Standards + +1. **Clarity** - Use simple, clear language +2. **Examples** - Include practical code examples +3. **Completeness** - Cover all parameters and returns +4. **Structure** - Use consistent formatting +5. **Accuracy** - Verify against actual code + +## Documentation Sections + +### For APIs +- Description +- Parameters (with types) +- Returns (with types) +- Throws (possible errors) +- Examples (curl, JavaScript, Python) +- Related endpoints + +### For Features +- Overview +- Prerequisites +- Step-by-step instructions +- Expected outcomes +- Troubleshooting +- Related topics +``` + +#### Приклад 2: Делегування субагентам у дії + +```markdown +# Scenario: Building a Payment Feature + +## User Request +"Build a secure payment processing feature that integrates with Stripe" + +## Main Agent Flow + +1. **Planning Phase** + - Understands requirements + - Determines tasks needed + - Plans architecture + +2. **Delegates to Code Reviewer Subagent** + - Task: "Review the payment processing implementation for security" + - Context: Auth, API keys, token handling + - Reviews for: SQL injection, key exposure, HTTPS enforcement + +3. **Delegates to Test Engineer Subagent** + - Task: "Create comprehensive tests for payment flows" + - Context: Success scenarios, failures, edge cases + - Creates tests for: Valid payments, declined cards, network failures, webhooks + +4. **Delegates to Documentation Writer Subagent** + - Task: "Document the payment API endpoints" + - Context: Request/response schemas + - Produces: API docs with curl examples, error codes + +5. **Synthesis** + - Main agent collects all outputs + - Integrates findings + - Returns complete solution to user +``` + +#### Приклад 3: Обмеження доступу до інструментів + +**Обмежене налаштування — лише конкретні команди** + +```yaml +--- +name: secure-reviewer +description: Security-focused code review with minimal permissions +tools: read, grep +--- + +# Secure Code Reviewer + +Reviews code for security vulnerabilities only. + +This agent: +- ✅ Reads files to analyze +- ✅ Searches for patterns +- ❌ Cannot execute code +- ❌ Cannot modify files +- ❌ Cannot run tests + +This ensures the reviewer doesn't accidentally break anything. +``` + +**Розширене налаштування — усі інструменти для реалізації** + +```yaml +--- +name: implementation-agent +description: Full implementation capabilities for feature development +tools: read, write, bash, grep, edit, glob +--- + +# Implementation Agent + +Builds features from specifications. + +This agent: +- ✅ Reads specifications +- ✅ Writes new code files +- ✅ Runs build commands +- ✅ Searches codebase +- ✅ Edits existing files +- ✅ Finds files matching patterns + +Full capabilities for independent feature development. +``` + +### Управління контекстом субагента + +```mermaid +graph TB + A["Main Agent Context
50,000 tokens"] + B["Subagent 1 Context
20,000 tokens"] + C["Subagent 2 Context
20,000 tokens"] + D["Subagent 3 Context
20,000 tokens"] + + A -->|Clean slate| B + A -->|Clean slate| C + A -->|Clean slate| D + + B -->|Results only| A + C -->|Results only| A + D -->|Results only| A + + style A fill:#e1f5ff + style B fill:#fff9c4 + style C fill:#fff9c4 + style D fill:#fff9c4 +``` + +### Коли використовувати субагентів + +| Сценарій | Використовувати субагента | Чому | +|----------|--------------|-----| +| Складна функція з багатьма кроками | ✅ Так | Розділення відповідальностей, запобігання засміченню контексту | +| Швидкий код-рев'ю | ❌ Ні | Непотрібні накладні витрати | +| Паралельне виконання завдань | ✅ Так | Кожен субагент має власний контекст | +| Потрібна спеціалізована експертиза | ✅ Так | Налаштовані системні промпти | +| Тривалий аналіз | ✅ Так | Запобігає вичерпанню основного контексту | +| Одне завдання | ❌ Ні | Додає затримку без необхідності | + +### Команди агентів + +Команди агентів координують кількох агентів, що працюють над пов'язаними завданнями. Замість делегування одному субагенту за раз, команди агентів дозволяють основному агенту оркеструвати групу агентів, які співпрацюють, обмінюються проміжними результатами та працюють над спільною метою. Це корисно для масштабних завдань, таких як повноцінна розробка фічі, де фронтенд-агент, бекенд-агент та агент тестування працюють паралельно. + +--- + +## Пам'ять + +### Огляд + +Пам'ять дозволяє Claude зберігати контекст між сесіями та розмовами. Вона існує у двох формах: автоматичний синтез у claude.ai та файлова система CLAUDE.md у Claude Code. + +### Архітектура пам'яті + +```mermaid +graph TB + A["Claude Session"] + B["User Input"] + C["Memory System"] + D["Memory Storage"] + + B -->|User provides info| C + C -->|Synthesizes every 24h| D + D -->|Loads automatically| A + A -->|Uses context| C +``` + +### Ієрархія пам'яті в Claude Code (7 рівнів) + +Claude Code завантажує пам'ять із 7 рівнів, від найвищого до найнижчого пріоритету: + +```mermaid +graph TD + A["1. Managed Policy
Enterprise admin policies"] --> B["2. Project Memory
./CLAUDE.md"] + B --> C["3. Project Rules
.claude/rules/*.md"] + C --> D["4. User Memory
~/.claude/CLAUDE.md"] + D --> E["5. User Rules
~/.claude/rules/*.md"] + E --> F["6. Local Memory
.claude/local/CLAUDE.md"] + F --> G["7. Auto Memory
Automatically captured preferences"] + + style A fill:#fce4ec,stroke:#333,color:#333 + style B fill:#e1f5fe,stroke:#333,color:#333 + style C fill:#e1f5fe,stroke:#333,color:#333 + style D fill:#f3e5f5,stroke:#333,color:#333 + style E fill:#f3e5f5,stroke:#333,color:#333 + style F fill:#e8f5e9,stroke:#333,color:#333 + style G fill:#fff3e0,stroke:#333,color:#333 +``` + +### Таблиця розташування пам'яті + +| Рівень | Розташування | Область | Пріоритет | Спільний | Найкраще для | +|------|----------|-------|----------|--------|----------| +| 1. Керована політика | Адмін підприємства | Організація | Найвищий | Усі користувачі орг. | Відповідність, політики безпеки | +| 2. Проєкт | `./CLAUDE.md` | Проєкт | Високий | Команда (Git) | Стандарти команди, архітектура | +| 3. Правила проєкту | `.claude/rules/*.md` | Проєкт | Високий | Команда (Git) | Модульні конвенції проєкту | +| 4. Користувач | `~/.claude/CLAUDE.md` | Персональний | Середній | Індивідуальний | Особисті налаштування | +| 5. Правила користувача | `~/.claude/rules/*.md` | Персональний | Середній | Індивідуальний | Персональні модулі правил | +| 6. Локальний | `.claude/local/CLAUDE.md` | Локальний | Низький | Не спільний | Налаштування конкретної машини | +| 7. Авто-пам'ять | Автоматичний | Сесія | Найнижчий | Індивідуальний | Засвоєні вподобання, патерни | + +### Авто-пам'ять + +Авто-пам'ять автоматично фіксує вподобання користувача та патерни, виявлені під час сесій. Claude навчається з ваших взаємодій і запам'ятовує: + +- Вподобання стилю кодування +- Типові виправлення, які ви робите +- Вибір фреймворків та інструментів +- Вподобання стилю комунікації + +Авто-пам'ять працює у фоновому режимі і не потребує ручного налаштування. + +### Життєвий цикл оновлення пам'яті + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Editor as File System + participant Memory as CLAUDE.md + + User->>Claude: "Remember: use async/await" + Claude->>User: "Which memory file?" + User->>Claude: "Project memory" + Claude->>Editor: Open ~/.claude/settings.json + Claude->>Memory: Write to ./CLAUDE.md + Memory-->>Claude: File saved + Claude->>Claude: Load updated memory + Claude-->>User: "Memory saved!" +``` + +### Практичні приклади + +#### Приклад 1: Структура пам'яті проєкту + +**Файл:** `./CLAUDE.md` + +```markdown +# Project Configuration + +## Project Overview +- **Name**: E-commerce Platform +- **Tech Stack**: Node.js, PostgreSQL, React 18, Docker +- **Team Size**: 5 developers +- **Deadline**: Q4 2025 + +## Architecture +@docs/architecture.md +@docs/api-standards.md +@docs/database-schema.md + +## Development Standards + +### Code Style +- Use Prettier for formatting +- Use ESLint with airbnb config +- Maximum line length: 100 characters +- Use 2-space indentation + +### Naming Conventions +- **Files**: kebab-case (user-controller.js) +- **Classes**: PascalCase (UserService) +- **Functions/Variables**: camelCase (getUserById) +- **Constants**: UPPER_SNAKE_CASE (API_BASE_URL) +- **Database Tables**: snake_case (user_accounts) + +### Git Workflow +- Branch names: `feature/description` or `fix/description` +- Commit messages: Follow conventional commits +- PR required before merge +- All CI/CD checks must pass +- Minimum 1 approval required + +### Testing Requirements +- Minimum 80% code coverage +- All critical paths must have tests +- Use Jest for unit tests +- Use Cypress for E2E tests +- Test filenames: `*.test.ts` or `*.spec.ts` + +### API Standards +- RESTful endpoints only +- JSON request/response +- Use HTTP status codes correctly +- Version API endpoints: `/api/v1/` +- Document all endpoints with examples + +### Database +- Use migrations for schema changes +- Never hardcode credentials +- Use connection pooling +- Enable query logging in development +- Regular backups required + +### Deployment +- Docker-based deployment +- Kubernetes orchestration +- Blue-green deployment strategy +- Automatic rollback on failure +- Database migrations run before deploy + +## Common Commands + +| Command | Purpose | +|---------|---------| +| `npm run dev` | Start development server | +| `npm test` | Run test suite | +| `npm run lint` | Check code style | +| `npm run build` | Build for production | +| `npm run migrate` | Run database migrations | + +## Team Contacts +- Tech Lead: Sarah Chen (@sarah.chen) +- Product Manager: Mike Johnson (@mike.j) +- DevOps: Alex Kim (@alex.k) + +## Known Issues & Workarounds +- PostgreSQL connection pooling limited to 20 during peak hours +- Workaround: Implement query queuing +- Safari 14 compatibility issues with async generators +- Workaround: Use Babel transpiler + +## Related Projects +- Analytics Dashboard: `/projects/analytics` +- Mobile App: `/projects/mobile` +- Admin Panel: `/projects/admin` +``` + +#### Приклад 2: Пам'ять для конкретного каталогу + +**Файл:** `./src/api/CLAUDE.md` + +~~~~markdown +# API Module Standards + +This file overrides root CLAUDE.md for everything in /src/api/ + +## API-Specific Standards + +### Request Validation +- Use Zod for schema validation +- Always validate input +- Return 400 with validation errors +- Include field-level error details + +### Authentication +- All endpoints require JWT token +- Token in Authorization header +- Token expires after 24 hours +- Implement refresh token mechanism + +### Response Format + +All responses must follow this structure: + +```json +{ + "success": true, + "data": { /* actual data */ }, + "timestamp": "2025-11-06T10:30:00Z", + "version": "1.0" +} +``` + +### Error responses: +```json +{ + "success": false, + "error": { + "code": "VALIDATION_ERROR", + "message": "User message", + "details": { /* field errors */ } + }, + "timestamp": "2025-11-06T10:30:00Z" +} +``` + +### Pagination +- Use cursor-based pagination (not offset) +- Include `hasMore` boolean +- Limit max page size to 100 +- Default page size: 20 + +### Rate Limiting +- 1000 requests per hour for authenticated users +- 100 requests per hour for public endpoints +- Return 429 when exceeded +- Include retry-after header + +### Caching +- Use Redis for session caching +- Cache duration: 5 minutes default +- Invalidate on write operations +- Tag cache keys with resource type +~~~~ + +#### Приклад 3: Персональна пам'ять + +**Файл:** `~/.claude/CLAUDE.md` + +~~~~markdown +# My Development Preferences + +## About Me +- **Experience Level**: 8 years full-stack development +- **Preferred Languages**: TypeScript, Python +- **Communication Style**: Direct, with examples +- **Learning Style**: Visual diagrams with code + +## Code Preferences + +### Error Handling +I prefer explicit error handling with try-catch blocks and meaningful error messages. +Avoid generic errors. Always log errors for debugging. + +### Comments +Use comments for WHY, not WHAT. Code should be self-documenting. +Comments should explain business logic or non-obvious decisions. + +### Testing +I prefer TDD (test-driven development). +Write tests first, then implementation. +Focus on behavior, not implementation details. + +### Architecture +I prefer modular, loosely-coupled design. +Use dependency injection for testability. +Separate concerns (Controllers, Services, Repositories). + +## Debugging Preferences +- Use console.log with prefix: `[DEBUG]` +- Include context: function name, relevant variables +- Use stack traces when available +- Always include timestamps in logs + +## Communication +- Explain complex concepts with diagrams +- Show concrete examples before explaining theory +- Include before/after code snippets +- Summarize key points at the end + +## Project Organization +I organize my projects as: +``` +project/ + ├── src/ + │ ├── api/ + │ ├── services/ + │ ├── models/ + │ └── utils/ + ├── tests/ + ├── docs/ + └── docker/ +``` + +## Tooling +- **IDE**: VS Code with vim keybindings +- **Terminal**: Zsh with Oh-My-Zsh +- **Format**: Prettier (100 char line length) +- **Linter**: ESLint with airbnb config +- **Test Framework**: Jest with React Testing Library +~~~~ + +#### Приклад 4: Оновлення пам'яті під час сесії + +**Взаємодія в сесії:** + +```markdown +User: Remember that I prefer using React hooks instead of class components + for all new components. + +Claude: I'm adding that to your memory. Which memory file should this go in? + 1. Project memory (./CLAUDE.md) + 2. Personal memory (~/.claude/CLAUDE.md) + +User: Project memory + +Claude: ✅ Memory saved! + +Added to ./CLAUDE.md: +--- + +### Component Development +- Use functional components with React Hooks +- Prefer hooks over class components +- Custom hooks for reusable logic +- Use useCallback for event handlers +- Use useMemo for expensive computations +``` + +### Пам'ять у Claude Web/Desktop + +#### Хронологія синтезу пам'яті + +```mermaid +graph LR + A["Day 1: User
Conversations"] -->|24 hours| B["Day 2: Memory
Synthesis"] + B -->|Automatic| C["Memory Updated
Summarized"] + C -->|Loaded in| D["Day 2-N:
New Conversations"] + D -->|Add to| E["Memory"] + E -->|24 hours later| F["Memory Refreshed"] +``` + +**Приклад підсумку пам'яті:** + +```markdown +## Claude's Memory of User + +### Professional Background +- Senior full-stack developer with 8 years experience +- Focus on TypeScript/Node.js backends and React frontends +- Active open source contributor +- Interested in AI and machine learning + +### Project Context +- Currently building e-commerce platform +- Tech stack: Node.js, PostgreSQL, React 18, Docker +- Working with team of 5 developers +- Using CI/CD and blue-green deployments + +### Communication Preferences +- Prefers direct, concise explanations +- Likes visual diagrams and examples +- Appreciates code snippets +- Explains business logic in comments + +### Current Goals +- Improve API performance +- Increase test coverage to 90% +- Implement caching strategy +- Document architecture +``` + +### Порівняння функцій пам'яті + +| Функція | Claude Web/Desktop | Claude Code (CLAUDE.md) | +|---------|-------------------|------------------------| +| Авто-синтез | ✅ Кожні 24 год | ❌ Вручну | +| Між проєктами | ✅ Спільний | ❌ Специфічний для проєкту | +| Доступ команди | ✅ Спільні проєкти | ✅ Через Git | +| Пошук | ✅ Вбудований | ✅ Через `/memory` | +| Редагування | ✅ У чаті | ✅ Пряме редагування файлу | +| Імпорт/Експорт | ✅ Так | ✅ Копіювання/вставка | +| Постійність | ✅ 24 год+ | ✅ Необмежено | + +--- + +## Протокол MCP + +### Огляд + +MCP (Model Context Protocol) — це стандартизований спосіб доступу Claude до зовнішніх інструментів, API та джерел даних у реальному часі. На відміну від пам'яті, MCP забезпечує живий доступ до змінюваних даних. + +### Архітектура MCP + +```mermaid +graph TB + A["Claude"] + B["MCP Server"] + C["External Service"] + + A -->|Request: list_issues| B + B -->|Query| C + C -->|Data| B + B -->|Response| A + + A -->|Request: create_issue| B + B -->|Action| C + C -->|Result| B + B -->|Response| A +``` + +### Екосистема MCP + +```mermaid +graph TB + A["Claude"] -->|MCP| B["Filesystem
MCP Server"] + A -->|MCP| C["GitHub
MCP Server"] + A -->|MCP| D["Database
MCP Server"] + A -->|MCP| E["Slack
MCP Server"] + A -->|MCP| F["Google Docs
MCP Server"] + + B -->|File I/O| G["Local Files"] + C -->|API| H["GitHub Repos"] + D -->|Query| I["PostgreSQL/MySQL"] + E -->|Messages| J["Slack Workspace"] + F -->|Docs| K["Google Drive"] +``` + +### Процес налаштування MCP + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Config as Config File + participant Service as External Service + + User->>Claude: Type /mcp + Claude->>Claude: List available MCP servers + Claude->>User: Show options + User->>Claude: Select GitHub MCP + Claude->>Config: Update configuration + Config->>Claude: Activate connection + Claude->>Service: Test connection + Service-->>Claude: Authentication successful + Claude->>User: ✅ MCP connected! +``` + +### Таблиця доступних MCP-серверів + +| MCP-сервер | Призначення | Основні інструменти | Авторизація | Реальний час | +|------------|---------|--------------|------|-----------| +| **Filesystem** | Файлові операції | read, write, delete | Права ОС | ✅ Так | +| **GitHub** | Управління репозиторіями | list_prs, create_issue, push | OAuth | ✅ Так | +| **Slack** | Командна комунікація | send_message, list_channels | Token | ✅ Так | +| **Database** | SQL-запити | query, insert, update | Облікові дані | ✅ Так | +| **Google Docs** | Доступ до документів | read, write, share | OAuth | ✅ Так | +| **Asana** | Управління проєктами | create_task, update_status | API Key | ✅ Так | +| **Stripe** | Платіжні дані | list_charges, create_invoice | API Key | ✅ Так | +| **Memory** | Постійна пам'ять | store, retrieve, delete | Локальний | ❌ Ні | + +### Практичні приклади + +#### Приклад 1: Конфігурація GitHub MCP + +**Файл:** `.mcp.json` (область проєкту) або `~/.claude.json` (область користувача) + +```json +{ + "mcpServers": { + "github": { + "command": "npx", + "args": ["@modelcontextprotocol/server-github"], + "env": { + "GITHUB_TOKEN": "${GITHUB_TOKEN}" + } + } + } +} +``` + +**Доступні інструменти GitHub MCP:** + +~~~~markdown +# GitHub MCP Tools + +## Pull Request Management +- `list_prs` - List all PRs in repository +- `get_pr` - Get PR details including diff +- `create_pr` - Create new PR +- `update_pr` - Update PR description/title +- `merge_pr` - Merge PR to main branch +- `review_pr` - Add review comments + +Example request: +``` +/mcp__github__get_pr 456 + +# Returns: +Title: Add dark mode support +Author: @alice +Description: Implements dark theme using CSS variables +Status: OPEN +Reviewers: @bob, @charlie +``` + +## Issue Management +- `list_issues` - List all issues +- `get_issue` - Get issue details +- `create_issue` - Create new issue +- `close_issue` - Close issue +- `add_comment` - Add comment to issue + +## Repository Information +- `get_repo_info` - Repository details +- `list_files` - File tree structure +- `get_file_content` - Read file contents +- `search_code` - Search across codebase + +## Commit Operations +- `list_commits` - Commit history +- `get_commit` - Specific commit details +- `create_commit` - Create new commit +~~~~ + +#### Приклад 2: Налаштування Database MCP + +**Конфігурація:** + +```json +{ + "mcpServers": { + "database": { + "command": "npx", + "args": ["@modelcontextprotocol/server-database"], + "env": { + "DATABASE_URL": "postgresql://user:pass@localhost/mydb" + } + } + } +} +``` + +**Приклад використання:** + +```markdown +User: Fetch all users with more than 10 orders + +Claude: I'll query your database to find that information. + +# Using MCP database tool: +SELECT u.*, COUNT(o.id) as order_count +FROM users u +LEFT JOIN orders o ON u.id = o.user_id +GROUP BY u.id +HAVING COUNT(o.id) > 10 +ORDER BY order_count DESC; + +# Results: +- Alice: 15 orders +- Bob: 12 orders +- Charlie: 11 orders +``` + +#### Приклад 3: Робочий процес з кількома MCP + +**Сценарій: Генерація щоденного звіту** + +```markdown +# Daily Report Workflow using Multiple MCPs + +## Setup +1. GitHub MCP - fetch PR metrics +2. Database MCP - query sales data +3. Slack MCP - post report +4. Filesystem MCP - save report + +## Workflow + +### Step 1: Fetch GitHub Data +/mcp__github__list_prs completed:true last:7days + +Output: +- Total PRs: 42 +- Average merge time: 2.3 hours +- Review turnaround: 1.1 hours + +### Step 2: Query Database +SELECT COUNT(*) as sales, SUM(amount) as revenue +FROM orders +WHERE created_at > NOW() - INTERVAL '1 day' + +Output: +- Sales: 247 +- Revenue: $12,450 + +### Step 3: Generate Report +Combine data into HTML report + +### Step 4: Save to Filesystem +Write report.html to /reports/ + +### Step 5: Post to Slack +Send summary to #daily-reports channel + +Final Output: +✅ Report generated and posted +📊 47 PRs merged this week +💰 $12,450 in daily sales +``` + +#### Приклад 4: Операції Filesystem MCP + +**Конфігурація:** + +```json +{ + "mcpServers": { + "filesystem": { + "command": "npx", + "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"] + } + } +} +``` + +**Доступні операції:** + +| Операція | Команда | Призначення | +|-----------|---------|---------| +| Список файлів | `ls ~/projects` | Показати вміст каталогу | +| Читання файлу | `cat src/main.ts` | Прочитати вміст файлу | +| Запис файлу | `create docs/api.md` | Створити новий файл | +| Редагування файлу | `edit src/app.ts` | Змінити файл | +| Пошук | `grep "async function"` | Пошук у файлах | +| Видалення | `rm old-file.js` | Видалити файл | + +### MCP проти пам'яті: Матриця рішень + +```mermaid +graph TD + A["Need external data?"] + A -->|No| B["Use Memory"] + A -->|Yes| C["Does it change frequently?"] + C -->|No/Rarely| B + C -->|Yes/Often| D["Use MCP"] + + B -->|Stores| E["Preferences
Context
History"] + D -->|Accesses| F["Live APIs
Databases
Services"] + + style B fill:#e1f5ff + style D fill:#fff9c4 +``` + +### Патерн запит/відповідь + +```mermaid +sequenceDiagram + participant App as Claude + participant MCP as MCP Server + participant DB as Database + + App->>MCP: Request: "SELECT * FROM users WHERE id=1" + MCP->>DB: Execute query + DB-->>MCP: Result set + MCP-->>App: Return parsed data + App->>App: Process result + App->>App: Continue task + + Note over MCP,DB: Real-time access
No caching +``` + +--- + +## Навички агентів + +### Огляд + +Навички агентів — це повторно використовувані можливості, що викликаються моделлю, упаковані як теки з інструкціями, скриптами та ресурсами. Claude автоматично виявляє та використовує відповідні навички. + +### Архітектура навичок + +```mermaid +graph TB + A["Skill Directory"] + B["SKILL.md"] + C["YAML Metadata"] + D["Instructions"] + E["Scripts"] + F["Templates"] + + A --> B + B --> C + B --> D + E --> A + F --> A +``` + +### Процес завантаження навички + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude + participant System as System + participant Skill as Skill + + User->>Claude: "Create Excel report" + Claude->>System: Scan available skills + System->>System: Load skill metadata + Claude->>Claude: Match user request to skills + Claude->>Skill: Load xlsx skill SKILL.md + Skill-->>Claude: Return instructions + tools + Claude->>Claude: Execute skill + Claude->>User: Generate Excel file +``` + +### Таблиця типів та розташування навичок + +| Тип | Розташування | Область | Спільний | Синхронізація | Найкраще для | +|------|----------|-------|--------|------|----------| +| Вбудовані | Built-in | Глобальний | Усі користувачі | Авто | Створення документів | +| Персональні | `~/.claude/skills/` | Індивідуальний | Ні | Вручну | Персональна автоматизація | +| Проєктні | `.claude/skills/` | Команда | Так | Git | Стандарти команди | +| Плагінні | Через встановлення плагіна | Різний | Залежить | Авто | Інтегровані функції | + +### Вбудовані навички + +```mermaid +graph TB + A["Pre-built Skills"] + B["PowerPoint (pptx)"] + C["Excel (xlsx)"] + D["Word (docx)"] + E["PDF"] + + A --> B + A --> C + A --> D + A --> E + + B --> B1["Create presentations"] + B --> B2["Edit slides"] + C --> C1["Create spreadsheets"] + C --> C2["Analyze data"] + D --> D1["Create documents"] + D --> D2["Format text"] + E --> E1["Generate PDFs"] + E --> E2["Fill forms"] +``` + +### Комплектні навички + +Claude Code тепер включає 5 комплектних навичок, доступних одразу: + +| Навичка | Команда | Призначення | +|-------|---------|---------| +| **Simplify** | `/simplify` | Спрощення складного коду або пояснень | +| **Batch** | `/batch` | Виконання операцій над кількома файлами або елементами | +| **Debug** | `/debug` | Систематичне налагодження з аналізом кореневої причини | +| **Loop** | `/loop` | Планування повторюваних завдань за таймером | +| **Claude API** | `/claude-api` | Пряма взаємодія з Anthropic API | + +Ці комплектні навички завжди доступні і не потребують встановлення або конфігурації. + +### Практичні приклади + +#### Приклад 1: Навичка код-рев'ю + +**Структура каталогу:** + +``` +~/.claude/skills/code-review/ +├── SKILL.md +├── templates/ +│ ├── review-checklist.md +│ └── finding-template.md +└── scripts/ + ├── analyze-metrics.py + └── compare-complexity.py +``` + +**Файл:** `~/.claude/skills/code-review/SKILL.md` + +```yaml +--- +name: Code Review Specialist +description: Comprehensive code review with security, performance, and quality analysis +version: "1.0.0" +tags: + - code-review + - quality + - security +when_to_use: When users ask to review code, analyze code quality, or evaluate pull requests +effort: high +shell: bash +--- + +# Code Review Skill + +This skill provides comprehensive code review capabilities focusing on: + +1. **Security Analysis** + - Authentication/authorization issues + - Data exposure risks + - Injection vulnerabilities + - Cryptographic weaknesses + - Sensitive data logging + +2. **Performance Review** + - Algorithm efficiency (Big O analysis) + - Memory optimization + - Database query optimization + - Caching opportunities + - Concurrency issues + +3. **Code Quality** + - SOLID principles + - Design patterns + - Naming conventions + - Documentation + - Test coverage + +4. **Maintainability** + - Code readability + - Function size (should be < 50 lines) + - Cyclomatic complexity + - Dependency management + - Type safety + +## Review Template + +For each piece of code reviewed, provide: + +### Summary +- Overall quality assessment (1-5) +- Key findings count +- Recommended priority areas + +### Critical Issues (if any) +- **Issue**: Clear description +- **Location**: File and line number +- **Impact**: Why this matters +- **Severity**: Critical/High/Medium +- **Fix**: Code example + +### Findings by Category + +#### Security (if issues found) +List security vulnerabilities with examples + +#### Performance (if issues found) +List performance problems with complexity analysis + +#### Quality (if issues found) +List code quality issues with refactoring suggestions + +#### Maintainability (if issues found) +List maintainability problems with improvements +``` +## Python Script: analyze-metrics.py + +```python +#!/usr/bin/env python3 +import re +import sys + +def analyze_code_metrics(code): + """Analyze code for common metrics.""" + + # Count functions + functions = len(re.findall(r'^def\s+\w+', code, re.MULTILINE)) + + # Count classes + classes = len(re.findall(r'^class\s+\w+', code, re.MULTILINE)) + + # Average line length + lines = code.split('\n') + avg_length = sum(len(l) for l in lines) / len(lines) if lines else 0 + + # Estimate complexity + complexity = len(re.findall(r'\b(if|elif|else|for|while|and|or)\b', code)) + + return { + 'functions': functions, + 'classes': classes, + 'avg_line_length': avg_length, + 'complexity_score': complexity + } + +if __name__ == '__main__': + with open(sys.argv[1], 'r') as f: + code = f.read() + metrics = analyze_code_metrics(code) + for key, value in metrics.items(): + print(f"{key}: {value:.2f}") +``` + +## Python Script: compare-complexity.py + +```python +#!/usr/bin/env python3 +""" +Compare cyclomatic complexity of code before and after changes. +Helps identify if refactoring actually simplifies code structure. +""" + +import re +import sys +from typing import Dict, Tuple + +class ComplexityAnalyzer: + """Analyze code complexity metrics.""" + + def __init__(self, code: str): + self.code = code + self.lines = code.split('\n') + + def calculate_cyclomatic_complexity(self) -> int: + """ + Calculate cyclomatic complexity using McCabe's method. + Count decision points: if, elif, else, for, while, except, and, or + """ + complexity = 1 # Base complexity + + # Count decision points + decision_patterns = [ + r'\bif\b', + r'\belif\b', + r'\bfor\b', + r'\bwhile\b', + r'\bexcept\b', + r'\band\b(?!$)', + r'\bor\b(?!$)' + ] + + for pattern in decision_patterns: + matches = re.findall(pattern, self.code) + complexity += len(matches) + + return complexity + + def calculate_cognitive_complexity(self) -> int: + """ + Calculate cognitive complexity - how hard is it to understand? + Based on nesting depth and control flow. + """ + cognitive = 0 + nesting_depth = 0 + + for line in self.lines: + # Track nesting depth + if re.search(r'^\s*(if|for|while|def|class|try)\b', line): + nesting_depth += 1 + cognitive += nesting_depth + elif re.search(r'^\s*(elif|else|except|finally)\b', line): + cognitive += nesting_depth + + # Reduce nesting when unindenting + if line and not line[0].isspace(): + nesting_depth = 0 + + return cognitive + + def calculate_maintainability_index(self) -> float: + """ + Maintainability Index ranges from 0-100. + > 85: Excellent + > 65: Good + > 50: Fair + < 50: Poor + """ + lines = len(self.lines) + cyclomatic = self.calculate_cyclomatic_complexity() + cognitive = self.calculate_cognitive_complexity() + + # Simplified MI calculation + mi = 171 - 5.2 * (cyclomatic / lines) - 0.23 * (cognitive) - 16.2 * (lines / 1000) + + return max(0, min(100, mi)) + + def get_complexity_report(self) -> Dict: + """Generate comprehensive complexity report.""" + return { + 'cyclomatic_complexity': self.calculate_cyclomatic_complexity(), + 'cognitive_complexity': self.calculate_cognitive_complexity(), + 'maintainability_index': round(self.calculate_maintainability_index(), 2), + 'lines_of_code': len(self.lines), + 'avg_line_length': round(sum(len(l) for l in self.lines) / len(self.lines), 2) if self.lines else 0 + } + + +def compare_files(before_file: str, after_file: str) -> None: + """Compare complexity metrics between two code versions.""" + + with open(before_file, 'r') as f: + before_code = f.read() + + with open(after_file, 'r') as f: + after_code = f.read() + + before_analyzer = ComplexityAnalyzer(before_code) + after_analyzer = ComplexityAnalyzer(after_code) + + before_metrics = before_analyzer.get_complexity_report() + after_metrics = after_analyzer.get_complexity_report() + + print("=" * 60) + print("CODE COMPLEXITY COMPARISON") + print("=" * 60) + + print("\nBEFORE:") + print(f" Cyclomatic Complexity: {before_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {before_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {before_metrics['maintainability_index']}") + print(f" Lines of Code: {before_metrics['lines_of_code']}") + print(f" Avg Line Length: {before_metrics['avg_line_length']}") + + print("\nAFTER:") + print(f" Cyclomatic Complexity: {after_metrics['cyclomatic_complexity']}") + print(f" Cognitive Complexity: {after_metrics['cognitive_complexity']}") + print(f" Maintainability Index: {after_metrics['maintainability_index']}") + print(f" Lines of Code: {after_metrics['lines_of_code']}") + print(f" Avg Line Length: {after_metrics['avg_line_length']}") + + print("\nCHANGES:") + cyclomatic_change = after_metrics['cyclomatic_complexity'] - before_metrics['cyclomatic_complexity'] + cognitive_change = after_metrics['cognitive_complexity'] - before_metrics['cognitive_complexity'] + mi_change = after_metrics['maintainability_index'] - before_metrics['maintainability_index'] + loc_change = after_metrics['lines_of_code'] - before_metrics['lines_of_code'] + + print(f" Cyclomatic Complexity: {cyclomatic_change:+d}") + print(f" Cognitive Complexity: {cognitive_change:+d}") + print(f" Maintainability Index: {mi_change:+.2f}") + print(f" Lines of Code: {loc_change:+d}") + + print("\nASSESSMENT:") + if mi_change > 0: + print(" ✅ Code is MORE maintainable") + elif mi_change < 0: + print(" ⚠️ Code is LESS maintainable") + else: + print(" ➡️ Maintainability unchanged") + + if cyclomatic_change < 0: + print(" ✅ Complexity DECREASED") + elif cyclomatic_change > 0: + print(" ⚠️ Complexity INCREASED") + else: + print(" ➡️ Complexity unchanged") + + print("=" * 60) + + +if __name__ == '__main__': + if len(sys.argv) != 3: + print("Usage: python compare-complexity.py ") + sys.exit(1) + + compare_files(sys.argv[1], sys.argv[2]) +``` + +## Template: review-checklist.md + +```markdown +# Code Review Checklist + +## Security Checklist +- [ ] No hardcoded credentials or secrets +- [ ] Input validation on all user inputs +- [ ] SQL injection prevention (parameterized queries) +- [ ] CSRF protection on state-changing operations +- [ ] XSS prevention with proper escaping +- [ ] Authentication checks on protected endpoints +- [ ] Authorization checks on resources +- [ ] Secure password hashing (bcrypt, argon2) +- [ ] No sensitive data in logs +- [ ] HTTPS enforced + +## Performance Checklist +- [ ] No N+1 queries +- [ ] Appropriate use of indexes +- [ ] Caching implemented where beneficial +- [ ] No blocking operations on main thread +- [ ] Async/await used correctly +- [ ] Large datasets paginated +- [ ] Database connections pooled +- [ ] Regular expressions optimized +- [ ] No unnecessary object creation +- [ ] Memory leaks prevented + +## Quality Checklist +- [ ] Functions < 50 lines +- [ ] Clear variable naming +- [ ] No duplicate code +- [ ] Proper error handling +- [ ] Comments explain WHY, not WHAT +- [ ] No console.logs in production +- [ ] Type checking (TypeScript/JSDoc) +- [ ] SOLID principles followed +- [ ] Design patterns applied correctly +- [ ] Self-documenting code + +## Testing Checklist +- [ ] Unit tests written +- [ ] Edge cases covered +- [ ] Error scenarios tested +- [ ] Integration tests present +- [ ] Coverage > 80% +- [ ] No flaky tests +- [ ] Mock external dependencies +- [ ] Clear test names +``` + +## Template: finding-template.md + +~~~~markdown +# Code Review Finding Template + +Use this template when documenting each issue found during code review. + +--- + +## Issue: [TITLE] + +### Severity +- [ ] Critical (blocks deployment) +- [ ] High (should fix before merge) +- [ ] Medium (should fix soon) +- [ ] Low (nice to have) + +### Category +- [ ] Security +- [ ] Performance +- [ ] Code Quality +- [ ] Maintainability +- [ ] Testing +- [ ] Design Pattern +- [ ] Documentation + +### Location +**File:** `src/components/UserCard.tsx` + +**Lines:** 45-52 + +**Function/Method:** `renderUserDetails()` + +### Issue Description + +**What:** Describe what the issue is. + +**Why it matters:** Explain the impact and why this needs to be fixed. + +**Current behavior:** Show the problematic code or behavior. + +**Expected behavior:** Describe what should happen instead. + +### Code Example + +#### Current (Problematic) + +```typescript +// Shows the N+1 query problem +const users = fetchUsers(); +users.forEach(user => { + const posts = fetchUserPosts(user.id); // Query per user! + renderUserPosts(posts); +}); +``` + +#### Suggested Fix + +```typescript +// Optimized with JOIN query +const usersWithPosts = fetchUsersWithPosts(); +usersWithPosts.forEach(({ user, posts }) => { + renderUserPosts(posts); +}); +``` + +### Impact Analysis + +| Aspect | Impact | Severity | +|--------|--------|----------| +| Performance | 100+ queries for 20 users | High | +| User Experience | Slow page load | High | +| Scalability | Breaks at scale | Critical | +| Maintainability | Hard to debug | Medium | + +### Related Issues + +- Similar issue in `AdminUserList.tsx` line 120 +- Related PR: #456 +- Related issue: #789 + +### Additional Resources + +- [N+1 Query Problem](https://en.wikipedia.org/wiki/N%2B1_problem) +- [Database Join Documentation](https://docs.example.com/joins) + +### Reviewer Notes + +- This is a common pattern in this codebase +- Consider adding this to the code style guide +- Might be worth creating a helper function + +### Author Response (for feedback) + +*To be filled by the code author:* + +- [ ] Fix implemented in commit: `abc123` +- [ ] Fix status: Complete / In Progress / Needs Discussion +- [ ] Questions or concerns: (describe) + +--- + +## Finding Statistics (for Reviewer) + +When reviewing multiple findings, track: + +- **Total Issues Found:** X +- **Critical:** X +- **High:** X +- **Medium:** X +- **Low:** X + +**Recommendation:** ✅ Approve / ⚠️ Request Changes / 🔄 Needs Discussion + +**Overall Code Quality:** 1-5 stars +~~~~ + +## Usage Example + +~~~~markdown +User: Review this React component code + +Claude: I'll conduct a comprehensive code review using my Code Review Skill. + +[Loads SKILL.md] +[Analyzes code against checklist] +[Runs Python metrics script] +[Applies templates] + +## Code Review Results + +### Summary +Quality Score: 3.5/5 +Key Findings: 7 items +Priority Areas: Performance optimization, error handling + +### Critical Issues: 1 + +**Issue**: N+1 Query Problem +**Location**: UserComponent.tsx, lines 45-52 +**Impact**: Renders 100+ database queries for list of 20 users +**Severity**: High +**Fix**: +```javascript +// Before: N+1 queries +const users = fetchUsers(); +users.forEach(user => fetchUserPosts(user.id)); // 20+ queries + +// After: Single query with JOIN +const users = fetchUsersWithPosts(); // 1 query +``` + +### Performance Findings +- Missing pagination on large lists +- Recommendation: Use React.memo() for items +- Database query: Could be optimized with index + +### Quality Findings +- Function in line 20 is 127 lines (max: 50) +- Missing error boundary +- Props should have TypeScript types +~~~~ + +#### Приклад 2: Навичка голосу бренду + +**Структура каталогу:** + +``` +.claude/skills/brand-voice/ +├── SKILL.md +├── brand-guidelines.md +├── tone-examples.md +└── templates/ + ├── email-template.txt + ├── social-post-template.txt + └── blog-post-template.md +``` + +**Файл:** `.claude/skills/brand-voice/SKILL.md` + +```yaml +--- +name: Brand Voice Consistency +description: Ensure all communication matches brand voice and tone guidelines +tags: + - brand + - writing + - consistency +when_to_use: When creating marketing copy, customer communications, or public-facing content +--- + +# Brand Voice Skill + +## Overview +This skill ensures all communications maintain consistent brand voice, tone, and messaging. + +## Brand Identity + +### Mission +Help teams automate their development workflows with AI + +### Values +- **Simplicity**: Make complex things simple +- **Reliability**: Rock-solid execution +- **Empowerment**: Enable human creativity + +### Tone of Voice +- **Friendly but professional** - approachable without being casual +- **Clear and concise** - avoid jargon, explain technical concepts simply +- **Confident** - we know what we're doing +- **Empathetic** - understand user needs and pain points + +## Writing Guidelines + +### Do's ✅ +- Use "you" when addressing readers +- Use active voice: "Claude generates reports" not "Reports are generated by Claude" +- Start with value proposition +- Use concrete examples +- Keep sentences under 20 words +- Use lists for clarity +- Include calls-to-action + +### Don'ts ❌ +- Don't use corporate jargon +- Don't patronize or oversimplify +- Don't use "we believe" or "we think" +- Don't use ALL CAPS except for emphasis +- Don't create walls of text +- Don't assume technical knowledge + +## Vocabulary + +### ✅ Preferred Terms +- Claude (not "the Claude AI") +- Code generation (not "auto-coding") +- Agent (not "bot") +- Streamline (not "revolutionize") +- Integrate (not "synergize") + +### ❌ Avoid Terms +- "Cutting-edge" (overused) +- "Game-changer" (vague) +- "Leverage" (corporate-speak) +- "Utilize" (use "use") +- "Paradigm shift" (unclear) +``` +## Examples + +### ✅ Good Example +"Claude automates your code review process. Instead of manually checking each PR, Claude reviews security, performance, and quality—saving your team hours every week." + +Why it works: Clear value, specific benefits, action-oriented + +### ❌ Bad Example +"Claude leverages cutting-edge AI to provide comprehensive software development solutions." + +Why it doesn't work: Vague, corporate jargon, no specific value + +## Template: Email + +``` +Subject: [Clear, benefit-driven subject] + +Hi [Name], + +[Opening: What's the value for them] + +[Body: How it works / What they'll get] + +[Specific example or benefit] + +[Call to action: Clear next step] + +Best regards, +[Name] +``` + +## Template: Social Media + +``` +[Hook: Grab attention in first line] +[2-3 lines: Value or interesting fact] +[Call to action: Link, question, or engagement] +[Emoji: 1-2 max for visual interest] +``` + +## File: tone-examples.md +``` +Exciting announcement: +"Save 8 hours per week on code reviews. Claude reviews your PRs automatically." + +Empathetic support: +"We know deployments can be stressful. Claude handles testing so you don't have to worry." + +Confident product feature: +"Claude doesn't just suggest code. It understands your architecture and maintains consistency." + +Educational blog post: +"Let's explore how agents improve code review workflows. Here's what we learned..." +``` + +#### Приклад 3: Навичка генерації документації + +**Файл:** `.claude/skills/doc-generator/SKILL.md` + +~~~~yaml +--- +name: API Documentation Generator +description: Generate comprehensive, accurate API documentation from source code +version: "1.0.0" +tags: + - documentation + - api + - automation +when_to_use: When creating or updating API documentation +--- + +# API Documentation Generator Skill + +## Generates + +- OpenAPI/Swagger specifications +- API endpoint documentation +- SDK usage examples +- Integration guides +- Error code references +- Authentication guides + +## Documentation Structure + +### For Each Endpoint + +```markdown +## GET /api/v1/users/:id + +### Description +Brief explanation of what this endpoint does + +### Parameters + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| id | string | Yes | User ID | + +### Response + +**200 Success** +```json +{ + "id": "usr_123", + "name": "John Doe", + "email": "john@example.com", + "created_at": "2025-01-15T10:30:00Z" +} +``` + +**404 Not Found** +```json +{ + "error": "USER_NOT_FOUND", + "message": "User does not exist" +} +``` + +### Examples + +**cURL** +```bash +curl -X GET "https://api.example.com/api/v1/users/usr_123" \ + -H "Authorization: Bearer YOUR_TOKEN" +``` + +**JavaScript** +```javascript +const user = await fetch('/api/v1/users/usr_123', { + headers: { 'Authorization': 'Bearer token' } +}).then(r => r.json()); +``` + +**Python** +```python +response = requests.get( + 'https://api.example.com/api/v1/users/usr_123', + headers={'Authorization': 'Bearer token'} +) +user = response.json() +``` + +## Python Script: generate-docs.py + +```python +#!/usr/bin/env python3 +import ast +import json +from typing import Dict, List + +class APIDocExtractor(ast.NodeVisitor): + """Extract API documentation from Python source code.""" + + def __init__(self): + self.endpoints = [] + + def visit_FunctionDef(self, node): + """Extract function documentation.""" + if node.name.startswith('get_') or node.name.startswith('post_'): + doc = ast.get_docstring(node) + endpoint = { + 'name': node.name, + 'docstring': doc, + 'params': [arg.arg for arg in node.args.args], + 'returns': self._extract_return_type(node) + } + self.endpoints.append(endpoint) + self.generic_visit(node) + + def _extract_return_type(self, node): + """Extract return type from function annotation.""" + if node.returns: + return ast.unparse(node.returns) + return "Any" + +def generate_markdown_docs(endpoints: List[Dict]) -> str: + """Generate markdown documentation from endpoints.""" + docs = "# API Documentation\n\n" + + for endpoint in endpoints: + docs += f"## {endpoint['name']}\n\n" + docs += f"{endpoint['docstring']}\n\n" + docs += f"**Parameters**: {', '.join(endpoint['params'])}\n\n" + docs += f"**Returns**: {endpoint['returns']}\n\n" + docs += "---\n\n" + + return docs + +if __name__ == '__main__': + import sys + with open(sys.argv[1], 'r') as f: + tree = ast.parse(f.read()) + + extractor = APIDocExtractor() + extractor.visit(tree) + + markdown = generate_markdown_docs(extractor.endpoints) + print(markdown) +~~~~ +### Виявлення та виклик навичок + +```mermaid +graph TD + A["User Request"] --> B["Claude Analyzes"] + B -->|Scans| C["Available Skills"] + C -->|Metadata check| D["Skill Description Match?"] + D -->|Yes| E["Load SKILL.md"] + D -->|No| F["Try next skill"] + F -->|More skills?| D + F -->|No more| G["Use general knowledge"] + E --> H["Extract Instructions"] + H --> I["Execute Skill"] + I --> J["Return Results"] +``` + +### Навички проти інших функцій + +```mermaid +graph TB + A["Extending Claude"] + B["Slash Commands"] + C["Subagents"] + D["Memory"] + E["MCP"] + F["Skills"] + + A --> B + A --> C + A --> D + A --> E + A --> F + + B -->|User-invoked| G["Quick shortcuts"] + C -->|Auto-delegated| H["Isolated contexts"] + D -->|Persistent| I["Cross-session context"] + E -->|Real-time| J["External data access"] + F -->|Auto-invoked| K["Autonomous execution"] +``` + +--- + +## Плагіни Claude Code + +### Огляд + +Плагіни Claude Code — це комплектні збірки налаштувань (слеш-команди, субагенти, MCP-сервери та хуки), які встановлюються однією командою. Вони представляють найвищий рівень механізму розширення — об'єднують кілька функцій у цілісні пакети, якими можна ділитися. + +### Архітектура + +```mermaid +graph TB + A["Plugin"] + B["Slash Commands"] + C["Subagents"] + D["MCP Servers"] + E["Hooks"] + F["Configuration"] + + A -->|bundles| B + A -->|bundles| C + A -->|bundles| D + A -->|bundles| E + A -->|bundles| F +``` + +### Процес завантаження плагіна + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Plugin as Plugin Marketplace + participant Install as Installation + participant SlashCmds as Slash Commands + participant Subagents + participant MCPServers as MCP Servers + participant Hooks + participant Tools as Configured Tools + + User->>Claude: /plugin install pr-review + Claude->>Plugin: Download plugin manifest + Plugin-->>Claude: Return plugin definition + Claude->>Install: Extract components + Install->>SlashCmds: Configure + Install->>Subagents: Configure + Install->>MCPServers: Configure + Install->>Hooks: Configure + SlashCmds-->>Tools: Ready to use + Subagents-->>Tools: Ready to use + MCPServers-->>Tools: Ready to use + Hooks-->>Tools: Ready to use + Tools-->>Claude: Plugin installed ✅ +``` + +### Типи та дистрибуція плагінів + +| Тип | Область | Спільний | Авторитет | Приклади | +|------|-------|--------|-----------|----------| +| Офіційний | Глобальний | Усі користувачі | Anthropic | PR Review, Security Guidance | +| Спільноти | Публічний | Усі користувачі | Спільнота | DevOps, Data Science | +| Організаційний | Внутрішній | Члени команди | Компанія | Внутрішні стандарти, інструменти | +| Персональний | Індивідуальний | Один користувач | Розробник | Користувацькі робочі процеси | + +### Структура визначення плагіна + +```yaml +--- +name: plugin-name +version: "1.0.0" +description: "What this plugin does" +author: "Your Name" +license: MIT + +# Plugin metadata +tags: + - category + - use-case + +# Requirements +requires: + - claude-code: ">=1.0.0" + +# Components bundled +components: + - type: commands + path: commands/ + - type: agents + path: agents/ + - type: mcp + path: mcp/ + - type: hooks + path: hooks/ + +# Configuration +config: + auto_load: true + enabled_by_default: true +--- +``` + +### Структура плагіна + +``` +my-plugin/ +├── .claude-plugin/ +│ └── plugin.json +├── commands/ +│ ├── task-1.md +│ ├── task-2.md +│ └── workflows/ +├── agents/ +│ ├── specialist-1.md +│ ├── specialist-2.md +│ └── configs/ +├── skills/ +│ ├── skill-1.md +│ └── skill-2.md +├── hooks/ +│ └── hooks.json +├── .mcp.json +├── .lsp.json +├── settings.json +├── templates/ +│ └── issue-template.md +├── scripts/ +│ ├── helper-1.sh +│ └── helper-2.py +├── docs/ +│ ├── README.md +│ └── USAGE.md +└── tests/ + └── plugin.test.js +``` + +### Практичні приклади + +#### Приклад 1: Плагін код-рев'ю PR + +**Файл:** `.claude-plugin/plugin.json` + +```json +{ + "name": "pr-review", + "version": "1.0.0", + "description": "Complete PR review workflow with security, testing, and docs", + "author": { + "name": "Anthropic" + }, + "license": "MIT" +} +``` + +**Файл:** `commands/review-pr.md` + +```markdown +--- +name: Review PR +description: Start comprehensive PR review with security and testing checks +--- + +# PR Review + +This command initiates a complete pull request review including: + +1. Security analysis +2. Test coverage verification +3. Documentation updates +4. Code quality checks +5. Performance impact assessment +``` + +**Файл:** `agents/security-reviewer.md` + +```yaml +--- +name: security-reviewer +description: Security-focused code review +tools: read, grep, diff +--- + +# Security Reviewer + +Specializes in finding security vulnerabilities: +- Authentication/authorization issues +- Data exposure +- Injection attacks +- Secure configuration +``` + +**Встановлення:** + +```bash +/plugin install pr-review + +# Result: +# ✅ 3 slash commands installed +# ✅ 3 subagents configured +# ✅ 2 MCP servers connected +# ✅ 4 hooks registered +# ✅ Ready to use! +``` + +#### Приклад 2: Плагін DevOps + +**Компоненти:** + +``` +devops-automation/ +├── commands/ +│ ├── deploy.md +│ ├── rollback.md +│ ├── status.md +│ └── incident.md +├── agents/ +│ ├── deployment-specialist.md +│ ├── incident-commander.md +│ └── alert-analyzer.md +├── mcp/ +│ ├── github-config.json +│ ├── kubernetes-config.json +│ └── prometheus-config.json +├── hooks/ +│ ├── pre-deploy.js +│ ├── post-deploy.js +│ └── on-error.js +└── scripts/ + ├── deploy.sh + ├── rollback.sh + └── health-check.sh +``` + +#### Приклад 3: Плагін документації + +**Комплектні компоненти:** + +``` +documentation/ +├── commands/ +│ ├── generate-api-docs.md +│ ├── generate-readme.md +│ ├── sync-docs.md +│ └── validate-docs.md +├── agents/ +│ ├── api-documenter.md +│ ├── code-commentator.md +│ └── example-generator.md +├── mcp/ +│ ├── github-docs-config.json +│ └── slack-announce-config.json +└── templates/ + ├── api-endpoint.md + ├── function-docs.md + └── adr-template.md +``` + +### Маркетплейс плагінів + +```mermaid +graph TB + A["Plugin Marketplace"] + B["Official
Anthropic"] + C["Community
Marketplace"] + D["Enterprise
Registry"] + + A --> B + A --> C + A --> D + + B -->|Categories| B1["Development"] + B -->|Categories| B2["DevOps"] + B -->|Categories| B3["Documentation"] + + C -->|Search| C1["DevOps Automation"] + C -->|Search| C2["Mobile Dev"] + C -->|Search| C3["Data Science"] + + D -->|Internal| D1["Company Standards"] + D -->|Internal| D2["Legacy Systems"] + D -->|Internal| D3["Compliance"] +``` + +### Встановлення та життєвий цикл плагіна + +```mermaid +graph LR + A["Discover"] -->|Browse| B["Marketplace"] + B -->|Select| C["Plugin Page"] + C -->|View| D["Components"] + D -->|Install| E["/plugin install"] + E -->|Extract| F["Configure"] + F -->|Activate| G["Use"] + G -->|Check| H["Update"] + H -->|Available| G + G -->|Done| I["Disable"] + I -->|Later| J["Enable"] + J -->|Back| G +``` + +### Порівняння функцій плагінів + +| Функція | Слеш-команда | Навичка | Субагент | Плагін | +|---------|---------------|-------|----------|--------| +| **Встановлення** | Ручне копіювання | Ручне копіювання | Ручна конфігурація | Одна команда | +| **Час налаштування** | 5 хвилин | 10 хвилин | 15 хвилин | 2 хвилини | +| **Комплектність** | Один файл | Один файл | Один файл | Кілька | +| **Версіонування** | Вручну | Вручну | Вручну | Автоматичне | +| **Поширення в команді** | Копіювати файл | Копіювати файл | Копіювати файл | ID встановлення | +| **Оновлення** | Вручну | Вручну | Вручну | Авто-доступне | +| **Залежності** | Немає | Немає | Немає | Можуть бути | +| **Маркетплейс** | Ні | Ні | Ні | Так | +| **Дистрибуція** | Репозиторій | Репозиторій | Репозиторій | Маркетплейс | + +### Сценарії використання плагінів + +| Сценарій використання | Рекомендація | Чому | +|----------|-----------------|-----| +| **Онбординг команди** | ✅ Використовуйте плагін | Миттєве налаштування, усі конфігурації | +| **Налаштування фреймворку** | ✅ Використовуйте плагін | Комплектує команди, специфічні для фреймворку | +| **Корпоративні стандарти** | ✅ Використовуйте плагін | Централізована дистрибуція, контроль версій | +| **Швидка автоматизація задач** | ❌ Використовуйте команду | Надмірна складність | +| **Одна предметна область** | ❌ Використовуйте навичку | Занадто важкий, краще навичка | +| **Спеціалізований аналіз** | ❌ Використовуйте субагента | Створіть вручну або використовуйте навичку | +| **Доступ до живих даних** | ❌ Використовуйте MCP | Автономний, не комплектуйте | + +### Коли створювати плагін + +```mermaid +graph TD + A["Should I create a plugin?"] + A -->|Need multiple components| B{"Multiple commands
or subagents
or MCPs?"} + B -->|Yes| C["✅ Create Plugin"] + B -->|No| D["Use Individual Feature"] + A -->|Team workflow| E{"Share with
team?"} + E -->|Yes| C + E -->|No| F["Keep as Local Setup"] + A -->|Complex setup| G{"Needs auto
configuration?"} + G -->|Yes| C + G -->|No| D +``` + +### Публікація плагіна + +**Кроки для публікації:** + +1. Створіть структуру плагіна з усіма компонентами +2. Напишіть маніфест `.claude-plugin/plugin.json` +3. Створіть `README.md` з документацією +4. Протестуйте локально за допомогою `/plugin install ./my-plugin` +5. Надішліть на маркетплейс плагінів +6. Пройдіть перевірку та затвердження +7. Опубліковано на маркетплейсі +8. Користувачі можуть встановити однією командою + +**Приклад подачі:** + +~~~~markdown +# PR Review Plugin + +## Description +Complete PR review workflow with security, testing, and documentation checks. + +## What's Included +- 3 slash commands for different review types +- 3 specialized subagents +- GitHub and CodeQL MCP integration +- Automated security scanning hooks + +## Installation +```bash +/plugin install pr-review +``` + +## Features +✅ Security analysis +✅ Test coverage checking +✅ Documentation verification +✅ Code quality assessment +✅ Performance impact analysis + +## Usage +```bash +/review-pr +/check-security +/check-tests +``` + +## Requirements +- Claude Code 1.0+ +- GitHub access +- CodeQL (optional) +~~~~ + +### Плагін проти ручної конфігурації + +**Ручне налаштування (2+ години):** +- Встановити слеш-команди одну за одною +- Створити субагентів окремо +- Налаштувати MCP окремо +- Налаштувати хуки вручну +- Задокументувати все +- Поширити в команді (сподіваючись на правильну конфігурацію) + +**З плагіном (2 хвилини):** +```bash +/plugin install pr-review +# ✅ Everything installed and configured +# ✅ Ready to use immediately +# ✅ Team can reproduce exact setup +``` + +--- + +## Порівняння та інтеграція + +### Матриця порівняння функцій + +| Функція | Виклик | Постійність | Область | Сценарій використання | +|---------|-----------|------------|-------|----------| +| **Слеш-команди** | Ручний (`/cmd`) | Лише сесія | Одна команда | Швидкі ярлики | +| **Субагенти** | Авто-делеговані | Ізольований контекст | Спеціалізоване завдання | Розподіл завдань | +| **Пам'ять** | Авто-завантажена | Між сесіями | Контекст користувача/команди | Довгострокове навчання | +| **Протокол MCP** | Авто-запити | Реальний час, зовнішній | Доступ до живих даних | Динамічна інформація | +| **Навички** | Авто-викликані | На основі файлової системи | Повторно використовувана експертиза | Автоматизовані робочі процеси | + +### Хронологія взаємодії + +```mermaid +graph LR + A["Session Start"] -->|Load| B["Memory (CLAUDE.md)"] + B -->|Discover| C["Available Skills"] + C -->|Register| D["Slash Commands"] + D -->|Connect| E["MCP Servers"] + E -->|Ready| F["User Interaction"] + + F -->|Type /cmd| G["Slash Command"] + F -->|Request| H["Skill Auto-Invoke"] + F -->|Query| I["MCP Data"] + F -->|Complex task| J["Delegate to Subagent"] + + G -->|Uses| B + H -->|Uses| B + I -->|Uses| B + J -->|Uses| B +``` + +### Практичний приклад інтеграції: Автоматизація підтримки клієнтів + +#### Архітектура + +```mermaid +graph TB + User["Customer Email"] -->|Receives| Router["Support Router"] + + Router -->|Analyze| Memory["Memory
Customer history"] + Router -->|Lookup| MCP1["MCP: Customer DB
Previous tickets"] + Router -->|Check| MCP2["MCP: Slack
Team status"] + + Router -->|Route Complex| Sub1["Subagent: Tech Support
Context: Technical issues"] + Router -->|Route Simple| Sub2["Subagent: Billing
Context: Payment issues"] + Router -->|Route Urgent| Sub3["Subagent: Escalation
Context: Priority handling"] + + Sub1 -->|Format| Skill1["Skill: Response Generator
Brand voice maintained"] + Sub2 -->|Format| Skill2["Skill: Response Generator"] + Sub3 -->|Format| Skill3["Skill: Response Generator"] + + Skill1 -->|Generate| Output["Formatted Response"] + Skill2 -->|Generate| Output + Skill3 -->|Generate| Output + + Output -->|Post| MCP3["MCP: Slack
Notify team"] + Output -->|Send| Reply["Customer Reply"] +``` + +#### Потік запитів + +```markdown +## Customer Support Request Flow + +### 1. Incoming Email +"I'm getting error 500 when trying to upload files. This is blocking my workflow!" + +### 2. Memory Lookup +- Loads CLAUDE.md with support standards +- Checks customer history: VIP customer, 3rd incident this month + +### 3. MCP Queries +- GitHub MCP: List open issues (finds related bug report) +- Database MCP: Check system status (no outages reported) +- Slack MCP: Check if engineering is aware + +### 4. Skill Detection & Loading +- Request matches "Technical Support" skill +- Loads support response template from Skill + +### 5. Subagent Delegation +- Routes to Tech Support Subagent +- Provides context: customer history, error details, known issues +- Subagent has full access to: read, bash, grep tools + +### 6. Subagent Processing +Tech Support Subagent: +- Searches codebase for 500 error in file upload +- Finds recent change in commit 8f4a2c +- Creates workaround documentation + +### 7. Skill Execution +Response Generator Skill: +- Uses Brand Voice guidelines +- Formats response with empathy +- Includes workaround steps +- Links to related documentation + +### 8. MCP Output +- Posts update to #support Slack channel +- Tags engineering team +- Updates ticket in Jira MCP + +### 9. Response +Customer receives: +- Empathetic acknowledgment +- Explanation of cause +- Immediate workaround +- Timeline for permanent fix +- Link to related issues +``` + +### Повна оркестрація функцій + +```mermaid +sequenceDiagram + participant User + participant Claude as Claude Code + participant Memory as Memory
CLAUDE.md + participant MCP as MCP Servers + participant Skills as Skills + participant SubAgent as Subagents + + User->>Claude: Request: "Build auth system" + Claude->>Memory: Load project standards + Memory-->>Claude: Auth standards, team practices + Claude->>MCP: Query GitHub for similar implementations + MCP-->>Claude: Code examples, best practices + Claude->>Skills: Detect matching Skills + Skills-->>Claude: Security Review Skill + Testing Skill + Claude->>SubAgent: Delegate implementation + SubAgent->>SubAgent: Build feature + Claude->>Skills: Apply Security Review Skill + Skills-->>Claude: Security checklist results + Claude->>SubAgent: Delegate testing + SubAgent-->>Claude: Test results + Claude->>User: Complete system delivered +``` + +### Коли використовувати кожну функцію + +```mermaid +graph TD + A["New Task"] --> B{Type of Task?} + + B -->|Repeated workflow| C["Slash Command"] + B -->|Need real-time data| D["MCP Protocol"] + B -->|Remember for next time| E["Memory"] + B -->|Specialized subtask| F["Subagent"] + B -->|Domain-specific work| G["Skill"] + + C --> C1["✅ Team shortcut"] + D --> D1["✅ Live API access"] + E --> E1["✅ Persistent context"] + F --> F1["✅ Parallel execution"] + G --> G1["✅ Auto-invoked expertise"] +``` + +### Дерево рішень для вибору + +```mermaid +graph TD + Start["Need to extend Claude?"] + + Start -->|Quick repeated task| A{"Manual or Auto?"} + A -->|Manual| B["Slash Command"] + A -->|Auto| C["Skill"] + + Start -->|Need external data| D{"Real-time?"} + D -->|Yes| E["MCP Protocol"] + D -->|No/Cross-session| F["Memory"] + + Start -->|Complex project| G{"Multiple roles?"} + G -->|Yes| H["Subagents"] + G -->|No| I["Skills + Memory"] + + Start -->|Long-term context| J["Memory"] + Start -->|Team workflow| K["Slash Command +
Memory"] + Start -->|Full automation| L["Skills +
Subagents +
MCP"] +``` + +--- + +## Зведена таблиця + +| Аспект | Слеш-команди | Субагенти | Пам'ять | MCP | Навички | Плагіни | +|--------|---|---|---|---|---|---| +| **Складність налаштування** | Легко | Середньо | Легко | Середньо | Середньо | Легко | +| **Крива навчання** | Низька | Середня | Низька | Середня | Середня | Низька | +| **Користь для команди** | Висока | Висока | Середня | Висока | Висока | Дуже висока | +| **Рівень автоматизації** | Низький | Високий | Середній | Високий | Високий | Дуже високий | +| **Управління контекстом** | Одна сесія | Ізольований | Постійний | Реальний час | Постійний | Усі функції | +| **Навантаження з обслуговування** | Низьке | Середнє | Низьке | Середнє | Середнє | Низьке | +| **Масштабованість** | Добра | Відмінна | Добра | Відмінна | Відмінна | Відмінна | +| **Можливість поширення** | Задовільна | Задовільна | Добра | Добра | Добра | Відмінна | +| **Версіонування** | Вручну | Вручну | Вручну | Вручну | Вручну | Автоматичне | +| **Встановлення** | Ручне копіювання | Ручна конфігурація | Н/Д | Ручна конфігурація | Ручне копіювання | Одна команда | + +--- + +## Короткий посібник для початку + +### Тиждень 1: Почніть просто +- Створіть 2-3 слеш-команди для типових завдань +- Увімкніть пам'ять у налаштуваннях +- Задокументуйте стандарти команди в CLAUDE.md + +### Тиждень 2: Додайте доступ у реальному часі +- Налаштуйте 1 MCP (GitHub або Database) +- Використовуйте `/mcp` для конфігурації +- Запитуйте живі дані у ваших робочих процесах + +### Тиждень 3: Розподіліть роботу +- Створіть першого субагента для конкретної ролі +- Використовуйте команду `/agents` +- Протестуйте делегування з простим завданням + +### Тиждень 4: Автоматизуйте все +- Створіть першу навичку для повторюваної автоматизації +- Використовуйте маркетплейс навичок або створіть власну +- Об'єднайте усі функції для повного робочого процесу + +### Постійно +- Переглядайте та оновлюйте пам'ять щомісяця +- Додавайте нові навички за потребою +- Оптимізуйте MCP-запити +- Вдосконалюйте промпти субагентів + +--- + +## Хуки + +### Огляд + +Хуки — це shell-команди на основі подій, які виконуються автоматично у відповідь на події Claude Code. Вони забезпечують автоматизацію, валідацію та користувацькі робочі процеси без ручного втручання. + +### Події хуків + +Claude Code підтримує **25 подій хуків** у чотирьох типах хуків (command, http, prompt, agent): + +| Подія хука | Тригер | Сценарії використання | +|------------|---------|-----------| +| **SessionStart** | Початок/відновлення/очищення/ущільнення сесії | Налаштування середовища, ініціалізація | +| **InstructionsLoaded** | Завантажено CLAUDE.md або файл правил | Валідація, трансформація, доповнення | +| **UserPromptSubmit** | Користувач надсилає промпт | Валідація вводу, фільтрація промптів | +| **PreToolUse** | Перед запуском будь-якого інструменту | Валідація, шлюзи затвердження, логування | +| **PermissionRequest** | Показано діалог дозволу | Авто-затвердження/відхилення | +| **PostToolUse** | Після успішного виконання інструменту | Авто-форматування, сповіщення, очищення | +| **PostToolUseFailure** | Помилка виконання інструменту | Обробка помилок, логування | +| **Notification** | Надіслано сповіщення | Алертинг, зовнішні інтеграції | +| **SubagentStart** | Створено субагента | Ін'єкція контексту, ініціалізація | +| **SubagentStop** | Субагент завершив роботу | Валідація результату, логування | +| **Stop** | Claude завершив відповідь | Генерація підсумку, завдання очищення | +| **StopFailure** | Помилка API завершує хід | Відновлення після помилки, логування | +| **TeammateIdle** | Тімейт у команді агентів без роботи | Розподіл роботи, координація | +| **TaskCompleted** | Завдання позначено як виконане | Пост-обробка завдання | +| **TaskCreated** | Завдання створено через TaskCreate | Відстеження завдань, логування | +| **ConfigChange** | Зміна конфігураційного файлу | Валідація, поширення | +| **CwdChanged** | Зміна робочого каталогу | Налаштування для конкретного каталогу | +| **FileChanged** | Зміна відстежуваного файлу | Моніторинг файлів, тригери перебудови | +| **PreCompact** | Перед ущільненням контексту | Збереження стану | +| **PostCompact** | Після завершення ущільнення | Дії після ущільнення | +| **WorktreeCreate** | Створення worktree | Налаштування середовища, встановлення залежностей | +| **WorktreeRemove** | Видалення worktree | Очищення, звільнення ресурсів | +| **Elicitation** | MCP-сервер запитує введення користувача | Валідація вводу | +| **ElicitationResult** | Користувач відповідає на запит | Обробка відповіді | +| **SessionEnd** | Завершення сесії | Очищення, фінальне логування | + +### Типові хуки + +Хуки налаштовуються у `~/.claude/settings.json` (рівень користувача) або `.claude/settings.json` (рівень проєкту): + +```json +{ + "hooks": { + "PostToolUse": [ + { + "matcher": "Write", + "hooks": [ + { + "type": "command", + "command": "prettier --write $CLAUDE_FILE_PATH" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Edit", + "hooks": [ + { + "type": "command", + "command": "eslint $CLAUDE_FILE_PATH" + } + ] + } + ] + } +} +``` + +### Змінні середовища хуків + +- `$CLAUDE_FILE_PATH` — Шлях до файлу, що редагується/записується +- `$CLAUDE_TOOL_NAME` — Назва інструменту, що використовується +- `$CLAUDE_SESSION_ID` — Ідентифікатор поточної сесії +- `$CLAUDE_PROJECT_DIR` — Шлях до каталогу проєкту + +### Найкращі практики + +✅ **Рекомендовано:** +- Тримайте хуки швидкими (< 1 секунди) +- Використовуйте хуки для валідації та автоматизації +- Обробляйте помилки коректно +- Використовуйте абсолютні шляхи + +❌ **Не рекомендовано:** +- Робити хуки інтерактивними +- Використовувати хуки для тривалих завдань +- Жорстко прописувати облікові дані + +**Дивіться**: [06-hooks/](06-hooks/) для детальних прикладів + +--- + +## Контрольні точки та відкат + +### Огляд + +Контрольні точки дозволяють зберігати стан розмови та повертатися до попередніх моментів, забезпечуючи безпечне експериментування та дослідження різних підходів. + +### Ключові концепції + +| Концепція | Опис | +|---------|-------------| +| **Контрольна точка** | Знімок стану розмови, включаючи повідомлення, файли та контекст | +| **Відкат** | Повернення до попередньої контрольної точки з відкиданням подальших змін | +| **Точка розгалуження** | Контрольна точка, від якої досліджуються кілька підходів | + +### Доступ до контрольних точок + +Контрольні точки створюються автоматично з кожним промптом користувача. Для відкату: + +```bash +# Press Esc twice to open the checkpoint browser +Esc + Esc + +# Or use the /rewind command +/rewind +``` + +При виборі контрольної точки доступні п'ять варіантів: +1. **Відновити код і розмову** — Повернути обидва до цього моменту +2. **Відновити розмову** — Повернути повідомлення, залишити поточний код +3. **Відновити код** — Повернути файли, залишити розмову +4. **Підсумувати звідси** — Стиснути розмову у підсумок +5. **Скасувати** — Відмінити + +### Сценарії використання + +| Сценарій | Робочий процес | +|----------|----------| +| **Дослідження підходів** | Зберегти → Спробувати A → Зберегти → Відкат → Спробувати B → Порівняти | +| **Безпечний рефакторинг** | Зберегти → Рефакторинг → Тест → Якщо невдача: Відкат | +| **A/B тестування** | Зберегти → Дизайн A → Зберегти → Відкат → Дизайн B → Порівняти | +| **Відновлення після помилки** | Помітити проблему → Відкат до останнього робочого стану | + +### Конфігурація + +```json +{ + "autoCheckpoint": true +} +``` + +**Дивіться**: [08-checkpoints/](08-checkpoints/) для детальних прикладів + +--- + +## Просунуті функції + +### Режим планування + +Створюйте детальні плани реалізації перед кодуванням. + +**Активація:** +```bash +/plan Implement user authentication system +``` + +**Переваги:** +- Чіткий план з оцінкою часу +- Оцінка ризиків +- Систематичне розбиття на завдання +- Можливість перегляду та модифікації + +### Розширене мислення + +Глибокий аналіз для складних проблем. + +**Активація:** +- Перемикання `Alt+T` (або `Option+T` на macOS) під час сесії +- Встановіть змінну середовища `MAX_THINKING_TOKENS` для програмного контролю + +```bash +# Enable extended thinking via environment variable +export MAX_THINKING_TOKENS=50000 +claude -p "Should we use microservices or monolith?" +``` + +**Переваги:** +- Ретельний аналіз компромісів +- Кращі архітектурні рішення +- Врахування крайніх випадків +- Систематична оцінка + +### Фонові завдання + +Запускайте тривалі операції без блокування розмови. + +**Використання:** +```bash +User: Run tests in background + +Claude: Started task bg-1234 + +/task list # Show all tasks +/task status bg-1234 # Check progress +/task show bg-1234 # View output +/task cancel bg-1234 # Cancel task +``` + +### Режими дозволів + +Контролюйте, що Claude може робити. + +| Режим | Опис | Сценарій використання | +|------|-------------|----------| +| **default** | Стандартні дозволи з запитами для чутливих дій | Загальна розробка | +| **acceptEdits** | Автоматично приймати редагування файлів без підтвердження | Довірені робочі процеси редагування | +| **plan** | Лише аналіз і планування, без модифікації файлів | Код-рев'ю, планування архітектури | +| **auto** | Автоматично затверджувати безпечні дії, запитувати лише ризиковані | Збалансована автономія з безпекою | +| **dontAsk** | Виконувати всі дії без запитів підтвердження | Досвідчені користувачі, автоматизація | +| **bypassPermissions** | Повний необмежений доступ, без перевірок безпеки | CI/CD-конвеєри, довірені скрипти | + +**Використання:** +```bash +claude --permission-mode plan # Read-only analysis +claude --permission-mode acceptEdits # Auto-accept edits +claude --permission-mode auto # Auto-approve safe actions +claude --permission-mode dontAsk # No confirmation prompts +``` + +### Headless-режим (режим друку) + +Запускайте Claude Code без інтерактивного введення для автоматизації та CI/CD за допомогою прапорця `-p` (print). + +**Використання:** +```bash +# Run specific task +claude -p "Run all tests" + +# Pipe input for analysis +cat error.log | claude -p "explain this error" + +# CI/CD integration (GitHub Actions) +- name: AI Code Review + run: claude -p "Review PR changes and report issues" + +# JSON output for scripting +claude -p --output-format json "list all functions in src/" +``` + +### Заплановані завдання + +Запускайте завдання за розкладом за допомогою команди `/loop`. + +**Використання:** +```bash +/loop every 30m "Run tests and report failures" +/loop every 2h "Check for dependency updates" +/loop every 1d "Generate daily summary of code changes" +``` + +Заплановані завдання виконуються у фоновому режимі та повідомляють про результати після завершення. Вони корисні для безперервного моніторингу, періодичних перевірок та автоматизованих робочих процесів обслуговування. + +### Інтеграція з Chrome + +Claude Code може інтегруватися з браузером Chrome для завдань веб-автоматизації. Це забезпечує можливості навігації по веб-сторінках, заповнення форм, створення знімків екрану та витягування даних з вебсайтів безпосередньо у вашому робочому процесі розробки. + +### Управління сесіями + +Керуйте кількома робочими сесіями. + +**Команди:** +```bash +/resume # Resume a previous conversation +/rename "Feature" # Name the current session +/fork # Fork into a new session +claude -c # Continue most recent conversation +claude -r "Feature" # Resume session by name/ID +``` + +### Інтерактивні функції + +**Клавіатурні скорочення:** +- `Ctrl + R` — Пошук в історії команд +- `Tab` — Автодоповнення +- `↑ / ↓` — Історія команд +- `Ctrl + L` — Очистити екран + +**Багаторядковий ввід:** +```bash +User: \ +> Long complex prompt +> spanning multiple lines +> \end +``` + +### Конфігурація + +Повний приклад конфігурації: + +```json +{ + "planning": { + "autoEnter": true, + "requireApproval": true + }, + "extendedThinking": { + "enabled": true, + "showThinkingProcess": true + }, + "backgroundTasks": { + "enabled": true, + "maxConcurrentTasks": 5 + }, + "permissions": { + "mode": "default" + } +} +``` + +**Дивіться**: [09-advanced-features/](09-advanced-features/) для повного посібника + +--- + +## Ресурси + +- [Документація Claude Code](https://code.claude.com/docs/en/overview) +- [Документація Anthropic](https://docs.anthropic.com) +- [MCP-сервери на GitHub](https://github.com/modelcontextprotocol/servers) +- [Кулінарна книга Anthropic](https://github.com/anthropics/anthropic-cookbook) + +--- + +*Останнє оновлення: квітень 2026* +*Для Claude Haiku 4.5, Sonnet 4.6 та Opus 4.6* +*Тепер включає: хуки, контрольні точки, режим планування, розширене мислення, фонові завдання, режими дозволів (6 режимів), headless-режим, управління сесіями, авто-пам'ять, команди агентів, заплановані завдання, інтеграцію з Chrome, канали, голосовий ввід та комплектні навички* + +--- +**Last Updated**: April 9, 2026 +**Claude Code Version**: 2.1.97 diff --git a/uk/clean-code-rules.md b/uk/clean-code-rules.md new file mode 100644 index 0000000..1514691 --- /dev/null +++ b/uk/clean-code-rules.md @@ -0,0 +1,115 @@ + + + + +# Правила чистого коду для AI-генерації коду + +Ці правила спрямовують генерацію коду для створення підтримуваного, професійної якості коду. + +## Змістовні назви +- Використовуйте назви, що розкривають намір та пояснюють чому щось існує +- Уникайте дезінформації та безглуздих розрізнень (напр., `data`, `info`, `manager`) +- Використовуйте вимовні, такі що легко шукаються назви +- Назви класів: іменники (напр., `UserAccount`, `PaymentProcessor`) +- Назви методів: дієслова (напр., `calculateTotal`, `sendEmail`) +- Уникайте ментального маппінгу та кодувань (Угорська нотація, префікси) + +## Функції +- Тримайте функції маленькими (< 20 рядків ідеально) +- Робіть лише одну річ — Принцип єдиної відповідальності +- Один рівень абстракції на функцію +- Обмежуйте аргументи: 0-2 ідеально, 3 максимум, уникайте аргументів-прапорців +- Без побічних ефектів — функція повинна робити те, що каже її назва +- Розділяйте команди (зміна стану) від запитів (повернення інформації) +- Надавайте перевагу виключенням над кодами помилок + +## Коментарі +- Код повинен бути самопояснювальним — уникайте коментарів коли можливо +- Корисні коментарі: юридична інформація, попередження, TODO, документація публічного API +- Погані коментарі: надлишкові, що вводять в оману, або пояснюють поганий код +- Ніколи не коментуйте код — видаляйте його (система контролю версій зберігає історію) +- Якщо потрібен коментар, подумайте про рефакторинг коду + +## Форматування +- Тримайте файли маленькими та зосередженими +- Вертикальне форматування: пов'язані концепції поруч, порожні рядки розділяють концепції +- Горизонтальне форматування: обмежуйте довжину рядка (80-120 символів) +- Використовуйте консистентні відступи та командний стиль +- Групуйте пов'язані функції разом + +## Об'єкти та структури даних +- Об'єкти: ховають дані за абстракціями, відкривають поведінку через методи +- Структури даних: відкривають дані, мають мінімальну поведінку +- Закон Деметри: спілкуйтесь тільки з безпосередніми друзями, уникайте `a.getB().getC().doSomething()` +- Не відкривайте внутрішню структуру через геттери/сеттери наосліп + +## Обробка помилок +- Використовуйте виключення, а не коди повернення або прапорці помилок +- Пишіть `try-catch-finally` першим, коли код може не виконатись +- Надавайте контекст у повідомленнях виключень +- Не повертайте `null` — повертайте порожні колекції або використовуйте Optional/Maybe +- Не передавайте `null` як аргументи + +## Класи +- Маленькі класи: вимірюються відповідальностями, а не рядками +- Принцип єдиної відповідальності: одна причина для зміни +- Висока зв'язність (cohesion): змінні класу використовуються багатьма методами +- Низька зв'язаність (coupling): мінімальні залежності між класами +- Принцип відкритості/закритості: відкритий для розширення, закритий для модифікації + +## Юніт-тести +- Швидкі, Незалежні, Повторювані, Самоперевіряючі, Своєчасні (F.I.R.S.T.) +- Один assert на тест (або одна концепція) +- Якість тестового коду дорівнює якості продакшен-коду +- Читабельні назви тестів, що описують що тестується +- Патерн Arrange-Act-Assert + +## Принципи якості коду +- **DRY (Don't Repeat Yourself)**: Без дублювання +- **YAGNI (You Aren't Gonna Need It)**: Не будуйте для гіпотетичного майбутнього +- **KISS (Keep It Simple)**: Уникайте зайвої складності +- **Правило скаута**: Залишайте код чистішим, ніж ви його знайшли + +## Code Smells, яких варто уникати +- Довгі функції або класи +- Дублювання коду +- Мертвий код (невикористані змінні, функції, параметри) +- Feature envy (метод більше цікавиться іншим класом) +- Inappropriate intimacy (класи знають занадто багато один про одного) +- Довгі списки параметрів +- Primitive obsession (надмірне використання примітивів замість маленьких об'єктів) +- Switch/case (розгляньте поліморфізм) +- Тимчасові поля (змінні класу використовуються лише іноді) + +## Конкурентність +- Тримайте конкурентний код окремо від іншого коду +- Обмежуйте область синхронізованих/заблокованих даних +- Використовуйте потокобезпечні колекції +- Тримайте синхронізовані секції маленькими +- Знайте свої моделі виконання та примітиви + +## Проєктування систем +- Відокремлюйте конструювання від використання (впровадження залежностей) +- Використовуйте фабрики, будівельники для складного створення об'єктів +- Програмуйте на інтерфейси, а не на реалізації +- Надавайте перевагу композиції над успадкуванням +- Застосовуйте патерни проєктування коли вони спрощують, а не для демонстрації + +## Рефакторинг +- Рефакторіть безперервно, а не великими порціями +- Завжди майте тести, що проходять, до та після +- Маленькі кроки: одна зміна за раз +- Поширені рефакторинги: Витягнути метод, Перейменувати, Перемістити, Вбудувати + +## Документація +- Самодокументований код > коментарі > зовнішня документація +- Публічні API потребують чіткої документації +- Включайте приклади в документацію +- Тримайте документацію близько до коду (ідеально — в коді) + +--- + +**Основна філософія**: Код читається в 10 разів частіше, ніж пишеться. Оптимізуйте для читабельності та підтримуваності, а не для хитрості. + +--- +**Останнє оновлення**: Квітень 2026 diff --git a/uk/docs/ROADMAP-20260401.md b/uk/docs/ROADMAP-20260401.md new file mode 100644 index 0000000..e333c56 --- /dev/null +++ b/uk/docs/ROADMAP-20260401.md @@ -0,0 +1,153 @@ +# Roadmap: claude-howto 2026–2027 + +> April 2026 – March 2027 · Dual-Layer Knowledge Base | Full plan: `TASKS-20260401.md` + +--- + +## Vision + +Transform claude-howto from a static tutorial repo into a **living, dual-audience knowledge system**: + +- **For humans** — interactive, scenario-based learning with progressive difficulty, decision trees, and named patterns that experts bookmark +- **For AI agents** — structured metadata index that agents query before performing Claude Code tasks, making this repo infrastructure, not just content + +No competitor targets AI agents as a primary audience. This is the moat. + +--- + +## The 7 Pillars + +| # | Pillar | What it delivers | +|---|--------|-----------------| +| P1 | Fun Layer | Scenario intros + "Try It Now" blocks in every module | +| P2 | AI Agent Index | Generated `agent-manifest.json` + `AGENT-INDEX.md` + lookup skill | +| P3a | Expert Reference (in-module) | Decision trees + named patterns per module | +| P3b | Expert Reference (cross-module) | `RECIPES.md` — compound multi-feature workflows | +| P4 | Newcomer Onboarding | `quickstart.sh` + `QUICKSTART.md` + difficulty badges | +| P5 | Community Showcase | `COMMUNITY-PROJECTS.md` — curated user projects | +| P6 | Content Quality | Expand weakest modules; project `CLAUDE.md` | +| P7 | Living Curriculum | `WHATS-NEW.md` + version badges + weekly staleness CI action | + +--- + +## Timeline at a Glance + +``` +Apr 2026 May–Jun 2026 Jul–Aug 2026 Sep 2026 Oct–Nov 2026 Dec 2026–Mar 2027 + | | | | | | + [M1] [M2] [M3] [M4] [M5] [M6] +Infrastructure 6/10 modules 10/10 Agent layer Version audit Self-sustaining ++ hooks/checks complete complete + recipes complete system +``` + +--- + +## Milestones + +### M1 — Infrastructure Live · End of April 2026 + +**What ships:** +- `scripts/quickstart.sh` — one-command setup for new users (idempotent) +- `QUICKSTART.md` — First 15 Minutes visual guide +- Difficulty badges + "What you'll build" previews on all 10 modules +- `WHATS-NEW.md` + version badges on all modules +- `.github/workflows/staleness-check.yml` — weekly Monday issue if module unverified 30+ days +- Root `CLAUDE.md` — project's own configuration as a best-practice example +- `scripts/build-agent-index.py` — generator that reads all 10 modules → outputs `agent-manifest.json` + `AGENT-INDEX.md` +- **06-hooks** — full deep pass: 5 complete hook scripts, decision tree, Try It Now, patterns +- **08-checkpoints** — full deep pass: 311 → 800+ lines, 3 workflow templates, decision tree, patterns + +**Why start here:** Infrastructure benefits every future phase. Hooks and checkpoints are the weakest modules and most likely to lose new visitors. + +--- + +### M2 — 6/10 Modules Complete · End of June 2026 + +**What ships (one deep pass per module):** +- **01-slash-commands** — scenario intro, decision tree, Try It Now, named patterns +- **02-memory** — scenario intro, decision tree, Try It Now, named patterns +- **03-skills** — scenario intro, decision tree, Try It Now, named patterns +- **10-cli** — scenario intro, decision tree, Try It Now, named patterns +- CI step: validate `agent-manifest.json` schema on every push + +Each module pass = run the generator to confirm valid manifest output. + +--- + +### M3 — All 10 Modules Complete · End of August 2026 + +**What ships:** +- **04-subagents** — full deep pass (incl. "The Multi-Agent Review Pattern") +- **05-mcp** — full deep pass +- **07-plugins** — full deep pass +- **09-advanced-features** — full deep pass + +Every module now has: scenario intro, 2+ Try It Now blocks, Mermaid decision tree, 2+ named patterns. + +--- + +### M4 — Agent Layer Live · End of September 2026 + +**What ships:** +- Final `agent-manifest.json` covering 100% of modules (generated from completed content) +- `AGENT-INDEX.md` linked from `README.md` +- `skills/claude-howto-lookup/SKILL.md` — lightweight agent skill that queries the manifest +- `RECIPES.md` — 5+ compound workflows (schema: name, modules-used, problem, solution, expected outcome) +- `COMMUNITY-PROJECTS.md` — static curated list with PR-based submission format + +**Why September:** The agent index is only meaningful once all 10 modules are content-complete. + +--- + +### M5 — Version Audit Complete · End of November 2026 + +**What ships:** +- Full version audit: all 10 modules verified against current CC version +- Updated `cc_version_verified` frontmatter + version badges everywhere +- `RECIPES.md` expanded to 8+ recipes based on observed community patterns +- Pinned GitHub Discussion: "Share your Claude Code workflows" — signal collection for agent usage + +--- + +### M6 — Self-Sustaining System · End of March 2027 + +**What ships / runs continuously:** +- `/docs-sync-claude-code` skill runs after every CC release → `WHATS-NEW.md` updated +- Agent manifest CI regression: 100% module coverage enforced +- `RECIPES.md` at 10+ recipes +- `COMMUNITY-PROJECTS.md` growing organically +- Agent usage signal evaluated → if validated, promote the lookup skill (marketing, asm registry) + +--- + +## Deliverables Summary + +| Deliverable | Type | Phase | +|-------------|------|-------| +| `scripts/quickstart.sh` | Script | P1 | +| `QUICKSTART.md` | Doc | P1 | +| Root `CLAUDE.md` | Config | P1 | +| `WHATS-NEW.md` | Doc | P1 | +| `.github/workflows/staleness-check.yml` | CI | P1 | +| `scripts/build-agent-index.py` | Script | P1 | +| 10 module deep passes (scenario + Try It Now + decision tree + patterns) | Content | P1–P3 | +| `agent-manifest.json` (generated) | Data | P4 | +| `AGENT-INDEX.md` (generated) | Doc | P4 | +| `skills/claude-howto-lookup/SKILL.md` | Skill | P4 | +| `RECIPES.md` (5 → 8 → 10+ recipes) | Doc | P4–P6 | +| `COMMUNITY-PROJECTS.md` | Doc | P4 | + +--- + +## What Is NOT in Scope + +Deferred to `TODOS.md` — do not let these creep in: + +- Skill marketplace or installable registry +- Custom website or dashboard +- Completion tracking (cc-progress) +- Community tutorial CI validation +- Auto-generated CONTRIBUTORS.md +- Multi-language translations +- Quiz/assessment infrastructure +- Community voting on projects diff --git a/uk/docs/TASKS-20260401.md b/uk/docs/TASKS-20260401.md new file mode 100644 index 0000000..fdad321 --- /dev/null +++ b/uk/docs/TASKS-20260401.md @@ -0,0 +1,291 @@ +# Tasks: Dual-Layer Knowledge Base — claude-howto + +> Created: 2026-04-01 + +--- + +## Milestones + +| # | Milestone | Target | Description | +|---|-----------|--------|-------------| +| M1 | Infrastructure Live | End of April 2026 | quickstart.sh, CLAUDE.md, staleness action, agent index generator live; 2 weakest modules upgraded | +| M2 | 6/10 Modules Complete | End of June 2026 | Slash commands, memory, skills, CLI modules fully upgraded; generator producing valid manifest | +| M3 | All 10 Modules Complete | End of August 2026 | Every module has scenario intro, Try It Now blocks, decision tree, named patterns | +| M4 | Agent Layer Live | End of September 2026 | agent-manifest.json + AGENT-INDEX.md generated; lookup skill in repo; RECIPES.md + COMMUNITY-PROJECTS.md live | +| M5 | Version Audit Complete | End of November 2026 | All 10 modules verified against current CC version; RECIPES.md at 8+ recipes | +| M6 | Self-Sustaining System | End of March 2027 | Agent manifest covers 100% modules (CI-validated); RECIPES.md at 10+; community page growing organically | + +--- + +## Phase 1 — Infrastructure & Weak Modules (April 2026) + +**Target milestone: M1** + +### Pillar 4: Newcomer Onboarding + +- [ ] **T-001** — Write `scripts/quickstart.sh` + - Detects `~/.claude/` directory (creates with user confirmation if missing) + - Copies first slash command + CLAUDE.md + skill to user's setup + - Appends agent-discovery line to CLAUDE.md linking to AGENT-INDEX.md + - Idempotent: skips existing files with a warning, never overwrites + - Prints next steps on completion + +- [ ] **T-002** — Create `QUICKSTART.md` (First 15 Minutes visual guide) + - Annotated terminal steps as code blocks (avoid PNG screenshots where possible; prefer ASCII or Mermaid) + - Document which commands produce each visual so they can be re-captured + +- [ ] **T-003** — Add difficulty badges to all 10 module READMEs + - Format: `> 🟢 **Beginner** | ⏱ 30 minutes` at top of each module README + - Add "What you'll build" bullet preview below the badge + +### Pillar 7: Living Curriculum + +- [ ] **T-004** — Create `WHATS-NEW.md` + - Format: `## CC vX.X — DATE` with bullet items per feature change + - Add at least one entry for current CC version + +- [ ] **T-005** — Add version badges to all 10 module READMEs + - Format: `> ✅ Verified against Claude Code **vX.X.X** · Last verified: YYYY-MM-DD` + - Add `cc_version_verified` to each module's frontmatter + +- [ ] **T-006** — Create `.github/workflows/staleness-check.yml` + - Schedule: weekly Monday 09:00 UTC + - Reads each module's `last_verified` date from frontmatter (use `yq` or 10-line Python script) + - Creates a GitHub Issue for any module not verified in 30+ days + - Skips if open issue with same title already exists + +### Pillar 6: Content Quality (CLAUDE.md) + +- [ ] **T-007** — Create root `CLAUDE.md` for the project + - Demonstrates best practices as the project's own configuration + - Documents contributing conventions, module structure, and maintenance workflow + +### Pillar 2: AI Agent Index (Generator) + +- [ ] **T-008** — Write `scripts/build-agent-index.py` + - Reads all 10 module README files + - Extracts: headings (→ topics), code blocks (→ examples with language tags), tables (→ reference data) + - Outputs `agent-manifest.json` with schema defined in CEO plan + - Outputs `AGENT-INDEX.md` (human-readable summary) + - Validates references point to actual files + +### Module 08-checkpoints: Full Deep Pass (311 → 800+ lines) + +- [ ] **T-009** — Rewrite module intro with real-world scenario + - Example: "Your refactor just broke 3 things. Here's how checkpoints save you..." + +- [ ] **T-010** — Add checkpoint strategy decision tree (Mermaid flowchart) + - "I want to do X" → follow arrows → land on checkpoint pattern + +- [ ] **T-011** — Add 3 workflow templates + - Safe refactoring workflow + - A/B testing with checkpoints + - Disaster recovery workflow + +- [ ] **T-012** — Add integration with planning mode section + +- [ ] **T-013** — Add Mermaid diagram for checkpoint lifecycle + +- [ ] **T-014** — Add 2+ "Try It Now" blocks with verifiable commands + - Each: context sentence, command to run, expected output description + +- [ ] **T-015** — Add "Patterns & Recipes" section with 2+ named patterns + - Each pattern: problem, solution code, when to use, when NOT to use + +### Module 06-hooks: Full Deep Pass + +- [ ] **T-016** — Rewrite module intro with real-world scenario + - Example: "Your CI caught a lint error after 20 minutes. Hooks catch it in 2 seconds..." + +- [ ] **T-017** — Add hooks decision tree (Mermaid flowchart) + - "I want to trigger X when Y happens" → follow arrows → land on hook type + +- [ ] **T-018** — Add 5 complete hook examples with full scripts (~80 lines each) + 1. Auto-format on write (prettier/black) + 2. Security scan on commit (trufflehog/bandit) + 3. Test runner on file change + 4. Notification on session end + 5. Prompt validation (block dangerous patterns) + +- [ ] **T-019** — Add 2+ "Try It Now" blocks with verifiable commands + +- [ ] **T-020** — Add "Patterns & Recipes" section with 2+ named patterns + +**M1 Checkpoint: infrastructure live, 2 weakest modules fully upgraded** + +--- + +## Phase 2 — Deep Pass: Strong Modules Batch 1 (May–June 2026) + +**Target milestone: M2** + +### Module 01-slash-commands: Full Deep Pass + +- [ ] **T-021** — Rewrite intro with scenario ("Your teammate just pushed 47 files...") +- [ ] **T-022** — Add decision tree (Mermaid) +- [ ] **T-023** — Add 2+ "Try It Now" blocks +- [ ] **T-024** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 02-memory: Full Deep Pass + +- [ ] **T-025** — Rewrite intro with real-world scenario +- [ ] **T-026** — Add decision tree (Mermaid) +- [ ] **T-027** — Add 2+ "Try It Now" blocks +- [ ] **T-028** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 03-skills: Full Deep Pass + +- [ ] **T-029** — Rewrite intro with real-world scenario +- [ ] **T-030** — Add decision tree (Mermaid) +- [ ] **T-031** — Add 2+ "Try It Now" blocks +- [ ] **T-032** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 10-cli: Full Deep Pass + +- [ ] **T-033** — Rewrite intro with real-world scenario +- [ ] **T-034** — Add decision tree (Mermaid) +- [ ] **T-035** — Add 2+ "Try It Now" blocks +- [ ] **T-036** — Add "Patterns & Recipes" section with 2+ named patterns + +### Generator Validation + +- [ ] **T-037** — Run `scripts/build-agent-index.py` after each module upgrade; confirm valid manifest output +- [ ] **T-038** — Add CI step: validate agent-manifest.json schema on every push + +**M2 Checkpoint: 6/10 modules complete, generator producing valid manifest** + +--- + +## Phase 3 — Deep Pass: Strong Modules Batch 2 (July–August 2026) + +**Target milestone: M3** + +### Module 04-subagents: Full Deep Pass + +- [ ] **T-039** — Rewrite intro with real-world scenario +- [ ] **T-040** — Add decision tree (Mermaid) +- [ ] **T-041** — Add 2+ "Try It Now" blocks +- [ ] **T-042** — Add "Patterns & Recipes" section (e.g., "The Multi-Agent Review Pattern") + +### Module 05-mcp: Full Deep Pass + +- [ ] **T-043** — Rewrite intro with real-world scenario +- [ ] **T-044** — Add decision tree (Mermaid) +- [ ] **T-045** — Add 2+ "Try It Now" blocks +- [ ] **T-046** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 07-plugins: Full Deep Pass + +- [ ] **T-047** — Rewrite intro with real-world scenario +- [ ] **T-048** — Add decision tree (Mermaid) +- [ ] **T-049** — Add 2+ "Try It Now" blocks +- [ ] **T-050** — Add "Patterns & Recipes" section with 2+ named patterns + +### Module 09-advanced-features: Full Deep Pass + +- [ ] **T-051** — Rewrite intro with real-world scenario +- [ ] **T-052** — Add decision tree (Mermaid) +- [ ] **T-053** — Add 2+ "Try It Now" blocks +- [ ] **T-054** — Add "Patterns & Recipes" section with 2+ named patterns + +**M3 Checkpoint: all 10 modules complete and consistent** + +--- + +## Phase 4 — Agent Layer & Cross-Module (September 2026) + +**Target milestone: M4** + +### Pillar 2: Finalize AI Agent Index + +- [ ] **T-055** — Run `scripts/build-agent-index.py` against all 10 completed modules + - Produce final `agent-manifest.json` with 100% module coverage + - Produce `AGENT-INDEX.md` and link from README.md + +- [ ] **T-056** — Create `skills/claude-howto-lookup/SKILL.md` + - Reads `agent-manifest.json` to find relevant modules + - Uses `Read` to load the section + - Installation: `cp -r claude-howto/skills/claude-howto-lookup ~/.claude/skills/` + +- [ ] **T-057** — Mention lookup skill in quickstart.sh and QUICKSTART.md as optional feature + +### Pillar 3b: Cross-Module RECIPES.md + +- [ ] **T-058** — Create `RECIPES.md` with 5+ compound workflows + - Schema per recipe: name, modules-used, problem, solution code block, expected outcome + - Example: skill + hook + subagent = automated review pipeline + - Ensure HTML anchors on all major headings for deep-linking + +### Pillar 5: Community Showcase + +- [ ] **T-059** — Create `COMMUNITY-PROJECTS.md` + - Static Markdown page with submission format: name, description, link, features used + - Template entry included + - PR-based submission instructions + +**M4 Checkpoint: agent index live, recipes live, community page live** + +--- + +## Phase 5 — Version Audit & Recipe Expansion (October–November 2026) + +**Target milestone: M5** + +- [ ] **T-060** — Run full version audit: verify all 10 modules against current CC version + - Update `cc_version_verified` frontmatter in each module + - Update version badges + +- [ ] **T-061** — Expand `RECIPES.md` to 8+ recipes based on observed community patterns + +- [ ] **T-062** — Iterate agent manifest schema if new patterns emerge from completed modules + +- [ ] **T-063** — Open pinned GitHub Discussion: "Share your Claude Code workflows" + - Collect signal on real agent usage to inform future recipe expansion + +**M5 Checkpoint: all modules verified current, recipes growing** + +--- + +## Phase 6 — Compound & Sustain (December 2026 – March 2027) + +**Target milestone: M6** + +- [ ] **T-064** — Run `/docs-sync-claude-code` skill after every CC release; update `WHATS-NEW.md` + +- [ ] **T-065** — Ensure agent manifest covers 100% of modules (CI regression test) + +- [ ] **T-066** — Grow `RECIPES.md` to 10+ recipes + +- [ ] **T-067** — Monitor `COMMUNITY-PROJECTS.md` for organic growth; curate new entries + +- [ ] **T-068** — Evaluate agent usage signal from GitHub Discussions; if validated, invest in promoting the lookup skill (marketing, asm registry) + +**M6 Checkpoint: the system is self-sustaining** + +--- + +## Deferred (TODOS.md) + +These items are out of scope for this plan. Record here to avoid scope creep: + +- Skill marketplace / installable registry +- Custom website or dashboard +- Completion tracking infrastructure (cc-progress) +- Community tutorial template with CI validation +- Auto-generated CONTRIBUTORS.md +- Multi-language translations +- Quiz/assessment infrastructure upgrades +- Community voting/review mechanism for COMMUNITY-PROJECTS.md + +--- + +## Task Summary by Phase + +| Phase | Tasks | Period | Modules Touched | +|-------|-------|--------|-----------------| +| 1 — Infrastructure & Weak Modules | T-001 to T-020 | April 2026 | 06-hooks, 08-checkpoints + infra | +| 2 — Batch 1 Deep Pass | T-021 to T-038 | May–June 2026 | 01, 02, 03, 10 | +| 3 — Batch 2 Deep Pass | T-039 to T-054 | July–August 2026 | 04, 05, 07, 09 | +| 4 — Agent Layer & Cross-Module | T-055 to T-059 | September 2026 | All (manifest) + new files | +| 5 — Version Audit & Recipes | T-060 to T-063 | October–November 2026 | All (audit) | +| 6 — Sustain | T-064 to T-068 | December 2026–March 2027 | Ongoing | diff --git a/uk/prompts/remotion-video.md b/uk/prompts/remotion-video.md new file mode 100644 index 0000000..700023d --- /dev/null +++ b/uk/prompts/remotion-video.md @@ -0,0 +1,350 @@ +You are an expert Motion Designer and Senior React Engineer specializing in **Remotion**. Your goal is to take a product description and turn it into a high-energy, professionally animated video using React code. + +**START BY EXPLORING AUTONOMOUSLY:** Immediately begin exploring the codebase to gather product information. Only ask the user questions if critical information is missing or unclear after your exploration. + +Follow a 7-phase workflow, making smart decisions at each step based on the information you gather. + +--- + +# 🔄 AUTOMATED WORKFLOW + +**KEY PRINCIPLES:** + +- **Explore First:** Always begin by automatically exploring the codebase to gather product information. Do NOT start with questions about the product. +- **Ask Before Planning:** After exploration, present findings and ask user for video preferences (size, style, duration, customizations) BEFORE creating the plan. +- **Product URL First:** When a product URL is found or provided, it serves as the PRIMARY source of truth. Information from the product page takes precedence over codebase findings. +- **Value Over Tech:** Focus on value propositions, customer benefits, and features (what users gain) rather than technical specifications or implementation details. +- **Customer-Centric:** Emphasize how the product solves problems, improves lives, or delivers benefits to users. +- **Autonomous Execution:** After user confirms preferences, proceed autonomously through planning and implementation without further approval requests. + +## 📋 Phase 1: Autonomous Resource Discovery + +**OBJECTIVE:** Automatically explore the codebase and gather all available product information without asking the user. + +**ACTIONS:** + +1. **Automatically explore the codebase first:** + - Search for `README.md` for product description and value proposition + - Check `package.json` for product name, description, homepage URL + - Look for brand assets in `/assets`, `/public`, `/static`, `/images` directories + - Extract color schemes from CSS/Tailwind config files + - Find any existing marketing copy or documentation + - Look for any product URLs in config files, environment variables, or documentation + +2. **If product URL found, fetch it immediately:** + - Use WebFetch to extract information from the product page + - Product page information takes precedence over codebase findings + - Extract all value propositions, features, and branding + +3. **Synthesize all gathered information:** + - Product name and description + - Value proposition + - Key features and benefits + - Brand colors and style + - Target audience (inferred from tone) + - Any existing assets or media + +4. **Apply smart defaults for missing information:** + - **Video Format:** Landscape 1920x1080 (YouTube/web optimized) + - **Duration:** 30 seconds (ideal for most platforms) + - **Style:** Modern, clean, professional (based on brand) + - **Brand Colors:** Use extracted colors or complementary modern palette + +5. **Only ask user IF (after exploration):** + - Cannot determine product name or find any product information + - Cannot find or access product URL + - Critical ambiguity exists (e.g., B2B vs B2C drastically changes messaging) + - Conflicting information needs clarification + +**IMPORTANT:** Complete this entire exploration silently and autonomously. Do NOT ask "What I need to get started" or list requirements. Only interrupt the user if truly necessary. + +**OUTPUT:** Proceed immediately to Phase 2 with all gathered information. + +--- + +## 🔍 Phase 2: Information Analysis & Deep Dive + +**OBJECTIVE:** Analyze gathered information and extract key insights for video creation. + +**ACTIONS:** + +1. **Review all information collected in Phase 1:** + - Product page content (if URL was found and fetched) + - Codebase findings (README, package.json, assets, etc.) + - Any brand guidelines or marketing materials + +2. **Extract and prioritize (FOCUS ON VALUE, NOT TECH):** + - **Value Proposition** (primary focus) - The main benefit to customers + - **Customer Benefits** (what users gain) - How it improves their lives + - **Key Features** (described as benefits, not technical specs) + - **Unique Selling Points** - What makes it different/better + - **Use Cases** - Real-world applications + - **Brand identity** (colors, fonts, style, tone) + - **Target audience insights** (who this is for) + - **Emotional appeal** and messaging (why people care) + +3. **Silently fill gaps with intelligent inferences:** + - If value prop is not explicit, infer from features and target audience + - If target audience is unclear, infer from product type and messaging tone + - If brand colors are missing, create a complementary modern palette + - Avoid technical implementation details unless user-facing + +4. **Only ask for clarification IF:** + - Multiple conflicting value propositions exist + - Cannot determine if product is B2B or B2C (drastically affects messaging) + - Genuinely ambiguous target audience + +**OUTPUT:** Clear understanding of product value, benefits, and brand for video creation. + +--- + +## ✅ Phase 3: Present Findings & Gather User Preferences + +**OBJECTIVE:** Share what you discovered and get user input on video preferences before planning. + +**ACTIONS:** + +1. **Present a summary of discovered information:** + + ```text + 📊 DISCOVERED INFORMATION + + Product: [Name] + Value Proposition: [Main benefit to customers] + Key Features: [2-3 main benefits] + Brand Colors: [Extracted or suggested colors] + Target Audience: [Who this is for] + ``` + +2. **Ask user for preferences (REQUIRED BEFORE PROCEEDING):** + + Use a clear, concise format: + + ```text + Before I create your video, please let me know your preferences: + + 1. **Video Size/Format:** + - Landscape (1920x1080) - YouTube, website + - Portrait (1080x1920) - TikTok, Instagram Reels + - Square (1080x1080) - Instagram feed + + 2. **Video Duration:** + - 15 seconds - Quick social media ad + - 30 seconds - Standard promotional video + - 60 seconds - Detailed feature showcase + - Custom duration + + 3. **Video Style:** + - Modern & Minimal - Clean, Apple-style aesthetics + - Energetic & Bold - Fast-paced, social media style + - Professional & Corporate - Business-focused + - Custom style (describe your vision) + + 4. **Anything else to highlight or customize?** + (Specific features, messaging, colors, etc.) + ``` + +3. **Wait for user response** before proceeding to Phase 4. + +4. **Acknowledge preferences and confirm:** + - Summarize user's choices + - Apply any custom requirements + - Proceed to structure design with confirmed direction + +**OUTPUT:** User-confirmed video specifications ready for planning phase. + +--- + +## 📐 Phase 4: Structure Design (Post-Confirmation) + +**OBJECTIVE:** Create a compelling video structure using the 3-act format based on user preferences. + +**ACTIONS:** + +1. **Design video structure with user's confirmed preferences:** + + ```text + 🎬 VIDEO STRUCTURE + + Act 1: The Hook (0-5 seconds) + - [Attention-grabbing visual concept] + - [Bold animation entrance] + - [Compelling headline/question] + + Act 2: Value Demonstration (middle section) + - [Show key benefits in action] + - [Visual storytelling of customer value] + - [2-3 feature highlights as benefits] + + Act 3: Call to Action (final section) + - [Clear CTA with brand reinforcement] + - [Memorable closing visual] + - [Smooth exit animation] + ``` + +2. **Apply user preferences:** + - Use specified video size/format + - Match chosen style (minimal/energetic/professional) + - Adapt timing to specified duration + - Incorporate any custom requirements + +3. **Make creative decisions based on:** + - Product value proposition (what makes it compelling) + - Target audience (what resonates with them) + - User's style preferences + - Brand personality (visual and tonal consistency) + +4. **Present the structure briefly** then automatically proceed to Phase 5. + +**OUTPUT:** Complete video structure ready for implementation planning. + +--- + +## 🛠️ Phase 5: Technical Architecture + +**OBJECTIVE:** Design implementation architecture and proceed directly to building. + +**ACTIONS:** + +1. **Silently design** the component architecture: + - Utility functions (easing, animation helpers, color utilities) + - Reusable components (AnimatedTitle, FeatureHighlight, etc.) + - Scene components (Hook, Demo, CTA scenes) + - Main composition structure (Video.tsx, Root.tsx) + +2. **Plan technical details:** + - Animation timing and easing curves + - Color palette implementation + - Typography hierarchy + - Icon and asset strategy + - Sequence timing breakdown + +3. **Proceed directly to Phase 6** implementation without requesting approval. + +**OUTPUT:** Internal technical blueprint ready for immediate implementation. + +--- + +## 💻 Phase 6: Implementation + +**OBJECTIVE:** Build the complete Remotion video project autonomously. + +**CONSTRAINTS & TECH STACK:** + +1. **Framework:** Remotion (React) +2. **Styling:** Tailwind CSS (via `className` or standard style objects) +3. **Animation:** Use `spring`, `interpolate`, and `useCurrentFrame` for smooth motion +4. **Code Style:** Modular components. Do not dump everything in `Root.tsx` +5. **Best Practices:** + - Nothing should be static. Everything must have an entrance (opacity/scale/slide) and exit + - Use Lucide-React for icons if needed + - Use standard fonts but style them heavily (bold, tracking-tight) + - Do not use external images unless they are placeholders (e.g., `https://placehold.co/600x400`) or user-provided assets + +**ACTIONS:** + +1. **Build complete project structure** in this order: + - Utility functions (easing, animation helpers, color utilities) + - Reusable components (AnimatedTitle, FeatureHighlight, transitions) + - Scene components (HookScene, DemoScene, CTAScene) + - Main composition (Video.tsx with sequencing) + - Root configuration (Root.tsx with proper registration) + +2. **Work silently and efficiently:** + - Create all files without narrating every step + - Make design decisions based on gathered information + - Use professional animation principles + - Ensure smooth transitions between scenes + +3. **Automatically proceed to Phase 7** when implementation is complete. + +**OUTPUT:** Complete, production-ready Remotion project code. + +--- + +## 🎥 Phase 7: Delivery & Next Steps + +**OBJECTIVE:** Provide rendering instructions and mark project complete. + +**ACTIONS:** + +1. **Provide rendering instructions:** + + ```bash + # Preview the video in browser + npm run dev + + # Render the final video + npm run build + npx remotion render Video out/video.mp4 + + # For specific codec/settings + npx remotion render Video out/video.mp4 --codec h264 + ``` + +2. **Deliver summary:** + - Brief description of what was created + - Key features of the video + - Video specifications (duration, format, dimensions) + - Any notable design decisions + +3. **User can request changes if needed:** + - Timing adjustments + - Animation modifications + - Content updates + - Style tweaks + +**OUTPUT:** Complete Remotion project with clear rendering instructions, ready to use. + +--- + +# 🎯 QUALITY STANDARDS + +Throughout all phases, maintain these standards: + +**Visual Quality:** +- Professional-grade animations (smooth, purposeful, on-brand) +- Consistent spacing and alignment +- Readable typography with proper contrast +- Cohesive color usage + +**Technical Quality:** +- Clean, modular code architecture +- Performance-optimized (smooth 30fps playback) +- Proper use of Remotion APIs (spring, interpolate, Sequence) +- Type-safe (if using TypeScript) + +**Creative Quality:** +- Clear narrative structure +- Attention-grabbing opening +- Strong call-to-action +- Memorable visual moments + +--- + +# 🚀 Getting Started + +I'll create a professional Remotion video project for your product. Here's my workflow: + +## Phase 1-2: Autonomous Exploration (I do this automatically) + +1. Explore your codebase for product details, brand assets, and colors +2. Fetch and analyze product page (if URL found) +3. Extract value propositions and key benefits + +## Phase 3: Your Input (I'll ask you) + +1. Present what I discovered +2. Ask for your video preferences: + - Video size/format (landscape/portrait/square) + - Duration (15s/30s/60s) + - Style (minimal/energetic/professional) + - Any customizations + +## Phase 4-7: Autonomous Execution (I do this automatically) + +1. Design video structure based on your preferences +2. Build complete Remotion project with professional animations +3. Deliver production-ready code with rendering instructions + +Let's create something amazing! diff --git a/uk/resources.md b/uk/resources.md new file mode 100644 index 0000000..66ecd13 --- /dev/null +++ b/uk/resources.md @@ -0,0 +1,255 @@ + + + + + + + Claude How To + + +# Список корисних ресурсів + +## Офіційна документація + +| Ресурс | Опис | Посилання | +|--------|------|-----------| +| Claude Code Docs | Офіційна документація Claude Code | [code.claude.com/docs/en/overview](https://code.claude.com/docs/en/overview) | +| Anthropic Docs | Повна документація Anthropic | [docs.anthropic.com](https://docs.anthropic.com) | +| MCP Protocol | Специфікація Model Context Protocol | [modelcontextprotocol.io](https://modelcontextprotocol.io) | +| MCP Servers | Офіційні реалізації MCP-серверів | [github.com/modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | +| Anthropic Cookbook | Приклади коду та туторіали | [github.com/anthropics/anthropic-cookbook](https://github.com/anthropics/anthropic-cookbook) | +| Claude Code Skills | Репозиторій навичок спільноти | [github.com/anthropics/skills](https://github.com/anthropics/skills) | +| Agent Teams | Координація та співпраця кількох агентів | [code.claude.com/docs/en/agent-teams](https://code.claude.com/docs/en/agent-teams) | +| Scheduled Tasks | Повторювані завдання з /loop та cron | [code.claude.com/docs/en/scheduled-tasks](https://code.claude.com/docs/en/scheduled-tasks) | +| Chrome Integration | Автоматизація браузера | [code.claude.com/docs/en/chrome](https://code.claude.com/docs/en/chrome) | +| Keybindings | Налаштування клавіатурних скорочень | [code.claude.com/docs/en/keybindings](https://code.claude.com/docs/en/keybindings) | +| Desktop App | Нативний десктопний додаток | [code.claude.com/docs/en/desktop](https://code.claude.com/docs/en/desktop) | +| Remote Control | Віддалене управління сесіями | [code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control) | +| Auto Mode | Автоматичне управління дозволами | [code.claude.com/docs/en/permissions](https://code.claude.com/docs/en/permissions) | +| Channels | Багатоканальна комунікація | [code.claude.com/docs/en/channels](https://code.claude.com/docs/en/channels) | +| Voice Dictation | Голосовий ввід для Claude Code | [code.claude.com/docs/en/voice-dictation](https://code.claude.com/docs/en/voice-dictation) | + +## Інженерний блог Anthropic + +| Стаття | Опис | Посилання | +|--------|------|-----------| +| Code Execution with MCP | Як вирішити проблему роздування контексту MCP за допомогою виконання коду — 98.7% зменшення токенів | [anthropic.com/engineering/code-execution-with-mcp](https://www.anthropic.com/engineering/code-execution-with-mcp) | + +--- + +## Опанування Claude Code за 30 хвилин + +_Відео_: https://www.youtube.com/watch?v=6eBSHbLKuN0 + +_**Усі поради**_ +- **Досліджуйте просунуті функції та скорочення** + - Регулярно перевіряйте нові функції редагування коду та контексту Claude в їхніх нотатках до випусків. + - Вивчіть клавіатурні скорочення для швидкого перемикання між чатом, файлами та редактором. + +- **Ефективне налаштування** + - Створюйте проєктно-специфічні сесії з чіткими назвами/описами для легкого пошуку. + - Закріпіть найчастіше використовувані файли або папки, щоб Claude мав до них доступ у будь-який час. + - Налаштуйте інтеграції Claude (напр., GitHub, популярні IDE) для оптимізації процесу кодування. + +- **Ефективне Q&A по кодовій базі** + - Ставте Claude детальні запитання про архітектуру, патерни проєктування та конкретні модулі. + - Використовуйте посилання на файли та рядки у запитаннях (напр., "Що робить логіка в `app/models/user.py`?"). + - Для великих кодових баз надайте резюме або маніфест, щоб допомогти Claude зосередитись. + - **Приклад промпту**: _"Can you explain the authentication flow implemented in src/auth/AuthService.ts:45-120? How does it integrate with the middleware in src/middleware/auth.ts?"_ + +- **Редагування та рефакторинг коду** + - Використовуйте інлайн-коментарі або запити в блоках коду для отримання цілеспрямованих правок ("Refactor this function for clarity"). + - Запитуйте порівняння до/після. + - Дозвольте Claude генерувати тести або документацію після значних правок для забезпечення якості. + - **Приклад промпту**: _"Refactor the getUserData function in api/users.js to use async/await instead of promises. Show me a before/after comparison and generate unit tests for the refactored version."_ + +- **Управління контекстом** + - Обмежуйте вставлений код/контекст лише тим, що стосується поточного завдання. + - Використовуйте структуровані промпти ("Here's file A, here's function B, my question is X") для найкращої продуктивності. + - Видаляйте або згортайте великі файли у вікні промпту, щоб не перевищувати ліміти контексту. + - **Приклад промпту**: _"Here's the User model from models/User.js and the validateUser function from utils/validation.js. My question is: how can I add email validation while maintaining backward compatibility?"_ + +- **Інтеграція командних інструментів** + - Підключайте сесії Claude до репозиторіїв та документації вашої команди. + - Використовуйте вбудовані шаблони або створюйте власні для повторюваних інженерних завдань. + - Співпрацюйте, діляться стенограмами сесій та промптами з колегами. + +- **Підвищення продуктивності** + - Давайте Claude чіткі, цілеорієнтовані інструкції (напр., "Summarize this class in five bullet points"). + - Видаляйте зайві коментарі та шаблонний код з вікон контексту. + - Якщо вивід Claude збився з курсу, скиньте контекст або переформулюйте запитання. + - **Приклад промпту**: _"Summarize the DatabaseManager class in src/db/Manager.ts in five bullet points, focusing on its main responsibilities and key methods."_ + +- **Практичні приклади використання** + - Дебаг: Вставте помилки та стек-трейси, потім запитайте можливі причини та виправлення. + - Генерація тестів: Запитайте property-based, юніт або інтеграційні тести для складної логіки. + - Код-рев'ю: Попросіть Claude виявити ризиковані зміни, граничні випадки або code smells. + - **Приклади промптів**: + - _"I'm getting this error: 'TypeError: Cannot read property 'map' of undefined at line 42 in components/UserList.jsx'. Here's the stack trace and the relevant code. What's causing this and how can I fix it?"_ + - _"Generate comprehensive unit tests for the PaymentProcessor class, including edge cases for failed transactions, timeouts, and invalid inputs."_ + - _"Review this pull request diff and identify potential security issues, performance bottlenecks, and code smells."_ + +- **Автоматизація робочих процесів** + - Скриптуйте повторювані завдання (форматування, очищення, перейменування) за допомогою промптів Claude. + - Використовуйте Claude для створення описів PR, нотаток до релізів або документації на основі git diff. + - **Приклад промпту**: _"Based on the git diff, create a detailed PR description with a summary of changes, list of modified files, testing steps, and potential impacts. Also generate release notes for version 2.3.0."_ + +**Порада**: Для найкращих результатів комбінуйте кілька цих практик — почніть з закріплення критичних файлів та резюмування цілей, потім використовуйте цілеспрямовані промпти та інструменти рефакторингу Claude для поступового покращення кодової бази та автоматизації. + + +**Рекомендований робочий процес з Claude Code** + +### Рекомендований робочий процес з Claude Code + +#### Для нового репозиторію + +1. **Ініціалізація репо та інтеграція Claude** + - Налаштуйте новий репозиторій з базовою структурою: README, LICENSE, .gitignore, кореневі конфіги. + - Створіть файл `CLAUDE.md` з описом архітектури, високорівневих цілей та настанов кодування. + - Встановіть Claude Code та підключіть до репозиторію для пропозицій коду, створення тестів та автоматизації. + +2. **Використовуйте режим плану та специфікації** + - Використовуйте режим плану (`shift-tab` або `/plan`) для створення детальної специфікації перед реалізацією. + - Запитайте Claude про пропозиції архітектури та початкове компонування проєкту. + - Тримайте чітку, цілеорієнтовану послідовність промптів — запитуйте контури компонентів, основні модулі та відповідальності. + +3. **Ітеративна розробка та рев'ю** + - Реалізуйте основні функції маленькими частинами, запитуючи Claude про генерацію коду, рефакторинг та документацію. + - Запитуйте юніт-тести та приклади після кожного інкременту. + - Підтримуйте поточний список завдань у CLAUDE.md. + +4. **Автоматизація CI/CD та деплою** + - Використовуйте Claude для створення каркасу GitHub Actions, npm/yarn скриптів або робочих процесів деплою. + - Легко адаптуйте конвеєри, оновлюючи CLAUDE.md та запитуючи відповідні команди/скрипти. + +```mermaid +graph TD + A[Start New Repository] --> B[Initialize Repository Structure] + B --> C[Create README, LICENSE, .gitignore] + C --> D[Create CLAUDE.md] + D --> E[Document Architecture & Guidelines] + E --> F[Install & Link Claude Code] + + F --> G[Enter Plan Mode] + G --> H[Draft Feature Specification] + H --> I[Get Architecture Suggestions] + I --> J[Define Components & Modules] + + J --> K[Implement Feature Chunk] + K --> L[Generate Code with Claude] + L --> M[Request Unit Tests] + M --> N[Review & Refactor] + N --> O{More Features?} + O -->|Yes| K + O -->|No| P[Update Task List in CLAUDE.md] + + P --> Q[Setup CI/CD Pipeline] + Q --> R[Scaffold GitHub Actions] + R --> S[Create Deployment Scripts] + S --> T[Test Automation] + T --> U[Repository Ready] + + style A fill:#e1f5ff + style G fill:#fff4e1 + style K fill:#f0ffe1 + style Q fill:#ffe1f5 + style U fill:#90EE90 +``` + +#### Для існуючого репозиторію + +1. **Налаштування репо та контексту** + - Додайте або оновіть `CLAUDE.md` з документацією структури репо, патернів кодування та ключових файлів. Для legacy-репозиторіїв використовуйте `CLAUDE_LEGACY.md` з описом фреймворків, карт версій, інструкцій, багів та нотаток оновлення. + - Закріпіть або виділіть основні файли, які Claude повинен використовувати для контексту. + +2. **Контекстне Q&A по коду** + - Запитуйте Claude про код-рев'ю, пояснення багів, рефакторинг або плани міграції з посиланням на конкретні файли/функції. + - Давайте Claude чіткі межі (напр., "modify only these files" або "no new dependencies"). + +3. **Управління гілками, worktree та кількома сесіями** + - Використовуйте кілька git worktree для ізольованих функцій або виправлень та запускайте окремі сесії Claude на кожен worktree. + - Тримайте вкладки/вікна терміналу організованими за гілкою або функцією для паралельних робочих процесів. + +4. **Командні інструменти та автоматизація** + - Синхронізуйте власні команди через `.claude/commands/` для крос-командної консистентності. + - Автоматизуйте повторювані завдання, створення PR та форматування коду через слеш-команди або хуки Claude. + - Діліться сесіями та контекстом з членами команди для спільного усунення проблем та рев'ю. + +```mermaid +graph TD + A[Start with Existing Repository] --> B{Legacy Codebase?} + B -->|Yes| C[Create CLAUDE_LEGACY.md] + B -->|No| D[Create/Update CLAUDE.md] + C --> E[Document Frameworks & Version Maps] + D --> F[Document Structure & Patterns] + E --> G[Pin Key Files for Context] + F --> G + + G --> H[Identify Task Type] + H --> I{Task Category} + I -->|Bug Fix| J[Ask Claude for Bug Analysis] + I -->|Code Review| K[Request Code Review] + I -->|Refactor| L[Plan Refactoring Strategy] + I -->|Migration| M[Create Migration Plan] + + J --> N[Set Explicit Boundaries] + K --> N + L --> N + M --> N + + N --> O{Multiple Features?} + O -->|Yes| P[Create Git Worktrees] + O -->|No| Q[Work on Main Branch] + P --> R[Launch Separate Claude Sessions] + R --> S[Organize Terminal Tabs] + Q --> S + + S --> T[Setup Team Automation] + T --> U[Sync .claude/commands/] + U --> V[Configure Slash Commands] + V --> W[Setup Hooks for Automation] + W --> X[Share Session Context with Team] + + X --> Y{More Tasks?} + Y -->|Yes| H + Y -->|No| Z[Workflow Complete] + + style A fill:#e1f5ff + style C fill:#ffecec + style D fill:#fff4e1 + style P fill:#f0ffe1 + style T fill:#ffe1f5 + style Z fill:#90EE90 +``` + +**Поради**: +- Починайте кожну нову функцію або виправлення зі специфікації та промпту в режимі плану. +- Для legacy та складних репозиторіїв зберігайте детальні настанови в CLAUDE.md/CLAUDE_LEGACY.md. +- Давайте чіткі, зосереджені інструкції та розбивайте складну роботу на багатофазні плани. +- Регулярно очищайте сесії, обрізайте контекст та видаляйте завершені worktree, щоб уникнути безладу. + +Ці кроки описують основні рекомендації для плавних робочих процесів з Claude Code як у нових, так і в існуючих кодових базах. + +--- + +## Нові функції та можливості (Березень 2026) + +### Ключові ресурси функцій + +| Функція | Опис | Дізнатися більше | +|---------|------|------------------| +| **Auto Memory** | Claude автоматично вивчає та запам'ятовує ваші уподобання між сесіями | [Посібник з пам'яті](02-memory/) | +| **Remote Control** | Програмне управління сесіями Claude Code із зовнішніх інструментів та скриптів | [Просунуті функції](09-advanced-features/) | +| **Web Sessions** | Доступ до Claude Code через браузерні інтерфейси для віддаленої розробки | [Довідник CLI](10-cli/) | +| **Desktop App** | Нативний десктопний додаток Claude Code з покращеним UI | [Claude Code Docs](https://code.claude.com/docs/en/desktop) | +| **Extended Thinking** | Перемикання глибокого мислення через `Alt+T`/`Option+T` або змінну `MAX_THINKING_TOKENS` | [Просунуті функції](09-advanced-features/) | +| **Permission Modes** | Тонке управління: default, acceptEdits, plan, auto, dontAsk, bypassPermissions | [Просунуті функції](09-advanced-features/) | +| **7-Tier Memory** | Managed Policy, Project, Project Rules, User, User Rules, Local, Auto Memory | [Посібник з пам'яті](02-memory/) | +| **Hook Events** | 25 подій: PreToolUse, PostToolUse, PostToolUseFailure, Stop, StopFailure, SubagentStart, SubagentStop, Notification, Elicitation та інші | [Посібник з хуків](06-hooks/) | +| **Agent Teams** | Координація кількох агентів для складних завдань | [Посібник з субагентів](04-subagents/) | +| **Scheduled Tasks** | Налаштування повторюваних завдань з `/loop` та cron | [Просунуті функції](09-advanced-features/) | +| **Chrome Integration** | Автоматизація браузера з headless Chromium | [Просунуті функції](09-advanced-features/) | +| **Keyboard Customization** | Налаштування клавіатурних скорочень включаючи chord-послідовності | [Просунуті функції](09-advanced-features/) | + +--- +**Останнє оновлення**: Квітень 2026 diff --git a/uk/resources/DESIGN-SYSTEM.md b/uk/resources/DESIGN-SYSTEM.md new file mode 100644 index 0000000..1b5e1f0 --- /dev/null +++ b/uk/resources/DESIGN-SYSTEM.md @@ -0,0 +1,121 @@ +# Claude How To — Дизайн-система + +## Візуальна ідентичність + +### Концепція дизайну іконки: Компас з кодовою дужкою + +Іконка Claude How To використовує **компас з кодовою дужкою `>`** для представлення направленої навігації кодом: + +``` + N (green) + ▲ + │ +W ───>─── E Compass = Guidance/Direction + │ > Bracket = Code/Terminal/CLI + ▼ + S (black) +``` + +Це створює: +- **Візуальна ясність**: Одразу комунікує "гайд з навігації кодом" +- **Символічне значення**: Компас = пошук шляху; `>` = код/термінал +- **Масштабованість**: Працює при будь-якому розмірі від 16px до 512px +- **Відповідність бренду**: Відповідає естетиці інструменту розробника з мінімальною палітрою + +--- + +## Кольорова система + +### Палітра + +| Колір | Hex | RGB | Використання | +|-------|-----|-----|-------------| +| Чорний (основний) | `#000000` | 0, 0, 0 | Основні обведення, текст, південна стрілка | +| Білий (фон) | `#FFFFFF` | 255, 255, 255 | Світлі фони | +| Сірий (вторинний) | `#6B7280` | 107, 114, 128 | Малі позначки, вторинний текст | +| Яскраво-зелений (акцент) | `#22C55E` | 34, 197, 94 | Північна стрілка, центральна точка, акцентні лінії | +| Майже чорний (темний фон) | `#0A0A0A` | 10, 10, 10 | Фони dark mode | + +### Коефіцієнти контрасту (WCAG) + +- Чорний на білому: **21:1** AAA +- Сірий на білому: **4.6:1** AA +- Зелений на білому: **3.2:1** (тільки декоративний, не для тексту) +- Білий на темному: **19.5:1** AAA + +### Правило акцентного кольору + +**Яскраво-зелений (#22C55E) зарезервований тільки для виділень:** +- Північна стрілка компасу +- Центральна точка +- Акцентні підкреслення/рамки +- Ніколи як фон +- Ніколи для основного тексту + +--- + +## Типографіка + +### Шрифт логотипу +- **Сімейство**: Inter, SF Pro Display, -apple-system, Segoe UI, sans-serif +- **"Claude"**: 42px, weight 700 (bold), Чорний +- **"How-To"**: 32px, weight 500 (medium), Сірий (#6B7280) +- **Підзаголовок**: 10px, weight 500, Сірий, letter-spacing 1.5px, uppercase + +--- + +## Деталі іконки + +### Специфікації компасу + +``` +Element | Stroke/Fill | Color +--------------------|----------------|------------------ +Outer ring | 3px stroke | Black / White (dark mode) +North tick | 2.5px stroke | Black / White (dark mode) +Other cardinal ticks| 2px stroke | Gray / White 50% (dark mode) +Intercardinal ticks | 1.5px stroke | Gray / White 40% (dark mode) +North needle | filled polygon | #22C55E (always green) +South needle | filled polygon | Black / White (dark mode) +> bracket | 3px stroke | Black / White (dark mode) +Center dot | filled circle | #22C55E (always green) +``` + +### Прогресія розмірів + +``` +16px → Кільце + стрілки + шеврон (мінімально) +32px → Додаються кардинальні позначки +64px → Додаються інтеркардинальні позначки +128px → Повна деталізація, всі елементи чіткі +256px → Максимальна деталізація, товсті обведення +``` + +--- + +## Настанови з розмірів + +### Розміри логотипу +- **Мінімум**: 200px ширина (для веб) +- **Рекомендовано**: 520px (нативний розмір) +- **Максимум**: Необмежено (векторний формат) +- **Пропорції**: ~4.3:1 (ширина:висота) + +### Розміри іконки +- **Мінімум**: 16px (фавікон) +- **Рекомендовано**: 64-256px (додатки, аватари) +- **Максимум**: Необмежено (векторний формат) +- **Пропорції**: 1:1 (квадрат) + +--- + +## Доступність + +- Усі тексти відповідають WCAG AA (мінімум 4.5:1) +- Зелений акцент — декоративний, не інформаційний +- Без залежності від червоно-зеленого розрізнення + +--- + +**Останнє оновлення**: Лютий 2026 +**Версія дизайн-системи**: 3.0 diff --git a/uk/resources/QUICK-START.md b/uk/resources/QUICK-START.md new file mode 100644 index 0000000..a7c446e --- /dev/null +++ b/uk/resources/QUICK-START.md @@ -0,0 +1,89 @@ +# Швидкий старт — Брендові ресурси + +## Копіювання ресурсів у ваш проєкт + +```bash +# Copy all resources to your web project +cp -r resources/ /path/to/your/website/ + +# Or just the favicons for web +cp resources/favicons/* /path/to/your/website/public/ +``` + +## Додавання в HTML (копіювання та вставка) + +```html + + + + + + +``` + +## Використання в Markdown/документації + +```markdown +# Claude How To + +![Claude How To Logo](resources/logos/claude-howto-logo.svg) + +![Icon](resources/icons/claude-howto-icon.svg) +``` + +## Рекомендовані розміри + +| Призначення | Розмір | Файл | +|-------------|--------|------| +| Заголовок сайту | 520×120 | `logos/claude-howto-logo.svg` | +| Іконка додатку | 256×256 | `icons/claude-howto-icon.svg` | +| Вкладка браузера | 32×32 | `favicons/favicon-32.svg` | +| Домашній екран мобільного | 128×128 | `favicons/favicon-128.svg` | +| Десктопний додаток | 256×256 | `favicons/favicon-256.svg` | +| Малий аватар | 64×64 | `favicons/favicon-64.svg` | + +## Значення кольорів + +```css +/* Use these in your CSS */ +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +## Значення дизайну іконки + +**Компас з кодовою дужкою**: +- Кільце компасу = Навігація, структурований навчальний шлях +- Зелена північна стрілка = Напрямок, прогрес, керівництво +- Чорна південна стрілка = Основа, міцний фундамент +- Дужка `>` = Промпт терміналу, код, контекст CLI +- Позначки = Точність, структуровані кроки + +Це символізує "пошук шляху через код з чітким керівництвом". + +## Що і де використовувати + +### Сайт +- **Заголовок**: Логотип (`logos/claude-howto-logo.svg`) +- **Фавікон**: 32px (`favicons/favicon-32.svg`) +- **Соціальний превʼю**: Іконка (`icons/claude-howto-icon.svg`) + +### GitHub +- **Бейдж README**: Іконка 64-128px +- **Аватар репозиторію**: Іконка + +### Соціальні мережі +- **Аватар**: Іконка 256×256px +- **Банер**: Логотип 520×120px +- **Мініатюра**: Іконка 256×256px + +### Документація +- **Заголовки розділів**: Логотип або іконка (масштабовані) +- **Іконки навігації**: Фавікон 32-64px + +--- + +Див. [README.md](README.md) для повної документації. diff --git a/uk/resources/README.md b/uk/resources/README.md new file mode 100644 index 0000000..e54ed45 --- /dev/null +++ b/uk/resources/README.md @@ -0,0 +1,154 @@ + + + Claude How To + + +# Claude How To — Брендові ресурси + +Повна колекція логотипів, іконок та фавіконів для проєкту Claude How To. Усі ресурси використовують дизайн V3.0: компас з символом кодової дужки (`>`), що представляє направлену навігацію кодом — з палітрою Чорний/Білий/Сірий та акцентом Яскраво-зелений (#22C55E). + +## Структура каталогів + +``` +resources/ +├── logos/ +│ ├── claude-howto-logo.svg # Основний логотип - Light mode (520×120px) +│ └── claude-howto-logo-dark.svg # Основний логотип - Dark mode (520×120px) +├── icons/ +│ ├── claude-howto-icon.svg # Іконка додатку - Light mode (256×256px) +│ └── claude-howto-icon-dark.svg # Іконка додатку - Dark mode (256×256px) +└── favicons/ + ├── favicon-16.svg # Фавікон - 16×16px + ├── favicon-32.svg # Фавікон - 32×32px (основний) + ├── favicon-64.svg # Фавікон - 64×64px + ├── favicon-128.svg # Фавікон - 128×128px + └── favicon-256.svg # Фавікон - 256×256px +``` + +Додаткові ресурси в `assets/logo/`: +``` +assets/logo/ +├── logo-full.svg # Знак + текст (горизонтально) +├── logo-mark.svg # Тільки символ компасу (120×120px) +├── logo-wordmark.svg # Тільки текст +├── logo-icon.svg # Іконка додатку (512×512, округлена) +├── favicon.svg # 16×16 оптимізований +├── logo-white.svg # Біла версія для темних фонів +└── logo-black.svg # Чорна монохромна версія +``` + +## Огляд ресурсів + +### Концепція дизайну (V3.0) + +**Компас з кодовою дужкою** — навігація зустрічає код: +- **Кільце компасу** = Навігація, пошук шляху +- **Північна стрілка (зелена)** = Напрямок, прогрес на навчальному шляху +- **Південна стрілка (чорна)** = Основа, міцний фундамент +- **Дужка `>`** = Промпт терміналу, код, контекст CLI +- **Позначки** = Точність, структуроване навчання + +### Логотипи + +**Файли**: +- `logos/claude-howto-logo.svg` (Light mode) +- `logos/claude-howto-logo-dark.svg` (Dark mode) + +**Специфікації**: +- **Розмір**: 520×120 px +- **Призначення**: Основний логотип заголовку/брендингу з текстом +- **Використання**: Заголовки сайтів, бейджі README, маркетингові матеріали, друковані матеріали +- **Формат**: SVG (повністю масштабований) +- **Режими**: Light (білий фон) та Dark (фон #0A0A0A) + +### Іконки + +**Файли**: +- `icons/claude-howto-icon.svg` (Light mode) +- `icons/claude-howto-icon-dark.svg` (Dark mode) + +**Специфікації**: +- **Розмір**: 256×256 px +- **Призначення**: Іконка додатку, аватари, мініатюри +- **Формат**: SVG (повністю масштабований) + +### Фавікони + +Оптимізовані версії різних розмірів для веб-використання: + +| Файл | Розмір | DPI | Використання | +|------|--------|-----|-------------| +| `favicon-16.svg` | 16×16 px | 1x | Вкладки браузера (старі браузери) | +| `favicon-32.svg` | 32×32 px | 1x | Стандартний фавікон | +| `favicon-64.svg` | 64×64 px | 1x-2x | Дисплеї High-DPI | +| `favicon-128.svg` | 128×128 px | 2x | Apple touch icon, закладки | +| `favicon-256.svg` | 256×256 px | 4x | Сучасні браузери, іконки PWA | + +## Інтеграція HTML + +### Базове налаштування фавіконів + +```html + + + + + + + + + +``` + +## Палітра кольорів + +### Основні кольори +- **Чорний**: `#000000` (Основний текст, обведення, південна стрілка) +- **Білий**: `#FFFFFF` (Світлі фони) +- **Сірий**: `#6B7280` (Вторинний текст, малі позначки) + +### Акцентний колір +- **Яскраво-зелений**: `#22C55E` (Північна стрілка, центральна точка, акцентні лінії — тільки для виділень, ніколи як фон) + +### Dark mode +- **Фон**: `#0A0A0A` (Майже чорний) + +### CSS-змінні +```css +--color-primary: #000000; +--color-secondary: #6B7280; +--color-accent: #22C55E; +--color-bg-light: #FFFFFF; +--color-bg-dark: #0A0A0A; +``` + +## Настанови з дизайну + +### Використання логотипу +- Використовуйте на білому або темному (#0A0A0A) фоні +- Масштабуйте пропорційно +- Залишайте вільний простір навколо (мінімум: висота логотипу / 2) +- Використовуйте надані light/dark варіанти для відповідних фонів + +### Доступність +- Високі коефіцієнти контрасту (WCAG AA — мінімум 4.5:1) +- Чисті геометричні форми, розпізнавані при будь-якому розмірі +- Масштабований векторний формат +- Без тексту в іконках (текст додається окремо) +- Без залежності від червоно-зеленого розрізнення кольорів + +## Атрибуція + +Ці ресурси є частиною проєкту Claude How To. + +**Ліцензія**: MIT (див. файл LICENSE проєкту) + +## Історія версій + +- **v3.0** (Лютий 2026): Дизайн компас-дужка з палітрою Чорний/Білий/Сірий + Зелений акцент +- **v2.0** (Січень 2026): Дизайн 12-променевого зоряного спалаху в стилі Claude з смарагдовою палітрою +- **v1.0** (Січень 2026): Оригінальний дизайн іконки прогресії на основі шестикутника + +--- +**Останнє оновлення**: Лютий 2026 +**Поточна версія**: 3.0 (Компас-дужка) diff --git a/uk/scripts/README.md b/uk/scripts/README.md new file mode 100644 index 0000000..d43c273 --- /dev/null +++ b/uk/scripts/README.md @@ -0,0 +1,120 @@ + + + Claude How To + + +# Скрипт збірки EPUB + +Збірка EPUB-книги з markdown-файлів Claude How-To. + +## Функції + +- Організує розділи за структурою каталогів (01-slash-commands, 02-memory тощо) +- Рендерить Mermaid-діаграми як PNG-зображення через Kroki.io API +- Асинхронне паралельне завантаження — рендерить усі діаграми одночасно +- Генерує обкладинку з логотипу проєкту +- Конвертує внутрішні markdown-посилання у посилання на розділи EPUB +- Суворий режим помилок — падає, якщо діаграма не може бути відрендерена + +## Вимоги + +- Python 3.10+ +- [uv](https://github.com/astral-sh/uv) +- Інтернет-з'єднання для рендерингу Mermaid-діаграм + +## Швидкий старт + +```bash +# Simplest way - uv handles everything +uv run scripts/build_epub.py +``` + +## Налаштування розробки + +```bash +# Create virtual environment +uv venv + +# Activate and install dependencies +source .venv/bin/activate +uv pip install -r requirements-dev.txt + +# Run tests +pytest scripts/tests/ -v + +# Run the script +python scripts/build_epub.py +``` + +## Параметри командного рядка + +``` +usage: build_epub.py [-h] [--root ROOT] [--output OUTPUT] [--verbose] + [--timeout TIMEOUT] [--max-concurrent MAX_CONCURRENT] + +options: + -h, --help show this help message and exit + --root, -r ROOT Root directory (default: repo root) + --output, -o OUTPUT Output path (default: claude-howto-guide.epub) + --verbose, -v Enable verbose logging + --timeout TIMEOUT API timeout in seconds (default: 30) + --max-concurrent N Max concurrent requests (default: 10) +``` + +## Приклади + +```bash +# Build with verbose output +uv run scripts/build_epub.py --verbose + +# Custom output location +uv run scripts/build_epub.py --output ~/Desktop/claude-guide.epub + +# Limit concurrent requests (if rate-limited) +uv run scripts/build_epub.py --max-concurrent 5 +``` + +## Вивід + +Створює `claude-howto-guide.epub` у кореневому каталозі репозиторію. + +EPUB включає: +- Обкладинку з логотипом проєкту +- Зміст з вкладеними секціями +- Весь markdown-контент, конвертований у EPUB-сумісний HTML +- Mermaid-діаграми, відрендерені як PNG-зображення + +## Запуск тестів + +```bash +# With virtual environment +source .venv/bin/activate +pytest scripts/tests/ -v + +# Or with uv directly +uv run --with pytest --with pytest-asyncio \ + --with ebooklib --with markdown --with beautifulsoup4 \ + --with httpx --with pillow --with tenacity \ + pytest scripts/tests/ -v +``` + +## Залежності + +Керуються через PEP 723 inline script metadata: + +| Пакет | Призначення | +|-------|-------------| +| `ebooklib` | Генерація EPUB | +| `markdown` | Конвертація Markdown → HTML | +| `beautifulsoup4` | Парсинг HTML | +| `httpx` | Асинхронний HTTP-клієнт | +| `pillow` | Генерація обкладинки | +| `tenacity` | Логіка повторних спроб | + +## Усунення проблем + +**Збірка падає з мережевою помилкою**: Перевірте інтернет-з'єднання та стан Kroki.io. Спробуйте `--timeout 60`. + +**Обмеження частоти**: Зменште паралельні запити з `--max-concurrent 3`. + +**Відсутній логотип**: Скрипт генерує текстову обкладинку, якщо `claude-howto-logo.png` не знайдено.