> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Оптимизация диалогов ClickHouse Assistant с помощью семантического слоя

> Руководство по использованию AGENTS.md для передачи агенту чата ClickHouse Assistant пользовательской бизнес-логики и инструкций, связанных с данными

Агента чата ClickHouse Assistant можно настроить так, чтобы он учитывал вашу бизнес-логику, структуры данных и специфику предметной области с помощью **AGENTS.md** — специального сохраненного запроса, который служит семантическим слоем поверх системного промпта агента.

Создав файл AGENTS.md, вы можете задать пользовательские инструкции, которые добавляются в начало каждого диалога и помогают направлять генерацию SQL-запросов и анализ данных с учетом уникальных требований, расчетов и принятых в вашей организации соглашений.

<div id="how-it-works">
  ## Как это работает
</div>

Когда вы сохраняете запрос с именем "AGENTS.md" (с учетом регистра) в Cloud Console:

1. Агент чата ClickHouse Assistant автоматически загружает этот файл при отправке сообщения
2. Содержимое помещается в структурированный тег content и добавляется в системный промпт агента
3. Эти инструкции применяются ко всем диалогам ClickHouse Assistant chat в этом сервисе

<div id="creating-agents-md">
  ## Создание AGENTS.md
</div>

<Steps>
  <Step>
    ### Создайте сохраненный запрос

    1. В Cloud Console создайте новый запрос
    2. Назовите его строго так: **"AGENTS.md"** (с учетом регистра)
    3. Введите свои пользовательские инструкции в редакторе текста запроса (это не SQL)
    4. Сохраните запрос
  </Step>

  <Step>
    ### Добавьте свои инструкции

    Структурируйте инструкции, используя четкий и практичный язык. Включите:

    * Бизнес-правила и расчеты
    * Рекомендации по структуре данных
    * Терминологию предметной области
    * Распространенные шаблоны запросов
    * Правила оптимизации производительности
  </Step>
</Steps>

<div id="best-practices">
  ## Лучшие практики
</div>

<div id="finite-resource">
  ### Относитесь к контексту как к ограниченному ресурсу
</div>

Контекст ценен — каждый токен расходует «бюджет внимания» агента. Подобно людям с ограниченной рабочей памятью, языковые модели работают хуже по мере увеличения контекста. Это значит, что нужно находить **как можно меньший набор наиболее информативных токенов**, который максимизирует вероятность желаемого результата.

<div id="right-altitude">
  ### Найдите правильный уровень детализации
</div>

Соблюдайте баланс между двумя крайностями:

* **Слишком конкретно**: Жёстко заданная хрупкая логика if-else, которая делает систему уязвимой и усложняет поддержку
* **Слишком расплывчато**: Высокоуровневые рекомендации, которые не дают конкретных ориентиров или ошибочно предполагают общий контекст

Оптимальный уровень детализации должен быть достаточно конкретным, чтобы эффективно направлять поведение, и при этом достаточно гибким, чтобы модель могла применять надёжные эвристики. Начните с минимального промпта на лучшей доступной модели, а затем добавляйте чёткие инструкции с учётом выявленных сбоев.

<div id="structured-sections">
  ### Структурируйте текст по разделам
</div>

Используйте XML-теги или заголовки Markdown, чтобы создать отдельные, удобные для быстрого просмотра разделы:

```xml theme={null}
<background_information>
Context about your data and domain
</background_information>

<calculation_rules>
Specific formulas and business logic
</calculation_rules>

<tool_guidance>
How to use specific ClickHouse features
</tool_guidance>
```

<div id="canonical-examples">
  ### Приводите разнообразные, эталонные примеры
</div>

Примеры говорят лучше тысячи слов. Вместо того чтобы пытаться уместить в промпт все возможные пограничные случаи, подберите компактный, но разнообразный набор примеров, который наглядно передаёт ожидаемое поведение.

<div id="minimal-complete">
  ### Минимум, но достаточно
</div>

* Включайте только действительно нужные инструкции
* Будьте кратки — слишком большой контекст снижает качество из-за «деградации контекста»
* Удаляйте устаревшие или редко используемые правила
* Давайте достаточно информации, чтобы направлять нужное поведение

