Урок 8.2. Plan Mode и Act Mode

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

В уроке 8.1 мы собрали controlled development loop:

read spec -> inspect code -> plan -> test -> implement -> verify -> review diff -> check AC

Теперь нужно добавить важную границу: агент не должен всегда иметь одинаковые права на всех этапах.

Когда агент проектирует решение, ему часто достаточно:

• читать spec;
• читать код;
• искать patterns;
• анализировать risks;
• составлять plan;
• задавать уточняющие вопросы.

Для этого не нужно право изменять production code, запускать destructive commands, деплоить или писать во внешние системы.

Когда plan согласован, агент переходит к execution:

• редактирует ограниченный набор файлов;
• запускает targeted tests;
• применяет skill;
• вызывает tools;
• возвращает evidence.

Разделение Plan Mode и Act Mode делает работу агента более управляемой. Это не просто удобный UX-паттерн. Это permission boundary.

Главная цель урока - научиться разделять проектирование и исполнение, вводить approval gate между ними и ограничивать права агента по режимам.

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

Plan Mode - режим анализа и проектирования без изменения системы.

Act Mode - режим исполнения согласованного плана в ограниченном scope.

Короткая формула:

Plan first.
Approve scope.
Act with limits.
Verify with evidence.

Самое важное:

Агент, который проектирует архитектуру,
не обязан иметь permission редактировать production code.

Это особенно важно для сложных задач, где сначала нужно подумать:

• как разбить work;
• какие файлы трогать;
• какие tests нужны;
• какие risks есть;
• нужны ли approvals;
• где остановиться.

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

Почему нельзя смешивать planning и edits

Если агент одновременно думает и редактирует, он часто начинает менять код слишком рано.

Плохой workflow:

User: "Как лучше реализовать team invitations?"
Agent:
1. Начал рассуждать.
2. Увидел похожий файл.
3. Сразу переписал часть auth.
4. Создал migration.
5. Потом понял, что spec не уточняет expiration.

Проблемы:

• edits сделаны до согласования architecture;
• scope расползся;
• непонятно, какие assumptions приняты;
• часть изменений может быть лишней;
• rollback сложнее;
• пользователь теряет контроль.

Хороший workflow:

Plan Mode:
- прочитать spec;
- найти patterns;
- предложить 3-step plan;
- назвать open questions;
- запросить approval.

Act Mode:
- выполнить только approved task;
- не выходить за scope;
- вернуть evidence.

Схема режимов

Переход из Plan Mode в Act Mode должен быть явным. Это может быть человеческое approval, task assignment, change request, ticket status или другой gate.

Plan Mode

Plan Mode отвечает на вопрос:

Что мы собираемся делать и почему?

В Plan Mode агент может:

• читать specification;
• читать relevant code;
• искать existing patterns;
• читать ADR;
• выбирать skills;
• предлагать task breakdown;
• оценивать risk;
• предлагать tests;
• задавать вопросы;
• формировать scope.

В Plan Mode агент не должен:

• редактировать production code;
• создавать migration;
• запускать destructive commands;
• делать external writes;
• коммитить;
• деплоить;
• менять tickets без явного разрешения;
• "заодно" исправлять найденные проблемы.

Plan Mode - это thinking with evidence, но без side effects.

Act Mode

Act Mode отвечает на вопрос:

Как выполнить согласованный plan и доказать результат?

В Act Mode агент может:

• редактировать approved files;
• создавать tests;
• запускать approved commands;
• применять approved skills;
• вызывать allowed tools;
• делать diff review;
• проверять acceptance criteria;
• готовить commit-ready output.

В Act Mode агент все равно не должен:

• выходить за scope без escalation;
• скрывать failed tests;
• делать production deploy без approval;
• удалять unrelated files;
• менять architecture direction без возврата в Plan Mode;
• принимать product/security decisions вместо пользователя.

Act Mode не означает "делай что хочешь". Это controlled execution.

Permission matrix

Эта таблица не universal law. В каждом project можно настроить иначе. Но baseline полезен: planning должен быть read-heavy, execution - write-limited.

Approval gate

Approval gate - момент, когда человек решает:

