AI Coding Agents

en el Desarrollo de Softwarein Software Development

Victor Martin
AI4Devs 2026
01
⏱ 5 min

LLM vs Agente vs HerramientaLLM vs Agent vs Tool

Tres conceptos distintos. Confundirlos es el primer error.Three distinct concepts. Confusing them is the first mistake.

LLM

Predice el siguiente token. No ejecuta, no guarda estado.Predicts the next token. Takes text, returns text. It doesn't execute, doesn't store state, doesn't act.

GPT-4, Claude, Gemini son LLMs.GPT-4, Claude, Gemini are LLMs.

HerramientaTool

Cualquier cosa que el agente puede ejecutar: leer archivo, buscar internet, ejecutar comando, abrir PR, actualizar Jira.Anything the agent can execute: read a file, search the internet, run a terminal command, open a PR, update a Jira ticket.

Agente de IAAI Agent

Un LLM al que le das herramientas y un bucle de decisión. No solo responde: evalúa, decide, ejecuta, observa, vuelve a decidir.An LLM given tools and a decision loop. It doesn't just respond: it evaluates, decides which tool to use, executes, observes the result, and decides again.

CapacidadCapability LLM soloLLM alone AgenteAgent
SugiereSuggests
EjecutaExecutes
Toma decisiones en bucleMakes decisions in a loop
Tiene consecuencias realesHas real consequences
Ejemplo: CopilotExample: Copilot
❌ NO es agente❌ NOT an agent
Autocompletado inline — solo sugiere.Inline autocomplete — only suggests.
✅ SÍ es agente✅ IS an agent
Copilot Chat modificando archivos y ejecutando tests.Copilot Chat modifying files and running tests.
"La diferencia clave: el agente puede ejecutar, no solo sugerir.""The key difference: the agent can execute, not just suggest."
02
⏱ 8 min

Prompting

5 Reglas de Oro + Role Prompting para obtener resultados predecibles y de calidad.5 Golden Rules + Role Prompting for predictable, high-quality results.

1
Da contexto antes de la tareaGive context before the task

Fórmula:Formula: contexto del proyecto → restricciones técnicas → tarea concretaproject context → technical constraints → concrete task

❌ MAL❌ BAD
"Crea un endpoint REST para actualizar usuarios.""Create a REST endpoint to update users."
✅ BIEN✅ GOOD
"Estamos en un proyecto Spring Boot 3 con arquitectura hexagonal. Los use cases están en el paquete application, los adaptadores en infrastructure. Crea el use case UpdateUserUseCase siguiendo el patrón existente en CreateUserUseCase.""We're in a Spring Boot 3 project with hexagonal architecture. Use cases are in the application package, adapters in infrastructure. Create the UpdateUserUseCase following the existing pattern in CreateUserUseCase."
2
Sé específico en las restricciones técnicasBe specific about technical constraints
ejemplo de prompt precisoprecise prompt example
"Crea un componente React con TypeScript.
Usa Tailwind para estilos.
Sin useState — el estado viene por props desde el contexto padre.
Debe ser accesible (aria-label incluido)."
"Create a React component with TypeScript.
Use Tailwind for styles.
No useState — state comes via props from the parent context.
Must be accessible (aria-label included)."
3
Pide el formato de salidaAsk for the output format
"Antes de implementar, muéstrame el plan de clases que vas a crear y espera mi confirmación.""Before implementing, show me the class plan you're going to create and wait for my confirmation." → evita implementaciones de 300 líneas en dirección equivocada→ avoids 300-line implementations going in the wrong direction
4
Itera en pasos pequeñosIterate in small steps
dominiodomain use case adaptadoradapter tests

Cada paso se revisa antes de continuar.Each step is reviewed before continuing.

5
Usa ejemplos negativosUse negative examples
"No uses @Autowired directamente.
No generes @Data de Lombok en entidades de dominio.
No mezcles lógica de negocio en los controladores."
"Don't use @Autowired directly.
Don't generate Lombok's @Data on domain entities.
Don't mix business logic in controllers."

Role Prompting

— La técnica que más cambia el output— The technique that changes output the most

Asigna un rol al agente antes de la tarea. No cambia el tono — cambia el marco de referencia completo. No es lo mismo pedirle que "revise código" que decirle que es un senior engineer especializado en arquitectura hexagonal haciendo code review.Assign a role to the agent before the task. It doesn't just change the tone — it changes the complete frame of reference. Asking it to "review code" is not the same as telling it that it is a senior engineer specialized in hexagonal architecture doing a code review.

CODE REVIEWER

"Eres un senior backend engineer especializado en arquitectura hexagonal. Haz code review estricto. Busca: violaciones de capas, lógica fuera del dominio, tests sin casos de error, dependencias innecesarias.""You are a senior backend engineer specialized in hexagonal architecture. Do a strict code review. Look for: layer violations, business logic outside the domain, tests missing error cases, unnecessary dependencies."

API DESIGNER

"Eres un tech lead revisando el diseño de esta API antes de implementarla. Tu objetivo es encontrar problemas antes de que se escriba código. Analiza contratos, casos de error y consistencia.""You are a tech lead reviewing this API design before implementation. Your goal is to find problems before code is written. Analyze contracts, error cases and consistency."

QA ENGINEER

"Eres un QA engineer. Tu única función es intentar romper este use case. Genera los casos de test que un developer optimista probablemente no escribiría.""You are a QA engineer. Your only job is to try to break this use case. Generate the test cases an optimistic developer would probably not write."

UX DESIGNER

"Eres un UX designer revisando este componente. Verifica: accesibilidad (aria-labels, contraste, focus states), consistencia con el design system, estados de error visibles y comprensibles para el usuario.""You are a UX designer reviewing this component. Check: accessibility (aria-labels, contrast, focus states), consistency with the design system, visible and understandable error states for the user."

PRODUCT MANAGER

"Eres un product manager revisando estos criterios de aceptación. ¿Son verificables? ¿Suficientemente específicos para implementar sin ambigüedad? ¿Cubren los casos de error? ¿Hay dependencias implícitas?""You are a product manager reviewing these acceptance criteria. Are they verifiable? Specific enough to implement without ambiguity? Do they cover error cases? Are there implicit dependencies?"

