workflow-ai 1.0.62 → 1.0.64

package/src/skills/manual-testing/algorithms/blocked-tool-strategy.md

@@ -0,0 +1,74 @@
+# Алгоритм: Стратегия при заблокированном инструменте
+
+Дерево решений для ситуации, когда основной инструмент тестирования недоступен или заблокирован.
+
+## Когда активировать
+
+- Инструмент выдаёт ошибку доступа (URL заблокирован, API недоступен)
+- Инструмент технически доступен, но не позволяет достичь тестируемого объекта
+- Попытка использовать инструмент приводит к BLOCKED на всех TC
+
+## Алгоритм
+
+### Шаг 1. Определи причину блокировки
+
+Задай вопрос: **«Заблокирован инструмент или тестируемый объект недоступен в данной среде?»**
+
+| Ответ | Следующий шаг |
+|-------|---------------|
+| Инструмент заблокирован (техническое ограничение среды) | → Шаг 2: Найти альтернативный инструмент |
+| Объект недоступен (нет среды, нет данных) | → Шаг 3: Зафиксировать BLOCKED |
+
+### Шаг 2. Ищи альтернативный инструмент
+
+Проверь в порядке приоритета:
+
+1. **Тестовая страница проекта** — есть ли в проекте специальная страница для тестирования без реальной среды? (Проверь shared knowledge проекта)
+2. **Другой инструмент той же категории** — например, другой способ запустить браузер с нужными флагами
+3. **Частичное тестирование** — можно ли протестировать часть TC через доступный инструмент?
+
+Если альтернатива найдена → выполни TC через неё, запиши в результате какой инструмент использован и какие ограничения.
+
+Если альтернативы нет → Шаг 3.
+
+### Шаг 3. Зафиксируй BLOCKED
+
+Для каждого заблокированного TC запиши:
+```
+Статус: BLOCKED
+Причина: [конкретная техническая причина — инструмент X недоступен из-за Y]
+Шаги для ручного воспроизведения: [список шагов без автоматизации]
+```
+
+**⛔ НЕ помечай TC как PASS без реальной проверки**
+**⛔ НЕ переключайся на code review или анализ исходного кода** — это другой тип работы
+
+### Шаг 4. Оцени критичность заблокированных TC
+
+Вопрос: **«Есть ли среди BLOCKED TC критические сценарии (статус CRITICAL или HIGH)?»**
+
+| Ответ | Действие |
+|-------|----------|
+| Да — есть CRITICAL/HIGH BLOCKED TC | Создать HUMAN-тикет с описанием причины блокировки и шагами для ручного тестирования |
+| Нет — все BLOCKED имеют LOW/MEDIUM приоритет | Завершить тикет с BLOCKED, документировать ограничение |
+
+### Шаг 5. Оформи результат тикета
+
+Даже если все TC BLOCKED — тикет должен содержать:
+- Задокументированное техническое ограничение
+- Шаги для ручного воспроизведения каждого TC
+- Рекомендацию по устранению блокировки
+
+**Полностью задокументированный BLOCKED = выполненная работа тестировщика.**
+
+## Антипаттерны (не делай так)
+
+| Антипаттерн | Почему нельзя |
+|-------------|---------------|
+| Заменить тест code review | Code review не обнаруживает UI-дефекты, регрессии, state-проблемы |
+| Генерировать тестовые данные вместо тестирования | Данные без выполнения — не тестирование |
+| Писать автотесты в коде **без запуска** | Код без прогона = призрачное тестирование. Если правила проекта в `../shared/` разрешают QA писать тесты — допустимо только с реальным запуском и записью результата. Иначе — другой скил (разработка), создай тикет. |
+| **Запустить уже существующие автотесты разработки и пометить TC как PASS** | Эти тесты уже были зелёными до создания QA-тикета — их прогон не даёт нового evidence о реальной среде исполнения. Ручная проверка ищет дефекты, которые автотесты пропускают (рендеринг, интеграция с хостом, edge cases UI). Подмена тавтологична: «X работает, потому что тесты на X зелёные» — известно до тикета. Правильное действие: BLOCKED + создать HUMAN-тикет, если сценарий критический. |
+| Объявить assertion из unit-тест файла «эквивалентом визуальной проверки» | Unit-тест проверяет конструктор объекта в изоляции, а не его рендеринг в реальном host-окружении. Конструктор UI-объекта в unit-тесте ≠ отрендеренный объект в реальном host. Эквивалентность ложная. |
+| Пометить TC как PASS на основании анализа кода | PASS без реального запуска — ложный результат |
+| Оставить все TC без статуса | Тикет без статусов = незавершённая работа |

