====== Conceptos básicos ====== Lo mínimo para no perderse en el resto del curso: qué es un agente, qué ve el modelo mientras trabaja y qué piezas se le añaden. Cada pieza tiene después su tema; aquí va solo lo justo. ---- ===== 1. El modelo ===== El modelo (LLM) es quien escribe: recibe texto y genera texto, **token a token**. Un token es un trozo de palabra, unos 4 caracteres. Todo se mide en tokens: lo que cabe, lo que se paga y lo que se gasta del plan. Tres cosas del modelo que condicionan todo lo demás: * **No tiene memoria**: cada petición empieza de cero. Lo que «recuerda» de la conversación es porque se le vuelve a mandar entera ([[#el_contexto|el contexto]]). * **No es determinista**: la misma petición dos veces da dos códigos distintos. Por eso las instrucciones se fijan en ficheros y el resultado se comprueba con tests, no a ojo. * **Su conocimiento tiene fecha**: no sabe nada de tu proyecto ni conoce la última versión de una librería. Lo que no sepa se lo tiene que dar el contexto; si no, se lo inventa con toda seguridad. ---- ===== 2. El agente ===== Un agente es un modelo metido en un **bucle con herramientas**: decide un paso, lo hace con una herramienta, mira el resultado y vuelve a decidir, hasta terminar. Un chat te da texto; el agente **actúa y ve las consecuencias**: si el test falla, lee el error y corrige el código. start :petición; repeat :decidir el paso siguiente; :usar una herramienta; :ver el resultado; backward:seguir; repeat while (¿terminado?) is (no) not (sí) :responder; stop * **Herramientas**: lo que el agente hace además de escribir: leer y editar ficheros, buscar en el proyecto, lanzar órdenes (''./mvnw test'', ''git diff''). * **El programa**: [[cursos:sdd:03-opencode|OpenCode]] o [[cursos:sdd:03-claude-code|Claude Code]] montan el bucle y ponen las herramientas; el modelo es una pieza que se cambia. Es el //harnés// de la [[cursos:sdd:04-ingenieria#ingenieria_de_harneses|ingeniería de harneses]]. * **Subagente**: un agente que lanza el principal para un trozo del trabajo, con **su propia ventana de contexto**. Lee veinte ficheros en la suya y al principal solo le devuelve el resumen. Más en [[cursos:sdd:07-agentes|Agentes]]. ---- ===== 3. El contexto ===== El contexto es **todo lo que ve el modelo** en una petición. Como no tiene memoria, en cada turno se le manda entero: * El //system prompt// del programa, con la descripción de sus herramientas. * ''AGENTS.md'' ([[#agentsmd|sección 4]]). * El nombre y la descripción de cada //skill// instalada ([[#skills|sección 5]]). * Las herramientas de cada servidor MCP conectado ([[#mcp|sección 6]]). * La conversación: tus mensajes, sus respuestas y **cada fichero que ha leído y cada salida de orden**. La **ventana de contexto** es lo máximo que cabe: hoy, entre 200.000 tokens y un millón según el modelo. ==== Se llena ==== La conversación crece en cada turno: un fichero leído se queda dentro hasta el final de la sesión. Y cuanto más llena está la ventana, **peor trabaja el modelo**: se le olvida lo que se dijo al principio, mezcla instrucciones y se equivoca más. Pasa mucho antes de llegar al tope. **No pases del 40 % de la ventana.** A partir de ahí la calidad baja aunque quede mucho sitio libre. Cuando te acerques, ''/clear'' y empieza otra vez con lo necesario. * **Cuánto llevas**: en Claude Code, ''/context'', o siempre a la vista con [[cursos:sdd:03-claude-code#claude-hudcontexto_y_limites_siempre_a_la_vista|claude-hud]]; OpenCode lo enseña en la cabecera de la sesión. * **Una tarea, una sesión**: al cambiar de tarea, ''/clear''. Lo de la tarea anterior solo estorba. * **Nada de ''/compact''**: el resumen lo hace el modelo y no sabe qué era lo importante ([[cursos:sdd:03-claude-code#compact|por qué]]). * **Lo que lee mucho, a un subagente**: buscar en todo el proyecto llena su ventana, no la tuya. * **Lo fijo, corto**: ''AGENTS.md'', //skills// y MCP ocupan sitio en todas las sesiones antes de escribir nada. Llenar el contexto también cuesta dinero: cada turno reenvía la conversación entera, así que un turno al final de una sesión larga gasta mucho más que uno al principio. ---- ===== 4. AGENTS.md ===== Un markdown en la raíz del repositorio con las instrucciones fijas del proyecto: lo que le contarías a un compañero nuevo el primer día. **Se carga entero en todas las sesiones**, así que tiene que ser pequeño. Lo leen todos los agentes (Claude Code, OpenCode, Codex, Cursor...). # Pedidos API REST de pedidos. Compilar y probar: `./mvnw verify`. - Los importes son `BigDecimal` con escala 2; nunca `double`. - Antes de crear cualquier clase, lee `.claude/skills/arquitectura/SKILL.md`. Qué entra y qué no: [[cursos:sdd:08-skills#agentsmd|AGENTS.md]]. ---- ===== 5. Skills ===== Una //skill// es una carpeta con un ''SKILL.md'' que le dice al agente **cómo se hace** una tarea concreta en tu equipo: revisar un PR, crear un endpoint, escribir una spec. .claude/skills/revisar-pr ├── SKILL.md <- las instrucciones, con nombre y descripción arriba └── checklist.md <- material de apoyo Del contexto solo ocupa **el nombre y la descripción**; el resto entra cuando la tarea encaja. Por eso se pueden tener muchas sin llenar la ventana. Cómo se escriben: [[cursos:sdd:08-skills|Skills]]. ---- ===== 6. MCP ===== Un servidor MCP (//Model Context Protocol//) le da al agente **herramientas nuevas**: abrir un navegador y ver la página que acaba de maquetar, consultar la documentación actual de una librería, lanzar consultas a la base de datos de desarrollo. Se escribe un servidor y lo usa cualquier agente. * **Cuándo sí**: el agente necesita algo que no está ni en el repositorio ni en sus herramientas. * **Cuándo no**: para leer ficheros, buscar o lanzar órdenes, que ya lo hace solo. Cada servidor conectado **ocupa contexto en todas las sesiones**, se use o no: las descripciones de todas sus herramientas. Conecta solo los que uses. Cuáles se instalan y cómo: [[cursos:sdd:09-mcp|MCP]]. ---- ===== 7. Qué usar para cada problema ===== ^ El problema que tienes ^ Lo que necesitas ^ | «Tengo que repetirle lo mismo en cada sesión» | Una línea en ''AGENTS.md'' | | «Cada vez lo hace distinto» | Una //skill// | | «Se inventa los datos» o «no puede consultarlo» | Un servidor MCP | | «Se llena el contexto en tareas grandes» | Un subagente | | «No sé por dónde empieza» | Ninguna: falta especificación ([[cursos:sdd:10-spec-driven-development|SDD]]) | **Empieza siempre por ''AGENTS.md'' y las //skills//.** Son ficheros de texto y arreglan la mitad de los problemas que la gente intenta resolver montando un agente. MCP cuando de verdad haya que salir fuera. ---- ===== Más información ===== * [[https://youtu.be/KeMRKkhLvEw?si=4WZSRlwM8hRxhdZT|Inteligencia artificial: la verdad sobre el autocompact (y tips)]]: cómo se llena el contexto y qué pasa al compactar. * [[https://research.trychroma.com/context-rot|Context Rot]]: el estudio de Chroma que mide cómo empeoran los modelos al crecer la entrada, aunque la tarea sea igual de fácil. * [[https://agents.md/|AGENTS.md]]: el estándar y la lista de herramientas que lo leen. * [[https://agentskills.io/specification|Agent Skills]]: el estándar de las //skills//. * [[https://modelcontextprotocol.io/|Model Context Protocol]]: la documentación oficial de MCP.