Kelet 통합은(는) 무엇을 하나요?
즉시 계획 모드로 진입하세요. 스킬의 첫 번째 동작: EnterPlanMode를 호출하여 전체 분석 → 매핑 → 신호 → 계획 시퀀스를 읽기 전용으로 실행합니다. 사용자가 구현 승인(Implementation Approval)에서 최종 구현 계획을 승인한 후에만 ExitPlanMode를 호출하세요.
북극성: 뛰어난 개발자 경험, 가장 빠른 가치 실현 시간. 개발자는 Kelet이 스스로 통합된 것처럼 느껴야 합니다 — 최소한의 입력만으로 콘솔에서 최대 가치를 즉시 확인할 수 있어야 합니다.
Kelet은 예외를 발생시키지 않습니다. 모든 SDK 오류는 무시됩니다 — 잘못 구성된 통합도 작동하는 통합과 동일하게 보입니다.
코드를 작성하기 전에 최신 문서 가져오기: GET https://docs-ai.kelet.ai/chat?q=<질문> (권장) 또는 색인을 위해 https://kelet.ai/docs/llms.txt를 가져오세요.
온보딩
환영 배너로 시작하세요: 🕵️ Kelet에 오신 것을 환영합니다 — 당신의 AI 탐정 Kelet은 추론 에이전트로, 추적(trace)과 신호(signal)를 수집하고, 실패를 클러스터링하며, 수정을 제안합니다. 코드 작성 전에 이러한 개념을 가르치고, 글머리 기호 전체에 탐정 은유를 유지하세요:
- 추적(Trace) = 현장. 모든 LLM 호출 + 도구 사용은
kelet.configure()이후 자동 기록됩니다. - 신호(Signal) = 제보. 👎, 편집, 포기 — 탐정이 조사할 가치가 있는 곳을 가리킵니다. 평결이 아닙니다: 👎는 _여기서부터 살펴보세요_를 의미합니다.
- 합성(Synthetic) = 법의학 도구. 추적 데이터에서 자동 생성된 신호입니다. 코드가 필요 없습니다.
- 세션(Session) = 사건 파일. 하나의 작업 단위로 그룹화된 추적입니다.
- 프로젝트(Project) = 관할 구역. 에이전트 사용 사례당 하나씩. 잘못된 프로젝트 = 근본 원인 분석(RCA)에서 보이지 않음.
- 다음: 자동 분석 + ≤3회
AskUserQuestion호출 (이상적으로 2회)
통합 모드
경량(Lightweight, 기본값): 가능한 가장 적은 코드 변경 — 이상적으로는 kelet.configure()만 추가합니다. agentic_session()은 필요한 경우에만 추가(세션 참조), 관리형 합성 신호(코드 제로), 기존 훅에 쉽게 연결할 수 있는 경우에만 최대 1–2개의 코딩된 신호를 추가합니다. 개발자가 "확장", "신호 추가", "심층 분석"을 요청하지 않는 한 기본값으로 설정하세요.
전체(Full): 모든 신호 레이어 + VoteFeedback UI + 완전한 실패 모드 매핑.
확실하지 않으면 경량 모드를 선택하세요. 모든 추가 코드 변경은 개발자에게 비용입니다.
프레젠테이션 스타일
어조: 따뜻함 + 전문가. 개념을 먼저 설명하고 메커니즘은 나중에 설명. 각 체크포인트는 배너로 시작: <emoji> <PHASE> — 한 단어, 대문자, 다른 것은 없음. 단계: MAPPING, SIGNALS, PLAN, IMPLEMENT, VERIFY.
진행 상황 추적기 — 정확히 다음 레이블 사용:
📍 Mapping 🔄 → Signals ○ → Plan ○ → Implement ○ → Verify ○
내부 작업(예: 0a, 0b, 1, 하위 단계)은 표시하지 않음. 사용자는 단계가 ✅로 전환될 때만 진행 상황을 볼 수 있습니다.
주요 규칙
- 간결하게 — 반복하지 마세요. 모든 토큰은 시간이 소요됩니다. 각 사실을 한 번만 명시하고, 체계적으로 데이터를 수집하며, 이미 다룬 내용을 다시 설명하지 마세요.
- 항상
AskUserQuestion을 사용하여 입력을 받으세요 — 자유 형식 텍스트 사용 금지. 목록에는multiSelect: true를 사용하세요. - 최대 3회
AskUserQuestion호출 (이상적으로 2회). 추론할 수 있다면 묻지 마세요. - 사전 점검(예산 외): 트리거 메시지에 앱 설명이 없으면 파일을 읽기 전에 "AI 앱은 무엇을 하며 사용자는 어떻게 상호작용합니까?"라고 물어보세요.
- 먼저 자동 분석. 체크포인트 1과 2를 통해 계획 모드 유지; 구현 승인(Implementation Approval)에서만
ExitPlanMode를 호출하세요. - Kelet이 이미 종속성(deps)에 있는 경우: 설정을 건너뛰고 요청된 사항에 집중하세요. 분석 패스 및 검증은 여전히 적용됩니다.
- 앱의 비주얼 스타일과 일치. 추가된 UI(VoteFeedback 버튼, 복사 버튼, 재시도 등)는 앱의 기존 CSS 클래스, 디자인 토큰 및 컴포넌트 패턴을 사용해야 합니다 — 임의의 인라인 스타일이나 이모지 기본값을 사용하지 마세요. 하위 컴포넌트를 작성하기 전에 스타일시트와 기존 컴포넌트를 읽으세요.
질문 슬롯:
- 체크포인트 1 — 프로젝트/워크플로 맵 확인
- 체크포인트 2 — 계획 확인 + 키 및 프로젝트 이름 수집
- 배포가 진정으로 알려지지 않았고 시크릿을 안전하게 진행할 수 없는 경우에만
이 사이에 마이크로 확인 없음.
분석 패스 (자동 실행)
🧠 질문하기 전에 모든 것을 읽으세요. 개발자는 퀴즈를 푸는 것이 아니라 확인을 받아야 합니다.
자동으로 읽기 — 아직 질문 없음. 다음을 다룹니다:
- 종속성 (Deps) — AI 프레임워크, UI 스택, 패키지 매니저
- 진입점 (Entrypoint) —
configure()가 위치할 곳 - LLM 호출 사이트 — 흐름, 오케스트레이션 패턴
- 세션 추적 (Session tracking) — 대화 ID, 요청 ID, Redis 키, DB 컬럼. 의미론 평가: 후보 ID가 초기화/새 대화 시 변경됩니까? 그렇지 않으면 불일치를 표면화하세요. references/implementation.md를 참조하세요.
- 기존 피드백 UI — thumbs, 평점, 편집, 재시도, 복사 버튼. 이것들에 연결하고 교체하지 마세요.
- 배포 인프라 (Deployment infra) — 묻기 전에 스캔:
helm/,charts/,.github/workflows/,vercel.json,railway.json,render.yaml,fly.toml,docker-compose.yml,Procfile,*.tf,template.yaml
스타일링, 인증, 관련 없는 비즈니스 로직은 건너뜁니다. 에이전트 플로우의 다른 저장소/서비스를 플래그 지정 — 개발자도 여기서 이 스킬을 실행해야 합니다.
프로젝트 맵 구축:
사용 사례: [에이전트가 하는 일]
흐름 → Kelet 프로젝트:
- flow "X" → project "X"
사용자 대상: 예/아니오
스택: [서버] + [LLM 프레임워크]
설정: .env / .envrc / k8s
배포: [플랫폼 | 찾을 수 없음]
모드: 경량 | 전체
ASCII 아키텍처 다이어그램을 구축하여 데이터 흐름과 세션 ID가 이동하는 위치를 보여줍니다.
체크포인트 1: 매핑 확인
다이어그램 + 프로젝트 맵 + 통합 모드 + 간단한 워크플로 요약(단계, 에이전트 관점에서 성공/실패의 모습)을 제시합니다.
AskUserQuestion: "이 다이어그램, 맵, 워크플로 요약이 시스템을 정확하게 나타내고 있습니까? 놓친 것이 있습니까?"
세션 의미론이 진정으로 모호한 경우 — 이 질문에 포함시키고 별도의 슬롯을 사용하지 마세요.
수정 사항이 흐름 수, 프레임워크 또는 세션 구조를 변경하는 경우 — 분석 패스를 다시 수행하세요. 확인될 때까지 신호 분석을 진행하지 마세요.
신호 분석 패스 (내부 추론)
🧠 이 추론을 사용자에게 보여주지 마세요. 체크포인트 2에서 최종 제안을 표면화하세요.
단서를 심는 수사관처럼 생각하세요: 나중에 문제가 발생하면 어떤 빵 조각이 그 근원을 추적하는 데 도움이 될까? 실패를 예측하지 마세요 — 사후에 이를 드러낼 순간을 계측하세요.
하나의 필터: Kelet이 세션 추적에서 이 단서를 도출할 수 있습니까? → 합성(코드 제로). 인간의 행동이나 외부 이벤트가 필요합니까? → 코딩된 신호.
합성 (플랫폼, 고객 코드 불필요):
이 특정 사용 사례에 대한 의미 있는 품질 신호를 포착하는 평가자를 선택하세요. 앵커: 작업 완료(Task Completion). 이 앱에서 "좋음"과 "나쁨"이 어떻게 보이는지 반영하는 1–2개를 추가하세요. 차원당 하나의 평가자 — 차원을 복제하면 노이즈가 배가됩니다. 사전 설정 목록은 references/signals.md를 참조하세요.
코딩 — 프론트엔드 (경량: 최대 0–2개):
거의 항상 프론트엔드 — AI 출력에 반응하는 인간. 서버 측은 소비자가 다른 시스템이거나 피드백이 엔드포인트(예: /approve)를 통해 도착하는 경우에만 해당됩니다.
- 투표 →
VoteFeedback, 편집 →useFeedbackState, 행동 이벤트 →useKeletSignal kind:FEEDBACK·EDIT·EVENT·METRIC·ARBITRARY—source:HUMAN·LABEL·SYNTHETIC- React UI 스캔: AI 출력 편집 입력 →
useFeedbackState; 클립보드 복사, 재시도, 세션 초기화 →useKeletSignal. 복사는 AI 텍스트를 렌더링하는 앱의 경우 항상 제안할 가치가 있습니다 — 아직 버튼이 없더라도 자연스러운 어포던스이자 강력한 암시적 신호입니다. 최대 1–2개 제안.
코딩 — 서버 측: 브라우저 UI가 없거나 피드백이 엔드포인트 기반인 경우에만 해당됩니다.
체크포인트 2 준비: 신호 제안 + 프로젝트 이름 제안 + "보게 될 것" 미리보기.
체크포인트 2: 계획 확인 + 입력 수집
신호 결과 + 완전한 경량 계획을 제시합니다. 개발자에게 설계를 요청하지 말고 제안하세요.
아직 계획 모드 — 아직 ExitPlanMode를 호출하지 마세요.
단일 AskUserQuestion (multiSelect: true), 구조화:
- 제안된 합성 평가자 (multiSelect) — 각 제안된 평가자를 옵션으로 나열하여 개발자가 프로젝트에 포함할 평가자를 명시적으로 선택하도록 합니다. "없음" 옵션을 포함하세요.
- 계획 승인 — "계획의 나머지 부분이 적절해 보입니까?"
- 키 + 프로젝트 이름 (누락된 것만):
KELET_API_KEY(sk-kelet-...) — console.kelet.ai/api-keys에서 획득. 합성 자동 생성에 필요합니다.- 게시 가능 키 (
pk-kelet-...) — 계획에 VoteFeedback이 있는 경우에만 필요합니다. - 프로젝트 이름: 먼저 생성 console.kelet.ai → 상단 탐색 → 새 프로젝트. 잘못된 이름 = 자동 라우팅 실패; 서버가 힌트와 함께 404를 반환합니다. 이를 표면화하세요.
- API 키 모드 (합성 평가자가 선택된 경우에만):
- "시크릿 키 붙여넣기 (sk-kelet-...)" → 기본 자동 생성.
- "하나 가져오겠습니다" → 중단: "console.kelet.ai/api-keys에서 키를 가져오세요(10초 소요), 계속하려면 여기에 붙여넣으세요."
- "여기에 시크릿을 붙여넣을 수 없습니다" → 딥링크 대체.
평가자 생성
기본 (키 붙여넣기): curl 전에, 다음을 그대로 출력:
⏳ 평가자를 생성 중입니다. 1~3분 (때로는 최대 5분) 소요 — Kelet이 LLM으로 각 설정을 생성하고 중복 제거 패스를 실행합니다. 기다려 주세요. 취소하지 마세요.
그런 다음 references/signals.md § 기본: API 호출을 실행하세요.
200 응답 시: ✅ Kelet이 이제 {project}을(를) 모니터링합니다. 첫 번째 평가자 결과는 ~3분 후 https://console.kelet.ai/{project}/signals에서 확인할 수 있습니다.
대체 (키를 붙여넣을 수 없음): references/signals.md에 따라 base64 마크다운 링크를 구축하세요.
보게 될 것
제안된 계획의 항목에 대한 행만 포함하는 테이블을 표시하세요:
| 구현 후 | Kelet 콘솔에서 보이는 것 |
|---|---|
kelet.configure() | 추적에서 LLM 스팬: 모델, 토큰, 지연 시간, 오류 |
agentic_session() | 세션 보기: RCA를 위해 그룹화된 전체 대화 |
| VoteFeedback | 신호: 👍/👎가 정확한 추적과 상관 관계 있음 |
편집 신호 (useFeedbackState) | 신호: 사용자가 수정한 내용 — 모델 오류를 드러냄 |
| 플랫폼 합성 신호 | 신호: 자동화된 품질 점수 |
source=SYNTHETIC 코드는 개발자가 명시적으로 요청하고 플랫폼이 구현할 수 없는 경우에만 작성하세요 — 플랫폼이 처리할 수 없는 이유를 설명하고 진행하기 전에 확인을 요청하세요.
구현 승인
예외: 배포가 알려지지 않은 것으로 플래그 지정되었고 시크릿을 안전하게 처리할 수 없는 경우, 질문 슬롯 3을 사용하세요: "어떻게 배포합니까? 시크릿은 어떻게 관리됩니까?" → references/deployment.md를 따르세요. 배포가 식별되었거나 관련이 없는 경우 건너뜁니다.
전체 구현 계획을 제시하고, ExitPlanMode를 호출하여 승인을 받은 다음 구현하세요.
API 키
두 가지 유형 — 절대 혼용하지 마세요:
- 시크릿 (Secret) (
KELET_API_KEY,sk-kelet-...): 서버 전용. SDK는 오류 없이 두 키 유형을 모두 허용합니다 — 잘못된 키를 사용하면 자동으로 실패합니다. - 게시 가능 (Publishable) (
VITE_KELET_PUBLISHABLE_KEY/NEXT_PUBLIC_KELET_PUBLISHABLE_KEY,pk-kelet-...): 프론트엔드 전용.
설정에 작성: .env → KEY=value · .envrc → export KEY=value · K8s → secrets manifest. .gitignore에 추가. 프로젝트 이름을 하드코딩하지 마세요 — 항상 환경 변수 사용. 앱에 서버와 프론트엔드가 모두 있는 경우, 두 env 파일에 키를 작성하세요 — 서버 .env에 시크릿 키, frontend/.env (또는 Vite/Next가 읽는 위치)에 게시 가능 키. 프로덕션의 경우 references/deployment.md를 따르세요.
세션
세션 = 하나의 작업 단위. 새 컨텍스트 = 새 세션.
agentic_session()이 필요하지 않음 (자동 계측됨):
LangChain/LangGraph · LlamaIndex · CrewAI · Haystack · Google ADK (kelet[google-adk] 권장) · pydantic-ai · DSPy · Langfuse · Langroid · OpenInference/OpenLLMetry 사용하는 모든 것
⚠️ 재정의 — 아래 REQUIRED 블록을 먼저 읽으세요. 위 목록은 프레임워크가 세션 ID도 소유한다고 가정합니다(수명이 짧은 프로세스 내 실행). 앱이 자체적으로 세션 ID(Redis, DB, 서버 발급 UUID)를 생성하거나 여러 요청에 걸쳐 여러 LLM 호출을 오케스트레이션하는 경우 agentic_session(session_id=...)은 프레임워크에 관계없이 필수(REQUIRED) 입니다 — 프레임워크는 사용자의 ID를 알 수 없으며 스팬이 연결되지 않습니다. 확실하지 않으면 래핑하세요.
⚠️ 기본 LiteLLM — 추적은 자동으로 캡처되지만, LiteLLM은 세션/에이전트 컨텍스트를 자체 스팬으로 전파하지 않습니다. LiteLLM이 직접 호출되는 경우(Google ADK와 같은 다른 지원 프레임워크를 통하지 않고), 호출을 agentic_session()(및 선택적으로 kelet.agent())으로 래핑하여 그룹화하세요. LiteLLM이 다른 계측된 프레임워크에서 실행되는 경우, 상위 스팬이 컨텍스트를 제공하므로 래핑이 필요하지 않습니다.
목록에 없는 경우 — 생략하기 전에 조사하세요.
agentic_session(session_id=...)이 필요함 (생략 시 모두 자동 실패):
- 앱이 세션 ID 소유 (Redis, DB, 서버 생성): 프레임워크가 모름 → VoteFeedback 연결이 깨짐
- 루프를 직접 소유 (에이전트 A → 에이전트 B, Temporal, 사용자 지정 오케스트레이터): 어떤 프레임워크도 전체 세션 ID를 설정하지 않음 → 스팬이 연결되지 않은 추적으로 표시됨. TS:
agenticSession({ sessionId }, callback).
⚠️ Vercel AI SDK — 지원되는 프레임워크이지만 세션 ID를 설정하지 않음: 라우트 수준에서 agenticSession()을 사용하세요.
사용자 신원(user identity) ≠ 세션 ID. 안정적인 식별자(전화번호, 이메일, user_id)는 세션보다 오래 지속됩니다. 앱에 안정적인 사용자 신원이 있는 경우: 대화당 UUID를 kelet_session_id로 생성하고 초기화 시 다시 생성. 식별자를 자동으로 평가: 비-PII(내부 사용자 ID, 불투명 UUID) → 묻지 않고 user_id=로 연결. 명백한 PII(전화번호, 이메일) → 생략하지만 눈에 띄게 표시: "⚠️ user_id=가 설정되지 않았습니다 — 사용자 식별자가 PII(전화번호/이메일)입니다. 비-PII 사용자 ID가 있다면 여기에 전달하여 사용자별 RCA를 활성화하세요." 진정으로 모호한 경우 → 체크포인트 1에 포함시키고 별도의 슬롯을 사용하지 마세요.
시그니처는 references/api.md를 참조하세요. 스택별 주의사항은 references/stack-notes.md를 참조하세요.
구현 참조
references/implementation.md 참조.
[truncated for translation]