Table of Contents

Вернуться к курсу по взаимодействию ИИ

После утверждения устава сопровождающий настраивает границу публикации с приоритетом GitHub. Требования, конфигурация, политика и runbook находятся в одном временном репозитории. Участники предлагают изменения через Issues и pull request. Вы задаёте расположение утверждённых фактов и блокируете непроверенные изменения до подключения агентов.

Главное

  • Защищённая main является границей публикации.
  • Issues собирают предложения, но не утверждают политику.
  • CODEOWNERS назначает подходящих проверяющих файлов.
  • Раздельные учётные записи позволяют продемонстрировать проверку и отказ.

Перед началом

Предварительные условия: основа пилота , распакованная лаборатория, администратор репозитория и отдельные проверяющие от продукта и эксплуатации. Расчётное время: 60 минут. Сложность: средняя.

Граница плана: GitHub документирует защищённые ветки для публичных репозиториев в Free и частных репозиториев в Pro, Team или Enterprise. В публичных репозиториях используйте только синтетические данные. Перед тем как полагаться на принудительное применение правил, проверьте видимость и тариф в документации по защите веток.

Результат: защищённая ветка публикации, владельцы файлов, карта источников и записанный как доказательство тест отказа.

Создание репозитория

  1. Создайте export-service-lab с README и веткой по умолчанию main.
  2. Скопируйте распакованную лабораторию в корень репозитория, сохранив check.py, test_check.py и baseline/. Скопируйте исходные записи из baseline/ в корень.
  3. Создайте docs/project-map.md на основе реестра пилота. Добавьте docs/policy.md с утверждённым POL-01.
  4. Создайте docs/decisions/DEC-12.md с одобрением устава, ролями, решением по базовой версии и статусом.
  5. Зафиксируйте начальную конфигурацию от имени администратора. Запишите это первоначальное исключение. Включите защиту до следующих изменений.

Локальная первоначальная настройка в Git Bash, Терминале macOS или оболочке Linux: войдите в GitHub через браузер, откройте новый репозиторий, выберите Code и скопируйте HTTPS URL для клонирования. В одноразовом рабочем каталоге выполните команды ниже. Замените два примера путей URL и путём загруженного ZIP лаборатории. Не вставляйте токен в URL.

git --version
git clone "https://github.com/OWNER/export-service-lab.git"
cd export-service-lab
unzip -n "/absolute/path/to/ai-collaboration-lab.zip"
cp baseline/config.json baseline/policy.json baseline/proposal.json baseline/requirement.json baseline/runbook.md .
mkdir -p docs/decisions
git status --short

Команда clone должна создать каталог репозитория. Если unzip недоступен, распакуйте ZIP файловым менеджером и скопируйте содержимое в этот checkout, сохранив README репозитория. git status --short должен показать скопированные записи, checker, тесты и baseline/ как новые файлы. Сохраните docs/project-map.md, docs/policy.md и docs/decisions/DEC-12.md из пакета пилота с помощью текстового редактора. Затем выполните:

git add README.md baseline check.py test_check.py config.json policy.json proposal.json requirement.json runbook.md docs
git commit -m "Add synthetic collaboration baseline"
git push origin main
git status --short
git remote -v

Git должен сообщить новый идентификатор коммита, а затем успешный push в main. В конце краткий статус должен быть пустым. Откройте репозиторий GitHub в новом окне браузера и подтвердите, что файлы и идентификатор коммита отображаются в main. Сохраните URL коммита как доказательство первоначальной настройки. Если Git запросит данные автора, выполните инструкции по настройке в центре курса. Если аутентификация не сработает, используйте поддерживаемый GitHub способ управления учётными данными и повторите тот же push. Если ветка или remote указаны неверно, остановитесь и проверьте git branch --show-current и git remote -v перед следующей записью. Если push отклонён из-за уже включённой защиты, откройте ветку предложения и PR вместо обхода правила. Также доступен следующий путь настройки только через браузер с помощью сопровождающего.

