Markdown Prompting — структура через разметку

Суть в двух словах

Markdown помогает явно показать:

• где задача;
• где контекст;
• какие требования обязательны;
• в каком формате нужен ответ.

Markdown полезен не потому, что "модель уважает разметку", а потому что он делает prompt визуально и логически сегментированным.

Когда markdown особенно полезен

В командах markdown prompting особенно полезен как "социальный стандарт":

• его легко читать в PR;
• легко обсуждать с коллегами;
• легко править без специальных инструментов;
• он естественно ложится в AGENTS.md, prompt registry или внутренние docs.

То есть markdown хорош не только для модели, но и для самого процесса prompt engineering.

Какие элементы работают лучше всего

Практически лучше всего работают четыре элемента:

1. Заголовки # / ## / ### для смысловых блоков.
2. Bullet lists для требований и критериев.
3. Code fences для данных, примеров и шаблонов.
4. Жирное выделение для обязательных ограничений.

Это простые приёмы, но именно они чаще всего стабилизируют большие human-authored prompts.

Примеры

Хороший markdown-подход для аналитики

# Роль
Ты product analyst.

# Задача
Оцени изменение onboarding flow.

## Данные
- Activation rate: 41% -> 48%
- Time to first action: 6.2 мин -> 4.9 мин
- Trial-to-paid: без изменений

## Формат ответа
1. Ключевой вывод
2. Что улучшилось
3. Что пока не доказано
4. Следующий эксперимент

Markdown как reusable template

# Задача
Перепиши текст для лендинга.

## ЦА
B2B-команды продаж

## Цель
Сделать value proposition яснее.

## Ограничения
- до 80 слов
- без штампов
- без слова 'инновационный'

## Исходник
Наша платформа позволяет компаниям улучшать процессы и достигать новых результатов.

Markdown для code review и engineering prompts

# Task
Review the patch.

## Focus
- bugs
- regressions
- missing tests

## Ignore
- style nits
- optional refactors

## Output format
1. Findings
2. Open questions
3. Residual risk

Markdown vs XML

Markdown обычно выигрывает, если:

• prompt пишет и редактирует человек;
• важна командная читаемость;
• структура умеренно сложная;
• результат нужен прежде всего человеку.

XML или schema лучше, если:

• prompt собирается программно;
• есть несколько независимых источников контекста;
• нужен machine-readable contract;
• пайплайн уже agentic и tool-heavy.

Anti-patterns

Плохой markdown prompt обычно страдает не от "нехватки разметки", а от плохой композиции:

1. Один огромный раздел вместо нескольких ясных блоков.
2. Смешение контекста, правил и output format в одном списке.
3. Декоративные заголовки без функционального смысла.
4. Слишком много выделения жирным.
5. Попытка использовать markdown там, где уже нужна строгая схема.

Отдельная ловушка — копировать красивый markdown-шаблон между задачами без переосмысления. У каждого prompt-а должен быть свой минимальный каркас, а не универсальный "монстр-шаблон".

Техническая реализация

Простой шаблон

template = """
# Role
{role}

# Task
{task}

## Context
{context}

## Requirements
- {requirement_1}
- {requirement_2}

## Output format
{output_format}
""".strip()

Полезное правило

Держите в markdown prompt-е отдельные секции:

• Role
• Task
• Context
• Constraints
• Output format

Если один блок начинает разрастаться и смешивать данные с правилами, это сигнал либо сократить prompt, либо перейти к XML/schema-based форме.

Шаблон для командной работы

TEAM_REVIEW_PROMPT = """
# Objective
{objective}

## Audience
{audience}

## Inputs
{inputs}

## Hard constraints
- {constraint_1}
- {constraint_2}

## Definition of good output
- concise
- grounded in provided data
- explicit about uncertainty

## Output sections
1. Summary
2. Key points
3. Risks
4. Next action
""".strip()

Плюс markdown в том, что такой шаблон удобно:

• хранить в git;
• обсуждать в PR;
• version control-ить как обычный документ;
• адаптировать без специальных SDK.

Когда markdown уже не хватает

def markdown_is_enough(needs_machine_validation: bool, input_layers: int) -> bool:
    return (not needs_machine_validation) and input_layers <= 4

Это не строгая формула, а полезная эвристика. Если:

• входных слоёв становится много;
• результат нужен машине;
• появляется tool orchestration;

то имеет смысл переходить либо к XML для входа, либо к schema constraints для выхода.