docs: make project documentation self-contained

development/agent-token-efficiency.md

@@ -1,62 +1,42 @@
-# Context discipline
+# Контекст знаний о системе
 
-Цель — получить правила, которые меняют текущее решение, и не читать остальные
-заранее. Это процедура прямой работы по задаче, без обязательных SDD artifacts,
-ролей, approval fingerprints или подсчёта документов как delivery gate.
+Цель навигации — дать читателю знания, необходимые для конкретного вопроса,
+без предварительного чтения всей документации. Самостоятельное объяснение
+связывает понятия, сценарии и ограничения, а не воспроизводит устройство кода.
 
 ## Routing context
 
-1. Определи требуемое поведение, тип решения и affected repos до supporting reads.
-2. Прочитай root/local AGENTS, затем CONVENTIONS и SOURCES affected code repo.
-3. Объедини сработавшие semantic, path и boundary triggers. Путь — сигнал ответственности, а не повод загружать всё по расширению `.tsx`/`.ts`.
-4. Прочитай выбранные conventions или явно указанные sections до зависимого решения. При domain/API/security вопросе открой точный source через [docs index](../AI_INDEX.md).
-5. Проследи ближайший существующий owner и подходящие код/тесты. Его поведение не заменяет canonical fact.
-6. Повтори routing при новой потребности и по финальным staged, unstaged и новым файлам. Содержимое работы важнее первоначального названия задачи.
-
-Первый проход работает без diff. Auth + refresh, например, активирует API,
-security и testing вместе. Отображение query state без изменения запросов не
-добавляет transport rules. Docs-only опечатка не требует frontend/backend conventions.
-Обычно хватает нескольких тем; это наблюдение, не лимит. Обязательный source
-нельзя пропускать ради числа файлов или token budget.
-
-Новая граница внутри задачи требует дочитать правила до работы. Расширение
-самой задачи сначала сообщи пользователю; уже данное разрешение не запрашивай
-повторно. Чужой concurrent diff учитывай при разграничении ownership.
+[Тематический индекс](../AI_INDEX.md) направляет к нужному предмету:
+аутентификация связана с безопасностью и сессиями, денежный показатель —
+с его происхождением и валютой, ошибка интерфейса — с восстановлением данных.
+Вопрос о внешнем виде не требует автоматически изучать хранение данных.
+При обнаружении новой существенной границы расширяется и нужный контекст.
 
 ## Источники и конфликты
 
-Прямое указание пользователя определяет задачу. Текущий executable HTTP contract
-генерируется backend; docs описывает проектные факты/решения; conventions задают
-выбор реализации; code показывает существующие аналоги. Generic framework advice
-используется после проектных источников. Research содержит рекомендации, которые
-нужно сверить с actual code/config, а не автоматически превращать в новый контракт.
+Публичный HTTP-контракт описывается OpenAPI backend; документация объясняет
+систему, ADR сохраняют причины решений, исследования предлагают варианты.
+Существующее поведение не отменяет согласованное требование, а рекомендация
+из исследования не становится принятым решением автоматически.
 
-Если задача намеренно меняет контракт, обновляй его source и зависимые материалы
-согласованно. Missing input, противоречие security/data правил или неоднозначный
-контракт блокируют только зависимое решение до установления фактов/уточнения.
-История чата, случайный аналог и предполагаемый путь не заменяют источник.
+При расхождении возможны устаревшее объяснение, дефект реализации или
+незавершённое изменение. Неустановленный смысл, особенно в безопасности,
+данных и публичном контракте, явно отмечается для ручного решения.
+Карта ответственности за знания — [ведение документации](documentation.md).
 
 ## Recovery и handoff
 
-Для продолжения достаточно текущей задачи, сделанных изменений, remaining work,
-точных checks/results и blockers. Не создавай параллельную копию требований,
-Design, state registry или обязательный handoff-файл.
-
-В новом контексте восстанови необходимые sources; в том же переиспользуй уже
-прочитанные неизменившиеся inputs. Supporting reads добавляй по возникшему вопросу.
-Git status/diff показывают staged и unstaged; новые файлы учитывай отдельно.
-Relevant ignored/workspace-owned inputs (например `.env`, root AGENTS) не
-теряются только потому, что Git их не показывает. Секреты в evidence не печатай.
+Продолжение работы опирается на ожидаемый результат, выполненные изменения,
+оставшиеся вопросы, результаты проверок и ограничения. Дублирование требований
+в нескольких независимых пересказах создаёт риск расхождения. Исторические
+проверки сохраняют своё значение только для того состояния системы, в котором
+они выполнялись; секреты не являются допустимым содержимым свидетельств.
 
 ## Проверка эффективности
 
-Используй [набор routing cases](agent-context-evals.md) для настройки новых правил.
-Проверяй activating case, safe exception и unrelated counterexample по реальным
-инструкциям. Source links и gates дополняют эту проверку, но не доказывают first-pass quality.
-
-Сравнивай startup context и реально выбранные sections, фиксируя способ измерения.
-Не объявляй меньшее число файлов или зелёный application test улучшением качества
-агента. Для first-pass acceptance нужны одинаковые реальные задачи/модель/tools,
-наблюдённые ошибки ownership/contract/security и число исправлений.
-Добавляй convention по повторяющейся decision error; уточняй trigger при missed
-source; deterministic regression отдавай существующему test/linter, если он подходит.
+[Проверочные вопросы](agent-context-evals.md) показывают, можно ли получить
+правильную модель системы и отличить близкие понятия. Качество оценивается по
+верности ответа, найденным ограничениям и необходимости дополнительных уточнений.
+Число документов, их краткость или успешная проверка Markdown сами по себе
+не доказывают полезность знания. Сравнение результатов требует одинаковых
+вопросов и сопоставимых условий.