Руководство по основам mattpocock Skills: заставьте ИИ освоить TDD и структурированную отладку

Обзор проекта

mattpocock/skills — это набор «инженерных методологий» для инструментов AI-программирования. Его главный посыл очень прост: инструменты для AI-кодинга быстры, но это не значит, что они надежны.

В ходе множества практических сессий Мэтт По коком обнаружил четыре наиболее частых сценария провалов в AI-кодинге:

• Несовпадение с требованиями: вам кажется, что ИИ всё понял, но он уходит в сторону
• Слишком многословный вывод: ИИ тратит 20 слов, чтобы сказать то, что можно выразить 1 словом
• Код не работает: нет петли обратной связи — ИИ пишет «в темноте» как в черном ящике
• Архитектура быстро превращается в мусор: AI ускоряет разработку, но так же ускоряет рост программного «энтропийного распада»

Эти проблемы — не баги инструментов, а провал методологии. mattpocock/skills «бьет в цель»: уплотняет decades инженерного опыта в набор компонуемых Skills, чтобы ИИ на любой модели соблюдал одну и ту же инженерную дисциплину.

Сложность / Длительность / Что вы получите

Сложность: начальный уровень — не нужен опыт TDD, достаточно уметь пользоваться командной строкой и инструментами AI-кодинга
Длительность: около 30 минут на полный проход процесса
Результат: выстроите полноценный рабочий процесс от выравнивания требований → TDD → структурированной отладки → архитектурного переосмысления

Портрет целевой аудитории

• Backend / full-stack разработчики с опытом 1–5 лет
• Те, кто уже пользовался Claude Code, Codex или подобными AI-инструментами для программирования
• Чувствуют, что код, сгенерированный ИИ, «вроде работает, но нестабилен», и хотят установить управляемый ритм разработки
• Интересуются TDD, но никак не находят подходящую точку входа

Ключевые зависимости и окружение

Полное дерево структуры проекта

skills/
├── CLAUDE.md                          # Спецификация правил для каталога Skills
├── README.md                          # Обзор и документация по использованию
├── skills/
│   ├── engineering/
│   │   ├── diagnose/
│   │   │   └── SKILL.md               # Процесс структурированной отладки
│   │   ├── grill-with-docs/
│   │   │   └── SKILL.md               # Глубинное интервью с опорой на документацию
│   │   ├── improve-codebase-architecture/
│   │   │   └── SKILL.md               # Диагностика для улучшения архитектуры
│   │   ├── setup-matt-pocock-skills/
│   │   │   └── SKILL.md               # Точка входа для инициализации
│   │   ├── tdd/
│   │   │   ├── SKILL.md               # Вертикальный срез: workflow под TDD
│   │   │   ├── tests.md               # Примеры хороших / плохих тестов
│   │   │   ├── mocking.md             # Лучшие практики для Mock
│   │   │   ├── refactoring.md         # Когда пора рефакторить
│   │   │   ├── deep-modules.md        # Принципы проектирования «глубоких модулей»
│   │   │   └── interface-design.md    # Проектирование интерфейсов под тестирование
│   │   ├── to-issues/
│   │   │   └── SKILL.md               # Разбиение требований на GitHub Issues
│   │   ├── to-prd/
│   │   │   └── SKILL.md               # Генерация PRD
│   │   ├── triage/
│   │   │   └── SKILL.md               # Состояния/машина для разборки Issue
│   │   └── zoom-out/
│   │       └── SKILL.md               # Интерпретация кода с глобальной перспективы
│   ├── productivity/
│   │   ├── caveman/
│   │   │   └── SKILL.md               # Сжатая коммуникация: экономия 75% токенов
│   │   ├── grill-me/
│   │   │   └── SKILL.md               # Глубинное интервью по требованиям
│   │   └── write-a-skill/
│   │       └── SKILL.md               # Руководство по написанию собственных Skills
│   └── misc/
│       ├── git-guardrails-claude-code/
│       │   └── SKILL.md               # Git: защитные ограждения
│       └── scaffold-exercises/
│           └── SKILL.md               # Скэффолдинг для упражнений
└── .claude-plugin/
    └── plugin.json                    # Метаданные плагина

