Дебаты 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]] допустим как дополнительная проекция
для конкретного просмотрщика, но не обязателен для чтения документации.
Индексы строятся из метаданных, а не ведутся вторым независимым источником:
- Корневой индекс показывает домены, стартовые ранбуки и правила входа.
- Индекс домена показывает правила, потоки, незакрытые вопросы и связи.
- Индекс ранбуков позволяет выбрать процедуру по результату и риску.
- Машинный реестр хранит типизированные рёбра и обратные ссылки.
Канонические рёбра: 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, существование файлов и якорей, типы связей, достижимость важных записей и воспроизводимость проекций. Отдельные проверки сопоставляют бизнес-примеры, нормы и поведение. Линтер ссылок не может доказать семантическую согласованность текста.
Каждый документ имеет владельца области и триггер обновления. Новая задача, инцидент, изменение кода, зависимостей или решения порождает проверку влияния. «У документа свежая дата» без источников и проверки не является свидетельством актуальности. Достаточность оценивается на задачах, как описано в главе об оценке.