Deepseek Code Mastery

DeepSeek Code Mastery — Guia Completa para Claude Code

1. Overview

DeepSeek Code es un asistente de programacion local basado en DeepSeek V3 (API o sesion web) con herramientas MCP (filesystem, shell, search, memory, Serena). Claude Code actua como cirujano (planifica, revisa, orquesta) y delega el trabajo pesado de generacion de codigo a DeepSeek Code como subordinado.

Ubicacion del proyecto: Directorio donde se clono/instalo DeepSeek Code (contiene run.py) Entry point: python run.py (o DeepSeekCode.exe) Lenguaje: Python 3 (PyQt5 para login web, asyncio para networking)

Nota sobre rutas: En esta documentacion, <DEEPSEEK_DIR> se refiere al directorio raiz del proyecto DeepSeek Code (donde esta run.py) y <APPDATA> se refiere al directorio de datos de la aplicacion (%APPDATA%\DeepSeek-Code en Windows, ~/.config/DeepSeek-Code en Linux/macOS). Detecta estas rutas automaticamente al ejecutar comandos.

Modos de Operacion

Flags Globales Nuevos (v2.0)

Sistema Adaptivo de Prompts (v2.0)

El sistema clasifica cada tarea en 5 niveles y adapta automaticamente:

• CHAT (0): "Hola" → ~25 tokens de system prompt, 0 skills
• SIMPLE (1): "Que es un closure?" → ~50 tokens, 0 skills
• CODE_SIMPLE (2): "Arregla typo" → ~80 tokens, max 10K skills
• CODE_COMPLEX (3): "Sistema de inventario" → ~600 tokens, max 40K skills
• DELEGATION (4): Via --delegate → prompt completo, max 80K skills

Negociacion de Skills (v2.0)

Con --negotiate-skills, DeepSeek recibe un catalogo compacto (~2K tokens) de las 51 skills disponibles y elige cuales necesita realmente. Esto reemplaza la inyeccion heuristica y reduce tokens desperdiciados.

Multi-Session (v2.0)

Generaliza quantum (2 instancias) a N instancias con roles:

• generate-review: Generador + reviewer (default)
• full-pipeline: Generador + reviewer + tester
• dual-generator: Dos generadores independientes
• specialist-pair: Dos especialistas en dominios diferentes

2. Rutas y Configuracion

Paths Criticos

Proyecto:    <DEEPSEEK_DIR>/                          (directorio raiz con run.py)
Config:      <APPDATA>/config.json                    (%APPDATA%\DeepSeek-Code en Windows)
WASM:        <APPDATA>/sha3_wasm_bg.wasm              (auto-descargado al primer login)
Skills:      <DEEPSEEK_DIR>/skills/                   (51 archivos .skill)
Memory:      <APPDATA>/memory.md
Surgical:    <APPDATA>/surgical_memory/
Global:      <APPDATA>/global_memory.json
EXE:         <DEEPSEEK_DIR>/dist/DeepSeekCode.exe     (si se compilo con PyInstaller)

config.json (campos importantes)

{
  "bearer_token": "...",       // Token de sesion web (auto via /login)
  "cookies": "...",            // Cookies de sesion web
  "api_key": "...",            // No usado (solo modo web)
  "wasm_path": "...",          // Ruta al WASM para firma de requests web
  "allowed_paths": [],         // Directorios permitidos (vacio = todo)
  "allowed_commands": [],      // Comandos shell permitidos
  "serena_enabled": true,      // Serena code intelligence
  "serena_project": "...",     // Proyecto activo en Serena
  "summary_threshold": 80,     // % de contexto antes de resumir
  "skills_dir": "...",         // Directorio de skills
  "auto_select_model": true,   // Auto deepseek-reasoner para CODE_COMPLEX+DELEGATION
  "thinking_enabled": true,    // Thinking mode en web sessions para codigo
  "pool_size": 5,              // Pool size para futuro multi-session (2-10, quantum actual usa 2)
  "chunk_threshold_tokens": 30000  // Umbral para chunking de templates
}

Autenticacion

DeepSeek Code se conecta directamente a la web de DeepSeek (gratis, open source, sin expiracion). Cada chat tiene 1M tokens de contexto — los chats son independientes y no comparten memoria entre si.

• Modo Web: bearer_token + cookies + WASM para firmar requests. Login via /login (PyQt5 WebEngine). Tokens expiran cada ~24-48h, re-login automatico si falla. Gratis.
• Modo API: api_key de platform.deepseek.com. Pago por tokens.
• 128,000 tokens de contexto — las skills se inyectan generosamente (hasta 80K) dejando espacio para template + respuesta

3. Delegacion Oneshot (--delegate)

Sintaxis Completa

python run.py --delegate "TAREA" [opciones] --json