Пошагово

Шаг первый: установите mattpocock Skills

В любом AI-инструменте для программирования, который поддерживает Skills, выполните команду ниже, чтобы установить:

npx skills@latest add mattpocock/skills

Установочный скрипт проведет вас через выбор Skills, которые нужно активировать, и привязку этих Skills к конкретному AI-инструменту. Ключевой шаг: убедитесь, что вы выбрали /setup-matt-pocock-skills — это точка инициализации всех последующих Skills.

Шаг второй: инициализация конфигурации

После установки выполните в AI-инструменте:

/setup-matt-pocock-skills

Этот Skill последовательно спросит вас:

1. Issue Tracker: каким инструментом вы управляете Issue (GitHub / Linear / локальные файлы)
2. Triage Labels: какие слова использовать для тегов Issue (/triage skill будет это использовать)
3. Путь для сохранения документов: где будут храниться сгенерированные ADR и документы

После завершения настройки в корне проекта появится файл CONTEXT.md — как «словарь общего языка» между AI и вами. Этот файл крайне важен: он унифицирует употребление терминов в проекте, а затем все последующие именования и комментарии AI будут строиться на нем.

Шаг третий: выравнивание требований через /grill-me

Когда у вас появляется новое требование или проектное решение, которое вы хотите отдать ИИ на выполнение — не приступайте сразу. Сначала выполните:

/grill-me

ИИ будет задавать вопросы по очереди, перебирая каждую ветку дерева решений. Например, если вы собираетесь «добавить в модуль платежей функциональность возврата средств», AI уточнит:

• Возврат полный или частичный?
• Каковы условия триггера возврата (пользователь вручную / риск-автоматически / оператор вручную)?
• Что происходит с остатком на складе после возврата?
• Нужно ли делать возвратные логи персистентными?

На каждый вопрос ИИ будет предлагать вариант ответа, а вам останется подтвердить или скорректировать. Этот процесс похож на структурированное интервью: он гарантирует, что AI действительно понимает, что вы хотите сделать, а не уходит в сторону «буквальным образом».

Шаг четвертый: /tdd и вертикальные срезы с тест-драйвом

После выравнивания требований переходите к разработке. Здесь — самая ключевая часть mattpocock/skills: запрещены горизонтальные срезы.

Что такое горизонтальный срез? Сначала вы пишете все тесты целиком, потом — весь код целиком. Это «зона наибольшего риска» при неправильном понимании TDD: AI особенно часто так и делает. В итоге тесты «проверяют воображаемое поведение», а не реальное.

Правильный подход: делать только один вертикальный срез за раз.

RED:   Напишите тест — опишите первое поведение → тест падает
GREEN: Напишите минимальный код, чтобы тест прошел → тест проходит
REFACTOR: рефакторинг (по желанию)

Повторяйте этот цикл. Как только AI заканчивает тест, он уже «увидел» реализацию, связанную с ним, поэтому проверяет именно реальное поведение, а не предполагаемое.

Посмотрим на конкретном примере. Допустим, нужно реализовать функциональность оформления заказа в корзине:

// Первая итерация: проверяем только «в корзину можно добавить товар»
import { describe, it, expect } from 'vitest';
import { Cart } from './cart';

describe('Cart', () => {
  it('allows adding an item', () => {
    const cart = new Cart();
    cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
    expect(cart.items).toHaveLength(1);
  });
});

// cart.ts — минимальная реализация, чтобы тест прошел
export interface CartItem {
  id: string;
  name: string;
  price: number;
}

export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }
}

// Вторая итерация: тестируем «корзина может вычислить общую стоимость»
it('calculates total price', () => {
  const cart = new Cart();
  cart.addItem({ id: 'book-1', name: 'TypeScript 入门', price: 59 });
  cart.addItem({ id: 'book-2', name: 'React 实战', price: 79 });
  expect(cart.totalPrice()).toBe(138);
});

// cart.ts — добавляем метод totalPrice
export class Cart {
  items: CartItem[] = [];

