Урок 10.4. Checkpoints

Зачем это нужно

Когда coding agent работает над задачей, он часто делает несколько промежуточных шагов:

read files
-> edit test
-> run test
-> edit implementation
-> run test
-> refactor
-> run verification

Даже если task маленькая, внутри нее могут быть неудачные edits. Агент может:

• сломать файл при первой попытке;
• удалить важную ветку логики;
• применить слишком широкий refactor;
• ухудшить test, чтобы он прошел;
• исправить один bug и добавить другой;
• потерять хороший intermediate state после следующей правки.

Git commit хорош для завершенного reviewable change. Но commit не всегда удобен для каждого промежуточного движения агента. Поэтому многие coding-agent workflows используют checkpoints.

Checkpoint - это промежуточная сохраненная точка, к которой можно вернуться во время agent session. Он полезен как "undo на уровне agent workflow". Но checkpoint не заменяет нормальный Git workflow, commits, tests, branch, pull request и review.

Главная мысль урока:

Checkpoint helps recover from intermediate agent mistakes.
Commit preserves a reviewed change in project history.
They are different safety layers.

Основная идея

Checkpoint - это сохраненное промежуточное состояние работы агента.

Обычно checkpoint отвечает на вопрос:

Можно ли быстро вернуться к состоянию до следующего risky edit?

Git commit отвечает на другой вопрос:

Есть ли осмысленное изменение, которое можно review, share, merge и revert?

Поэтому checkpoint и commit находятся на разных уровнях:

Checkpoint:
agent-session safety

Commit:
project-history safety

Checkpoint может быть создан автоматически после каждого edit или вручную перед рискованным шагом. Commit должен быть сознательным результатом task: small diff, tests, review, message.

Ключевые термины

Checkpoint vs Commit

Checkpoint и commit легко спутать, потому что оба "сохраняют состояние". Но у них разные цели.

Правило:

Use checkpoints for local recovery.
Use commits for project history.

Checkpoint vs Stash vs Worktree

Еще одно полезное сравнение:

Пример:

Agent edits implementation and breaks tests.
Checkpoint helps return to state before bad edit.

Другой пример:

Feature branch was merged and broke production.
Checkpoint не поможет.
Нужен git revert или release rollback.

Где checkpoint находится в agent loop

Контролируемый development loop:

Read -> Plan -> Test -> Implement -> Verify -> Review -> Commit

С checkpoints:

Read
-> Plan
-> checkpoint: before edits
-> Test
-> checkpoint: after RED
-> Implement
-> checkpoint: after first GREEN
-> Verify
-> Refactor
-> checkpoint: before risky refactor
-> Review
-> Commit

В виде схемы:

Checkpoint не является обязательным после каждого шага. Он полезен перед рискованными edits и после ценных промежуточных состояний.

Shadow Git repositories

Один способ реализовать checkpointing - shadow Git repository.

Идея:

Main repository:
project Git history, branches, commits, PRs

Shadow repository:
tool-managed snapshots/checkpoints of working files

Shadow repository может хранить:

• snapshots перед edit;
• snapshots после edit;
• diff между agent steps;
• metadata: prompt, command, timestamp, tool action;
• restore points.

Почему это удобно:

• не загрязняет основную Git history;
• позволяет agent tool делать frequent snapshots;
• дает быстрый undo;
• может работать даже до того, как change готов для commit;
• помогает восстановиться после неудачного refactor.

Но есть ограничения:

• shadow history может быть tool-specific;
• reviewer может ее не видеть;
• CI не работает по shadow checkpoints;
• checkpoint может не включать untracked/generated/external state;
• checkpoint не является PR artifact;
• checkpoint не заменяет commit message и evidence.

Именно поэтому:

Checkpoint не заменяет нормальный Git workflow.

Что должен сохранять хороший checkpoint

Хороший checkpoint должен быть полезен для восстановления.

Минимально:

• timestamp или order;
• short label;
• changed files snapshot или diff;
• текущая branch/worktree;
• reason for checkpoint;
• command/test result рядом с checkpoint, если есть;
• dirty state information;
• relation to task step.

Пример labels:

before-red-test
after-red-confirmed
before-green-implementation
after-targeted-test-pass
before-refactor
after-refactor-tests-pass

