Разработка: первый task из плана

После модуля 10 у меня на руках всё для старта. Спецификация в docs/design.md, план в docs/plan.md, ближайшая задача в docs/todo.md, первый executable slice я уже вижу.

Первое, что тянет сделать:

Реализуй всю спецификацию JobTrack за одну сессию.

Логично же. Материалы готовы, контекст собран, задача понятна.

плохой старт.

Даю агенту 10 задач подряд — на выходе один здоровый diff. И дальше веселье начинается) непонятно, что работает, что уехало в сторону, где сломался сценарий. Раскопки вместо разработки.

Второй заход хитрее — не вся спецификация, а первые три задачи из плана.

Реализуй первые 3 задачи, они же маленькие.

Empty state, форма добавления, список, сохранение, стили — всё рядом, один маленький заход. И снова теряю контроль: такой заход ломает контроль. Если что-то не работает, ломаться могло где угодно: состояние, форма, список, сохранение или улучшение, которое агент подкинул по дороге. Опять раскопки.

Короче, первый executable slice важен. И граница одной задачи важнее.

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

Вопрос уже не в том, можно ли писать код. Можно. Вопрос — как не потерять управление на первой же реализации.

В модуле 11 начинается разработка.

До этого мы писали документы: discovery, спецификацию, план, todo. Теперь можно менять код, но только по одной задаче из docs/todo.md. Только не пытайся реализовать всю спецификацию за одну сессию. На мой взгляд, это главная ошибка новичка в вайбкодинге.

Цель модуля скромная: взять первый шаг плана, реализовать, проверить и сохранить маленьким commit. Один шаг, не весь MVP.

Разработку по одной задаче в SPP ведёт фаза subagent-driven-development (внутри — test-driven-development и verification-before-completion).

SPP держит память о проекте в docs/spp/pipeline-state.md: что за продукт, что уже сделано, какие решения приняты. Работу можно прервать и продолжить в новой сессии. Следующий модуль — следующая фаза того же пайплайна, не случайный шаг со стороны.

Почему нельзя запускать весь план сразу

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

В конце — большой диф.

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

Правильный режим: один task, одна реализация, одна проверка, один маленький commit.

Два режима разработки с агентом

Есть 2 нормальных режима работы с агентом.

Agent session — даёшь агенту задачу, он сам читает файлы, правит код, гоняет проверки и приносит diff. Годится, когда задача понятная, ограниченная и уже лежит в docs/todo.md текстом.

Inline work — ты сам в редакторе и дёргаешь агента на конкретный кусок: написать функцию, объяснить ошибку, подобрать текст, глянуть diff. Это про контроль каждой строки и быстрый разбор мелкого фрагмента.

Для курса основной режим — agent session по одному task. Так учишься гонять агента как исполнителя плана, а не размазывать чат в вечную переписку.

Плохой режим — дать агенту всю спецификацию и уйти ждать финал.

Но есть и обратная крайность — слишком мелкий task. Одна строка или тривиальная правка? Не заводи под неё отдельную agent session и отдельный commit. Сделай inline и приложи к соседнему осмысленному task.

Признак простой: acceptance criteria и expected diff звучат смешно, потому что менять нечего — task слишком мелкий.

Цикл одного task

Цикл одного task всегда одинаковый:

1. Взять одну задачу из current.
2. Попросить агента повторить scope: что делает и что не делает.
3. Реализовать только этот task.
4. Запустить smoke check.
5. Запустить тесты или documented manual fallback.
6. Проверить руками, что результат совпал с задачей.
7. Прочитать diff.
8. Исправить текущий task, если разошлось.
9. Сделать commit только этого шага.
10. Обновить docs/todo.md: current уходит в done, next становится current.

И только после этого можно идти дальше.

Smoke check

Smoke check — быстрая проверка, что приложение вообще живое после изменения. И всё.

Для JobTrack это может быть так:

— dev server запускается; — стартовая страница открывается; — нет явной runtime error; — основной экран не пустой из-за падения приложения.

Smoke не заменяет тесты и ручную проверку. Он отвечает на один вопрос: приложение не сломалось на входе?

Тесты и manual fallback

Если в проекте уже есть тесты, запускай их после каждого task. Задача добавляет логику — добавляй проверку по плану.

Test runner ещё не настроен — держи documented manual fallback:

Manual check для task:
- открыть JobTrack;
- выполнить действие из current task;
- увидеть ожидаемый результат;
- записать, что именно проверено руками.