  addItem(item: CartItem) {
    this.items.push(item);
  }

  totalPrice(): number {
    return this.items.reduce((sum, item) => sum + item.price, 0);
  }
}

Каждая итерация — это: тест падает → минимальный код проходит → следующая итерация. Это и есть главный ритм вертикального среза.

Шаг пятый: /diagnose и структурированная отладка

Если в коде что-то пошло не так, не просите ИИ «починить баг». Сначала создайте петлю обратной связи — выполните:

/diagnose

/diagnose заставляет AI пройти весь шестистадийный цикл отладки:

Почему этот процесс важен? Потому что самый частый способ отладки у ИИ — «угадать, что сломалось, поменять, посмотреть результат; если не то — угадать снова». Без петли обратной связи это все равно что метать дротики в темноте. /diagnose превращает отладку в инженерную дисциплину, а не в магию.

Типичный сценарий: допустим, ваш платежный интерфейс внезапно начал возвращать 500.

// Стадия 1: построить петлю обратной связи — напишите тест, который локализует проблему до конкретного интерфейса
import { describe, it, expect } from 'vitest';
import { createHonoServer } from './server';
import fetch from 'node-fetch';

describe('Payment API', () => {
  it('returns 200 for valid checkout', async () => {
    const app = createHonoServer();
    const response = await fetch('http://localhost:3000/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items: [{ id: 'book-1', quantity: 1 }],
        userId: 'user-123',
      }),
    });
    expect(response.status).toBe(200); // сейчас тест падает, фактически возвращается 500
  });
});

Стадия 3 сгенерирует список гипотез:

1. Если проблема в том, что «сервис складов таймаутит и из-за этого возникает необработанное исключение», то mock-сервис склада, возвращающий success, уберет 500
2. Если «транзакция с базой данных не фиксируется», то проверка вызова transaction.commit() обнаружит проблему
3. Если «парсинг формата от платежного шлюза не проходит», то валидация mock-данных шлюза сможет воспроизвести проблему

ИИ будет проверять гипотезы по одной, а не складывать все правки сразу.

Шаг шестой: /write-a-skill — создайте собственный Skill

Когда вы накопили набор уникальных рабочих процессов в рамках какого-то проекта, вы можете упаковать их в Skill — чтобы ИИ мог вызывать их в этом проекте в любой момент:

/write-a-skill

AI по очереди спросит вас:

1. Этот Skill покрывает какую область?
2. Какие есть конкретные сценарии использования?
3. Нужно прикладывать скрипты или достаточно чистых инструкций?
4. Есть ли справочные материалы?

Затем будет сгенерирована стандартная структура:

my-custom-skill/
├── SKILL.md              # Основной файл команд (обязателен)
├── REFERENCE.md          # Подробная документация (разбивайте, если контент > 100 строк)
├── EXAMPLES.md           # Примеры использования
└── scripts/
    └── helper.ts         # Скрипт-инструмент (опционально)

Поле description в SKILL.md — это единственный вход для восприятия этого Skill ИИ, и у него строгий формат:

---
name: my-custom-skill
description: Сгенерирует типобезопасный API-клиент из JSON Schema и внедрит Mock-данные.
              Use when user mentions "API client", "generate types", or "mock data".
---

В description первая фраза должна говорить «что он делает», вторая — «в каких сценариях срабатывает», а срабатывающие триггер-слова должны подталкивать ИИ к автоматической загрузке.

Частые проблемы / Troubleshooting

1. ИИ не выполняет тесты и сразу пишет код

Симптом: вы вызываете /tdd, но AI сразу переходит к реализации и пропускает стадию RED.

Как проверить:

• Убедитесь, что в CONTEXT.md определены тестовый фреймворк проекта и соглашения по тестам
• В начале /tdd явно скажите «пишите только один тест, не пишите другой код»
• Если AI все равно пропускает — вручную в разговоре напишите «сначала напишите падающий тест», чтобы вернуть его в RED

Причина: ИИ понимает TDD буквально — считает, что раз «написали тест», то это TDD, но не понимает, что «падение теста» — это сам по себе сигнал.