Opciones:

Flujo Interno de Delegacion

1. Carga config.json y crea DeepSeekCodeClient
2. SurgicalMemory.pre_delegation() -> briefing del proyecto (reglas, errores previos)
3. GlobalMemory.pre_delegation() -> briefing personal cross-proyecto (estilo, skills, errores)
4. build_delegate_skills_context():
   a. Carga CORE_SKILLS siempre (programming-foundations, data-structures, common-errors)
   b. Detecta skills Domain relevantes por keywords de la tarea
   c. Llena hasta el budget de tokens (core:15K + domain:45K + specialist:20K = 80K)
5. SessionOrchestrator.prepare_session_call() detecta inyecciones pendientes:
   - Skills relevantes (TF-IDF semantic detection)
   - SurgicalMemory briefing (contexto del proyecto)
   - GlobalMemory briefing (perfil personal cross-proyecto)
6. chat_in_session() ejecuta protocolo 3-fases:
   Fase 1: system_prompt (DELEGATE_SYSTEM_PROMPT base) -> "OK"
   Fase 2: pending_injections (skills, surgical, global) -> "Ack" por cada uno
   Fase 3: user_message limpio (task + template + context + feedback)
7. DeepSeek genera la respuesta (codigo puro, sin markdown)
8. delegate_validator valida: no truncamiento, TODOs completos, sin errores canvas
9. Si falla validacion y quedan retries: re-intenta con feedback de errores
10. SurgicalMemory.post_delegation() -> aprende de resultado del proyecto
11. GlobalMemory.post_delegation() -> aprende patrones personales cross-proyecto
12. Retorna JSON: { success, response, validation, retries_used, duration_s }

Interpretacion del JSON de Respuesta

{
  "success": true,
  "response": "// === TODO 1: ENEMY_TYPES ===\nlet ENEMY_TYPES = {...}\n...",
  "mode": "delegate",
  "had_template": true,
  "had_context": false,
  "duration_s": 12.5,
  "validation": {
    "valid": true,
    "truncated": false,
    "issues": [],
    "todos_found": ["ENEMY_TYPES", "renderMap"],
    "todos_missing": [],
    "stats": {"lines": 150, "functions": 8}
  },
  "token_usage": {
    "system_prompt": 7000,
    "skills_injected": 35000,
    "surgical_briefing": 1200,
    "global_briefing": 500,
    "template": 3000,
    "context_file": 0,
    "user_prompt": 250,
    "total_input": 46950,
    "response_estimated": 8500,
    "total_estimated": 55450,
    "context_remaining": 953050,
    "context_used_percent": "4.7%"
  }
}

Campos clave:

• success: false + validation.truncated: true = respuesta cortada, reducir scope
• success: false + validation.todos_missing: ["renderMap"] = TODOs no completados
• success: true + response = codigo listo para usar
• token_usage.context_used_percent = cuanto del 1M se consumio
• token_usage.skills_injected = tokens de conocimiento inyectado

Cuando Usar --template vs Tarea Libre

Usar --template cuando:

• Tienes un archivo esqueleto con marcadores // TODO: nombre que DeepSeek debe rellenar
• Quieres controlar la estructura exacta del codigo
• El resultado debe integrarse en un archivo existente

Usar tarea libre (sin --template) cuando:

• Pides generar codigo desde cero
• La tarea es autocontenida (un endpoint, una funcion, un componente)
• No hay estructura preexistente que seguir

Cuando Usar --context

Pasa --context archivo.js cuando quieres que DeepSeek imite el estilo de codigo existente: nombres de variables, patrones, estructura, convenciones del proyecto. DeepSeek lo lee y adapta su output para ser consistente.

Cuando Usar --feedback

Pasa --feedback "descripcion de errores" cuando un intento anterior fallo y quieres que DeepSeek corrija errores especificos. El feedback se inyecta como "CORRECCION IMPORTANTE" en el prompt.

Ejemplo Completo de Delegacion

# Tarea libre - generar desde cero
python run.py --delegate "crea un servidor Express con endpoints CRUD para usuarios, validacion Zod, y middleware de auth JWT" --json

# Con template - rellenar TODOs
python run.py --delegate "implementa las funciones de combate" --template game-combat.js --context game-player.js --json

# Con feedback - corregir intento anterior
python run.py --delegate "implementa sistema de inventario" --template inventory.js --feedback "falta drag-and-drop entre slots, el grid debe ser 6x4" --json

4. Quantum Bridge (--quantum)

Que Es

Delegacion paralela dual: lanza 2 sesiones de DeepSeek simultaneamente, cada una con un "angulo" diferente (perspectiva/enfoque), y luego mergea las respuestas en una sola. Ideal para tareas complejas donde dos perspectivas producen mejor resultado.

Sintaxis