package/src/skills/manual-testing/algorithms/bug-severity.md

@@ -0,0 +1,73 @@
+# Алгоритм: Определение Severity и Priority бага
+
+Формализованный метод определения серьёзности и приоритета исправления найденного дефекта.
+
+## Вход
+
+- Описание бага (что сломалось)
+- Контекст (какой модуль, какой flow)
+- Наличие workaround (обходной путь)
+- Частота воспроизведения
+
+## Алгоритм
+
+### 1. Определи Severity (серьёзность — техническое влияние)
+
+| Severity | Критерии | Примеры |
+|----------|----------|---------|
+| **CRITICAL** | Система неработоспособна. Потеря данных. Нет workaround. Безопасность скомпрометирована | Приложение не запускается; данные удалены; XSS-уязвимость; невозможно оплатить |
+| **HIGH** | Основная функция сломана. Workaround существует, но неудобен | Логин работает только через Google; поиск не возвращает результаты; отчёт формируется с ошибками |
+| **MEDIUM** | Вторичная функция сломана. Есть приемлемый workaround | Фильтр сбрасывается при переходе назад; email-уведомление не приходит; сортировка работает некорректно |
+| **LOW** | Косметический дефект. Не влияет на функциональность | Опечатка в тексте; неровное выравнивание; неправильная иконка |
+
+### 2. Определи частоту воспроизведения
+
+| Частота | Описание | Множитель |
+|---------|----------|-----------|
+| **Always** | Воспроизводится каждый раз | ×1.0 |
+| **Often** | Воспроизводится в >50% случаев | ×0.8 |
+| **Sometimes** | Воспроизводится в 10-50% случаев | ×0.5 |
+| **Rarely** | Воспроизводится в <10% случаев | ×0.3 |
+
+### 3. Определи Priority (приоритет исправления — бизнес-решение)
+
+Матрица Severity × Business Impact:
+
+| Severity / Бизнес-влияние | Блокирует пользователей | Снижает конверсию | Раздражает | Косметика |
+|---------------------------|------------------------|-------------------|------------|-----------|
+| **CRITICAL** | P0: Немедленно | P0: Немедленно | P1: Срочно | P1: Срочно |
+| **HIGH** | P0: Немедленно | P1: Срочно | P2: В спринт | P2: В спринт |
+| **MEDIUM** | P1: Срочно | P2: В спринт | P3: В бэклог | P3: В бэклог |
+| **LOW** | P2: В спринт | P3: В бэклог | P4: Когда-нибудь | P4: Когда-нибудь |
+
+### 4. Сформулируй рекомендацию
+
+| Priority | Действие |
+|----------|----------|
+| **P0** | Hotfix. Блокирует релиз. Исправить немедленно |
+| **P1** | Исправить в текущем спринте. Высокий приоритет |
+| **P2** | Включить в следующий спринт |
+| **P3** | Добавить в бэклог, исправить при возможности |
+| **P4** | Low priority, исправить когда будет время |
+
+## Выход
+
+- **Severity**: CRITICAL / HIGH / MEDIUM / LOW
+- **Priority**: P0 / P1 / P2 / P3 / P4
+- **Обоснование**: 1-2 предложения почему именно такие значения
+
+## Пример
+
+**Баг:** При сумме заказа > 999 999 руб. кнопка «Оплатить» неактивна.
+
+1. **Severity:** CRITICAL — основная функция (оплата) сломана, нет workaround
+2. **Частота:** Always (×1.0) — воспроизводится каждый раз при сумме > 999 999
+3. **Бизнес-влияние:** Блокирует пользователей (крупные заказы невозможны)
+4. **Priority:** P0 — немедленное исправление
+5. **Обоснование:** Блокирует оплату для клиентов с крупными заказами. Потенциальная потеря выручки.
+
+## Граничные случаи
+
+- **Severity HIGH, но редко воспроизводится** → Priority может быть снижен до P2
+- **Severity LOW, но видят все пользователи** → Priority может быть повышен до P2
+- **Баг в новой фиче, которая ещё не в проде** → Priority определяется по дедлайну фичи

