skills-reasoning: четыре навыка мышления для агента

Костя начал неделю плохо. Он попросил агента починить одну падающую проверку — и получил дифф на четыреста строк: заодно переформатирован соседний модуль, заодно «улучшены» комментарии, заодно удалён кусок кода, который никто не просил трогать. Проверка, кстати, чинилась одной строкой.

Вот в чём фокус: агенту не хватало не знаний. Ему не хватало дисциплины рассуждения. Именно это и ставит пак @dzhechkov/skills-reasoning — четыре навыка, которые меняют не то, ЧТО агент знает, а то, КАК он думает:

• investigate — расследовать, не хватаясь за правку;
• solid — писать код как старший инженер: SOLID, TDD, чистый код;
• karpathy-guidelines — поведенческие ограничители против типовых ошибок языковой модели;
• agents-md-creator — собирать для каждого репозитория архитектурный скелет AGENTS.md.

Ключевое слово — устанавливаемый. Это не советы в чате, которые улетают вместе с историей диалога: каждый такой навык лежит файлом в твоём харнесе, агент подхватывает его по описанию задачи или ты называешь его сам.

Второе ключевое слово — нейтральный к стеку. Пак обезличен: из него вычищены упоминания конкретных продуктов, фреймворков и репозиториев, и это проверяется отдельной проверкой на нулевую связанность. Поэтому он одинаково ложится и на Python-монолит Кости, и на твой TypeScript.

Компромисс: ты платишь тем, что агент становится медленнее и разговорчивее — он теперь останавливается и спрашивает. Взамен ты перестаёшь читать диффы, в которых девяносто процентов строк никто не заказывал.

Костя не любит длинные инструкции по установке, и здесь ему повезло: способов ровно три, и все помещаются в четыре строки.

1. Весь пак пресетом — dz init --target claude-code --preset reasoning. Пресет reasoning собирает все четыре навыка разом, это дорога по умолчанию.
2. Один навык точечно — dz init --target claude-code --select karpathy-guidelines. Берёшь ровно то, чего не хватает.
3. Голым npm — npm install @dzhechkov/skills-reasoning; файлы навыков копируются в твой .claude/skills/.

Страница пакета: npm: @dzhechkov/skills-reasoning, исходники и зеркало — GitHub: dz-harness.

Одно правило, которое стоит запомнить сразу. Ищешь systematic-debugging? Его здесь нет и не будет: он уже живёт в @dzhechkov/skills-qe, и пак сознательно не дублирует чужие навыки. Костя потратил полчаса на поиск, прежде чем прочитал эту строчку в README — не повторяй.

Компромисс: пресет ставит четыре навыка вместо одного нужного, и агент читает описания всех четырёх. Взамен ты не собираешь арсенал по кусочкам и не гадаешь, что забыл.

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

Таблица в README пака построена ровно так: первая колонка — не имя, а ситуация, в которой ты оказался.

• «Разберись, почему падает, но НЕ чини» → investigate;
• «Пишу, рефакторю, проектирую, ревьюю код» → solid;
• «Хочу, чтобы агент перестал делать типовые ошибки модели» → karpathy-guidelines;
• «У меня три репозитория, и агент каждый раз заново ищет, куда класть код» → agents-md-creator.

Практическое следствие: имена не заучивают. Агент выбирает навык по описанию задачи — ты просто говоришь «разберись, почему падает импорт, но пока ничего не чини», и включается investigate. Имена в этом курсе нужны, чтобы ты понимал, что происходит под капотом, а не чтобы их помнить.

Компромисс: выбор по описанию удобнее, но менее предсказуем — формулировка «почини быстренько» включит совсем не тот навык, который ты имел в виду. Если нужна гарантия, называй навык явно.

У навыка investigate есть ровно одно правило, и оно написано капслоком: расследуй, не меняй код. Выход — документ с диагнозом, а не дифф.

Звучит как формальность, пока не прочитаешь причину. Навык существует потому, что желание починить прямо во время расследования — источник плохих патчей номер один. Ты ещё не знаешь первопричину, но уже правишь то, что попалось под руку, — и симптом уходит, а причина остаётся.

В навыке перечислены красные флаги — фразы, на которых надо остановиться:

• «сейчас быстренько починю, раз уж я здесь»;
• «это же очевидный однострочник»;
• «расследую и сразу поправлю, сэкономлю время»;
• ты открыл файл инструментом правки вместо чтения.