Плохой label:

checkpoint 7

Он лучше, чем ничего, но мало помогает человеку.

Когда checkpoint полезен

Checkpoint полезен там, где есть риск потерять хорошее промежуточное состояние.

Типичные сценарии:

Ключевой критерий:

Checkpoint useful when next step may make the current useful state worse.

Когда checkpoint не нужен

Checkpoint может быть лишним.

Не нужен, если:

• task очень маленькая;
• working tree clean, и один edit легко review;
• есть commit перед началом risky work;
• change уже завершен и должен стать commit;
• нет meaningful intermediate state;
• overhead больше пользы.

Пример:

Write one Markdown paragraph in one file.

Здесь достаточно обычного diff review.

Checkpoint не должен превращаться в ritual. Он должен отвечать на конкретный risk.

Когда checkpoint вреден

Checkpoint вреден, если создает ложное чувство безопасности.

Опасные ситуации:

Checkpoint помогает восстановиться от ошибки. Он не предотвращает плохой engineering process.

Ограничения checkpointing

Checkpoint обычно не гарантирует полный snapshot мира.

Он может не включать:

• database state;
• running services;
• external API state;
• generated files outside repo;
• package manager cache;
• browser session;
• Docker volumes;
• secrets in environment;
• OS-level files;
• untracked files, depending on implementation;
• file permissions, depending on implementation.

Поэтому restore checkpoint может вернуть files, но не вернуть environment.

Пример:

Agent ran migration against local database.
Checkpoint restores code files.
Database schema remains migrated.

В таком случае нужен отдельный rollback plan:

• migration rollback;
• reset test DB;
• recreate container;
• clear cache;
• restart service.

Checkpoint и Git status

Перед restore checkpoint нужно смотреть Git state.

Вопросы:

• какие changes появились после checkpoint;
• есть ли user changes;
• есть ли untracked files;
• есть ли staged changes;
• что будет потеряно при restore;
• можно ли сохранить patch перед restore;
• относится ли current dirty state к другой task.

Safe restore mindset:

Before restoring, know what you will discard.

Агент не должен делать restore checkpoint, если это может стереть чужие изменения.

Checkpoint и dirty worktree

Dirty worktree с checkpoints становится еще сложнее.

Сценарий:

User edited docs.
Agent edited auth code.
Checkpoint was created after both changes were present.
Agent wants to restore earlier checkpoint.

Risk:

Restore may remove user docs edits.

Правило:

Do not restore checkpoint across unknown user changes without explicit approval.

Лучше:

• отделить user changes;
• создать worktree для agent task;
• commit/stash user work with consent;
• restore only files owned by agent;
• show diff before restore.

Checkpoint не отменяет правило из урока 10.1:

Never overwrite or revert user changes unless explicitly asked.

Checkpoint и one task - one change

Checkpoint не дает разрешение на большой diff.

Правильное отношение:

One task - one change controls scope.
Checkpoint controls recoverability inside the scope.

Плохо:

У нас есть checkpoints, поэтому можно дать агенту "сделай весь auth".

Хорошо:

Task: AUTH-RESET-04.
Checkpoint before implementation.
Checkpoint after targeted test passes.
Commit after diff review and verification.

Checkpoints делают маленькую task комфортнее, но не превращают большую task в безопасную.

Checkpoint и worktree

Worktree и checkpoint дополняют друг друга.

Сценарий:

../app-auth-api
  branch: feature/auth-reset-api
  Agent A works on backend task

Внутри worktree:

checkpoint: before edit
checkpoint: after RED test
checkpoint: after GREEN

Итог:

Git commit on feature/auth-reset-api

То есть:

• worktree изолирует physical workspace;
• branch изолирует line of work;
• checkpoint изолирует промежуточные states;
• commit сохраняет final reviewable change.

Checkpoint и tests

Checkpoint без tests - это просто сохраненная версия неизвестного качества.

Лучше связывать checkpoint с verification state:

checkpoint: after-red-confirmed
status:
- targeted test fails for expected reason

checkpoint: after-green
status:
- targeted test passed

checkpoint: after-refactor
status:
- targeted and nearby tests passed

Так restore становится осмысленным:

Вернуться к последнему green checkpoint.

А не:

