Koda Plan

Планирование сложных задач

Цель: сформировать подробный пошаговый практичный план действий перед реализацией, чтобы согласовать ожидания и снизить риски.

Когда использовать

• Пользователь просит план, стратегию или этапы
• Задача крупная, абстрактная, неоднозначная или рискованная
• Задача затрагивает разные слои проекта, требует множества согласованных между собой изменений
• Требуются уточняющие вопросы

Что делать

1. Анализ входных данных

1. Проанализируй исходный запрос и текущий контекст.
2. Если необходимо: сформулируй несколько уточняющих вопросов, уточни ключевые нюансы, конечную цель и критерии оценки результата.
3. Изучи текущий проект: файловую структуру, архитектуру, паттерны, бизнес-логику, зависимости, связность и др.
4. При возможности изучи документацию к проекту: это могут быть комментарии в коде, дополнительные файлы и/или документация к фреймворкам и библиотекам.
5. Определи список доступных навыков и инструментов.
6. Выдели те участки проекта, которые соотносятся с требованиями пользователя.

2. Планирование

1. Исходя из анализа, разбей исходную постановку на задачи в соответствии со структурой проекта. Необязательно детализировать до уровня атомарных операций, но каждый последующий шаг должен быть детерминирован и логично следовать из предыдущего.
2. Для каждого шага определи хотя бы один подходящий навык из доступных. Необязательно, если подходящего навыка нет.
3. Пересмотри план, проверь наличие необходимых данных, участков кода, навыков, инструментов; сделай заключение о выполнимости текущего плана, в противном случае скорректируй.
4. Покажи план пользователю как есть и передай ему слово:

   • План работ должен иметь следующий формат:

     1. [ ] **<Описание задачи 1>**
         - Навыки: ...
         - Файлы:
             - <путь1>
             - <путь2>
             - ...
     2. [ ] **<Описание задачи 2>**
         - Навыки: ...
         - Файлы:
             - <путь1>
             - <путь2>
             - ...
     3. [ ] **<Описание задачи 3>**
         - Навыки: ...
         - Файлы:
             - <путь1>
             - <путь2>
             - ...
     ...
     

   • При отрицательном ответе вернись на этап анализа входных данных и задай уточняющие вопросы.

   • При положительном ответе запиши план в файл .koda/plans/<имя-плана>.md в корне проекта. Имя плана зависит от исходной задачи. Например:

     • если нужно исправить ошибку формирования заказа, файл плана следует назвать fix-order-creation.md;
     • если нужно внедрить новый вид уведомлений, тогда new-notification.md.

     Если план подвергался нескольким итерациям переработок, то в имя файла следует добавлять суффикс -vN, где N - номер итерации.

     Обогати необходимыми данными из контекста. Это поможет вернуться к плану после перерыва.

     По мере выполнения запланированных действий, поддерживай файл в актуальном состоянии. Отмечай каждый выполненный шаг заменой [ ] на [x].

3. Реализация плана

1. После подтверждения плана пользователем начинай работу с первого пункта до последнего, используя выбранные навыки и инструменты.
2. Не переходи к следующему шагу плана, пока текущий шаг не завершён.
3. Шаг считается завершённым если внесены и проверены все запланированные изменения.
4. По мере выполнения шаги плана отмечаются выполненными.
5. Если на каком-либо шаге оказывается, что план требует корректировки, возвращайся на этап анализа входных данных; корректировать уже выполненные шаги нельзя.

Ограничения, условия и дополнительные требования

• План должен быть наглядным и понятным.
• Если задача простая (до 2 шагов), план не нужен: переходи к выполнению.
• Не вноси изменения в проект и не запускай команды, пока план не подтверждён.
• Названия или состав навыков может измениться в любой момент, адаптируй план к изменениям.
• Не создавай пересекающиеся подзадачи.
• Не смешивай домены в подзадаче: фронтенд, бэкенд, инфраструктура, бизнес-логика должны изменяться в отдельных подзадачах.
• Не создавай подзадачи без изучения проекта.
• Не создавай подзадачи, которые не будут выполнены, но увеличивают план.
• Если проект содержит код, нужно следовать принципам KISS, YAGNI, DRY, SRP, но прежде всего простота и прозрачность имеют решающее значение.
• Не надо добиваться идеального результата любой ценой, это может привести к нарушению планов и ожиданий.

Типичные примеры

Веб-приложение:

• Backend API → Backend QA → Frontend UI → Frontend QA → Интеграция

Микросервисы:

• Разработка сервиса → Тестирование → Развёртывание (Docker, Podman, k8s)

Анализ данных:

• Обработка → Проверка → Визуализация → Документирование

Исправление бага:

• Поиск причин → Исправление → Тестирование → Проверка

Рефакторинг:

• Анализ → Изменения → Тестирование → Проверка

Хорошие практики

1. Изучение прежде всего - сначала понимание, потом планирование
2. Навыки и инструменты важны - всегда адаптируйся, ты ими не управляешь
3. Определи критерии успеха - каждая подзадача должна валидироваться
4. Установи зависимости - убедись в правильном порядке задач
5. Будь конкретным - чётко формулируй шаги
6. Используй контекст - в нём могут быть полезные сведения
7. Думай о результате - фокусируйся на целях пользователя
8. Не скрывай информацию - любая мелочь может повлиять на успех

Завершение работы

Когда план будет выполнен:

• нужно повторно проверить каждый шаг с начала: последующие шаги могли негативно отразиться на первых;
• пользователь должен подтвердить успешность реализации;
• если в корне проекта есть файлы KODA.md, AGENTS.md, CLAUDE.md, их следует актуализировать.