Костя узнал в этом списке себя целиком. Его личный рекорд — «очевидный однострочник», который через два дня пришлось откатывать, потому что настоящая причина лежала слоем ниже.

Что делать, если чинить хочется невыносимо: записать предполагаемое направление починки словами в раздел «Suggested Fix Direction» и остановиться. Направление словами — часть диагноза; готовый код — уже другая работа.

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

Костя привык искать баг вперёд: «где мы стартуем и что происходит дальше». Навык investigate разворачивает движение — обратная трассировка идёт от симптома назад.

Механика простая и повторяемая:

1. начни с симптома — того, что видит пользователь;
2. найди непосредственную причину этого симптома;
3. спроси: а что вызвало ЕЁ;
4. повторяй, пока не упрёшься в первопричину;
5. на каждой границе слоёв проверяй реальные данные — журналы, отладчик, отпечатки значений.

Пятый пункт — тот, ради которого всё и затевалось. Для системы из нескольких компонентов навык предлагает пройти каждую границу и ответить на три вопроса: какие данные входят, какие выходят и где именно они расходятся с ожидаемыми.

Целиком путь расследования — пять шагов: понять симптом, воспроизвести, трассировать назад, назвать сопутствующие факторы, написать диагноз. Костя раньше начинал сразу с третьего и поэтому регулярно объяснял не тот дефект.

Сопутствующие факторы — не украшение отчёта. Три вопроса: почему это не поймали раньше, может ли тот же класс проблем жить в другом месте, что сделало поиск трудным. Именно отсюда рождаются пропущенные тесты.

Компромисс: проверка данных на каждой границе стоит времени и требует доступа к живой системе. Взамен ты не принимаешь за первопричину первое правдоподобное объяснение.

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

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

1. что проверил и что исключил;
2. что подозреваешь, но подтвердить не смог;
3. какой конкретный диагностический шаг развёл бы гипотезы;
4. прямая формулировка пробела: «я не смог определить X, потому что Y».

Отдельно есть стоп-кран: если ты прочитал десятки файлов, выполнил кучу команд, а первопричина всё ещё не видна — расследование не сходится. Тогда не углубляешься, а останавливаешься, подводишь итог по тем же пунктам и спрашиваешь у человека направление.

Есть и защита от собственной предвзятости — независимая проверка субагентами, и её объём привязан к размеру задачи: маленькая задача (один файл, очевидная трассировка) — ноль проверяющих; средняя (несколько файлов, один сервис) — один; большая (несколько сервисов, неясная трассировка) — два-три, каждый со своего угла. Проверяющие читают только на чтение: они подтверждают или спорят, но не чинят. Несогласие проверяющего — ценная находка, а не помеха: его разбирают до того, как диагноз объявлен окончательным.

Компромисс: отчёт без вывода некомфортно отдавать заказчику. Взамен никто не строит починку на догадке, которую выдали за факт.

Навык karpathy-guidelines — это поведенческие ограничители против типовых ошибок языковой модели, собранные из наблюдений Андрея Карпатого. Начинается он с правила, которое Костя теперь цитирует на планёрках: не додумывай, не прячь непонимание, называй компромиссы.

Четыре требования перед тем, как написать первую строку:

• допущения проговариваются вслух; сомневаешься — спроси;
• есть несколько прочтений задачи — покажи их все, а не выбери одно молча;
• знаешь способ проще — скажи об этом и поспорь, если есть основания;
• что-то непонятно — остановись, назови, ЧТО именно непонятно, и спроси.

Обрати внимание на формулировку третьего пункта: не «сделай проще», а «скажи, что проще, и поспорь». Навык явно разрешает агенту возражать — молчаливое согласие с неудачной постановкой стоит дороже спора.

Четвёртый пункт — самый недооценённый. Разница между «я не понял задачу» и «мне неясно, считаем ли мы отменённые заказы» — это разница между потерянным днём и одним уточняющим вопросом.

Костя завёл себе привычку: если в ответе агента нет ни одного проговорённого допущения, значит агент их не осознал, а не «их не было».

Компромисс: ты получаешь больше вопросов и медленнее стартуешь. Взамен ты не оплачиваешь реализацию не того требования.

Вернёмся к диффу на четыреста строк из первой секции. У навыка karpathy-guidelines для него есть проверка в одну фразу: каждая изменённая строка должна напрямую восходить к запросу пользователя. Костя прогнал свой дифф через неё — прошли одиннадцать строк из четырёхсот.

