Разработка с участием ИИ-агента¶

Требования применяются к изменению прикладного проекта, при котором ИИ-агент читает, создаёт или изменяет исходный код, конфигурацию, схемы либо документацию. Проект объявляет такую работу возможностью ai-assisted-development. Уровни обязательности определены в корневом README.md.

AI-DEV-001. Машинообнаружимая точка входа¶

Уровень: MUST

Применяется к: проекту с возможностью ai-assisted-development

Корень проекта должен содержать версионируемый AGENTS.md, который ИИ-агент читает до других проектных инструкций. Файл должен указывать расположение manifest стандартов — .standards/standards.yaml либо путь согласованного исключения из STD-MAN-001, — локальных ADR и публичных контрактов, команды запуска и обязательных проверок, воспроизводимый способ проверить версию стандартов и получить применимый контекст, а также условия остановки и эскалации.

Ссылки и команды не должны зависеть от пользовательского home-каталога, неверсионируемого локального файла или устаревающей ссылки на ветку стандартов. Вложенный AGENTS.md MAY уточнять инструкции только для своего каталога.

Обоснование¶

Стабильная точка входа не позволяет агенту выводить правила работы из названий каталогов, кэшированного контекста или случайно найденной документации.

Проверка¶

проверка наличия корневого AGENTS.md;
проверка локальных ссылок и существования указанных команд;
сопоставление manifest с указанной версией стандартов.

Исключения¶

Не допускаются для имени и расположения корневой точки входа.

AI-DEV-002. Обновление контекста перед изменением¶

Уровень: MUST

Применяется к: началу новой задачи или продолжению работы после изменения ветки, manifest либо инструкций

До изменения агент должен заново прочитать применимые AGENTS.md, проверить текущую ветку и рабочее дерево, сопоставить checkout стандартов с standards.tag и standards.commit_sha, а затем получить вычисленный перечень документов. Агент должен прочитать требования, область которых пересекает затрагиваемые компоненты, возможности, данные или операции, а также связанные локальные ADR и контракты.

До отбора требований агент должен проверить объявленную область каждого требования по индексу context --depth index или эквивалентному результату. Полное повторное чтение требования, объявленная область которого не пересекает задачу, не требуется. Название файла или кэшированный перечень прошлой задачи не должны использоваться как единственное основание для исключения требования.

Кэшированный текст прошлой сессии не должен считаться подтверждением текущего состояния репозитория.

Обоснование¶

Ветка, инструкции и стандарты изменяются независимо от сохранённого контекста агента.

Проверка¶

воспроизводимый preflight script либо журнал команд в agent session;
сопоставление SHA рабочей ветки, manifest и checkout стандартов;
сопоставление затронутых компонентов и возможностей с индексом требований;
review перечня прочитанных требований, ADR и контрактов.

Исключения¶

Повторное чтение неизменившегося файла MAY быть заменено проверкой его зафиксированного digest в пределах одной непрерывной задачи.

AI-DEV-003. Результат и проверка до реализации¶

Уровень: SHOULD

Применяется к: изменению поведения, контракта, данных или сборки

До начала реализации следует зафиксировать в задаче, merge request или другом версионируемом рабочем объекте наблюдаемый результат, границы изменения и команды либо проверки, которыми результат будет подтверждён.

Критерий не следует заменять после реализации только потому, что исходная проверка обнаружила дефект. Изменение критерия должно сохранять причину и согласование.

Обоснование¶

Предварительный критерий отделяет проверку результата от постфактум самосертификации удобного поведения.

Проверка¶

сравнение времени фиксации критерия с первым commit реализации;
сопоставление критерия с тестами и итоговым evidence;
review причины изменения критерия.

Исключения¶

Исследовательская задача MAY начинаться с гипотезы, если отдельно определено, что её результатом является проверяемое решение, а не production-изменение.

AI-DEV-004. Остановка при недостатке полномочий или контекста¶

Уровень: MUST

Применяется к: конфликту требований, отсутствующему manifest, неясному публичному контракту или действию вне явно предоставленных полномочий

Агент должен остановить затронутую часть работы, зафиксировать конкретный конфликт или недостающий факт и запросить решение уполномоченного человека. Агент не должен самостоятельно выбирать более удобное требование, придумывать исключение, менять зафиксированную версию стандартов или расширять область задачи.

Независимая часть задачи MAY продолжаться, если она не зависит от спорного решения и не скрывает блокирующее условие.

Обоснование¶

Предположение агента не предоставляет организационного полномочия изменить контракт, риск или область задачи.

Проверка¶

review сообщения об эскалации и остановленного diff;
проверка отсутствия изменения спорного контракта до решения;
сопоставление продолженной части с независимой областью.

Исключения¶

Не допускаются для security-границы, публичного контракта, целостности данных, миграции или production-доступа.

AI-DEV-005. Связность изменения¶

Уровень: SHOULD

Применяется к: diff, создаваемому агентом для одной задачи

Изменение следует ограничивать одним наблюдаемым результатом и необходимыми для него тестами, схемами и документацией. Смену стека, несвязанный рефакторинг и самостоятельное изменение публичного контракта следует выносить в отдельные решения и merge requests.

