126 lines
13 KiB
Markdown
126 lines
13 KiB
Markdown
# Конвейер разработки на агентах: этап → исполнение → проверки (dx-flow)
|
||
|
||
> ЖИВАЯ карточка процесса: совершенствуется ретроспективами (dx-retro-1),
|
||
> оценки приёмов пересматриваются по новой фактуре, дописывается
|
||
> доказательной базой следующих проектов. Первая доказательная база — Kit.RAG
|
||
> (2026-10-30…11-01: 3 дня, 90 коммитов, 39 workflow-прогонов ~0,7 млрд
|
||
> токенов, ~26 ревизий; гейт 104→607 монотонно, находки ревизий 53→1–2
|
||
> low, ускорение модуль к модулю ×3–5). См. [readme.md](../../readme.md).
|
||
|
||
## Цикл этапа (проверен на 3 модулях)
|
||
|
||
```
|
||
ТЗ этапа (/stage: «Среда и гейты» B1–B8 + RAG-темы с якорями)
|
||
→ ИСПОЛНЕНИЕ: субагенты-workflow параллельно по зонам (или агент напрямую)
|
||
→ ИНТЕГРАТОР: полный гейт (build+test решения), точечные — у исполнителей
|
||
→ РЕВИЗИЯ СВЕЖИМ КОНТЕКСТОМ: независимый агент без контекста исполнителя;
|
||
сверяет код↔канон, якоря перепроверяет живым запросом (dx-dev-8),
|
||
числа пересчитывает сам (руками/своим парсером)
|
||
→ ПРАВКИ по находкам (применить/отклонить с обоснованием)
|
||
→ КОНТРОЛЬНЫЙ ГЕЙТ (правки ничего не сломали)
|
||
→ КАСКАД статусов (одно место: readme модуля; plan — строка; handoff —
|
||
хвосты/грабли) → GIT-КОММИТ (рецепт — в коммите этапа, B5/D3)
|
||
```
|
||
|
||
## Роли проверок
|
||
|
||
| Роль | Что проверяет | Ключевое свойство |
|
||
|---|---|---|
|
||
| Исполнитель | свою зону (точечные тесты) | не видит чужих зон |
|
||
| Интегратор | сборка целиком, швы (DI/slnx/фикстуры — dx-dev-3) | единственный полный гейт |
|
||
| Ревизор («проверка разработчиком со стороны» + «архитектором») | код↔канон, псевдо-цитаты, якоря, числа | СВЕЖИЙ контекст — главный источник качества; ловил high, невидимые исполнителю |
|
||
| Главная сессия | эскалации/развилки, инциденты вне зон | решает владелец |
|
||
|
||
Архитектурная проверка решений = протокол dx-dev-1 (до утверждения) +
|
||
ревизия шага 0 (module_reqs/спеки как документы, B7).
|
||
|
||
## Приёмы (оценки по ретроспективе Kit.RAG; пересматриваются)
|
||
|
||
| Приём | Оценка | Комментарий |
|
||
|---|---|---|
|
||
| Ревизия свежим контекстом + контрольный гейт | ядро, не трогать | находки 53→1–2 low; ловила вне-зонные правки, псевдо-цитаты |
|
||
| Авточемод с эскалациями на развилках | высокоэффективно | темп ×3–5 без потери контуров контроля; вводить ПОСЛЕ обкатки конвейера |
|
||
| Workflow-исполнители этапов | высокоэффективно | цена: капы/redo-прогоны (6/39), кэш-переигрывания — лечится маркером «ТЗ vN» |
|
||
| Honest-skip вместо молчаливого пропуска | высоко | все skip'ы позже сняты живыми прогонами |
|
||
| TCP-стабы внешних сервисов + детерминированные векторы | высоко | приёмочные стабильны и доказательны, не зависят от живой LLM |
|
||
| docChanges-реестр → легализация одним Изм. на замыкании | высоко (клапан) | симптом дрейфа канона — следить за возрастом |
|
||
| Метрики замыкания с независимым пересчётом | высоко | «не замерено честно» — списком, не замалчивать |
|
||
| Повторные полные гейты ×3–4 на этап | условно | после введения файл-лока основания нет — точечные + контрольный |
|
||
| Дублирование статусов в 3+ документах | НЕ окупилось | ~68% документационных коммитов; одно место + ссылки |
|
||
|
||
## Анти-паттерны (пережито, не повторять)
|
||
|
||
- Канон утверждается до схождения решений → смена курса после начала
|
||
кода (Изм. 5: переделка этапа, 53 находки). Лечение: dx-dev-1 до
|
||
утверждения.
|
||
- Вне-процессные правки «по ходу» с самовольной атрибуцией → откат,
|
||
инцидент. Лечение: изменения — через записи канона/эскалации.
|
||
- Закрытый этап «доезжает» потом дважды. Лечение: замыкание = контрольный
|
||
гейт + хвосты в handoff, не «потом».
|
||
|
||
## Открытые хвосты (совершенствуется)
|
||
|
||
- Страж-навык d-proc-guard (авто-проверка чек-листа при генерации ТЗ) —
|
||
решение на замыкании И4 по метрикам.
|
||
- Фильтр `--tag env:*` для search — среда из текста запроса в фильтр.
|
||
- Каноническая нарезка (чанк = законченная единица) — в очереди
|
||
легализации; снимет и недетерминизм LLM-нарезки.
|
||
- Формы исполнения вне workflow (короткие этапы) — накопить фактуру.
|
||
|
||
## Scorecard: оценки, по которым совершенствуется процесс
|
||
|
||
**Механика влияния на знания.** Замер (замыкание итерации, dx-retro-2)
|
||
→ светофор 🟢/🟡/🔴 → порог-триггер → изменение КОНКРЕТНОГО артефакта
|
||
знаний (карточка `_env` / правило dx / приём в dx-flow / строка dx-map /
|
||
наполнение дерева) → коммит std1-ext с указанием источника-замера →
|
||
переиндексация корпуса. Если правило соблюдается, а метрика хуже цели —
|
||
пересматривается ОЦЕНКА правила/приёма (понижается, хвост в «Открытых
|
||
хвостах»). Правки знаний — только через ретроспективу (владелец в
|
||
контуре утверждения), никогда «по ходу».
|
||
|
||
**Фиксация.** Замер — факт в отчёте замыкания итерации проекта (формат:
|
||
`итерация | метрика | значение | светофор | триггер | действие`), не
|
||
редактируется. Светофор и цели — здесь, с датой и источником. Действие —
|
||
git-коммит std1-ext («ретроспектива ИN, метрика M»). **Версионность** —
|
||
git: вся история правил и оценок = история коммитов; откат = `git
|
||
revert` правки знаний с обоснованием; замеры-факты не откатываются;
|
||
корпус пересобирается из git (индекс — производное, не версионируется).
|
||
|
||
### Метрики (база / цель / триггер / текущий светофор 2026-11-02)
|
||
|
||
| # | Метрика | База (И1/И2) | Цель | Триггер (порог действия) | Сейчас |
|
||
|---|---|---|---|---|---|
|
||
| А1 | Находки ревизии/этап, медиана | ~7 (пик 53) / ~2 | ≤2, high=0 | high на этапе → усилить B-блок ТЗ и фокус ревизии | 🟡 (И3-э1: 2 high) |
|
||
| А2 | Псевдо-якоря/псевдо-цитаты | 0 / 0 (И3-э1: 2) | 0 | >0 → приём в dx-flow + формулировка dx-dev-8 | 🟡 |
|
||
| А3 | Дефекты после замыкания этапа | И1: этап доезжал ×2 | 0 | >0 → ужесточить замыкание (контрольный + хвосты в handoff) | 🟡 |
|
||
| А4 | Повторы известных граблей | И2: 3 (кодировка/лок/байты) | 0 | 1-й повтор → инструмент (dx-retro-3); 2-й → эскалация владельцу | 🟡 (проверка И3: инструменты введены) |
|
||
| Б1 | Доля документационных коммитов | ~70% / ~56% | ≤40% | >50% две итерации подряд → упрощать каскад (одно место статусов) | 🟡 |
|
||
| Б2 | Redo-прогоны workflow/этап | 4 / 2 | ≤1 | >2 → стабильность скриптов (маркер «ТЗ vN», прогон сниппетов) | 🟡 |
|
||
| Б3 | Wall-clock и токены этапа | база И1/И2 зафиксирована | тренд ↓ на однотипных этапах | рост ×2 → разбор причин | 🟢 (ускорение ×3–5) |
|
||
| В1 | Возврат правил: батарея top-3 | 16/16 | 100% | <100% → чинить корпус/нарезку, не батарею | 🟢 |
|
||
| В2 | Темы с первого захода | 2/4 до env-фикса | ≥75% | <75% → тюнинг запросов / ускорить `--tag env:*` | 🟡 (контрольный прогон /decision) |
|
||
| В3 | Дыры корпуса (темы без находок) | механизм заведён | закрытие в ту же итерацию | каждая → кандидат наполнения дерева | 🟢 |
|
||
| В4 | Возраст docChanges на легализации | до 4 этапов | ≤1 итерации | >1 итерации → выносить легализацию чаще | 🟡 |
|
||
| Г1 | Honest-skip'ы сняты к замыканию | И1: все сняты живыми | 100% | остаток → в хвосты handoff | 🟢 |
|
||
| Г2 | Эскалации закрыты владельцем | не замерялось | ≤1 дня | дольше → выносить в повестку явно | 🟢 (эмпирически быстро) |
|
||
| Г3 | Инциденты среды: новые → карточка | правило заведено | в тот же день | дольше → помнить о dx-retro-3 | 🟢 |
|
||
|
||
**Пересмотр целей** — не чаще каждой второй ретроспективы, коммитом с
|
||
обоснованием. Добавление метрики — через ретроспективу (какие решения
|
||
она изменит? не изменяет — не заводить).
|
||
|
||
### История светофоров (полная — git log карточки)
|
||
|
||
- 2026-11-02 — базовая фиксация: А1–А4/Б1/Б2/В2/В4 🟡, Б3/В1/В3/Г* 🟢;
|
||
источники — ретроспектива Kit.RAG (И1/И2) и живой прогон /decision.
|
||
|
||
## Правило обновления карточки
|
||
|
||
Ретроспектива проекта (dx-retro-1) дописывает: новые приёмы с оценкой и
|
||
прецедентом-числом, пересматривает существующие оценки, закрывает хвосты,
|
||
обновляет светофоры со ссылкой на замер. Числа обязательны
|
||
(«быстрее/лучше» без чисел не принимается, dx-retro-2). Коммит в
|
||
std1-ext с указанием источника-ретроспективы + переиндексация корпуса.
|
||
Откат оценки/правила — git revert с обоснованием; замеры-факты
|
||
последующих итераций не откатываются.
|