Запись Расположение Владелец
POL-01 policy.json, docs/policy.md Владелец политики
REQ-17 requirement.json Владелец продукта
RUN-04 runbook.md Владелец эксплуатации
Поведение config.json Сопровождающий репозитория
Решения docs/decisions/ Руководитель проекта

Карта указывает расположение, а не копирует значения. В README оставьте инструкции по настройке и карту. Повторяющиеся требования по хранению данных приводят к дрейфу даже в одном репозитории.

Назначение владельцев файлов

Локально создайте .github/CODEOWNERS с реальными идентификаторами учётных записей в песочнице. Вводите их без начального символа @. Идентификаторы аккаунтов храните в частной лаборатории, а не в открытых доказательствах упражнения.

python3 - <<'PY'
from pathlib import Path
roles = ['product', 'operations', 'maintainer', 'policy']
handles = {r: input(r + ' GitHub handle: ').strip().lstrip('@') for r in roles}
if any(not h or not all(c.isalnum() or c == '-' for c in h) for h in handles.values()):
    raise SystemExit('Invalid handle')
paths = {'requirement.json': 'product', 'runbook.md': 'operations',
         'config.json': 'maintainer', 'policy.json': 'policy',
         'docs/policy.md': 'policy', 'AGENTS.md': 'policy',
         'CLAUDE.md': 'policy', '.clinerules/': 'policy',
         '.github/': 'maintainer', 'check.py': 'maintainer',
         'test_check.py': 'maintainer', 'baseline/': 'maintainer'}
Path('.github').mkdir(exist_ok=True)
Path('.github/CODEOWNERS').write_text(''.join(
    '/' + path + ' @' + handles[role] + '\n' for path, role in paths.items()))
PY

Для распознавания GitHub владельцам нужен доступ на запись. Проверьте файл CODEOWNERS в браузере на ошибки. Защитите файлы владения и определения рабочих процессов наравне с обычным содержимым.

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

Защита публикации

  1. Откройте Settings, Branches и добавьте правило защиты ветки main. В этом упражнении последовательно используйте защиту ветки, не смешивая её с ruleset.
  2. Требуйте pull request, два одобрения и проверку владельцами кода.
  3. Сбрасывайте устаревшие одобрения после новых коммитов и требуйте разрешать обсуждения.
  4. Включите запрет обхода указанных выше настроек. Отключите принудительные push и удаление.
  5. Добавьте проверку согласованности после её первого запуска в следующем модуле. Перед слиянием требуйте актуальную ветку.

Два одобрения задают число, а не членство в бизнес-роли. CODEOWNERS добавляет покрытие владельцев по путям. Сопровождающий также проверяет подтверждения двух ролей. Явно запишите эту процедурную меру, а не описывайте её как автоматическое принудительное назначение двух ролей.

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

Проверка границы

Попытка Ожидаемый результат
Участник отправляет ветку Предложение разрешено
Участник публикует напрямую Защищённая публикация запрещена
Один проверяющий одобряет Слияние блокирует порог проверок
После проверки появляется новый коммит Требуется новое одобрение
Для чувствительного файла нет владельца Исправить до публикации

Проверьте путь из браузерной сессии участника. Веб-редактор GitHub не редактирует защищённую ветку main. Предложение создать ветку показывает поддерживаемый браузерный путь. Оно не доказывает, что сервер отклонил прямой push. Для доказательства отказа платформы попросите участника с утверждённым локальным доступом Git выполнить безвредную попытку прямого push в защищённую ветку main и сохраните ответ сервера. Если локальный доступ недоступен, отметьте тест отказа как заблокированный.

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

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

Роль участника: участник проекта
Попытка: безвредная синтетическая прямая отправка в main
Результат удалённого репозитория: отклонено, обновление защищённой ветки запрещено
Начальный коммит main: [запишите коммит sandbox]
Итоговый коммит main: [запишите тот же коммит после повторного чтения]
Решение: отказ платформы подтверждён только если наблюдались обе записи

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

Создание полезной карты источников

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

Проект: export-service-lab
Трек: GitHub-first
Утверждённая граница: защищённая main