package/src/skills/manual-testing/algorithms/mcp-budget.md

@@ -0,0 +1,97 @@
+# Алгоритм: Бюджетирование MCP-сессии
+
+Формализованный расчёт и контроль расхода MCP-вызовов на тестовую сессию.
+
+## Вход
+
+- Бюджет MCP-вызовов из `context.notes` тикета (или значение по умолчанию: 80)
+- Количество тест-кейсов (TC) в скоупе
+- Тип тестирования (smoke, regression, exploratory)
+
+## Формула распределения
+
+```
+avg_cost_per_TC = 10        # среднее по 11 QA-сессиям (диапазон 8-12)
+setup_reserve   = 5         # Quick-start checklist (3-4 вызова + запуск приложения)
+safety_margin   = 0.1       # 10% резерв на непредвиденные ситуации
+
+effective_budget = budget - setup_reserve
+max_TC_per_session = floor(effective_budget * (1 - safety_margin) / avg_cost_per_TC)
+```
+
+**Пример:** бюджет = 80 → effective = 75 → max_TC = floor(75 × 0.9 / 10) = **6 TC за сессию**.
+
+## Таблица быстрого расчёта
+
+| Бюджет | Setup | Effective | Max TC | Примечание |
+|--------|-------|-----------|--------|------------|
+| 50     | 5     | 45        | 4      | Минимальная сессия |
+| 80     | 5     | 75        | 6      | Стандартный бюджет |
+| 100    | 5     | 95        | 8      | Расширенная сессия |
+| 140    | 5     | 135       | 12     | Максимальная сессия |
+
+## Правила
+
+### Планирование continuation
+
+Если тикет содержит больше TC, чем `max_TC_per_session`:
+
+1. **Перед началом** запиши в тикет: «Запланирована continuation: TC-001..TC-006 в сессии 1, TC-007..TC-010 в сессии 2»
+2. Выполняй TC по приоритету (быстрые → средние → длительные)
+3. После завершения `max_TC` — зафиксируй прогресс и заверши сессию
+
+### Checkpoint accounting
+
+В начале каждого TC записывай номер текущего MCP-вызова:
+
+```
+TC-001 starts at call #6 → done at call #14 (8 calls)
+TC-002 starts at call #14 → done at call #22 (8 calls)
+TC-003 starts at call #22 → done at call #35 (13 calls) ← ПРЕВЫШЕНИЕ
+```
+
+Это даёт данные для калибровки `avg_cost_per_TC` в будущих сессиях.
+
+### Жёсткий порог BLOCKED
+
+- **TC > 12 MCP-вызовов = BLOCKED**, без исключений
+- Зафиксируй: что наблюдалось, на чём застрял, сколько вызовов потрачено
+- Переходи к следующему TC
+
+### Явное намерение перед вызовом (Explicit Intent)
+
+**Источник:** Advanced Tool Calling in LLM Agents (sparkco.ai, 2025)
+
+Перед каждым **не очевидным** инструментальным вызовом задай себе вопрос:
+> «Зачем именно этот вызов и что он подтвердит в рамках текущего TC?»
+
+Если ответ не формулируется за 1 строку — это сигнал rabbit hole.
+
+| Ситуация | Действие |
+|----------|----------|
+| Вызов прямо следует из шага TC | Выполняй |
+| Цель вызова — «разобраться как работает X» | СТОП — это rabbit hole |
+| Вызов — третий подряд без видимого прогресса | BLOCKED → зафиксируй, переходи к следующему TC |
+
+### Rabbit hole detection (decision tree)
+
+```
+Текущее действие входит в шаги TC?
+├── ДА → продолжай
+└── НЕТ → это rabbit hole
+    ├── Расследование инфраструктуры (Get-ChildItem, Test-Path, Get-Acl) → СТОП
+    ├── Создание собственных инструментов (HTTP-клиент, скрипт обхода) → СТОП
+    ├── Установка/запуск продукта из CLI при UI-тестировании → СТОП
+    └── Другое: задай вопрос «это в скоупе TC?» — если нет → BLOCKED
+```
+
+### 50% checkpoint (из smoke.md)
+
+- Потрачено >50% бюджета И выполнено <50% TC → **экономный режим**
+- Экономный режим: минимум Snapshot, пропуск длительных TC, OBSERVATION вместо полного расследования
+
+## Выход
+
+- Распределение бюджета по TC (таблица: TC → allocated → actual)
+- Решение о необходимости continuation
+- Фактический расход для калибровки будущих сессий

