CKP LLM: AI 에이전트와 지식 베이스 사이의 누락된 계층

지난주 나의 AI 코딩 에이전트가 매우 자신감 있고 상세한 답변을 내놓았는데, 완전히 잘못된 프로젝트를 참조하고 있었습니다.

문제는 모델이 아니었습니다. 바로 컨텍스트 (Context) 문제였습니다. 에이전트가 20개의 지식 파일을 로드한 뒤, 답변을 위해 잘못된 파일을 선택한 것이었습니다. 신호 (Signal)가 노이즈 (Noise) 속에 파묻혀 있었습니다.

이 버그를 계기로 저는 CKP LLM — Compiled Knowledge Pattern을 구축하게 되었습니다.

문제점

AI 코딩 에이전트를 사용하는 대부분의 개발자들은 지식 베이스 (Knowledge Base)를 구축합니다. 프로젝트, 아키텍처 결정 사항, 반복되는 패턴을 설명하는 Markdown 파일 폴더를 만드는 방식입니다. 에이전트는 시작 시 이 파일들을 읽고 메모리 (Memory)로 사용합니다.

이 방식은 작동합니다. 하지만 작동하지 않는 순간이 옵니다.

에이전트는 매번 모든 것을 로드합니다. 질문이 인증 (Authentication)에 관한 것이든 데이터베이스 스키마 (Database Schemas)에 관한 것이든, 에이전트는 답변하기 전에 20개의 파일을 모두 읽습니다. 컨텍스트가 노이즈로 가득 차게 됩니다. 답변의 품질이 떨어지는데, 이는 LLM이 나빠서가 아니라 너무 많은 것을 읽고 있기 때문입니다.

RAG (Retrieval-Augmented Generation)는 대규모 환경에서 이 문제를 해결하지만, 20~100개의 파일로 구성된 개인 또는 팀 지식 베이스의 경우 과잉 대응 (Overkill)입니다. 임베딩 모델 (Embedding Model), 벡터 스토어 (Vector Store), 그리고 매 쿼리마다 실행 시점의 연산 (Runtime Computation)이 필요합니다. 문제의 규모에 비해 너무 복잡합니다.

아이디어: 더 스마트한 파일

만약 지식 파일이 에이전트에게 언제 로드해야 하는지, 그리고 무엇을 함께 가져와야 하는지를 알려줄 수 있다면 어떨까요?

CKP는 각 지식 파일에 다섯 가지 구조화된 필드를 추가합니다:

---
CONCEPT:      mentat
TLDR:         Civic intelligence platform with ISTAT data, RAG chat and AI analytics for municipalities.
...

파일의 본문은 변경되지 않습니다. 그 외의 모든 것은 그대로 유지됩니다.

각 필드의 역할

TLDR — LLM 읽기에 최적화된 한 문장입니다. 만약 이 내용만으로 이미 쿼리 (Query)에 대한 답변이 가능하다면, 전체 파일은 로드되지 않습니다.

ANSWERS_WHEN — 이 파일을 트리거하는 키워드 (Keywords)입니다. 에이전트는 무엇인가를 로드하기 전에 쿼리와 이 키워드들을 대조합니다.

SIMILAR_HIGH — 이 파일과 항상 함께 로드되어야 하는 파일들입니다. 직접적인 의존성 (Dependencies), 공유 API, 동일한 아키텍처 등이 해당됩니다. 에이전트가 추론할 필요가 없도록 명시적으로 인코딩됩니다.

SIMILAR_MID — 쿼리 도메인(query domain)이 해당 파일과도 일치할 때만 로드되는 파일입니다. 자동이 아닌 조건부(Conditional)로 작동합니다.

VALIDATED — 파일 단위가 아닌 관계(relationship)당 부여되는 타임스탬프입니다. 관련 파일이 이 날짜 이후에 업데이트되었다면, 해당 특정 관계는 잠재적으로 오래된(stale) 것으로 표시됩니다.

쿼리 시점의 작동 방식 (How It Works at Query Time)