python run.py --quantum "TAREA" [--template archivo] [--quantum-angles "angulo1,angulo2"] --json

Angulos

Automaticos (sin --quantum-angles): el sistema detecta el tipo de tarea y asigna angulos:

• game_full -> "gameplay,visual"
• fullstack -> "frontend,backend"
• refactor -> "architecture,implementation"
• template_split -> "core_logic,visual_audio"

Manuales (con --quantum-angles):

--quantum-angles "logica,render"
--quantum-angles "api,database"
--quantum-angles "core,ui"

Estrategias de Merge (en cascada)

1. Template-guided: Si hay template con TODOs, asigna cada TODO al angulo que mejor lo resolvio
2. Function-based (v4.2): Extrae funciones, clases ES6, y variables de ambas respuestas. Deduplica clases y funciones con pick_better_implementation() (score por lineas de codigo, control flow, error handling, validacion). Compone: variables → clases → funciones. Threshold: >= 1 simbolo merged para usar esta estrategia.
3. Raw: Concatena ambas respuestas eliminando duplicados

Cuando Usar Quantum vs Delegate Simple

Ejemplo

# Juego completo con gameplay + visual
python run.py --quantum "crea un juego de tower defense con oleadas, upgrades y particulas" --template tower-defense.js --json

# Fullstack
python run.py --quantum "crea API REST + frontend React para gestionar tareas" --quantum-angles "api,frontend" --json

5. Multi-Step (--multi-step)

Que Es

Ejecuta un plan de multiples pasos secuenciales y/o paralelos. Cada paso es una delegacion independiente que puede depender de resultados anteriores.

Sintaxis

python run.py --multi-step plan.json --json
# O inline:
python run.py --multi-step-inline '{"steps":[...]}' --json

Formato del Plan JSON

{
  "steps": [
    {
      "id": "step1",
      "task": "crea el modelo de datos de Usuario",
      "template": "models/user.ts",
      "validate": true,
      "max_retries": 2
    },
    {
      "id": "step2",
      "task": "crea los endpoints CRUD usando el modelo",
      "template": "routes/users.ts",
      "context_from": ["step1"],
      "validate": true
    },
    {
      "id": "step3a",
      "task": "crea tests unitarios para el modelo",
      "parallel_group": "tests"
    },
    {
      "id": "step3b",
      "task": "crea tests de integracion para los endpoints",
      "context_from": ["step2"],
      "parallel_group": "tests"
    },
    {
      "id": "step4",
      "task": "crea componente React complejo con formulario",
      "dual_mode": true
    }
  ]
}

Campos de StepSpec

Flujo de Ejecucion

1. Agrupa pasos por parallel_group
2. Ejecuta grupos secuencialmente, pero pasos dentro del grupo en paralelo
3. context_from inyecta el response de pasos anteriores como --context
4. dual_mode: true ejecuta el paso via Quantum Bridge en vez de delegate simple
5. Resultado: JSON con array de resultados por paso

6. Sistema de Skills 3-Tier

Arquitectura

DeepSeek Code tiene un sistema de inyeccion automatica de conocimiento en 3 niveles:

Tier 1 - Core Knowledge (SIEMPRE inyectado en delegacion, ~15K tokens):

• programming-foundations — SOLID, GoF patterns, Clean Code, Error Handling, Async, Testing
• data-structures-algorithms — O(), estructuras, algoritmos, spatial
• common-errors-reference — 27+ errores comunes con soluciones

Tier 2 - Domain Skills (por relevancia de keywords, hasta ~45K tokens):

• Se activan segun las palabras clave de la tarea
• Con 45K tokens de budget, pueden entrar 5-8 skills completas
• Ejemplos: canvas-2d-reference, math-foundations, physics-simulation, typescript-advanced, database-patterns, security-auth-patterns, backend-node-patterns, css-modern-patterns
• 46 skills mapeadas en SKILL_KEYWORD_MAP

Tier 3 - Specialist (si hay espacio, ~20K tokens):

• Skills de nicho que puntuaron pero no entraron en Tier 2
• Con 20K tokens, pueden entrar 2-3 skills adicionales

Budget de Tokens (1M Contexto Web)

Cada chat de DeepSeek via web tiene 1M tokens de contexto (cada ventana de chat es independiente, no comparten memoria entre si). El budget de skills esta diseñado para maximizar conocimiento inyectado dejando amplio espacio para template y respuesta.

Modo Delegacion (1M contexto web):
  Core:       15,000 tokens (siempre presente, ~60K chars)
  Domain:     45,000 tokens (por relevancia, ~180K chars)
  Specialist: 20,000 tokens (si hay espacio, ~80K chars)
  TOTAL:      80,000 tokens para skills (~320K chars, 8% del contexto)

  + DELEGATE_SYSTEM_PROMPT:  ~7,000 tokens
  + SurgicalMemory briefing: ~3,000 tokens
  + GlobalMemory briefing:   ~2,000 tokens
  + Template + context:      variable
  = ~92,000 tokens de sistema (~9% del contexto de 1M)
  = ~908,000 tokens disponibles para la respuesta de DeepSeek

