Планирование с файлами — Файловое планирование в стиле Manus

Работайте как Manus (ИИ-агент за $2 млрд, приобретённый Meta): Используйте постоянные markdown-файлы как «рабочую память на диске».

Основной принцип

Контекстное окно = ОЗУ (летучее, ограниченное)
Файловая система = Диск (постоянное, неограниченное)

→ Всё важное записывается на диск.

Паттерн из 3 файлов

Для каждой сложной задачи создайте ТРИ файла в директории проекта:

task_plan.md      → Отслеживание фаз и прогресса
findings.md       → Хранение исследований и находок
progress.md       → Журнал сессии и результаты тестов

Шаблоны доступны по адресу: assistant/planning-with-files/templates/

Когда использовать этот паттерн

Используйте для:

Многошаговых задач (3+ шагов)
Исследовательских задач
Проектов создания/построения
Задач, требующих множества вызовов инструментов
Всего, что требует организации

Пропустите для:

Простых вопросов
Редактирования одного файла
Быстрых поисков

Критические правила времени

Эти правила имитируют хуки для обеспечения правильного рабочего процесса:

📌 В начале задачи (SessionStart)

ОБЯЗАТЕЛЬНО создайте все три файла ПЕРВЫМИ перед любой другой работой:

Создать task_plan.md по шаблону
Создать findings.md по шаблону
Создать progress.md по шаблону
Заполнить раздел Goal в task_plan.md

Зачем: Без файлов планирования вы забудете цели после 50+ вызовов инструментов.

📌 Перед важными решениями (PreToolUse)

ОБЯЗАТЕЛЬНО перечитайте task_plan.md перед:

Записью или редактированием файлов
Выполнением команд
Принятием архитектурных решений
Реализацией функций

Как: Используйте инструмент Read для обновления плана в контексте.

Зачем: Это сохраняет цели свежими в вашем окне внимания («манипуляция вниманием» Manus).

📌 После операций с файлами (PostToolUse)

ОБЯЗАТЕЛЬНО обновите статус немедленно после:

Записи файлов
Редактирования файлов
Завершения фазы задачи

Как: Отредактируйте task_plan.md для обновления статуса фазы:

markdown

- **Status:** pending → in_progress → complete

Зачем: Отслеживает прогресс и предотвращает потерю информации о том, что сделано.

📌 Перед завершением задачи (Stop)

ОБЯЗАТЕЛЬНО проверьте завершение:

Убедитесь, что все фазы отмечены как complete
Просмотрите раздел deliverables
Убедитесь, что не осталось неразрешённых ошибок

Зачем: Предотвращает преждевременное завершение с недостающей работой.

6 критических правил

1. Сначала создайте план

Никогда не начинайте сложную задачу без task_plan.md. Без исключений.

markdown

## Goal

[Одно предложение, описывающее конечное состояние]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints
- **Status:** in_progress

2. Правило 2 действий

«После каждых 2 операций просмотра/браузера/поиска НЕМЕДЛЕННО сохраняйте ключевые находки в findings.md.»

Это предотвращает потерю визуальной/мультимодальной информации.

markdown

## Visual/Browser Findings

- Screenshot shows login form with email and password fields
- API documentation indicates JSON response format

3. Читайте перед решением

Перед важными решениями прочитайте файл плана. Это сохраняет цели в вашем окне внимания.

bash

# Перед реализацией функции:
Read tool → task_plan.md
# Теперь приступайте к реализации

4. Обновляйте после действия

После завершения любой фазы:

Отметьте статус фазы: pending → in_progress → complete
Запишите все встреченные ошибки
Отметьте созданные/изменённые файлы

markdown

## Errors Encountered

| Error             | Attempt | Resolution             |
| ----------------- | ------- | ---------------------- |
| FileNotFoundError | 1       | Created default config |

5. Записывайте ВСЕ ошибки

Каждая ошибка заносится в файл плана. Это создаёт знания и предотвращает повторения.

6. Никогда не повторяйте неудачи

if action_failed:
    next_action != same_action

Отслеживайте, что вы пробовали. Изменяйте подход.

Протокол ошибок «3 удара»

ПОПЫТКА 1: Диагностика и исправление
  → Внимательно прочитайте ошибку
  → Определите первопричину
  → Примените целенаправленное исправление

ПОПЫТКА 2: Альтернативный подход
  → Та же ошибка? Попробуйте другой метод
  → Другой инструмент? Другая библиотека?
  → НИКОГДА не повторяйте точно то же неудачное действие