Правило хирургической правки состоит из запретов, и каждый из них закрывает знакомую подмену:

• не «улучшай» соседний код, комментарии и форматирование;
• не рефактори то, что не сломано;
• держись существующего стиля, даже если сам писал бы иначе;
• увидел посторонний мёртвый код — скажи о нём, но не удаляй.

И одно симметричное разрешение: убирай сирот, которых создали ТВОИ правки — импорты, переменные, функции, ставшие ненужными из-за твоего изменения. Чужой мёртвый код — не твоя уборка.

Рядом живёт правило простоты: минимум кода, решающий задачу, и ничего впрок. Ни фич сверх заказанных, ни абстракций ради одного использования, ни «гибкости», которую не просили, ни обработки невозможных ситуаций. Контрольный вопрос навыка звучит так: написал двести строк там, где хватило бы пятидесяти — перепиши.

Компромисс: ты сознательно оставляешь в репозитории замеченную грязь. Взамен ревьюер видит дифф, в котором каждая строка объяснима, и не ищет твою правку среди косметики.

Четвёртое правило навыка — про то, почему агент постоянно возвращается за уточнениями. Причина обычно не в агенте, а в постановке: сильный критерий успеха позволяет работать самостоятельно, слабый («сделай, чтобы работало») требует непрерывных вопросов.

Навык показывает превращение прямо в виде трёх пар:

• «добавь валидацию» → «напиши тесты на невалидный вход, потом сделай их зелёными»;
• «почини баг» → «напиши тест, воспроизводящий баг, потом сделай его зелёным»;
• «отрефактори X» → «убедись, что тесты зелёные до и после».

Видишь общий приём? В каждой паре справа появляется проверка, которую можно выполнить, а не оценить на глаз. Костя теперь переписывает так каждую задачу, прежде чем отдать её агенту.

Для многошаговых задач навык требует короткого плана в жёсткой форме: каждая строка — это шаг и его проверка.

1. [шаг] → проверка: [чем убедимся]
2. [шаг] → проверка: [чем убедимся]

Строка без правой части — это не шаг плана, а намерение. Именно она потом и превращается в «вроде работает».

Компромисс: формулировка проверяемого критерия — это работа до работы, и на «поменяй цвет кнопки» она выглядит бюрократией. Взамен агент перестаёт возвращаться с вопросом «а как понять, что готово».

Навык solid включается на любой работе с кодом и начинается с процесса, который в нём назван необсуждаемым: красный — зелёный — рефакторинг.

Три фазы читаются буквально:

1. красный — напиши падающий тест, описывающий нужное поведение;
2. зелёный — напиши самый простой код, который его проходит;
3. рефакторинг — почисти, убери дублирование по правилу трёх повторений.

Три закона TDD в навыке сформулированы как ограничения на каждое следующее действие: production-код пишется только чтобы сделать зелёным падающий тест; теста пишется ровно столько, чтобы он упал; кода — ровно столько, чтобы он прошёл.

А теперь фраза, ради которой Костя перечитал секцию дважды: дизайн рождается на стадии рефакторинга, а не во время написания кода. На зелёной фазе твоя задача — пройти тест самым простым способом, даже некрасивым; думать о структуре ты будешь на третьей фазе, когда тесты уже держат спину.

Это переворачивает привычный порядок. Костя раньше проектировал заранее и потом защищал спроектированное. Теперь структура появляется там, где её уже страхуют зелёные тесты.

Компромисс: цикл дороже на старте и требует, чтобы код вообще был тестируемым — на прототипе и в исследовательском коде он тормозит. Взамен рефакторинг перестаёт быть страшным: спину держат тесты.

Костя третий год слушает в своей команде один и тот же спор: что важнее — читаемо или без дублирования. Навык solid спор закрывает, потому что даёт приоритет, а не список: четыре элемента простого дизайна перечислены строго по важности.

1. проходят все тесты — код обязан работать правильно;
2. выражает намерение — читается и раскрывает смысл;
3. нет дублирования — но с оговоркой про правило трёх повторений;
4. минимальность — как можно меньше классов и методов.

Порядок несёт смысл: красивый неработающий код проигрывает работающему некрасивому, а снятие дублирования стоит ниже читаемости. Отсюда и знаменитая формулировка навыка: немного дублирования в десять раз лучше неправильной абстракции.

