"#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, а прописывать особенности реализации, решённые проблемы, существенные детали; не сказал бы чтобы агентам было понятно это требование, поэтому пишут чего могут; ..."