#DeksdenFlow - 4, Protocol, Этап фиксации плана


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

Такое нельзя держать в себе, и для этого момента у меня есть длинный промпт, называется "protocol-new".

▶️ Сначала о терминах - почему "протокол"? Потому что эта система родилась из желания "тянуть" длинные рефакторинги через несколько контекстов, и для фиксации текущего состояния был использован файл "протокола" - там был раздел "выполненной работы", отсюда отличие от термина "план".

▶️ В итоге я пришёл к системе "protocol": это когда мы нашу доработку ведём фиксируя ряд файлов: протокол = план + контекст + методика + лог.

---

- папка протокола нумеруется, паттерн "XXXX-{название протокола}/", например "0040-server-refactoring/";
- ключевым является номер ХХХХ, который называется номером протокола, и по нему система его идентифицирует.
- все папки протокола у меня живут в корне проекта в папке ".protocols/"; точка в начале папки обозначает типа "системную" папку, подчёркивая её служебный характер;
- Идентифицировать протокол по полному названию папки смысла особого нету, агент разберётся и по номеру. Вполне работают промпты типа "Прочитай протокол 0074 из папки .protocols/".
- если прописать в главном индексном файле что есть такая папка .protocols, что там есть папки с названиями по паттерну XXXX-имя_папки, что ХХХХ тут номер протокола, что внутри содержатся протоколы доработок системы в наборе файлов, и пояснить про набор файлов -> тогда агент ищет быстрее и лучше.

---

- план разделён на крупные этапы, которые я исторически назвал "шагами"; по своей сути "шаг" - это группа задач;
- шаг разделён на несколько задач, обычно до 5-7;
- ‼️ мы уже обсуждали, что деление плана на шаги и оценка сложности/размера шага - это область доработки системы

---

- plan.md: в папке содержится файл "plan.md" с общим планом
- шапка общего плана написана в формате mini-ADR (погуглите про этот термин - **Architecture Decision Record**), это попытка сохранить из обсуждения не только информацию о том ЧТО необходимо делать, но и ПОЧЕМУ мы делаем именно так и ДЛЯ ЧЕГО;

---

- отдельные шаги получают собственные файлы планов в файлах с паттерном имени "YY-{название шага}.md"; это помогает сфокусировать агента на задачах текущего шага, не засоряя контекст/внимание деталями задач других шагов;
- внутри отдельного шага прописаны не только задачи доработки, но и организационные действия по плану (методика работы)

---

- перед началом каждого шага система проверяет что все изменения закоммичены
- задачи шага выполняются последовательно
- после выполнения всех задач мы делаем проверки:
* typecheck : обязательно, надо чтобы созданный код был корректным
* lint : обязательно, а то потом мы устанем вычищать стиль кода после больших правок; ‼️ лог линтера на каждом шаге поначалу стоит изучить: если ошибок довольно много, это означает что агентам неправильно доведён стиль кодирования в проекте, и они систематически что то делают не то - значит, следует исправить промпты;
* я запускаю 'test' : на этот скрипт завязаны юнит тесты; ‼️ стратегия тестирования - отдельная большая тема, про неё можно сказать много и там существует куча подходов со своими плюсами;
* когда все проверки прошли - агент должен сделать коммит и пуш; коммит делается с тегом шага, вида "[XXXX-YY]", где XXXX это номер протокола, YY-номер шага.

---

* Briefing: в файле шага есть секция briefing - это важные сведения для формирвоания контекста для выполнения работы по этому шагу; там прописывается цель доработок, важные файлы которые нужно знать, дополнительная информация - на что нужно обратить внимание. Эта секция помогает агенту подготовится для работы по шагу и сформировать нужный контекст.

---

* log.md: это файл про то, что сделано; ‼️ тут тоже была идея фиксировать не просто дубль лога изменения файлов в git, а прописывать особенности реализации, решённые проблемы, существенные детали; не сказал бы чтобы агентам было понятно это требование, поэтому пишут чего могут;

...