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