Modo Interactivo (1M contexto web): 80,000 tokens para skills

Nota: Con 1M de contexto via web, el budget de 80K para skills deja espacio masivo. En tareas con templates grandes, el sistema auto-reduce skills inyectadas como optimizacion. Para delegaciones simples sin template, el budget completo funciona bien. DeepSeek es open source y no caduca.

Skills Disponibles (51 total)

Fundamentales (Core): programming-foundations, data-structures-algorithms, common-errors-reference

Juegos: canvas-2d-reference, physics-simulation, game-genre-patterns, web-audio-api, sounds-on-the-web, procedural-generation, character-sprite, custom-algorithmic-art

Web/Frontend: modern-javascript-patterns, vercel-react-best-practices, server-side-rendering, css-modern-patterns, interface-design, ui-ux-pro-max, web-design-guidelines, building-native-ui, chat-ui

Backend: backend-node-patterns, security-auth-patterns, database-patterns, server-management, java-spring-boot

TypeScript: typescript-advanced

3D/GPU: webgpu, threejs-shaders, webgpu-threejs-tsl

Otros: claude-delegate, project-architecture, code-review-excellence, audit-website, launch-strategy, remotion-best-practices, json-canvas, document-chat-interface, official-skill-creator, skill-judge, apollo-mcp-server, cloudflare-mcp-server, audiocraft-audio-generation, manaseed-integration, rivetkit-client-javascript, ue57-rhi-api-migration, create-design-system-rules, custom-web-artifacts-builder, advanced-coding

Seleccion Semantica de Skills (v2.3)

A partir de v2.3, la seleccion de skills usa TF-IDF cosine similarity como metodo primario:

1. SemanticSkillIndex vectoriza las descripciones de las 46 skills del keyword map
2. La tarea del usuario se vectoriza con el mismo TFIDFVectorizer
3. Se calculan cosine similarities y se ranquean las top-K skills
4. Si hay historial en GlobalMemory, search_with_boost() multiplica similarity * bayesian_success_rate
5. Si TF-IDF no encuentra resultados, fallback al keyword map original

Esto permite que tareas como "construir interfaz responsive" matcheen con css-modern-patterns aunque no contengan keywords exactos.

Crear Skills Nuevas

Las skills son archivos .skill (ZIP conteniendo SKILL.md con frontmatter YAML).

Para crear una nueva:

1. Crear archivo .md con frontmatter ---\nname: mi-skill\ndescription: ...\n---
2. Empaquetar como ZIP renombrando a .skill
3. Colocar en <DEEPSEEK_DIR>/skills/
4. Agregar keywords en src/deepseek_code/skills/skill_constants.py -> SKILL_KEYWORD_MAP
5. El SemanticSkillIndex se reconstruye automaticamente al siguiente uso

7. Sistema de Memoria Dual

7a. SurgicalMemory (Nivel 1 — Por Proyecto)

Sistema de memoria persistente que conecta Claude Code (cirujano/planificador) con DeepSeek Code (asistente/ejecutor). Aprende de cada delegacion para mejorar las siguientes.

Flujo:

ANTES de delegar:
  pre_delegation() ->
    1. Detecta proyecto (sube directorios buscando CLAUDE.md, .git, package.json)
    2. Carga store JSON del proyecto (%APPDATA%/surgical_memory/{name}_{hash}.json)
    3. Lee CLAUDE.md si existe
    4. Construye briefing con budget de 3000 tokens:
       Prioridad: rules > errors > conventions > architecture > patterns > claude_md

DESPUES de delegar:
  post_delegation() ->
    1. Aprende reglas de errores detectados
    2. Registra en historial: tarea, modo, exito, duracion
    3. Guarda store actualizado a disco

Busqueda Semantica (v2.3):

# find_relevant(query, section, top_k) — busca entradas relevantes por TF-IDF
store.find_relevant("error innerHTML", "error_log", top_k=5)
# → retorna las 5 entradas mas semanticamente similares a la query
# Fallback Jaccard para corpus <5 entradas

Compactacion Inteligente (v2.3):

• error_log y failure_analyses ahora se ordenan por relevance = temporal_decay(age) * (1 + 0.1*(freq-1))
• Entradas recientes y frecuentes sobreviven; antiguas e infrecuentes se purgan primero

Almacenamiento:

%APPDATA%\DeepSeek-Code\surgical_memory\
  LiminalCrown_a1b2c3d4.json   # Store del proyecto LiminalCrown
  MyWebApp_e5f6g7h8.json       # Store de otro proyecto

7b. GlobalMemory (Nivel 2 — Personal Cross-Proyecto)

Sistema de aprendizaje personal que acumula patrones del desarrollador a traves de TODOS los proyectos. Se vuelve mas inteligente con cada delegacion.

Lo que aprende (7 dimensiones):

1. Estilo de codigo: let vs const, camelCase vs snake_case, idioma de comentarios
2. Skills por exito real: rankea las 51 skills por tasa de exito (no solo keywords)
3. Complejidad optima: sweet spot de TODOs por template y tokens input (EMA)
4. Rendimiento por modo: delegate vs quantum vs multi-step (exito y duracion)
5. Errores cross-proyecto: patrones que se repiten en multiples proyectos
6. Keywords de tarea: que temas tienen mejor tasa de exito
7. Recomendaciones automaticas: briefing con skills a usar/evitar

Briefing inyectado (~2000 tokens max):

== PERFIL PERSONAL DEL DESARROLLADOR (GlobalMemory) ==
ESTILO DE CODIGO:
- Usar let (no const) — 100% preferencia historica
- Naming: camelCase
- Comentarios en espanol

SKILLS RECOMENDADAS (por tasa de exito real):
- canvas-2d-reference: 92% exito (12 usos)
- physics-simulation: 88% exito (8 usos)
EVITAR:
- threejs-shaders (30% exito, trunca 60%)

COMPLEJIDAD OPTIMA:
- TODOs por template: 5 (sweet spot historico)
- Input tokens optimo: ~40,000

RENDIMIENTO POR MODO:
- delegate: 85% exito (50 usos, ~45s promedio)
- quantum: 78% exito (12 usos, ~90s promedio)
== FIN PERFIL PERSONAL ==

Almacenamiento: %APPDATA%\DeepSeek-Code\global_memory.json (unico archivo)

Bayesian Skill Ranking (v2.3):

• Cada skill stat ahora incluye bayesian_mean, bayesian_ci_lower, bayesian_ci_upper
• Calculado via BayesianEstimator(alpha=successes+1, beta=failures+1)
• Con 2 exitos de 3 intentos: mean=0.6, CI 95%=[0.19, 1.0] (alta incertidumbre)
• Con 20 exitos de 25: mean=0.78, CI 95%=[0.61, 0.95] (confianza alta)

Semantic Error Clustering (v2.3):

• add_cross_error() ahora compara nuevos errores con existentes via cosine similarity
• Si similarity > 0.6, merge en vez de crear nueva entrada (reduce duplicados semanticos)

Compactacion automatica:

• Max 30 skill combos, max 20 cross-project errors, max 50 task keywords
• Purga skills con <2 inyecciones y >90 dias sin uso
• Cross-project errors ordenados por temporal_decay(age, half_life=60) * count

Protocolo 3-fases de inyeccion (v2.6)

Fase 1 — System prompt:
  DEEPSEEK_CODE_IDENTITY + DELEGATE_BASE + bloques modulares (~7K tokens, via assemble_delegate_prompt())

Fase 2 — Inyecciones separadas (pending_injections):
  + skill:programming-foundations  (~15K tokens, core skills)
  + skill:domain-relevante         (~45K tokens, domain skills por TF-IDF)
  + memory:surgical-project        (~3K tokens, contexto del proyecto)
  + global:developer-profile       (~2K tokens, perfil personal)
  Total inyecciones: ~80K tokens, cada una como mensaje independiente

Fase 3 — User message limpio:
  build_delegate_prompt(task, template, context, feedback)

SessionOrchestrator trackea que inyecciones ya se enviaron a cada sesion, evitando re-envios en llamadas subsiguientes (~92K tokens ahorrados por reuso).

8. Modo Interactivo y Agente

Interactivo (default)

python run.py
# o
DeepSeekCode.exe

Chat con herramientas MCP: filesystem (read/write/edit/list/delete/move/copy), shell, web search, memory, Serena.

Comandos internos:

• /exit — Exit
• /skills — List available skills
• /agent <goal> — Run autonomous agent
• /skill <name> [args] — Run skill workflow
• /serena [start|stop|status] — Control Serena
• /login — Web login (PyQt5 WebEngine)
• /test — Verify connection
• /health — Session health check
• /account — Multi-account management
• /lang — Change language (English/Spanish/Japanese)
• /keys — API key help

Agente Autonomo (--agent)

python run.py --agent "crea un proyecto React con auth, dashboard y API backend" --json

El agente planifica, ejecuta acciones con herramientas, evalua resultados, y adapta su plan. Incluye la palabra COMPLETADO cuando termina.

