---
name: "BlackboxBook Manuscript Rules"
description: "Use when editing BlackboxBook chapters in book/. Covers chapter structure, sources, navigation, terminology consistency, and Russian technical manuscript style."
applyTo: "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.