From 714342f5ac32eb60fb688a48d662b52bf80563aa Mon Sep 17 00:00:00 2001 From: Sergey Vanyushkin Date: Thu, 7 May 2026 22:31:23 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB?= =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20workflow=20=D0=B4=D0=BB=D1=8F=20bugfix=20?= =?UTF-8?q?=D0=B8=20refactoring?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - blog/AGENTS.md: добавлены Bugfix Lifecycle и Refactoring Lifecycle - tests/AGENTS.md: добавлены Bugfix Test Workflow и Refactor Test Workflow - Добавлены правила для regression tests - Добавлены anti-patterns для багфикса и рефакторинга - Обновлены commit rules для всех типов задач --- AGENTS.md | 95 ++++++++++++++++++++++++++++++++++++++++++++----- tests/AGENTS.md | 37 +++++++++++++++++-- 2 files changed, 122 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b785fb7..62c3db2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -408,9 +408,85 @@ Commit (во все затронутые проекты) |-- blog, pytfm, pyaqa (root) ``` +### Bugfix Lifecycle + +``` +User: "исправить баг" + | + v +Reproduction Phase + |-- Анализ бага, воспроизведение + |-- Определение root cause + |-- Создание artifact: pyaqa/bugfix/{name}.md + | + v +Write Regression Test + |-- Написать тест, воспроизводящий баг + |-- Убедиться что тест падает (RED) + | + v +Fix (GREEN) + |-- Минимальный фикс + |-- Убедиться что тест проходит + | + v +Verification + |-- Все существующие тесты проходят + |-- Coverage не упал + |-- Линтеры, type checker + | + v +User Acceptance + |-- Пользователь проверяет исправление + | + v +Commit (во все затронутые проекты) +``` + +### Refactoring Lifecycle + +``` +User: "отрефакторить" + | + v +Analysis Phase + |-- Анализ кода + |-- Определение scope и рисков + |-- Создание artifact: pyaqa/refactor/{name}.md (опционально) + | + v +Pre-check + |-- Все тесты проходят ДО рефакторинга + |-- Фиксация coverage baseline + | + v +Refactoring + |-- Пошаговые изменения + |-- Проверка тестов после каждого шага + | + v +Post-check + |-- Все тесты проходят ПОСЛЕ рефакторинга + |-- Coverage не ниже baseline + |-- Поведение не изменилось + | + v +Verification + |-- Линтеры, type checker + |-- Нет новых warnings + | + v +User Acceptance (опционально) + |-- Пользователь проверяет, что ничего не сломалось + | + v +Commit (во все затронутые проекты) +``` + ### Branch Naming -- Формат: `feature/{feature-name}` -- База: `dev` +- **Feature**: `feature/{feature-name}` от `dev` +- **Bugfix**: `bugfix/{bug-name}` от `dev` +- **Refactor**: `refactor/{name}` от `dev` ### Test Case IDs - `TC-UNIT-NNN` — unit тесты (domain, use cases) @@ -419,20 +495,23 @@ Commit (во все затронутые проекты) - `TC-E2E-NNN` — End-to-end тесты (Playwright) ### Test Level Selection -Все 4 уровня по умолчанию. Можно сокращать в зависимости от фичи: +Все 4 уровня по умолчанию. Можно сокращать в зависимости от задачи: - **Domain-only фича**: только TC-UNIT - **API-only фича**: TC-UNIT + TC-API - **Web UI фича**: TC-UNIT + TC-WEB + TC-E2E - **Full-stack фича**: все 4 уровня +- **Bugfix**: уровни в зависимости от слоя бага (минимум unit + regression) +- **Refactor**: все существующие тесты (unit + api + web + e2e) ### Artifact Location -- **Шаблон**: `pyaqa/feature/TEMPLATE.md` -- **Артефакт фичи**: `pyaqa/feature/{feature-name}.md` +- **Feature**: `pyaqa/feature/TEMPLATE.md` → `pyaqa/feature/{feature-name}.md` +- **Bugfix**: `pyaqa/bugfix/TEMPLATE.md` → `pyaqa/bugfix/{bug-name}.md` +- **Refactor**: `pyaqa/refactor/TEMPLATE.md` → `pyaqa/refactor/{name}.md` ### Commit Rules -При приемке фичи коммитить во ВСЕ затронутые подпроекты: -1. `blog/` — если затронут -2. `pytfm/` — если затронут +При завершении коммитить во ВСЕ затронутые подпроекты: +1. `blog/` — если изменен +2. `pytfm/` — если изменен 3. `pyaqa/` (root) — всегда (обновление ссылок на подпроекты) ## Notes diff --git a/tests/AGENTS.md b/tests/AGENTS.md index bf415ea..cb44ca6 100644 --- a/tests/AGENTS.md +++ b/tests/AGENTS.md @@ -65,7 +65,7 @@ Agents MUST consult these files before adding or modifying tests. ### Adding a Feature Test -1. **User triggers**: `"начнем новую фичу"` +1. **User triggers**: `"начем новую фичу"` 2. **Agent analyzes**: существующий код, затронутые слои, рекомендует тесткейсы 3. **User agrees**: подтверждает или корректирует набор тесткейсов 4. **Agent creates**: @@ -78,6 +78,31 @@ Agents MUST consult these files before adding or modifying tests. 9. **User accepts**: подтверждает приемку 10. **Agent commits**: во все затронутые проекты +### Bugfix Test Workflow + +1. **User triggers**: `"исправить баг"` +2. **Agent analyzes**: воспроизводит баг, определяет root cause +3. **Agent creates**: `pyaqa/bugfix/{bug-name}.md` — артефакт бага +4. **Agent writes regression test**: + - Unit тест, воспроизводящий баг (должен падать) + - Дополнительные тесты на уровне бага (API/Web/E2E) +5. **Agent fixes**: минимальный фикс +6. **Agent verifies**: все тесты проходят, coverage не упал +7. **User accepts**: проверяет исправление +8. **Agent commits**: во все затронутые проекты + +### Refactor Test Workflow + +1. **User triggers**: `"отрефакторить"` +2. **Agent analyzes**: scope рефакторинга, затронутые файлы +3. **Agent creates**: `pyaqa/refactor/{name}.md` (опционально) +4. **Pre-check**: фиксирует baseline (все тесты проходят, coverage) +5. **Agent refactors**: пошаговые изменения +6. **Post-check**: все тесты проходят, coverage не ниже baseline +7. **Agent verifies**: линтеры, нет новых warnings +8. **User accepts**: опционально проверяет поведение +9. **Agent commits**: во все затронутые проекты + ### Test Case Assignment Rules - **TC-UNIT-NNN**: unit тесты (domain, use cases) @@ -91,7 +116,7 @@ Agents MUST consult these files before adding or modifying tests. ```markdown ### TC-UNIT-NNN: Test Name -- **Type:** Positive | Negative | Policy +- **Type:** Positive | Negative | Policy | Regression - **Layer:** Unit | API | Web | E2E - **File:** `path/to/test.py::TestClass::test_method` - **Expected:** Что ожидается @@ -113,6 +138,12 @@ Agents MUST consult these files before adding or modifying tests. | Web | 60% | Routes + handlers | | E2E | Cover all AC | Все acceptance criteria | +### Regression Test Rules + +- **Bugfix**: ДОЛЖЕН включать regression test (unit минимум) +- **Refactor**: ВСЕ существующие тесты должны проходить ДО и ПОСЛЕ +- **Coverage**: Не должен упасть после багфикса или рефакторинга + ## Anti-Patterns - Do NOT add `@pytest.mark.asyncio` to `async def` tests (auto mode handles it) @@ -121,6 +152,8 @@ Agents MUST consult these files before adding or modifying tests. - Do NOT put fixtures in `__init__.py` — use `conftest.py` - Do NOT write implementation before tests (no TDD bypass) - Do NOT skip RED phase (tests must fail before implementation) +- Do NOT commit багфикс без regression test +- Do NOT commit рефакторинг с упавшим coverage ## Notes