Serena Auto-Init (v4.2): En agent mode, Serena se inicializa automaticamente al arrancar — no requiere /serena start manual. Las 3 herramientas de code intelligence (serena_search_for_pattern, serena_get_symbols_overview, serena_find_symbol) quedan disponibles para que el agente navegue codigo de forma simbolica sin intervencion del usuario.

8.5. DeepSeek V3.2 — Auto-Select, Thinking, Chunking

Auto-Select de Modelo

El sistema selecciona automaticamente el modelo optimo segun la complejidad:

deepseek-reasoner da 64K output max con chain-of-thought (vs 8K de deepseek-chat). Se activa automaticamente — no necesita flags especiales. Desactivar con "auto_select_model": false en config.json.

Thinking Mode (Web Sessions)

Cuando "thinking_enabled": true en config, las sesiones web envian thinking_enabled: true en el payload SSE, activando el razonamiento profundo de DeepSeek para codigo.

Template Chunking

Templates >30K tokens se dividen automaticamente en chunks por bloques TODO:

1. Detecta // === TODO 1A: nombre === markers
2. Divide en chunks de ~5K tokens cada uno
3. Cada chunk recibe contexto del output anterior
4. Si no hay TODOs, divide por lineas (fallback)

Umbral configurable: "chunk_threshold_tokens": 30000 en config.json.

Sesiones Paralelas (Quantum)

Quantum Bridge usa DualSession con 2 clientes en paralelo. La funcion create_pool_clients(N) esta disponible en quantum_helpers.py para futuras implementaciones multi-session, pero actualmente el runner quantum solo usa 2 sesiones.

# quantum_helpers.py - disponible para uso futuro
from cli.quantum_helpers import create_pool_clients
clients = create_pool_clients(config, mcp_server)  # Default: 5

Config "pool_size": N (clamp: 2-10) para cuando se integre multi-session.

8.6. Intelligence Package (v2.2) — 5 Features Revolucionarias

El Intelligence Package convierte a DeepSeek Code de un generador de codigo en un sistema que aprende, predice y se auto-corrige. Todas las features son fail-safe: si fallan, el flujo principal continua sin interrupcion.

Feature 1: Introspective Debugging

Cuando una delegacion falla, en vez de retry ciego, analiza la causa raiz correlacionando con el historial de errores del SurgicalMemory.

Antes (retry ciego):
  Falla → "intenta de nuevo" → misma falla → frustración

Ahora (root cause analysis):
  Falla → analiza patron → "truncation_many_todos" detectado
       → fix: "Dividir template: TODOs 1-5 en chunk A, 6-10 en chunk B"
       → retry dirigido con feedback especifico → exito

Patrones conocidos: truncation, missing_todos, innerHTML_violation, const_usage. Se integra automaticamente en el review phase de collaboration.py (via chat_in_session() con protocolo 3-fases).

Feature 2: Shadow Learning

Aprende de las correcciones manuales del usuario. Despues de cada delegacion exitosa, compara lo que DeepSeek genero con lo que el usuario realmente commiteo (via git diff).

Ciclo de aprendizaje:
  1. DeepSeek genera codigo sin try/catch
  2. Usuario agrega try/catch manualmente y commitea
  3. Shadow Learning detecta patron: "added_error_handling" (git diff)
  4. Siguiente delegacion: "CORRECCIONES APRENDIDAS: [3x] Usuario siempre agrega try/catch"
  5. DeepSeek genera codigo CON try/catch automaticamente

7 clasificadores: error_handling, logging, null_check, type_annotation, let_to_const, const_to_let, added_comments. Tambien detecta renombramientos sistematicos.

Feature 3: Git Intelligence (MCP Tool)

Detecta y resuelve conflictos de merge usando AI con contexto del proyecto. Expuesto como MCP tool resolve_conflicts para que Claude Code lo invoque directamente.

# Detectar conflictos
python -c "from deepseek_code.intelligence.git_intel import detect_conflicts; print(detect_conflicts('.'))"

# Via MCP tool (Claude Code invoca directamente):
# resolve_conflicts(action="detect", project_path="/proyecto")
# resolve_conflicts(action="preview", project_path="/proyecto")
# resolve_conflicts(action="resolve", project_path="/proyecto", auto_apply=true)

Acciones: detect (lista archivos), preview (muestra conflictos), resolve (resuelve con heuristica o AI).

Feature 4: Requirements Pipeline

Parsea un documento de requisitos (markdown/texto) y genera un plan multi-paso ejecutable compatible con --multi-step.

# Solo generar plan
python run.py --requirements features.md --json

# Generar plan Y ejecutarlo automaticamente
python run.py --requirements features.md --auto-execute --json

Deteccion automatica de:

• Prioridad: MUST/REQUIRED → "must", SHOULD → "should", COULD → "could"
• Dependencias: "depende de:", "requires:", "after:", "prerequisitos:"
• Formato: Headers markdown, listas numeradas, parrafos libres

Genera plan con topological sort + parallel grouping para maxima eficiencia.

Feature 5: Predictive Intelligence

Analiza memorias existentes (Surgical + Global) para generar un reporte de salud predictivo.

python run.py --health-report --json
# o con proyecto especifico:
python run.py --health-report --project-context ./CLAUDE.md --json

Detecta:

• File risks: Archivos cerca del limite de 400 LOC (75%+)
• Error clusters: Errores recurrentes agrupados por tipo con tendencias
• Tech debt trends: failure_rate creciente, duracion aumentando, errores repetidos
• Risk level: healthy / warning / critical con recomendaciones priorizadas

Bayesian Composite Risk (v2.3):

• bayesian_risk_score (0-100): 50% failure rate + 20% trend severity + 30% file/debt risks
• confidence_intervals: CI 95% para delegation success rate via Beta posterior
• trend_slopes: Mann-Kendall trend direction para duration y error frequency series

Protocolo de Inyeccion con Intelligence Data (v2.6)

Fase 1 — System prompt:
  DEEPSEEK_CODE_IDENTITY + DELEGATE_BASE + bloques modulares (~7K tokens)

Fase 2 — Inyecciones via SessionOrchestrator:
  + skill:core-skills            (~15K tokens, siempre inyectados)
  + skill:domain-detected        (~45K tokens, TF-IDF semantic match)
  + memory:surgical-project      (~3K tokens, proyecto + intelligence data)
  + global:developer-profile     (~2K tokens, perfil personal)
  Total: ~80K tokens en mensajes separados (trackeo por sesion)

Fase 3 — User message limpio (task + template)

El briefing de SurgicalMemory ahora incluye seccion 5.5 "Intelligence Data":

• Shadow corrections aprendidas (frecuencia >= 2)
• Reglas de prevencion de failure analyses

8.7. Semantic Engine (v2.3) — Motor Central de Inteligencia

El Semantic Engine es un modulo 100% Python puro (zero dependencies) que reemplaza heuristicas basicas con algoritmos reales. Todos los subsistemas lo consumen.

Componentes del Engine

Tokenizacion

Input: "sistema de inventario drag-and-drop"
→ lowercase + strip accents
→ unigrams: ["sistema", "de", "inventario", "drag", "and", "drop"]
→ bigrams: ["sistema_de", "de_inventario", "inventario_drag", ...]
→ TF-IDF vector (sparse dict)

Impacto en Subsistemas

Skills (SemanticSkillIndex):

• Antes: 46-entry keyword map (match exacto)
• Ahora: TF-IDF cosine similarity sobre descripciones de skills
• search_with_boost(): similaridad * bayesian_success_rate (skills con historial de exito suben)
• Fallback a keywords si TF-IDF no encuentra resultados

SurgicalMemory (find_relevant):

• Antes: FIFO (primero-entra-ultimo-sale)
• Ahora: relevance = temporal_decay(age) * (1 + 0.1*(freq-1))
• find_relevant(query, section): busqueda TF-IDF sobre entradas de memoria
• Compactacion: ordena por relevancia en vez de FIFO
• Fallback Jaccard para corpus pequeños (<5 entradas)

GlobalMemory (Bayesian):

• Skill stats: BayesianEstimator.from_stats(successes, total) → mean, CI 95%
• Error clustering: merge semantico si cosine_similarity > 0.6
• Compactacion: temporal_decay(age, half_life=60) * count

Predictive Intelligence (Bayesian composite risk):

• composite_risk = 0.5*failure_rate + 0.2*trend_severity + 0.3*file_debt_risks (0-100)
• Confidence intervals via normal approximation del Beta posterior
• Mann-Kendall trend slopes para delegation duration y error frequency
• HealthReport ahora incluye: bayesian_risk_score, confidence_intervals, trend_slopes

Archivos del Semantic Engine

src/deepseek_code/intelligence/semantic_engine.py  (258 LOC) — Motor central
src/deepseek_code/intelligence/predictor_bayesian.py (145 LOC) — Helper Bayesiano
src/deepseek_code/skills/semantic_skill_index.py   (104 LOC) — Indice semantico de skills

9. Patrones de Uso Optimos

Receta: Generar Codigo de Juego

# 1. Crear template con TODOs
# 2. Pasar un juego existente similar como contexto
python run.py --delegate "implementa juego SHMUP con oleadas, power-ups y boss" \
  --template shmup-template.js \
  --context existing-game.js \
  --json

Tip: DeepSeek inyecta automaticamente: canvas-2d-reference, physics-simulation, game-genre-patterns, web-audio-api, math-foundations.

Receta: Backend Completo

