Перейти к содержанию

Инструкции для ИИ-агентов

Назначение

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

Корневой README.md определяет назначение репозитория, источник правды, уровни обязательности, обязательный формат требования и семантику версий. Этот файл определяет обязательный рабочий процесс агента, изменяющего репозиторий. Не переноси агентные инструкции в README.md или нормативные документы.

Инструкции действуют для всего репозитория. Более вложенный AGENTS.md может уточнять их только для своего каталога.

Перед изменением

  1. Прочитай README.md, этот файл и все документы в изменяемом разделе.
  2. Проверь рабочее дерево и не изменяй несвязанные пользовательские правки.
  3. Определи цель, область применения и предполагаемых исполнителей требования.
  4. Найди требования с близким смыслом и существующие ссылки на изменяемые ID.
  5. До написания выясни решения, которые нельзя безопасно вывести из репозитория: обязательный стек, маршрут данных, границы применимости, допустимые исключения и способ проверки.
  6. Если задача противоречит действующему стандарту, останови затронутую часть работы и явно опиши конфликт.

Поддержание консистентности

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

  • README.md и CHANGELOG.md;
  • manifest, каталог применимости, schema и CLI, если меняется применимость;
  • диаграммы, сводные таблицы, примеры и тесты;
  • AGENTS.md, если изменение влияет на порядок работы агента;
  • инфраструктурный слой, если меняется реализуемый им архитектурный контракт.

Если изменение затрагивает оба слоя, обновляй архитектурный контракт, инфраструктурную реализацию, profiles, каталоги и проверки одним merge request. Не создавай обратные нормативные ссылки из архитектурного слоя.

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

Размещение документов

  • Нормативные документы размещай в тематическом каталоге docs/.
  • Ненормативные схемы и сводные таблицы размещай в тематическом каталоге docs/, а машинно-проверяемые JSON Schema — в schemas/.
  • Примеры кода, конфигурации, payload и интеграции размещай только в examples/ по требованиям DOC-CLR-006 и DOC-CLR-007.
  • Для поведения приложения используй docs/architecture/, для deployment, runtime и платформы — docs/infrastructure/, для общих правил авторинга и применимости — docs/governance/.
  • Для backend-требований используй docs/architecture/backend/.
  • Технологический profile размещай в profiles/technologies/; он может только выбирать нормативные документы и не должен содержать новые обязанности.
  • Один документ должен регулировать одну ясно названную область.
  • Разделяй документы, если у требований различаются назначение, модель доступа, маршрут данных или жизненный цикл. Например, аудит-лог не является разновидностью диагностического лога.
  • Не создавай index, шаблон, профиль, конфигурацию MkDocs или CI «на будущее», если этого не требует задача.
  • При добавлении нормативного документа, справочного материала или схемы добавь на него ссылку в соответствующий перечень в README.md. Пример из examples/ связывай с иллюстрируемым нормативным требованием.
  • При добавлении, удалении или переносе публикуемой Markdown-страницы синхронно актуализируй nav в mkdocs.yml. Размещай страницу по задаче читателя, а не механически по пути в репозитории, и проверяй полной строгой сборкой MkDocs, что все публикуемые страницы доступны из меню.

Имена файлов должны быть короткими, стабильными, в kebab-case и отражать предмет документа.

Проектирование требований

Используй формат требования и уровни обязательности из README.md.

Перед добавлением каждого требования проверь:

  1. Какой конкретный риск или необходимый результат оно регулирует?
  2. Кто и при каких условиях обязан его выполнять?
  3. Можно ли определить соответствие без субъективного толкования?
  4. Не смешаны ли в одной формулировке независимые требования?
  5. Не дублирует ли оно другой ID?
  6. Не навязывает ли оно реализацию там, где достаточно контракта?
  7. Определено ли поведение при отказе, если требование касается распределённого взаимодействия?

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