<Tip>
  Минимальность не обязательно означает краткость. Деталей должно быть достаточно, чтобы агент придерживался ожидаемого поведения, но без лишней многословности.
</Tip>

<div id="example-calculated-metrics">
  ## Пример: Вычисляемые метрики на основе сырых данных
</div>

Указывайте агенту, если для метрик требуются специальные вычисления, а не прямой доступ к столбцам:

```xml theme={null}
<metric_calculations>
ВАЖНО: "active_sessions" — это НЕ столбец. Его необходимо вычислить.

Для вычисления активных сеансов:
COUNT(DISTINCT session_id || '|' || user_id) AS active_sessions

Это подсчитывает уникальные комбинации идентификаторов сеанса и пользователя.

Когда пользователь запрашивает "active sessions" или "session count", всегда используйте следующую формулу:
SELECT
    date,
    COUNT(DISTINCT session_id || '|' || user_id) AS active_sessions
FROM events
GROUP BY date;

</metric_calculations>
```

<div id="example-business-logic">
  ## Пример: Правила бизнес-логики
</div>

Определите вычисления и категории, характерные для предметной области:

```xml theme={null}
<business_rules>
Revenue Calculation:
- Exclude refunded transactions: WHERE transaction_status != 'refunded'
- Apply regional tax rates using CASE expressions
- Use MRR for subscriptions:
  SUM(CASE
    WHEN billing_cycle = 'monthly' THEN amount
    WHEN billing_cycle = 'yearly' THEN amount / 12
    ELSE 0
  END) AS mrr

Traffic Source Classification:
Use CASE expression to categorize:
CASE
  WHEN traffic_source IN ('google', 'bing', 'organic') THEN 'Organic Search'
  WHEN traffic_source IN ('facebook', 'instagram', 'social') THEN 'Social Media'
  WHEN traffic_source = 'direct' THEN 'Direct'
  ELSE 'Other'
END AS source_category

Customer Segmentation:
- Enterprise: annual_contract_value >= 100000
- Mid-Market: annual_contract_value >= 10000 AND annual_contract_value < 100000
- SMB: annual_contract_value < 10000

Always include these categorizations when generating traffic or revenue reports.
</business_rules>
```

<div id="example-data-quirks">
  ## Пример: особенности структуры данных
</div>

Описывайте нестандартные форматы данных или решения, унаследованные от устаревшей схемы:

```xml theme={null}
<data_structure_notes>
The user_status column uses numeric codes, not strings:
- 1 = 'active'
- 2 = 'inactive'
- 3 = 'suspended'
- 99 = 'deleted'

When filtering or displaying user status, always use:
CASE user_status
  WHEN 1 THEN 'active'
  WHEN 2 THEN 'inactive'
  WHEN 3 THEN 'suspended'
  WHEN 99 THEN 'deleted'
END AS status_label

The product_metadata column contains JSON strings that must be parsed:
SELECT
    product_id,
    JSONExtractString(product_metadata, 'category') AS category,
    JSONExtractInt(product_metadata, 'inventory_count') AS inventory
FROM products;
</data_structure_notes>
```

<div id="example-terminology">
  ## Пример: терминология предметной области
</div>

Сопоставьте бизнес-термины с технической реализацией:

```xml theme={null}
<terminology>
When users refer to "conversions", they mean:
- For e-commerce: transactions WHERE transaction_type = 'purchase'
- For SaaS: subscriptions WHERE subscription_status = 'active' AND first_payment_date IS NOT NULL

"Churn" is calculated as:
COUNT(DISTINCT user_id) WHERE last_active_date < today() - INTERVAL 90 DAY
AND previous_subscription_status = 'active'

"DAU" (Daily Active Users) means:
COUNT(DISTINCT user_id) WHERE activity_date = today()

"Qualified leads" must meet ALL criteria:
- lead_score >= 70
- company_size >= 50
- budget_confirmed = true
- contact_role IN ('Director', 'VP', 'C-Level')
</terminology>
```