Соглашения для многоповерхностных окружений

Каноническая нормативная справка для нижестоящих участников. Этот документ отражает разделы спецификации проекта «Соглашения для многоповерхностных окружений» (Спецификация §0.6 + §2.8 + §4.7); это самостоятельная справка, которая поставляется вместе с опубликованным репозиторием. Архитектурное обоснование зафиксировано в ADR-0003.

1. Почему во множественном числеCopy Anchor Link

Современную инженерную поверхность затрагивают несколько окружений — чат-консоли, движки автодополнения внутри IDE, компаньоны для парного программирования и рецензенты pull request. Каждое из них читает собственный канонический файл конфигурации. Если проект поставляет только один такой файл, остальные среды выполнения молча импровизируют, опираясь на невысказанные соглашения; отсутствие памяти внутри репозитория проявляется сразу же.

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

Конфигурация сред выполнения окружений множественна в силу реальности развёртывания. Опубликованная экосистема ДОЛЖНА поставлять три обязательные поверхности, перечисленные в §3: AGENTS.md, файл поведенческой памяти для среды выполнения чат-консоли (CLAUDE.md) и файл инструкций уровня репозитория для среды автодополнения внутри IDE. Эти поверхности ДОЛЖНЫ быть взаимно согласованы — без противоречий, без дрейфа — и ДОЛЖНЫ совместно кодировать одни и те же дисциплины.

2. Контракт согласованностиCopy Anchor Link

Каждая поверхность соглашений, входящая в область действия (§3), — это канал, выражающий единую спецификацию соглашений проекта. Спецификация раскладывается на:

• Общие разделы — дисциплина планов, структурированный запрос (или эквивалент для поверхности), заголовок авторства, именование, антипаттерны, модальная иерархия. Они ДОЛЖНЫ присутствовать в каждой обязательной поверхности и ДОЛЖНЫ быть семантически эквивалентны во всех поверхностях.
• Разделы, специфичные для поверхности — описания возможностей, шаблоны вызова инструментов, различия между генерацией кода и чатом. Они МОГУТ различаться между поверхностями, но НЕ ДОЛЖНЫ противоречить общим разделам.

Валидатор multi-surface-coherence (§7) выполняется при каждом прогоне CI и в pre-commit, проверяя соблюдение контракта.

Поверхности — это разные каналы, выражающие одну спецификацию. Общие разделы ДОЛЖНЫ совпадать во всех поверхностях — семантически и, где возможно, лексически. Разделы, специфичные для поверхности, НЕ ДОЛЖНЫ противоречить общим разделам.

3. Поверхности в области действияCopy Anchor Link

Для этого репозитория поверхности, подключаемые по явному согласию, — это те, которые фикстура списка утверждений (tests/fixtures/multi-surface-claims.yaml) перечисляет под ключом optional-in. Неиспользуемые корневые конфигурации, специфичные для вендоров, намеренно отсутствуют; файл конфигурации, специфичный для инструмента, добавляется только тогда, когда этот инструмент является активной поверхностью редактирования для этого репозитория.

4. Список разделов файла инструкций внутри IDECopy Anchor Link

Файл инструкций уровня репозитория в .github/ ДОЛЖЕН содержать в указанном порядке следующие разделы (каждый с точным текстом заголовка, приведённым ниже; тела разделов пишутся вручную, а не штампуются по шаблону, но каждый раздел ДОЛЖЕН охватывать перечисленные утверждения):

1. Project Context — один абзац: что представляет собой этот репозиторий, кто им пользуется, какова его структура верхнего уровня. Конкретно, без маркетинга.
2. Coding Conventions — именование, модальная иерархия, фронтматтер, стиль Markdown, особенности стиля для конкретных языков там, где они отличаются от умолчаний.

3. File Headers — каждый файл, который генерирует среда выполнения, ДОЛЖЕН начинаться с канонической единственной строки SPDX-License-Identifier: MIT согласно site/content/docs/reference/authorship-header.mdx, в варианте комментария, соответствующем типу файла. Указатель на scripts/inject-header.* и site/content/docs/reference/authorship-header.mdx.

