77 lines
5.6 KiB
Markdown
77 lines
5.6 KiB
Markdown
---
|
||
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.
|