Вернуться к checkpoint 12, кажется, там было лучше.

Checkpoint и TDD

TDD отлично сочетается с checkpoints.

Стадии:

RED
GREEN
REFACTOR

Checkpoints:

before-red:
clean starting state

after-red:
failing test proves missing behavior

after-green:
test passes with minimal fix

before-refactor:
safe point before cleanup

after-refactor:
tests still pass

Если refactor пошел плохо, restore:

return to after-green

Это лучше, чем вручную распутывать плохой cleanup.

Checkpoint и Bug Fix Flow

Bug Fix Flow:

Bug report
-> Reproduce
-> Root cause
-> Failing regression test
-> Fix
-> Test passes
-> Full regression
-> Review

Checkpoints:

checkpoint: before reproduction edits
checkpoint: after failing regression test
checkpoint: before fix
checkpoint: after targeted regression pass
checkpoint: before broader refactor, if any

Самый ценный checkpoint в bug fix:

after failing regression test

Почему:

• bug уже executable;
• fix еще не внесен;
• можно вернуться к доказанному RED;
• reviewer видит, что test не был написан под implementation.

Пример 1. Checkpoint спасает от плохого refactor

Task:

BUG-AUTH-12:
Used reset token can be reused.

Flow:

1. Agent adds regression test.
2. Test fails for expected reason.
3. Checkpoint: after-red-confirmed.
4. Agent implements minimal fix.
5. Test passes.
6. Checkpoint: after-green.
7. Agent tries to refactor auth token service.
8. Refactor breaks expired token behavior.

Без checkpoint:

Нужно вручную отделять good fix от bad refactor.

С checkpoint:

Restore after-green.
Keep bug fix.
Discard bad refactor.
Run tests again.
Commit minimal fix.

Итог:

Refactor becomes follow-up task, not hidden part of bug fix.

Пример 2. Checkpoint не заменяет commit

Scenario:

Agent completed Plan Mode tool policy fix.
All evals passed.
There is a checkpoint named after-green.
No Git commit was created.

Проблема:

• reviewer не видит нормальный commit;
• CI не привязан к checkpoint;
• другой разработчик не получит checkpoint through Git;
• branch может потерять useful state при cleanup;
• history не объясняет change.

Правильный next step:

1. Review git diff.
2. Run verification.
3. Stage related files.
4. Create commit.
5. Open PR or continue workflow.

Checkpoint был полезен во время работы. Но deliverable - commit/PR.

Пример 3. Checkpoint не откатывает database

Task:

Add consumed_at to reset_tokens.

Agent:

1. Creates migration.
2. Runs migration locally.
3. Creates checkpoint.
4. Changes migration incorrectly.
5. Restores checkpoint.

Code files вернулись. Но database может остаться в измененном состоянии.

Что нужно:

Database rollback plan:
- use test DB only;
- run rollback migration if available;
- recreate test database if needed;
- rerun migration apply test.

Checkpoint не заменяет environment rollback.

Пример 4. Checkpoint для prompt/skill editing

Task:

Improve bug-fix skill so agent reproduces bug before editing.

Flow:

1. Baseline eval shows agent edits too early.
2. Checkpoint: before-skill-edit.
3. Agent updates SKILL.md.
4. Eval improves but breaks vague bug report handling.
5. Restore checkpoint.
6. Apply narrower instruction.
7. Run both evals.

Здесь checkpoint полезен, потому что prompt/skill changes часто тонкие. Легко сделать instruction слишком сильной и сломать соседний behavior.

Но final change все равно должен быть:

• diff review;
• eval evidence;
• commit.

Пример 5. Checkpoint в multi-agent context

Multi-agent workflow:

Planner -> Implementer -> Verifier -> Reviewer

Checkpoint может быть у каждого агента:

Но checkpoints должны оставаться локальными recovery points. Coordination между агентами лучше делать через:

• task DAG;
• branches;
• commits;
• PRs;
• verification artifacts;
• reviewer comments.

Нельзя передавать "checkpoint 8" как основной artifact между агентами. Передавать нужно diff, commit, test output, spec update или review finding.

Checkpoint labels

Хорошие labels:

before-agent-edits
after-red-token-reuse-test
after-green-token-reuse-fix
before-auth-service-refactor
after-plan-mode-eval-pass
before-migration-edit