REQ-17 -> requirement.json
  Полномочие: намерение по хранению синтетических файлов экспорта
  Ответственный: product-owner
  Ревизия: укажите ревизию и защищённый коммит

RUN-04 -> runbook.md
  Полномочие: инструкции по работе с синтетической лабораторией
  Ответственный: operations-owner
  Ревизия: защищённый коммит

Поведение -> config.json
  Полномочие: зафиксированная конфигурация хранения
  Ответственный: repository-maintainer
  Ревизия: защищённый коммит

Предложения -> Issues и ветки предложений
  Полномочие: только запрошенные изменения

Не указывайте текущее значение хранения данных в каждой записи карты. Карта со значением «семь дней» станет ещё одним значением, которое нужно синхронизировать после PROP-042. Храните в карте стабильные идентификаторы и расположения, а значение читайте из авторитетной записи.

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

Разделение базы и кандидата

Корень репозитория содержит активные записи лаборатории. Загруженный каталог baseline/ — учебная заготовка. Он не становится автоматически защищённой базой для каждого следующего PR. После попадания проверенной работы в main защищённые записи в корне становятся базой следующего предложения.

Расположение Назначение Редактировать в PROP-042?
Корневые requirement/config/runbook Активные записи-кандидаты в ветке Да, через проверенные изменения
baseline/ Исходная заготовка офлайн-упражнения Нет
Отделённый доверенный worktree Снимок защищённых корневых записей Нет
context.json Доказательство байтов захваченной базы Перегенерировать после согласования

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

Проверка всего изменения

Перед принятием описания PR откройте Files changed. Описание объясняет намерение автора. Diff показывает отправленное изменение. В PROP-042 проверьте ревизию требования, исключения области, конфигурацию, runbook, базу предложения и доказательства манифеста.

  1. Проверка продукта: подтвердите намерение на тридцать дней и неизменность исключений.
  2. Проверка эксплуатации: убедитесь, что runbook соответствует предлагаемой конфигурации и сохраняет ограничение среды выполнения.
  3. Проверка сопровождающего: изучите JSON, захват источника, результаты проверок и посторонние изменения.
  4. Проверка контроля: отдельно изучите изменения карты, политики, CODEOWNERS или рабочего процесса.

Зелёная проверка не объясняет постороннее удаление. Если ветка удаляет документ политики при изменении срока хранения, запросите отдельное предложение или конкретную проверку владельца. Ограниченная область делает объект проверки понятнее.

Диагностика теста отказа

Для каждой строки доказательств используйте одну попытку действия. Формулировка «у участника не получилось» неоднозначна. У пользователя может не быть обычного доступа на запись, он может столкнуться с ограничением браузера или попасть под ожидаемое правило ветки. Это разные наблюдаемые границы.

Наблюдение Интерпретация Дальнейший шаг
Не удаётся создать ни одной ветки Нет доступа к внесению изменений Использовать утверждённый путь через Issue или fork
Ветка создаётся, публикация в main недоступна Проверенный путь публикации ограничен Зафиксировать неизменную ревизию main
Слияние блокирует одна проверка Порог проверок действует на этот PR Добавить подтверждение по роли
Администратор публикует несмотря на правило Проверенная личность обходит границу Проверить настройки обхода и права

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

Проверка завершения репозитория

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

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

Устранение неполадок и откат

Нет запроса владельца: подтвердите доступ на запись и покрытие пути базовой ветки. Защита отсутствует: проверьте план и видимость. Слияние всё ещё возможно: проверьте цель правила, обход защиты и число проверок.

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

Упражнение и самопроверка

Предложите как участник изменить docs/policy.md. Решите, подтверждает ли одно одобрение сопровождающего согласие владельца политики.

Ожидаемое рассуждение: число проверок само по себе не подтверждает полномочия. Для этого пути нужны покрытие владельцем политики и актуальная проверка роли. Перечислите не принудительно применяемые требования к ролям как процедурные меры.

Основные источники

Следующие шаги

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