AI Coding Agents
en el Desarrollo de Softwarein Software Development
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.
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.
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.
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 | ❌ | ✅ |
Prompting
5 Reglas de Oro + Role Prompting para obtener resultados predecibles y de calidad.5 Golden Rules + Role Prompting for predictable, high-quality results.
Fórmula:Formula: contexto del proyecto → restricciones técnicas → tarea concretaproject context → technical constraints → concrete task
"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)."
Cada paso se revisa antes de continuar.Each step is reviewed before continuing.
"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 mostAsigna 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.
"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."
"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."
"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."
"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."
"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?"
Ejemplos de prompt completo por perfilFull prompt examples by profile
"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."
"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."
"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."
"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."
Archivos de ContextoContext Files
Define tu arquitectura o el agente inventará la suya.Define your architecture or 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
# 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
# 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.
---
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`
| 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 |
{
"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
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 |
|||
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
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.
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.
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.
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.
{
"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}"
}
}
}
}
"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.
"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."
"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."
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.
Multi-Agente y OrquestaciónMulti-Agent and Orchestration
Subagentes, skills, equipos y patrones de orquestación.Subagents, skills, teams and orchestration patterns.
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+ |
---
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
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.
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.
name · description · tools · model · maxTurns · permissionMode · skills · mcpServers
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.
---
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`
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.
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.
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 |
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.
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.
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.
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.
Reglas atómicas por contexto: backend, testing, frontend. Archivo por responsabilidad.Atomic rules per context: backend, testing, frontend. One file per responsibility.
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.
Perfiles de agente especializados: reviewer, architect, DBA. Definen expertise y criterios.Specialized agent profiles: reviewer, architect, DBA. Define expertise and criteria.
Templates reutilizables para operaciones comunes: generar tests, escribir ADR, analizar performance.Reusable templates for common operations: generate tests, write ADR, analyze performance.
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)
¿Cuándo empezar sesión nueva?When to start a new session
- ⏱ 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
## 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}
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: 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
→ 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.
Fase 4 — Checklist de ReviewPhase 4 — Review Checklist
Fase 5 — Métricas de la IndustriaPhase 5 — Industry Metrics
(métricas org. planas sin proceso)% more individual PR volume with AI
(org-level metrics flat without process)
(antes: 40%)% time writing tests
(before: 40%)
(vs 67% en PRs grandes)% rejection rate for small PRs
(vs 67% for large PRs)
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.
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 |
5 tips aplicables esta semana (Copilot y cualquier agente)5 tips you can apply this week (Copilot and any agent)
.github/copilot-instructions.md con el contexto de arquitectura.Create .github/copilot-instructions.md with your architecture context.
AGENTS.md para portabilidad.Create AGENTS.md for portability.
.instructions.md por tipo de tarea (tests, endpoints, refactorizaciones).Create .instructions.md files by task type (tests, endpoints, refactors).
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.
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.
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.
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.
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.
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).
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.
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
docs.github.com/copilot
docs.anthropic.com/claude-code
github.com/google-gemini/gemini-cli
modelcontextprotocol.io
cursor.com/docs
faros.ai
dora.dev
metr.org/blog
linearb.io/resources
mckinsey.com/capabilities/mckinsey-digital