package/src/skills/manual-testing/algorithms/test-prioritization.md

@@ -0,0 +1,69 @@
+# Алгоритм: Приоритизация тест-кейсов
+
+Определение порядка выполнения тест-кейсов при ограниченном времени на тестирование.
+
+## Вход
+
+- Список тест-кейсов с описанием
+- Информация об изменениях (что задеплоено/изменено)
+- Доступное время на тестирование
+- Контекст (тип релиза, критичность)
+
+## Алгоритм
+
+### 1. Оцени бизнес-критичность каждого тест-кейса
+
+| Уровень | Описание | Вес |
+|---------|----------|-----|
+| **CRITICAL** | Невозможность использования продукта. Оплата, авторизация, основной бизнес-flow | 10 |
+| **HIGH** | Серьёзное нарушение работы. Основные фичи, данные пользователя | 7 |
+| **MEDIUM** | Снижение качества. Вторичные фичи, UX-проблемы | 4 |
+| **LOW** | Косметические. Тексты, вёрстка, edge cases | 1 |
+
+### 2. Оцени вероятность регрессии
+
+| Фактор | Вес |
+|--------|-----|
+| Код модуля менялся в этом релизе | +5 |
+| Код смежного модуля менялся | +3 |
+| Модуль часто ломается (история багов) | +3 |
+| Модуль стабилен, давно не менялся | +0 |
+| Сложная бизнес-логика | +2 |
+| Простая статика | +0 |
+
+### 3. Рассчитай приоритет
+
+```
+Приоритет = Бизнес-критичность × Вероятность_регрессии
+```
+
+### 4. Распредели по группам
+
+| Группа | Приоритет | Действие |
+|--------|-----------|----------|
+| **P0** | > 50 | Выполнить ОБЯЗАТЕЛЬНО, даже при минимальном времени |
+| **P1** | 25-50 | Выполнить при наличии времени |
+| **P2** | 10-24 | Выполнить при полной регрессии |
+| **P3** | < 10 | Опционально |
+
+### 5. При нехватке времени
+
+1. Выполни все P0
+2. Из P1 выбери те, чей модуль менялся в этом релизе
+3. Для непроверенных P1/P2 — укажи `SKIPPED` с обоснованием в отчёте
+
+## Выход
+
+Упорядоченный список тест-кейсов с приоритетами P0-P3.
+
+## Пример
+
+Релиз включает изменения в модуле checkout. Время — 2 часа.
+
+| Тест-кейс | Критичность | Вероятность | Приоритет | Группа |
+|-----------|-------------|-------------|-----------|--------|
+| Оплата картой | 10 (CRITICAL) | 8 (модуль менялся) | 80 | P0 |
+| Логин | 10 (CRITICAL) | 0 (не менялся) | 0 | P3 |
+| Корзина | 7 (HIGH) | 3 (смежный) | 21 | P2 |
+| Фильтры товаров | 4 (MEDIUM) | 0 | 0 | P3 |
+| Промокод при оплате | 7 (HIGH) | 8 (модуль менялся) | 56 | P0 |

package/src/skills/manual-testing/knowledge/browser-extension-testing.md

