Дебаты Astra × Fablefinal
Большой Django-проект: полный гайд перехода к разработке с LLM
Универсальная концепция · 8 сентября 2026 года · синтез реальных дебатов Codex / GPT-6 Astra и Claude Code / Fable 5.1.
Рекомендуемый результат — связанная система знаний, исполняемых ранбуков, ограниченных полномочий и проверяемой приёмки. Человек сообщает намерения и принимает необходимые решения; модели и инструменты готовят материал, выполняют механику, проверяют и фиксируют результат. Действующие решения используются повторно.
Содержательные дебаты завершены за 3 раунда при потолке 6. Статус независимой проверки конкретной версии и её хеш находятся в реестре проверки. Согласие моделей — проверка согласованности концепции, а не доказательство правильности ещё не обследованного проекта.
В этом файле целиком собраны десять глав, шаблоны, решения синтеза и карта покрытия. HTML-демонстрация показывает работу и остановки процесса. Реестр результата содержит отдельные главы для удобного чтения. Ключевые технические положения сверены с официальными источниками. Django 5.2 используется как явно указанная версия примеров документации; версия будущего проекта определяется обследованием.
Практический маршрут: сначала главы 1–2 для устройства процесса, затем 7 для плана перехода. Главы 3–6 объясняют выполнение, 8–9 — проверку достаточности и технические адаптеры. Глава 10 и приложение A дают сценарии и заготовки.
Гайд не требует сначала описать каждый метод проекта. Для первого результата выбирается полезный ограниченный срез, который проходит весь цикл до приёмки и восстановления. Затем охват расширяется по результатам испытаний.
1. Целевая модель разработки
Статус: универсальная концепция. Состояние проверки итоговой версии указано в реестре результата.
Что мы строим
Результат перехода — воспроизводимый процесс, в котором модель получает намерение, находит достаточный контекст, выполняет разрешённые ранбуки, предоставляет проверяемый кандидат изменения и доводит его до результата. Документация — память и контракт этого процесса. Она не заменяет работающую среду, тесты, контроль полномочий и приёмку.
Человек сообщает смысл и выбирает между вариантами там, где выбор нельзя вывести из уже действующих решений. Модель готовит вопрос, варианты, последствия, рекомендуемый вариант и материалы для проверки. После ответа она сама фиксирует решение и исполняет разрешённую механику. Человек не переписывает YAML, не переносит отчёты между чатами и не запускает команды за модель только потому, что процесс не автоматизирован.
Это универсальная концепция для существующего Django-проекта. Ни один пример заказов, скидок, PostgreSQL, Celery или DRF ниже не является утверждением о вашем живом репозитории. Состав стека выясняется при применении гайда.
Семь сущностей, которые нельзя путать
| Сущность | Что хранит | Кто/что служит основанием |
|---|---|---|
| Намерение, INT | Нужный результат, мотив, ограничения | Сообщение уполномоченного человека |
| Решение, DEC | Выбранный вариант и границы выбора | Аутентифицированный ответ на конкретный пакет решения |
| Норма, BR/POL | Требуемое бизнес-поведение или правило процесса | Действующее решение либо утверждённая политика |
| Наблюдение, OBS | Что обнаружено в определённых условиях | Код, эксперимент, тест, история, разрешённые наблюдения |
| Проекция, PROJ | Механически извлечённая структура | Конкретные версии анализатора, исходников и конфигурации |
| Доказательство, EV | Результат конкретной проверки | Доверенный исполнитель и идентифицированные входы |
| Полномочие, GRANT | Разрешённые действия и условия их выполнения | Решение о полномочиях и доверенная система исполнения |
Ранбук RB связывает эти сущности в процедуру. Контракт изменения CHG задаёт, какое поведение должно измениться и по каким критериям результат принимается.
«Тест проходит», «так написано в старом коде», «так хочет бизнес» и «это разрешено выкладывать в production» — четыре разных утверждения. Совпадение первых двух не разрешает подменять ими третье или четвёртое.
Статусы по разным осям
Не используйте один флаг verified для всего документа. Минимальная модель:
- жизненный цикл записи: draft, active, retired;
- нормативный статус правила: proposed, accepted, superseded;
- основание знания: extracted, observed, inferred, unknown;
- актуальность к снимку: current, suspect, stale, unknown;
- наличие противоречия: none, open, resolved;
- полномочие: proposed, active, expired, revoked;
- результат проверки: passed, failed, blocked, not_run, not_applicable.
Диагноз flaky хранится отдельно от результата конкретной попытки:
нестабильная проверка может иметь и passed, и failed в истории. Приёмка
записывает accept/reject/blocked; устаревшее evidence даёт blocked с причиной
stale_evidence, а не новую разновидность успешной приёмки.
Изменение кода делает зависимое наблюдение кандидатом на перепроверку,
но не отменяет бизнес-норму. Новая норма может быть утверждена раньше её
реализации: такая запись честно хранит implementation: pending.
Пропущенный тест не равен пройденному. not_applicable требует основания
от доверенного правила отбора, а не свободной отписки автора PR.
Решение человека один раз, исполнение многократно
Начальный пакет решения содержит: цель, точные варианты, последствия, рекомендацию, существенные неизвестные, версию рассматриваемых материалов, какие действия разрешаются и чего это решение не определяет.
Если человек уже ясно сказал «новая скидка действует только для будущих заказов», это фиксируется как решение о границе поведения. Повторно спрашивать то же самое не нужно. Если неизвестно, что считать будущим заказом (создание, оплата или подтверждение), модель исследует варианты и задаёт вопрос только об этой разнице.
Нужно различать два допуска:
- Право действовать: например, доверенная политика разрешает публикацию и merge определённого класса изменений после проверок.
- Правильность результата: конкретное изменение удовлетворяет контракту.
Действующий GRANT не делает ошибочную реализацию приемлемой. Одобрение бизнес-смысла само по себе не расширяет технические права инструмента.
Решение сохраняется с автором, временем, ID и хешем пакета, выбранным вариантом,
областью действия и заменяемыми решениями. Его нельзя получить простым
созданием моделью файла approved: true. Клиент, через который человек
отвечает, фиксирует реальное событие ответа; исполнитель проверяет его
происхождение и текущую применимость. В Git допустима читаемая проекция
такого события, но она не является самостоятельным источником полномочий.
Граница доверия
Для начала достаточно небольшого доверенного сервиса/CI-адаптера, отдельной учётной записи приёмки и хранилища событий; отдельная большая платформа не обязательна. Принцип обязателен: автор изменения не может тем же PR переписать действующие правила собственной приёмки или выдать себе доступ.
Проверка использует утверждённую версию политики из доверенного источника. Если PR меняет эту политику, новая версия является кандидатом и проходит отдельный ранбук изменения процесса. До её принятия действует прежняя версия. Публикация новой политики в основной ветке и её активация — разные события. Активация требует права по прежней политике и фиксирует точную версию. Смешанный PR с политикой и бизнес-кодом разделяется, если бизнес-части нужно разрешение, которое ещё только предлагается этим же PR. Привилегированные credentials не передаются процессу, который исполняет произвольный код проверяемого PR.
Файлы AGENTS.md и CLAUDE.md объясняют процедуру и навигацию. Это не
техническая блокировка действий. Документация Claude Code прямо различает
контекст и принудительные ограничения. См. проверенные источники.
Полномочия без постоянного участия человека
GRANT фиксирует проект, роль исполнителя, разрешённые действия, класс задач, область и исключения, риск, требуемые проверки, применимые версии ранбуков и политики, срок/условия окончания, отзыв и поведение текущих запусков.
Для повторяемой механики возможен ограниченный допуск на класс работ; для отдельного чувствительного действия — на точный кандидат. Нельзя определять низкий риск только количеством строк или маской каталога: одна строка проверки прав может менять доступ ко всем данным.
Перед внешним действием исполнитель вновь проверяет полномочие. Отзыв останавливает новые действия, а выполненные эффекты обрабатываются по ранбуку восстановления. Истечение срока не стирает историю, но запрещает использовать старое разрешение как действующее.
Адаптер определяет точку допуска действия и упорядочивает её с отзывом: отзыв, принятый раньше этой точки, блокирует действие; более поздний отзыв не отменяет уже допущенный внешний эффект задним числом. Для этого нужна сериализация/проверяемый протокол, а не только сравнение SHA веток. Если платформа оставляет окно отзыва, его границы явно входят в принятую политику.
Что считать достаточной автономностью
Автономность задаётся по паре «область × класс действий»: например, добавление проверок в известном домене уже допускается до merge, а изменение схемы данных пока требует решения перед выпуском. Это точнее одного глобального уровня зрелости всего репозитория.
Увеличивать автономность можно, когда реальные задачи показывают: контекст найден, критерии сформулированы, проверки ловят существенные ошибки, полномочия соблюдаются, прерывания восстанавливаются и человек не выполняет скрытую механику. Число успешных пилотов и допустимый остаточный риск устанавливаются до оценки, с учётом разнообразия задач.
В результате человек получает подготовленное решение, а не очередь команд «нажмите за меня». Но неоднозначный бизнес-смысл, конфликт интересов и изменение допустимого риска остаются поводами вернуть его в процесс.
2. Архитектура документации и поиск контекста
Минимальная структура
Документы, которые меняются вместе с кодом, удобно держать в том же репозитории. Большие доказательства, журналы исполнения и действующие полномочия могут находиться отдельно. В Git остаются их неизменяемые ссылки, хеши и проекции. Для нескольких репозиториев добавляется общий реестр контрактов и владельцев; локальные индексы продолжают работать без чтения всех соседних репозиториев.
AGENTS.md короткий вход для Codex
CLAUDE.md короткий вход для Claude Code
docs/
index.md откуда начать и как выбрать маршрут чтения
operating-model.md роли, состояния, точки решений
governance/ нормы процесса и проекции полномочий
domain/
glossary.md
context-map.md
<domain>/
index.md
rules/ требуемое поведение BR
observations/ фактическое поведение OBS
flows/ сквозные операции
states/ переходы и инварианты
examples/ проверяемые примеры
conflicts/ расхождения и неизвестное
architecture/
system-context.md
entrypoints/ HTTP, admin, команды, задачи, hooks
runtime-flows/
data/ модели, транзакции, миграции, владение данными
integrations/
operations/
guidelines/ текущая практика отдельно от нормы
decisions/ решения и их история
runbooks/ типовые процедуры RB
testing/ стратегия, baseline, данные, известные ограничения
changes/<change-id>/ контракт, влияние, карта контекста, приёмка
generated/ воспроизводимые индексы и проекции
onboarding/ воспроизведение среды и вход новой модели
migration/ план внедрения процесса и оценка пилотов
Это каркас, не требование заранее заполнить каждый каталог. Начните с одного пилотного домена. Создавайте документы по отдельным смысловым единицам; не дробите каждый абзац в файл ради формального типа. В одном обзоре могут соседствовать норма и наблюдение, если каждое утверждение явно типизировано и ссылается на свою каноническую запись.
Как выбирать единицу документации
- Правило: одно проверяемое условие или связанная группа инвариантов.
- Поток: один бизнес-результат от входа до эффектов и восстановления.
- Архитектурный контракт: одна граница, за которой меняются ответственность или гарантии — транзакция, очередь, API, файловое хранилище.
- Ранбук: повторяемая задача с собственными входами, результатом и поведением при сбое.
- Решение: один выбор с областью и последствиями.
Большой файл делится, когда его части независимо меняются, имеют разных владельцев или редко нужны вместе. Мелкие записи объединяются в обзор, если без него нельзя понять смысл связей. Размер в токенах — диагностический сигнал, а не универсальный норматив.
ID, ссылки, индексы
Используйте стабильный ID с типом и уникальным суффиксом, например
BR-orders-cancel-01J.... UUID/ULID или иной механизм без глобального
счётчика позволяет параллельным веткам создавать записи. CI проверяет
коллизии и типы. Имя файла может содержать короткий slug; ID не меняется
при переименовании и не используется повторно.
Основные ссылки — обычные относительные Markdown-ссылки с понятным текстом.
ID хранится в front matter и типизированных отношениях. Генератор строит
реестр ID → path, проверяет ссылки и обновляет их при перемещении.
Пользовательский синтаксис [[ID]] допустим как дополнительная проекция
для конкретного просмотрщика, но не обязателен для чтения документации.
Индексы строятся из метаданных, а не ведутся вторым независимым источником:
- Корневой индекс показывает домены, стартовые ранбуки и правила входа.
- Индекс домена показывает правила, потоки, незакрытые вопросы и связи.
- Индекс ранбуков позволяет выбрать процедуру по результату и риску.
- Машинный реестр хранит типизированные рёбра и обратные ссылки.
Канонические рёбра: implements, tested_by, observed_in, authorized_by,
depends_on, supersedes, conflicts_with. Обратные рёбра вычисляются;
две редактируемые копии одной связи быстро расходятся.
Минимальные метаданные
Для каждого типа определяется небольшая схема. Пример нормы:
id: BR-orders-cancel-example
kind: business_rule
revision: 1
lifecycle: active
normative_status: accepted
freshness: current
owner_role: orders_owner
scope: orders.cancellation
authority_ref: DEC-orders-cancellation-example
implementation: pending
relations:
implements: []
tested_by: []
Статус наблюдения содержит дополнительно метод, условия, снимок, версию анализатора и ограничения. Ссылка на код содержит repo, commit и symbol; номера строк служат вспомогательным адресом. Для изменившегося символа связь не считается актуальной только потому, что такой путь ещё существует.
Хеш всей схемы, автора и политики не нужно вручную вписывать в каждый файл. Генератор и исполнитель вычисляют технические поля; человек подтверждает смысл. Примеры полных карточек собраны в шаблонах.
Сборка контекста задачи
Сборщик начинает с контракта изменения и предполагаемой области воздействия. Он добавляет обязательные правила, бизнес-инварианты, актуальные решения, ранбук, зависимости и существенные неизвестные. Затем добавляет поясняющие наблюдения, примеры и историю по необходимости.
Результат — manifest с ID/версиями, снимком исходников, основанием включения, признаками устаревания, исключениями и причиной каждого исключения. Простой вариант — скрипт, обходящий структурированные ссылки и Git diff. Семантический поиск может находить кандидатов, но не является источником полномочий или доказательством полноты.
Обязательные нормы и неизвестные, способные изменить результат, нельзя удалять ради бюджета контекста. Если пакет не помещается: разделить задачу, собрать проверенную сводку с источниками или исполнить исследовательский ранбук. Низкая уверенность — повод сохранить предупреждение, а не спрятать его.
После обнаружения новой точки входа, обратного вызова, общей зависимости или интеграции модель расширяет impact map и пересобирает manifest. Проверяющий самостоятельно ищет соседние пути, а не доверяет только списку затронутых файлов автора.
Актуальность без циклических коммитов
Содержание нормы и наблюдения версионируется в Git. Результаты CI и текущая оценка актуальности для кандидата сохраняются как внешние attestation/report с хешами. Нельзя записать SHA коммита внутрь того же коммита как его самоподтверждение: запись изменила бы SHA.
Документ может ссылаться на проверку предыдущего снимка как на исторический
источник. Для текущего PR отдельный evidence manifest связывает неизменённые
материалы и результат. Производная панель состояния показывает актуальность,
не требуя коммитить новое verified после каждой проверки.
Изменения путей, символов, интерфейсов, схемы, зависимостей и конфигурации инвалидируют соответствующие доказательства. Граф сам может быть неполным: для общих компонентов, динамических путей и неизвестных зависимостей расширяют проверки, а периодические выборочные аудиты ищут пропуски.
Приёмка системы документации
Сборка из чистого снимка проверяет схемы, уникальность ID, существование файлов и якорей, типы связей, достижимость важных записей и воспроизводимость проекций. Отдельные проверки сопоставляют бизнес-примеры, нормы и поведение. Линтер ссылок не может доказать семантическую согласованность текста.
Каждый документ имеет владельца области и триггер обновления. Новая задача, инцидент, изменение кода, зависимостей или решения порождает проверку влияния. «У документа свежая дата» без источников и проверки не является свидетельством актуальности. Достаточность оценивается на задачах, как описано в главе об оценке.
3. Как извлекать бизнес-логику и устройство Django-проекта
Сначала воспроизводимый объект исследования
При переходе к живому репозиторию модель собирает паспорт: repo/revision, Python/Django и библиотеки, БД и расширения, broker/cache/storage, способы запуска, тестов и выпуска, настройки окружений, владельцев интеграций, источники бизнес-намерений. Укажите, какие сведения доступны только в runtime, какие конфигурации ещё не исследованы и какие системы не охвачены.
До исполнения неизвестного кода изучите команды запуска и инициализацию.
Импорт Django-приложения, AppConfig.ready() или management command могут
иметь побочные эффекты. Для динамической инвентаризации используйте
изолированную среду с синтетическими данными и без production-credentials.
Статический разбор также не безошибочен: у анализатора есть версия,
поддерживаемые конструкции и перечень неразрешённых связей.
Входы, работа, выходы
| Вход | Работа модели/инструментов | Выход |
|---|---|---|
| Исходники и конфигурации | Инвентаризация приложений, точек входа, способов записи | Реестры с координатами в конкретном снимке |
| История PR и инцидентов | Найти часто меняемые/опасные процессы и повторяемые задания | Кандидаты пилота и ранбуков |
| Тесты и инструкции запуска | Воспроизвести существующие проверки и ограничения | Baseline: passed/failed/not_run/flaky |
| Разрешённые примеры данных и интеграций | Проверить сценарии в изоляции | Наблюдения и границы эксперимента |
| Намерения человека | Выделить спорные бизнес-решения и уже данные ответы | Решения, неизвестное, порядок уточнений |
Критерий выхода: другой исполнитель может повторить получение карты и baseline; каждый существенный вывод имеет источник либо пометку неизвестности. Неполная карта с явными пробелами лучше вымышленной полной карты.
Минимальная карта входов, способов записи и обратных зависимостей пилота нужна уже на старте. Это может быть воспроизводимый поиск и небольшой реестр; дорогая платформа полного графа не обязательна. Анализ каждого изменения имеет независимый вход из кода, даже если все ссылки документации валидны. Импорты и статические вызовы дают кандидатов, но не гарантируют полноту динамических путей.
Инвентаризация технических аспектов
| Область | Что искать и документировать | Чем проверять |
|---|---|---|
| Запуск и конфигурация | WSGI/ASGI, middleware, settings variants, init, flags | Чистый запуск, реестр конфигураций, порядок инициализации |
| HTTP и интерфейсы | URL, views/viewsets, формы, сериализация, шаблоны, OpenAPI при наличии | Разрешение маршрутов, контракты запросов/ответов, негативные примеры |
| Бизнес-операции | Сервисы, методы моделей, managers, handlers, вычисления | Трассировка сценариев, decision tables, примеры и инварианты |
| Запись данных | ORM, raw SQL, bulk operations, admin actions, импорты | Реестр всех writers и обходов обычной валидации |
| Схема и совместимость | Ограничения, индексы, routers, multi-DB, миграции, исторические модели | Schema diff, прогон миграций, план совместимости версий |
| Конкурентность | Транзакции, locks, optimistic versions, unique constraints | Конкурентные тесты на существенных свойствах реальной БД |
| Неявные эффекты | Signals, save/delete overrides, callbacks, middleware | Статические кандидаты плюс динамическая проверка маршрутов |
| Фоновые циклы | Tasks, schedules, retries, deadlines, queues, deduplication | Тесты повторов, падения worker и доставки |
| Интеграции | API, webhooks, auth, timeouts, quotas, idempotency | Версии контрактов, sandbox/contract tests, отказ внешней стороны |
| Данные вне БД | Cache, files, search, exports, email | Инвалидация, восстановление и рассогласование копий |
| Доступ | Authentication, role/object/tenant filtering, admin и task access | Матрица actor × operation × object × tenant |
| Эксплуатация | Deploy, logs, metrics, traces, backups, restore, alerts | Rehearsal и evidence на каждой операции |
| Нефункциональные свойства | Latency, query budget, throughput, locale/time/money | Измерения и согласованные допустимые границы |
Не все строки применимы ко всем проектам. not_applicable нужно обосновать
по инвентаризации. Дополнительные механизмы проекта расширяют таблицу.
Извлечение бизнес-логики по потокам
Модель начинает с бизнес-результата: оформить заказ, назначить доступ, пересчитать баланс, импортировать данные. Для каждого потока она:
- Находит всех инициаторов и точки входа, включая admin, команды и workers.
- Выделяет участников, предусловия, источники данных и проверки прав.
- Строит состояния и переходы: допустимо/запрещено, инициатор, причина отказа.
- Выписывает правила расчёта, порядок операций и исключения.
- Отмечает транзакционные границы и внешние эффекты.
- Разбирает повторный вызов, конкурентный вызов и сбой между шагами.
- Сопоставляет чтение кода, тесты, документацию, историю и намерения.
- Создаёт наблюдения отдельно от нормы и предлагает проверяемые примеры.
Карточка правила содержит не только счастливый путь: границы времени, пустые значения, отрицательные/предельные суммы, округление и единицы, повтор, конфликт состояний, недоступность зависимости. Не относящиеся к правилу измерения отмечаются как неприменимые.
Пример decision table
Условная норма: отменять заказ может оператор своего пространства, пока передача исполнителю не зафиксирована.
| Роль/объект | Состояние | Событие | Требуемый результат |
|---|---|---|---|
| Оператор своего пространства | created | cancel | cancelled, один согласованный внешний эффект |
| Оператор чужого пространства | created | cancel | отказ без изменения данных |
| Оператор своего пространства | dispatched | cancel | отказ по бизнес-правилу |
| Оператор своего пространства | cancelled | cancel повторно | прежний результат, без нового эффекта |
| Разрешённый оператор | гонка cancel/dispatch | оба запроса | результат определяется утверждённой семантикой конкуренции |
Последняя строка не дополняется выдумкой модели. Если порядок приоритета ещё не решён, она становится предметом подготовленного выбора человека.
Три вида несогласованности
- Норма и код расходятся. Зафиксировать разницу, защитить нужное существующее поведение и выполнить ранбук приведения реализации к решению.
- Источники фактов расходятся. Сравнить снимки, настройки, входные данные и маршруты; провести воспроизводимый эксперимент.
- Намерение неоднозначно. Подготовить варианты с конкретными примерами. Человек выбирает смысл, после чего модель обновляет связанные записи.
Не каждый вопрос требует человека. Название файла, исправление ссылки, сбор отчёта и выбор команды по уже утверждённому ранбуку решает исполнитель. Неизвестные вопросы приоритизируются по влиянию на текущую задачу и риску; ненужные для решения пробелы сохраняются в backlog с владельцем.
Django-ловушки, которые должны попасть в гайд проекта
Справочник не заменяет обследование, но задаёт обязательные вопросы.
save()не вызываетfull_clean()автоматически; наличиеclean()не доказывает проверку всех writers. Django instancesQuerySet.update()обходитsave()и сигналы сохранения. Массовое удаление отличается по вызову методов и сигналов. QuerySeton_commit()не делает запись в БД и внешний вызов одной атомарной операцией. Для надёжной доставки может потребоваться outbox или иной согласованный протокол, с собственной проверкой. Transactions- Объектные права DRF требуют отдельного внимания к list/create и кастомным путям получения объекта. DRF permissions
- Миграции данных работают с историческим состоянием моделей; прямой импорт текущего класса может ломать повторное применение истории. Migrations
- Повтор задачи и подтверждение сообщения — часть контракта Celery, а не гарантия «ровно один раз». Celery tasks
Алгоритмы, циклы и практики
Карточка алгоритма: назначение; вход/выход; предусловия; шаги; инварианты; условие завершения; сложность и пределы; детерминированность; обработка ошибок; связи с данными, кодом и тестами.
Для цикла фиксируются начало, повтор, выход, лимиты, тайм-ауты и побочные эффекты. Ищите не только циклы импортов, но и сигнал → запись → сигнал, task → retry → task и webhook → API → webhook. Неразрешённое динамическое ребро остаётся явным пробелом, а не исчезает из красивой диаграммы.
Повторяющаяся практика в коде — кандидат на анализ, а не автоматически правило для будущего. Документируйте отдельно фактическую практику, рекомендованный путь, исключение и план устранения наследия.
Приёмка извлечённого знания
Независимый проверяющий получает утверждение, источники и контекст, ищет контрпример и обходные пути. Значимые утверждения переводятся в исполняемые проверки с отдельно установленным оракулом. Проверка текста другой моделью не доказывает бизнес-смысл и не заменяет эксперимент.
Готовность пилотной области означает, что для выбранных классов задач видны правила, основные пути и риски, есть основания приёмки и понятны непроверенные области. Это не заявление о полном документировании всего кода.
4. Ранбуки и выполнение задач
Как получить ранбуки из существующей работы
Соберите типы изменений из backlog, истории PR и инцидентов. Группируйте
по результату, предусловиям и риску, а не только по файлам. Добавление
поля без изменения семантики и преобразование исторических данных требуют
разных проверок, даже если оба меняют models.py и миграции.
Для каждого кандидата модель разбирает несколько примеров: повторяемые шаги, точки решения, обязательные проверки, сбои и ручную механику. Ранбук рождается из проверенного исполнения и сохраняет причины шагов. Не превращайте случайные привычки автора старого PR в обязательную норму.
На старте достаточно исследовательской процедуры и двух процедур: создание изменения и независимая приёмка. По накоплении различий выделяются специализированные ранбуки.
| Класс задачи | Что должно быть особенным в ранбуке |
|---|---|
| Исследование неизвестного | Вопрос, источники, эксперимент, границы вывода, без изменения продукта |
| Исправление дефекта | Воспроизведение, бизнес-оракул, regression test, причины и соседние пути |
| Изменение бизнес-правила | Намерение, совместимость, примеры до/после, версия нормы |
| Изменение API | Контракт, права, потребители, обратная совместимость, версия/депрекация |
| Схема и данные | Поддерживаемые исходные состояния, ограничения, блокировки, rollout/restore |
| Фоновая задача | Повторы, дедупликация, тайм-аут, delivery semantics, observability |
| Интеграция | Контракты, sandbox, credentials, отказ зависимости, компенсация |
| Рефакторинг | Явно неизменное поведение, characterization, сравнение критических свойств |
| Производительность | Baseline, нагрузка, ограничения ресурса и проверка семантики |
| Обновление зависимости | Lockfile, changelog, лицензия, совместимость, косвенные эффекты |
| Изменение знаний/ранбука | Происхождение, ссылки, обновление проекций, тест самой процедуры |
| Инцидент/восстановление | Ограниченные полномочия, стабилизация, доказательство восстановления |
Контракт ранбука
Обязательные поля: ID, версия, назначение, область, входы, предусловия, разрешённые инструменты/действия, состояния и переходы, проверки, выходные артефакты, лимиты, обработка ошибок, восстановление, точки решений. Подробные команды определяются после выяснения стека и сохраняются как проверенный адаптер; универсальное «выполни тесты» не является исполняемым шагом.
Пример перехода (предложенный контракт, а не установленный инструмент):
transition: verified_to_pr_created
requires:
- candidate_is_current
- prepublish_checkpoint_checks_completed
- publish_authority_is_applicable
operation: adapter.ensure_pull_request
operation_key: project/change_id/target_branch
inputs: [candidate_id, expected_head, expected_base, pr_body_digest]
outputs: [pull_request_id, url, observed_head, observed_base]
on_timeout: outcome_unknown
reconcile: adapter.find_owned_pull_request
retry: only_after_reconciliation
Здесь проверки checkpoint — установленный набор перед публикацией на текущем head. Он не заменяет полный набор приёмки результата интеграции: тот исполняется на соответствующем candidate core после определения точных head/base/result. Наличие PR не является техническим условием вычисления кандидата, но его публикация и приёмка имеют разные предусловия.
Ранбук содержит и смысл операции, и её техническое исполнение. У каждого адаптера определены параметры, credentials с минимальными правами, выходная схема, проверка результата и совместимые версии инструмента.
Цепочка типового изменения
- Intake. Сохранить намерение, границы, уже принятые решения и неизвестное.
- Research/context. Построить impact map, собрать manifest и baseline.
- Contract. Зафиксировать критерии поведения, ограничения и план проверок.
- Implement. Подготовить изолированный checkout, правку, тесты и документы.
- Verify. Проверить фактический diff, выполнить релевантные проверки.
- Publish. Создать логические коммиты, push, PR и evidence manifest.
- Accept. Независимо проверить текущий кандидат и полномочие действия.
- Merge/release. Исполнить разрешённую механику и проверить результат.
- Close/learn. Обновить связность знаний, статус задачи и кандидаты улучшений.
Это логическая цепочка, а не обязательные девять ручных approval. Переход между ранбуками автоматический, если все условия выполнены и новое решение не нужно. Иначе модель готовит конкретный выбор и ставит только зависимую ветку работы на ожидание.
Состояния и журнал
Минимальные состояния выполнения: prepared, running, waiting_decision, blocked, outcome_unknown, verified, completed, failed, cancelled. У каждого события есть run ID, step ID, actor, время, входные отпечатки, ожидаемое действие, фактический результат и внешние идентификаторы. Перед внешним эффектом записывается намерение операции, после — наблюдаемый результат. Текст чата не заменяет журнал.
Примеры блокеров: обязательный источник неизвестен, проверка не запустилась, кандидат изменился, отсутствует разрешение, несовместимая версия инструмента. Ожидание человека отличается от ошибки сети и от неизвестного результата внешнего действия: эти ситуации нельзя обрабатывать одной кнопкой retry.
Возобновление после прерывания
- Найти run ID, закреплённую версию ранбука и последнее подтверждённое состояние.
- Проверить, какие операции уже имели внешний эффект, и сверить их по стабильным ключам/идентификаторам с реальной системой.
- Сравнить working tree и ветку с сохранённым состоянием. Не сбрасывать посторонние или смешанные изменения. Сохранить копию и продолжить в отдельном checkout, если принадлежность правок не установлена.
- Для
outcome_unknownсначала запросить статус операции. Повтор разрешён только если доказана безопасность повтора или подтверждено отсутствие эффекта. - Перепроверить полномочия и актуальность входов. Отзыв может разрешать только безопасное завершение/компенсацию, а не продолжение исходной задачи.
- Выполнить следующий допустимый переход и записать его результат.
Имя ветки или текст в PR помогают поиску, но недостаточны для доказательства принадлежности: сверяются repository, branch, actor/run marker и ожидаемое содержимое. Редактирование кода моделью не объявляется идемпотентным само по себе. Повтор генерации должен сравниваться с сохранённой правкой.
Отсутствие объекта в одном ответе поиска не всегда доказывает, что создание не произошло: адаптер учитывает задержку видимости платформы. При нескольких подходящих объектах состояние остаётся неоднозначным. Сохраняется вся рабочая копия, включая untracked-файлы; одного diff-патча для этого недостаточно.
Для каждого внешнего эффекта в паспорте фиксируются: есть ли устойчивый ключ,
записанный до отправки; поддерживается ли дедупликация; можно ли запросить
фактический результат; есть ли компенсация и кто вправе её выполнить.
Если это неизвестно, нельзя обещать автономный retry. При потерянном ответе
шаг остаётся outcome_unknown; зависимая работа останавливается. Добавление
outbox/ключа в старый продукт является отдельным изменением со своей приёмкой.
Компенсация — тоже внешнее действие, а не безусловно безопасный rollback.
Новая версия ранбука не подменяет текущую незаметно. Совместимое обновление имеет явное отображение checkpoint; иначе запуск завершается по прежней версии либо останавливается согласно политике. Отзыв опасной версии может быть автоматическим событием по уже принятому решению, без нового approval.
Решения и эскалации
Человеку передаётся: что именно нельзя решить по действующим правилам, проверенные факты, варианты, последствия, рекомендация и область выбранного ответа. Обычные технические ошибки сначала обрабатываются ранбуком.
Пример хорошего пакета: «Новая скидка меняет сумму в уже оплаченных заказах. Действующее правило запрещает их перерасчёт. Предлагается применять только к новым заказам; альтернатива — отдельная миграция с компенсацией». Нужен выбор поведения. Подготовка миграции, отчёта и фиксация решения не перекладываются на человека.
Контроль стоимости и сложности
Лимиты времени, числа попыток, инструментальных вызовов и стоимости задаются в ранбуке/политике. Исчерпание лимита сохраняет состояние и причины; не превращает незавершённую задачу в успех. Модель может предложить меньшую область или иной инструмент, сохраняя критерии качества.
Добавлять workflow engine, очередь, векторный поиск или отдельную БД нужно, когда измерены соответствующие проблемы: потеря состояния, параллельные исполнители, долгие ожидания, сложные зависимости. До этого достаточно малого исполнителя с долговечным журналом и проверяемыми адаптерами.
5. Коммиты, PR и независимая приёмка
Подготовка изменения
До реализации создаётся контракт: цель, границы, намерение/решения, затронутые инварианты, критерии приёмки, совместимость, риск, проверки, rollout и восстановление. После исследования область может уточняться; существенное расширение возвращает задачу на оценку влияния и полномочий.
Автор работает в выделенной ветке/checkout. Перед коммитом он проверяет status/diff, явный список включаемых файлов, новые зависимости, миграции, обновления знаний и отсутствие случайных секретов/артефактов. Логические коммиты объясняют проблему и изменение поведения; один коммит на каждый механический шаг ранбука не обязателен.
Локальные hooks дают быстрый feedback. Обязательное условие приёмки дублируется в доверенном исполнении: часть hooks Git можно пропустить. Git hooks
Push и PR — самостоятельные внешние действия. Адаптер проверяет remote, ветку, target и права; сохраняет результат. При повторе используется уже созданный PR соответствующего запуска, а не публикуется дубликат.
Содержание PR
Пользовательское описание: проблема, итоговое поведение, важные ограничения, существенные риски, что проверено и что остаётся неизвестным. Техническое приложение: CHG, решения, кандидат, manifest контекста, версии ранбуков, список проверок и артефактов, порядок выпуска/восстановления.
Раздел «не проверено» содержит конкретную область, последствия и план. Его пустота не считается обещанием абсолютной полноты. Если проверка не применима, приводится основание. Если не запущена — это отдельный статус, а не отсутствие строки в отчёте.
Идентичность принимаемого кандидата
Создайте неизменяемый core:
repository identity
head SHA + target base SHA
merge strategy + candidate tree/commit
source/dependency/configuration/environment digests
test plan + test data + trusted runner configuration digests
acceptance contract version
trusted policy version + runbook versions
candidate_id = SHA256(canonical_json(core)). Канонизацию, типы и версии
схемы определяет адаптер; самовольное изменение сериализации создаёт новую
версию схемы. Evidence не входит в core и ссылается на candidate ID извне,
поэтому нет циклического вычисления хеша. Grant проверяется как отдельное
текущее условие действия и ссылается на свою версию и область.
Новый head, base или значимый вход создаёт нового кандидата. В первом варианте процесса обязательные проверки повторяются. Переиспользование результата допускается позже только по формальному правилу неизменности входов. Локальный успех на head не подтверждает автоматически merge result.
Для squash/rebase полученный commit может иметь другой SHA. Доверенный адаптер предпочитает идентифицировать содержимое через tree вместе с явно записанными head/base и стратегией. Если используется синтетический merge commit, адаптер сохраняет созданный объект для повторного использования: его метаданные могут менять SHA при одинаковом дереве. После squash/rebase доверенный merge-адаптер должен проверить соответствие дерева и необходимых родителей проверенному результату по выбранной стратегии. Это часть его контракта.
Версия применимой активной политики входит в core намеренно. Её смена консервативно создаёт нового кандидата и повтор обязательных проверок, даже если diff продукта тот же. Это принятая цена простого MVP. При разделении политики на области адаптер доказывает, какая версия применима к действию; автор PR не может объявить чужое изменение политики нерелевантным сам.
Что является доказательством
Минимальный EV содержит candidate ID, проверку и её версию, доверенного исполнителя, время, фактические входы, статус, число/набор выполненных тестов, выходные артефакты и их хеши. Обязательные поля зависят от вида проверки.
«Автор сообщил passed» не является EV. Доверенный сборщик получает сведения из CI/исполнителя, проверяет происхождение, полноту, привязку к кандидату и целостность артефактов. Крупные логи хранятся отдельно, но доступны для проверки в пределах принятой retention policy.
Хеш проверяет целостность, но не происхождение и не истинность отчёта. При экспорте сохраняется проверяемое основание доверия к producer: идентичность запуска/сервиса и аттестация по выбранному протоколу. Утраченные основания прошлой приёмки маркируются как недоступные; сама историческая запись о выполненной приёмке не переписывается.
Кандидат не коммитит собственный свежий статус verified: результат
вычисляется по внешним свидетельствам. В Git остаются нормы, тесты,
планы проверки и исторические ссылки. Подробности — в главе 2.
Независимая приёмка
Приёмочный исполнитель самостоятельно получает кандидат, контракт и действующие правила. Авторский отчёт используется как указатель, а не единственный источник фактов. Для снижения общего заблуждения проверяющий сначала ищет контрпримеры и пропущенные пути, затем сопоставляет своё заключение с авторским объяснением.
Независимость имеет несколько измерений: отдельные полномочия; защищённый источник политики; отдельный запуск проверок; самостоятельно собранный критический контекст; разные методы проверки. Другая модель полезна, но сама по себе не создаёт технической независимости.
| Условие | Результат приёмки |
|---|---|
| Обязательная проверка не исполнилась/набор пуст | blocked, если доверенное правило не доказало неприменимость |
| Проверка прошла на другом кандидате | blocked, причина stale_evidence; нужна актуальная проверка |
| Обнаружено нарушение бизнес-критерия | вернуть на реализацию |
| Есть фактологический спор | исследовательский ранбук |
| Нужен новый выбор поведения/риска | подготовленный пакет решения человеку |
| Всё подтверждено, полномочие применимо | разрешить следующее действие в пределах GRANT |
Финальный gate и merge
Gate проверяет: кандидат текущий; обязательный набор реально выполнен; результаты и происхождение валидны; существенные критерии закрыты; нет блокирующих конфликтов; требуемые решения относятся к нужному пакету; полномочие сейчас действует; есть доказанный механизм привязки merge к проверенным head/base/result.
Только после этого отдельный исполнитель выполняет условный merge или добавляет кандидата в корректно настроенную очередь. Изменение веток между проверкой и действием должно привести к отказу/перепроверке, а не к незаметной подмене. Если платформа или права не обеспечивают такую гарантию, этот режим автоматического merge пока недоступен.
GitHub предоставляет required checks, правила approvals и merge queue,
но общий зелёный индикатор недостаточен: допустимые для платформы
skipped/neutral не доказывают исполнение вашей обязательной проверки.
Проверяются также источник статуса и конфигурация защиты от обхода.
GitHub protected branches
Для GitLab проверяются соответствующие настройки MR approvals и запреты самоодобрения с учётом фактической версии/плана. Название функции платформы не заменяет теста отрицательного сценария. GitLab approvals
Изменение самой приёмки
PR, меняющий workflow, grant, схему evidence, правила тестового отбора или инструкции с исполняемыми полномочиями, проходит по прежней доверенной политике. Новая политика не может разрешить собственное принятие. Защищённые пути и отдельные роли — часть реализации; CODEOWNERS без проверки фактических прав и обходов нельзя считать достаточной защитой.
Код кандидата не исполняется с merge/production credentials. Проверяются пустые/пропущенные тесты, подмена workflow и источник отчёта. Сам policy-adapter имеет отдельные тесты допуска/отказа и процедуру выпуска.
Merge, выпуск и эксплуатационная приёмка
Merge подтверждает готовность интеграции кода. Выпуск требует отдельной проверки артефакта сборки, конфигурации, схемы и rollout. Эксплуатационная приёмка проверяет сигналы после выпуска: критические сценарии, ошибки, latency, очередь, данные и внешние эффекты по принятому контракту.
Одно решение может заранее разрешить цепочку этих действий в заданном классе. Если появляются новые последствия, модель готовит новый выбор, не перекладывая механику выпуска на человека.
Для доказательств назначаются срок хранения по риску и сроку эксплуатации, экспорт/резервная копия важных manifest и проверка восстановления. Удалённый CI-артефакт не считается доступным доказательством. Если свежий gate требует такое evidence, его восстанавливают или проверяют заново.
6. Система тестирования
Исходная линия
Первый прогон должен ответить: какие тесты существуют, какие обнаружены runner, что реально запускается, что падает, пропускается и зависит от среды. Сохраните версии, команды, конфигурацию, данные, длительность, число тестов и результаты. Команда с exit code 0 и нулём обнаруженных тестов не означает защищённость проекта.
Различайте неисправную среду, стабильный дефект, нестабильный тест и недостаток самой проверки. Все исходные падения не переводятся автоматически в карантин. Для исключения нужны идентичность сбоя, область, причина, владелец, срок, потерянная защита и решение по политике риска.
На новом кандидате сравнивается не просто число падений. Проверяются те же сбои и условия на baseline; новое или изменившееся падение не списывается на наследие без анализа.
Оракул: откуда берётся ожидаемый результат
Тест, написанный моделью по её же реализации, может закрепить ту же ошибку. Ожидание выводится из нормы, решения, независимого примера, внешнего контракта либо явно временной характеризации существующего поведения. В EV фиксируется, что именно проверено; в норме — почему это правильно.
Характеризующий тест полезен до изменения наследия, но не делает старый дефект желаемым поведением. Для изменения правила нужны примеры до/после, основание смены совместимости и оценка соседних потребителей. Ясное новое намерение не требует второго идентичного approval.
Матрица проверок
| Изменение/риск | Нужные проверки |
|---|---|
| Чистое вычисление | Границы, свойства, единицы/округление, исключения |
| Бизнес-переход | Decision table, инварианты, запрещённые переходы, повтор |
| Права/tenant | Роль × операция × объект × tenant, list/create/detail, обходные entrypoints |
| ORM/транзакции | Реальная существенная SQL-семантика, constraints, rollback/commit, конкурентность |
| API | Вход/выход, ошибки, права, совместимость клиентов, контракты |
| Фоновая задача | Повтор, падение worker, timeout, потеря/задержка ответа, deduplication |
| Интеграция | Contract/sandbox, недоступность, изменённый ответ, idempotency |
| Схема/данные | Граф и состояния миграций, инварианты, совместимость, блокировки, восстановление |
| Производительность | Baseline и измерение на репрезентативной нагрузке без регрессии семантики |
| Процесс разработки | Некорректный grant, stale evidence, поддельный passed, resume и отзыв |
Это выбор по риску, а не обязанность запускать все возможные виды тестов при каждой правке. Обоснование отбора сохраняется. Если граф влияния неполон или меняется общий компонент, набор расширяется.
Слои и скорость
Быстрые проверки помогают локальной итерации. На checkpoint выполняются обязательные проверки класса задачи. При приёмке запускается согласованный набор на реальном кандидате объединения; для опасных/широких изменений он может включать полный regression suite.
Не нужно повторять долгий полный прогон после каждого механического сохранения файла. Повтор оправдан новыми входами, изменениями, провалом или ещё не проверенным свойством. Кэш результатов допускается только с точной привязкой к неизменным входам и доверенной политике.
Django-специфика тестов
Для транзакций выбирайте подходящий механизм: проверка в обычном TestCase
и проверка реального commit/locking — разные эксперименты. Callback можно
исследовать через captureOnCommitCallbacks, но это не заменяет проверку
доставки задачи и внешнего эффекта. Django testing tools
Конкурентные тесты используют независимые соединения/исполнители и явную синхронизацию, а не случайные sleep. Среда должна сохранять существенные свойства production-БД; SQLite не объявляется эквивалентом другой СУБД для locks/constraints только потому, что тест быстро проходит.
Если проект использует Celery, eager/заглушка подходят для части проверок, но не подтверждают реальную очередь, подтверждение сообщения или сбой worker. Для таких свойств нужен отдельный интеграционный прогон.
Миграции данных
Проверяется не число файлов как универсальное правило, а ожидаемые операции и их эффект. Типовой набор:
- Модели и сохранённое миграционное состояние согласованы.
- Граф применим с поддерживаемых исходных состояний; чистая установка работает.
- На репрезентативных синтетических/обезличенных данных сохраняются нужные инварианты и выполняются новые ограничения.
- Старая/новая версия приложения совместимы с промежуточной схемой там, где rollout допускает совместную работу.
- Измерены время, locks, размер транзакции, ресурсы и поведение прерывания.
- Проверен обещанный путь восстановления, включая данные и внешние эффекты.
makemigrations --check --dry-run — полезная проверка несохранённых
изменений моделей в соответствующей версии Django. Она не доказывает
правильность миграции. Наличие reverse-функции не доказывает восстановление
утраченных значений. Для необратимого изменения нужны backup/restore,
компенсация или исправление вперёд с принятыми пределами восстановления.
Django migrations
Данные, нестабильность и чувствительность
Тестовые данные имеют назначение, generator/fixture version, seed и правила обезличивания. Нельзя подменять реалистичные крайние случаи случайным набором, который всегда удобен реализации.
Flaky test не становится надёжным после повторов до зелёного состояния. Сохраняются исходное падение и все попытки. Карантин ограничен сроком и явно показывает потерянную защиту. pytest flaky tests
Для критичных инвариантов выборочно внедряйте неверный вариант и проверяйте, что тест падает. Property/stateful testing помогает исследовать пространство входов и последовательностей, если оракул сформулирован независимо. Hypothesis stateful testing
Когда система тестирования достаточна
Относительно заданного класса задач: критические сценарии и риски названы; изменённое поведение защищено; тесты чувствительны к существенным ошибкам; прогоны воспроизводимы; известные потери защиты не скрыты; результаты связаны с кандидатом; среда и данные имеют понятные ограничения. Процент покрытия строк полезен для поиска пробелов, но не является разрешением на автономное изменение сам по себе.
7. Переход от текущего проекта к рабочему процессу
Нулевой запуск: что поручить модели в живом репозитории
Предоставьте путь и доступный снимок, исходное намерение, кто принимает доменные решения и какие действия уже разрешены. Остальные технические сведения модель должна попытаться собрать сама. Первый результат — паспорт проекта, воспроизводимый baseline и предложение пилота, а не массовая генерация тысяч описаний функций.
Исследуй указанный репозиторий и подготовь план внедрения LLM-разработки.
Сначала зафиксируй снимок, инструкции и способы запуска. Собери паспорт
стека, точек входа, бизнес-областей, тестов, CI и выпуска; отмечай источники
и пробелы. Предложи пилот по риску и частоте изменений. Не изменяй поведение
продукта в рамках обследования. Вопросы человеку задавай только там, где
нельзя установить факт исследованием или требуется выбор намерения/риска.
Этапы внедрения
| Этап | Что выполняют модели и инструменты | Решение человека | Выход и проверяемый переход |
|---|---|---|---|
| M0. Мандат | Подготовить цель, роли, начальные полномочия, варианты риска | Выбрать цель и пределы автономности | Версионированный мандат; исполнитель умеет отказать вне него |
| M1. Baseline | Воспроизвести среду, карту запуска/проверок и известные сбои | Выбрать пилот и значимые компромиссы | Другой исполнитель повторяет baseline; ограничения видны |
| M2. Знания пилота | Извлечь критические правила и пути, проверить противоречия | Разрешить только смысловые конфликты | Прослеживаются правило, код, пример и недостающая проверка |
| M3. Ранбуки | Выполнить изменение и приёмку в учебной/теневой среде | Утвердить границы процедуры и полномочий | Успех, отказ, прерывание и resume проверены |
| M4. Реальные задачи | Исполнить ограниченный класс задач и собрать evidence | Решать реальные исключения по действующей политике | Задачи закрываются без скрытой ручной механики; дефекты измерены |
| M5. Расширение | Сопоставить оценку с критериями, предложить новые области | Принять расширение/сохранение/сужение | Новая область допускается только при достаточных основаниях |
| M6. Сопровождение | Обновлять знания, проводить аудит, восстанавливать сбои | Менять намерения и допустимый риск | Процесс остаётся воспроизводимым на новых задачах |
Порядок логический, допускает обратные переходы. Нельзя пройти M2 по количеству написанных файлов и объявить M5 успешным по отсутствию жалоб. Испытания отказа должны показывать, что процесс умеет остановиться.
Минимальный пилот
Выберите один частый и ограниченный бизнес-сценарий, который достаточно представителен, но не требует сразу менять всю систему. Состав пилота:
- паспорт и baseline;
- краткий индекс, несколько критических правил и путей;
- контракт изменения и manifest контекста;
- ранбук исполнения, исследовательская ветка и независимая приёмка;
- ограниченное полномочие и работающий доверенный gate;
- внешние доказательства, журнал и восстановление прерванного запуска;
- набор реальных/учебных задач, включая негативные сценарии.
Автоматический merge допускается только там, где он уже разрешён и границы доказаны. Временная политика «человек решает по каждому PR» — возможный консервативный режим, особенно пока контроль платформы не готов. Она не является обязательной архитектурой универсального процесса. В обоих режимах модель готовит материал и исполняет решение.
Матрица допуска вместо глобальной автономности
Для каждой области и действия сохраняются: допустимый риск, уровень доказательств, действующий GRANT, ограничения, источник решения, результаты пилота и триггеры остановки. Например:
| Область | Действие | Текущее состояние |
|---|---|---|
| Пилотный модуль | Исправление известного дефекта до PR | Допущено по ранбуку |
| Тот же модуль | Merge изменения поведения | По конкретной политике допуска |
| Общая аутентификация | Новая семантика прав | Исследование и решение перед исполнением |
| Схема данных | Массовое преобразование production | Только после отдельного плана и права действия |
Это пример формата, а не решения по вашему проекту. Риск определяется эффектом изменения. Зависимость, тест или Markdown с инструкциями могут быть более опасны, чем большой локальный рефакторинг.
Совместная работа команды и моделей
Обычные разработчики и модели используют одинаковые контракты приёмки. Документация обновляется в том же change, где меняется смысл. У каждого домена есть владелец решений; у автоматизации — владелец обслуживания, прав и восстановления. Эти роли не означают ручное исполнение каждого шага.
Конкурентные изменения изолируются в ветках/checkout, объединение проходит через проверенный кандидат. Изменение общей нормы или интерфейса публикует событие инвалидации затронутых контекстов. Длительные задачи пересматривают актуальность перед следующими действиями, а не продолжают по памяти чата.
Замечания человека преобразуются моделью в кандидаты правил, примеров или единичных исключений. Не каждое замечание автоматически становится вечной нормой: сначала устанавливаются область и повторяемость.
Откат процесса
Триггерами могут быть нарушение полномочий, пропуск критического дефекта, неработающий отказ gate, потеря evidence или невозможность безопасного resume. Порог и действия задаются до запуска. Автоматическая остановка по заранее принятой политике — исполнение решения, а не новая выдуманная воля человека.
Останавливают конкретную затронутую возможность, если риск локализован. Новые действия блокируются; текущие внешние эффекты сверяются и безопасно завершаются/компенсируются. Код и данные восстанавливаются отдельными ранбуками; откат процесса сам по себе их не откатывает.
Сохраняется обычный путь работы с репозиторием и тестами. Для аварийного режима заранее определяются права, отчётность и последующая сверка знаний. Вернуть обычную разработку нельзя ценой потери истории решений и проверок.
Завершение миграции
Миграция считается завершённой для заявленных областей/классов, когда новая модель из чистой сессии может найти контекст, исполнить ранбук, пройти приёмку, восстановиться после сбоя и обновить знания без скрытых ручных операций. Известные ограничения перечислены; новые классы задач проходят собственный допуск. Абсолютная автономность всего будущего развития не является достижимым одноразовым состоянием.
8. Консистентность, достаточность и проверка самого процесса
Какие гарантии возможны
Можно технически гарантировать свойства в явно определённой границе: ID уникален в проверенном наборе; ссылка существует; действие без валидного GRANT не допускается данным исполнителем; evidence относится к кандидату; запись журнала не изменена по проверяемому протоколу.
Нельзя из этого вывести, что обнаружены все бизнес-правила, тесты ловят все будущие ошибки или модель всегда понимает намерение. Для этих свойств нужны эмпирическая оценка, независимые источники и явные ограничения. Универсальный гайд задаёт систему проверок, а не абсолютную гарантию.
Прослеживаемость
Для каждого значимого изменения должна восстанавливаться цепочка:
INT → DEC/норма → CHG → impact/context → RB run
→ code/tests/docs candidate → EV → acceptance
→ authorized action → observed result → обновление знаний
Из правила можно найти реализацию и проверки; из changed symbol — правила, потребителей и входы; из PR — намерение и доказательства; из инцидента — затронутую норму и причины, почему предыдущие проверки не обнаружили дефект. Исторические ссылки на заменённые решения разрешены, но не используются как действующая политика без проверки статуса.
Четыре слоя контроля
| Слой | Что обнаруживает | Чего не доказывает |
|---|---|---|
| Структурный | Broken links, duplicate IDs, schema/type errors, отсутствующие связи | Правильность смысла |
| Фактический | Несоответствие наблюдения коду/снимку/эксперименту | Желаемость старого поведения |
| Нормативный | Конфликт решений и требований, нарушение критериев | Полноту всех возможных намерений |
| Исполнительный | Неверные полномочия, stale candidate, подделанные проверки, нарушение перехода | Отсутствие неизвестных дефектов продукта |
Не заставляйте LLM быть единственным проверяющим всех четырёх слоёв. Детерминированные проверки выполняются программно, бизнес-конфликты решаются по иерархии решений, а модели помогают исследовать и объяснять.
Оценка на задачах
До прогона сформируйте development-набор для настройки и отдельный контрольный набор. Он должен представлять разрешаемые классы: локальная правка, междоменный эффект, права, данные, конкурентность, внешний эффект, прерывание и возобновление. Нет универсального числа задач, достаточного для любого проекта; расширение допуска ограничено реально испытанным классом.
Для каждой задачи заранее фиксируются поведенческие критерии, существенные инварианты и ограничения. Исполнитель получает допустимый снимок и контекст. Проверяющий оценивает поведение, регрессии, полноту evidence, соблюдение полномочий, нужные эскалации, время и расход. Одинаковый diff не требуется.
Историческая задача запускается на состоянии до решения без поздней документации и веток ответа. Реальное историческое решение раскрывается после независимой оценки и тоже может содержать ошибку. Для публичного проекта нельзя гарантировать отсутствие знакомства модели с историей; ретроспектива дополняется новыми задачами. Повторно использованный пример становится regression-тестом процесса, а не независимым испытанием.
Сохраняются все попытки и вмешательства человека. Нельзя выбирать лучший из десяти результатов и представлять его как обычный одиночный прогон. При малом backlog используйте учебные вариации и узкий допуск; не экстраполируйте три похожих успеха на весь проект.
Обязательные испытания отказа пилота
В отдельной учебной копии внедрите:
- Ложное бизнес-утверждение с правдоподобной ссылкой.
- Правку общей функции, затрагивающую неописанный admin/command-путь.
- Поддельный passed или evidence другого кандидата.
- Skipped/пустой/неполный обязательный тестовый набор.
- Новый head/base после проверок и отзыв GRANT в разные моменты допуска.
- Потерю ответа после создания PR с untracked/посторонними файлами в workspace.
- Потерю подтверждения внешнего эффекта и опасный повтор.
- Изменение политики, пытающееся активировать само себя.
Заранее опишите ожидаемую реакцию и какой механизм обязан сработать. Если дефект заметил только человек, это подтверждает полезность его проверки, но не готовность автоматического барьера. Непойманный значимый сбой блокирует расширение соответствующих полномочий. После исправления используйте новые контрольные варианты.
Метрики без подмены цели
Измеряйте успех задач по критериям, пропущенные дефекты по последствиям, возвраты приёмки, обнаруженные устаревшие знания, ручную механику, количество новых решений и повторных ненужных вопросов, стоимость, длительность и успешность восстановления. Для каждой метрики указывайте знаменатель, класс задач, период и ограничения выборки.
Снижение числа эскалаций полезно только если не растёт пропуск рисков. Рост числа страниц или тестов не означает рост качества. Порог расширения выбирается до измерения и меняется отдельным решением, а не под результат.
Поддержание актуальности
Каждое изменение проходит impact-анализ, а пропуски регистрируются как дефекты знаний/процесса. Периодический аудит смотрит участки, редко попадающие в задачи: legacy admin, batch jobs, runtime flags, обходные writers. Изменение модели/инструмента/системных инструкций также запускает регрессионную оценку процесса; прежний результат не переносится автоматически.
Критерий достаточности для конкретной задачи: известны необходимые нормы, существенные пути и неизвестные; критерии проверяемы; полномочия применимы; доказательства актуальны; восстановление предусмотрено; оставшийся риск укладывается в ранее принятые границы либо представлен человеку для решения.
9. Инструменты и минимальная реализация
Выбор по потребности
Не требуется заранее выбирать единую платформу для всех задач. Сначала выясняется стек проекта и существующие возможности, затем проверяются контракты адаптеров. Ниже — категории, а не обязательные новые зависимости.
| Потребность | Начальный вариант | Когда усложнять |
|---|---|---|
| Знания и review | Markdown/YAML в Git, обычный просмотрщик | Много репозиториев/типов связей — общий реестр |
| Поиск и impact | Поиск символов, импорты, регистрации, индексы | Измеренные пропуски/масштаб — AST/LSP/graph; semantic search для кандидатов |
| Извлечение runtime | Изолированное Django introspection и тестовая трассировка | Динамика требует покрыть больше конфигураций/процессов |
| Тесты | Существующий runner, Django tests/pytest по факту проекта | Свойства/состояния — property testing; критичные слабые проверки — mutation |
| Исполнение ранбуков | Небольшой runner, долговечный журнал, subprocess/API adapters | Долгие ожидания, concurrency, распределённость — workflow engine |
| Приёмка | Доверенная CI-конфигурация, отдельный gate/identity | Платформа не даёт нужные права/условные операции — отдельный сервис |
| Доказательства | CI artifacts + экспорт важных manifest | Долгий аудит/смена платформы — независимое объектное хранилище |
| Работа моделей | CLI/SDK с зафиксированными моделями и правами | Оркестрация нескольких ролей, оценка и учёт затрат |
Точные версии и доступность функций проверяются по официальной документации фактического окружения. В универсальном гайде нельзя обещать единую готовую команду Django для экспорта абсолютно всех бизнес-связей, сигналов и динамики — такой результат требует нескольких методов и явной оценки неполноты.
Контракты четырёх обязательных адаптеров
Policy / approval
Вход: субъект, действие, объект/кандидат, контекст, версия действующей политики. Выход: allow/deny/waiting_decision, основания, область и версия GRANT, момент допуска и audit event. Источник решения и политики защищён.
Проверки: поддельное/чужое решение, истёкший/отозванный grant, саморазрешение в PR, несоответствие роли, публикация политики без активации. Отзыв и допуск упорядочены по документированному протоколу. Недоступность обязательного источника не превращается в allow.
CI / evidence
Вход: candidate core и доверенный verification plan. Выход: manifest фактических запусков, результатов, попыток и артефактов с происхождением. Runner исполняет кандидат изолированно; привилегированный сборщик не доверяет произвольному JSON, который записал этот же кандидат.
Проверки: чужой candidate ID, ложный producer, неправильный hash, неполный набор, пустые tests, skipped, потеря артефакта, прерванный запуск. Состав/смысл тестов важнее только счётчика: один нерелевантный тест не заменяет удалённый обязательный набор.
Merge / release
Вход: принятый кандидат, ожидаемые head/base/result и актуальный допуск. Выход: конкретный внешний ID/commit/artifact, подтверждённое содержимое, время и результат действия. Право записи принадлежит отдельному исполнителю.
Проверки: сдвиг head/base, другая merge strategy, подмена workflow, отзыв до точки допуска, повтор операции, потерянное подтверждение. Одна кнопка человека не компенсирует отсутствие правильного технического барьера. Если enforcement не прошёл проверку, соответствующая автоматическая операция не допускается.
Resume / reconciliation
Вход: run ID, журнал, закреплённые версии, известные объекты и workspace. Выход: восстановленное состояние либо конкретный unknown/blocked. Сохраняются tracked, untracked и чужие правки. Побочные эффекты сверяются по идентичности; отсутствие ответа не равно отсутствию операции.
Проверки: crash в каждой границе до/после эффекта, два параллельных resume, посторонняя правка, конфликт PR, отозванный ранбук, недоступный provider. Для параллельного исполнения нужен lease/lock с документированной семантикой, чтобы два runner не выполнили одно действие независимо.
Истёкший lease не останавливает старый процесс физически. Передача владения использует проверяемое поколение владельца (fencing token), сериализованный посредник или иной испытанный механизм, который отвергает поздний вызов прежнего владельца. Проверка включает паузу старого runner, передачу lease и его последующее пробуждение перед внешним эффектом.
Порядок сборки MVP
- Зафиксировать схемы CHG, RB, candidate, EV, DEC/GRANT.
- Реализовать чтение/валидацию и построение manifest без побочных эффектов.
- Подключить проверенный запуск существующих тестов и запись evidence.
- Подключить операции Git/PR с устойчивыми ID и reconciliation.
- Подключить доверенный policy/approval и отдельную приёмку.
- Прогнать положительные и отрицательные испытания адаптеров.
- Разрешить узкий класс внешних действий и пройти пилот.
До подключения рабочего policy-адаптера внешние операции выполняются в учебной среде с ограниченными credentials либо в пределах технически обеспеченного начального мандата. Порядок списка не разрешает сначала действовать без права, а затем добавлять контроль.
| Шаг | Критерий выхода |
|---|---|
| 1. Схемы | Обязательные поля, статусы, связи и версии определены; примеры валидны |
| 2. Чтение | Один и тот же снимок даёт воспроизводимый manifest; missing/конфликт не скрыт |
| 3. Тесты | Подтверждены фактический набор, входы и producer; пустой/чужой отчёт отвергается |
| 4. Git/PR | Подтверждён внешний объект; тайм-аут и повтор не создают дубликат и не теряют файлы |
| 5. Политика | Чужое, истёкшее и отозванное право отвергается; кандидат не активирует своё разрешение |
| 6. Испытания | Каждый внедрённый сбой остановлен ожидаемым механизмом, результат сохранён |
| 7. Пилот | Заданные критерии класса выполнены на контрольных задачах; ограничения и область допуска приняты |
Названия операций в примерах гайда — проектируемые интерфейсы; файлы руководства сами их не устанавливают. Конкретный код адаптеров и CI создаётся на этапе живого репозитория.
Сопровождение и пропущенные аспекты
Нужны владельцы процесса и доменов, журнал версий инструментов/моделей, доступы и секреты, ограничение расходов, резервирование журнала, проверка восстановления, observability, лицензии зависимостей и политика данных. Документация и правила самих агентов обновляются через тот же контролируемый процесс; инструкции в issue, логах и внешних материалах не выдают новых прав.
Release evidence должен переживать удаление ветки. Экспорт содержит контрольные суммы и происхождение записей, а восстановление проверяется на отдельном экземпляре. Переезд на другой provider требует перепроверки семантики API, прав и статусов, а не только замены URL.
10. Сквозные примеры
Все названия, правила, значения и идентификаторы ниже учебные. Они показывают механику будущего процесса и не описывают обследованный проект. Короткие ID используются для чтения; реальные документы получают устойчивые UUID/ULID.
Сценарий A. Новое правило отмены заказа
Человек: «Разрешить покупателю отменять неоплаченный заказ до передачи в сборку. Оплаченные заказы и возвраты не затрагивать». Предположим, его роль позволяет принимать это бизнес-решение; действующая политика разрешает исследование, реализацию и публикацию PR, а автоматический merge этого класса уже проверен.
| Шаг | Действия модели и инструментов | Артефакт и условие перехода | Участие человека |
|---|---|---|---|
| Намерение | Сохранить точный текст, автора, область и исключения | INT-17, DEC-12: разрешённая смена поведения | Исходное решение уже дано |
| Исследование | Найти API, admin, workers, импорты, прямые update, писателей статуса и оплаты | OBS-31, entrypoint/writer map, baseline | Не требуется |
| Правило | Описать состояния, акторов, предикат отмены и конкурентную оплату | BR-08: примеры, запреты, источник решения | Только если намерение не определяет важное поведение |
| Контракт | Связать rule, context manifest, impact map и тестовые обязательства | CHG-42: границы, проверка гонок, сохранность истории | Не требуется |
| Реализация | Обновить фактическое место проверки инварианта и все обходные входы | Изменение кода, тестов и документов в отдельном checkout | Не требуется |
| Проверки | Воспроизвести старое поведение, выполнить новый oracle и конкурентный тест | Evidence по актуальному кандидату | Не требуется |
| PR | Создать коммиты и PR, сохранить внешнюю идентичность | PR-71, candidate K1, неизменяемые CI-артефакты | Не требуется |
| Приёмка | Независимо сверить намерение, пути, права, тесты и grant | Acceptance record с результатом gate | Не требуется при выполнении политики |
| Merge и закрытие | Допустить действие на K1, исполнить, проверить дерево и статус | Merge receipt, обновлённые проекции и журнал | Не требуется |
Критическая находка: статус оплаты записывается отдельным процессом, а отмена проверяет только устаревшее поле заказа. Модель исследует существующую транзакционную границу и выбирает техническую защиту в рамках принятого инварианта. Если две операции требуют нового бизнес-правила приоритета, она формирует один decision packet: варианты, последствия, рекомендация. Вопрос «можно продолжать?» не нужен.
Пример обязательств приёмки: свой заказ можно отменить в разрешённом состоянии; чужой нельзя; оплаченный нельзя; сборка не начинается для отменённого; конкурентные оплата/отмена сохраняют согласованный инвариант; повтор запроса не повторяет внешний эффект. Точные блокировки и ограничения определяются после изучения БД и путей записи, не угадываются из названия Django.
Если во время проверки появился новый commit, K1 становится недостаточным для нового merge. Строится K2, пересчитывается impact и повторяются обязательные проверки. Ранее принятое намерение остаётся действующим: пересогласовывать бизнес-решение из-за нового SHA не требуется.
Сценарий B. Миграция без потери исторических данных
Человек решил разделить одно состояние заказа на два, не изменяя смысл уже завершённых операций. Модель сначала строит распределение исходных состояний на разрешённой обезличенной копии и находит записи, которые нельзя однозначно классифицировать. Это неизвестное бизнес-значение, а не ошибка генератора миграций.
Пакет решения содержит размеры групп, причины неоднозначности, варианты «сохранить legacy», «вывести на отдельную классификацию», «применить правило X» и последствия. Человек выбирает правило для неоднозначной группы. Модель фиксирует решение и выполняет всю последующую механику:
- Создаёт совместимое расширение схемы и переходный путь чтения/записи.
- Готовит повторяемый backfill с checkpoint, предельным временем и мониторингом.
- Проверяет historical models, поддерживаемые исходные версии, объём, блокировки и конкурирующие записи. Сравнивает количества и бизнес-инварианты до/после.
- Репетирует остановку и продолжение, совместимость старой и новой версии, восстановление данных по реально доступной процедуре.
- Публикует последовательность PR/релизов и отдельные evidence каждого кандидата.
- После разрешённого выпуска проверяет результаты; удаление старого поля выполняет только после прохождения согласованного окна совместимости.
Наличие reverse-функции не закрывает вопрос восстановления. Если откат кода не возвращает преобразованные данные, план отдельно описывает restore или корректирующую миграцию. Решение о допустимом простое/потере данных принимается человеком при необходимости; команды, репетиции и отчёты выполняются системой.
Сценарий C. Тайм-аут публикации PR и смешанная рабочая копия
Исполнитель отправил запрос создания PR, но не получил ответ. Одновременно в его старой папке появились чужие изменения и новый untracked-файл.
Состояние шага — outcome_unknown. Система сохраняет рабочую копию целиком,
получает исключительное право возобновления этого run и сверяет операцию по
repository, branch, run identity и содержимому. Если PR найден однозначно,
она сохраняет его ID и проверяет фактические head/base. Если поиск временно
пуст, учитывает окно видимости сервиса. Если найдено несколько кандидатов,
не выбирает произвольный и не создаёт ещё один.
Новая попытка идёт в отдельном checkout. Посторонние изменения остаются
сохранёнными; автоматический reset --hard не является процедурой восстановления.
Если grant отозван до точки допуска публикации, новый внешний вызов запрещён.
Уже созданный PR не исчезает от отзыва: дальнейшая обработка следует ранее
разрешённой процедуре. Закрытие или компенсация тоже требуют применимого права.
Человек подключается только когда ранбук не может разрешить существенную неоднозначность или нужен новый выбор. Сеть, поиск, сохранение файлов, восстановление checkpoint и подготовка вариантов остаются механикой системы.
Сценарий D. Изменение документации меняет полномочия
PR назван «обновление документации», но меняет правило отбора тестов и список действий, разрешённых агенту. Impact-анализ классифицирует его по последствиям. Он проходит прежнюю доверенную политику. Автор не может принять собственное расширение полномочий, сославшись на новый текст внутри PR.
Публикация версии политики, её проверка и активация фиксируются отдельно. Если бизнес-правка в том же PR требует новых полномочий, изменения разделяют или откладывают зависимую часть. Человеку нужен выбор только там, где действующая политика не уполномочила такую смену. Никакой тип файла не делает изменение автоматически малорисковым.
Приложение A. Рабочие шаблоны
Это контракты для адаптации к репозиторию, а не установленная схема данных.
Модель заполняет их по источникам. <...> означает отсутствующее значение;
проверка готовности запрещает такие placeholders в обязательных полях.
Короткие ID учебных примеров не заменяют реальные устойчивые идентификаторы.
Неизвестное отмечается явно вместе с последствиями и способом проверки.
A1. Паспорт проекта и карта обследования
schema_version: 1
project_id: <stable-id>
snapshot:
repository: <verified-identity>
revision: <commit>
dirty_state: <none-or-saved-manifest>
stack:
python: <verified-version>
django: <verified-version>
database: <engine-version-and-isolation>
workers: <engine-version-delivery-settings-or-none>
dependencies: <lockfile-and-digest>
environment:
bootstrap: <verified-adapter>
test_data: <approved-fixture-or-dataset-ref>
external_effects: <sandbox-and-egress-policy>
inventory:
entrypoints: <manifest-ref>
writers_and_readers: <manifest-ref>
integrations_and_effects: <manifest-ref>
deployments_and_jobs: <manifest-ref>
owners_and_authority: <registry-ref>
baseline:
tests: <evidence-ref>
known_failures: <list-ref>
unknowns: <list-ref-with-consequences>
Для каждого внешнего эффекта: операция, вызывающие пути, область данных, ключ до вызова, дедупликация, запрос статуса, окно видимости, тайм-аут, компенсация, полномочие, тест безопасного resume. Значение «неизвестно» запрещает обещать безопасный повтор соответствующего эффекта.
A2. Наблюдение о текущем поведении — OBS
ID: <stable-id>
Lifecycle: draft | active | retired
Kind: observation
Source revision: <commit>
Evidence: <code-symbols, experiment, logs, interview>
Freshness: current | suspect | stale | unknown
## Наблюдение
Что фактически делает система и при каких условиях.
## Охват
Проверенные входные точки, состояния и исключённые области.
## Уверенность и неизвестное
Что наблюдали непосредственно, что вывели, что ещё может опровергнуть вывод.
## Связи
Правила, операции, тесты, конфликты и владельцы решения.
OBS не становится бизнес-требованием только потому, что код так работает. Для повторения эксперимента сохраняются команда/адаптер, входные данные и окружение. Секреты и необезличенные данные в Markdown не попадают.
A3. Бизнес-правило — BR
ID: <stable-id>
Kind: business_rule
Lifecycle: draft | active | retired
Normative status: proposed | accepted | superseded
Authority: <authorized-decision-ref>
Freshness: current | suspect | stale | unknown
Owner role: <role>
## Правило
Для какого актора, объекта и состояния что разрешено/обязательно/запрещено.
## Инварианты и исключения
Предикаты, конкурентные события, временные границы и допустимые исключения.
## Таблица решений
Входы → ожидаемое поведение → пример → проверка.
## Реализация
Все известные входные точки и места обеспечения правила; обходные писатели.
## Источники и конфликты
Решение, наблюдения, прежняя версия, несовпадения факта и намерения.
## Проверки и изменение
Тестовые обязательства, влияние изменения и условие пересмотра.
Мини-пример таблицы для BR «отмена заказа»:
| Актор / состояние | Ожидаемое поведение | Проверка |
|---|---|---|
| Владелец / неоплачен / не в сборке | Отмена разрешена | Основной сценарий |
| Другой покупатель / те же состояния | Отказ без изменения объекта | Изоляция прав |
| Владелец / оплачен | Отказ | Запрет изменения оплаченного |
| Оплата и отмена одновременно | Согласованный инвариант, без двойного эффекта | Конкурентный сценарий на целевой БД |
Конкретный результат последней строки должен быть определён действующей нормой или решением до реализации; слово «согласованный» не заменяет oracle.
A4. Архитектурный поток и ADR
Для потока фиксируются: trigger, актор/права, входы, шаги и ветвления, читаемые/изменяемые данные, транзакционные границы, асинхронные переходы, повторы/дедупликация, внешние эффекты, конкурентные писатели, ошибки, наблюдаемость, нагрузочные ограничения, тесты и известные обходы.
Для алгоритма добавляются предусловия, постусловия, состояние, завершение, сложность, граничные случаи, детерминизм и причина выбора. Для цикла зависимостей указывается вид: импортный, вызовов, бизнес-процесса, событийный; критерий допустимости и способ обнаружения регрессии.
ADR хранит контекст, решение, рассмотренные варианты, аргументы, последствия, область действия, authority и условие пересмотра. Извлечённое из кода решение без подтверждённого происхождения помечается реконструкцией, не историческим фактом.
A5. Контракт изменения — CHG
change_id: <stable-id>
intent: <exact-intent-ref>
decisions: [<decision-ref>]
goal: <observable-result>
scope:
included: [<behavior-or-component>]
excluded: [<explicit-boundary>]
impact:
rules: [<rule-ref>]
entrypoints: [<entrypoint-ref>]
writers: [<writer-ref>]
dependencies: [<dependency-ref>]
uncertainty: [<unknown-with-consequence>]
acceptance:
obligations: [<condition-with-oracle-and-check>]
compatibility: [<required-compatibility>]
nonfunctional: [<measurable-bound>]
risk: <semantic-class-and-rationale>
context_manifest: <versioned-ref>
runbooks: [<id-and-version>]
test_plan: <versioned-ref>
rollout: <plan-ref-or-reason-not-applicable>
recovery: <tested-plan-ref-or-explicit-gap>
authority: <applicable-policy-and-grant-ref>
Изменение scope фиксируется в журнале и пересчитывает impact. Модель не должна сохранять прежний класс риска лишь для прохождения gate.
A6. Пакет решения и ограниченное полномочие
Decision packet: вопрос о поведении или последствиях; уже известное намерение; почему действующих решений недостаточно; факты и неизвестное; варианты; рекомендация; область, срок и последствия выбора; что система сделает после него.
Запись решения: точная формулировка выбора, кто вправе его принять, источник
ответа, время, область, связанные нормы, что заменено и условие пересмотра.
Обязательная привязка: decision_packet_id, decision_packet_digest и ссылка
на аутентифицированное событие ответа. Для исходного однозначного поручения
пакетом может быть само сообщение с неизменяемым ID и отпечатком, без
искусственного повторного согласования.
Если исходное сообщение уже однозначно решает вопрос в пределах полномочий,
модель оформляет запись без повторного approval.
grant_id: <stable-id>
version: <immutable-version>
issued_under: <trusted-policy-version>
decision: <authorized-decision-ref>
subject: <executor-identity-or-role>
scope:
project: <verified-identity>
action: <one-action-or-explicit-action-set>
change_class: <semantic-class>
target: <branch-environment-data-boundary>
conditions: [<required-gates>]
validity: <expiry-or-explicit-valid-until-revocation>
limits: <impact-cost-concurrency-limits>
revocation: <trusted-registry-and-ordering-contract>
admission: <where-live-authority-and-candidate-are-checked>
Одна запись может разрешать класс однотипных действий, если это прямо выбрано. Она не даёт общий доступ ко всем окружениям. Расширение scope не наследуется автоматически. Текст grant в непроверенном PR не активирует полномочие.
Запись активации политики содержит: activation ID; новую версию и digest; прежнюю активную версию, по которой разрешена активация; применимое решение и полномочие; субъект; область; точку упорядочивания/время; что заменено; результат и receipt доверенного исполнителя. Недоступность реестра не означает активацию. Начальная политика получает явный bootstrap-мандат, а не одобряет себя отсутствующей предыдущей версией.
A7. Context manifest
manifest_id: <stable-id>
task: <change-id>
snapshot: <revision>
mandatory:
- ref: <rule-policy-intent-or-contract>
version: <version-or-digest>
reason: <why-required>
supporting: [<source-refs>]
conflicts: [<refs-and-resolution-state>]
unknowns: [<question-consequence-resolution>]
impact_basis: [<entrypoints-reverse-deps-writer-search-evidence>]
excluded:
- ref: <nonmandatory-source>
reason: <why-outside-scope>
budget: <context-budget-and-splitting-plan>
Обязательные нормы и существенное неизвестное не отбрасываются из-за лимита контекста. Область делится; проверенное сжатое представление сохраняет ссылки, версии, оговорки и возможность открыть источник.
A8. Ранбук и checkpoint
runbook_id: <stable-id>
version: <immutable-version>
purpose: <result>
inputs: [<typed-ref>]
preconditions: [<check>]
allowed_actions: [<authority-bound-action>]
transitions:
- id: <step-id>
from: <state>
requires: [<predicate>]
operation: <verified-adapter-with-typed-inputs>
before_effect: <durable-intent-and-operation-key>
outputs: [<artifact-or-external-id>]
verify: <result-check>
on_unknown: <reconciliation-procedure>
on_failure: <bounded-recovery-procedure>
next: <state>
decision_points: [<condition-and-decision-packet>]
limits: <attempt-time-cost>
completion: <verifiable-result>
Checkpoint содержит run/step ID, версию ранбука, event sequence, owner/lease, snapshot входов, workspace manifest, operation key, известные внешние ID, последний подтверждённый результат и следующий допустимый переход. Он не должен хранить credentials. Lease и CAS дополняются защитой от позднего вызова прежнего владельца после передачи lease: проверяемым поколением владельца или сериализованным посредником. Два параллельных resume и пробуждение старого runner должны быть испытаны; одного факта истечения lease недостаточно.
A9. Candidate core и evidence
{
"schema_version": 1,
"repository_id": "<verified-identity>",
"head_sha": "<sha>",
"base_sha": "<sha>",
"merge_strategy": "<verified-strategy>",
"candidate_tree": "<tree-or-merge-commit>",
"source_digest": "<digest>",
"dependency_digest": "<digest>",
"configuration_digest": "<digest>",
"environment_digest": "<digest>",
"test_plan_digest": "<digest>",
"test_data_digest": "<digest>",
"trusted_runner_configuration_digest": "<digest>",
"acceptance_contract_version": "<version>",
"trusted_policy_version": "<active-version>",
"runbook_versions": ["<id@version>"]
}
candidate_id = SHA256(canonical_json(core)); контракт адаптера фиксирует
канонизацию. Изменение значимого входа создаёт новый core. Никакой evidence
или собственный хеш внутрь core не добавляется.
Evidence manifest содержит candidate ID, check ID/version, producer identity,
проверяемое основание доверия к producer и конфигурации, фактические входы,
время, статус, exit code, выбранные/собранные/исполненные тесты, обоснованные
skip, все попытки, ссылки и хеши логов/отчётов, срок хранения. Файл, созданный
автором PR, становится лишь заявлением автора, пока доверенная система не
проверила происхождение. Ссылки на защищённый storage и подписи выбираются
по модели угроз; само наличие поля producer не является проверкой.
A10. PR, приёмка и receipt действия
PR для человека:
## Проблема и результат
Что происходило и как изменилось наблюдаемое поведение.
## Область и последствия
Совместимость, данные, внешние эффекты, существенные ограничения.
## Проверка
Что проверено, результат, ссылки на доказательства; что не проверено и почему.
## Выпуск и восстановление
Нужные действия и проверенные условия их применения.
## Технические ссылки
CHG, правила/решения, candidate, context manifest, runbook, evidence.
Acceptance record: независимый reviewer/runner; candidate ID; обязательства контракта; проверка intent и authority; findings с важностью и доказательствами; результат каждого gate; известные ограничения; решение accept/reject/blocked; время. Модель пишет семантическое заключение, доверенный gate разрешает действие.
Admission receipt: конкретное действие, candidate, активная policy, версия grant, порядок относительно revocation, момент допуска и вызывающий субъект. Completion receipt: внешняя операция, фактический результат, head/base/tree или deployment identity, доказательство сверки и состояние при неоднозначности. Они различают «действие допущено» и «результат подтверждён».
A11. Карточка пилота и готовность класса задач
Класс и границы: <semantic-scope>
Действия, которые предлагается автоматизировать: <actions>
Набор задач: <development-set and unseen-holdout-set>
Baseline: <manual/current-process evidence>
Оракулы: <who/what establishes expected behavior>
Выпуски адаптеров: <policy, CI evidence, merge, resume>
Нормальные сценарии: <expected/actual/evidence>
Внедрённые сбои: <expected gate / actual gate / evidence>
Человеческие решения и ручная механика: <separate counts and causes>
Дефекты/инциденты/восстановление: <all outcomes>
Время/стоимость: <total and distribution with sample size>
Нерешённые ограничения: <consequence and owner>
Вердикт по каждому действию: <ready / limited / not-ready>
Разрешённая область и условие отзыва: <decision/policy/grant>
Число задач, доля успеха и допустимый риск выбираются под класс, а не берутся из универсального магического процента. Все попытки остаются в знаменателе соответствующей метрики. После исправления обнаруженной слабости добавляют новые скрытые случаи, иначе повторный успех может отражать подгонку.
Решения синтеза и границы согласия
Это вывод координатора по реальным ответам Astra и Fable, а не дополнительные решения пользователя о конкретном репозитории. Все оригиналы сохранены в реестре раундов.
Согласованные пользователем принципы
Универсальная концепция предшествует обследованию живого репозитория. Человек задаёт намерения и принимает необходимые решения. Модель сама готовит, исполняет, проверяет и фиксирует механику. Принятые решения используются повторно. Инструменты выбираются по потребностям. Потолок — 6 содержательных раундов, структура этапов адаптивная.
Рекомендуемый результат дебатов
| Решение | Основание и отклонённая альтернатива |
|---|---|
| Связать знания, ранбуки, полномочия и evidence | Одни Markdown-инструкции не обеспечивают исполнимость и контроль |
| Разделить намерение, норму, наблюдение и доказательство | Текущее поведение и зелёный тест не определяют желаемое бизнес-поведение |
| Канонические Markdown + небольшие метаданные + генерируемый индекс | Жёсткая папка для каждой сущности и wiki-only связи затрудняют переносимость и эволюцию |
| Устойчивые ID без общего счётчика | Параллельные изменения не должны бороться за следующий номер |
| Собирать контекст от задачи и независимо проверять impact по коду | Существующий граф ссылок не видит собственных пропусков; векторный поиск не обеспечивает обязательный контекст |
| Сохранять существенные неизвестные и противоречия | Отбрасывание слабоуверенных сведений из-за бюджета скрывает риск |
| Доверенная политика вне контроля принимаемого кандидата | PR не должен менять требования к собственной приёмке или активировать новые права |
| Внешнее неизменяемое evidence по candidate core | Запись доказательства собственного SHA в том же коммите создаёт цикл |
| Проверять head, base, результат интеграции и значимые входы | Проверка только head не покрывает изменение базовой ветки и окружения |
| Повтор внешнего действия через reconciliation | Тайм-аут не означает отсутствие эффекта; сброс рабочей копии теряет чужие файлы |
| Отдельно тестировать policy, evidence, merge и resume | Связный текст процедуры не доказывает работоспособность механизма |
| Автономность расширять по испытанным классам и действиям | Общий флаг «проект автономен» скрывает различия риска и непроверенные операции |
Существенное разногласие
Fable рекомендует ручное решение по каждому pilot PR до подтверждения четырёх адаптеров; Astra допускает более ранний узкий автоматический merge, если необходимые гарантии уже испытаны. Итог использует общий критерий: действие получает автономные полномочия после проверки требуемых механизмов и принятия границ риска. Обязательный повторный approval каждого PR после этого не вводится. Осторожный ручной пилот остаётся возможным выбором владельца.
Неопределённое до живого проекта
Версии Django/Python/БД; домены и бизнес-оракулы; фактические обходные writers; внешние эффекты; права и хранение данных; CI и merge-семантика; допустимый риск, порог достаточности пилота, окна релизов и восстановления. Гайд содержит способ получить эти ответы. Они не подменены предположениями о текущей рабочей папке.
Что сделано и что предстоит
Сделано: реальные дебаты, сверка ключевых технических утверждений с официальными источниками, гайд, шаблоны и демонстрация. Проверки моделей и файлов фиксируются отдельно в реестре результата, с хешем конкретной версии.
Предложено: архитектура знаний и процесса, контракты адаптеров, этапы внедрения. Следующий практический этап: применить начальный ранбук обследования к выбранному репозиторию. Исполняемый контур разработки, CI/merge-адаптеры и бизнес-тесты этим обсуждением не установлены и на продукте не испытаны.
Покрытие исходного задания
| Запрос | Где разобран | Конкретный выход при применении |
|---|---|---|
| 1. Архитектура и связность Markdown | Главы 1–2, шаблоны A2–A7 | Канонические документы, ID, типизированные связи, индекс, context manifest |
| 2. Бизнес-логика | Глава 3, A2–A4, сценарий A | BR, таблицы решений, инварианты, источники и конфликты |
| 3. Архитектура бэкенда | Глава 3, A1/A4 | Entry points, writers, потоки, транзакции, алгоритмы, циклы, практики и ADR |
| 4. Ранбуки | Глава 4, A8, сценарии A–D | Каталог задач, входы/переходы/выходы, checkpoints и recovery |
| 5. Коммиты и создание PR | Глава 5, A5/A9/A10 | Контракт изменения, кандидат, логические коммиты, PR и evidence |
| 6. Приёмка PR | Главы 5/9, A6/A10 | Независимая приёмка, policy/CI/merge gate, admission и completion receipts |
| 7. Тестирование | Главы 6/8, A11 | Baseline, тестовые обязательства, oracle, failure injection и holdout |
| 8. Переход с текущего состояния | Глава 7 | Этапы M0–M6 с входами, действиями, результатом и gate |
| 9. Консистентность и достаточность | Главы 2/5/8 | Четыре слоя контроля, traceability, freshness, критерии достаточности и границы гарантий |
| 10. Пропущенные аспекты | Главы 1/3/4/7/9 | Полномочия, внешние эффекты, данные/секреты, эксплуатация, стоимость, конкуренция и восстановление |
Каждое направление включено в руководство. Это покрытие разделов запроса; оно не доказывает полноту знаний о ещё не обследованном проекте. Реальное покрытие измеряется по доменам, входным точкам, инвариантам и классам задач.