Урок 10.1. Git как safety mechanism

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

Git в обычной разработке часто воспринимают как инструмент истории и совместной работы. В AI Agent Development у Git появляется еще одна роль: safety mechanism.

AI agent может быстро изменить десятки файлов. Иногда это именно то, что нужно. Иногда это смесь полезного fix, лишнего refactor, случайного форматирования, измененного lockfile, удаленного test и маленькой правки, которая ломает поведение в соседнем модуле.

Git нужен, чтобы человек и reviewer agent могли ответить на вопросы:

• что именно изменилось;
• почему это относится к task;
• какие изменения случайные;
• как откатиться;
• можно ли безопасно review, test и merge;
• не смешались ли разные задачи в одном diff.

Без Git agent-generated changes становятся потоком текста и файлов. С Git они становятся контролируемым изменением.

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

Agent changes must be inspectable, reversible and reviewable.
Git gives us the mechanism.

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

Git защищает AI-разработку не магией, а дисциплиной границ.

Хороший agent workflow выглядит так:

Clean baseline
-> Task branch
-> Agent edits
-> Diff review
-> Tests
-> Commit
-> Pull Request
-> Review
-> Merge or rollback

Каждый этап уменьшает неопределенность.

До изменения:

Мы знаем стартовое состояние.

После изменения:

Мы видим точный diff.

После tests:

Мы знаем, какие проверки прошли.

После commit:

Мы можем вернуться к сохраненной точке.

После PR review:

Мы отделяем useful change от accidental change.

Git не заменяет specification, tests или review. Но Git делает их применимыми к реальному изменению файлов.

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

Для курса достаточно понимать Git не как набор команд, а как систему ответов:

Where am I?
What changed?
What will be committed?
How do I review it?
How do I go back?

Mental Model: три состояния файла

В Git один и тот же файл может находиться в нескольких состояниях.

Для agentic development особенно важны первые два состояния:

• working tree показывает все, что агент изменил;
• index показывает, что вы собираетесь сохранить.

Если вы бездумно делаете:

git add .
git commit

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

Git как safety layer для агента

AI agent работает быстро. Поэтому перед ним нужны guardrails.

Git дает такие guardrails:

Git не говорит, правильно ли изменение с точки зрения продукта. Но Git показывает, что именно изменилось и где можно поставить контроль.

Safe Start перед работой агента

Перед тем как дать агенту задачу, нужно понять стартовое состояние repository.

Минимальная проверка:

git status --short
git branch --show-current
git diff --stat

Что важно увидеть:

• на какой branch вы находитесь;
• есть ли незакоммиченные изменения;
• есть ли untracked files;
• есть ли staged changes;
• отличается ли local branch от remote;
• есть ли уже начатая чужая работа.

Если working tree dirty, это не обязательно плохо. Но это должно быть осознанно.

Хороший стартовый отчет для агента:

Current branch: feature/password-reset
Working tree: clean
Task: AUTH-RESET-04 single-use token
Expected diff scope:
- reset token service
- password reset tests
Out of scope:
- UI redesign
- password policy
- email templates

Если working tree dirty:

Current branch: feature/auth
Working tree has existing changes:
- docs/auth.md
- tests/auth/test_login.py

Do not modify or revert these files unless required by the task.
Before editing, explain whether they affect the task.

Важный принцип:

Agent must not overwrite or revert user changes unless explicitly asked.

Branch как граница задачи

Branch помогает изолировать работу агента.

Пример:

git switch -c feature/auth-reset-token-single-use

Название branch должно помогать понять task:

Branch не обязан быть идеальным, но должен отвечать на вопрос:

Что здесь должно измениться?

Для AI-разработки branch особенно полезен, потому что:

• можно сравнить branch с base;
• можно открыть PR;
• можно удалить branch, если эксперимент неудачный;
• можно запустить другого агента в другой branch;
• можно держать main стабильным.

Commit как сохраненная точка смысла

Commit - это не просто snapshot файлов. Это утверждение:

Вот законченное изменение, которое имеет смысл review и rollback.

Хороший commit для agent task должен иметь:

• один смысл;
• понятную связь с task или requirement;
• tests или объяснение, почему tests не запускались;
• diff без unrelated changes;
• message, по которому понятно, что изменилось.

