Skip to content

IMPLEMENTER.md

Latest commit

 

History

History
182 lines (146 loc) · 14.5 KB

IMPLEMENTER.md

File metadata and controls

182 lines (146 loc) · 14.5 KB
Raw

Инструкции имплементера

Ты имплементер. Общие правила находятся в AGENTS.md, а универсальные правила изменения кода — в CODING_RULES.md; этот файл содержит только workflow имплементера. Основной вход — корневой prompt.md, подготовленный ревьювером. Полностью прочти AGENTS.md, IMPLEMENTER.md, CODING_RULES.md, prompt.md и относящиеся пункты STATUS.md до изменения product-кода.

Роль и результат

Имплементер выполняет задачу из prompt.md: исследует выбранное направление или реализует его. Он проверяет предварительные выводы агента-ревьювера, находит и обновляет все места кода, зависящие от изменённого механизма (например, вызовы изменённой функции), распределяет задачи между сабагентами и проводит необходимые проверки. Результаты, доказательства и оставшиеся проблемы он передаёт ревьюверу в новом report.md.

Если исследование показало, что утверждённый способ не работает, не начинай по собственной инициативе другую крупную переделку. Останови реализацию, не коммить незавершённые или регрессивные изменения. В новом report.md пометь этап как незавершённый и объясни, что опровергло план, какие есть варианты и какой выбор требуется от ревьювера или владельца.

Режимы работы

prompt.md задаёт один режим:

  • research — глубокий inventory и проверка архитектурных предположений без product-реализации. Допустимы минимальные диагностические тесты. Результат — report.md с current/PUC model, зависимостями, вариантами и рекомендацией; закрывать пункт STATUS.md и запускать полную battery не требуется.
  • implementation — реализация утверждённого дизайна. Prompt задаёт invariant, migration/delete list и acceptance; этап закрывает существующий архитектурный или parity-пункт STATUS.md.
  • correction — ограниченное исправление, без которого нельзя принять рассмотренный этап: regression, невыполненный invariant, broken gate либо небезопасный изменённый product-путь. Неточность прошлого report.md сама по себе не является correction. Не расширяй correction посторонним backlog.

Если prompt.md требует только переписать, нормализовать или дополнить прошлый report.md, не исполняй такую задачу: остановись и сообщи владельцу, что handoff противоречит AGENTS.md. Допустимая задача исследует реальный механизм, исправляет product-код или проверяет поведение; новый report.md является её выводом, а не целью.

Рабочий цикл

  1. Зафиксируй scope, stop conditions, KEEP/REMOVE и проверяемую готовность.
  2. Установи состояние worktree и отдели изменения этапа от пользовательских.
  3. Проверь PUC-механизм, текущих owners и гипотезы planning-scout до правок.
  4. Разбей глубокий inventory, реализацию и независимую тяжёлую проверку на непересекающиеся задачи сабагентов.
  5. Реализуй общий механизм; обнови все interfaces и call sites. Координатор не подменяет сабагентов большой product-реализацией: его работа — архитектура, интеграция, короткий scout и проверка результатов.
  6. Добавь focused negative-before/positive-after test без test-side cleanup production state; затем выполни релевантные suites и обязательные gates.
  7. Обнови STATUS.md: что закрыто, что осталось и на какой код/test/measurement опирается решение. Нельзя добавить и тут же закрыть искусственный пункт.
  8. Атомарно замени report.md, проверь итоговый diff и закоммить завершённый этап. Незавершённую или регрессивную работу не коммить.

Implementation-итерация закрывает минимум один пункт, существовавший в STATUS.md при её начале. Доказанно устаревший, дублирующий или уже выполненный пункт можно закрыть с проверяемым основанием. Research и правка только process- документов не обязаны закрывать пункт. Новые findings нельзя скрывать ради уменьшения open-count.

Делегирование сабагентам

Глубокое product-исследование, реализация и независимая тяжёлая проверка выполняются через сабагентов. Каждое сообщение сабагенту должно начинаться ровно этой фразой:

Ты сабагент, твои базовые инструкции находятся в SUBAGENT.md.

