Claude Code CLI + RAG + Context Engineering: полный гайд

# Требования: Node.js 18+
node --version  # v18.x или выше

# Установка через npm
npm install -g @anthropic-ai/claude-code

# Или через npx (без установки)
npx @anthropic-ai/claude-code

# Проверка
claude --version

# Запуск (потребует API ключ Anthropic)
claude

# Или с указанием модели
claude --model claude-sonnet-4-20250514

npm install -g @anthropic-ai/claude-code
claude --version

# Установка
curl -fsSL https://ollama.ai/install.sh | sh

# MoE модель (30B параметров, 3B активных)
ollama pull qwen3:30b-a3b

# Embedding модель
ollama pull mxbai-embed-large

cat > /tmp/Modelfile << 'EOF'
FROM qwen3:30b-a3b

PARAMETER num_ctx 16384
PARAMETER temperature 0.6

SYSTEM """
You are a DevOps assistant with access to tools and a knowledge base.

CRITICAL BEHAVIOR:
1. ALWAYS use search_knowledge FIRST when user asks about concepts
2. ALWAYS use Read tool when user mentions specific files
3. ALWAYS use Bash tool to verify (nginx -t, docker ps, etc.)
4. NEVER hallucinate file contents — READ them

RESPONSE PATTERN:
1. Search/Read relevant context
2. Analyze what you found
3. Answer based on ACTUAL data
4. If documentation exists, cite it: "According to nginx-guide.md:45..."

MENTORING STYLE:
- Use Socratic method: ask guiding questions
- Don't give full solutions immediately
- If student is stuck long, give more hints

LANGUAGE: Russian for explanations, English for technical terms.
"""
EOF

ollama create devops-assistant -f /tmp/Modelfile

# litellm-config.yaml
model_list:
  - model_name: devops-assistant
    litellm_params:
      model: ollama_chat/devops-assistant:latest
      api_base: http://localhost:11434

general_settings:
  master_key: sk-ant-api03-local-ollama-proxy

docker run -d \
  --name litellm \
  -p 4000:4000 \
  -v $(pwd)/litellm-config.yaml:/app/config.yaml \
  ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml

docker run -d \
  --name qdrant \
  -p 6333:6333 \
  -v qdrant_data:/qdrant/storage \
  qdrant/qdrant

# Реальные параметры из продакшена
CHUNK_SIZE = 800       # ~20-30 строк markdown
CHUNK_OVERLAP = 150    # ~15-20% overlap
MAX_EMBED_CHARS = 8000 # Лимит embedding модели
VECTOR_SIZE = 1024     # mxbai-embed-large

# Индексируем только нужные директории
ALLOWED_DIRS = ["docs", "guides", "tutorials"]

759 файлов → 16,548 чанков
≈ 21.8 чанков на файл
≈ 800 символов = 20-30 строк markdown = 1 логический блок

CHUNK_SIZE = Средняя_длина_файла / Желаемое_кол-во_чанков

Наш случай:
- Средний файл: ~17,500 символов
- Хотим ~20 чанков на файл
- 17,500 / 20 ≈ 875 → округляем до 800

def chunk_text(text, file_path):
    """Чанкуем с metadata для цитирования"""
    chunks = []
    lines = text.split("\n")
    # ...
    chunks.append({
        "content": chunk_text_str,
        "file_path": file_path,      # ← Откуда
        "start_line": start_line,    # ← Где начало
        "end_line": i - 1            # ← Где конец
    })
    return chunks

БЕЗ metadata:
  "Для reverse proxy используйте proxy_pass..."
  → Откуда это? Можно верить?

С metadata:
  "Согласно nginx-guide.md:45-89, для reverse proxy..."
  → Можно проверить, можно открыть файл

#!/usr/bin/env python3
"""index_knowledge.py — Context Engineering: слой знаний"""

import httpx
import hashlib
from pathlib import Path

QDRANT_URL = "http://localhost:6333"
OLLAMA_URL = "http://localhost:11434"
EMBED_MODEL = "mxbai-embed-large"
COLLECTION = "knowledge_base"
CHUNK_SIZE = 800
CHUNK_OVERLAP = 150
MAX_EMBED_CHARS = 8000
ALLOWED_DIRS = ["docs", "guides", "tutorials"]


def get_embedding(text: str) -> list[float]:
    """Embedding с truncation"""
    if len(text) > MAX_EMBED_CHARS:
        text = text[:MAX_EMBED_CHARS]

    response = httpx.post(
        f"{OLLAMA_URL}/api/embeddings",
        json={"model": EMBED_MODEL, "prompt": text},
        timeout=60.0
    )
    return response.json()["embedding"]