Плохие labels:

save
tmp
checkpoint
try2
maybe-good

Label должен отвечать:

К какому состоянию я вернусь?
Почему это состояние ценно?

Checkpoint notes

Если tooling позволяет добавить note, используйте короткий формат:

Checkpoint:
after-green-token-reuse-fix

Task:
BUG-AUTH-12 / AUTH-RESET-04

State:
- regression test passes
- minimal consumed-token fix implemented
- no refactor yet

Verification:
- reset_token_cannot_be_reused_after_successful_reset: passed

Reason:
Safe point before refactor.

Такая note помогает человеку и future agent понять, что можно восстановить.

Когда создавать checkpoint вручную

Если tool делает автоматические checkpoints, manual checkpoints все равно полезны перед важными стадиями.

Создавайте checkpoint:

• перед первым edit;
• после подтвержденного RED;
• после GREEN;
• перед risky refactor;
• перед массовым rename;
• перед migration;
• перед dependency update, если она approved;
• перед changing generated files;
• перед applying reviewer suggestions;
• перед integration conflict resolution.

Не нужно создавать checkpoint после каждой строки. Хорошая гранулярность - meaningful state.

Restore checkpoint: порядок действий

Перед restore:

1. Inspect current git status.
2. Identify changes after checkpoint.
3. Identify user-owned changes.
4. Decide whether to restore all files or selected files.
5. Preserve any useful patch if needed.
6. Confirm destructive restore if user work may be lost.

После restore:

1. Inspect git status again.
2. Run relevant tests if state should be green.
3. Verify no unrelated files changed.
4. Continue from restored step or commit if ready.

Restore не должен быть слепой кнопкой "назад". Это engineering action.

Rollback levels

Rollback бывает на разных уровнях.

Checkpoint покрывает только первый уровень и иногда часть file-level recovery. Для всего остального нужен Git/process/environment plan.

Rollback decision table

Prompt-шаблоны для checkpoint-aware агента

Prompt 1. Создать checkpoint plan

Work with checkpoint-aware workflow.

Before editing, propose:
- task step sequence;
- checkpoints to create;
- reason for each checkpoint;
- verification expected near each checkpoint;
- rollback plan if a step fails.

Do not treat checkpoints as commits.
Final deliverable still requires diff review, tests and commit/PR.

Prompt 2. Перед risky edit

Before the next risky edit, create or request a checkpoint.

Risky edit:
<refactor/migration/generated update/etc>

Checkpoint label:
<meaningful label>

After checkpoint:
- perform the edit;
- run targeted verification;
- if verification fails badly, propose restore instead of piling more edits.

Prompt 3. Restore decision

A recent edit appears wrong.

Before restoring checkpoint:
- inspect git status;
- summarize changes that would be lost;
- identify possible user changes;
- recommend restore all, restore selected files, or continue fixing;
- ask for approval if restore may discard user work.

Prompt 4. Final evidence

In the final report include:
- which checkpoints were used and why;
- whether any checkpoint was restored;
- final changed files;
- verification commands/results;
- why final state should be committed;
- risks not covered by checkpoints.

Checkpoint policy для проекта

Project rule может быть коротким:

Checkpoint policy:
- Use checkpoints before risky edits: refactor, migration, generated files, dependency changes.
- Prefer meaningful labels: before-refactor, after-green, before-migration.
- Checkpoints do not replace tests, diff review or Git commits.
- Before restoring, inspect git status and protect user changes.
- Final deliverable must be a reviewable diff and, when approved, a Git commit.

Это можно добавить в project instructions или skill, если команда активно использует agents with checkpointing.

Чек-лист: когда checkpoint помогает

[ ] Следующий шаг может ухудшить уже рабочее состояние
[ ] Есть meaningful state, к которому стоит вернуться
[ ] Task не завершена для commit
[ ] Restore не должен затереть user changes
[ ] Checkpoint label понятен
[ ] Verification state рядом с checkpoint понятен
[ ] Environment side effects отдельно учтены

Если большинство пунктов не выполняется, checkpoint может быть лишним.

Чек-лист перед restore checkpoint