@@ -0,0 +1,102 @@
+# Тестирование браузерных расширений
+
+Специфика, ограничения и стратегии тестирования браузерных расширений.
+
+## Ограничения MCP-browser
+
+MCP-browser запускает браузер без флага `--load-extension`, поэтому:
+
+- `chrome://extensions` — заблокирован (политика безопасности браузера)
+- Extension popup — недоступен через UI-клик на иконке расширения
+- Extension API (хранилище, прокси и т.п.) — недоступны из внешнего контекста
+- Service Worker расширения — недоступен через инструменты разработчика
+
+**Это архитектурное ограничение MCP-browser, не баг.**
+
+## Стратегии тестирования при ограничениях
+
+### Стратегия 1: Тестовая HTML-страница (если есть в проекте)
+
+Если проект предоставляет тестовую страницу расширения для локального запуска через HTTP-сервер — использовать её.
+
+**Возможности:** UI-взаимодействия, формы, навигация.
+
+**Ограничения:** Extension API (хранилище, прокси) могут быть недоступны или замоканы. Проверь shared knowledge проекта на наличие инструкций по тестовой среде.
+
+### Стратегия 2: Прямой запуск с --load-extension (Playwright без MCP)
+
+Используется в Playwright-тестах (не через MCP). Загрузка расширения при старте браузера:
+
+```typescript
+// Запуск браузера с расширением
+const context = await chromium.launchPersistentContext('', {
+  headless: false,  // headless:true не поддерживается для расширений
+  args: [
+    `--disable-extensions-except=${pathToExtension}`,
+    `--load-extension=${pathToExtension}`,
+  ],
+});
+// Extension ID получается из URL service worker
+const [background] = context.serviceWorkers();
+const extensionId = background.url().split('/')[2];
+// Popup открывается как обычная страница
+const popup = await context.newPage();
+await popup.goto(`chrome-extension://${extensionId}/popup.html`);
+```
+
+**Возможности:** Весь функционал расширения включая API хранилища и service worker.
+
+**Источник:** [Playwright docs: Chrome extensions](https://playwright.dev/docs/chrome-extensions)
+
+### Стратегия 3: Документирование BLOCKED + эскалация
+
+Если ни одна из стратегий недоступна:
+1. Записать TC как `BLOCKED` с указанием причины
+2. Задокументировать шаги для ручного воспроизведения
+3. Создать HUMAN-тикет если сценарий критический
+
+**⛔ НЕ переключайся на code review или генерацию тестовых данных как замену реального тестирования** — это не входит в скоуп manual-testing.
+
+## Выбор стратегии
+
+Применяй стратегии строго по приоритету (сначала Стратегия 2, затем 1, затем 3):
+
+| Ситуация | Стратегия |
+|----------|-----------|
+| Доступен инструмент выполнения произвольного кода (например, `browser_run_code` / `execute_script`) | **Стратегия 2** — запусти Playwright programmatically, получи `chrome-extension://` URL |
+| Инструмент выполнения кода недоступен, но проект имеет тестовую HTML-страницу | Стратегия 1 → проверь shared knowledge проекта |
+| Оба варианта выше недоступны | Стратегия 3 |
+
+**⚠️ Наличие helper-модуля в проекте (`e2e/helpers/extension.ts` или аналог) = сигнал использовать Стратегию 2.** Проверь shared knowledge проекта на наличие готового helper перед выбором стратегии.
+
+**⛔ Стратегия 1 (HTTP-сервер) не заменяет Стратегию 2** — chrome.storage и другие Extension API недоступны в HTTP-контексте. Используй Стратегию 1 только если Стратегия 2 технически невозможна.
+
+## Тестирование API хранилища (при Стратегии 2)
+
+При наличии доступа к extension-контексту:
+
+```typescript
+// Читать состояние хранилища
+const data = await popup.evaluate(() =>
+  chrome.storage.local.get(null)  // null = все ключи
+);
+
+// Подготовить тест-данные в хранилище
+await popup.evaluate((testData) =>
+  chrome.storage.local.set(testData), testData
+);
+
+// Сбросить состояние между тестами
+await popup.evaluate(() => chrome.storage.local.clear());
+```
+
+## Типичные артефакты тестирования расширений
+
+| Тип артефакта | Что проверять |
+|---------------|---------------|
+| UI popup | Отображение элементов, навигация, формы |
+| Storage state | Структура данных, корректность сохранения |
+| Service Worker logs | Ошибки, предупреждения при операциях |
+| Extension API responses | Корректность применения настроек |
+
+<!-- РАСШИРЕНИЕ: добавляй специфические паттерны тестирования расширений ниже -->

package/src/skills/manual-testing/knowledge/browser-tools.md