Puedes encadenar roles sobre el mismo artefacto: primero el reviewer de arquitectura, luego el QA, luego el UX designer — cada uno activa un criterio de evaluación distinto.You can chain roles on the same artifact: first the architecture reviewer, then QA, then the UX designer — each activates a different evaluation criterion.

Ejemplos de prompt completo por perfilFull prompt examples by profile

🔧 Backend

"Siguiendo arquitectura hexagonal con Spring Boot 3, crea el use case ProcessOrderUseCase en application.usecase. Recibe ProcessOrderCommand, valida que el pedido existe a través del puerto OrderRepository, aplica las reglas del agregado Order, y publica el evento OrderProcessed. Inyección por constructor. Sin lógica en el controlador.""Following hexagonal architecture with Spring Boot 3, create the ProcessOrderUseCase use case in application.usecase. Receives ProcessOrderCommand, validates the order exists through the OrderRepository port, applies the Order aggregate rules, and publishes the OrderProcessed event. Constructor injection. No business logic in the controller."

⚛ Frontend

"Crea un componente React en TypeScript para mostrar una tarjeta de producto. Sin useState propio — recibe product: ProductDTO como prop. Usa Tailwind. Accesible con aria-labels. Sin any. Named export.""Create a React component in TypeScript to display a product card. No own useState — receives product: ProductDTO as prop. Use Tailwind. Accessible with aria-labels. No any. Named export."

🎨 Diseño🎨 Design

"Tengo este componente de formulario. Actúa como UX designer: identifica problemas de accesibilidad, verifica que los estados de error son claros para el usuario, y comprueba que los espaciados y jerarquías visuales son consistentes con el design system.""I have this form component. Act as a UX designer: identify accessibility issues, verify that error states are clear to the user, and check that spacing and visual hierarchies are consistent with the design system."

📋 Product

"Divide esta épica en tareas técnicas de máximo 2 días. Para cada tarea: criterios de aceptación verificables, dependencias entre tareas y estimación en puntos. No mezcles frontend y backend en la misma tarea. Señala si algún criterio es ambiguo o no implementable.""Break this epic into technical tasks of maximum 2 days each. For each task: verifiable acceptance criteria, dependencies between tasks and story point estimate. Don't mix frontend and backend in the same task. Flag any criteria that are ambiguous or not implementable."

03
⏱ 10 min

Archivos de ContextoContext Files

Define tu arquitectura o el agente inventará la suya.Define your architecture or the agent will invent its own.

"Un archivo bien escrito vale por 100 prompts repetidos. Si no defines tu arquitectura, el agente inventará la suya.""A well-written file is worth 100 repeated prompts. If you don't define your architecture, the agent will invent its own."
my-service/
│
│  ── 📋 Conocimiento central (fuente única de verdad) ──
│
├── AGENTS.md                              ← manifiesto maestro (índice + persona + reglas)
├── docs/
│   ├── ai/
│   │   ├── instructions/                  ← reglas atómicas por responsabilidad
│   │   │   ├── backend.md
│   │   │   └── testing.md
│   │   ├── skills/                        ← workflows reutilizables (SKILL.md)
│   │   │   └── create-pr/
│   │   │       ├── SKILL.md
│   │   │       └── prepare-pr-readiness.sh
│   │   ├── personas/                      ← roles especializados
│   │   │   └── pr-reviewer.agent.md
│   │   └── prompts/                       ← templates reutilizables
│   │       └── generate-tests.prompt.md
│   └── context/
│       ├── DOMAIN.md                      ← glosario de dominio
│       └── USE-CASES.md                   ← casos de uso
│
│  ── 🔌 Entry points (thin proxies → AGENTS.md) ──
│
├── .github/copilot-instructions.md        ← Copilot: "lee AGENTS.md"
├── CLAUDE.md                              ← Claude Code: @AGENTS.md (import)
├── GEMINI.md                              ← Gemini CLI: @AGENTS.md (import)
│
│  ── 🔒 Permisos y config tool-specific ──
│
├── .claude/settings.json                  ← allow / deny / ask
├── .gemini/settings.json                  ← sandbox + excludeTools
├── .codex/config.toml                     ← sandbox_mode + approval
│
│  ── 🔗 Discovery nativo de skills (symlinks → docs/ai/skills/) ──
│
├── .agents/skills/create-pr → ../../docs/ai/skills/create-pr  ← Copilot + Gemini + Codex
└── .claude/skills/create-pr → ../../docs/ai/skills/create-pr  ← Claude Code
my-service/
│
│  ── 📋 Central knowledge (single source of truth) ──
│
├── AGENTS.md                              ← master manifest (index + persona + rules)
├── docs/
│   ├── ai/
│   │   ├── instructions/                  ← atomic rules per concern
│   │   │   ├── backend.md
│   │   │   └── testing.md
│   │   ├── skills/                        ← reusable workflows (SKILL.md)
│   │   │   └── create-pr/
│   │   │       ├── SKILL.md
│   │   │       └── prepare-pr-readiness.sh
│   │   ├── personas/                      ← specialized roles
│   │   │   └── pr-reviewer.agent.md
│   │   └── prompts/                       ← reusable templates
│   │       └── generate-tests.prompt.md
│   └── context/
│       ├── DOMAIN.md                      ← domain glossary
│       └── USE-CASES.md                   ← use cases
│
│  ── 🔌 Entry points (thin proxies → AGENTS.md) ──
│
├── .github/copilot-instructions.md        ← Copilot: "read AGENTS.md"
├── CLAUDE.md                              ← Claude Code: @AGENTS.md (import)
├── GEMINI.md                              ← Gemini CLI: @AGENTS.md (import)
│
│  ── 🔒 Permissions and tool-specific config ──
│
├── .claude/settings.json                  ← allow / deny / ask
├── .gemini/settings.json                  ← sandbox + excludeTools
├── .codex/config.toml                     ← sandbox_mode + approval
│
│  ── 🔗 Native skill discovery (symlinks → docs/ai/skills/) ──
│
├── .agents/skills/create-pr → ../../docs/ai/skills/create-pr  ← Copilot + Gemini + Codex
└── .claude/skills/create-pr → ../../docs/ai/skills/create-pr  ← Claude Code
AGENTS.md — manifiesto maestro (todos los agentes)AGENTS.md — master manifest (all agents)
# Agent Manifest — My Service