Пример:

fix(auth): reject reused reset tokens

или:

test(agent): enforce Plan Mode read-only behavior

Плохой commit:

updates

Еще хуже:

agent changes

Он не помогает reviewer и future rollback.

Diff как главный артефакт контроля

В AI Agent Development reviewer часто должен читать не весь проект, а diff.

Команды:

git diff
git diff --stat
git diff --name-only
git diff --staged
git diff --check

Что они дают:

Diff review отвечает на вопросы:

• изменения относятся к task?
• tests добавлены или обновлены?
• не ослаблены ли tests?
• нет ли случайного форматирования всего файла?
• нет ли secrets?
• не изменены ли generated files без причины?
• не изменены ли lockfiles без dependency change?
• не появился ли broad refactor?
• нет ли conflict markers?
• не удалены ли важные checks?

Related vs unrelated changes

Agent-generated diff нужно делить на related и unrelated.

Task:

Fix reused reset token bug.

Diff:

Unrelated change не всегда плохой. Но он должен быть объяснен и, часто, вынесен в отдельную task.

Правило:

If a file is hard to justify from the task, it should not be in the diff.

Как читать diff агента

Практический порядок:

1. git status --short
2. git diff --stat
3. git diff --name-only
4. Review tests first
5. Review production changes
6. Review config/lock/generated files
7. git diff --check
8. Run verification
9. Stage only related changes
10. Commit

Почему tests first? Потому что tests показывают, что агент считает контрактом.

Если test неверный, production code может быть аккуратным, но задача все равно решена неправильно.

Для bug fix из прошлого урока reviewer сначала смотрит:

Есть ли failing regression test, который соответствует bug report?

Для feature:

Есть ли test/eval, связанный с acceptance criterion?

Для docs:

Не потеряна ли структура, контекст и переход к соседнему уроку?

Staging как ручной фильтр

Index позволяет выбрать, какие изменения попадут в commit.

Простой вариант:

git add src/auth/resetTokenService.ts
git add tests/auth/resetToken.test.ts
git diff --staged
git commit -m "fix(auth): reject reused reset tokens"

Если в одном файле есть related и unrelated изменения, можно использовать patch staging:

git add -p

Но с agent-generated changes лучше не доводить до смешанного файла. Если агент изменил один файл сразу по нескольким темам, это сигнал, что task boundary была слишком широкой.

Опасный вариант:

git add .

Он допустим только когда вы уже проверили git status и git diff --stat, и действительно хотите включить все изменения.

Revert, reset, restore, stash

Эти команды часто путают. Для AI-разработки важно понимать разницу на уровне safety.

Для shared branches default:

Prefer revert over reset.

Для dirty working tree default:

Never discard changes unless you know whose changes they are and why they can be removed.

Для agents это должно быть жестким правилом:

Do not run destructive Git commands without explicit approval.

Revert как safety mechanism

revert полезен, когда изменение уже стало частью истории.

Scenario:

Agent fixed password reset.
PR merged.
Later CI or production reveals regression in login flow.

Без Git:

Нужно вручную вспоминать, что менялось.

С Git:

git revert <bad_commit_sha>

Revert создает новый commit, который отменяет старый. Это хорошо для shared history, потому что история остается линейно объяснимой:

Commit A: add reset token consumed check
Commit B: revert A because it broke legacy token import

Revert не всегда решает все автоматически. Могут быть conflicts. Но принцип важен:

Published change should be undone by an explicit undo change.

Reset как инструмент повышенного риска

reset полезен, но опасен.

Особенно опасен:

git reset --hard

Он может удалить незакоммиченные изменения из working tree. Если там была работа человека или другого агента, она может быть потеряна.

В agentic workflow reset --hard допустим только когда:

• вы точно знаете, что working tree не содержит нужных изменений;
• есть commit/checkpoint/backup;
• это local branch;
• пользователь явно согласен;
• command и цель понятны.

Более безопасные альтернативы:

В курсе reset нужно знать, но не романтизировать.

Stash как временная полка

stash полезен, когда нужно временно убрать незакоммиченные изменения.

Пример:

git stash push -m "wip before agent task"

