spar

Продолжайте учиться, пока ИИ пишет код.

Просмотр готового, убедительного кода почти ничему вас не учит. У вас нет позиции, с которой можно его оценить, поэтому вы читаете, киваете и идёте дальше.

spar возвращает эту позицию. Прежде чем агент что-либо напишет, вы говорите, куда относится изменение, как бы вы его сделали и где оно сломается. Затем он реализует, показывает вам разницу и записывает все места, где ваша модель оказалась неверной.

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

Как это выглядит

› add an endpoint for cancelling an order

  spar: level 2 (skeleton), 2 open gaps on "transaction boundaries in an ORM"

  Before I write anything:
    1. Where does this belong, and why there?
    2. How would you approach it? (two sentences)
    3. Where will this go wrong?

› 1. Orders controller, calling into the service
  2. load the order, set status, save
  3. no idea

  [writes the controller, the DI wiring and the error handling,
   and leaves the one line that matters]

  // TODO(spar: decide the transaction boundary. Who opens it,
  //             and what happens if the refund call fails halfway?)

Вы сами пишете эти пять строк. Затем spar done сравнивает их с тем, что написал бы агент, и сортирует каждое различие по одной из трёх категорий: вы что-то неправильно поняли, вы что-то неправильно набрали или ваш вариант лучше. Только первые две записываются как пробелы.

Три недели спустя, в разгар несвязанной работы:

spar: one gap has come due. Ask them to explain "transaction boundaries in an ORM"
in their own words at the next natural pause. Do not show them the answer first.

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

Related MCP server: Learning Assistant MCP Server

Установка

npm i -g spar-agent
spar install                                       # finds your agents, backs up, merges
spar setup --project /path/to/repo --stack ".NET"

Эта последняя строка важна: ничего не происходит в каталоге, который вы не назвали. Свежая установка полностью инертна. Она даже не создаст ~/.spar, пока вы не укажете ей на проект.

spar install осторожен с файлами, которые он не создавал. Он объединяется с тем, что уже есть, сначала создаёт резервную копию и заменяет только те записи, которые добавил сам. Запустите его дважды — второй запуск ничего не изменит. Используйте --dry-run, чтобы увидеть, что он сделает.

Где вы находитесь

spar stats        # in the terminal
spar dashboard    # one self-contained HTML file

CALIBRATION, share of predictions that held, by week
  2026-07-13  ███████▁▁▁   67%     4/6   clean   mean level 2.3
  2026-07-20  ████▁▁▁▁▁▁   44%     4/9   clean   mean level 2.3
  2026-08-03  ████████▁▁   83%    10/12  clean   mean level 0.8
  2026-08-17  ██████████  100%     9/9   clean   mean level 0.3

CURRICULUM, concepts by weakness. The top row is what to learn next.
  * idempotency in webhooks              3 open / 3   box 1.3
    transaction boundaries in an ORM     8 open / 8   box 2.0
    EF change tracking                   0 open / 3   box 5.0

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

Шесть недель вымышленного онбординга на .NET. Страница следует системной теме.

Панель управления — это один файл, который никогда не обращается к сети. Ни CDN, ни веб-шрифтов, ни библиотек графиков, а графики написаны вручную на SVG. Каждое число находится в разметке, поэтому страница читается одинаково с отключёнными скриптами, за строгим CSP или в предпросмотре вложений. Скрипт добавляет только мультивыбор в панель фокуса. Она всё равно откроется, офлайн, по двойному клику, через пять лет.

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

Объяснение с помощью картинки

spar card --layout chain --title "Predict before you're told" \
  --subtitle "The gap between your guess and what was true is worth writing down." \
  --step "you:You predict" --step "agent:AI implements" --step "you:You compare"

Одна идея на карточку, записывается в ~/.spar/cards/. Четыре макета покрывают большинство объяснений: цепочка шагов, расходящаяся схема, последовательность между двумя сторонами и сравнение.

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

Цвет обозначает, чем является объект, а не какой это шаг, поэтому --step "вы:..." сохраняет вы одного цвета на всех ваших карточках. cards.theme в ~/.spar/config.json выбирает вид: neon (по умолчанию, тёмный с контурными рамками) или plain.

Уровни

На уровнях 2 и 3 агент всегда оставляет падающий тест, и spar отказывается от передачи, если его нет. Маркер без теста передаёт вам догадку и ничего, с чем её можно сверить, поэтому единственный способ узнать, были ли вы правы, — спросить агента, а это та зависимость, которую весь инструмент и создан разорвать. Тест позволяет вам работать в одиночку двадцать минут и всё равно знать.

Установите testCommand для проекта, и spar также запустит набор тестов при передаче и ожидает, что он будет красным, потому что тест, который уже проходит на пустой заглушке, ничего не фиксирует:

spar setup --project "$(pwd)" --test-command "npm test"

Эта проверка по умолчанию выключена. Автоматический запуск чужого набора тестов — вмешательство и может быть медленным.

Нет выключателя, только уровень 0. Ваш собственный журнал пробелов предлагает уровень и объясняет почему, и вы всегда можете его переопределить. Переопределения учитываются, потому что кто-то постоянно исправляющий предложение говорит вам, что пороги неверны.