## Core Persona
- Senior Software Engineer, Hexagonal Architecture, Spring Boot.
- Todo código, comentarios y documentación en inglés.

## Stack: Java 21, Spring Boot 3.3, PostgreSQL, Kafka, Redis

## Knowledge Base (fuente única de verdad)
- Backend: [docs/ai/instructions/backend.md](docs/ai/instructions/backend.md)
- Testing: [docs/ai/instructions/testing.md](docs/ai/instructions/testing.md)
- Dominio: [docs/context/DOMAIN.md](docs/context/DOMAIN.md)

## Skills
- Crear PR: [docs/ai/skills/create-pr/SKILL.md](docs/ai/skills/create-pr/SKILL.md)

## Personas
- PR Reviewer: [docs/ai/personas/pr-reviewer.agent.md](docs/ai/personas/pr-reviewer.agent.md)

## Lo que NUNCA debes hacer
- No añadas dependencias sin pedirlo
- No hagas commits automáticos
- No mezcles responsabilidades entre capas
# Agent Manifest — My Service

## Core Persona
- Senior Software Engineer, Hexagonal Architecture, Spring Boot.
- All code, comments and documentation in English.

## Stack: Java 21, Spring Boot 3.3, PostgreSQL, Kafka, Redis

## Knowledge Base (single source of truth)
- Backend: [docs/ai/instructions/backend.md](docs/ai/instructions/backend.md)
- Testing: [docs/ai/instructions/testing.md](docs/ai/instructions/testing.md)
- Domain: [docs/context/DOMAIN.md](docs/context/DOMAIN.md)

## Skills
- Create PR: [docs/ai/skills/create-pr/SKILL.md](docs/ai/skills/create-pr/SKILL.md)

## Personas
- PR Reviewer: [docs/ai/personas/pr-reviewer.agent.md](docs/ai/personas/pr-reviewer.agent.md)

## What you must NEVER do
- Do not add dependencies without being asked
- Do not make automatic commits
- Do not mix responsibilities between layers
docs/context/DOMAIN.md — el más infravaloradodocs/context/DOMAIN.md — the most underrated
# Glosario de Dominio
## Entidades core
- **Artículo**: SKU físico con stock y precio. Tiene talla y color.
- **Producto**: Agrupación lógica de artículos.

## Reglas de negocio invariantes
- Un artículo no puede tener stock negativo.
- Un pedido solo se puede cancelar en estado PENDING o CONFIRMED.
# Domain Glossary
## Core entities
- **Article**: Physical SKU with stock and price. Has size and color.
- **Product**: Logical grouping of articles.

## Invariant business rules
- An article cannot have negative stock.
- An order can only be cancelled in PENDING or CONFIRMED status.
docs/ai/skills/create-pr/SKILL.md — formato portabledocs/ai/skills/create-pr/SKILL.md — portable format
---
name: create-pr
description: Crea un PR con formato convencional
context: fork
agent: code-reviewer        # invoca al subagente tras crear el PR
---

# Crear Pull Request

## Pasos
1. Ejecuta `git diff main...HEAD` para entender los cambios
2. Analiza y categoriza (feature, fix, refactor)
3. Genera título siguiendo conventional commits
4. Genera cuerpo con resumen, testing, breaking changes
5. Crea el PR con `gh pr create`
---
name: create-pr
description: Creates a PR with conventional format
context: fork
agent: code-reviewer        # invokes the subagent after creating the PR
---

# Create Pull Request

## Steps
1. Run `git diff main...HEAD` to understand all changes
2. Analyze and categorize (feature, fix, refactor)
3. Generate title following conventional commits
4. Generate body with summary, testing, breaking changes
5. Create the PR using `gh pr create`
Permisos por agente — dónde se configuranPermissions per agent — where they live
Copilot Claude Code Gemini CLI Codex CLI
ArchivoFile copilot-setup-steps.yml
+ org firewall
.claude/settings.json .gemini/settings.json .codex/config.toml
ModeloModel Firewall de red + permisos de orgNetwork firewall + org permissions allow / deny / ask sandbox + excludeTools sandbox_mode + approval
Nivel globalGlobal level Org/Enterprise settings ~/.claude/settings.json ~/.gemini/settings.json ~/.codex/config.toml
Ejemplo: .claude/settings.json — allowlist investigada para vibe coding seguroExample: .claude/settings.json — researched allowlist for secure vibe coding
{
  "permissions": {
    "allow": [
      "Read(**)", "Write(src/**)",
      // Shell solo-lectura
      "Bash(find:*)", "Bash(grep:*)", "Bash(cat:*)", "Bash(ls:*)",
      "Bash(tree:*)", "Bash(head:*)", "Bash(tail:*)", "Bash(wc:*)",
      "Bash(diff:*)", "Bash(jq:*)", "Bash(yq:*)",
      // Build tools
      "Bash(mvn test*)", "Bash(./mvnw verify*)",
      "Bash(./gradlew test*)", "Bash(npm:*)", "Bash(cargo test:*)",
      // Git solo-lectura
      "Bash(git status:*)", "Bash(git log:*)", "Bash(git diff:*)",
      // Git escritura controlada
      "Bash(git add:*)", "Bash(git pull:*)", "Bash(git stash:*)",
      // GitHub CLI solo-lectura
      "Bash(gh pr view:*)", "Bash(gh issue view:*)"
    ],
    "deny": [
      "Bash(sudo:*)", "Bash(rm -rf .git:*)", "Bash(rm .env:*)",
      "Bash(bash -c:*)", "Bash(eval:*)", "Bash(node -e:*)",
      "Bash(nc:*)", "Bash(curl * | bash:*)",
      "Bash(git push --force:*)", "Bash(git reset --hard:*)",
      "Bash(mvn *deploy*:*)", "Bash(docker push:*)",
      "Read(**/.env)", "Read(~/.ssh/**)", "Read(~/.aws/**)"
    ],
    "ask": [
      "Bash(curl:*)", "Bash(rm:*)",
      "Bash(npm install:*)", "Bash(pip install:*)",
      "Bash(git commit:*)", "Bash(git push:*)",
      "Bash(docker run:*)", "Bash(docker build:*)"
    ]
  }
}
{
  "permissions": {
    "allow": [
      "Read(**)", "Write(src/**)",
      // Shell read-only
      "Bash(find:*)", "Bash(grep:*)", "Bash(cat:*)", "Bash(ls:*)",
      "Bash(tree:*)", "Bash(head:*)", "Bash(tail:*)", "Bash(wc:*)",
      "Bash(diff:*)", "Bash(jq:*)", "Bash(yq:*)",
      // Build tools
      "Bash(mvn test*)", "Bash(./mvnw verify*)",
      "Bash(./gradlew test*)", "Bash(npm:*)", "Bash(cargo test:*)",
      // Git read-only
      "Bash(git status:*)", "Bash(git log:*)", "Bash(git diff:*)",
      // Git controlled write
      "Bash(git add:*)", "Bash(git pull:*)", "Bash(git stash:*)",
      // GitHub CLI read-only
      "Bash(gh pr view:*)", "Bash(gh issue view:*)"
    ],
    "deny": [
      "Bash(sudo:*)", "Bash(rm -rf .git:*)", "Bash(rm .env:*)",
      "Bash(bash -c:*)", "Bash(eval:*)", "Bash(node -e:*)",
      "Bash(nc:*)", "Bash(curl * | bash:*)",
      "Bash(git push --force:*)", "Bash(git reset --hard:*)",
      "Bash(mvn *deploy*:*)", "Bash(docker push:*)",
      "Read(**/.env)", "Read(~/.ssh/**)", "Read(~/.aws/**)"
    ],
    "ask": [
      "Bash(curl:*)", "Bash(rm:*)",
      "Bash(npm install:*)", "Bash(pip install:*)",
      "Bash(git commit:*)", "Bash(git push:*)",
      "Bash(docker run:*)", "Bash(docker build:*)"
    ]
  }
}