Теперь про таблицу запахов кода. Легко пролистать её как справочный придаток — и это ошибка: таблица устроена как рабочий инструмент, где у каждого запаха уже назван приём исправления. Длинный метод → извлечение метода. Большой класс → извлечение класса. Длинный список параметров → объект-параметр. Одержимость примитивами → объект-значение. Оператор выбора по типу → полиморфизм. Спекулятивная общность → выкинуть неиспользуемую абстракцию.

Рядом лежит список красных флагов «остановись и подумай»: код без теста, класс больше чем с двумя полями, метод длиннее десяти строк, больше одного уровня вложенности, else там, где хватило бы раннего возврата, абстракция раньше третьего дубликата.

Компромисс: пороги в навыке заданы жёстко и местами спорны — десять строк на метод и два поля на класс подойдут не каждому языку. Взамен у тебя есть измеримая планка вместо «пиши хорошо».

У Кости три репозитория, и каждую сессию агент заново выясняет, куда класть код. Ровно на этот случай существует навык agents-md-creator: он собирает по одному файлу AGENTS.md на репозиторий.

Главная идея — разделение слоёв:

• AGENTS.md — постоянно включённый архитектурный скелет: направление зависимостей, ответственности пакетов («можно» и «нельзя»), запрещённые имена файлов, таблица заморозки god-объектов с измеренными числами, инварианты репозитория, дисциплина рефакторинга, чек-лист изменений. Агент читает его в начале каждой сессии.
• Навыки — деталь по требованию: антипаттерны, признаки обнаружения, решающие ворота. Подгружаются, когда нужны.

Правило, которое навык повторяет несколько раз: скелет не дублирует содержимое навыков. Ловишь себя на том, что пишешь в AGENTS.md список антипаттернов — остановись, это материал навыка; в скелете должна стоять ссылка по имени.

Есть и честное «не применяй». Навык прямо перечисляет случаи пропуска: один маленький репозиторий (хватит одного файла в корне) и уже сильный существующий AGENTS.md, которому нужна пара точечных правок, а не полный конвейер.

А для существующих файлов есть жёсткая установка: считать их мусором и писать заново. Причина названа: старые файлы писались, когда репозиторий был маленьким, и с тех пор разошлись с реальностью. Костя сначала возмутился, потом открыл свой CLAUDE.md двухлетней давности и молча согласился.

Компромисс: «писать заново» иногда выбрасывает пару верных абзацев из старого файла. Взамен ты не наследуешь дрейф, который никто не отслеживал.

Финальная секция — та, где решения принимаешь ты, а Костя только задаёт вопросы.

Самая ошибкоопасная часть AGENTS.md — числа. Навык говорит об этом прямо: измеренные значения строк и методов дают наибольшую долю ошибок в готовых файлах, поэтому их считают командами (wc -l, grep -c), а не оценивают на глаз, и хранят в одном файле измерений, который читают все анализаторы. Одно измерение на всех — иначе анализаторы разойдутся в числах.

Пороги таблицы заморозки заданы двумя уровнями:

• кандидат на заморозку — от 700 строк для сервера и от 500 для интерфейса;
• жёсткий блок — больше 1000 строк ИЛИ больше 50 методов или маршрутов; такой файл не просто замораживают, ему предписывают конкретное действие по расколу.

Почему нижний порог именно 700, объяснено измерением: прогон с порогом «больше 1000» пропускает целую полосу 700–1000, а это ровно та зона, где новые god-объекты копятся незаметно.

Проверяют результат два независимых проверяющих на файл, и роли у них принципиально разные: один смотрит качество содержания (есть ли направление зависимостей, конкретны ли «можно/нельзя», не продублирован ли материал навыков), второй проверяет факты (существуют ли пути, совпадают ли числа с wc -l, ведут ли ссылки на разделы навыков туда, куда обещают). Один проверяющий видит только половину: качественный пропустит неверное число, фактический — отсутствие чек-листа.

Правило применения находок: находка идёт в работу, если её подтвердили минимум двое проверяющих ИЛИ если это объективный факт — число, путь, ссылка на строку. Единичное суждение применяют с оглядкой на эталон качества.

И бюджет длины: 200–400 строк на файл. Меньше 200 обычно означает отсутствие ограничений, но у этого есть законные исключения — чистый индекс-файл и тонкий переходный сервис. Больше 400 означает, что файл начал делать работу навыка.

Компромисс: конвейер тяжёлый — измерения, параллельные анализаторы, две проверки на файл. Для одного маленького репозитория это перебор, и навык сам просит его пропустить.