Подключение стандартов к прикладному проекту¶

Ненормативный пример. Иллюстрирует STD-MAN-001, STD-MAN-002, STD-MAN-003, STD-MAN-004, STD-MAN-005, DEV-ADR-001, DEV-ADR-002, AI-DEV-001, AI-DEV-002, AI-DEV-006 и DEV-VER-003. Фрагменты нельзя копировать без выбора фактических компонентов, команд и версии стандартов.

Ограничения применимости: пример показывает один GitLab-проект с backend API, frontend, Docker image и разработкой с участием ИИ-агента. Он не определяет язык, framework, способ доставки checkout стандартов, набор project tests, protected-branch rules или production pipeline.

Итоговая структура¶

orders/
├── .standards/
│   └── standards.yaml
├── docs/
│   ├── adr/
│   └── api/
│       └── openapi.yaml
├── services/
│   ├── orders-api/
│   └── customer-web/
├── AGENTS.md
├── Dockerfile
├── Makefile
└── .gitlab-ci.yml

Checkout стандартов в примере доступен CI и разработчику по отдельному пути /workspace/standards. Он не является частью показанного дерева.

Точка входа агента¶

Корневой AGENTS.md проекта может иметь следующую форму:

# Инструкции проекта orders

Перед изменением прочитай `.standards/standards.yaml`, затем получи
зафиксированную версию стандартов и выполни:

    make standards-check
    make standards-context

Локальные решения находятся в `docs/adr`, HTTP-контракт —
в `docs/api/openapi.yaml`.

Запуск:

    make dev

Обязательные проверки:

    make standards-check
    make lint
    make test
    make integration-test

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

Реальные команды должны существовать в проекте. Пустые каталоги ADR в рабочем проекте могут содержать версионируемый README, чтобы ссылка имела стабильную цель.

Показанные команды могут быть определены в Makefile проекта:

STANDARDS_DIR ?= /workspace/standards
STANDARDS_CLI = python3 $(STANDARDS_DIR)/scripts/standards.py
STANDARDS_MANIFEST = .standards/standards.yaml

standards-check: ; $(STANDARDS_CLI) check $(STANDARDS_MANIFEST) --project-root .

standards-context: ; $(STANDARDS_CLI) context $(STANDARDS_MANIFEST) --project-root . --depth index --format json

STANDARDS_DIR должен указывать на чистый checkout версии из manifest, а Python environment — содержать зависимости из requirements-cli.lock.

Manifest¶

schema_version: 3
standards:
  tag: v0.1.0
  commit_sha: 0123456789abcdef0123456789abcdef01234567
project: platform/orders
owner:
  name: Orders team
  contact: "#orders-team"
  escalation: on-call/orders
components:
  - id: orders-api
    kind: backend
  - id: customer-web
    kind: frontend
capabilities:
  - id: orders-http
    type: http-api
    providers:
      - orders-api
    consumers:
      - customer-web
  - id: orders-image
    type: container-image
    providers:
      - orders-api
  - id: agent-work
    type: ai-assisted-development
    providers:
      - orders-api
      - customer-web
targets:
  - name: local
    environment: local
    platform: local-workstation
    runtime: compose
    availability: single-instance
    delivery: local
    configuration:
      project: platform/orders
      path: deploy/compose
    capabilities: []
  - name: production
    environment: production
    platform: kubernetes-eu-1
    runtime: kubernetes
    namespace: orders-production
    availability: high-availability
    failure_tolerance:
      - worker-node
      - control-plane-node
    delivery: gitlab-ci-agent
    configuration:
      project: platform/orders
      path: deploy/kubernetes/overlays/production
    capabilities: []

Для возможности без producer/consumer-взаимодействия providers обозначает компоненты, которые её реализуют, исполняют или публикуют. Поэтому у agent-work это компоненты, над которыми работает агент, а у orders-image — компонент, чей image собирается.

Согласованное исключение¶

Если проекту действительно требуется принятое исключение, manifest дополняют ссылкой на применимый ID и ADR:

exceptions:
  - requirement_id: BE-CONF-001
    adr: docs/adr/exception-runtime-config.md

Указанный файл имеет обязательный front matter и содержательную часть:

---
id: exception-runtime-config
status: accepted
requirement_id: BE-CONF-001
expires_on: 2099-12-31
---

# Временное исключение для runtime-конфигурации

## Контекст и причина

Синтетическое описание причины, по которой требование временно невыполнимо.

## Риски

Закрытый перечень принятых рисков.

## Компенсирующие меры

Проверяемые временные меры.

## Владелец

Команда или роль, отвечающая за устранение исключения.

## Условия пересмотра

Проверяемое событие или критерий досрочного пересмотра.

Дата в реальном ADR выбирается по сроку допустимого отклонения, а не переносится из примера. check принимает только status: accepted, совпадающий requirement_id, уникальный ID ADR-исключения и дату, которая ещё не прошла по UTC.

Локальная проверка¶

standards=/workspace/standards
project=/workspace/orders

python3 "${standards}/scripts/standards.py" check \
  "${project}/.standards/standards.yaml" \
  --project-root "${project}"

python3 "${standards}/scripts/standards.py" context \
  "${project}/.standards/standards.yaml" \
  --project-root "${project}" \
  --depth index \
  --format json

check должен завершиться кодом 0. Индекс context перечислит требования, области применения и исключения. Для краткого объяснения причин можно отдельно выполнить explain; среди прочего он подключит:

docs/architecture/development/ai-assisted-development.md
  <- capability agent-work type=ai-assisted-development
docs/architecture/backend/http-api.md
  <- capability orders-http provider=orders-api
docs/architecture/frontend/api-integration.md
  <- capability orders-http consumer=customer-web kind=frontend
docs/architecture/deployment/dockerfile.md
  <- capability orders-image type=container-image

Если этап audit внутри check найдёт Dockerfile, но container-image не объявлен, команда завершится кодом 2 и напечатает предупреждение. Это означает необходимость исправить manifest либо структуру проекта, а не разрешение игнорировать результат.

Минимальный CI job¶

standards:
  stage: validate
  script:
    - python3 "$STANDARDS_DIR/scripts/standards.py"
        check .standards/standards.yaml --project-root .

Переменная STANDARDS_DIR, установка зависимостей из requirements-cli.lock и получение чистого checkout должны быть явно определены воспроизводимой CI-конфигурацией. Отдельный yq не требуется. Job дополняет, но не заменяет project tests, security checks и проверки применимых требований.