에이전트는 모든 지식 파일의 헤더(header)만을 포함하는 작은 _index.md를 유지하며, 본문 내용은 포함하지 않습니다. 이 인덱스는 항상 컨텍스트(context) 내에 존재합니다. 그 외의 모든 것은 필요할 때(on demand) 로드됩니다.

쿼리가 도착하면:

인덱스를 읽고, 모든 항목의 ANSWERS_WHEN을 대상으로 쿼리 키워드를 매칭합니다.
매칭되는 파일과 해당 파일의 모든 SIMILAR_HIGH를 자동으로 로드합니다.
SIMILAR_MID는 해당 파일의 키워드 또한 일치하는 경우에만 로드합니다.
만약 TLDR이 이미 쿼리에 대한 답을 제공한다면, 전체 파일을 아예 로드하지 않습니다.

결과: 20개가 아닌 2~4개의 파일만 로드됩니다.

핵심 혁신: 컴파일 타임(Compile Time) vs 런타임(Runtime)

기존의 시맨틱 검색(semantic search)은 런타임에 관계를 계산합니다. 즉, 모든 쿼리가 임베딩 조회(embedding lookup), 유사도 계산(similarity calculation), 검색(retrieval)을 트리거합니다. 이 계산은 하루에도 수백 번씩 실행됩니다.

CKP는 이 계산을 **쓰기 시점(write time)**으로 옮깁니다. 지식 파일을 업데이트할 때, LLM이 관계를 한 번 계산하여 헤더에 저장합니다. 쿼리 시점에 에이전트는 미리 계산된 구조를 읽기만 하면 됩니다.

벡터 데이터베이스(vector database)가 필요 없습니다. 런타임에 임베딩 모델(embedding model)도 필요 없습니다. 유지 관리해야 할 인프라도 없습니다.

왜 소수점 점수 대신 범주형 계층(categorical tiers)을 사용하는가?

LLM은 소수점 점수를 할당할 때보다 범주(categories)로 분류할 때 훨씬 더 일관적입니다. 한 세션에서의 0.73이라는 점수가 다른 세션에서는 0.61이 될 수 있습니다.

고정된 루브릭(rubric)과 앵커 예시(anchor examples)를 사용하면, HIGH / MID / 없음 방식은 어떤 LLM과 어떤 세션에서도 안정적이고 재현 가능한 결과를 생성합니다:

계층 (Tier)	정의 (Definition)	상한 (Cap)	앵커 예시 (Anchor example)
HIGH	한 개념을 이해하기 위해 다른 개념의 이해가 필수적임. 직접적인 의존성.	3	`jwt` ↔ `oauth2`
...

벤치마크 (Benchmarks)

Claude Sonnet을 사용하여 실제 NestJS 코드베이스(Mentat — 시민 지능 플랫폼)에서 테스트되었습니다. 5가지 쿼리 유형, 유형당 3회 실행, 총 30회 실행, 두 가지 환경을 비교했습니다.

지식 베이스 크기에 따른 토큰 감소 (Token reduction)

파일 수	토큰 — CKP 미사용	토큰 — CKP 사용	감소율
3개 파일	564	522	8% ← 손익분기점 미만
...

손익분기점은 약 5~6개 파일입니다. 그 이상부터는 절감 효과가 초선형적(super-linearly)으로 증가합니다.

답변 정확도 (Answer accuracy)

환경	정답	전체	정확도
CKP 미사용 (11개 파일)	9	15	60%
CKP 사용 (11개 파일)	15	15	100%

CKP 미사용 시의 실패는 무작위가 아니었습니다:

Q3 (Auth/JWT Guards): 에이전트가 지리(geography), ISTAT, 프론트엔드 파일의 정보를 혼합했습니다. 관련 없는 모듈을 참조하며 모호하고 희석된 답변을 생성했습니다.
Q4 (Stripe — 도메인 외): 에이전트가 시민 플랫폼 코드베이스 내의 Stripe와 기존 NestJS 모듈 간의 연결 관계를 환각(hallucination)했습니다.

Q4에서 CKP는 아무것도 로드하지 않았고, 도메인 외(out-of-domain)임을 선언한 뒤 정직하게 답변했습니다.

컨텍스트(Context) 축소는 단순히 비용 절감만을 의미하지 않습니다. 이는 환각(hallucination) 위험을 줄이는 것입니다.

