BlackboxBook/AGENTS.md

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

# Проверка форматирования
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-версию с узкой страницей для чтения на смартфоне без зума.

./build_all.command собирает всё разом: три PDF-варианта (default, ebook, phone) + EPUB3 (pandoc) + MOBI и FB2 (ebook-convert из EPUB).

Скрипт сборки работает с временной копией файлов, но исходные Markdown-файлы в book/ должны оставаться человекочитаемыми и содержать исходные Unicode-символы. PDF собирается через xelatex с fallback-шрифтами для символов и математики; перед сборкой полезно прогонять scripts/validate_book_format.py.

---

Чего не делать

• Не редактируй BlackboxBook.pdf, BlackboxBook_ebook.pdf и BlackboxBook_phone.pdf — это артефакт сборки.
• Не перестраивай нумерацию глав и навигацию без явной причины и без обновления всех ссылок.
• Не вноси массовые стилистические правки ради «унификации», если они не повышают точность или читаемость.
• Не добавляй редакторские комментарии внутрь глав, если это не запрошено.
• Не заменяй выразительные аналогии сухими формулировками — метафоры в книге работают как объяснительный инструмент.
• Не добавляй фичи, рефакторинг или «улучшения» за пределами запрошенной задачи.