BlackboxBook/.github/instructions/book-manuscript.instructions.md

name, description, applyTo

name	description	applyTo
BlackboxBook Manuscript Rules	Use when editing BlackboxBook chapters in book/. Covers chapter structure, sources, navigation, terminology consistency, and Russian technical manuscript style.	book/**/*.md

BlackboxBook Chapter Rules

Use these rules for any edit under book/. AGENTS.md is the canonical source of truth for the full book context, chapter map, and style guide. These rules are the actionable editing checklist.

Chapter Structure

• Preserve the top-level # heading and the chapter's numbered ## sections.
• Keep the required ending blocks: Практический вывод, Источники, Навигация.
• Preserve --- separators where they structure the chapter.
• If a chapter gains or loses sections, keep section numbering coherent.
• If a new chapter is created, follow the numeric prefix + snake_case naming pattern.

Navigation

• Keep previous/next chapter links correct after any structural change.
• If chapter order changes or a new chapter is added, update all affected navigation links.
• Do not leave dangling references to renamed headings or removed files.

Sources And Factual Claims

• For model families, vendor naming, release status, architecture claims, benchmark claims, and timeline-sensitive statements, use primary sources whenever possible.
• Acceptable source types: official vendor docs or blogs, arXiv papers, official GitHub repositories, benchmark repositories.
• Avoid Medium posts, news rewrites, generic tutorials, and unsourced percentages or forecasts.
• When a claim changes materially, update the Источники block accordingly.
• If a table or model-parameter breakdown is used to support a comparison, theme, or argument, keep it populated with actual source-backed data.
• If an important LLM or SLM must be mentioned but some parameters cannot be verified from primary sources, move that mention into prose with an explicit caveat instead of leaving a partially empty row in the table.
• If fact-checking or research shows that a recommendation, workflow, or engineering pattern in the manuscript is outdated, superseded, or materially less correct than current source-backed practice, update the manuscript text itself. Do not merely label it stale; replace it with the better approach and refresh the Источники block.

Style And Terminology

• Write in Russian; keep established English technical terms in English when they are standard in the industry.
• Preserve the book's pattern: analogy -> mechanism -> practical implication -> sources.
• Do not flatten useful analogies into dry textbook prose.
• Keep terminology stable: LLM, attention, self-attention, MLP, MoE, SSM, 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, LDD.

Markdown Formatting

• Use plain Unicode symbols in manuscript Markdown: ✓, ✗, ⚠, ↻, ★, →, ←, ↔, ↑, ↓, Σ, τ, λ, ∈, ℝ, ₁…₅.
• Do not use emoji variants such as ✅, ❌, ⚠️, ❗, 🔄, ↺, ⭐.
• Do not use internal TeX macros like \BookCheckMark inside chapter files.
• In tables, do not duplicate meaning with pictograms: prefer Да, Нет, Зависит, Агент, Человек instead of ✓ Да, ✗ Нет, ⚠ Зависит, ✓ Агент.
• Use a normal space instead of thin space  .
• Use _n instead of ₙ.

Content Rules

Formulas

• Do not use complex mathematical formulas. Describe general approaches, intuition, and mechanism in words.
• Simple formulas are acceptable where they genuinely aid understanding (e.g., \text{softmax}, Q \cdot K^T, basic normalization).
• Criterion: an engineer reader should understand the formula without a separate linear algebra course.

Code

• Do not include code blocks in chapters. Code becomes outdated faster than ideas.
• Instead of a code example, write an AI prompt that lets the reader generate up-to-date code themselves. The prompt should describe: the desired output, the stack/API to use, and the constraints.
• Flows, processes, approaches, and diagrams (textual or visual) are useful and encouraged.
• Pseudocode is acceptable in rare cases when it explains an algorithm or pattern better than prose.

Practical Assignments

• Where applicable to the chapter topic, add practical assignments to the Практический вывод section or a dedicated ### Задания subsection.
• Each assignment must include: a clear formulation, application context (where and when it is useful), and the expected outcome.
• Assignments must be relevant to real engineering practice, not academic exercises.

Editing Discipline

• Prefer minimal, targeted edits over broad rewrites unless structure is the actual issue.
• Do not remove expressive examples or analogies that still explain the mechanism correctly.
• Do not introduce claims that cannot be verified.
• When one outdated recommendation is fixed in one chapter, check whether the same guidance appears in adjacent or related chapters and synchronize those mentions when they are in scope.
• If a structural gap is real, it is acceptable to add a new section or chapter, but keep the chapter map coherent.
• After any structural change, verify that AGENTS.md and readme.md remain accurate.
• After editing manuscript files, run python3 scripts/validate_book_format.py <changed_files> and fix all reported errors before finishing.