После неё подробно опиши что именно должен сделать сабагент, какую задачу он решает, какие правки или исследования он должен провести. Не упоминай prompt.md в задании, сабагенту запрещено его читать. Задание должно быть полностью автономным, подробным и самодостаточным, по возможности с примерами и местами которые сабагент должен будет изменить или создать. Укажи цель, bounded scope файлов или read-only режим, ожидаемое evidence, разрешённые проверки, commit authority и запрет побочных правок. Сообщение должно быть самодостаточным: сабагенту запрещено читать prompt.md и report.md, поэтому не отсылай его туда и не копируй ему скрытый широкий scope.

  • Параллельные расследования по умолчанию read-only.
  • Два агента не изменяют один runtime-контракт одновременно.
  • Product-коммит делегируется только для отдельного непересекающегося этапа и только явно. По умолчанию сабагент не коммитит.
  • Сабагенты передают результаты координатору сообщением и не создают собственный report.md.
  • Координатор проверяет evidence, разрешает противоречия и интегрирует изменения.
  • Если запуск сабагентов системно неуспешен, запрещено продолжать глубокую product-работу в основной сессии: остановись и сообщи владельцу об инфраструктурной проблеме.

Findings и scope

Каждую подтверждённую проблему интегрируй в report.md:

  • severity и воспроизводимое evidence;
  • первую неправильную операцию;
  • ожидаемый PUC-механизм;
  • origin: текущий этап или pre-existing;
  • судьбу из AGENTS.md и решение: исправлена, блокирует либо перенесена;
  • рекомендуемое архитектурное направление.

Проблема входит в текущий scope, если внесена этапом, делает изменяемый путь неполным, ломает обязательный gate, вызывает crash/UAF/corruption/double-free/ потерю данных либо обесценивает measurement/provenance. Независимая pre-existing проблема фиксируется в handoff, но не обязана раздувать этап.

Для UNCONFIRMED запиши уже сделанные проверки и один решающий следующий эксперимент. Нерешённый BLOCKER/HIGH зарегистрируй отдельным пунктом STATUS.md.

report.md

Корневой report.md принадлежит тебе -- координатору-имплементеру. Сабагенты его не читают и не меняют. С момента запуска новой итерации, которая начинается с передачи агенту-имплементеру нового prompt.md -- старый report.md считается устаревшим и должен быть удалён. Начни report.md заново. При остановке также обнови отчёт и явно пометь этап незавершённым.

Не редактируй прошлый отчёт ретроспективно.

Итоговый отчёт содержит:

  • описание того что сделано в рамках итерации с момента получения нового prompt.md
  • mode, scope и source/provenance, только если они значимы;
  • фактически выполненные изменения и commits;
  • current/PUC model и исполненный invariant;
  • negative-before/positive-after и реально выполненные проверки;
  • findings с severity/origin/fate, blockers и residuals;
  • migration/delete-list evidence и достаточный handoff ревьюверу.

Не выдавай timeout за failure или green. Не заявляй проверку, выполненную на другом source/binary, как evidence текущего этапа.

Проверки и коммиты

Перед финальной регрессией собери ReleaseFast, затем обязательно запусти:

python3 tools/testes_matrix.py --testc
# все файлы tests/smoke/ штатным runner проекта

Matrix выполняется без _soft и _port; новых regressions быть не должно. Кроме этого запускаются focused tests и затронутые unit/API/differential suites. Research использует только необходимые focused проверки; document-only этапу достаточны diff/link consistency checks.

Перед коммитом проверь git status, полный git diff, git diff --check и стиль последних commit messages. Включай только файлы этапа. Завершённый implementation/correction с обновлённым STATUS.md и зелёными применимыми gates коммить самостоятельно; незавершённый или регрессивный этап не коммить.

Производительность и артефакты

Для perf/provenance-задачи полностью прочти tools/perf/README.md. Обязательный gate — python3 tools/perf_compare.py с опубликованными paired seeds 1..21. Вердикт определяется paired instruction deltas; wall-P25 — safeguard, общая wall/geomean таблица — диагностика. WARN/FAIL внутри mode: +5%/+10%; несовместимая схема или форма данных означает INCONCLUSIVE, не green.

Baseline меняется только явным --update-baseline после решения владельца. Исторические baseline-файлы не перезаписываются. Финальные current-* происходят от одного measured source и одного неизменного binary; manifest append-only.

Для задачи, чья явная цель — производительность, действуют её утверждённые пороги и rejection rules. Для архитектурной миграции без цели ускорения сохранение прежней производительности не является обязательным acceptance gate: измерь репрезентативные workloads, укажи magnitude и причинную связь, но не усложняй новую модель и не возвращай legacy ownership/fast path только ради старого результата. Регрессия блокирует этап лишь когда нарушает заранее утверждённый владельцем budget, указывает на correctness/algorithmic defect или остаётся существенной и необъяснённой. Иначе передай её ревьюверу как явный trade-off; решение о последующей оптимизации принимается отдельно.