Да, этот plan и scope можно выполнять.

Хороший approval payload содержит:

• краткое понимание задачи;
• acceptance criteria;
• proposed files/layers;
• in scope;
• out of scope;
• test plan;
• risky actions;
• required tools/commands;
• open questions;
• stop conditions.

Плохой approval payload:

Можно начинать?

Пользователь не понимает, что именно разрешает.

Хороший:

Plan:
1. Add API test for POST /api/projects.
2. Reuse existing teams endpoint pattern.
3. Add route/controller and validation schema.
4. Run targeted API test and typecheck.

In scope:
- backend route
- validation
- service method
- API tests

Out of scope:
- frontend form
- billing
- auth middleware

Risk:
- authorization behavior uses existing authenticated route pattern.

Approval needed:
- edit backend files and tests;
- run targeted tests.

Plan Mode не заменяет SDD

Plan Mode часто путают со Specification-Driven Development, потому что оба начинаются до кода. Но это разные уровни.

Plan Mode полезен даже без полного SDD:

прочитать код -> предложить scope -> получить approval -> выполнить

Но если task меняет product behavior, API contract, security rule или architecture boundary, одного plan в chat недостаточно. Нужен durable spec:

spec.md -> plan.md -> tasks.md -> implementation -> evidence

Практическое правило:

Именно поэтому в controlled workflow Plan Mode обычно стоит после чтения spec, а не вместо spec.

Plan output contract

Plan Mode должен возвращать не размышления потоком, а structured plan.

Шаблон:

Understanding:
- ...

Acceptance criteria:
- ...

Relevant context inspected:
- ...

Proposed plan:
1. ...
2. ...
3. ...

In scope:
- ...

Out of scope:
- ...

Test/verification plan:
- ...

Risks:
- ...

Open questions:
- ...

Approval request:
- Allow edits to ...
- Allow commands ...

Это делает approval meaningful.

Act output contract

Act Mode должен завершаться evidence.

Шаблон:

Summary:
- ...

Changed files:
- ...

Verification:
- `<command>`: passed/failed/not run, exit code ...

Acceptance criteria:
- AC1: satisfied/not satisfied
- AC2: satisfied/not satisfied

Diff review:
- focused/unrelated changes/notes

Risks and follow-ups:
- ...

Act Mode без evidence превращается в "я сделал". В controlled development этого недостаточно.

Когда Plan Mode обязателен

Plan Mode особенно нужен, если:

• задача больше одного файла;
• затрагиваются architecture boundaries;
• есть database migration;
• меняется public API;
• есть security/auth behavior;
• нужны external tools;
• есть production risk;
• задача плохо специфицирована;
• есть несколько возможных решений;
• пользователь просит "спланируй";
• work может быть разбит на несколько tasks.

Для совсем маленьких задач Plan Mode может быть коротким:

Понял: исправить typo в README. Scope: один файл. Verification: diff review.

Но для software changes с behavior Plan Mode лучше не пропускать.

Когда можно сразу Act

Не каждая мелочь требует длинного plan.

Можно сразу действовать, если:

• user явно просит small edit;
• файл и изменение очевидны;
• нет production/security risk;
• нет ambiguity;
• нет external writes;
• scope один файл;
• verification простая.

Пример:

Исправь опечатку в заголовке README.

Но даже здесь агент должен:

• не трогать unrelated files;
• проверить diff;
• сказать, что изменено.

Важно: "сразу Act" не означает "без контроля". Это просто короткий loop.

Escalation

Escalation нужен, когда в Act Mode агент обнаружил, что задача требует больше прав или другой scope.

Примеры:

Plan approved:
- change API validation only.

During Act:
- existing service lacks required persistence support.

Escalation:
- need permission to modify service layer and add tests.

Или:

Plan approved:
- add endpoint.

During Act:
- requires database migration.

Escalation:
- stop and request approval for migration task.

Escalation output:

I hit a scope boundary.

Approved scope:
- validation and controller.

New required change:
- database migration for `projects.slug`.

Why:
- service cannot satisfy AC2 without persisted slug.

Options:
1. Approve migration as separate task.
2. Change AC to not require slug persistence.
3. Stop here.