Работа с задачей по шагам

spar plan --from docs/plan.md          # reads ## Task / ### Task headings
spar plan --step "..." --step "..."    # or name the steps yourself
spar plan                              # where am I
spar step done --session <id>

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

Эта гранулярность и есть суть. «Где это пойдёт не так?» — реальный вопрос для «добавить конечную точку отмены» и догадка для «реализовать отмену с возвратом средств», а догадка заставляет число калибровки перестать что-либо измерять.

spar не планирует. Ваш агент читает задачу, а ваш планировщик разбивает её; spar решает, какая часть каждого шага ваша. План живёт в .spar/ в проекте, и spar добавляет его в ваш .gitignore в момент создания.

Что получает каждый агент

MCP стандартизирован там, где хуки — нет, поэтому сервер достигает любого MCP-клиента без адаптера. Единственное, что он не может сделать, — это ворота, потому что MCP-сервер предлагает инструменты и никогда не перехватывает собственные записи хоста. Это ограничение — весь аргумент за поддержку адаптеров хуков для каждого агента и причина, по которой добровольные уровни хороши для пробы, но плохая замена.

Установка в качестве плагина

/plugin marketplace add Lander-Parren/spar

Это предлагает два плагина. spar — этот репозиторий. humanizer необязателен и не мой: это blader/humanizer, MIT, Copyright (c) 2025 Siqi Chen, привязан к конкретному коммиту, а не к его основной ветке.

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

Чего он не будет делать

Всё остаётся на вашей машине, в ~/.spar/. Ни аккаунта, ни телеметрии, ни сетевых вызовов, ни собственного API-ключа. Журнал хранит концепции и недопонимания, а не вашу бизнес-логику, поэтому его безопасно показывать коллеге в виде скриншота.

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

Один раз на задачу, а не на файл. Пятнадцать правок за одним предсказанием — это одни ворота.

Он также следит за командами оболочки, а не только за инструментами записи, потому что агент гораздо чаще использует cat > file <<EOF или perl -0pi, чем специальный инструмент записи, а некоторые настройки говорят ему предпочитать именно это. Команда оболочки останавливается только тогда, когда она действительно пишет куда-то внутри отслеживаемого проекта: перенаправления, tee, sed и perl на месте, назначения cp и mv, а также однострочники интерпретатора, открывающие файл для записи. Чтения и запуски тестов проходят без изменений. Оболочку нельзя разобрать регулярными выражениями, поэтому это намеренно консервативно и пропускает экзотические формы, а не останавливает обычную работу.

Задача остаётся активной, пока в ней есть движение, и истекает после 30 минут тишины (idleMinutes в ~/.spar/config.json). Это измеряет бездействие, а не возраст, поэтому длительная тщательная задача никогда не прерывается на полпути. Если вы начинаете что-то новое до истечения таймера, spar next --session <id> немедленно перевооружает его.

Смещение намеренно. Перевооружение при последующем действии стоит вам тридцати секунд и подталкивает к spar rush, а именно так эти инструменты умирают. Пропуск одной задачи стоит одного пробела, и эта концепция вернётся снова.

Один пробел возвращается в начале сессии, сформулированный как вопрос для следующей естественной паузы. Никогда не очередь, никогда не прерывание. Ответите хорошо — он поднимется на ячейку вверх (1, 3, 7, 16 и 35 дней). Ответите плохо — начнётся завтра заново.

Нет отдельного приложения и нет входящих, которые можно игнорировать, потому что он приходит в ту сессию, в которой вы уже работали.

Попробовать без риска

example/ — это небольшой TypeScript-проект без зависимостей, созданный для того, чтобы на него указывать.

cd example
spar setup --project "$(pwd)" --stack "TypeScript"

Затем попросите агента добавить отмену заказа и посмотрите, как ворота его остановят. example/README.md объясняет, на что обратить внимание.

Где живут инструкции

Команда выдаёт факты. Навык говорит, что с ними делать. spar done печатает diff; что считается недопониманием, а не опечаткой, — в навыке. Ворота сообщают, что задача не была проверена, и называют команды; почему вы предсказываете сначала — в навыке.

Это разделение существует, чтобы процедуру мог прочитать любой клиент, поддерживающий навыки, и изменить без выпуска. Для агентов, которые не могут загружать навыки, spar guide <topic> печатает те же разделы из того же файла:

spar guide                       # list the topics
spar guide the-closing-review

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

npm install
npm test              # spar's own suite
npm run build
npm run emit          # regenerate the checked-in hook configs
npm run validate:example   # drive every hook end to end against example/

validate:example — тот, что ловит проблемы с подключением. Модульные тесты доказывают части; этот скрипт доказывает, что реальная полезная нагрузка хука даёт правильное решение, во временном домашнем каталоге, против собранного бинарника.

Одно и то же определение хука проверяется трижды: в макете плагина Claude Code, в пространстве имён Agent Plugins и в Cursor. Два стандарта расходятся во мнениях о том, где должны находиться файлы, специфичные для клиента, поэтому нет единого места, удовлетворяющего обоим. Все три генерируются из src/core/hookconfig.ts с помощью npm run emit, и тест падает, как только они расходятся.

Лицензия

MIT