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

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

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

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

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

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

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

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

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

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

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

3. Поверхности в области применения

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

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

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

1. Project Context — один абзац: чем является этот репозиторий, кто его использует, его верхнеуровневая форма. Конкретно; без маркетинга.
2. Coding Conventions — именование, модальная иерархия, frontmatter, стиль 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, этот документ соглашений, 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. Справка по списку утверждений

Фикстура в 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 authorship-header banner per site/content/docs/reference/authorship-header.mdx."
  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. Правило согласования

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

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

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

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

7. Валидаторы

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

- 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, и начинается с канонического баннера авторства.
• Второй разбирает канонические разделы каждой поверхности; утверждает, что общие разделы взаимно согласованы при нормализованном компараторе (нечувствительном к регистру, толерантном к пробелам, допускающем лексический парафраз, но требующем семантической эквивалентности по списку утверждений, определённому фикстурой).
• Третий утверждает, что строка авторских прав LICENSE и строка «Copyright (c)» канонического баннера называют одного и того же автора.

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

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

См. также

• 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 — полный канонический текст, отражённый здесь.