Тесты никто не отменял. Это костыль для раннего проекта, пока нет раннера. Как только появляется тестовая инфраструктура, ручной fallback остаётся как smoke/manual check, а ключевая логика закрывается тестами.

Как понять, что task готов

Task готов, когда сошлось всё разом:

• реализовано только то, что было в current;
• smoke check прошёл;
• тесты или manual fallback подтверждают поведение;
• ручной сценарий совпал с acceptance criteria;
• diff не содержит задач из next и backlog;
• docs/todo.md обновлён после принятия;
• commit можно откатить отдельно.

Тесты зелёные, а руками сценарий не идёт — task не готов. Руками работает, а diff содержит половину будущего MVP — тоже не готов. Это не разработка, это комбайн по производству проблем.

Как ставить задачу агенту

Промпт агенту — примерно такой:

Прочитай docs/design.md, docs/plan.md и docs/todo.md.

Работай только с current task.

Перед изменениями коротко напиши:
- какой task реализуешь;
- что входит в scope;
- что явно не входит в scope;
- какой smoke check запустишь;
- какие тесты или manual fallback нужны;
- какой diff ожидается.

После реализации:
- запусти smoke check;
- запусти тесты или documented manual fallback;
- опиши ручную проверку;
- покажи diff;
- не переходи к следующей задаче без подтверждения.

С таким промптом агент держится плана.

Что делать, если шаг не прошёл

Если шаг не прошёл, не надо героически ехать дальше.

Если smoke check падает, чини запуск. Никаких новых функций поверх сломанного старта.

Если тест или manual fallback говорит, что поведение разошлось с задачей, правишь текущий task. Не следующий, не соседний, не тот, который внезапно захотелось улучшить.

Если diff раздулся, проси агента снести всё, что не про current task.

Агент не понимает задачу — вернись в docs/plan.md и уточни task текстом. Плохая задача в todo не станет хорошей от того, что её начали кодить.

Diff и commit boundary

Diff читаешь до commit.

Нормальный diff для одного task:

— файлы, которые нужны текущему поведению; — тест или documented manual fallback; — точечное обновление docs/todo.md.

Плохой diff:

• будущие задачи из next;
• функции из out of scope;
• auth, search, import, tags без задачи;
• deploy-настройки, если task не про deploy;
• лишний refactor.

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

Когда идти дальше

К следующему task можно переходить только после принятого текущего task: smoke check прошёл, тесты или manual fallback прошли, руками проверено, diff прочитан, commit сделан, docs/todo.md обновлён.

Итог модуля 11 — один шаг плана. Реализованный, проверенный, сохранённый маленьким commit. Один. Работаем дальше.

Цель практики — впервые разрешить агенту менять код, но только по одной задаче из docs/todo.md. Не весь MVP, не три следующих шага, не внезапный рефактор по дороге.

Шаг 1. Проверь вход

Должны быть:

• docs/design.md со статусом принятой спецификации;
• docs/plan.md;
• docs/todo.md;
• в docs/todo.md секция current с одной задачей.

Если чего-то нет, не начинай код. Вернись в модуль 9 или 10.

Шаг 2. Возьми одну задачу из current

Открой docs/todo.md и возьми только первую задачу из current.

Если в current несколько задач, попроси агента сначала привести todo в порядок:

В docs/todo.md в current должно быть ровно 1 задание.
Оставь текущей первую задачу (Slice 0: scaffold), остальные перенеси в next.
Код не трогай.

Шаг 2a. Первый task: scaffold проекта (Slice 0)

Самый первый task в current — это Slice 0: создать проект и запустить dev server. Пока проекта нет, добавлять вакансии некуда.

Команда создания проекта зависит от стека, выбранного в модуле 8. Примеры для канонических стеков:

• Next.js: npx create-next-app@latest jobtrack;
• Vite + React: npm create vite@latest jobtrack -- --template react;
• статический frontend без сборщика: минимальные index.html и app.js.

Как выполнить команду — зависит от инструмента:

• Дорожка A (Codex App): попроси агента в Codex App создать проект этой командой в папке jobtrack, показать, что он сделал, и запустить dev server.
• Дорожка B (Claude Code): в терминале Claude Code выполни команду создания проекта в папке jobtrack, затем запусти dev server.

Критерий Slice 0: dev server стартует и стартовая страница открывается в браузере без ошибок.

Diff для Slice 0 — особый случай. Здесь expected diff — весь каркас проекта, и это единственный task, где большой diff нормален. Дальше правило минимальный diff на задачу снова действует.