라우팅 세부 정보 — 쿼리당 CKP가 로드한 내용

쿼리	로드된 파일	이유
Q1 — ISTAT SDMX fetch	`mentat-istat` + `mentat`	키워드 일치: ISTAT, SDMX, municipio
...

비용 영향 (Claude Sonnet — 입력 토큰 100만 개당 $3, 쿼리당 3,182개 토큰 절감)

일일 쿼리 수	월간 절감액
1,000	$286
...

기존 메모리 뱅크(Memory Banks)와의 통합

이미 구조화된 메모리 뱅크(Karpathy 스타일)를 사용하고 있다면, CKP는 이를 대체하지 않습니다. 그 위에 계층을 쌓는 방식입니다.

projects/ 파일에 CKP 헤더를 추가하십시오. 기존의 메타데이터 필드는 변경되지 않은 상태로 유지됩니다. 인덱스에는 TLDR과 ANSWERS_WHEN이라는 두 개의 새로운 컬럼이 추가됩니다.

에이전트 설정에는 새로운 블록인 BOOT 프로토콜이 추가됩니다. 이 프로토콜은 세션 시작 시 인덱스를 읽고, package.json, README.md, 그리고 소스 폴더 구조를 읽어와 존재하지 않는 경우 자동으로 memory-bank/ 구조를 생성하는 INIT 루틴을 포함합니다. 질문할 필요도 없고, 별도의 설정도 필요 없습니다.

## CKP LLM — Compiled Knowledge Pattern (필수)

### BOOT — 모든 첫 메시지에서 무조건 실행
...

Karpathy의 LLM Wiki 패턴을 기반으로 구축

CKP는 Andrej Karpathy의 LLM Wiki 패턴을 기반으로 합니다. 이 패턴은 지식을 구조화된 파일로 컴파일하여 컨텍스트에 직접 로드하는 방법을 제안했습니다.

원래 패턴의 격차: 파일들이 고립되어 있습니다. 에이전트는 어떤 파일이 존재하는지 알지만, 어떤 파일들이 서로 관련 있는지, 그리고 얼마나 강하게 관련되는지를 추론해야 합니다. CKP는 이러한 관계를 명시적이고(explicit), 사전 계산되며(pre-computed), 일관성 있게(consistent) 만듭니다.

컴파일된 위키에서 자체 라우팅 지식 그래프로, 그 모든 것이 일반 텍스트에 저장됩니다.

이런 분들께 적합합니다

CKP는 다음 사용자들을 위해 설계되었습니다:

AI 코딩 에이전트를 매일 사용하는 비용 절감 개발자
지식 베이스가 10개에서 200개의 파일로 구성된 팀
인프라를 추가하지 않고도 더 스마트한 컨텍스트 관리가 필요한 모든 사람
모든 LLM (Claude, GPT, Gemini, 로컬 모델), 모든 에이전트, 모든 파일 형식

수백만 개의 문서를 처리하도록 설계된 것은 아닙니다. 그 규모에서는 RAG가 여전히 적절한 도구입니다. CKP는 '모두 로드하기'와 '완벽한 RAG 인프라' 사이의 격차를 메웁니다.

시작하기

전체 패턴 문서 + 복사/붙여넣기 AGENT.md / GEMINI.md 규칙:

https://alessandro-marocchini.github.io/ckp-llm/

첫 번째 지식 파일에 헤더를 추가하세요. 에이전트 설정에 BOOT 규칙을 추가하세요. 나머지는 자동으로 처리됩니다.

Aworan에서 시민 기술 및 AI 기반 플랫폼을 개발하는 과정의 일부로 구축되었습니다.

벤치마크 방법론 (Benchmark methodology): 토큰 수 (token counts)는 문자 기반 추정치 (chars ÷ 4)입니다. 시뮬레이션은 세션 내에서 결정론적 (deterministic)으로 수행됩니다. 모델 (Model): Claude Sonnet (Thinking). 날짜 (Date): 2026-05-20. 전체 원시 데이터 (Full raw data)는 보고서 (writeup)에서 확인할 수 있습니다.