Но stash не должен заменять commit.

Проблемы stash:

• легко забыть, что в нем лежит;
• можно применить не туда;
• untracked files не всегда включены без отдельного флага;
• stash плохо объясняет смысл изменения;
• stash не проходит review.

Agent-safe правило:

Do not stash user changes silently.

Если рабочее дерево dirty, лучше сначала понять изменения. Иногда правильнее сделать WIP commit на отдельной branch, иногда попросить человека завершить текущую работу, иногда создать worktree.

Merge и rebase в agentic workflow

Для курса достаточно базовой разницы.

Merge:

Объединяет histories и может создать merge commit.

Rebase:

Переносит commits текущей branch поверх другой base.

Для AI agent:

• merge/rebase не должны быть автоматической частью маленькой coding task без причины;
• conflicts нужно review вручную или отдельным agent step;
• после conflict resolution нужны tests;
• rebase shared branch требует особой осторожности.

В этом курсе важно не стать Git-экспертом, а не потерять контроль над agent-generated changes.

Pull Request как review gate

Pull Request - это не формальность. Это место, где change становится reviewable.

Хороший PR для agent task содержит:

• ссылку на task/spec/requirement;
• краткое описание behavior change;
• список changed areas;
• tests/evidence;
• screenshots, если UI;
• migration notes, если есть migration;
• risks и not-run checks;
• маленький diff.

PR помогает:

• отделить author context от reviewer context;
• запустить CI;
• увидеть conversation around diff;
• оставить audit trail;
• подключить reviewer agent или человека;
• откатить merge понятным способом.

В agentic development PR особенно полезен, потому что агент может звучать уверенно. PR заставляет смотреть на evidence.

Что агент должен писать в final answer перед commit или PR

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

Summary:
- what changed

Diff:
- files changed
- why each area belongs to task

Verification:
- commands run
- results
- commands not run and why

Risk:
- residual risks
- possible follow-up

Плохой final answer:

Готово, все работает.

Хороший final answer:

Implemented AUTH-RESET-04 single-use reset token.

Changed:
- resetTokenService: rejects consumed tokens
- passwordReset tests: adds regression for second use

Verification:
- pytest tests/auth/test_password_reset.py::test_reset_token_cannot_be_reused_after_successful_reset: passed
- pytest tests/auth/test_password_reset.py: passed

Not run:
- browser E2E reset flow

Residual risk:
- concurrent double-submit not covered in this task

Git делает этот answer проверяемым через diff.

Git и dirty worktree

Dirty worktree - это рабочая директория с незакоммиченными изменениями.

Команда:

git status --short

Пример:

 M src/auth/resetTokenService.ts
 M tests/auth/resetToken.test.ts
?? notes/debug-output.txt

Для агента dirty worktree означает:

There may be user work here.
Be careful.

Правильное поведение агента:

• прочитать status;
• понять, какие изменения уже были;
• не считать их своими;
• не откатывать их без явного запроса;
• не смешивать их с новой task;
• в final answer отделить собственные изменения от pre-existing changes, если это важно.

Если task невозможно выполнить без изменения already modified file, агент должен работать аккуратно:

File already has changes.
I will inspect current content and make a minimal compatible edit.
I will not revert existing edits.

Untracked и ignored files

Git защищает только то, что попало в history. Untracked files не сохранены в commit.

Команда:

git status --short

может показать:

?? scripts/debug-reset-token.sh
?? tmp-output.json

Untracked files бывают полезными:

• новый test;
• новый module;
• generated artifact;
• temporary debug script.

Но они часто случайные:

• local logs;
• screenshots;
• downloaded files;
• temporary output;
• .env copy;
• editor files.

Agent review должен спросить:

Should this untracked file be committed?

Если нет, его нужно оставить вне commit или удалить только с пониманием, что это безопасно.

Ignored files тоже важны. Они не видны в обычном git status, но могут влиять на build:

• .env;
• local database;
• cache;
• generated outputs;
• virtual environments.

Поэтому "Git чистый" не всегда означает "environment чистый".

Generated files и lockfiles

Agent-generated changes часто случайно затрагивают generated files.

Примеры:

• package-lock.json;
• pnpm-lock.yaml;
• yarn.lock;
• generated API clients;
• snapshots;
• compiled assets;
• schema files;
• docs build output.

Правило:

Generated or lockfile changes must have a reason.

Если dependency не менялась, но lockfile изменился, это suspicious.

Если snapshot изменился, нужно понять:

• user-visible UI действительно изменился?
• snapshot baseline устарел?
• agent случайно обновил snapshots, чтобы tests прошли?
• есть ли screenshot или visual evidence?

Generated changes не запрещены. Но они требуют отдельного review.

Secrets и конфиги

AI agent может случайно добавить sensitive data в diff:

• API keys;
• tokens;
• passwords;
• database URLs;
• .env;
• private endpoints;
• customer data;
• logs с персональными данными.

Перед commit нужно проверять:

git diff
git diff --staged

И держать простое правило:

Secrets must not enter Git history.

Если secret уже попал в commit, простого revert может быть недостаточно: secret мог остаться в history. Это отдельный security incident. В рамках этого урока достаточно запомнить: secrets нужно ловить до commit.

Git safety loop для одной Agent Task

Эта схема является базовой для следующих уроков модуля.

Команды, которые должен знать студент

Не нужно знать весь Git. Для курса нужен operational minimum.

Где я?

git status --short
git branch --show-current
git log --oneline -5

Что изменилось?

git diff
git diff --stat
git diff --name-only
git diff --staged

Как начать task?

git switch main
git pull
git switch -c feature/task-name

Важно: git pull на dirty worktree может привести к conflicts. Сначала проверяйте status.

Как сохранить selected changes?

git add path/to/file
git add -p
git diff --staged
git commit -m "fix(auth): reject reused reset tokens"

Как убрать из staging?

git restore --staged path/to/file

Как отменить опубликованный commit?

git revert <commit-sha>

Как посмотреть историю?

git log --oneline --decorate --graph -10

Как увидеть, что branch отличается от main?

git diff main...HEAD
git diff --stat main...HEAD

Эти команды дают достаточно контроля для большинства agent tasks.

Как давать Git-инструкции агенту

Agent prompt должен включать Git boundaries.

Пример:

Task:
Fix AUTH-RESET-04: used reset token can be reused.

Git rules:
- Inspect git status before edits.
- Do not modify unrelated files.
- Do not revert existing user changes.
- Keep diff scoped to reset token service and tests unless you explain why.
- After implementation, show git diff --stat and verification commands.
- Do not commit until asked.

Почему "do not commit until asked"? В некоторых workflows агент может делать commit сам. Но в курсе сначала важно научиться читать diff до commit. Позже можно автоматизировать commit step, если review discipline уже есть.

Для задач, где commit разрешен:

After tests pass and diff review is clean,
create one commit with message tied to task ID.

Пример 1. Branch для Password Reset bug fix

Task:

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

Safe start:

git status --short
git branch --show-current
git switch -c fix/auth-reset-token-reuse

Prompt агенту:

Fix BUG-AUTH-12 via Bug Fix Flow.

Expected diff:
- password reset regression test
- reset token service/repository logic

Out of scope:
- password policy
- email template
- login UI
- dependency changes

Do not commit.
Show diff summary and verification evidence.

После работы агента:

git diff --stat
git diff --name-only
git diff

Expected diff:

src/auth/resetTokenService.ts
tests/auth/resetToken.test.ts

Suspicious diff:

src/auth/resetTokenService.ts
tests/auth/resetToken.test.ts
src/auth/passwordPolicy.ts
web/styles/theme.css
package-lock.json

Reviewer action:

Ask why passwordPolicy, theme.css and package-lock changed.
If unrelated, split or remove them before commit.

Пример 2. Найти unrelated changes в diff

Представим diff summary:

 src/auth/resetTokenService.ts       | 18 +++++++---
 tests/auth/resetToken.test.ts       | 42 +++++++++++++++++++++
 src/auth/passwordPolicy.ts          |  6 ++--
 web/components/Button.tsx           | 90 +++++++++++++++++++++----------------
 package-lock.json                   | 200 +++++++++++++++++++++++++++++++-----

Task:

Reject reused reset token.

Классификация:

Возможный prompt агенту:

Diff contains unrelated files:
- src/auth/passwordPolicy.ts
- web/components/Button.tsx
- package-lock.json

Explain why each is necessary for BUG-AUTH-12.
If not necessary, remove those changes without touching the related fix.
Do not weaken tests.

Важно: если эти unrelated changes сделаны пользователем до агента, агент не должен их удалять. Сначала нужно понять ownership изменения.

Пример 3. Commit после verification

После review diff:

git add src/auth/resetTokenService.ts
git add tests/auth/resetToken.test.ts
git diff --staged
git commit -m "fix(auth): reject reused reset tokens"

Commit message должен быть связан с behavior:

Если есть task ID:

fix(auth): reject reused reset tokens

Covers BUG-AUTH-12 / AUTH-RESET-04.

Команда commit может быть разной в проекте. Смысл один: commit должен объяснять, что было сделано и почему.

Пример 4. Rollback после плохой agent правки

Scenario:

Agent changed 15 files while fixing one API bug.
Tests now fail.
No commit has been made.

Первое действие:

git status --short
git diff --stat

Дальше варианты.

Если все изменения точно принадлежат агенту и не нужны:

Discard agent changes after explicit confirmation.

Команда может быть:

git restore path/to/file

или для нескольких файлов:

git restore src/unrelated.ts web/unrelated.tsx

Но это удаляет local edits. Поэтому сначала нужно убедиться, что это не работа пользователя.

Если часть изменений полезна:

Stage only useful files or hunks.
Move unrelated work to separate task or discard with approval.

Если плохая правка уже committed locally:

Use revert or reset depending on whether commit was shared and whether you need to preserve changes.

Если commit уже pushed или merged:

Prefer git revert.

Rollback thinking важнее конкретной команды:

Before undoing, know what state you are returning to.

Git и tests

Git сам не проверяет behavior. Он хранит changes. Поэтому Git должен работать вместе с tests.

Minimum loop:

diff -> tests -> staged diff -> commit

Не:

diff -> commit -> maybe tests later

Перед commit:

• targeted tests для task;
• nearby tests для затронутого module;
• lint/typecheck, если есть;
• broader regression, если change risky;
• manual check, если automation невозможна;
• список not-run checks.

Для bug fix:

before fix: regression test fails
after fix: same test passes

Для feature:

acceptance criterion has test/eval evidence

Для docs:

Markdown structure and links checked when tooling exists

Git commit без verification - это сохраненная неопределенность.

Git и specification

Git diff должен быть связан со specification.

Пример:

Так появляется traceability:

Spec -> Task -> Diff -> Tests -> Commit -> PR

Если diff нельзя связать со spec, это warning.

Git и agent permissions

Не каждый агент должен иметь право делать все Git operations.

Пример policy:

На раннем этапе курса полезно держать агента в режиме:

Agent edits and verifies.
Human reviews diff and decides commit.

Позже можно расширять permissions, если process стабилен.

Git для нескольких агентов

Этот урок только вводит тему, но важно увидеть связь.

Если два агента работают в одной working tree, они могут:

• перезаписать изменения друг друга;
• смешать diffs;
• запустить tests на промежуточном состоянии;
• создать conflicts без понятной ownership;
• удалить чужие temporary files.

Для параллельной работы нужны:

• отдельные branches;
• отдельные worktrees;
• clear task boundaries;
• independent commits;
• merge/review protocol.

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

One working directory is a shared physical space.
Do not let parallel agents write into it blindly.

Чек-лист перед запуском агента

[ ] Я знаю текущую branch
[ ] Я проверил git status
[ ] Working tree clean или dirty state понятен
[ ] Если есть user changes, агенту запрещено их трогать без причины
[ ] Создана или выбрана task branch
[ ] Task scope сформулирован
[ ] Expected files/areas названы
[ ] Out-of-scope areas названы
[ ] Verification expectation названа
[ ] Агенту запрещены destructive Git commands без approval

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

[ ] git status просмотрен
[ ] git diff --stat просмотрен
[ ] git diff просмотрен
[ ] Unrelated changes removed or split
[ ] Tests/evals добавлены или причина отсутствия указана
[ ] Verification commands run
[ ] Not-run checks documented
[ ] Secrets не попали в diff
[ ] Generated/lockfile changes justified
[ ] git diff --check clean
[ ] Staged diff reviewed
[ ] Commit message связан с task/behavior