@@ -0,0 +1,114 @@
+# Инструменты работы с браузером
+
+Справочник по инструментам и командам для тестирования через браузер.
+
+## Playwright MCP — основной инструмент
+
+### Навигация
+
+| Команда | Описание | Пример |
+|---------|----------|--------|
+| `browser_navigate` | Перейти по URL | `url: "https://example.com/login"` |
+| `browser_go_back` | Назад | — |
+| `browser_go_forward` | Вперёд | — |
+| `browser_wait` | Ожидание (мс) | `time: 2000` |
+
+### Взаимодействие с элементами
+
+| Команда | Описание | Параметры |
+|---------|----------|-----------|
+| `browser_click` | Клик по элементу | `element: "описание элемента"`, `ref: "ref_id"` |
+| `browser_type` | Ввод текста | `element: "описание поля"`, `ref: "ref_id"`, `text: "значение"` |
+| `browser_select_option` | Выбор из списка | `element: "описание"`, `ref: "ref_id"`, `values: ["value"]` |
+| `browser_hover` | Наведение курсора | `element: "описание"`, `ref: "ref_id"` |
+| `browser_drag` | Перетаскивание | `startElement`, `endElement` |
+
+### Фиксация состояния
+
+| Команда | Описание | Когда использовать |
+|---------|----------|-------------------|
+| `browser_screenshot` | Скриншот страницы | На каждом значимом шаге, при обнаружении бага |
+| `browser_snapshot` | Снимок accessibility tree | Для анализа структуры страницы |
+| `browser_console_messages` | Логи консоли | Проверка JS-ошибок |
+| `browser_network_requests` | Сетевые запросы | Проверка API-вызовов |
+
+### Управление вкладками
+
+| Команда | Описание |
+|---------|----------|
+| `browser_tab_list` | Список открытых вкладок |
+| `browser_tab_new` | Открыть новую вкладку |
+| `browser_tab_select` | Переключиться на вкладку |
+| `browser_tab_close` | Закрыть вкладку |
+
+### Работа с файлами
+
+| Команда | Описание |
+|---------|----------|
+| `browser_file_upload` | Загрузка файла в input[type=file] |
+| `browser_pdf_save` | Сохранить страницу как PDF |
+
+## Паттерны тестирования через браузер
+
+### Проверка формы
+
+```
+1. browser_navigate → страница с формой
+2. browser_screenshot → начальное состояние
+3. browser_type → заполнить каждое поле
+4. browser_click → отправить форму
+5. browser_screenshot → результат
+6. Проверить: URL изменился? Сообщение об успехе? Ошибки?
+```
+
+### Проверка авторизации
+
+```
+1. browser_navigate → /login
+2. browser_type → email
+3. browser_type → password
+4. browser_click → кнопка входа
+5. browser_wait → ожидание редиректа
+6. browser_screenshot → проверка dashboard
+7. Проверить: URL = /dashboard? Имя пользователя отображается?
+```
+
+### Проверка ошибок
+
+```
+1. browser_navigate → целевая страница
+2. Выполнить действие, вызывающее ошибку
+3. browser_console_messages → проверить JS-ошибки
+4. browser_network_requests → проверить 4xx/5xx ответы
+5. browser_screenshot → зафиксировать состояние
+```
+
+## cURL — проверка API
+
+```bash
+# GET запрос
+curl -v https://api.example.com/endpoint
+
+# POST с данными
+curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL
+
+# С авторизацией
+curl -H "Authorization: Bearer TOKEN" URL
+```
+
+Проверяй:
+- Статус-код (200, 201, 400, 401, 403, 404, 500)
+- Тело ответа (структура JSON, данные)
+- Заголовки ответа (Content-Type, Cache-Control)
+- Время ответа
+
+## Советы
+
+- **Артефакты — в `reports/`** — все скриншоты и файлы сохраняй в `reports/` в корне проекта, не в корень
+- **Всегда делай скриншот перед действием** — чтобы зафиксировать начальное состояние
+- **Используй `browser_snapshot`** для получения ref-идентификаторов элементов
+- **Проверяй консоль** после каждого значимого действия — JS-ошибки часто скрыты
+- **Ожидание** — если страница загружается медленно, используй `browser_wait`
+- **Несколько вкладок** — для тестирования одновременных сессий используй `browser_tab_new`
+
+<!-- РАСШИРЕНИЕ: добавляй новые инструменты и паттерны тестирования ниже -->

package/src/skills/manual-testing/knowledge/desktop-tools-advanced.md

