Línea de apertura (opcional, para el feed): En cada sesión nueva, Claude abre el README, escanea el árbol de directorios, busca el pom.xml, encuentra src/main/java... 33 tool calls para orientarse. Con un archivo de 50 líneas en la raíz del proyecto, eso baja a 3. Mismo codebase. Mucho menos tiempo perdido.
Basado en la presentación de Thor Henning Hetland (Totto) · Ægis, The KCP Universe: Everything, and What July Changed (v0.30.3, 29 julio 2026).
El Pilar 1 de esta serie explica cómo construir el CLAUDE.md con el ADN del proyecto: convenciones, anti-patrones, flujo de Git, requisitos de testing. Es el conocimiento del codebase.
Pero hay un problema que el CLAUDE.md no resuelve: la IA tiene que encontrarlo.
En cada sesión nueva con Claude Code, el agente empieza desde cero. No recuerda dónde está el CLAUDE.md. No sabe que el proyecto tiene arquitectura hexagonal con cuatro capas de paquetes. No sabe que los skills están en .claude/skills/. Tiene que descubrirlo leyendo archivos, escaneando directorios y abriendo configuraciones.
En un proyecto Java típico, eso cuesta entre 20 y 33 tool calls antes de que el agente pueda empezar la primera tarea.
El Knowledge Context Protocol (KCP) resuelve exactamente eso.
El problema: relevancia no es autoridad
Antes de ver la solución, vale la pena entender por qué el problema es más profundo de lo que parece.
Un agente leyendo tu codebase no tiene forma de saber qué es verdad. Encuentra un documento de arquitectura de marzo y uno de junio. Nada en ninguno de los dos dice cuál es el actual. Sigue el runbook que fue supersedido en abril. Lee la guía de API interna escrita para una versión que ya no existe. Los lee todos con exactamente la misma confianza, porque un archivo es un archivo.
El Retrieval Augmented Generation (RAG) no resuelve esto. RAG encuentra texto relevante. No tiene concepto de texto autoritativo. Relevancia y autoridad son preguntas distintas, y solo una de ellas tiene una respuesta que se puede verificar.
KCP es la otra respuesta.
Qué es KCP: dos mecanismos, un archivo
Un knowledge.yaml en la raíz del repositorio. La IA lo lee primero, al inicio de cada sesión, y se orienta en 3 tool calls en lugar de 33.
El knowledge.yaml hace dos trabajos distintos:
Mecanismo 1 — Índice de navegación del proyecto: Declara arquitectura, ubicaciones de skills, convenciones, puntos de entrada y paths clave. La IA lo lee una vez al inicio de sesión y conoce la estructura del proyecto sin explorar.
CLAUDE.md es conocimiento. knowledge.yaml es navegación.
Mecanismo 2 — Command manifests: Interceptan el output de CLI antes de que la IA lo procese. git status en un repo grande genera 200+ líneas; el manifest lo filtra a las 12 relevantes. mvn test genera 500+ líneas de INFO y descargas; el manifest devuelve solo los fallos.
Resultado medido: 33% del context window ahorrado por sesión en operaciones rutinarias de desarrollo. 60–80% en operaciones con output especialmente verboso.
Cómo se ve en un proyecto Java Spring Boot
# knowledge.yaml — raíz del repositorio
project:
name: pedidos-api
type: java-spring-boot
architecture: CLAUDE.md#architecture
skills:
global: ~/.claude/skills/common/
project: .claude/skills/
navigator: .claude/skills/navigator.yaml
entry_points:
- src/main/java/com/empresa/pedidos/PedidosApplication.java
- src/main/java/com/empresa/pedidos/api/
conventions:
- CLAUDE.md#conventions
- docs/ADRs/
commands:
maven_test:
filter: failures_only
ignore: ["^\\[INFO\\]", "^\\[WARNING\\]", "Downloading:", "Downloaded:"]
inject: "Verifica si los fallos tienen @Tag de integración — pueden requerir Docker"
git_status:
filter: staged_only
ignore: ["target/", ".mvn/", "*.class", "*.jar"]
inject: "Verifica que no se modificaron archivos de corpus de tests"
maven_compile:
filter: errors_only
ignore: ["^\\[INFO\\]", "^\\[WARNING\\]"]
inject: "Si hay errores de javax.*, revisar migración jakarta — ver CLAUDE.md#antipatrones"
El impacto concreto del filtrado de mvn test:
Los tres artefactos que KCP gobierna
Con la versión v0.29 (julio 2026), el protocolo introdujo tres clases de artefactos que cambian la naturaleza de lo que puede gobernar:
La distinción que más importa para Java devs:
Una unidad de conocimiento (kind: knowledge) es un hecho: el ADR que explica por qué el equipo usa hexagonal, el documento que dice que monto siempre es BigDecimal. Puede tener valid_until y expira solo cuando caduca.
Un skill (kind: skill) es un procedimiento sobre una cosa: cómo migrar un controlador Spring Boot 2 a 3, cómo generar un DTO con record. Tiene action_scope declarado — qué herramientas puede usar — y el agente no puede salirse de ese scope sin que el harness lo bloquee.
Un playbook (kind: playbook, nuevo en v0.29) es un objetivo compuesto: "actualizar Spring Boot de 2.x a 3.x en este módulo". Contiene una secuencia de skills con checkpoints. Al terminar, emite una cadena de decisiones firmada — no un log, sino evidencia criptográfica de que cada paso se ejecutó dentro de lo que estaba autorizado a hacer.
La unidad de confianza: qué dice un entry de knowledge.yaml
# Ejemplo de unidad de skill declarada en knowledge.yaml
- id: jakarta-migration-skill
path: .claude/skills/jakarta-migration.md
kind: skill
intent: "Migración de javax.* a jakarta.* en controladores Spring Boot 3.
Incluye anotaciones OpenAPI 3 y tests MockMvc actualizados."
scope: project
audience: [agent]
triggers: [jakarta, javax, spring-boot-3, migration]
load_eligible: true
action_scope:
tools: ["read_file", "replace_string_in_file"]
valid_until: "2027-01-01"
Cada campo responde una pregunta que el agente de otra forma tendría que adivinar:
intent — ¿para qué sirve esto? No un resumen del texto; una declaración de propósito.
audience: [agent] — ¿es para mí? Un doc de onboarding humano y un runbook de agente son artefactos distintos.
kind: skill — ¿es conocimiento o un procedimiento? Esta línea hace que la unidad sea gobernable como acción.
load_eligible: true — ¿se puede cargar? La elegibilidad es separada de la relevancia.
action_scope — ¿qué puede tocar? Una tool call fuera de read_file y replace_string_in_file es rechazada en el loop, con la razón escrita.
Lo que cambió en julio 2026 (v0.28–v0.30.3)
El protocolo pasó de v0.22 a v0.30.3 en julio con 1.012 commits y 88 releases. Cuatro cambios que importan para quienes lo usan:
Paridad de implementaciones (v0.28) KCP tiene bridges para TypeScript, Java y Python. Hasta julio, "la spec dice X" y "las implementaciones hacen X" eran claims separados. v0.28 los unificó con vectores de conformance compartidos. Una diferencia entre el parser Java y el Python ahora es un test failure, no un descubrimiento en producción seis semanas después.
El plano procedimental — kind: playbook (v0.29) Antes KCP gobernaba hechos. Ahora también puede gobernar objetivos compuestos. Un playbook emite una cadena de decisiones firmada — evidencia que puede presentarse en una auditoría de cumplimiento.
Eligibility grants (v0.30) Un sistema de gobernanza que solo puede decir no es un freno. Los grants permiten que unidades sean elegibles bajo condiciones específicas, con el historial de qué se solicitó y qué se rechazó. La solicitud misma es parte del audit trail.
Parse diagnostics Antes de julio, un campo mal escrito (audiance: en lugar de audience:) se ignoraba silenciosamente. La unidad parseaba limpia y quedaba sin gobierno para siempre. Ahora lo dice.
"El campo mal escrito es el mejor ejemplo del problema central: la diferencia entre algo que está bien y algo que no fue verificado es invisible a menos que construyas la maquinaria para verlo."
Por qué importa para proyectos Java en particular
Los proyectos Java son exactamente el tipo de codebase donde el problema de orientación es más costoso:
Multi-módulo Maven: ls en el root no dice nada. La estructura real está cuatro niveles abajo.
Spring Boot conventions: La convención de paquetes, la separación de capas, los beans esperados — nada de esto es visible sin explorar.
Output verboso de Maven: 500 líneas de INFO por cada mvn test. Sin filtrado, la IA gasta contexto en ruido que tú ya ignoras automáticamente.
Migraciones largas: Una migración Spring Boot 2 → 3 abarca docenas de archivos con el mismo patrón. El playbook KCP puede gobernar cada paso con evidencia firmada.
Cómo empezar: tres pasos
Paso 1 — Instala kcp-commands (10 minutos, resultado inmediato)
Es el único punto de entrada con payoff inmediato sin conocer el protocolo. Envuelve comandos frecuentes (git, mvn) con filtrado token-eficiente. Corre como hook en ~12ms. No necesitas saber qué es KCP para beneficiarte.
Paso 2 — Escribe un knowledge.yaml básico para tu proyecto Java
Seis unidades. Para cada una: intent, audience, y donde aplique valid_until. Luego:
kcp-agent plan "migrar PedidoController a Spring Boot 3" \
--manifest knowledge.yaml \
--trace --json
Leer los 14 gate verdicts explicados por escrito es el momento en que el concepto aterriza.
La conexión con los 6 pilares
KCP no reemplaza al CLAUDE.md del Pilar 1. Lo complementa:
|
CLAUDE.md |
knowledge.yaml |
| Qué es |
Conocimiento del codebase |
Mapa de navegación del codebase |
| Para quién |
La IA lee el contenido |
La IA navega hacia el contenido |
| Qué declara |
Convenciones, anti-patrones, errores comunes |
Arquitectura, paths, skills, entry points |
| Qué gobierna |
Comportamiento esperado |
Qué puede cargar, qué puede tocar |
El Pilar 6 (volante de aprendizaje) actualiza el CLAUDE.md con cada bug. KCP hace que esas actualizaciones sean encontrables y autoritativas, no solo relevantes.
La estructura del flujo de trabajo no es una barrera para el código. Son los rieles que permiten al equipo ir a 300 km/h sin descarrilar.
Los rieles funcionan mejor cuando la IA sabe dónde están desde el primer tool call.
¿Cuántos tool calls hace Claude en tu proyecto Java antes de empezar la primera tarea? Puedes medirlo abriendo una sesión nueva y contando. Ese número es tu baseline de cold-start. ¿Cuánto mejoraría con un knowledge.yaml?
Enjoy!
Joe
