Imported from AgelxNash/DocLister (
AGENTS.md). Install upstream withnpx skills add AgelxNash/DocLister. Copyright stays with the author.
DocLister Maintenance Instructions
1. Цель
DocLister — стабильный фундаментальный компонент экосистемы Evolution CMS.
Постоянные инварианты сопровождения:
- каждый issue исследуется и получает доказательное решение;
- исправленные дефекты имеют regression tests;
- публичный API и поведение DocLister не изменяются без обоснованного решения о breaking change;
- проекты-потребители DocLister не ломаются после изменений;
- результаты исследования и принятые решения сохраняются в
ai-context.
Наличие открытого issue само по себе НЕ означает необходимость изменения production-кода.
Главная задача — разрешить issue, а не выполнить буквально исходное пожелание его автора.
2. Основной принцип
DocLister — legacy-компонент с большим количеством внешних потребителей.
Приоритеты в порядке важности:
- Correctness.
- Backward compatibility.
- Regression protection.
- Predictability публичного API.
- Maintainability.
- Modernization.
Не выполнять модернизацию ради модернизации.
Не менять архитектуру, синтаксис, API или минимальную версию PHP только потому, что существует более современный способ реализации.
3. Источник истины
Перед работой над любой задачей обязательно исследовать:
- текст GitHub issue;
- все комментарии issue;
- связанные commits / PR / issues;
HISTORY.md;- README и существующую документацию;
- текущую реализацию соответствующего поведения;
- tests;
- историю Git соответствующего участка кода, если она помогает понять контракт;
- связанные проекты-потребители, если изменение затрагивает публичное поведение.
Issue является описанием проблемы пользователя, но не спецификацией реализации.
Предложения автора issue рассматриваются как гипотезы.
4. Классификация каждого issue
Каждый issue после исследования должен получить ровно одну итоговую классификацию.
FIXED
Дефект подтверждён и исправлен.
Требования:
- воспроизведение старого поведения;
- regression test, падающий до исправления;
- минимальное исправление;
- тест проходит после исправления;
- проверены соседние сценарии.
ALREADY_FIXED
Проблема существовала ранее, но текущий master её уже не содержит.
Требования:
- определить участок кода, исправивший проблему, если возможно;
- добавить regression test, если его нет;
- документировать текущее корректное поведение.
CANNOT_REPRODUCE
Сценарий из issue воспроизведён максимально близко к исходному окружению, но проблема отсутствует.
Требования:
- зафиксировать reproduction scenario;
- добавить regression test текущего ожидаемого поведения, если это разумно;
- указать версии и ограничения проверки;
- закрыть issue после документированного результата.
Не оставлять такие issues открытыми бесконечно.
OBSOLETE
Issue описывает API, архитектуру, версию Evolution CMS или сценарий, который больше не является частью поддерживаемого поведения.
Не реализовывать устаревшее требование только ради закрытия issue.
Обязательно объяснить, почему оно потеряло актуальность.
DUPLICATE
Проблема полностью покрывается другим issue.
Указать canonical issue.
UPSTREAM
Причина находится в Evolution CMS или другом компоненте, а изменение DocLister было бы неправильным архитектурным решением.
Зафиксировать зависимость и закрыть issue со ссылкой на upstream-проблему либо решение.
WONTFIX
Запрошенное изменение возможно технически, но нарушает существующий контракт, создаёт disproportionate complexity или противоречит архитектуре компонента.
Решение должно содержать техническое обоснование.
5. Workflow одного issue
Работать только с одним issue за один атомарный цикл.
Последовательность обязательна:
Research
Получить issue и комментарии.
Определить:
- ожидаемое поведение;
- фактическое поведение;
- версию DocLister;
- версию Evolution CMS;
- PHP version;
- затронутый controller/extender/API;
- вероятные связанные issues.
Code tracing
Проследить весь путь данных от входного параметра до результата.
Не исправлять первое подозрительное место без понимания полного execution flow.
Reproduction
Создать минимальный воспроизводимый сценарий.
По возможности сначала получить failing regression test.
Если полноценная Evolution CMS для воспроизведения не требуется, использовать минимальный runtime harness.
Если без Evolution CMS сценарий недостоверен — использовать integration environment.
Classification
Только после reproduction выбрать итоговый статус issue.
Implementation
Если требуется исправление:
- менять минимально необходимый участок;
- не выполнять попутный рефакторинг;
- не менять публичный API;
- не переименовывать параметры;
- не менять default behavior без отдельного решения.
Verification
Проверить:
- regression test;
- существующий test suite;
- соседние сценарии;
- потенциальные consumers.
Documentation
Создать запись в ai-context/tasks.
Сохранить существенные результаты исследования в ai-context/notes.
Сырые диагностические данные при необходимости сохранять в ai-context/artifacts.
GitHub resolution
Комментарий в issue должен содержать:
- результат диагностики;
- причину;
- что изменилось или почему изменение не потребовалось;
- commit/test при наличии;
- итоговое ожидаемое поведение.
После этого issue закрывается с корректной причиной.
6. Definition of Done для bugfix
Bugfix НЕ считается завершённым только потому, что код изменён.
Минимальный DoD:
- исходная проблема воспроизведена либо доказано отсутствие воспроизведения;
- причина установлена;
- изменение минимально;
- regression test существует;
- regression test проверяет именно публичное наблюдаемое поведение;
- соседние tests проходят;
- поведение документировано;
- issue получил итоговый комментарий;
- issue закрыт.
7. Backward compatibility
DocLister используется другими Evolution CMS extras и пользовательским кодом.
Считать публичным контрактом:
- snippet parameters;
- controller names;
- extenders;
- методы классов, используемые внешним кодом;
- callbacks
prepare,prepareWrap,onIterationи аналогичные; - placeholders;
- API/json output;
- filters syntax;
- pagination behavior;
- template processing;
- document/TV selection semantics;
- порядок применения filters/prepare/select/api;
- доступные поля возвращаемых структур;
- загрузку legacy classes.
Любое изменение такого поведения считается потенциальным breaking change.
Breaking change запрещён в рамках обычного issue fix.
8. Consumer compatibility
При изменениях фундаментальных механизмов искать использование затронутого API в связанных Evolution CMS extras: GitHub code search по изменяемому классу, методу или параметру.
Если consumer опирается на поведение, которое кажется ошибочным, не исправлять его молча.
Зафиксировать compatibility decision.
9. Работа с legacy PHP
Приоритет — стабильность и сопровождение, а не повышение минимальной версии PHP.
Запрещено в issue fixes без отдельного ADR:
- массово добавлять современные PHP type declarations;
- переводить классы на namespaces;
- менять autoloading architecture;
- использовать синтаксис, исключающий ранее поддерживаемое окружение;
- менять minimum PHP version;
- обновлять зависимости только ради актуальности версии.
Modernization должна выполняться отдельным этапом с собственным планом.
10. SQL и данные
Особое внимание уделять:
- escaping;
- placeholders;
- типам значений;
NULL;- датам;
- числовым comparison operators;
- LIMIT/OFFSET;
- total count;
- JOIN;
- TV values;
- aliases таблиц;
- idField/idType;
- различиям controller implementations.
Не исправлять SQL через string replacement, если можно сохранить существующую модель построения запросов.
Для изменений SQL обязательны tests как минимум на boundary cases.
11. Refactoring issues
Issues с Refactoring, Enhancement, Pause, Not confirmed сначала переоценивать относительно текущего master.
Старый enhancement не является автоматически обязательным feature.
Перед реализацией ответить:
- Какая пользовательская проблема решается?
- Существует ли она сегодня?
- Есть ли уже другой механизм?
- Использует ли внешний код старое поведение?
- Можно ли закрыть issue как obsolete?
- Требуется ли это для дальнейшей Evolution CMS Community работы?
Если реальной потребности больше нет — закрыть issue с объяснением вместо реализации исторического design proposal.
12. Большие архитектурные изменения
Для задач уровня:
- SQL query builder;
- autoloader;
- paginator refactoring;
- logging architecture;
- event architecture;
- user API;
- access control;
сначала создать отдельный ADR.
ADR должен описывать:
Context Existing behavior Consumers Alternatives Backward compatibility Decision Migration strategy Testing strategy
До принятия ADR production-код не менять.
13. Что запрещено агенту
Не выполнять массовый рефакторинг.
Не исправлять code style в файлах, не относящихся к задаче.
Не менять поведение «потому что так правильнее».
Не удалять legacy API без анализа consumers.
Не выполнять несколько независимых issues одним commit.
Не закрывать issue без доказательства результата.
Не считать комментарий пользователя технической спецификацией.
Не маскировать отсутствие воспроизведения speculative fix'ом.
Не добавлять compatibility shim без подтверждённого consumer.
Не переписывать компонент на современную архитектуру без отдельного решения.