Дебаты Astra × Fableresponse
Предлагаю строить переход как систему управляемого исполнения, в которой Markdown описывает знания и правила, ранбуки задают воспроизводимую работу, инструменты проверяют её результаты, а человек определяет намерения и принимает решения на заранее обозначенных границах. Само наличие документации не делает разработку автономной. Автономность появляется, когда для следующего действия можно установить: какие сведения достаточны, какое правило действует, кто разрешил действие, чем подтвердить результат и куда перейти при сбое.
Ни версия Django, ни структура приложения, ни способ развёртывания сейчас не известны. Поэтому ниже — предлагаемая архитектура процесса, а не описание существующего проекта. Названия каталогов условны; конкретные средства автоматизации выбираются после обследования. Поддержку нужных ограничений конкретной системой размещения кода, CI или оркестратором предстоит подтвердить по первичным источникам.
Основной единицей управления предлагаю сделать изменение с проверяемым контрактом. Оно связывает человеческое намерение, исследованный участок системы, согласованные критерии результата, разрешённые действия, выполнение ранбуков, конкретный снимок кода и доказательства проверки. Отдельный диалог с моделью остаётся вспомогательным каналом: продолжение работы не должно зависеть от сохранности его контекста.
Человек участвует между ранбуками, если следующему шагу требуется новое решение. Он не собирает отчёты, не переносит решения вручную, не ставит технические отметки и не повторяет уже одобренные инструкции. Модель готовит варианты и последствия; человек выбирает; инструменты фиксируют выбор, проверяют применимость разрешения, исполняют действия и сохраняют свидетельства.
Разделение знаний и полномочий
Нужны шесть разных классов записей. Их смешивание — главный источник ложной уверенности.
| Класс | Что утверждает | Пример |
|---|---|---|
| Наблюдаемые факты | Что обнаружено в определённом снимке системы | В обработчике имеется проверка статуса |
| Намерения | Какого результата хочет человек | Разрешить определённой роли отмену операции |
| Решения и правила | Какое поведение принято и какие ограничения действуют | После передачи исполнителю отмена запрещена |
| Проекции | Что автоматически извлечено из исходников или конфигурации | Граф зависимостей приложений |
| Доказательства | Что именно проверено и с каким результатом | Проверка конкурентной отмены на данном SHA |
| Полномочия | Какие действия разрешены при каких условиях | Создание PR для определённого класса изменений |
Даже наблюдение надо формулировать точно. Наличие проверки в функции ещё не доказывает, что любой путь выполнения проходит через неё. Успешный тест доказывает результат конкретного эксперимента. Код может содержать ошибку, а утверждённое правило — ещё не реализованное намерение.
Каждая существенная запись получает стабильный идентификатор, тип, статус, владельца области, источник, область применимости и основание последней проверки. Например:
id: BR-ORDER-017
kind: business-rule
status: approved
scope: order-cancellation
owner: role:order-domain-owner
decision: DEC-0042
applies_when: fulfillment_not_started
verified_against: commit:<sha>
evidence:
- EV-CHANGE-0081-03
relations:
implemented_by:
- SYM-ORDER-CANCEL
tested_by:
- TEST-ORDER-CANCEL-RACE
Набор полей зависит от типа записи. Разрешению нужны срок и условия отзыва; факту — метод наблюдения; решению — рассмотренные варианты и последствия. Статус approved нельзя автоматически присваивать извлечённому из кода описанию.
Структура документации и получение контекста
Предлагаю следующий каркас:
AGENTS.md
docs/
index.md
governance/
operating-model.md
authority-policy.md
risk-policy.md
evidence-policy.md
knowledge-lifecycle.md
intents/
INT-*.md
decisions/
DEC-*.md
domain/
glossary.md
context-map.md
orders/
index.md
lifecycle.md
rules/
BR-*.md
examples.md
open-questions.md
architecture/
system-context.md
runtime-inventory.md
applications.md
execution-paths/
data-and-transactions/
integrations/
security/
operations/
guidelines/
runbooks/
index.md
RB-*.md
testing/
strategy.md
baseline.md
environments.md
data-policy.md
quarantine.md
changes/
CHANGE-*/
contract.md
context-manifest.yaml
impact.md
acceptance.md
evidence-manifest.yaml
migration/
roadmap.md
capability-matrix.md
pilot-scorecard.md
generated/
object-registry.json
dependency-map.json
code-inventory.md
knowledge-health.md
AGENTS.md содержит короткий протокол входа: найти применимые правила, определить область изменения, собрать контекст, выбрать ранбук и проверить полномочия. Бизнес-правила там не дублируются.
Идентификатор не зависит от пути файла и не используется повторно. Перемещение документа сохраняет ID; отменённая запись остаётся с указанием замены. Ссылки между сущностями задаются типизированными отношениями: implements, supersedes, contradicts, requires, verified_by, authorized_by. Обычная Markdown-ссылка помогает чтению, реестр обеспечивает машинную проверку. Обратные ссылки и индексы генерируются.
Верхний индекс отвечает на вопрос «с чего начать». Индекс предметной области показывает правила, пути выполнения, открытые вопросы и подходящие ранбуки. Индекс ранбуков классифицирует задачи по результату, риску и предусловиям. Один факт имеет одно основное место хранения; остальные документы ссылаются на него.
Крупные логи, трассы и тестовые отчёты лучше хранить в хранилище артефактов. В репозитории остаются их адреса, контрольные суммы, сроки хранения и связь с изменением. Секреты и персональные данные в документацию не включаются.
Минимальный достаточный контекст — результат отдельной процедуры, а не произвольный набор найденных файлов. Она начинается с намерения и предполагаемых точек изменения, затем включает:
- Применимые правила полномочий и риска.
- Контракт задачи, словарь и бизнес-инварианты.
- Затрагиваемые пути исполнения и зависимости.
- Ограничения совместимости, данных и эксплуатации.
- Ранбук, необходимые проверки и известные неопределённости.
Получается context-manifest: включённые ID и версии, снимок кода, основания выбора, существенные исключения. Поиск по смыслу помогает обнаруживать кандидатов, но обязательные зависимости добавляются по графу.
Контекст расширяется, если обнаружены динамический вызов, новый побочный эффект, незнакомая интеграция или противоречие. Если всё необходимое не помещается, задача делится либо создаются проверенные промежуточные сводки со ссылками. Молчаливое отбрасывание правил ради размера окна запрещается.
Извлечение бизнес-логики и архитектуры
Обследование начинается с воспроизводимого снимка: ревизии репозитория, зависимостей, доступных конфигураций, способов запуска и проверки. Отдельно отмечается, какие сведения получены из рабочего окружения, а какие относятся только к исходникам. Секретные значения не требуются для описания назначения настроек.
Бизнес-логику следует извлекать по пользовательским операциям и жизненным циклам, а затем связывать с модулями. Для каждого сценария модель исследует инициатора, права, входы, состояния, переходы, вычисления, транзакционные границы, ошибки, внешние эффекты и восстановление. Исследуются также административные интерфейсы, команды, фоновые задачи и обходные пути.
Источники сопоставляются: код, миграции, тесты, существующая документация, согласованная история решений и разрешённые эксплуатационные наблюдения. Совпадение нескольких источников повышает обоснованность вывода, но не заменяет решение владельца бизнеса.
Карточка бизнес-правила должна содержать:
- формулировку и область действия;
- участников, предусловия и инварианты;
- допустимые и запрещённые переходы;
- положительные, отрицательные и граничные примеры;
- вычисления, округление, время, валюты или единицы измерения, если применимо;
- идемпотентность, конкурентность и побочные эффекты;
- исключения, источники, расхождения и проверки.
Неизвестное маркируется прямо: «предположение», «наблюдение в тестовой среде», «подтверждено владельцем», «не установлено». Вместо численной уверенности без основания полезнее указать, какого свидетельства недостаёт.
Если код допускает операцию, а документация запрещает, создаётся противоречие с точными ссылками и последствиями вариантов. До решения можно добавить характеризующий тест существующего поведения, явно отметив, что он фиксирует совместимость, а не утверждает правильность.
Архитектурное извлечение имеет два слоя. Структурный слой показывает приложения, модели, зависимости, интерфейсы, хранилища, очереди и внешние системы. Поведенческий слой показывает реальные пути: запрос, middleware, маршрутизация, обработчик, доменная операция, ORM, фиксация транзакции, отложенная задача, внешний эффект.
Для Django обследование проверяет наличие и использование следующих механизмов, не предполагая их заранее:
- настройки и различия окружений, инициализацию приложений;
- модели, менеджеры, queryset, ограничения и миграции;
- URL, views, формы, сериализацию, шаблоны и API;
- аутентификацию, объектные права, административные действия;
- сигналы, переопределения сохранения и удаления;
- транзакции, блокировки, callbacks после commit;
- фоновые задачи, повторы, планировщики, management commands;
- кэш, файлы, поиск, внешние клиенты;
- синхронное и асинхронное исполнение, если применимо.
Циклы надо искать не только в импортах. Возможны циклические бизнес-вызовы, повторное срабатывание сигналов, цепочки задач и обратные вызовы интеграций. Статический граф показывает кандидатов; трассировка и целевые эксперименты проверяют доступные маршруты. Непокрытая динамика остаётся ограничением карты.
Алгоритмы описываются через входы, выходы, инварианты, порядок действий, сложность и условия завершения. Для практик фиксируется различие: «так сделано в старом коде», «так рекомендовано для новых изменений», «так запрещено». Часто встречающийся антипаттерн не должен автоматически становиться гайдом.
Исполняемый контракт ранбука
Ранбук — версия процедуры с проверяемыми переходами. Markdown объясняет смысл, а структурированные поля позволяют исполнителю проверить допустимость следующего шага.
id: RB-BUSINESS-CHANGE
version: 1
inputs:
- change_contract
- context_manifest
- repository_snapshot
preconditions:
- scope_resolved
- applicable_authority_valid
states:
- prepared
- implemented
- verified
- proposed
- accepted
- blocked
- failed
outputs:
- patch
- evidence_manifest
- pull_request
- knowledge_update
on_scope_expansion: return_to_prepared
on_permission_gap: blocked
resume_from: last_verified_checkpoint
Для каждого перехода необходимы конкретные входы, операция, разрешённые инструменты, выходы, машинные проверки, тайм-аут, политика повторов и обработка частичного успеха. Например, переход verified → proposed требует проверенного SHA, действующего права публикации и проверки отсутствия секретов в публикуемых материалах.
Исполнитель ведёт журнал событий с ID выполнения, шагом, входными отпечатками, результатом и внешними идентификаторами. После прерывания он сверяет внешнее состояние. Уже созданный PR переиспользуется; команда с неизвестным результатом не повторяется автоматически, если могла иметь необратимый эффект.
Идемпотентность указывается отдельно для каждого шага. Повтор теста обычно допустим; повтор отправки уведомления требует ключа дедупликации; повтор миграции оценивается по её устройству. Для необратимых операций описываются компенсация и пределы восстановления.
Типовые ранбуки выделяются из повторяющихся работ: исправление дефекта, изменение бизнес-правила, схема данных, интеграция, производительность, зависимость, инцидент. Новый ранбук сначала проходит управляемое исполнение; автоматизация расширяется после наблюдения его сбоев. Нельзя одним ранбуком «сделать всё» скрыть различия риска.
Решения человека как ограниченные разрешения
Решение о желаемом поведении и разрешение выполнять действие — разные записи. Первое может быть долгоживущим; второе действует только в заданных границах.
Разрешение включает субъекта или роль исполнителя, проект, класс задач, разрешённые действия, исключения, максимальный риск, обязательные проверки, версию ранбука, срок действия и условия отзыва. Для чувствительного одноразового действия оно привязывается к точному изменению; для повторной безопасной механики — к классу задач и проверяемым ограничениям.
Например, можно разрешить автоматически создавать ветку, выполнять проверки и открывать PR для внутренних изменений без миграций и изменения прав. Это разрешение не распространяется на merge, production, внешние платежи или расширение API, если они явно не включены.
Перед действием инструмент вычисляет применимость полномочия. Изменился объём работ, истёк срок, обновилась обязательная политика или перестало выполняться условие — требуется новое решение. Старые разрешения не редактируются задним числом; создаются новые версии и события отзыва.
Человеку предъявляется подготовленный пакет: вопрос, варианты, рекомендация, последствия, неизвестное, точный объём разрешения. Его ответ должен однозначно относиться к версии пакета. Неполный или двусмысленный ответ не трактуется как широкое согласие. После решения вся фиксация и дальнейшая механика автоматизируются.
Создание коммита и PR
Авторское исполнение завершается проверкой diff, области изменения, тестов, миграций, документации и воспроизводимости результата. Коммит создаётся из явно перечисленных файлов; посторонние локальные изменения не включаются. Его сообщение объясняет причину и эффект, ссылается на контракт изменения.
До отправки проверяются выбранные remote и ветка, политика публикации и отсутствие конфиденциальных материалов. Создание локального коммита, push и открытие PR — отдельные действия с отдельными условиями, даже если один ранбук выполняет их подряд.
PR содержит проблему, итоговое поведение, границы изменения, существенные риски, проверенные сценарии, ограничения проверки, порядок развёртывания и восстановления. Технический пакет включает SHA ветки, базовую ревизию, состав diff, версии зависимостей и окружения, команды проверок и ссылки на артефакты.
Не каждый лог нужно показывать человеку. Краткое представление должно позволять принять решение, а подробные свидетельства — проверить его основания.
Приёмка и независимость проверки
Приёмочный ранбук получает кандидат из PR и независимо извлекает его diff и применимые правила. Самоотчёт автора полезен как навигация, но не является доказательством.
Независимость состоит в разделении полномочий, исходных данных и выполнения: автор не присваивает себе статус приёмки; проверки запускаются доверенным способом; критерии берутся из утверждённого контракта. Вторая модель может помогать, но не обеспечивает независимость сама по себе.
Особенно важно защищать механизм проверки от изменения проверяемым кодом. Если PR меняет CI или тестовые правила, этот фрагмент требует отдельного маршрута приёмки. Исполнение недоверенного кода выполняется без production-секретов и лишних прав.
Все свидетельства связаны с конкретным кандидатом: head SHA, основанием сравнения, конфигурацией и версией правил. После нового коммита подтверждение всего кандидата устаревает. Отдельные результаты можно переиспользовать только по утверждённому правилу зависимости, если доказано, что их входы сохранились.
Непосредственно перед merge проверяется соответствие проверенного и принимаемого состояния. Изменение целевой ветки может потребовать проверки результата объединения. Конкретную реализацию этого барьера надо выбрать с учётом возможностей платформы.
Приёмка означает выполнение критериев разработки. Разрешение на развёртывание и эксплуатационное подтверждение могут быть отдельными границами. Автоматический merge допустим для заранее согласованного класса задач; значимый остаточный риск требует решения человека.
Тестирование существующего проекта
Сначала нужна честная исходная линия: какие проверки запускаются, какие падают, какие нестабильны, насколько воспроизводимо окружение. Не следует требовать немедленно исправить всё наследие, но нельзя объявлять известные падения безусловно допустимыми.
Стратегия развивается вокруг риска:
- характеризующие тесты сохраняют важное существующее поведение;
- тесты правил проверяют бизнес-инварианты;
- интеграционные тесты проверяют ORM, ограничения и границы транзакций;
- контрактные тесты проверяют интерфейсы и интеграции;
- небольшое число сквозных тестов подтверждает критические маршруты;
- проверки миграций, конкурентности, производительности и безопасности добавляются по типу изменения.
Для конкурентности и SQL-семантики среда должна воспроизводить существенные свойства используемой БД. Заглушка внешнего сервиса не доказывает совместимость с его реальным контрактом. Тестовые данные создаются воспроизводимо и без бесконтрольного копирования персональных данных.
Неустойчивые тесты получают владельца, основание карантина, срок исправления и оценку потерянной защиты. Новый сбой нельзя списать на наследие без сопоставления с базовой ревизией.
Минимальный барьер изменения: не появилось необъяснённых регрессий, защищён изменяемый инвариант, проверены релевантные риски. Покрытие строк — диагностический сигнал, а не мера правильности. Выборочные мутационные проверки и преднамеренно ошибочные варианты помогают понять, способен ли набор тестов обнаружить существенный дефект.
Последовательность перехода
| Этап | Вход | Работа модели и инструментов | Решение человека | Выход и критерий перехода |
|---|---|---|---|---|
| 0. Границы | Намерения команды | Подготовить роли, риски, ограничения данных | Утвердить начальную автономность | Политики; понятны запрещённые действия |
| 1. Исходная линия | Снимок проекта | Восстановить запуск, проверки, карту окружений | Выбрать пилот, принять явные ограничения | Воспроизводимый baseline либо перечень блокеров |
| 2. Карта пилота | Код и доступные источники | Извлечь правила и пути, проверить гипотезы | Разрешить существенные противоречия | Для пилота прослеживаются инварианты и источники |
| 3. Ранбук | Типовая задача | Подготовить контракт, исполнить в теневом режиме | Утвердить границы процедуры | Проверено выполнение, прерывание и возобновление |
| 4. Ограниченное применение | Реальные задачи малого риска | Выполнять работу до PR и готовить приёмку | Решать исключения | Несколько задач пройдены без скрытой ручной механики |
| 5. Расширение | Метрики и разборы сбоев | Предложить новые классы автономности | Утвердить расширение | Разрешения расширены только для доказанных возможностей |
| 6. Эксплуатация | Поток изменений | Обновлять знания, проверки и отчётность | Менять правила и приоритеты | Процесс регулярно проверяется на реальных задачах |
Количество пилотов определяется разнообразием рисков, а не магическим числом. При переходе команда осваивает формулирование намерений, оценку решений и разбор исключений. Доменные владельцы сохраняют ответственность за смысл; сопровождение автоматизации получает своего владельца.
Rollout идёт по областям и классам действий. Сначала наблюдение, затем подготовка изменений, затем ограниченная публикация и только потом более широкое исполнение.
Rollback процесса означает отзыв разрешений, остановку новых запусков и безопасное завершение либо приостановку текущих. Рабочий репозиторий и обычный путь разработки должны оставаться доступными. Откат процесса не равен откату кода или данных: для них действуют отдельные процедуры восстановления.
Сквозной условный сценарий
Предположим исключительно для примера, что существует сущность заказа. Человек сообщает намерение: «Оператор должен отменять заказ до передачи исполнителю; повторное действие не должно повторять внешние эффекты».
Модель создаёт намерение и исследовательский ранбук. В условном обследовании обнаруживаются два пути отмены, отложенная отправка уведомления и отсутствие установленного правила для гонки с передачей исполнителю. Это ещё не спецификация решения.
Модель готовит варианты: отмена выигрывает при любом незавершённом исполнении либо право определяется первым зафиксированным переходом. Показывает последствия, сценарии гонки и необходимость единого поведения двух точек входа. Человек выбирает второй вариант и утверждает критерии. Инструмент фиксирует решение, не поручая человеку редактировать YAML.
Контракт требует: только уполномоченный оператор может отменять; после зафиксированной передачи отмена отклоняется; повтор отмены сохраняет результат; внешний эффект не дублируется в пределах согласованной гарантии доставки. Последний пункт требует отдельного понимания возможностей интеграции: обещание «ровно один раз» нельзя вывести из локального флага.
Исполнитель собирает контекст, проверяет разрешение и изменяет обе точки входа с общей доменной операцией. Конкретный способ блокировки выбирается после проверки БД. Проверки охватывают права, переходы, повторный запрос, конкурентное исполнение и сбой доставки.
После успешных проверок создаются коммит и PR. Независимая приёмка обнаруживает, допустим, что административный маршрут обходит общую операцию. Кандидат возвращается на реализацию, область контекста расширяется, прежнее подтверждение становится устаревшим.
Исправленный кандидат проверяется заново. Если он соответствует разрешённому классу, приёмка и merge выполняются автоматически; иначе человек получает уже готовое решение по конкретному кандидату. Документация обновляется вместе с реализацией: правило связывается с кодом и тестами, прежнее наблюдение сохраняется как история, а непроверенная эксплуатационная часть остаётся явно открытой.
Для согласования этого сценария прилагаю минимальную HTML-демонстрацию. Это текстовый макет предложения: он не утверждает, что обследование или реализация уже состоялись.
<!doctype html>
<html lang="ru">
<meta charset="utf-8">
<title>Предлагаемый путь изменения</title>
<style>
body{font:18px system-ui;max-width:850px;margin:40px auto;padding:20px}
article{border:1px solid #aaa;border-radius:12px;padding:20px}
summary{cursor:pointer;font-weight:bold}
small{display:block;color:#555}
</style>
<h1>Отмена условного заказа</h1>
<p><b>Статус:</b> предложение процесса. Продукт не изменён.</p>
<p><b>Согласованный принцип:</b> человек принимает решения;
подготовку, исполнение и проверки выполняют инструменты.</p>
<article>
<details open>
<summary>1. Намерение → исследование</summary>
<p>Найти все пути отмены, права, гонки и внешние эффекты.</p>
<small>Выход: факты отдельно от неизвестного.</small>
</details>
<details>
<summary>2. Решение человека</summary>
<p>Предлагаемый выбор: результат определяет первый
зафиксированный переход. Это решение ещё не принято.</p>
<small>Выход: версия правила и ограниченное разрешение.</small>
</details>
<details>
<summary>3. Исполнение → PR</summary>
<p>Изменить затронутые маршруты, проверить повторы и гонки,
связать результаты с конкретным коммитом.</p>
</details>
<details>
<summary>4. Приёмка или возврат</summary>
<p>Независимо проверить кандидат. Новый коммит отменяет
готовность прежнего кандидата к принятию.</p>
</details>
<details>
<summary>5. Обновление знаний</summary>
<p>Связать правило, реализацию и доказательства.
Непроверенные эксплуатационные свойства оставить открытыми.</p>
</details>
</article>
</html>
Консистентность и достаточность
Автоматическая проверка документации контролирует уникальность ID, существование ссылок, обязательные поля, недопустимые статусы и связи. Изменение исходников помечает зависимые проекции и утверждения как требующие перепроверки. Оно не должно автоматически переписывать нормативное правило.
Семантические противоречия выявляются сопоставлением правил, примеров и поведения; неоднозначные случаи направляются владельцу решения. Для критических областей нужен периодический полный пересмотр: граф зависимостей сам может оказаться неполным.
Достаточность определяется относительно задачи и риска. Перед исполнением проверяется, можно ли объяснить путь воздействия, назвать инварианты, сформулировать приёмку, определить полномочия и восстановиться после сбоя. Если неизвестное способно изменить решение, сначала выполняется исследовательский ранбук.
Качество системы измеряется на репрезентативных задачах: долей возвратов, пропущенными дефектами, ручными вмешательствами, временем ожидания решений, стоимостью исполнения и успешностью восстановления. Документация достаточна настолько, насколько помогает пройти эти задачи с известными ограничениями.
Существенные дополнительные аспекты — защита от инструкций в недоверенных данных, разделение секретов и исполняемого кода, лицензии и зависимости, лимиты расходов, конкурентные изменения, наблюдаемость production, резервирование артефактов и сохранение человеческой компетенции. Инструкции из issue, логов или внешних страниц не могут выдавать новые полномочия.
Где предложение может дать сбой
- Неверная реконструкция бизнеса. Код и тесты согласованно отражают старую ошибку. Нужны источники намерений и решение владельца.
- Неполная карта воздействия. Динамический путь остаётся незамеченным. Нужны целевые эксперименты и расширение проверки по риску.
- Формально зелёные проверки. Тесты повторяют реализацию и пропускают дефект. Нужны независимые примеры и проверка чувствительности тестов.
- Слишком широкое разрешение. Исполнитель относит опасную задачу к безопасному классу. Нужны машинные ограничения и отдельные права инструментов.
- Устаревшие доказательства. Принимается новый код по старым результатам. Нужна проверка идентичности кандидата непосредственно перед действием.
- Бюрократический рост. Поддержка записей стоит дороже выигрыша. Нужны генерация проекций и минимальные схемы по риску.
- Невосстановимый частичный эффект. Повтор шага дублирует внешнюю операцию. Нужны журнал, сверка состояния и компенсации.
- Общая ошибка автора и проверяющего. Оба принимают одну гипотезу. Нужны разные источники свидетельств и проверяемые инварианты.
Для второго раунда предлагаю обсудить пять решений: насколько широко разрешать автоматический merge; хранить ли журнал разрешений внутри репозитория или отдельно; насколько строгой делать структурированную схему Markdown; какую независимость приёмки требовать для разных рисков; когда характеризующее поведение наследия считать обязательством совместимости. По каждому вопросу стоит выбрать исходную политику и измеримый повод её пересмотреть.