Агент не должен молча расширять scope.

Plan Mode prompt

Пример prompt:

Work in Plan Mode only.

Task:
<task>

Rules:
- Do not edit files.
- Do not run write or destructive commands.
- Read the spec and relevant code.
- Identify local patterns.
- Return a concise implementation plan.
- Include in scope, out of scope, test plan, risks, open questions, and approval request.

Output format:
Understanding:
Acceptance criteria:
Relevant context inspected:
Plan:
In scope:
Out of scope:
Verification plan:
Risks:
Open questions:
Approval request:

Этот prompt полезен, когда задача еще не ясна или может быть большой.

Act Mode prompt

После approval:

Proceed in Act Mode.

Approved plan:
<approved plan>

Approved scope:
- <files/layers>

Allowed commands:
- <test commands>

Constraints:
- Do not edit files outside approved scope without asking.
- Do not add dependencies.
- Do not change public API beyond the spec.
- Report failed checks honestly.

Expected final output:
- summary;
- changed files;
- verification commands and results;
- acceptance criteria status;
- diff review notes;
- residual risks.

Act Mode prompt должен быть конкретным. Чем опаснее task, тем точнее scope и approvals.

Two-turn workflow

Хорошая практика для сложной задачи:

Turn 1: Plan

User:
Составь plan для добавления team invitations.
Работай read-only, без edits.

Agent:

Understanding:
...

Plan:
1. Migration for invitations table.
2. Backend endpoint.
3. Email integration.
4. Frontend form.

Recommended first task:
Migration only.

Approval request:
Allow edit of migration files and model tests.

Turn 2: Act

User:
Одобряю только Task 1: migration.
Не трогай backend endpoint и frontend.

Agent:

Act Mode:
- edits migration files only;
- adds migration test;
- runs targeted verification;
- reports evidence.

Такой workflow не мешает скорости. Он делает скорость безопаснее.

Mode transitions

Ключевые transitions:

• Plan -> WaitingApproval: агент завершил analysis.
• WaitingApproval -> Act: человек согласовал scope.
• Act -> WaitingApproval: обнаружен scope boundary.
• Verifying -> Done: есть evidence.

Как это связано с permissions

Mode без permissions - просто договоренность в prompt. Это полезно, но не достаточно для high-risk systems.

Лучше, когда режимы поддержаны runtime:

Если runtime не умеет enforce permissions, prompt discipline все равно помогает. Но для production-risk actions нужны technical controls.

Read-only planning

Read-only не значит "ничего полезного не делать". В Plan Mode агент может выполнить большую часть интеллектуальной работы:

• понять domain;
• найти relevant files;
• выявить hidden dependencies;
• обнаружить missing spec;
• предложить task split;
• выбрать skill;
• составить test plan;
• заметить risks;
• сформулировать questions.

Для сложной задачи это часто экономит время. Дешевле изменить plan, чем откатывать большой diff.

Scope-limited execution

Act Mode должен иметь конкретные границы:

Allowed files:
- src/api/projects.ts
- src/services/projects.ts
- tests/api/projects.test.ts

Allowed commands:
- npm test -- tests/api/projects.test.ts
- npm run typecheck

Not allowed:
- auth middleware edits
- database migrations
- frontend files
- deployment

Если agent должен выйти за scope, он спрашивает.

Scope-limited execution особенно важен в dirty worktree, где могут быть чужие изменения. Агент не должен "навести порядок" в unrelated files.

Approval granularity

Approval может быть разного уровня:

Не смешивайте:

"План выглядит хорошо"

с:

"Можно деплоить production"

Это разные approvals.

Risk-based mode policy

Чем выше риск, тем более явным должен быть gate.

Example: API endpoint

Task:

Добавить POST /api/projects.

Plan Mode output

Understanding:
- Need endpoint for authenticated project creation.

Acceptance criteria:
- Valid name creates project.
- Empty name returns validation error.
- Owner is current user.
- Response returns 201 and id.

Relevant context inspected:
- Existing POST /api/teams endpoint.
- Existing API tests for teams.
- Validation schema pattern.

