Дебаты Astra × Fable02-knowledge-architecture

2. Архитектура документации и поиск контекста

Минимальная структура

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

AGENTS.md                     короткий вход для Codex
CLAUDE.md                     короткий вход для Claude Code
docs/
  index.md                    откуда начать и как выбрать маршрут чтения
  operating-model.md          роли, состояния, точки решений
  governance/                 нормы процесса и проекции полномочий
  domain/
    glossary.md
    context-map.md
    <domain>/
      index.md
      rules/                  требуемое поведение BR
      observations/           фактическое поведение OBS
      flows/                  сквозные операции
      states/                 переходы и инварианты
      examples/               проверяемые примеры
      conflicts/              расхождения и неизвестное
  architecture/
    system-context.md
    entrypoints/              HTTP, admin, команды, задачи, hooks
    runtime-flows/
    data/                     модели, транзакции, миграции, владение данными
    integrations/
    operations/
    guidelines/               текущая практика отдельно от нормы
  decisions/                  решения и их история
  runbooks/                   типовые процедуры RB
  testing/                    стратегия, baseline, данные, известные ограничения
  changes/<change-id>/        контракт, влияние, карта контекста, приёмка
  generated/                  воспроизводимые индексы и проекции
  onboarding/                 воспроизведение среды и вход новой модели
  migration/                  план внедрения процесса и оценка пилотов

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

Как выбирать единицу документации

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

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

ID, ссылки, индексы

Используйте стабильный ID с типом и уникальным суффиксом, например BR-orders-cancel-01J.... UUID/ULID или иной механизм без глобального счётчика позволяет параллельным веткам создавать записи. CI проверяет коллизии и типы. Имя файла может содержать короткий slug; ID не меняется при переименовании и не используется повторно.

Основные ссылки — обычные относительные Markdown-ссылки с понятным текстом. ID хранится в front matter и типизированных отношениях. Генератор строит реестр ID → path, проверяет ссылки и обновляет их при перемещении. Пользовательский синтаксис [[ID]] допустим как дополнительная проекция для конкретного просмотрщика, но не обязателен для чтения документации.

Индексы строятся из метаданных, а не ведутся вторым независимым источником:

  1. Корневой индекс показывает домены, стартовые ранбуки и правила входа.
  2. Индекс домена показывает правила, потоки, незакрытые вопросы и связи.
  3. Индекс ранбуков позволяет выбрать процедуру по результату и риску.
  4. Машинный реестр хранит типизированные рёбра и обратные ссылки.

Канонические рёбра: implements, tested_by, observed_in, authorized_by, depends_on, supersedes, conflicts_with. Обратные рёбра вычисляются; две редактируемые копии одной связи быстро расходятся.

Минимальные метаданные

Для каждого типа определяется небольшая схема. Пример нормы:

id: BR-orders-cancel-example
kind: business_rule
revision: 1
lifecycle: active
normative_status: accepted
freshness: current
owner_role: orders_owner
scope: orders.cancellation
authority_ref: DEC-orders-cancellation-example
implementation: pending
relations:
  implements: []
  tested_by: []

Статус наблюдения содержит дополнительно метод, условия, снимок, версию анализатора и ограничения. Ссылка на код содержит repo, commit и symbol; номера строк служат вспомогательным адресом. Для изменившегося символа связь не считается актуальной только потому, что такой путь ещё существует.

Хеш всей схемы, автора и политики не нужно вручную вписывать в каждый файл. Генератор и исполнитель вычисляют технические поля; человек подтверждает смысл. Примеры полных карточек собраны в шаблонах.

Сборка контекста задачи

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

Результат — manifest с ID/версиями, снимком исходников, основанием включения, признаками устаревания, исключениями и причиной каждого исключения. Простой вариант — скрипт, обходящий структурированные ссылки и Git diff. Семантический поиск может находить кандидатов, но не является источником полномочий или доказательством полноты.

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

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

Актуальность без циклических коммитов

Содержание нормы и наблюдения версионируется в Git. Результаты CI и текущая оценка актуальности для кандидата сохраняются как внешние attestation/report с хешами. Нельзя записать SHA коммита внутрь того же коммита как его самоподтверждение: запись изменила бы SHA.

Документ может ссылаться на проверку предыдущего снимка как на исторический источник. Для текущего PR отдельный evidence manifest связывает неизменённые материалы и результат. Производная панель состояния показывает актуальность, не требуя коммитить новое verified после каждой проверки.

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

Приёмка системы документации

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

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