4. Plans Discipline — среда выполнения НЕ ДОЛЖНА генерировать код или скрипты, которые записывают в каталог конфигурации окружения (например, ~/.claude/plans/ или ~/.codex/.plans/) или в любое другое глобальное расположение планов. Артефакты планирования размещаются в <project-root>/.apothem/plans/ (устаревшее дерево <project-root>/.plans/ обновляется через apothem migrate-workspace) согласно site/content/docs/reference/plans-discipline.mdx.
5. Structured Inquiry Behavior — когда среда выполнения не уверена, она НЕ ДОЛЖНА молча выдумывать. Вместо этого она вставляет чётко помеченный блок уточнения (например, комментарий # TODO(clarify): <question>) и выносит вопрос в чат, где это позволяет поверхность. Никаких выдуманных API, выдуманных названий моделей, выдуманных путей к файлам.
6. Forbidden Patterns — явные запреты: никаких маркетинговых прилагательных, никаких уклончивых слов-заполнителей, никакого отладочного мусора в виде console.log, никаких жёстко заданных абсолютных путей к домашнему каталогу пользователя, никаких коммитов секретов, никаких коммитов файлов в .apothem/plans/ (или в устаревшем .plans/), никаких противоречий каноническому файлу инструкций проекта.
7. Output Format — сгенерированный код/текст соответствует единым соглашениям о диалоговом выводе: определённость, единообразное разбиение на разделы, плотность, дисциплина резюме, цитирование. Для кода: документированная публичная поверхность, типизация там, где язык поддерживает типы, тесты там, где есть тестовый каркас.
8. Review Checklist — что рецензент (человек или среда выполнения в режиме ревью PR) ДОЛЖЕН проверить перед одобрением: заголовок присутствует, именование соответствует соглашениям, нет записей в .apothem/plans/, нет противоречий с каноническим файлом инструкций проекта, валидаторы локально зелёные.
9. Pointers — ссылки на AGENTS.md, CLAUDE.md, site/content/docs/reference/plans-discipline.mdx, site/content/docs/reference/authorship-header.mdx, этот документ соглашений, src/apothem/schemas/ и CONTRIBUTING.md.

Файл начинается с канонической SPDX-строки заголовка авторства (вариант для Markdown) согласно site/content/docs/reference/authorship-header.mdx §2 — видимой или невидимой в зависимости от выбранной проектом политики видимости заголовка.

Файл инструкций внутри IDE не является дословной копией AGENTS.md или CLAUDE.md. AGENTS.md — каноническая поверхность инструкций проекта, CLAUDE.md отражает её для Claude Code, а файл инструкций внутри IDE написан для среды автодополнения кода внутри редактора, которая выдаёт предложения, принимаемые или отклоняемые разработчиком. Информация (дисциплины, соглашения, антипаттерны) идентична; различается подача.

5. Справка по списку утвержденийCopy Anchor Link

Фикстура tests/fixtures/multi-surface-claims.yaml перечисляет каждое общее утверждение. Примеры записей:

- id: plans.location
  claim: "Planning artifacts live at <project-root>/.apothem/plans/, never inside a harness configuration directory."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
  optional-in: [site/content/docs/architecture/agents.mdx, .cursorrules]
- id: header.canonical
  claim: "Every applicable new file begins with the canonical SPDX-License-Identifier: MIT header line, in the comment family matching the filetype."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
- id: ambiguity.resolution
  claim: "Ambiguity is surfaced via the structured-inquiry channel or a clearly-marked TODO(clarify); never silently invented."
  required-in: [AGENTS.md, CLAUDE.md, .github/copilot-instructions.md]
# ... (one entry per shared claim)

Валидатор разбирает каждую поверхность, пытается найти присутствие каждого утверждения в поверхности (по иерархии заголовков + извлечению ключевых слов из тела) и завершается с ошибкой при любом пропуске или противоречии.

6. Правило согласованияCopy Anchor Link

Когда обнаруживается, что две поверхности противоречат друг другу в общем утверждении, согласование по умолчанию таково:

AGENTS.md — канонический голос проекта. Любая противоречащая поверхность переписывается так, чтобы отражать семантику AGENTS.md в подаче, подходящей для этой поверхности.

Переопределение, специфичное для поверхности, допускается только при наличии явного маркера <!-- coherence-override: <claim-id> --> в самом файле, указывающего на ADR, который объясняет намеренное расхождение. Сам маркер переопределения перечислен в списке разрешений валидатора и отображается в отчёте CI.

Для этого репозитория утверждённая стратегия согласования — agents-md-wins: AGENTS.md является каноническим, а каждое активное зеркало для окружений остаётся семантически эквивалентным.

7. ВалидаторыCopy Anchor Link

Три валидатора совместно реализуют контракт согласованности:

- in-IDE-instructions-presence    (src/apothem/conformity/copilot_instructions_presence_grep.py)
- multi-surface-coherence         (src/apothem/conformity/multi_surface_coherence_grep.py)
- license-author-consistency      (src/apothem/conformity/license_author_consistency_grep.py)

• Первый проверяет, что файл инструкций внутри IDE существует, разбирается, содержит каждый канонический раздел, перечисленный в §4, и начинается с канонической строки SPDX-License-Identifier: MIT (вариант для Markdown).
• Второй разбирает канонические разделы каждой поверхности и проверяет, что общие разделы взаимно согласованы при нормализованном сравнении (без учёта регистра, с допуском различий в пробелах, с разрешением лексического перефразирования, но с требованием семантической эквивалентности по списку утверждений, заданному фикстурой).
• Третий проверяет только то, что корневой LICENSE содержит разбираемую строку Copyright (c) <name>. Он не читает пофайловые заголовки, которые не содержат имени автора.

8. Жизненный цикл поверхностиCopy Anchor Link

• Добавить поверхность. Оператор явно подключает её через канал структурированного запроса. Генератор создаёт поверхность по списку утверждений, запускает валидатор и оформляет ADR, если нужно переопределение, специфичное для поверхности.
• Удалить поверхность. Структурированный запрос подтверждает удаление, ADR фиксирует обоснование, список required-in валидатора изменяется.
• Обнаружение дрейфа. Любой коммит, расходящийся со списком утверждений, отклоняется pre-commit / CI; автор коммита переписывает поверхность, чтобы восстановить согласованность.

См. такжеCopy Anchor Link

• ADR-0003 — архитектурное обоснование, рассмотренные альтернативы.
• tests/fixtures/multi-surface-claims.yaml — каноническая фикстура списка утверждений.
• AGENTS.md — канонический голос проекта.
• CLAUDE.md — зеркало для Claude Code.
• site/content/docs/reference/plans-discipline.mdx — каноническая справка по общему утверждению о дисциплине планов.
• site/content/docs/reference/authorship-header.mdx — каноническая справка по общему утверждению о заголовке авторства.
• Спецификация проекта §0.6 + §2.8 + §4.7 — полный канонический текст, отражённый здесь.