La guía definitiva de Claude Code para desarrollo: carpetas, skills y flujos

Casi todo lo que se escribe sobre Claude Code es una lista de trucos. Este post no. Es un intento de referencia: cómo se usa de verdad en desarrollo de software, qué arquitectura de carpetas es la canónica, qué skills conviene montar, y —lo más importante— qué dice la evidencia cuando dejamos el marketing de lado. Todo lo que afirmo aquí está citado a documentación oficial de Anthropic o a papers, y lo verás en Fuentes al final.

Empecemos por la única idea de la que cuelga todo lo demás:

¿Suena exagerado que la estructura importe más que el modelo? La evidencia va en esa dirección, y de paso incomoda. En un ensayo controlado de METR (2025), desarrolladores open-source experimentados que podían usar IA tardaron un 19 % más en cerrar sus tareas —aunque ellos creían que iban más rápido—. La herramienta no era mágica por sí sola. Lo que separa el 19 % de más lento del salto de productividad real es el método y el andamiaje del repo. A eso vamos.

1 · Cómo se usa Claude Code: el loop agéntico

Anthropic documenta un flujo recomendado de cuatro fases: Explorar, Planificar, Implementar y Confirmar. La clave no son las fases en sí, sino la costura entre ellas: el plan mode separa investigar de ejecutar, para que el agente no salte a codificar y termine resolviendo el problema equivocado.

Las piezas que hacen que el loop funcione

2 · La arquitectura de carpetas estándar

Un repo pensado para agentes tiene una estructura bastante estable, y conocerla de memoria te ahorra pelear con la herramienta.

mi-repo/
├── CLAUDE.md                 # reglas del proyecto (versionado)
├── .mcp.json                 # servidores MCP del equipo (versionado)
└── .claude/
    ├── settings.json         # permisos, hooks, modelo… (committed)
    ├── settings.local.json   # tus overrides (gitignored)
    ├── rules/                # un .md por tema (testing.md, api-design.md)
    ├── commands/             # /slash commands
    ├── agents/               # subagentes
    └── skills/               # SKILL.md por skill

3 · Los skills adecuados para desarrollo

Las Agent Skills son el mecanismo recomendado para empaquetar flujos repetibles. Un skill es una carpeta con un SKILL.md (más los recursos que necesite); un command es un solo .md. Los dos se disparan con /nombre, pero el skill tiene una ventaja: Claude puede invocarlo por su cuenta cuando su description encaja con lo que estás haciendo. Por eso Anthropic empuja los skills para cualquier flujo nuevo que quieras reutilizar.

Por qué son baratos: divulgación progresiva

El diseño clave es la divulgación progresiva en tres niveles. Es lo que te deja tener muchos skills sin ahogar el contexto:

• Nivel 1 · Metadata — name + description del frontmatter. ~100 tokens por skill, siempre en el system prompt (así Claude sabe cuándo usarlo).
• Nivel 2 · Instrucciones — el cuerpo del SKILL.md. Menos de 5k tokens, cargado solo al activarse el skill.
• Nivel 3+ · Recursos — scripts, plantillas, datos empaquetados. 0 tokens hasta que Claude los abre.

Anatomía de un SKILL.md

Los únicos dos campos requeridos del frontmatter son name y description:

---
name: code-review
description: Revisa el diff actual en busca de bugs y problemas de estilo.
  Úsalo cuando el usuario pida revisar cambios antes de commitear.
---

# Instrucciones
1. Corre `git diff` y analiza los archivos cambiados.
2. Señala bugs, code smells y tests faltantes.
3. Devuelve una lista priorizada, sin reescribir el código sin permiso.

Reglas exactas: name máximo 64 caracteres (solo [a-z0-9-], sin las palabras anthropic/claude); description no vacío, máximo 1024 caracteres, y debe decir qué hace y cuándo usarlo. En Claude Code los skills son basados en el sistema de archivos (sin subida por API): ~/.claude/skills/ para uso personal (todos tus repos) o .claude/skills/ para el proyecto (versionado).

Cuáles usar

El repositorio oficial anthropics/skills trae skills técnicos listos: webapp-testing, mcp-builder, claude-api, frontend-design, skill-creator y web-artifacts-builder (además de los de documentos: docx, pdf, pptx, xlsx).

4 · Lo que dice la evidencia (sin marketing)

Los números existen; el punto es leerlos con honestidad.

SWE-bench es el benchmark de referencia: el paper original (Princeton, arXiv:2310.06770) reúne 2 294 problemas reales de issues + pull requests de 12 repos Python. Su variante SWE-bench Verified (500 casos revisados por humanos, curada por OpenAI) es la que se cita para agentes; sobre ella, Claude 3.5 Sonnet marcó 49 %, superando el estado del arte previo de 45 %. La filosofía de Anthropic para lograrlo fue reveladora: scaffolding mínimo, máximo control al modelo. Ya hay variantes más duras —SWE-bench Pro, con 1 865 problemas de 41 repos profesionales (open-source y privados)— precisamente porque las viejas se saturaron.

Con un matiz que importa. Un trabajo reciente (arXiv:2512.10218) muestra que parte de esos puntajes puede reflejar memorización del set de entrenamiento más que capacidad real. Y otro (arXiv:2510.08996) apunta a un desajuste de formato: los issues largos y formales del benchmark no se parecen a las preguntas cortas que uno escribe de verdad. Un número alto ahí no te promete productividad en tu repo.

Qué NO hacer

Cierre

Si te llevas una sola cosa, que sea el principio del inicio: el repo es el que rinde, no el agente. La arquitectura de carpetas (CLAUDE.md por ámbitos, .claude/ canónico, settings versionados), el loop de cuatro fases con plan mode, los subagentes para revisión adversarial, los MCP justos y los hooks como guardrail no son "configuración": son lo que convierte a un modelo capaz en un colaborador que se corrige solo. La evidencia lo confirma por la vía dura —sin ese andamiaje, la IA hasta te frena—.

Fuentes