시맨틱 레이어로 ClickHouse Assistant 대화 최적화

AGENTS.md를 사용해 ClickHouse Assistant chat 에이전트에 맞춤형 비즈니스 로직과 데이터별 지침을 제공하는 가이드

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

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

​

작동 방식

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

1. 메시지를 보내면 ClickHouse Assistant chat 에이전트가 이 파일을 자동으로 불러옵니다
2. 콘텐츠는 구조화된 content 태그 안에 배치되어 에이전트의 시스템 프롬프트에 삽입됩니다
3. 이 지침은 해당 서비스의 모든 ClickHouse Assistant chat 대화에 적용됩니다

​

AGENTS.md 만들기

1. 저장된 쿼리 만들기

   1. Cloud Console에서 새 쿼리를 생성합니다
   2. 이름을 정확히 **“AGENTS.md”**로 지정합니다(대소문자 구분)
   3. 쿼리 텍스트 편집기에 사용자 지정 지침을 작성합니다(실제 SQL이 아님)
   4. 쿼리를 저장합니다
2. 지침 추가하기

   명확하고 실행 가능한 표현으로 지침을 구성합니다. 다음을 포함하십시오:

   • 비즈니스 규칙 및 계산
   • 데이터 구조 관련 지침
   • 도메인별 용어
   • 일반적인 쿼리 패턴
   • 성능 최적화 규칙

​

권장 사항

​

컨텍스트를 유한한 자원으로 다루기

컨텍스트는 매우 소중합니다. 토큰이 하나씩 추가될 때마다 에이전트의 “주의력 예산”이 소모됩니다. 작업 메모리가 제한된 인간과 마찬가지로, 언어 모델도 컨텍스트가 길어질수록 성능이 저하됩니다. 즉, 원하는 결과를 얻을 가능성을 최대화하려면 정보 밀도가 가장 높은 최소한의 토큰 집합을 찾아야 합니다.

​

적절한 추상화 수준 찾기

다음 두 극단 사이에서 균형을 맞추십시오.

• 지나치게 구체적임: 취약한 if-else 로직을 하드코딩해 시스템을 쉽게 깨지게 하고 유지 관리 복잡성을 키움
• 지나치게 모호함: 구체적인 신호를 주지 못하거나, 서로 공유된 맥락이 있다고 잘못 가정하는 고수준 지침

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

​

구조화된 섹션으로 정리하기

XML 태그 또는 Markdown 헤더를 사용해 명확히 구분되고 훑어보기 쉬운 섹션을 만드세요:

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

​

다양하고 대표적인 예시를 제공하세요

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

​

간결하게 유지하되 필요한 내용은 모두 포함하세요

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

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

​

예시: 원시 데이터에서 계산된 메트릭

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

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

​

예시: 비즈니스 로직 규칙

도메인별 계산과 분류를 정의합니다:

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

​

예시: 데이터 구조의 특이사항

비표준 데이터 포맷이나 레거시 스키마 설계상의 결정 사항을 문서화합니다:

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

​

예시: 도메인 용어

비즈니스 용어를 기술 구현에 대응시킵니다:

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