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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. Создать `task_plan.md` по шаблону
2. Создать `findings.md` по шаблону
3. Создать `progress.md` по шаблону
4. Заполнить раздел 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

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

---

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