Формулировка должна:

  • использовать MUST, MUST NOT, SHOULD, SHOULD NOT или MAY;
  • описывать наблюдаемое свойство или результат;
  • явно называть область применения;
  • различать запрет, обязательство и допустимый вариант;
  • использовать один термин для одного понятия;
  • раскрывать аббревиатуру при первом использовании, если она не общеупотребительна в разделе;
  • указывать точные имена полей, протоколы и форматы, когда они являются частью контракта;
  • определять отсутствие значения отдельно от пустого, нулевого или фиктивного значения;
  • учитывать ошибки, повторы, тайм-ауты, частичные отказы и конкурентное выполнение, когда они применимы.

Не используй как нормативную формулировку:

  • «желательно», «обычно», «по возможности», «корректно» и «лучшие практики» без проверяемого определения;
  • «и другие», «и так далее» или открытый перечень обязательных условий;
  • конкретный язык, framework или библиотеку, если контракт можно выразить технологически нейтрально;
  • пример как единственное определение обязательного поведения;
  • ссылку на «актуальную версию» изменяемой внешней спецификации без зафиксированного диапазона или правила обновления.

Идентификаторы

  • Используй существующий префикс предметной области.
  • Перед назначением ID найди все ID этого префикса во всём репозитории.
  • Выбирай следующий свободный номер, не перенумеровывая опубликованные требования.
  • Не меняй ID при переносе требования между разделами.
  • Не используй освобождённый ID для нового смысла.
  • При разделении требования сохраняй исходный ID за основной нормой, а новым нормам назначай новые ID.

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

Технологическая нейтральность

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

Инфраструктурные механизмы доставки и эксплуатации принадлежат docs/infrastructure/. В docs/architecture/ фиксируй только наблюдаемое поведение приложения, контракт данных или release-инвариант. Архитектурные требования не должны ссылаться на инфраструктурные ID: инфраструктурный слой зависит от стабильных архитектурных ID, а обратная ссылка создаёт цикл.

Если изменение требует нового поведения приложения и платформенной реализации, сначала сформулируй архитектурный контракт, затем в том же изменении обнови инфраструктурную реализацию и проверки. Не копируй формулировку требования между слоями.

Для текущего раздела наблюдаемости учитывай целевую архитектуру:

  • выбранные проектом трассы и метрики: приложение → OpenTelemetry Protocol (OTLP) → OpenTelemetry Collector → OpenObserve;
  • диагностические и аудит-логи: приложение → stdout/stderr → Vector → OpenObserve;
  • выбранный проектом сбор ошибок: приложение → Sentry SDK → GlitchTip.

OpenTelemetry, Vector, OpenObserve и GlitchTip задают интеграционные границы, но требования не должны зависеть от конкретного языка. Go, Node.js, Python, PHP, Angular, React и Vue учитываются при проверке реализуемости, а не оформляются как разные нормативные правила без необходимости.

Нормативный стиль документа

Документ должен содержать только:

  • название и краткую область применения;
  • нормативные требования в формате из README.md;
  • необходимые определения, если без них требования неоднозначны.

В нормативный документ не добавляй:

  • учебное введение;
  • пошаговую инструкцию по настройке библиотеки;
  • примеры кода или конфигурации;
  • обзор инструментов;
  • ненормативный список «лучших практик»;
  • повтор разделов из README.md.

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

Не копируй содержимое examples/ в прикладной проект и не используй его как готовую реализацию. Проектируй решение по нормативным требованиям, локальной архитектуре и зафиксированным версиям зависимостей. Пример можно использовать только для понимания намерения требования.

Обоснование объясняет риск или архитектурную причину, но не добавляет новое обязательство. Раздел «Проверка» должен содержать реально исполнимые способы контроля: автоматический тест, статическую проверку, запрос к платформе, проверку схемы или ограниченный review. Формулировка «проверить корректность» без критерия недостаточна.

Исключение должно либо:

  • прямо запрещаться;
  • ссылаться на согласованный ADR;
  • задавать точные условия и границы допустимого отклонения.

