> ## 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 chat 에이전트에 맞춤형 비즈니스 로직과 데이터별 지침을 제공하는 가이드

ClickHouse Assistant chat 에이전트는 에이전트의 시스템 프롬프트에 시맨틱 레이어로 작동하는 특별한 저장된 쿼리인 **AGENTS.md**를 통해, 조직별 비즈니스 로직, 데이터 구조, 도메인 지식을 이해하도록 맞춤 설정할 수 있습니다.

AGENTS.md 파일을 만들면 각 대화의 시작 부분에 삽입되는 사용자 지정 지침을 제공할 수 있으며, 이를 통해 조직 고유의 요구 사항, 계산 방식, 규약에 따라 SQL 쿼리 생성과 데이터 분석을 안내할 수 있습니다.

<div id="how-it-works">
  ## 작동 방식
</div>

Cloud Console에서 "AGENTS.md"(대소문자 구분)라는 이름의 쿼리를 저장하면 다음과 같이 동작합니다:

1. 메시지를 보내면 ClickHouse Assistant chat 에이전트가 이 파일을 자동으로 불러옵니다
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 로직을 하드코딩해 시스템을 쉽게 깨지게 하고 유지 관리 복잡성을 키움
* **지나치게 모호함**: 구체적인 신호를 주지 못하거나, 서로 공유된 맥락이 있다고 잘못 가정하는 고수준 지침

최적의 추상화 수준은 동작을 효과적으로 유도할 만큼 충분히 구체적이면서도, 모델이 강력한 휴리스틱을 적용할 수 있을 만큼 충분히 유연합니다. 우선 사용 가능한 최상의 모델에 최소한의 prompt를 제공해 시작한 다음, 관찰된 실패 양상에 따라 명확한 지침을 추가하십시오.

<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>

예시는 "천 마디 말보다 나은 그림"과 같습니다. 모든 예외 상황을 prompt에 억지로 담기보다, 기대하는 동작을 효과적으로 보여 주는 다양하고 핵심적인 예시를 선별하십시오.

<div id="minimal-complete">
  ### 간결하게 유지하되 필요한 내용은 모두 포함하세요
</div>

* 자주 필요한 지침만 포함하세요
* 간결하게 작성하세요. 컨텍스트가 지나치게 길면 "context rot"로 인해 성능이 저하됩니다
* 오래되었거나 거의 사용하지 않는 규칙은 제거하세요
* 원하는 동작을 유도하는 데 충분한 정보를 제공하세요

<Tip>
  간결하다고 해서 반드시 짧아야 하는 것은 아닙니다. 에이전트가 기대하는 동작을 따르도록 하려면 충분한 세부 정보가 필요하지만, 불필요하게 장황하게 작성하는 것은 피해야 합니다.
</Tip>

<div id="example-calculated-metrics">
  ## 예시: 원시 데이터에서 계산된 메트릭
</div>

메트릭을 컬럼에서 직접 가져오는 대신 특정 계산이 필요한 경우 에이전트를 다음과 같이 안내합니다:

```xml theme={null}
<metric_calculations>
IMPORTANT: "active_sessions" is NOT a column. It must be calculated.

To calculate active sessions:
COUNT(DISTINCT session_id || '|' || user_id) AS active_sessions

This counts unique combinations of session and user identifiers.

When the user asks for "active sessions" or "session count", always use this formula:
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>
```