busya/BlackboxBook
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d550fdccb82efd0c694dfd8f9851b71f7d9342b8
BlackboxBook/AGENTS.md
busya d67af98363 init
2026-05-20 20:55:03 +03:00

18 KiB
Raw Blame History

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

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

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

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