Согласованность наблюдаемости

При изменении логирования, трассировки или сбора ошибок проверь согласованность как минимум следующих понятий:

  • service.name;
  • service.version;
  • deployment.environment.name;
  • event.name;
  • trace_id;
  • span_id;
  • request_id;
  • correlation_id;
  • классификация ошибок;
  • защита секретов и персональных данных;
  • поведение при недоступности платформы наблюдаемости.

Одинаковое понятие должно иметь одинаковое имя и семантику во всех сигналах. Не требуй создания фиктивного идентификатора, если соответствующего контекста нет.

Проверка изменений

Перед завершением:

  1. Запусти полную проверку из корня репозитория:
scripts/check-docs.sh

Скрипт вызывает mado check . с обязательной конфигурацией mado.toml и выполняет структурные проверки. Не отключай отдельные правила в документе или командной строке. Если правило мешает утверждённому формату требований, изменяй общую конфигурацию с явным обоснованием.

  1. Найди дублирующиеся ID во всём репозитории.
  2. Проверь локальные Markdown-ссылки.
  3. Проверь синтаксис и примеры JSON Schema доступным валидатором.
  4. Проверь, что каждое нормативное требование содержит ID, уровень, область применения, обоснование, проверку и исключения.
  5. Сопоставь термины и поля со связанными документами и схемами.
  6. При изменении требования найди его ID в схемах, таблицах, диаграммах и примерах и обнови связанные материалы.
  7. Проверь, что новый документ или схема указаны в README.md, а новая или перемещённая Markdown-страница включена в nav файла mkdocs.yml.
  8. Сверь навигацию README.md и меню сайта с изменёнными требованиями, затем просмотри итоговый diff и исключи несвязанные изменения.

GitLab CI запускается только для default branch. Не считай отсутствие pipeline рабочей ветки или merge request подтверждением результата и выполни все применимые проверки локально до commit и push.

Успешный scripts/check-docs.sh не доказывает содержательную корректность или полноту нормативных требований.

Готовность изменения

Перед merge или прямым commit в main проверь, что:

  • сформулированы область применения и ожидаемый результат;
  • каждое требование допускает объективную проверку;
  • устранены противоречия и дублирование с существующими правилами;
  • определены влияние на действующие проекты и обратная совместимость;
  • при необходимости описана миграция;
  • получены требуемые согласования в GitLab;
  • итоговый diff не содержит несвязанных изменений.

Commit, release-тег и push

Каждый commit, который агент создаёт или публикует как новое состояние ветки main, агент должен автоматически, без дополнительного напоминания, снабдить новым release-тегом. Для этого:

  1. получить актуальные remote main и release-теги, затем выбрать следующую свободную SemVer-версию по наиболее существенной категории изменения: PATCH — редакционное исправление без изменения смысла, MINOR — обратно совместимое дополнение, MAJOR — новое обязательство или несовместимое изменение;
  2. заменить раздел «Не выпущено» в CHANGELOG.md на версию и текущую дату;
  3. после успешных проверок убедиться, что итоговый commit содержит запись release в CHANGELOG.md, и создать новый аннотированный release-тег, указывающий на этот commit;
  4. атомарно отправить main и тег в один remote, например:
git push --atomic origin main refs/tags/vX.Y.Z

Рабочую ветку тегировать нельзя. Нельзя перемещать, перезаписывать или повторно использовать существующий release-тег. Если версию нельзя однозначно определить, remote main изменился либо атомарный push недоступен, останови публикацию и запроси решение.

Результат работы

В итоговом сообщении кратко укажи:

  • какие документы добавлены или изменены;
  • какие нормативные решения зафиксированы;
  • были ли изменены смыслы существующих требований или ID;
  • какие проверки выполнены;
  • какой release-тег создан при commit в main либо почему тег не применим;
  • какие вопросы или риски остались открыты.