def chunk_file(text: str, file_path: str) -> list[dict]:
    """Чанкинг с overlap и metadata"""
    chunks = []
    lines = text.split("\n")
    current_chunk = []
    current_size = 0
    start_line = 1

    for i, line in enumerate(lines, 1):
        line_size = len(line) + 1

        if current_size + line_size > CHUNK_SIZE and current_chunk:
            chunk_text = "\n".join(current_chunk)
            if chunk_text.strip():
                chunks.append({
                    "content": chunk_text,
                    "file_path": file_path,
                    "start_line": start_line,
                    "end_line": i - 1
                })

            # Overlap
            overlap_lines = []
            overlap_size = 0
            for ln in reversed(current_chunk):
                if overlap_size + len(ln) > CHUNK_OVERLAP:
                    break
                overlap_lines.insert(0, ln)
                overlap_size += len(ln)

            current_chunk = overlap_lines
            current_size = overlap_size
            start_line = i - len(overlap_lines)

        current_chunk.append(line)
        current_size += line_size

    # Последний чанк
    if current_chunk:
        chunk_text = "\n".join(current_chunk)
        if chunk_text.strip():
            chunks.append({
                "content": chunk_text,
                "file_path": file_path,
                "start_line": start_line,
                "end_line": len(lines)
            })

    return chunks


def is_allowed(file_path: Path, base: Path) -> bool:
    """Фильтр директорий"""
    rel = str(file_path.relative_to(base))
    return any(rel.startswith(d + "/") for d in ALLOWED_DIRS)


def create_collection():
    """Создать коллекцию с правильным размером вектора"""
    httpx.delete(f"{QDRANT_URL}/collections/{COLLECTION}")
    httpx.put(
        f"{QDRANT_URL}/collections/{COLLECTION}",
        json={"vectors": {"size": 1024, "distance": "Cosine"}}
    )


def index_all(docs_path: str):
    """Индексация с batch upload"""
    base = Path(docs_path)
    all_files = list(base.rglob("*.md"))
    md_files = [f for f in all_files if is_allowed(f, base)]

    print(f"Total: {len(all_files)}, Filtered: {len(md_files)}")

    all_chunks = []
    for f in md_files:
        text = f.read_text(encoding="utf-8", errors="ignore")
        rel_path = str(f.relative_to(base))
        all_chunks.extend(chunk_file(text, rel_path))

    print(f"Chunks: {len(all_chunks)}")

    # Batch upload
    batch = []
    for chunk in all_chunks:
        emb = get_embedding(chunk["content"])
        batch.append({
            "id": int(hashlib.md5(chunk["content"].encode()).hexdigest()[:15], 16),
            "vector": emb,
            "payload": {
                "document": chunk["content"],
                "metadata": {
                    "file_path": chunk["file_path"],
                    "start_line": chunk["start_line"],
                    "end_line": chunk["end_line"]
                }
            }
        })

        if len(batch) >= 20:
            httpx.put(
                f"{QDRANT_URL}/collections/{COLLECTION}/points",
                json={"points": batch},
                timeout=120.0
            )
            print(f"Uploaded {len(batch)} points")
            batch = []

    if batch:
        httpx.put(
            f"{QDRANT_URL}/collections/{COLLECTION}/points",
            json={"points": batch}
        )


if __name__ == "__main__":
    import sys
    create_collection()
    index_all(sys.argv[1] if len(sys.argv) > 1 else ".")

#!/usr/bin/env python3
"""mcp_server.py — Context Engineering: слой инструментов"""

from fastmcp import FastMCP  # Сторонняя библиотека от Prefect (не Anthropic)
import httpx
import json

QDRANT_URL = "http://localhost:6333"
OLLAMA_URL = "http://localhost:11434"
EMBED_MODEL = "mxbai-embed-large"
COLLECTION = "knowledge_base"

mcp = FastMCP("Knowledge Base")


def get_embedding(text: str) -> list[float]:
    with httpx.Client(timeout=30.0) as client:
        response = client.post(
            f"{OLLAMA_URL}/api/embeddings",
            json={"model": EMBED_MODEL, "prompt": text}
        )
        return response.json()["embedding"]


@mcp.tool()
def search_knowledge(query: str, limit: int = 5) -> str:
    """
    Search the knowledge base for relevant documentation.

    Args:
        query: Natural language search query
        limit: Max results (default: 5)

    Returns:
        JSON array of matching documents with source and relevance score
    """
    embedding = get_embedding(query)

    with httpx.Client(timeout=30.0) as client:
        response = client.post(
            f"{QDRANT_URL}/collections/{COLLECTION}/points/search",
            json={
                "vector": embedding,
                "limit": limit,
                "with_payload": True
            }
        )
        results = response.json().get("result", [])

    # Context Engineering: структурированный output
    output = []
    for r in results:
        payload = r.get("payload", {})
        metadata = payload.get("metadata", {})
        output.append({
            "content": payload.get("document", "")[:2000],  # Truncate!
            "source": metadata.get("file_path", "unknown"),
            "lines": f"{metadata.get('start_line', '?')}-{metadata.get('end_line', '?')}",
            "score": round(r.get("score", 0), 3)  # Модель видит уверенность
        })

    return json.dumps(output, ensure_ascii=False, indent=2)