Plan:
1. Add tests for success and invalid name.
2. Add project validation schema.
3. Add route/controller using teams pattern.
4. Add service create method if missing.
5. Run targeted API test and typecheck.

In scope:
- backend route/controller
- validation
- service method
- API tests

Out of scope:
- frontend form
- billing
- auth middleware

Approval request:
- edit backend API/service/test files;
- run targeted tests.

Act Mode final output

Summary:
- Added POST /api/projects endpoint with validation and service integration.

Changed files:
- src/api/projects.ts
- src/services/projects.ts
- tests/api/projects.test.ts

Verification:
- npm test -- tests/api/projects.test.ts: passed, exit code 0
- npm run typecheck: passed, exit code 0

Acceptance criteria:
- Valid name creates project: satisfied.
- Empty name rejected: satisfied.
- Owner is current user: satisfied.
- 201 with id: satisfied.

Diff review:
- focused on approved backend scope;
- no auth middleware changes;
- no new dependencies.

Example: scope escalation

Task approved:

Add endpoint only. No database changes.

Agent discovers:

There is no projects table.

Wrong behavior:

Агент сам добавляет migration.

Correct behavior:

Scope escalation:
- Approved scope excluded database changes.
- Endpoint cannot satisfy persistence AC without schema support.
- Need approval to create migration as separate task.

Options:
1. Approve migration task now.
2. Change endpoint to call existing storage if available.
3. Stop after test skeleton and plan migration.

Это и есть управляемость.

Example: security-sensitive task

Task:

Добавь admin endpoint для блокировки пользователя.

Plan Mode должен выявить:

• auth requirement;
• role model;
• audit requirement;
• affected user state;
• tests for unauthorized access;
• possible abuse path.

Plan Mode output:

Open questions:
- Which roles can block users?
- Should blocked users receive notification?
- Is audit log required?
- Is unblock in scope?

Stop condition:
- Do not implement admin endpoint until authorization policy is explicit.

Здесь Act Mode без уточнения опасен. Planning сохраняет безопасность.

Relation to skills

Skill может задавать special loop для конкретного workflow.

Пример:

Plan Mode:
- выбрать skill `create-api-endpoint`;
- прочитать `SKILL.md`;
- на основе skill составить task-specific plan.

Act Mode:
- выполнять procedure из skill в approved scope;
- запускать verification из skill;
- вернуть output contract.

Skill не отменяет approval. Он помогает сделать plan и act качественнее.

Relation to tools and MCP

Plan Mode обычно использует read capabilities:

read_file
search_repository
read_docs_resource
get_pr_diff
get_schema

Act Mode может использовать write capabilities:

apply_patch
run_tests
comment_on_pr
create_issue
rerun_ci

High-risk tools все равно требуют отдельного approval:

deploy_production
delete_resource
write_database
charge_customer

Mode не заменяет tool security policy. Mode помогает решать, какие tools вообще показывать или разрешать на этапе.

Relation to testing

Plan Mode должен предложить verification strategy.

Act Mode должен выполнить verification или честно объяснить, почему не смог.

Переход к модулю 9:

Plan says what should be tested.
Act produces test evidence.
Testing discipline determines whether we trust the result.

Если plan не содержит test strategy, Act Mode часто заканчивается "готово" без доказательств.

Anti-pattern: endless planning

Plan Mode может стать ловушкой.

Плохо:

Агент бесконечно уточняет, классифицирует, рисует варианты,
но не предлагает executable next step.

Хороший Plan Mode заканчивается:

• recommended next task;
• concrete steps;
• approval request;
• open questions only where they matter;
• stop conditions.

Plan Mode не должен быть способом избегать работы. Он должен делать Act Mode безопаснее и точнее.

Anti-pattern: silent act

Другой перекос:

Пользователь просит plan.
Агент молча редактирует код.

Это нарушение режима.

Если пользователь просит plan, brainstorming или analysis, агент должен оставаться read-only, пока не получит разрешение на execution.

Anti-pattern: approval laundering

Approval laundering - когда агент получает общее "ок" и трактует его как разрешение на все.

Пример:

User: "План норм."
Agent: deploys production.

