# AGENTS.md ## О проекте Книга **«От чёрного ящика к инженерии»** — практическое руководство по механике LLM, промпт-протоколам, агентным контурам и AI-friendly разработке. Контекст — апрель 2026: фронтирные модели (Claude Opus 4.6 и выше, GPT-5.x (включая GPT-5.4, GPT-5.3 Instant и Codex), Gemini 3.x, Grok 4.x, Llama 4, DeepSeek-V3, Qwen3 и выше, GLM-5.1, MiniMax M2.7), гибридные архитектуры (Transformer + Mamba/SSM + MoE), reasoning через test-time compute, агенты в production. Аудитория — software-инженеры, ML-инженеры, техлиды и архитекторы, которые строят системы на LLM и хотят перейти от интуитивного промптинга к предсказуемой инженерии. ### Структура репозитория | Путь | Назначение | |------|-----------| | `book/` | Основной редактируемый корпус. 26 глав: `00_introduction.md` … `25_summary_and_references.md` | | `.github/agents/` | Специализированные агенты для оркестрации review, research, fact-checking и точечных правок книги | | `.github/instructions/` | Дополнительные инструкции для работы с рукописью и review-workflow | | `.github/prompts/` | Готовые entrypoint-промпты для оркестрированных сценариев работы с книгой | | `.github/review-cache/` | Долговременный кэш источников, topic files и scope log для повторяемого fact-checking и research | | `scripts/build_book_pdf.py` | Скрипт сборки PDF из `book/` | | `scripts/validate_book_format.py` | Валидатор Markdown-форматирования и структурных правил для `book/` | | `build_pdf.command` | Обёртка для локального запуска сборки (macOS) | | `build_pdf_ebook.command` | Обёртка для ebook/Kindle-сборки (macOS) | | `build_pdf_phone.command` | Обёртка для phone-сборки под узкий экран (macOS) | | `BlackboxBook.pdf` | Артефакт сборки. Не редактируется вручную | ### Карта глав | Главы | Блок | Содержание | |-------|------|-----------| | 0 | Введение | Зачем понимать механику, для кого книга, как читать | | 1–5 | Фундамент | Токены, embeddings, attention, MLP, галлюцинации, каузальное декодирование, длинный контекст | | 6–9 | Протоколирование | Промпт как контракт, XML-разметка, многогипотезная генерация, chain-of-thought, декомпозиция | | 10–13 | Архитектура | Агент ≠ чат, tool use, RAG-пайплайны, антигаллюцинационный контур, верификация | | 14–15 | Качество и безопасность | Evals (golden sets, LLM-as-Judge, regression gates, failure taxonomy), безопасность (prompt injection, jailbreaks, red-teaming, guardrails, tenant isolation) | | 16–17 | Код и наблюдаемость | AI-friendly код, LDD, observability (OpenTelemetry, SLO, incident response) | | 18–20 | Продвинутые темы | Мультимодальные системы, дообучение и post-training, паттерны проектирования | | 21–22 | Serving и runtime | Inference pipeline, KV-кэш, PagedAttention, batching, quantization, durable orchestration, жизненный цикл агента | | 23 | Внедрение | Минимальный контур, метрики, постепенная интеграция | | 24 | Ландшафт | Гибриды (Mamba + Transformer + MoE), reasoning-модели, SLM и edge-first, длинный контекст и мультимодальность, Diffusion LLM, open-weight frontier, MCP-экосистема, экономика inference | | 25 | Резюме | Принципы LLM-инженерии, общий список источников | --- ## Тон и стиль Книга написана для людей, которые строят production-системы — не для блогеров и не для рецензентов на NeurIPS. **Формула стиля:** аналогия → механизм → практические следствия → источники. - **Язык:** русский. Английский — для терминов, названий методов, API, статей, примеров кода. Не транслитерируй то, что устоялось на английском (`attention`, `tool use`, `structured outputs`), и не русифицируй то, что в индустрии используется как есть. - **Тон:** инженерный, точный, насыщенный смыслом. Каждое предложение несёт информацию или объясняет причинно-следственную связь. Не «вода с выводом в конце», а контекст → механизм → следствие. - **Объяснения:** не только «что это», но и «почему это важно» и «что с этим делать». Если нет ответа на «что делать» — абзац не нужен. - **Аналогии и метафоры:** используются целенаправленно для объяснения механизмов (библиотекарь vs детектив для чата vs агента, LEGO vs гипсовый монолит для модульности, аэропорт для O(n²) attention). Не удаляй их, если они работают — они часть стиля. Не добавляй аналогии ради красоты. - **Калибровка сложности:** не упрощай до блога, не превращай в академическую статью. Читатель — инженер, который ценит ясное объяснение и практические промпты для генерации кода через ИИ. --- ## Структура глав Каждая глава — самостоятельный модуль с устоявшимся форматом: ``` # ЗАГОЛОВОК ВЕРХНЕГО УРОВНЯ --- [Вводная часть: проблема, аналогия, контекст] --- ## N.1. Первая секция ### Подсекция ## N.2. Вторая секция ... --- ## Практический вывод [Конкретные действия, чек-листы, правила] --- ## Источники [Первичные статьи, репозитории, бенчмарки] --- **Навигация:** [Ссылки на предыдущую и следующую главы] ``` **Правила:** - Сохраняй заголовок `#` верхнего уровня, секции `##` с нумерацией (`N.1`, `N.2`), подсекции `###`, разделители `---` где они есть. - Блоки `## Практический вывод`, `## Источники`, `**Навигация:**` — обязательный финал каждой главы. Не удаляй и не переименовывай. - Навигационные ссылки между главами должны оставаться корректными. При переименовании файла или заголовка — проверь все ссылки. - Имена файлов в `book/` — числовой префикс + snake_case: `01_tokens_vectors_and_semantic_space.md`. Новые главы — только с сохранением последовательной нумерации. --- ## Содержание и терминология ### Терминологическая консистентность Следующие термины используются в книге в устоявшемся виде — не заменяй их синонимами: `LLM`, `attention`, `self-attention`, `MLP`, `MoE` (Mixture of Experts), `SSM` (State Space Models), `Mamba`, `RAG`, `RLHF`, `DPO`, `RoPE`, `BPE`, `KV-кэш`, `context window`, `structured outputs`, `tool use`, `agent loop`, `chain-of-thought`, `test-time compute`, `cross-entropy loss`, `Flash Attention`, `CoVe`, `MCP` (Model Context Protocol), `LDD` (Log-Driven Development). ### Фактичность - Новые утверждения о моделях, архитектурах или индустрии — только с проверяемым первоисточником (статья, репозиторий, бенчмарк, официальная документация). - Раздел `Источники` — первичные работы. Допустимы: arXiv, официальные блоги (OpenAI, Anthropic, Google DeepMind, Meta AI), GitHub-репозитории. Не допустимы: Medium-статьи, туториалы, новостные пересказы. - Контекст книги — 2023–2026. Для фундамента (Vaswani 2017, Kaplan 2020, Geva 2021) допустимы более ранние работы. - Не добавляй проценты, доли рынка и прогнозы без конкретного источника, который можно проверить. - Если в ходе редактирования, фактчекинга или ресерча выяснилось, что описанный в книге подход устарел, вытеснен более корректной практикой или формулировка вводит читателя в заблуждение, обновляй саму книгу, а не только список источников. Замени рекомендацию на более точный source-backed вариант, синхронизируй все затронутые главы и обнови `Практический вывод`, если изменилась прикладная рекомендация. ### Содержательные принципы - Для прикладных рекомендаций: конкретные паттерны, анти-паттерны, чек-листы. Не общие советы. - Таблицы — для сравнений и структурированных данных (свойства архитектур, размеры модулей, температурные режимы). - Если таблица или разбор параметров моделей используются для обсуждения подхода, темы или сравнения, в них должны быть заполненные данные. Если модель или семейство (LLM/SLM) важно упомянуть, но по части параметров нет проверяемых данных и нет источников, выноси такое упоминание отдельно в текст с явной оговоркой; в таблицу его лучше не включать. - Списки — для перечислений, где порядок или параллельная структура повышают ясность. ### Формулы - **Не используй сложные математические формулы.** Вместо развёрнутых выкладок описывай общий подход, интуицию и суть механизма словами. - Простые формулы допустимы там, где они действительно нужны для понимания (например, $\text{softmax}$, $Q \cdot K^T$, базовая нормализация). Критерий: читатель-инженер должен понять формулу без отдельного курса линейной алгебры. - Формулы (KaTeX / LaTeX) — только где они объясняют механизм, а не где они «выглядят серьёзно». ### Код - **Не включай блоки кода в главы.** Читателю книги код не нужен — он устаревает быстрее, чем идеи. - Вместо примера кода пиши **промпт для ИИ**, по которому читатель сможет сгенерировать актуальный код самостоятельно. Промпт должен описывать: что нужно получить, какой стек/API использовать, какие ограничения учесть. - Флоу, процессы, подходы и схемы (текстовые или в формате диаграмм) полезны и приветствуются. - Псевдокод допустим в исключительных случаях, когда он объясняет алгоритм или архитектурный паттерн лучше, чем текст. ### Markdown-форматирование - Пиши символы прямо в Markdown: `✓`, `✗`, `⚠`, `↻`, `★`, `→`, `←`, `↔`, `↑`, `↓`, `Σ`, `τ`, `λ`, `∈`, `ℝ`, `₁…₅`. - Не используй emoji-варианты, если есть простой символьный аналог: `✅`, `❌`, `⚠️`, `❗`, `🔄`, `↺`, `⭐`. - Не вставляй внутренние TeX-макросы вроде `\BookCheckMark` в главы. Исходники должны оставаться обычным читаемым Markdown. - В таблицах не дублируй смысл пиктограммой: пиши `Да`, `Нет`, `Зависит`, `Агент`, а не `✓ Да`, `✗ Нет`, `⚠ Зависит`, `✓ Агент`. - Не используй тонкий пробел ` `; используй обычный пробел. - Не используй `ₙ`; вместо этого пиши `_n`. - После правок в главах запускай `python3 scripts/validate_book_format.py <изменённые_файлы>` и исправляй найденные ошибки до завершения работы. ### Практические задания - Где это применимо к теме главы, добавляй **практические задания** в секцию `Практический вывод` или в отдельную подсекцию `### Задания`. - Каждое задание должно содержать: чёткую формулировку, контекст применения (где и когда это полезно), ожидаемый результат. - Задания должны быть релевантны реальной инженерной практике, а не академическими упражнениями. - Примеры хороших заданий: «Настройте RAG-пайплайн для вашего проекта по следующему алгоритму…», «Проведите A/B-тест двух вариантов промпта и сравните по метрикам…», «Проведите red-teaming сессию по чек-листу из этой главы». --- ## Сборка PDF ```bash # Проверка форматирования python3 scripts/validate_book_format.py book # Основная команда python3 scripts/build_book_pdf.py --source book --output BlackboxBook.pdf # Обёртка (macOS) ./build_pdf.command ``` **Зависимости:** `pandoc` + `xelatex`. `./build_pdf_ebook.command` собирает ebook-версию с уменьшенным форматом страницы для ридеров. `./build_pdf_phone.command` собирает phone-версию с узкой страницей для чтения на смартфоне без зума. Скрипт сборки работает с временной копией файлов, но исходные Markdown-файлы в `book/` должны оставаться человекочитаемыми и содержать исходные Unicode-символы. PDF собирается через `xelatex` с fallback-шрифтами для символов и математики; перед сборкой полезно прогонять `scripts/validate_book_format.py`. --- ## Чего не делать - **Не редактируй `BlackboxBook.pdf`, `BlackboxBook_ebook.pdf` и `BlackboxBook_phone.pdf`** — это артефакт сборки. - **Не перестраивай нумерацию глав и навигацию** без явной причины и без обновления всех ссылок. - **Не вноси массовые стилистические правки** ради «унификации», если они не повышают точность или читаемость. - **Не добавляй редакторские комментарии** внутрь глав, если это не запрошено. - **Не заменяй выразительные аналогии** сухими формулировками — метафоры в книге работают как объяснительный инструмент. - **Не добавляй фичи, рефакторинг или «улучшения»** за пределами запрошенной задачи.