📁 Allowlist completa en examples/templates/.claude/settings.json📁 Full allowlist in examples/templates/.claude/settings.json

04
⏱ 7 min

Mapa de Archivos por AgenteAgent File Map

Cada agente tiene sus archivos de configuración. AGENTS.md los unifica.Each agent has its configuration files. AGENTS.md unifies them.

ConceptoConcept GitHub Copilot Claude Code Gemini CLI Codex CLI
Contexto principalMain context .github/copilot-instructions.md CLAUDE.md GEMINI.md AGENTS.md
Contexto por directorioDirectory context *.instructions.md CLAUDE.md (subdir) GEMINI.md (subdir) AGENTS.md (subdir)
Permisos/SeguridadPermissions/Security copilot-setup-steps.yml
+ org firewall
.claude/settings.json .gemini/settings.json .codex/config.toml
Skills (canónico)Skills (canonical) docs/ai/skills/*/SKILL.md
Skills (discovery)Skills (discovery) .agents/skills/* .claude/skills/* .agents/skills/* .agents/skills/*
Subagents .github/agents/*.md .claude/agents/*.md experimental experimental
Personas (tool-agnostic) docs/ai/personas/*.agent.md
"Patrón Pointer: AGENTS.md como fuente única de verdad. Los archivos específicos de cada agente (.github/copilot-instructions.md, CLAUDE.md, GEMINI.md) son thin proxies que apuntan al manifiesto central. Cursor también lee AGENTS.md nativamente y usa .cursor/rules/ como entry point propio.""Pointer Pattern: AGENTS.md as single source of truth. Agent-specific files (.github/copilot-instructions.md, CLAUDE.md, GEMINI.md) are thin proxies that point to the central manifest. Cursor also reads AGENTS.md natively and uses .cursor/rules/ as its own entry point."

Cursor — No aparece como columna en esta tabla porque es un IDE (no CLI), pero su file map es análogo: .cursor/rules/*.mdc (contexto principal), .cursor/agents/*.md (subagentes), .cursor/skills/ (skills). Lee AGENTS.md nativamente.Cursor — Not shown as a column here because it's an IDE (not CLI), but its file map is analogous: .cursor/rules/*.mdc (main context), .cursor/agents/*.md (subagents), .cursor/skills/ (skills). Reads AGENTS.md natively.

Primeros 3 pasos para cualquier equipoFirst 3 steps for any team

1. AGENTS.md

Crear AGENTS.md en la raíz con stack, arquitectura y convenciones. Es el manifiesto maestro.Create AGENTS.md at root with stack, architecture and conventions. This is the master manifest.

2. Entry points2. Entry points

Crear thin proxies para tus agentes: .github/copilot-instructions.md, CLAUDE.md, etc. — que apunten a AGENTS.md.Create thin proxies for your agents: .github/copilot-instructions.md, CLAUDE.md, etc. — pointing to AGENTS.md.

3. Contexto3. Context

Añadir docs/context/DOMAIN.md y docs/ai/instructions/ con reglas atómicas por responsabilidad.Add docs/context/DOMAIN.md and docs/ai/instructions/ with atomic rules per concern.

05
⏱ 7 min

MCP

Model Context Protocol — estándar abierto bajo la Linux Foundation (AAIF) para conectar agentes con herramientas externas.Model Context Protocol — open standard under the Linux Foundation (AAIF) for connecting agents with external tools.

USB-C de los agentes — un protocolo común para hablar con cualquier herramientaUSB-C of agents — a common protocol to talk to any tool
"Estándar abierto creado por Anthropic en 2024 y adoptado por toda la industria (OpenAI, Google, Microsoft, JetBrains) para conectar agentes con herramientas externas.""Open standard created by Anthropic in 2024 and adopted by the entire industry (OpenAI, Google, Microsoft, JetBrains) to connect agents with external tools."
mcp-config.json
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {
        "JIRA_HOST": "https://acme.atlassian.net",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_TOKEN": "${JIRA_API_TOKEN}"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "confluence": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-confluence"],
      "env": {
        "CONFLUENCE_HOST": "https://acme.atlassian.net/wiki",
        "CONFLUENCE_TOKEN": "${CONFLUENCE_TOKEN}"
      }
    }
  }
}
Jira

"Lee el ticket PROJ-1234 de Jira y crea la implementación siguiendo los criterios de aceptación." → el agente accede al ticket directamente."Read Jira ticket PROJ-1234 and create the implementation following the acceptance criteria." → the agent accesses the ticket directly.

GitHub

"Revisa el PR #456, identifica los comentarios de review pendientes y aplica los cambios sugeridos.""Review PR #456, identify pending review comments and apply the suggested changes."

Confluence

"Antes de implementar el módulo de pagos, busca en Confluence si hay documentación de la arquitectura existente.""Before implementing the payments module, search Confluence for existing architecture documentation."

Seguridad & EstadoSecurity & State

Los tokens siempre como variables de entorno — nunca hardcodeados.Tokens always as environment variables — never hardcoded.

MCP soportado en VS Code, JetBrains, Xcode, Eclipse. El MCP Registry está en public preview. Gobernanza: AAIF (Linux Foundation) desde dic 2025.MCP supported in VS Code, JetBrains, Xcode, Eclipse. The MCP Registry is in public preview. Governance: AAIF (Linux Foundation) since Dec 2025.

06
⏱ 15 min

Multi-Agente y OrquestaciónMulti-Agent and Orchestration

Subagentes, skills, equipos y patrones de orquestación.Subagents, skills, teams and orchestration patterns.

Nivel 1Level 1
Single Agent
← Empezad aquí← Start here
Un agente, una tarea, revisión humana entre pasos. El 80% del valor está en este nivel.One agent, one task, human review between steps. 80% of the value is at this level.
Nivel 2Level 2
Orchestrator + Specialists
AvanzadoAdvanced
Un agente orquestador recibe el objetivo y delega a agentes especializados.An orchestrator agent receives the objective and delegates to specialized agents.
Nivel 3Level 3
Parallel Agents
Solo senior+Senior+ only
Múltiples agentes en paralelo. Potente pero complejo de coordinar.Multiple agents in parallel. Powerful but complex to coordinate.

A · SubagentesA · Subagents

Instancias especializadas que el agente principal lanza para tareas concretas. Cada herramienta los implementa de forma diferente, pero el concepto es el mismo.Specialized instances launched by the main agent for specific tasks. Each tool implements them differently, but the concept is the same.

Claude Code GitHub Copilot Gemini CLI Cursor
DefiniciónDefinition .claude/agents/*.md .github/agents/*.md Markdown + YAML experimental .cursor/agents/*.md
Built-in Explore, Plan, General-purpose Explore, Task, Code Review Research, Terminal, ParallelResearch, Terminal, Parallel
Custom experimental v2.4+
Ejemplo: subagente custom (.claude/agents/ o .github/agents/)Example: custom subagent (.claude/agents/ or .github/agents/)
---
name: code-reviewer
description: Reviews code for quality and patterns
tools:
  - Read
  - Grep
  - Glob
model: sonnet
---

# Code Reviewer Agent

Review code changes for:
1. Architecture compliance
2. Code quality and duplication
3. Security vulnerabilities
4. Test coverage
DebuggerDebugger

Subagente que investiga errores: lee logs, reproduce el bug, propone fix con test.Subagent that investigates errors: reads logs, reproduces the bug, proposes fix with test.

Docs WriterDocs Writer

Subagente que genera y mantiene documentación técnica sincronizada con el código.Subagent that generates and maintains technical documentation in sync with the code.

Frontmatter válidoValid frontmatter

name · description · tools · model · maxTurns · permissionMode · skills · mcpServers

Hooks (Claude Code)

Eventos de ciclo de vida deterministas en settings.json: PreToolUse · PostToolUse · Stop. Garantizan reglas de seguridad y formateo sin depender del prompt.Deterministic lifecycle events in settings.json: PreToolUse · PostToolUse · Stop. Enforce security rules and formatting without relying on the prompt.

B · Sistema de SkillsB · Skills System

Tareas reutilizables definidas como SKILL.md. Formato abierto y portable — soportado por Claude Code, Copilot, Gemini CLI, Codex CLI y Cursor.Reusable tasks defined as SKILL.md. Open and portable format — supported by Claude Code, Copilot, Gemini CLI, Codex CLI and Cursor.

SKILL.md — formato portableSKILL.md — portable format
---
name: create-pr
description: Creates a PR with conventional format
agent: code-reviewer
---

# Create Pull Request

## Steps
1. Run `git diff main...HEAD`
2. Categorize changes (feature, fix, refactor)
3. Generate conventional commit title
4. Create PR with `gh pr create`
Dónde vivenWhere they live

Canónico:Canonical: docs/ai/skills/name/SKILL.md
Discovery:
  Claude: .claude/skills/name/
  Cursor: .cursor/skills/name/
  Copilot + Gemini + Codex: .agents/skills/name/

Centraliza en docs/ai/skills/ y usa symlinks para discovery nativo.Centralize in docs/ai/skills/ and use symlinks for native discovery.

InvocaciónInvocation

Manual: /create-pr en el chat del agente. Automática: el agente decide basándose en la descripción del frontmatter.Manual: /create-pr in the agent chat. Automatic: the agent decides based on the frontmatter description.

ComposiciónComposition

El campo agent: encadena un subagente tras el skill. Cada skill puede incluir scripts, templates y archivos de soporte en su directorio.The agent: field chains a subagent after the skill. Each skill can include scripts, templates and support files in its directory.

C · Agent TeamsC · Agent Teams experimental

Múltiples instancias del agente ejecutándose en paralelo, coordinadas por un orquestador o de forma independiente. Disponible en Claude Code (experimental) y como patrón general.Multiple agent instances running in parallel, coordinated by an orchestrator or independently. Available in Claude Code (experimental) and as a general pattern.

Subagents Agent Teams
InstanciasInstances Dentro del mismo procesoWithin the same process Procesos independientesIndependent processes
ContextoContext Comparten contexto padreShare parent context Contexto aislado por instanciaIsolated context per instance
CoordinaciónCoordination El agente padre orquestaParent agent orchestrates Git como mecanismo de syncGit as sync mechanism
Caso de usoUse case Tareas especializadas dentro de un flujoSpecialized tasks within a flow Trabajo paralelo en módulos independientesParallel work on independent modules
Investigación paralelaParallel research

3 agentes investigan simultáneamente: uno lee docs, otro analiza código existente, otro busca en internet.3 agents research simultaneously: one reads docs, another analyzes existing code, another searches the web.

Multi-móduloMulti-module

Cada agente trabaja en un módulo distinto del monorepo. Git worktrees evitan conflictos de archivos.Each agent works on a different monorepo module. Git worktrees prevent file conflicts.

Hipótesis competitivasCompeting hypotheses

Dos agentes proponen soluciones diferentes al mismo problema. El humano elige la mejor.Two agents propose different solutions to the same problem. The human picks the best one.

D · Patrones de OrquestaciónD · Orchestration Patterns

Tres patrones comunes para coordinar múltiples agentes.Three common patterns for coordinating multiple agents.

Patrón 1Pattern 1
Orchestrator + Workers
Un agente principal descompone la tarea y delega subtareas a workers especializados. Recoge y consolida los resultados.A main agent breaks down the task and delegates subtasks to specialized workers. Collects and consolidates results.
Ejemplo: implementar feature completaExample: implement complete feature
Patrón 2Pattern 2
DAG
Grafo dirigido acíclico de tareas con dependencias. Cada nodo se ejecuta cuando sus dependencias terminan.Directed acyclic graph of tasks with dependencies. Each node executes when its dependencies complete.
Ejemplo: pipeline CI con fasesExample: CI pipeline with phases
Patrón 3Pattern 3
Hipótesis CompetitivasCompeting Hypotheses
Múltiples agentes atacan el mismo problema con estrategias distintas. Se comparan resultados y se elige el mejor.Multiple agents attack the same problem with different strategies. Results are compared and the best one is chosen.
Ejemplo: debugging complejoExample: complex debugging

E · Arquitectura de Documentación Multi-HerramientaE · Multi-Tool Documentation Architecture

Una estructura de documentación que funciona con cualquier agente, no atada a una herramienta específica.A documentation structure that works with any agent, not tied to a specific tool.

Cuatro pilaresFour pillars
Instructions

Reglas atómicas por contexto: backend, testing, frontend. Archivo por responsabilidad.Atomic rules per context: backend, testing, frontend. One file per responsibility.

Skills

Tareas reutilizables en formato SKILL.md. Cada agente las lee de .<agent>/skills/ — mismo contenido, diferente ruta.Reusable tasks in SKILL.md format. Each agent reads them from .<agent>/skills/ — same content, different path.

Personas

Perfiles de agente especializados: reviewer, architect, DBA. Definen expertise y criterios.Specialized agent profiles: reviewer, architect, DBA. Define expertise and criteria.

Prompts

Templates reutilizables para operaciones comunes: generar tests, escribir ADR, analizar performance.Reusable templates for common operations: generate tests, write ADR, analyze performance.

Estructura de directorio recomendadaRecommended directory structure
docs/ai/                          ← conocimiento centralizadocentralized knowledge
├── instructions/
│   ├── backend.md
│   └── testing.md
├── skills/
│   └── create-pr/
│       ├── SKILL.md
│       └── prepare-pr-readiness.sh
├── personas/
│   └── pr-reviewer.agent.md
└── prompts/
    └── generate-tests.prompt.md

symlinks para discovery nativo:symlinks for native discovery:
.agents/skills/ → docs/ai/skills/ (Copilot+Gemini+Codex)(Copilot+Gemini+Codex)
.claude/skills/ → docs/ai/skills/ (Claude Code)(Claude Code)
"Tool-agnostic by design — la misma estructura de docs funciona con Claude Code, Copilot, Gemini CLI y cualquier agente futuro.""Tool-agnostic by design — the same docs structure works with Claude Code, Copilot, Gemini CLI and any future agent."

¿Cuándo empezar sesión nueva?When to start a new session

Señales de alertaWarning signals
  • ⏱ La sesión lleva más de 60 minutos y el agente pierde precisión⏱ The session has lasted more than 60 minutes and the agent is losing precision
  • ⚠ Aparece el aviso de "context window approaching limit"⚠ The "context window approaching limit" warning appears
  • 🔄 El agente toma decisiones contradictorias con las anteriores🔄 The agent makes decisions that contradict previous ones
  • 🔀 Habéis cambiado de tarea completamente🔀 You have switched to a completely different task
Buena práctica — resumen de sesiónBest practice — session summary
## Estado actual — [fecha]
- Implementado: UpdateUserUseCase
  con puerto UserRepository
- Tests pasando: UpdateUserUseCaseTest
- Pendiente: Adaptador HTTP en UserController
- Próximo paso: implementar PUT /users/{id}
## Current status — [date]
- Implemented: UpdateUserUseCase
  with port UserRepository
- Tests passing: UpdateUserUseCaseTest
- Pending: HTTP Adapter in UserController
- Next step: implement PUT /users/{id}
07
⏱ 8 min

Workflow: Del Ticket al PRWorkflow: From Ticket to PR

5 fases que convierten un ticket en un PR revisable y mergeable.5 phases that turn a ticket into a reviewable and mergeable PR.

Fase 1 — Ticket bien escritoPhase 1 — Well-written ticket

PROJ-1234
PROJ-1234: Implementar endpoint para
actualizar datos de usuario

Criterios de aceptación:
- [ ] PUT /api/v1/users/{id} acepta { email, name }
- [ ] Valida que el email tiene formato válido
- [ ] Retorna 404 si el usuario no existe
- [ ] Retorna 409 si el email ya está en uso
- [ ] Emite evento UserUpdated en Kafka

Restricciones técnicas:
- Arquitectura hexagonal — lógica en el dominio
- El evento Kafka debe incluir:
  userId, oldEmail, newEmail, timestamp
PROJ-1234: Implement endpoint to
update user data

Acceptance criteria:
- [ ] PUT /api/v1/users/{id} accepts { email, name }
- [ ] Validates email format
- [ ] Returns 404 if user does not exist
- [ ] Returns 409 if email is already in use
- [ ] Emits UserUpdated event in Kafka

Technical constraints:
- Hexagonal architecture — logic in the domain
- The Kafka event must include:
  userId, oldEmail, newEmail, timestamp

Fase 2 — Plan primeroPhase 2 — Plan first

claude — plan mode
$ |

→ Espera confirmación antes de implementar→ Wait for confirmation before implementing

Fase 3 — Build iterativoPhase 3 — Iterative build

El agente ejecuta los tests en cada paso. Si fallan, los corrige solo. Intervención solo si el fallo es conceptual.The agent runs tests at each step. If they fail, it fixes them on its own. Intervention only if the failure is conceptual.

dominiodomain → tests use case → tests adaptadoradapter → tests integraciónintegration

Fase 4 — Checklist de ReviewPhase 4 — Review Checklist

ArquitecturaArchitecture
Tests
ConvencionesConventions
SeguridadSecurity

Fase 5 — Métricas de la IndustriaPhase 5 — Industry Metrics

0
% más volumen de PRs individuales con IA
(métricas org. planas sin proceso)
% more individual PR volume with AI
(org-level metrics flat without process)
DORA 2025
0
% tiempo en escribir tests
(antes: 40%)
% time writing tests
(before: 40%)
Referencia internaInternal reference
0
% rechazo en PRs pequeños
(vs 67% en PRs grandes)
% rejection rate for small PRs
(vs 67% for large PRs)
LinearB 2026
0
% más rápido en tareas de código% faster in coding tasks
McKinsey 2023

Tesis central DORA 2025: "La IA es un amplificador, no una solución." Sin prácticas base, la productividad individual no se traduce en mejora organizacional.DORA 2025 central thesis: "AI is an amplifier, not a solution." Without foundational practices, individual productivity does not translate to organizational improvement.

08
⏱ 5 min

ComparativaComparison

GitHub Copilot · Claude Code · Gemini CLI · Codex CLI · Cursor

CapacidadFeature GitHub Copilot Claude Code Gemini CLI Codex CLI Cursor
Integración nativa en IDENative IDE integration ExcelenteExcellent ❌ Terminal ❌ Terminal ❌ Terminal Nativo (VS Code fork)Native (VS Code fork)
Inline completion InstantáneoInstant ✅ Cursor Tab
Contexto máximoMax context ~128K (64K–1M) 200K tokens 1M tokens 400K tokens ~200K (Max Mode: 1M)
Ejecución autónomaAutonomous execution ✅ Agent Mode (GA) CompletaFull CompletaFull CompletaFull CompletaFull
MCP nativoNative MCP ✅ GA (tools)
Agente cloud / asyncCloud / async agent ✅ Coding Agent (GA) ✅ Cloud Agents
Skills ✅ SKILL.md ✅ SKILL.md ✅ SKILL.md ✅ SKILL.md ✅ SKILL.md
"Las cinco herramientas ofrecen ejecución autónoma. Copilot y Cursor ganan en integración IDE y autocompletado. Claude Code / Gemini CLI / Codex ofrecen contexto largo y control total desde terminal. No son opciones exclusivas: IDE para el día a día, CLI para tareas largas.""All five tools offer autonomous execution. Copilot and Cursor win in IDE integration and autocomplete. Claude Code / Gemini CLI / Codex offer long context and full control from terminal. They are not exclusive options: IDE for daily work, CLI for long tasks."

5 tips aplicables esta semana (Copilot y cualquier agente)5 tips you can apply this week (Copilot and any agent)

01 Crear .github/copilot-instructions.md con el contexto de arquitectura.Create .github/copilot-instructions.md with your architecture context.
02 Crear AGENTS.md para portabilidad.Create AGENTS.md for portability.
03 Configurar MCP para Jira y GitHub.Configure MCP for Jira and GitHub.
04 Añadir en las instrucciones: "Nunca generes comandos git commit o git push — espera confirmación."Add to the instructions: "Never generate git commit or git push commands — wait for confirmation."
05 Crear archivos .instructions.md por tipo de tarea (tests, endpoints, refactorizaciones).Create .instructions.md files by task type (tests, endpoints, refactors).
09
⏱ 5 min

AntipatronesAnti-patterns

El 90% de adopción con malos resultados no viene de que la IA sea mala. Viene de cómo se usa.90% of poor adoption results don't come from the AI being bad. They come from how it's used.

"Faros AI 2025: +9% bugs, +91% tiempo en review, +154% tamaño de PR. El problema no es la IA. Es la ausencia de proceso.""Faros AI 2025: +9% bugs, +91% review time, +154% PR size. The problem is not the AI. It's the absence of process."
AP1
Vibe Coding
el más peligrosothe most dangerous

Aceptar el código del agente sin leerlo. Compilar no es correcto. Compilar no es arquitecturalmente sano.Accepting the agent's code without reading it. Compiling is not the same as correct. Compiling is not architecturally sound.

Regla: Si no podéis explicar lo que hace el código, no está listo para mergear.Rule: If you can't explain what the code does, it's not ready to merge.
AP2
Context Poisoning

Sesiones largas donde el agente acumula errores y empieza a replicar patrones incorrectos ya corregidos.Long sessions where the agent accumulates errors and starts replicating already-corrected incorrect patterns.

Regla: Sesiones cortas y enfocadas. Nueva sesión = contexto limpio.Rule: Short and focused sessions. New session = clean context.
AP3
Over-engineering

El agente añade factories, builders, decorators que nadie pidió. Los LLMs tienden a "mejorar" el código añadiendo capas de abstracción innecesarias.The agent adds factories, builders, decorators that nobody asked for. LLMs tend to "improve" code by adding unnecessary abstraction layers.

## Principio YAGNI
No añadas abstracciones ni patrones de diseño
sin pedirlos explícitamente. Si necesitas un
patrón, explica por qué antes de implementarlo.
## YAGNI Principle
Do not add abstractions or design patterns
without being explicitly asked. If you need a
pattern, explain why before implementing it.
AP4
Delegación sin comprensiónDelegation without understanding

Pedir al agente que implemente algo que no sabéis revisar. Si hay un bug en producción no sabéis por dónde empezar.Asking the agent to implement something you can't review. If there's a production bug you don't know where to start.

Regla: Nunca delegues en el agente un área técnica en la que no puedas revisar el resultado.Rule: Never delegate to the agent a technical area where you can't review the result.
AP5
PRs gigantesGiant PRs

Los PRs generados por IA tienen de media un 154% más de líneas que los manuales (Faros AI 2025). Tasa de rechazo: 67% en PRs grandes vs 15% en PRs pequeños (LinearB 2026).AI-generated PRs have on average 154% more lines than manual ones (Faros AI 2025). Rejection rate: 67% for large PRs vs 15% for small PRs (LinearB 2026).

Regla: Iterar por fases produce PRs pequeños que se mergean.Rule: Iterating in phases produces small PRs that get merged.
AP6
Código sin testsCode without tests

Sin tests, cada iteración puede romper la anterior sin que os enteréis hasta producción.Without tests, each iteration can break the previous one without you noticing until production.

Regla: No cerréis un ticket sin tests que fallen antes de la implementación y pasen después.Rule: Don't close a ticket without tests that fail before implementation and pass after.
10
⏱ 15 min

Q&A

Las 8 preguntas que siempre surgen.Questions and answers

¿El agente puede romper el código de producción?Can the agent break production code?

Si le das permisos para actuar en producción, sí. Los agentes deben trabajar siempre en rama feature, con tests, y con revisión humana obligatoria antes de cualquier merge.If you give it permissions to act in production, yes. Agents should always work on a feature branch, with tests, and with mandatory human review before any merge.

El fichero .claude/settings.json permite restringir exactamente qué puede ejecutar el agente. Nunca le des acceso al entorno de producción.The .claude/settings.json file allows you to restrict exactly what the agent can execute. Never give it access to the production environment.

¿Copilot aprende de mi código privado?Does Copilot learn from my private code?

En los planes Business y Enterprise de GitHub Copilot, el código de tu organización no se usa para entrenar los modelos. Verifica siempre la política de tu empresa antes de usar cualquier herramienta de IA con código propietario o datos sensibles.In GitHub Copilot's Business and Enterprise plans, your organization's code is not used to train the models. Always verify your company's policy before using any AI tool with proprietary code or sensitive data.

¿Cuánto tiempo ahorra realmente?How much time does it really save?

McKinsey 2023 (n=40): un 25-45% más rápido en tareas de código. El estudio de GitHub (2023, n=95, peer-reviewed) midió un 55% más rápido en tareas controladas.McKinsey 2023 (n=40): 25-45% faster on coding tasks. The GitHub study (2023, n=95, peer-reviewed) measured 55% faster on controlled tasks.

Sin embargo, el METR Study (2025) encontró que developers experimentados eran un 19% más lentos con herramientas de IA mientras creían ser un 20% más rápidos.However, the METR Study (2025) found that experienced developers were 19% slower with AI tools while believing they were 20% faster.

El ROI real depende de cuánto se invierte en contexto, prompting y revisión de calidad.The real ROI depends on how much is invested in context, prompting and quality review.

¿El agente puede escribir los ADRs?Can the agent write ADRs?

Sí. Puedes pedirle que documente las decisiones arquitectónicas que ha tomado durante la implementación. El Tech Lead revisa y aprueba antes de commitear.Yes. You can ask it to document the architectural decisions it made during implementation. The Tech Lead reviews and approves before committing.

También puedes pedirle que actualice el DOMAIN.md cuando aparecen nuevos conceptos de negocio.You can also ask it to update DOMAIN.md when new business concepts appear.

¿Qué pasa con el código legacy sin tests?What about legacy code without tests?

Primero pídele al agente que genere tests de caracterización que describan el comportamiento actual (aunque sea incorrecto). Una vez tienes cobertura, el agente puede refactorizar con seguridad.First ask the agent to generate characterization tests that describe the current behavior (even if incorrect). Once you have coverage, the agent can refactor safely.

Es una de las tareas donde los agentes aportan más valor en proyectos maduros.It's one of the tasks where agents add the most value in mature projects.

¿Debería usar Claude Code en lugar de Copilot?Should I use Claude Code instead of Copilot?

Depende de la política de tu empresa. Copilot tiene mejor integración con el ecosistema GitHub. Claude Code es técnicamente más potente para tareas complejas y refactors multi-fichero. Cursor combina IDE nativo (fork de VS Code) con agente autónomo y autocompletado — es una tercera vía para quienes quieren lo mejor de ambos mundos. Windsurf, otro IDE con agente, fue adquirido por Cognition (Devin) en 2025.It depends on your company's policy. Copilot has better integration with the GitHub ecosystem. Claude Code is technically more powerful for complex tasks and multi-file refactors. Cursor combines a native IDE (VS Code fork) with an autonomous agent and autocomplete — a third option for those who want the best of both worlds. Windsurf, another IDE with an agent, was acquired by Cognition (Devin) in 2025.

Lo más importante con cualquiera de ellos: configurar bien los archivos de contexto y aprender a escribir prompts precisos.The most important thing with any of them: properly configure the context files and learn to write precise prompts.

¿Qué es AGENTS.md y por qué importa?What is AGENTS.md and why does it matter?

Es un estándar AAIF presente en más de 60K repositorios para definir las reglas de comportamiento del agente. GitHub Copilot, Claude Code, Cursor y otros agentes lo leen nativamente.It's an AAIF standard present in 60K+ repositories for defining agent behavior rules. GitHub Copilot, Claude Code, Cursor and other agents read it natively.

A diferencia de copilot-instructions.md (que define convenciones de código), AGENTS.md define qué puede y qué no puede hacer el agente: qué comandos puede ejecutar, qué ficheros puede modificar, cuál es el flujo de trabajo esperado.Unlike copilot-instructions.md (which defines code conventions), AGENTS.md defines what the agent can and cannot do: what commands it can run, what files it can modify, what the expected workflow is.

¿Cómo evito que el agente genere código que no entiendo?How do I avoid the agent generating code I don't understand?

Tres técnicas:Three techniques:

(1) Pídele que explique cada decisión antes de implementarla.Ask it to explain each decision before implementing it.

(2) Itera en pasos muy pequeños, revisando después de cada uno.Iterate in very small steps, reviewing after each one.

(3) Si el agente propone algo que no reconoces, pídele alternativas más simples antes de aceptar.If the agent proposes something you don't recognize, ask for simpler alternatives before accepting.

La regla de oro: si no puedes revisarlo, no lo mergeas.The golden rule: if you can't review it, you don't merge it.

Para continuarWhat's next

HERRAMIENTASTOOLS
GitHub Copilot docs.github.com/copilot
Claude Code docs.anthropic.com/claude-code
Gemini CLI github.com/google-gemini/gemini-cli
MCP Spec & ServidoresMCP Spec & Servers modelcontextprotocol.io
Cursor cursor.com/docs
ESTUDIOS & REPORTESSTUDIES & REPORTS
Faros AI Productivity Paradox 2025 faros.ai
Google DORA Report 2025 dora.dev
METR Study 2025 metr.org/blog
LinearB Benchmarks 2026 linearb.io/resources
McKinsey Developer Productivity 2023 mckinsey.com/capabilities/mckinsey-digital
GraciasThank you
Victor Martin
Java/Kotlin Spring Boot Hexagonal Arch DDD TDD