---

2. Ловушка горизонтального среза — сразу написать все тесты

Симптом: AI в /tdd генерирует 10 тестовых файлов за раз, а затем так же разом пишет всю реализацию.

Как проверить:

• Прямое вмешательство: скажите AI «сначала напиши только первый тест — и реализуй его»
• Добавьте в CONTEXT.md предупреждение об анти-паттерне: «запрещен горизонтальный срез; каждый раз делайте только один вертикальный срез»

Причина: ИИ любит иллюзию «сделал разом все». Горизонтальные срезы создают ощущение полноты, но на деле результат оказывается хрупким.

---

3. В отладочном цикле нет сигнала обратной связи

Симптом: вы вызываете /diagnose, но AI лишь постоянно правит код, не создавая повторяемый сигнал падения.

Как проверить:

• Если Phase 1 не проходит, не переходите к Phase 2. Скажите AI прямо: «еще нет повторяемого сигнала падения; продолжайте строить петлю обратной связи»
• Попробуйте собрать end-to-end сигнал через node-fetch и реальные HTTP-запросы, а не просто замокать весь модуль

Причина: петля обратной связи — это ядро отладки; без нее все последующие действия — вслепую.

---

4. Описание Skill не срабатывает — Skill не запускается автоматически

Симптом: вы написали кастомный Skill, но AI его не загружает.

Как проверить:

• Проверьте, зарегистрирован ли этот Skill в plugin.json
• Убедитесь, что в description есть триггерные слова (те слова, которые пользователь реально будет говорить)
• Убедитесь, что SKILL.md содержит корректные name и description в требуемом формате (YAML frontmatter)

Причина: загрузка Skills зависит от совпадения ключевых слов в description; если описание неточное — Skill не сработает.

---

5. Интервью /grill-me превращается в односторонний отчет

Симптом: при выполнении /grill-me AI получает вашу информацию и ничего не уточняет — не задает вопросов.

Как проверить:

• Сообщайте, что AI зашел в режим интервью, только когда он задает вопросы: продолжайте отвечать и не обрывайте процесс
• Если AI молчит дольше 3 раундов — вручную скажите: «продолжай задавать вопросы, у меня есть еще больше информации»
• Обычно корень в том, что AI «решает, что уже понял», хотя на самом деле это лишь буквальное понимание

Причина: AI склонен быстро «сходиться» к состоянию «похоже, понял», вместо того чтобы перебрать все ветви.

---

6. Слишком большой CONTEXT.md — взрыв токенов

Симптом: по мере продвижения проекта CONTEXT.md становится все больше, и AI начинает ловить переполнение контекста или отвечает медленнее.

Как проверить:

• Регулярно рефакторьте CONTEXT.md: оставляйте «уже стабильные универсальные термины», а «временные решения» переносите в каталог docs/adr/
• /improve-codebase-architecture может помочь определить, какие части стоит вынести из CONTEXT.md

Причина: CONTEXT.md — файл, который динамически растет; если им не заниматься, он станет вторым monorepo.

Дополнительное чтение / Направления развития

Расширение методологии: сам Мэтт По коком — сторонник TypeScript type gymnastics; его курс Total TypeScript — отличное дополнение для понимания типо-ориентированной разработки.

От TDD к улучшению архитектуры: когда ваш кодобаз пройдет несколько циклов TDD-рефакторинга, можно провести архитектурную диагностику через /improve-codebase-architecture. Она опирается на доменную лексику из CONTEXT.md и на записи решений в docs/adr/, чтобы выявлять «поверхностные модули» (сложные интерфейсы при малом функционале) и возможности для рефакторинга.

Экосистема кастомных Skills: философия дизайна mattpocock/skills — «маленькие и компонуемые». Вы не обязаны устанавливать все Skills, которые он предлагает: можно оставить только /tdd и /diagnose и постепенно вводить остальное в ежедневной разработке. Также в сообществе есть и другие разработчики, которые собирают наборы Skills на базе этого фреймворка — за ними тоже стоит следить.