# Quantum con angulos api + database
python run.py --quantum "crea API REST completa para e-commerce: productos, carrito, ordenes, auth JWT" \
  --quantum-angles "api,database" \
  --json

Tip: DeepSeek inyecta: backend-node-patterns, security-auth-patterns, database-patterns, typescript-advanced.

Receta: Feature Multi-Archivo

# Crear plan JSON
echo '{
  "steps": [
    {"id": "model", "task": "modelo TypeScript de Usuario con Zod schema"},
    {"id": "api", "task": "endpoints Express CRUD", "context_from": ["model"]},
    {"id": "tests", "task": "tests con vitest", "context_from": ["model", "api"]}
  ]
}' > plan.json

python run.py --multi-step plan.json --json

Receta: Debugging/Correccion

# Primer intento
python run.py --delegate "crea sistema de inventario drag-and-drop" --template inventory.js --json

# Si falla, corregir con feedback
python run.py --delegate "crea sistema de inventario drag-and-drop" \
  --template inventory.js \
  --feedback "el drag no funciona: falta preventDefault en dragover, los items no se renderizan en el slot destino" \
  --json

Receta: Generacion Rapida sin Template

# Solo una funcion/componente
python run.py --delegate "funcion JavaScript que implementa A* pathfinding en una grid 2D con obstaculos" --json

# Un componente React completo
python run.py --delegate "componente React TypeScript de tabla paginada con sorting, filtering y seleccion multiple" --json

10. Errores Comunes y Soluciones

Truncamiento (respuesta cortada)

Sintoma: validation.truncated: true, respuesta incompleta Causa: deepseek-chat tiene limite de 8K output (4K default). deepseek-reasoner soporta hasta 64K output (incluye CoT). Soluciones:

1. Usar --template para que solo responda los TODOs (no repita codigo)
2. Reducir numero de TODOs en el template
3. Usar --quantum (split en 2 sesiones = doble capacidad)
4. Agregar en la tarea: "funciones de maximo 20 lineas, sin comentarios"

Validacion Fallida

Sintoma: success: false, validation.errors tiene mensajes Causa: Auto-validador detecto problemas Soluciones:

1. --max-retries 2 para auto-reintentar con feedback
2. Re-ejecutar con --feedback "errores especificos"
3. --no-validate si la validacion es falso positivo

WASM No Encontrado (modo web)

Sintoma: Error "WASM not found" o "FileNotFoundError" Causa: sha3_wasm_bg.wasm no esta en APPDATA Soluciones:

1. DeepSeek Code lo auto-descarga al conectarse
2. Verificar ruta en config.json wasm_path
3. Re-login: python run.py -> /login

Credenciales Expiradas

Sintoma: Error 401, "Invalid token" Causa: Bearer token o cookies expiraron (tipicamente cada 24-48h) Solucion: Re-login web: python run.py -> /login -> inicia sesion en DeepSeek

Security Hook (desarrollo)

Sintoma: Write tool rechazado con "Setting innerHTML..." Causa: Hook de seguridad en el proyecto detecta patrones peligrosos en archivos Solucion: No escribir la cadena literal "innerHTML" concatenada en archivos. Usar textContent, DOMParser, o document.createElement().

10b. Internationalization (i18n)

DeepSeek Code supports 3 languages: English (default), Spanish, and Japanese.

Language Selection Flow

1. First run: After the ASCII art banner, a language selector appears before login
2. Subsequent runs: Language is loaded from config.json ("lang": "en")
3. Runtime change: Use /lang command in interactive mode to switch

Architecture

• cli/i18n.py: Central module with t(key, **kwargs) function
• 155 translated keys across EN and ES, 36 for JA
• Fallback chain: current_lang → English → raw key
• Japanese: 36 most visible keys translated, rest falls back to English
• Persistence: "lang" field in config.json

Adding Translations

1. Add key-value pairs to _STRINGS["en"] and _STRINGS["es"] in cli/i18n.py
2. Optionally add to _STRINGS["ja"] (fallback to English if missing)
3. Use t("key_name") in CLI code instead of hardcoded strings
4. For formatted strings: t("greeting", name="Alice") with "greeting": "Hello {name}"

11. Estructura del Proyecto DeepSeek Code

<DEEPSEEK_DIR>/
├── run.py                           # Entry point -> cli.main
├── src\
│   ├── cli\
│   │   ├── main.py                  # DeepSeekCodeApp, argparse, modes
│   │   ├── i18n.py                  # Internationalization (en/es/ja), t() function
│   │   ├── oneshot.py               # run_delegate_oneshot(), run_agent_oneshot()
│   │   ├── multi_step.py            # run_multi_step() + multi_step_helpers.py
│   │   ├── quantum_runner.py        # run_quantum() -> D

…(truncated)