if __name__ == "__main__":
    mcp.run(transport="sse", host="0.0.0.0", port=4002)

// ❌ Плохо: просто текст
"Для настройки reverse proxy используйте proxy_pass директиву..."

// ✅ Хорошо: структура + metadata + score
{
  "content": "## Reverse Proxy\n\nlocation /api/ {\n    proxy_pass http://backend:8000;\n}",
  "source": "nginx-guide.md",
  "lines": "45-89",
  "score": 0.92
}

version: "3.9"

services:
  ollama:
    image: ollama/ollama
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]
    volumes:
      - ollama_data:/root/.ollama
    ports:
      - "11434:11434"

  qdrant:
    image: qdrant/qdrant
    volumes:
      - qdrant_data:/qdrant/storage
    ports:
      - "6333:6333"

  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    command: --config /app/config.yaml
    volumes:
      - ./litellm-config.yaml:/app/config.yaml:ro
    ports:
      - "4000:4000"
    depends_on:
      - ollama

  mcp-rag:
    build: ./mcp-server
    ports:
      - "4002:4002"
    depends_on:
      - qdrant
      - ollama

volumes:
  ollama_data:
  qdrant_data:

# Переменные
export ANTHROPIC_API_KEY="sk-ant-api03-local-ollama-proxy"
export ANTHROPIC_BASE_URL="http://localhost:4000"

# MCP сервер
claude mcp add --transport sse knowledge-base http://localhost:4002/sse

# Запуск
claude --model devops-assistant

Вы: как настроить nginx reverse proxy?

Claude: [search_knowledge("nginx reverse proxy configuration")]

        Нашёл в базе знаний:

        1. nginx-guide.md:45-89 (score: 0.92)
           "## Reverse Proxy
            location /api/ {
                proxy_pass http://backend:8000;
            }"

        2. troubleshooting.md:12-34 (score: 0.85)
           "### Ошибка 502 Bad Gateway..."

        Вижу, что у тебя есть документация по nginx.
        Какой backend ты хочешь проксировать?

# Проверить количество чанков
curl -s http://localhost:6333/collections/knowledge_base | jq '.result.points_count'
# 16548

# Тест поиска
curl -X POST http://localhost:6333/collections/knowledge_base/points/search \
  -H "Content-Type: application/json" \
  -d '{"vector": [...], "limit": 3}' | jq '.result[].score'
# 0.92, 0.85, 0.78

[ ] System Prompt определяет поведение (tools first, style)
[ ] RAG чанки оптимального размера (800-1200 для docs)
[ ] Metadata позволяет цитировать (file_path, lines)
[ ] Score передаётся модели (уверенность)
[ ] Tool output структурирован (JSON, не plain text)
[ ] Truncation на всех уровнях (не переполнять контекст)
[ ] Conversation history ограничена (последние N сообщений)

❌ "Будь умным ассистентом" — бесполезный prompt
✅ "ALWAYS use search_knowledge before answering" — конкретное поведение

❌ Чанки по 5000 символов — потеря precision
✅ Чанки по 800 символов — один логический блок

❌ Возвращать весь документ из RAG — переполнение контекста
✅ Truncate до 2000 символов + metadata для навигации

❌ Игнорировать score — модель не знает уверенность
✅ Передавать score — "score 0.92 means high confidence"

v1: Просто промпт
    "Ты эксперт по nginx"
    → Галлюцинации

v2: Промпт + RAG
    System + search_knowledge
    → Отвечает по документации, но без источников

v3: Промпт + RAG + Metadata
    System + search + file_path + lines + score
    → Цитирует источники, можно проверить

v4: Полный Context Engineering
    System + RAG + Tools + History + Truncation
    → Надёжный ассистент с верифицируемыми ответами

# litellm_config.yaml
model_list:
  - model_name: devops-assistant
    litellm_params:
      model: groq/llama-3.1-70b-versatile
      api_key: os.environ/GROQ_API_KEY

# 7B модель — работает на любом железе с 8GB RAM
ollama pull qwen2.5:7b

# 14B модель — для 12-16GB VRAM
ollama pull qwen2.5:14b-instruct

Context  = System + RAG + Tools + History
Response = f(Context), а не f(Prompt)