Обоснование¶

Связный diff позволяет независимо проверить результат и откатить его без захвата несвязанных изменений.

Проверка¶

сопоставление каждого изменённого файла с критерием задачи;
review несвязанных изменений и причин их включения;
проверка возможности разделить независимые результаты.

Исключения¶

Механическое изменение MAY охватывать несколько каталогов, если один проверяемый контракт требует их атомарного обновления.

AI-DEV-006. Воспроизводимое evidence¶

Уровень: MUST

Применяется к: утверждению агента о соответствии или успешной проверке

Текст ответа агента не должен считаться evidence. Утверждение должно указывать фактически выполненную команду или проверку, её результат и ограничения. Решение о merge должно использовать обязательный CI для того же commit по DEP-CI-001 и DEV-VER-003.

Невыполненная, пропущенная, отменённая или неуспешная проверка должна быть названа явно и не должна описываться как успешная.

Обоснование¶

Агент может ошибочно пересказать результат, использовать вывод другого commit или не заметить частичное выполнение проверки.

Проверка¶

сопоставление утверждения с job, отчётом и commit SHA;
повторный запуск указанной команды в чистой среде;
проверка раскрытия пропущенных и неуспешных проверок.

Исключения¶

Локальный результат MAY использоваться для промежуточной диагностики, но не заменяет обязательный merge gate.

AI-DEV-007. Передача данных модели¶

Уровень: MUST NOT

Применяется к: prompt, context, attachment, tool output и telemetry, передаваемым ИИ-модели или её провайдеру

Запрещено передавать секреты, аутентификационные данные, полные платёжные реквизиты и любой класс выше разрешённого для провайдера. Персональные и остальные защищаемые данные могут передаваться только тогда, когда договор обработки, политика классификации и конфигурация провайдера явно разрешают этот класс и цель.

Обоснование¶

Контекст модели покидает локальную границу процесса и может обрабатываться и храниться отдельным поставщиком.

Проверка¶

сопоставление классов данных с договором и настройками retention/training;
DLP или secret scanning исходящего контекста;
контролируемый тест маскирования tool output.

Исключения¶

Секреты, аутентификационные данные и полные платёжные реквизиты не передаются модели независимо от договора.

AI-DEV-008. Минимальные полномочия агента¶

Уровень: MUST

Применяется к: identity, credentials, filesystem и network среды агента

Среда должна предоставлять минимальные полномочия для текущей задачи и ограничивать доступ репозиторием и явно необходимыми системами. Агент не должен иметь изменяющий доступ к production, право самостоятельного merge в защищённую ветку или неограниченные организационные credentials.

Push, публикация артефакта и изменение внешней системы должны выполняться только при явном задании в области задачи и отдельной проверяемой авторизации. Секреты должны передаваться конкретному инструменту без включения в prompt, лог или общий context агента.

Обоснование¶

Ошибка интерпретации задачи не должна автоматически становиться production-изменением или компрометацией всей организации.

Проверка¶

review scopes identity, sandbox и network policy;
тест запрета production, protected branch и несогласованной публикации;
проверка отсутствия секретов в transcript и tool output.

Исключения¶

Расширенное полномочие требует ограниченных цели, времени и ресурсов, подтверждения человеком и аудит-записи.

AI-DEV-010. Атрибуция участия агента¶

Уровень: SHOULD

Применяется к: merge request, в котором ИИ-агент создал или изменил код, конфигурацию, схему либо проектную документацию

Merge request следует помечать как созданный с участием агента и указывать зафиксированную версию стандартов, проверенные области и фактически выполненные проверки. Модель, провайдера и ограничения context следует указывать, когда это разрешено политикой и эти сведения влияют на воспроизводимость или review.

Полный prompt, секреты и защищаемые данные не следует сохранять ради атрибуции.

Обоснование¶

Происхождение помогает ревьюеру применить проверки к характерным ошибкам агента без раскрытия избыточного контекста.

Проверка¶

review metadata merge request;
сопоставление версии стандартов и evidence;
проверка отсутствия защищаемых данных в описании.

Исключения¶

Редакционное изменение MAY не иметь отдельной пометки, если политика репозитория не требует её для любого использования агента.

AI-DEV-011. Минимизация контекста модели¶

Уровень: MUST

Применяется к: данным, разрешённым для передачи модели по AI-DEV-007

Передаваемый context должен быть ограничен минимальным набором файлов, фрагментов и tool output, необходимых текущей задаче. Защищаемые значения должны маскироваться до передачи по DATA-CLS-002. Инструкция в prompt «не использовать данные» не должна считаться маскированием или контролем доступа.

Автоматическое включение всего репозитория, истории сообщений, environment или вывода инструментов запрещено без проверки их необходимости и класса данных.

Обоснование¶

Разрешение провайдера обрабатывать класс данных не устраняет обязанность минимизировать объём раскрытия и последствия ошибочного выбора context.

Проверка¶

review правил выбора context и исключаемых путей;
DLP или secret scanning сформированного запроса;
тест маскирования и запрета автоматического включения environment.

Исключения¶

Полный файл MAY передаваться, если его целостный контекст необходим задаче и все его данные разрешены для выбранного провайдера.