[ ] Я посмотрел git status
[ ] Я понимаю, какие files изменены сейчас
[ ] Я знаю, какие changes появились после checkpoint
[ ] Я отделил user changes от agent changes
[ ] Я понимаю, что restore удалит или изменит
[ ] Я сохранил useful patch, если он нужен
[ ] Я получил approval, если есть риск потерять чужую работу
[ ] После restore я запущу relevant verification

Чек-лист перед final commit

Даже если checkpoints использовались, перед commit нужно:

[ ] git status понятен
[ ] git diff просмотрен
[ ] diff связан с одной task
[ ] checkpoints не скрывают unrelated changes
[ ] tests/evals запущены
[ ] not-run checks названы
[ ] environment side effects учтены
[ ] staged diff reviewed
[ ] commit message связан с task
[ ] rollback через Git понятен

Практика 1. Составить checkpoint plan

Task:

BUG-AUTH-12:
Used reset token can be reused.

Заполните:

Возможный ответ:

Практика 2. Выбрать rollback mechanism

Для каждой ситуации выберите mechanism:

Возможное решение:

Практика 3. Написать checkpoint-aware prompt

Task:

Refactor auth token service after all password reset tests are green.

Напишите prompt, который требует:

• проверить current tests;
• создать checkpoint before refactor;
• сделать behavior-preserving refactor;
• запустить tests после refactor;
• restore checkpoint if refactor creates broad failure;
• не делать feature changes;
• финально показать diff и verification.

Шаблон:

Work checkpoint-aware.

Task:
<task>

Before refactor:
- run relevant tests;
- create checkpoint named <label>.

During refactor:
- behavior-preserving changes only;
- no new feature behavior;
- no test weakening.

After refactor:
- rerun tests;
- if failures are broad or unrelated, recommend restoring checkpoint;
- report changed files and verification.

Практика 4. Объяснить, почему checkpoint не заменяет commit

Сценарий:

Agent implemented Plan Mode write-tool guard.
Eval passed.
Tool created checkpoint after success.
No Git commit was made.

Ответьте:

• почему checkpoint недостаточен для завершения task;
• что должен увидеть reviewer;
• какие Git шаги нужны дальше;
• какие risks остаются, если оставить только checkpoint.

Короткий правильный вывод:

Checkpoint is a local recovery point, not a project artifact.
The task needs diff review, verification evidence, staged changes and commit/PR.

Типичные ошибки

Критерии готовности

После урока студент должен уметь:

• объяснить, что такое checkpoint в agent workflow;
• отличить checkpoint от Git commit;
• отличить checkpoint от stash и worktree;
• объяснить shadow repository concept;
• выбрать моменты для checkpointing;
• определить, когда checkpoint не нужен;
• назвать ограничения checkpoint restore;
• составить checkpoint-aware prompt;
• восстановиться после bad refactor без потери good state;
• составить rollback checklist;
• объяснить, почему final deliverable все равно должен быть diff, tests и commit/PR.

Краткое резюме

Checkpoint - это промежуточная recovery point внутри agent workflow.

Он полезен, когда агент делает risky edit и нужно быстро вернуться к последнему meaningful state:

before edit
after RED
after GREEN
before refactor
after verification

Но checkpoint не заменяет:

• branch;
• worktree;
• tests;
• diff review;
• commit;
• pull request;
• environment rollback.

Правильная модель:

Worktree isolates task workspace.
Checkpoint protects intermediate agent steps.
Commit preserves verified reviewable change.
PR provides review gate.

Checkpoint дает удобное undo. Engineering safety появляется только когда checkpoint встроен в disciplined workflow: маленькая task, понятный diff, verification, commit и rollback plan.

Вопросы для самопроверки

1. Чем checkpoint отличается от Git commit?
2. Почему checkpoint не доказывает, что change correct?
3. В какой момент TDD loop особенно полезно создать checkpoint?
4. Какие состояния checkpoint может не восстановить?
5. Почему перед restore checkpoint нужно смотреть git status?

Что дальше

Модуль 10 завершает safety foundation: Git, маленькие changes, worktrees и checkpoints. Дальше курс переходит к multi-agent development. Теперь у нас есть база, без которой несколько агентов быстро создают хаос: task boundaries, reviewable diffs, isolated workspaces, tests, rollback thinking и понятные recovery points.