ПОПЫТКА 3: Более широкое переосмысление
  → Поставьте под сомнение предположения
  → Ищите решения
  → Рассмотрите обновление плана

ПОСЛЕ 3 НЕУДАЧ: Эскалация к пользователю
  → Объясните, что вы пробовали
  → Покажите конкретную ошибку
  → Попросите руководства

Назначение файлов

Файл	Назначение	Когда обновлять
`task_plan.md`	Фазы, прогресс, решения	После каждой фазы
`findings.md`	Исследования, открытия	После ЛЮБОГО открытия
`progress.md`	Журнал сессии, результаты тестов	На протяжении сессии

Матрица решений Read vs Write

Ситуация	Действие	Причина
Только что записали файл	НЕ читайте	Содержимое ещё в контексте
Просмотрели изображение/PDF	Запишите находки СЕЙЧАС	Мультимодальное → текст до потери
Браузер вернул данные	Записать в файл	Скриншоты не сохраняются
Начало новой фазы	Прочитать план/находки	Переориентация при устаревании контекста
Произошла ошибка	Прочитать релевантный файл	Нужно текущее состояние для исправления
Возобновление после перерыва	Прочитать все файлы планирования	Восстановление состояния

Тест перезагрузки из 5 вопросов

Если вы можете ответить на них, ваше управление контекстом в порядке:

Вопрос	Источник ответа
Где я?	Текущая фаза в task_plan.md
Куда я иду?	Оставшиеся фазы
Какова цель?	Утверждение цели в плане
Что я узнал?	findings.md
Что я сделал?	progress.md

Структура шаблонов

Шаблон task_plan.md

markdown

# Task Plan: [Brief Description]

## Goal

[One sentence describing the end state]

## Current Phase

Phase 1

## Phases

### Phase 1: Requirements & Discovery

- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress

### Phase 2: Planning & Structure

- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending

### Phase 3: Implementation

- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending

### Phase 4: Testing & Verification

- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending

### Phase 5: Delivery

- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending

## Key Questions

1. [Question to answer]
2. [Question to answer]

## Decisions Made

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Errors Encountered

| Error | Attempt | Resolution |
| ----- | ------- | ---------- |
|       | 1       |            |

Шаблон findings.md

markdown

# Findings & Decisions

## Requirements

## <!-- Captured from user request -->

## Research Findings

## <!-- Key discoveries during exploration -->

## Technical Decisions

<!-- Decisions made with rationale -->

| Decision | Rationale |
| -------- | --------- |
|          |           |

## Issues Encountered

<!-- Errors and how they were resolved -->

| Issue | Resolution |
| ----- | ---------- |
|       |            |

## Resources

## <!-- URLs, file paths, API references -->

## Visual/Browser Findings

## <!-- CRITICAL: Update after every 2 view/browser operations -->

Шаблон progress.md

markdown

# Progress Log

## Session: [DATE]

### Phase 1: [Title]

- **Status:** in_progress
- **Started:** [timestamp]
- ## Actions taken:
- ## Files created/modified:

## Test Results

| Test | Input | Expected | Actual | Status |
| ---- | ----- | -------- | ------ | ------ |
|      |       |          |        |        |

## Error Log

| Timestamp | Error | Attempt | Resolution |
| --------- | ----- | ------- | ---------- |
|           |       | 1       |            |

## 5-Question Reboot Check

| Question             | Answer           |
| -------------------- | ---------------- |
| Where am I?          | Phase X          |
| Where am I going?    | Remaining phases |
| What's the goal?     | [goal statement] |
| What have I learned? | See findings.md  |
| What have I done?    | See above        |

Антипаттерны

Не делайте	Делайте вместо этого
Использовать TodoWrite для постоянства	Создать файл task_plan.md
Один раз озвучить цели и забыть	Перечитывать план перед решениями
Скрывать ошибки и тихо повторять	Записывать ошибки в файл плана
Пихать всё в контекст	Хранить большой контент в файлах
Начинать выполнение немедленно	Сначала создать файл плана
Повторять неудачные действия	Отслеживать попытки, менять подход

Принципы Manus

Принцип	Реализация
Файловая система как память	Хранить в файлах, не в контексте
Манипуляция вниманием	Перечитывать план перед решениями
Постоянство ошибок	Записывать неудачи в файл плана
Отслеживание целей	Чекбоксы показывают прогресс
Проверка завершения	Проверить все фазы перед остановкой

Помните: Чем больше контекста вы соберёте заранее и запишете на диск, тем лучше будет ваше выполнение. Файлы — это ваша постоянная память.