# 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`** — это артефакт сборки.
- **Не перестраивай нумерацию глав и навигацию** без явной причины и без обновления всех ссылок.
- **Не вноси массовые стилистические правки** ради «унификации», если они не повышают точность или читаемость.
- **Не добавляй редакторские комментарии** внутрь глав, если это не запрошено.
- **Не заменяй выразительные аналогии** сухими формулировками — метафоры в книге работают как объяснительный инструмент.
- **Не добавляй фичи, рефакторинг или «улучшения»** за пределами запрошенной задачи.
