Markdown для агентов: полная шпаргалка по синтаксису и работе с нейросетями

07.05.2026 · 8 мин чтения

Markdown — это язык разметки, который используют все современные нейросети-агенты. Claude Code читает CLAUDE.md, Cursor — .cursorrules, ChatGPT и Copilot — системные промпты в Markdown. Если вы работаете с AI-ассистентами, умение писать Markdown — это не просто навык оформления текста, а инструмент управления поведением нейросети.

В этой статье — полный справочник по синтаксису Markdown, особенности разных платформ и практические советы по написанию файлов-инструкций для AI-агентов.

Базовый синтаксис Markdown

Заголовки

Заголовки создаются символом # перед текстом. Количество решёток определяет уровень:

# Заголовок H1
## Заголовок H2
### Заголовок H3
#### Заголовок H4
##### Заголовок H5
###### Заголовок H6

Правило: после решётки обязателен пробел. #Текст не работает, а # Текст — работает.

Жирный текст и курсив

**жирный текст**
*курсив*
***жирный курсив***
~~зачёркнутый~~

Результат: жирный текст, курсив, жирный курсив, ~~зачёркнутый~~.

Ссылки и изображения

[текст ссылки](https://example.com)
![alt-текст изображения](https://example.com/image.png)

Изображения — это те же ссылки, но с восклицательным знаком в начале.

Списки

Маркированные:

- Первый пункт
- Второй пункт
  - Вложенный пункт
  - Ещё один вложенный
- Третий пункт

Нумерованные:

1. Первый шаг
2. Второй шаг
3. Третий шаг

Чек-листы (GitHub Flavored Markdown):

- [x] Выполненная задача
- [ ] Невыполненная задача
- [ ] Ещё одна задача

Цитаты

> Это цитата.
> Она может быть многострочной.

> **Важно:** внутри цитаты можно использовать другое форматирование.

Горизонтальная линия

Три дефиса, звёздочки или подчёркивания на отдельной строке:

---

Код

Строчный код — в обратных кавычках:

Используйте функцию `print()` для вывода.

Блоки кода — тройные обратные кавычки с указанием языка:

```python
def hello():
    print("Привет, мир!")
```

Поддерживаемые языки: python, javascript, bash, json, yaml, html, css, sql, markdown и десятки других.

Расширенный синтаксис (GFM)

GitHub Flavored Markdown (GFM) расширяет стандартный CommonMark дополнительными элементами. Именно GFM стал де-факто стандартом для большинства платформ.

Таблицы

| Столбец 1 | Столбец 2 | Столбец 3 |
|-----------|:---------:|----------:|
| Лево      | Центр     | Право     |
| Ячейка    | Ячейка    | Ячейка    |

Двоеточия в строке разделителя управляют выравниванием: :--- — влево, :---: — по центру, ---: — вправо.

Ограничения: внутри ячеек нельзя вставлять списки, заголовки и вложенные таблицы. Большинство рендереров это не поддерживают.

Сноски

Это утверждение нуждается в источнике[^1].

[^1]: Источник: документация CommonMark.

⚠️ Сноски поддерживаются не везде: GitHub — да, Telegram и Discord — нет.

Определения

Термин
: Определение термина.
: Ещё одно определение.

Автоматические ссылки

URL-адреса автоматически превращаются в кликабельные ссылки: https://example.com

Специфика платформ

Один и тот же Markdown выглядит по-разному на разных платформах. Вот ключевые различия:

Telegram поддерживает MarkdownV2 и HTML. Синтаксис отличается от стандартного:

*жирный* (одинарная звёздка, не двойная)
_курсив_
__подчёркивание__
~зачёркивание~
||спойлер||
`строчный код`
```блок кода```
[ссылка](https://example.com)

Чего нет в Telegram: — Таблицы (не поддерживаются вообще) — Сноски — Чек-листы — Заголовки (#) — Изображения в markdown-синтаксисе (нужно отправлять как медиа)

⚠️ Важно: многие символы нужно экранировать обратным слэшем: _ * [ ] ( ) ~ > # + — = | { } . !`

GitHub

GitHub поддерживает полный GFM плюс свои расширения:

Алерты: > [!NOTE], > [!TIP], > [!WARNING], > [!IMPORTANT], > [!CAUTION]
Цветовые свотчи: запись #ff0000 показывает превью цвета
@упоминания: @username создаёт уведомление
Ссылки на issues: #123 автоматически ссылается на issue
Mermaid-диаграммы в блоках кода ```mermaid
Математика: $x^2$ и $$\int_0^1 f(x)dx$$

Discord

Discord поддерживает базовый GFM: — Заголовки только в длинных сообщениях (более 16 строк) — Цитаты с > и вложенные с >> — Таймстампы: <t:1234567890:F> для динамических дат — Нет таблиц, сносок, чек-листов

ChatGPT и Claude

Оба понимают стандартный Markdown. Claude дополнительно хорошо работает с XML-тегами для структурирования промптов.

Как нейросети понимают Markdown

Парсинг через статистику, а не правила

Нейросети не парсят Markdown как компилятор (с построением AST). Вместо этого они обрабатывают текст как последовательность токенов, где символы #, **, ` — это отдельные токены.

LLM были обучены на огромных объёмах веб-контента (GitHub, StackOverflow, Reddit, документация), где Markdown используется повсеместно. Поэтому модели имеют глубокую статистическую связь между markdown-паттернами и их семантическим смыслом:

## Заголовок → нейросеть понимает, что это начало нового раздела
**жирный** → акцент, важный термин
- пункт списка → перечисление, структурированные данные
`код` → технический термин, имя функции, команда

Как пишет Microsoft в документации: «Модели обучены на большом объёме веб-контента в XML и Markdown, что может давать лучшие результаты.»

Форматирование влияет на качество вывода

Исследование «The Format Tax» (Lee et al., 2026, arXiv:2604.03616) показало:

Требования к структурированному выводу (JSON, XML, LaTeX, Markdown) снижают качество рассуждений у открытых моделей
Ключевая находка: само требование форматирования вызывает потерю точности ещё до применения каких-либо ограничений
Решение: разделять рассуждения и форматирование — сначала генерировать свободный текст, затем форматировать отдельным проходом
Закрытые модели (GPT-4, Claude) показывают минимальное или нулевое влияние «налога форматирования»

Em-dash как «отпечаток» Markdown

Исследование «The Last Fingerprint» (Freeburg, 2026, arXiv:2603.27006) обнаружило:

LLM по умолчанию генерируют текст в markdown-формате — это усвоенное поведение из обучающих данных
Длинное тире (—) описано как «утечка markdown в прозу» — мельчайший структурный ориентир из обучения
Даже при инструкции «не использовать markdown» тире сохраняется в большинстве моделей
Модели сильно различаются: от 0.0 на 1000 слов (Llama) до 9.1 (GPT-4.1)

XML vs Markdown для промптов

Anthropic в своей документации рекомендует:

XML-теги лучше подходят для сложных многочастных промптов — они однозначно разделяют секции
Markdown лучше для инструкций, где важна читаемость человеком
Для файлов-инструкций (CLAUDE.md, AGENTS.md) используется именно Markdown

Файлы-инструкции для AI-агентов

Что такое AGENTS.md и CLAUDE.md

Современные AI-агенты кодирования используют специальные Markdown-файлы как «память проекта»:

Агент	Файл	Описание
Claude Code	`CLAUDE.md`	Инструкции для Claude при работе с проектом
Cursor	`.cursor/rules/*.md`	Правила с активацией по glob-паттернам
Windsurf	`.windsurf/rules/*.md`	Правила с триггерами
OpenAI Codex	`AGENTS.md`	Универсальный стандарт
Hermes	`AGENTS.md` + `SOUL.md`	Инструкции + личность агента

AGENTS.md становится межагентным стандартом. Claude Code явно рекомендует импортировать его: @AGENTS.md в CLAUDE.md.

Оптимальная структура

Анализ реальных open-source проектов (Next.js, Rails, Codex, Excalidraw) показывает лучшие практики:

# Название проекта — Руководство разработчика

## Структура кодовой базы
- Основные директории и их назначение
- Точки входа и ключевые модули

## Команды сборки
```bash
pnpm build
pnpm test
pnpm lint

Соглашения по коду

Использовать TypeScript strict mode
Prefunctional компоненты вместо классов
snake_case для колонок БД

Тестирование

Команды запуска тестов
Ожидания по написанию тестов

Архитектурные заметки

Ключевые паттерны и решения
Антипаттерны (чего избегать)

Типовые сценарии

Пошаговые процедуры
Когда какой подход использовать


### Правила написания

Из документации Anthropic, Cursor и Windsurf:

1. **До 200 строк** на файл (Anthropic). Cursor допускает до 500, но лучше разбивать
2. **Конкретные инструкции** — «Используй 2-пробельные отступы», а не «Форматируй код правильно»
3. **H2-заголовки** для разделов, **списки** для правил, **блоки кода** для примеров
4. **Примеры «хорошо/плохо»** — показывать паттерны, а не описывать их словами
5. **Не копировать** стилистические гайды — для этого есть линтеры
6. **Не добавлять очевидные правила** — «писать хороший код» уже есть в обучающих данных

### Frontmatter для условной активации

Cursor и Windsurf поддерживают YAML-frontmatter для активации правил по условиям:

```yaml
---
description: "Стандарты для React-компонентов"
globs: "src/components/**/*.tsx"
alwaysApply: false
---

Claude Code поддерживает привязку к путям:

---
paths:
  - "src/api/**/*.ts"
---

Иерархия и область действия

Файлы инструкций работают по принципу вложенности:

project/
├── AGENTS.md                  # Корень — действует всегда
├── frontend/
│   ├── AGENTS.md              # Только для frontend/**
│   └── src/
│       └── components/
│           └── AGENTS.md      # Только для components/**
├── backend/
│   └── AGENTS.md              # Только для backend/**
└── .claude/rules/             # Модульные правила Claude
    ├── code-style.md
    ├── testing.md
    └── security.md

Практические советы

Как структурировать промпт для нейросети

Используйте заголовки для разделения логических блоков — нейросеть надёжно интерпретирует ## как маркер новой секции
Жирный текст для ключевых терминов и важных указаний
Нумерованные списки для последовательных шагов
Маркированные списки для перечислений и правил
Блоки кода для примеров, команд и технических данных
Таблицы для сравнения вариантов

Чего избегать

Не используйте заголовки H1 больше одного раза в файле
Не смешивайте табуляцию и пробелы в отступах списков
Не полагайтесь на форматирование для передачи смысла — продублируйте важное текстом
Не используйте сноски там, где они не поддерживаются (Telegram, Discord)
Помните про экранирование спецсимволов в Telegram MarkdownV2

Токен-экономия

Markdown-символы потребляют токены. Каждый #, *, |, - — это отдельные токены. В длинных промптах это может быть значительным:

## Заголовок = 3-4 токена (включая пробел)
- пункт списка = 2-3 токена на строку
Таблица из 10 строк = 50-80 «пустых» токенов на форматирование

Для экономии токенов в системных промптах можно использовать более компактные форматы, но жертвовать читаемостью не стоит — лучше структурированный промпт работает качественнее.

Ссылки и источники

Markdown Guide — шпаргалка — полный справочник по синтаксису
CommonMark Spec — базовая спецификация
GitHub Flavored Markdown Spec — спецификация GFM
Telegram Bot API — форматирование — синтаксис Telegram
Anthropic — Claude Code Memory — CLAUDE.md и AGENTS.md
Cursor Rules — система правил Cursor
Windsurf Memories — правила Windsurf
The Format Tax (2026) — влияние форматирования на рассуждения LLM
The Last Fingerprint (2026) — как Markdown-обучение формирует стиль LLM