Чек-лист rollback thinking

Перед merge или risky change спросите:

[ ] Какой commit нужно revert, если change сломает production?
[ ] Один ли смысл у commit?
[ ] Можно ли revert без отката unrelated changes?
[ ] Есть ли migration или data change?
[ ] Есть ли feature flag?
[ ] Есть ли tests, которые доказывают bug/feature behavior?
[ ] Есть ли known residual risk?

Rollback difficult, если commit содержит:

• несколько unrelated tasks;
• schema migration и UI refactor вместе;
• dependency upgrades вместе с bug fix;
• regenerated snapshots без explanation;
• formatting всей codebase;
• hidden config changes.

Поэтому Git safety начинается не в момент rollback. Она начинается с маленького diff.

Практика 1. Прочитать diff агента

Task:

AUTH-RESET-04:
Used reset token cannot be reused.

Diff summary:

 src/auth/resetTokenService.ts          | 24 ++++++---
 tests/auth/resetToken.test.ts          | 58 +++++++++++++++++++++
 src/auth/passwordPolicy.ts             | 12 ++---
 web/components/ResetPasswordForm.tsx   | 80 ++++++++++++++++--------------
 package-lock.json                      | 310 +++++++++++++++++++++++++++++++--
 docs/auth.md                           | 10 ++++

Разделите:

Возможный вывод:

Related:
- resetTokenService
- resetToken test

Maybe related:
- docs/auth.md, if behavior contract was documented

Suspicious:
- ResetPasswordForm, unless UI error handling changed by requirement
- package-lock, unless dependency changed

Unrelated:
- passwordPolicy

Практика 2. Подготовить branch для Agent Task

Task:

AGENT-WF-01:
Plan Mode must not edit files.

Подготовьте:

Пример:

Практика 3. Написать Git правила для агента

Составьте prompt block:

Git rules for this task:
- ...

Минимальный хороший вариант:

Git rules for this task:
- Inspect git status before edits.
- Treat existing changes as user work.
- Do not revert or overwrite user changes.
- Keep diff scoped to the task.
- Do not run destructive Git commands.
- Show git diff --stat before final answer.
- Do not commit until explicitly asked.

Для более автономного агента можно добавить:

- After verification passes, stage only related files.
- Show staged diff.
- Create one commit with a task-linked message.

Но это нужно включать только там, где команда доверяет агенту commit step.

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

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

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

• объяснить Git как safety mechanism для AI-generated changes;
• проверить стартовое состояние repository;
• создать task branch;
• прочитать git diff, git diff --stat, git diff --name-only;
• отделить related changes от unrelated changes;
• понять разницу между working tree, index и commit;
• аккуратно stage selected changes;
• объяснить разницу между revert, reset, restore и stash;
• выбрать безопасный rollback approach;
• описать PR как review gate;
• сформулировать Git rules для агента.

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

Git делает agentic development управляемым.

Главная цепочка:

Task branch
-> Agent edits
-> Diff review
-> Verification
-> Staged diff
-> Commit
-> PR review

git status отвечает, где мы находимся.

git diff показывает, что изменилось.

commit сохраняет осмысленную точку.

revert помогает безопасно отменить опубликованное изменение.

reset, restore и stash полезны, но требуют осторожности, потому что могут скрыть или удалить local work.

Для AI-разработки Git особенно важен потому, что агент может создавать большой diff быстро. Safety возникает не от самого Git, а от привычки читать diff, держать task boundary и сохранять изменения маленькими reviewable commits.

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

1. Почему git status нужно смотреть до запуска агента?
2. Чем working tree отличается от index?
3. Почему git add . опасен после работы агента?
4. Когда лучше использовать git revert, а не git reset?
5. Какие признаки говорят, что agent diff содержит unrelated changes?

Что дальше

В следующем уроке мы сформулируем главное правило модуля: one task - one change. Git дает механизм контроля, но сам по себе не гарантирует маленький diff. Для этого нужно правильно нарезать задачи, держать границы и завершать каждую agent task отдельным проверенным изменением.