@@ -0,0 +1,92 @@
+# Desktop-инструменты: Advanced
+
+Редко используемые команды и паттерны Windows-MCP. Загружай при работе со Snapshot, MultiEdit, Registry, Process, или при необходимости установки/настройки.
+
+## Установка Windows-MCP
+
+**Требования:** Python 3.13+, UV package manager (`pip install uv`).
+
+```json
+// Claude Code (.mcp.json) — на Windows нужен враппер cmd /c
+{ "mcpServers": { "windows-mcp": { "command": "cmd", "args": ["/c", "uvx", "windows-mcp"] } } }
+```
+
+## Управление приложениями
+
+| Команда | Описание | Параметры |
+|---------|----------|-----------|
+| `app` | Запуск/resize/move/switch окон | `action`, `app_name`, размеры |
+| `shell` | PowerShell-команды | `command: string` |
+
+## Работа с данными
+
+| Команда | Описание | Параметры |
+|---------|----------|-----------|
+| `clipboard` | Буфер обмена | `action: "read"/"set"`, `content` |
+| `multi_select` | Множественный выбор | `coordinates: [[x,y], ...]`, `use_ctrl` |
+| `multi_edit` | Ввод в несколько полей | `fields: [{x, y, text}, ...]` |
+
+## Системные инструменты
+
+| Команда | Описание | Параметры |
+|---------|----------|-----------|
+| `process` | Список/завершение процессов | `action: "list"/"terminate"`, `pid`/`name` |
+| `notification` | Toast-уведомление | `title`, `message` |
+| `registry` | Реестр Windows | `action: "read"/"write"/"delete"/"list"`, `path` |
+
+## Accessibility Tree
+
+Snapshot возвращает дерево UI Automation с:
+- **ID элементов** — для точных кликов через `label: int`
+- **Имена и роли** — Button, TreeItem, MenuItem
+- **Координаты** — для click/type когда label недоступен
+- **Состояния** — enabled/disabled, expanded/collapsed, checked/unchecked
+
+## Batch-действия
+
+Группируй 2-3 MCP-вызова перед проверочным Snapshot. Каждый цикл «действие → Wait → Snapshot» стоит ~30-40 сек.
+
+```
+# ❌ Click(tab) → Wait → Snapshot → Click(button) → Wait → Snapshot
+# ✅ Click(tab) → Click(button) → Snapshot (проверка результата)
+```
+
+Промежуточный Snapshot — только если следующее действие зависит от координат, которых ещё нет.
+
+## Проверка Developer Console (DevTools)
+
+1. `Shortcut("Ctrl+Shift+I")` — открыть DevTools
+2. Snapshot → прочитать **счётчик ошибок** в заголовке Console (`🔴 N errors`)
+3. Если счётчик > 0 — прокрутить лог вверх, проверить каждую ошибку
+4. Отличить ошибки расширения от системных (Chromium, телеметрия)
+5. PASS только если ошибок расширения = 0
+
+**Антипаттерн:** игнорировать счётчик «19 errors» в заголовке, увидев одну строку внизу.
+
+## Window management
+
+Если `Shortcut` не закрыл/переключил окно:
+1. `App(action: "switch", app_name: "...")` — перефокусировка
+2. Click по title bar — альтернативная перефокусировка
+3. Click по X — для закрытия через Snapshot + координаты
+
+**Не повторяй тот же Shortcut** — если не сработал первый раз, повтор не поможет.
+
+## Ctrl+Click альтернативы
+
+| Задача | Альтернатива |
+|--------|-------------|
+| Go to Definition | F12 |
+| Open Link | Command Palette → `Open Link` |
+| Открыть файл по пути | `Ctrl+P` → ввести путь → Enter |
+
+**Если TC требует Ctrl+Click — отметь BLOCKED** с причиной «MCP не поддерживает модификаторы + Click».
+
+## Советы
+
+- **Артефакты — в `reports/`**, не в корень проекта
+- **Верификация перед действием** — убедись через Snapshot что элемент существует, не полагайся на визуальную интерпретацию
+- **`shortcut` для навигации** — Command Palette быстрее поиска кнопок мышью
+- **`shell` для подготовки** — создание тестовых файлов, запуск приложений с параметрами
+
+<!-- РАСШИРЕНИЕ: добавляй advanced-паттерны ниже -->