Это неправильно.

Approval должен соответствовать действию:

• approve plan;
• approve file edits;
• approve command;
• approve external write;
• approve deploy.

Чем выше риск, тем точнее approval.

Anti-pattern: broad Act Mode

Плохо:

Act Mode:
Можешь менять что угодно, чтобы заработало.

Для агента это invitation to scope creep.

Лучше:

Approved scope:
- only backend endpoint files and tests;
- no auth middleware changes;
- no migrations;
- ask before adding dependencies.

Scope должен быть достаточно узким, чтобы diff можно было review.

Mode checklist

Перед Plan Mode:

[ ] Есть task/spec или понятный вопрос
[ ] Режим read-only
[ ] Агент знает, что edits запрещены
[ ] Нужно вернуть plan, risks, questions, approval request

Перед Act Mode:

[ ] Plan approved
[ ] Scope approved
[ ] Allowed files/layers названы
[ ] Allowed commands названы
[ ] Risky tools имеют approval policy
[ ] Stop conditions названы
[ ] Expected final output задан

После Act Mode:

[ ] Changed files reported
[ ] Verification commands/results reported
[ ] Diff reviewed
[ ] Acceptance criteria checked
[ ] Risks/follow-ups named

Практика: сначала plan, потом act

Задача:

Добавить reset password flow.

Шаг 1. Plan Mode

Напишите prompt:

Work in Plan Mode only.

Task:
Add reset password flow.

Do not edit files.
Read the relevant specs and code.
Return:
- understanding;
- acceptance criteria;
- existing patterns;
- task breakdown;
- recommended first task;
- in scope/out of scope;
- test plan;
- risks;
- open questions;
- approval request.

Ожидаемый plan:

Task breakdown:
1. Request reset endpoint.
2. Token generation/storage.
3. Reset endpoint.
4. Email integration.
5. Frontend form.

Recommended first task:
Token model and backend request endpoint.

Risks:
- token reuse;
- token expiration;
- no user enumeration;
- email delivery side effects.

Open questions:
- token TTL?
- email provider in scope?

Шаг 2. Approval

Пользователь разрешает только часть:

Approve first backend task only.
Do not implement email sending.
Do not modify frontend.
Allowed files:
- backend auth module
- tests for auth reset request
Allowed commands:
- targeted auth tests

Шаг 3. Act Mode

Агент выполняет только approved scope и возвращает:

Summary:
Changed files:
Verification:
Acceptance criteria:
Diff review:
Risks:

Цель практики - почувствовать, как approval уменьшает ambiguity.

Практика: матрица прав

Заполните таблицу для своего проекта:

Возможный baseline:

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

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

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

• объяснить разницу между Plan Mode и Act Mode;
• назвать риски смешивания planning и execution;
• составить approval gate;
• задать permissions by mode;
• написать prompt для read-only Plan Mode;
• написать prompt для scoped Act Mode;
• распознать scope escalation;
• ограничить Act Mode approved files и commands;
• связать plan с test strategy;
• завершить Act Mode evidence-based output.

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

Plan Mode и Act Mode разделяют две разные работы:

Plan Mode:
понять, спроектировать, ограничить scope, запросить approval.

Act Mode:
выполнить approved scope, проверить, показать evidence.

Это разделение превращает агента из "автоматического редактора" в управляемого участника engineering process. Самое важное не название режима, а permission boundary:

Planning should be read-heavy.
Execution should be scope-limited.
Risky actions need explicit approval.

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

1. Почему архитектурное планирование не должно автоматически давать агенту право редактировать код?
2. Что должно входить в approval payload между Plan Mode и Act Mode?
3. Когда Act Mode должен остановиться и запросить escalation?
4. Чем approval plan отличается от approval production deploy?
5. Какие permissions вы бы дали агенту в Plan Mode для своего проекта?

Что дальше

Модуль 8 завершает single-agent execution discipline. Дальше курс переходит к testing для agentic development: чем быстрее агент генерирует изменения, тем сильнее должна быть verification. Plan Mode помогает выбрать, что проверять. Act Mode должен принести evidence, что проверка действительно выполнена.