Commit для scaffold отдельный:

Проверь git status и staged diff.
После моего подтверждения сделай commit с сообщением:
chore: scaffold проекта

Дальше проведи Slice 0 через тот же цикл проверок ниже (smoke check, diff, commit), а потом повторяй цикл для остальных задач.

Шаг 3. Выбери режим работы

Для курса используй agent session:

Я даю агенту одну задачу из current.
Агент сам меняет файлы, запускает проверки и показывает diff.

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

Не используй режим сделай весь план.

Шаг 4. Дай агенту prompt на один task

Prompt:

Используй /spp.

Прочитай docs/design.md, docs/plan.md и docs/todo.md.

Работай только с current task.

Выбери workflow для implementation session: одна задача, маленький diff, smoke check, tests/manual fallback, review перед commit.

Перед изменениями коротко напиши:
- какой task реализуешь;
- что входит в scope;
- что явно не входит в scope;
- какой smoke check запустишь;
- какие тесты или manual fallback нужны;
- какой diff ожидается.

После реализации:
- запусти smoke check;
- запусти тесты или documented manual fallback;
- опиши ручную проверку;
- покажи diff;
- не переходи к следующей задаче без моего подтверждения.

Шаг 5. Реализуй только текущий task

Разреши агенту писать код только после того, как он повторил scope. Если он не может словами объяснить границы задачи, код ему доверять рано.

Запреты:

• не реализуй весь MVP;
• не бери задачи из next и backlog;
• не добавляй auth/search/import/tags без current task;
• не делай deploy, если task не про deploy;
• не делай большой refactor по дороге.

Шаг 6. Запусти smoke check

Smoke check отвечает на вопрос: приложение после изменения вообще живое?

Пример:

Запусти приложение локально или существующую проверку запуска.
Убедись, что стартовый экран открывается без runtime error.
Если есть smoke-test script, запусти его.

Если smoke падает, сначала исправь запуск. Следующая задача не начинается.

Шаг 7. Проверь поведение

Запусти тесты, если они есть.

Если хочешь поставить автотесты, а test runner ещё не настроен, это делается за 15 минут — см. дополнительный материал «Тесты: установка за 15 минут». Если ставить пока не будешь, используй documented manual fallback:

Manual check:
- открыть JobTrack;
- выполнить действие из current task;
- увидеть ожидаемый результат;
- записать, что именно проверено руками.

Потом пройди сценарий руками. Для первого JobTrack task это может быть:

1. Открыть приложение.
2. Увидеть empty state.
3. Добавить вакансию, если task про добавление.
4. Увидеть ожидаемый результат.

Если поведение не совпадает с acceptance criteria, попроси агента исправить текущий task.

Шаг 8. Прочитай diff

Попроси агента показать diff:

Покажи git diff.
Проверь, что изменения относятся только к current task.
Отдельно перечисли, если в diff есть файлы не из expected diff.
Скажи, не оказался ли task слишком мелким: если менять почти нечего и diff в одну строку, такой task лучше не заводить отдельно, а приложить к соседнему.

Нормальный diff:

• минимальный код текущего task;
• тест или documented manual fallback;
• точечное обновление docs/todo.md.

Плохой diff:

• задачи из next;
• функции из out of scope;
• deploy-настройки без задачи;
• большой refactor;
• auth/search/import/tags без current task.

Шаг 9. Commit только после подтверждения

Если smoke, проверки, ручной сценарий и diff нормальные, попроси агента подготовить commit:

Подготовь к commit только файлы current task.
Покажи staged diff.
После моего подтверждения сделай commit с сообщением:
feat: реализовать первый шаг MVP

Если staged diff содержит лишнее, остановись и попроси убрать лишнее из staged.

Шаг 10. Обнови docs/todo.md и остановись

После принятого task:

• текущую задачу перенеси в done;
• следующую задачу из next перенеси в current;
• не начинай её в этом же шаге без отдельного решения.

Формула: current task done, next task current.

Шаг 11. Повтори цикл до рабочего сценария

Slice 0 — это только запуск пустого приложения. Основного сценария пока нет.

Повторяй цикл шагов 2–10 для задач Slice 1, пока основной сценарий JobTrack не проходит руками: добавить вакансию, увидеть её в списке, изменить статус. Только после этого переходи в модуль 12. Не уходи в дизайн, пока основной сценарий не работает хотя бы на простом UI.