Construyamos repositorios prompt-first para tus aplicaciones

Las aplicaciones en producción nunca fueron solo código.

Incluso un servicio modesto tiene capas que las personas deben mantener: pipelines de build, entornos, pruebas, documentación, controles de seguridad, observabilidad, gestión de dependencias y el proceso social de revisión y publicación. Los agentes de programación con IA no eliminan esas capas. Cambian dónde se realiza el trabajo y quién —o qué— se encarga de las tareas repetitivas.

Un repositorio prompt-first trata las instrucciones para agentes, las skills, las conexiones a herramientas y los loops de ejecución como artefactos de primera clase junto al código de la aplicación. «Prompt-first» no significa que todo se resuelva con prompts, ni pone las instrucciones en lenguaje natural por encima de la arquitectura. Significa que el repositorio contiene suficiente contexto operativo legible por máquina para que un agente trabaje sin reconstruir el proceso del equipo a partir del historial de chat.

La tesis de este artículo es una hipótesis editorial, no el resultado de un benchmark: reforzar esos cuatro componentes puede reducir el retrabajo evitable y acortar el camino hacia un cambio listo para revisión, pero solo si los controles deterministas —pruebas, permisos, CI y escalamiento a una persona— conservan la autoridad final.

Este artículo compara el stack tradicional de mantenimiento con los avances recientes en desarrollo con IA, relaciona cada avance con un cuello de botella específico y termina con preguntas abiertas sobre lo que viene después.

TL;DR

• Las aplicaciones modernas en producción requieren muchas capas más allá del código fuente: CI/CD, entornos, observabilidad, seguridad, documentación y prácticas de revisión.
• El desarrollo con IA no elimina esas capas. Desplaza el esfuerzo hacia la especificación, el contexto del repositorio, el acceso a herramientas y los loops de verificación.
• Un repositorio prompt-first reúne cuatro componentes básicos:
  • AGENTS.md — instrucciones del repositorio para distintas herramientas (build, pruebas, convenciones, límites)
  • Skills — conocimiento procedimental reutilizable en carpetas con SKILL.md
  • MCP — conexiones estandarizadas a sistemas externos (gestores de issues, bases de datos, CI, documentación)
  • Loops — ciclos de agentes programados o activados por eventos, con estado persistente y condiciones de salida
• Cada componente aborda un cuello de botella distinto: incorporación, flujos de trabajo repetidos, fricción de integración y fatiga de dar prompts turno a turno.
• Las instrucciones orientan el comportamiento; las pruebas, los permisos, CI, la protección de ramas y la revisión hacen cumplir los límites.
• El terreno aún abierto es la gobernanza: versionar skills, auditar el acceso de MCP, gestionar workspaces entre repositorios y decidir cuándo un repositorio prompt-first justifica el costo adicional.

Qué aprenderás aquí

• Las capas de mantenimiento que realmente necesita una aplicación en producción, presentadas como un mapa del sistema y no como una lista de herramientas.
• Cómo los patrones recientes de desarrollo con IA se relacionan uno a uno con los cuellos de botella clásicos.
• Una estructura de referencia para un repositorio prompt-first reforzado.
• Dónde encajan las skills, MCP y los loops con respecto a las especificaciones, los worktrees y los subagentes.
• Cómo migrar un repositorio existente una capa a la vez.
• Qué controles deben hacerse cumplir fuera del prompt y qué métricas muestran si el enfoque está ayudando.
• Límites reales y preguntas abiertas para la próxima etapa del desarrollo de aplicaciones.

Audiencia: ingenieros y arquitectos que ya usan agentes de programación y quieren un diseño de repositorio que escale más allá de los prompts improvisados.

El stack de mantenimiento que ya teníamos

Antes de que los agentes entraran al IDE, una «aplicación moderna en producción» ya era un conjunto de capas. El código de la aplicación era el centro visible, pero los equipos pagaban un costo continuo por todo lo que lo rodeaba.

                         ┌─────────────────────────────┐
                         │   Product & requirements      │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │   Application code + tests   │
                         └──────────────┬──────────────┘
                                        │
        ┌───────────────────────────────┼───────────────────────────────┐
        │                               │                               │
┌───────▼────────┐            ┌─────────▼─────────┐           ┌────────▼────────┐
│ Build & deploy │            │ Environments &     │           │ Security &       │
│ CI/CD          │            │ configuration      │           │ compliance       │
└───────┬────────┘            └─────────┬─────────┘           └────────┬────────┘
        │                               │                               │
        └───────────────────────────────┼───────────────────────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │ Observability & operations   │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │ Docs, onboarding, decisions  │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │ Review, release, ownership   │
                         └─────────────────────────────┘

Cada capa existe porque, sin ella, algo falló:

Esta estructura es conocida. Si quieres la versión arquitectónica completa —cuándo incorporar CQRS, eventos, autenticación externalizada e IA como capa de producto—, consulta Las piezas del diseño de software moderno y eficaz.

El punto importante para este artículo: los agentes heredan el mismo stack. Si tu repositorio carece de pruebas, CI o convenciones claras, un agente no puede inferir de manera confiable los controles que faltan. Puede producir resultados plausibles rápidamente, pero plausibilidad no significa estar listo para producción.

Cómo el desarrollo con IA aborda los cuellos de botella

El desarrollo asistido por IA suele describirse como «programar más rápido». Esa descripción está incompleta. Las mejoras duraderas deben evaluarse según si cada avance reduce un punto de fricción específico del flujo de trabajo anterior.

Este es el mapa de cuellos de botella que considero más útil como modelo editorial al July 17, 2026:

Dos artículos relacionados profundizan en temas cercanos:

• El diseño por encima del código — por qué las especificaciones importan más, no menos, cuando generar código es barato.
• Construir un agente ingeniero sénior — ingeniería de loops, subagentes y la escala de confianza para PR automáticos.

El repositorio prompt-first es la capa de organización para una sola aplicación que hace que esos avances sean repetibles dentro de Git. Tiene un alcance menor que un workspace agéntico, que coordina varios repositorios, y es distinto de una auditoría del flujo de trabajo diario, que ayuda a decidir dónde debe vivir el conocimiento que se utiliza repetidamente.

Qué significa «prompt-first»

«Prompt-first» no significa «sin código». Significa que el repositorio está diseñado para que un agente pueda responder estas preguntas sin adivinar:

1. ¿Qué es este proyecto?
2. ¿Cómo ejecuto el build, las pruebas y el lint?
3. ¿Qué no debo hacer nunca?
4. ¿Qué flujos de trabajo están estandarizados?
5. ¿A qué sistemas externos puedo acceder?
6. ¿Cuándo está realmente terminada una tarea?

Las personas necesitaban las mismas respuestas. Los equipos suelen dispersarlas entre README, wikis, chats y experiencia individual. Los agentes hacen visible el costo de esas respuestas ausentes mediante diffs deficientes, builds fallidos y correcciones repetidas.

Capa 1: AGENTS.md — instrucciones del repositorio para máquinas

AGENTS.md es una convención abierta de Markdown administrada por la Agentic AI Foundation bajo la Linux Foundation. Complementa a README.md: README orienta a las personas; AGENTS.md orienta a los agentes de programación.

Según la documentación disponible al July 17, 2026, un conjunto creciente de herramientas lee AGENTS.md directamente, entre ellas OpenAI Codex, GitHub Copilot, Cursor, Google Jules y otras enumeradas en agents.md. El formato es intencionalmente sencillo: no hay un esquema obligatorio, solo secciones de Markdown que los agentes interpretan como instrucciones.

Secciones recomendadas:

• descripción general del proyecto
• comandos de build y pruebas
• estilo de código y convenciones
• riesgos de seguridad a tener en cuenta
• reglas para commits y PR

En los monorepos, los archivos AGENTS.md anidados permiten que los subpaquetes tengan reglas locales. Prevalece el archivo más cercano a la ruta editada.

Advertencia sobre las herramientas (respaldada por fuentes, no una opinión): Claude Code lee CLAUDE.md, no AGENTS.md. El patrón de compatibilidad documentado es un archivo CLAUDE.md de una línea que importa las reglas compartidas: @AGENTS.md. Cursor admite AGENTS.md y agrega reglas específicas en .cursor/rules/*.mdc. Una fuente de verdad, varios puntos de entrada; no tres copias que divergen.

Capa 2: Skills — conocimiento procedimental bajo demanda

Una skill es un directorio con un archivo SKILL.md obligatorio. Según la especificación Agent Skills, compartida entre herramientas, el frontmatter YAML requiere name y description; el cuerpo contiene instrucciones y puede apuntar a scripts, referencias y recursos. El artículo técnico de Anthropic sobre Agent Skills describe la divulgación progresiva: los agentes precargan metadatos y solo cargan las instrucciones completas cuando son relevantes.

Las implementaciones difieren en algunos detalles. Cursor exige ambos campos, mientras que la documentación actual de Claude Code es más permisiva para las skills específicas de Claude. Si la portabilidad importa, sigue la especificación abierta, que es más estricta.

Las skills abordan un cuello de botella distinto al de AGENTS.md:

• AGENTS.md responde «¿cómo funciona este repositorio?».
• Las skills responden «¿cómo ejecutamos este flujo de trabajo en distintos repositorios?».

Ejemplos: redacción de artículos de investigación, auditoría de fuentes, preparación de PR con worktrees, revisión de seguridad y guías de migración.

Para conocer cómo gobernar skills a escala de empresa, consulta Cómo construir un registro de skills empresariales para agentes de IA.

Capa 3: MCP — integraciones sin código de conexión a medida

El Model Context Protocol estandariza cómo los agentes se conectan a herramientas y datos mediante JSON-RPC. En lugar de que cada host invente su propio adaptador para Jira/Slack/Postgres, los servidores MCP exponen herramientas, recursos y, cuando se admite, interfaces interactivas.

Hitos importantes de 2026:

• January 26, 2026 — MCP Apps se lanzó como la primera extensión oficial, permitiendo que las herramientas devuelvan interfaces interactivas aisladas dentro de los hosts de agentes.
• July 28, 2026 (lanzamiento final programado) — la versión candidata de la especificación MCP 2026-07-28 avanza hacia un núcleo sin estado, una política formal de obsolescencia, autorización alineada con OAuth y extensiones que alcanzan un mayor nivel de madurez, como Tasks.

MCP aborda la fricción de integración, no la calidad de la generación de código. Con un host configurado apropiadamente, puede convertir «aquí está el patch» en «PR abierto, ticket actualizado y estado de CI verificado».

La configuración de MCP es específica de cada host, aunque el protocolo sea compartido. Claude Code admite un archivo .mcp.json en la raíz para servidores asociados al proyecto; Cursor usa .cursor/mcp.json. Trata el acceso a los servidores como credenciales de API: privilegio mínimo, acciones auditables y aprobación explícita para los sistemas de producción.

Capa 4: Loops — de conversar a operar

La ingeniería de loops es el cambio de darle un prompt a un agente una sola vez a diseñar un ciclo acotado que se ejecuta hasta alcanzar una condición de salida verificable, un límite de presupuesto o una condición de escalamiento. Los activadores pueden ser horarios, etiquetas, fallos de CI o issues nuevos. El estado persistente vive fuera del contexto del modelo: tableros de tareas, archivos de estado, grafos de Beads o artefactos de Spec Kit.

Las capacidades de agentes de Cursor documentadas al July 17, 2026 hacen que varios componentes de loops sean prácticos en herramientas de uso generalizado:

• Worktrees para checkouts aislados por tarea de agente
• Subagentes y /multitask para trabajo paralelo
• Subagentes en la nube para loops de larga duración o de corrección de CI en VM separadas

Anatomía mínima de un loop:

trigger -> load repo context (AGENTS.md + skills)
       -> plan in isolated worktree
       -> act (edit code, call MCP tools)
       -> verify (tests, lint, CI)
       -> exit or escalate
       -> open PR / update ticket

Las condiciones de salida explícitas mejoran la confiabilidad solo cuando están respaldadas por controles que se puedan hacer cumplir. Si CI debe pasar antes del merge, documenta esa expectativa en AGENTS.md y hazla cumplir mediante la protección de ramas.

Estructura de referencia: un repositorio prompt-first reforzado

A continuación se muestra una estructura inicial práctica. Adapta su profundidad al tamaño del equipo; un proyecto individual necesita menos formalidades que un equipo de plataforma.

repo/
├── AGENTS.md                 # cross-tool instructions (build, test, guardrails)
├── CLAUDE.md                 # optional: @AGENTS.md import for Claude Code
├── README.md                 # human onboarding
├── .cursor/
│   ├── rules/                # scoped Cursor overrides (*.mdc)
│   └── skills/               # repo-local skills (or .claude/skills/)
├── .claude/
│   ├── skills/               # Claude Code project skills
│   └── commands/             # slash commands for repeatable workflows
├── .github/
│   └── workflows/            # CI — the agent's hard verifier
├── .mcp.json                 # Claude Code project MCP config (optional)
├── .cursor/mcp.json          # Cursor project MCP config (optional)
├── specs/ or openspec/       # optional: approved change artifacts
└── src/ ...                  # application code (still the product)

No incluyas ambos archivos de MCP en commits por defecto. Elige los puntos de configuración que tu equipo realmente usa, evita duplicar definiciones de servidores y nunca coloques secretos directamente en ninguno de los dos archivos.

Matriz de portabilidad

El modelo de contenido converge más rápido que las ubicaciones de los archivos:

AGENTS.md inicial (resumido)

# MyApp

## Commands
- Install: `npm ci`
- Dev: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Test: `npm test`

## Conventions
- TypeScript strict mode; match existing file layout.
- Keep diffs minimal; do not refactor unrelated code.
- Commit with signoff: `git commit --signoff`

## Behavioral boundaries
- Do not commit secrets or edit production env files.
- Do not disable tests to make CI pass.
- Run `npm run build` before opening a PR for user-facing changes.

## PR rules
- One logical change per PR.
- Include validation steps in the PR description.

Plantilla básica de skill

---
name: release-patch
description: Prepare a patch release. Use when the user asks to cut a release or bump patch version.
---

# Release patch workflow

1. Confirm main is green in CI.
2. Update CHANGELOG and version fields.
3. Run full test suite.
4. Open PR with release notes; do not push tags until approved.

Tabla de decisión: dónde colocar el conocimiento

Refuerzo: orientar no es hacer cumplir

Este es el límite más importante en un repositorio prompt-first:

AGENTS.md + skills     -> influence agent behavior
permissions + CI      -> constrain what can happen
branch protection     -> decides what can merge
human escalation      -> handles ambiguity and high-impact actions

Las instrucciones son contexto, no una barrera de seguridad. La documentación de Claude Code lo dice directamente: CLAUDE.md moldea el comportamiento, mientras que las configuraciones administradas hacen cumplir las políticas. El mismo principio se aplica a otros hosts.

Prueba los artefactos destinados a los agentes

Trata las instrucciones y las skills como código, incluso cuando estén en Markdown:

1. Valida el frontmatter de las skills contra la especificación Agent Skills.
2. Mantén un conjunto pequeño de evaluaciones con prompts que deberían y no deberían activar cada skill importante.
3. Ejecuta en CI los comandos de build y pruebas documentados para que las instrucciones desactualizadas fallen de forma visible.
4. Revisa los cambios de configuración de MCP con el mismo cuidado que los cambios en los permisos de la aplicación.
5. Registra una persona responsable y la fecha de última revisión para las instrucciones, skills y herramientas de alto impacto.

Define responsables antes de escalar

El modelo exacto de responsabilidades depende de la organización. El requisito no es que cada artefacto necesite un comité distinto. El requisito es que cada artefacto con privilegios tenga a alguien responsable de sus cambios y de revertirlos.

Ejemplo de fallo: importa que la salida sea segura

Considera un loop de publicación que recibe instrucciones contradictorias y luego falla la validación:

Issue requests patch release
  -> AGENTS.md says "release only from main"
  -> release skill says "work on a release branch"
  -> agent detects conflict and escalates instead of guessing
  -> human confirms branch policy
  -> agent works in isolated worktree
  -> restricted GitHub MCP can read CI and open a PR, but cannot merge
  -> build fails twice
  -> loop reaches retry limit and records logs + blocker
  -> human receives a reviewable PR, not a hidden production action

Un resultado exitoso no siempre es un cambio integrado. A veces es un fallo acotado con evidencia suficiente para que una persona continúe de forma segura.

Cuello de botella por cuello de botella: antes y después

Incorporación

Antes: Quienes contribuyen por primera vez leen el README, preguntan en Slack y copian comandos de un PR antiguo.

Después: AGENTS.md les indica a los agentes compatibles qué comandos intentar. Los archivos anidados cubren los paquetes del monorepo, mientras CI comprueba si los comandos realmente pasan.

Límite: AGENTS.md se desactualiza como cualquier documento. Asigna una persona responsable y revísalo en los PR cuando cambien los pasos de build.

Flujos de trabajo repetidos

Antes: Los ingenieros sénior vuelven a escribir la misma lista de verificación para publicaciones, migraciones o auditorías.

Después: Las skills codifican la lista una sola vez. Las descripciones actúan como metadatos para determinar cuándo usarlas.

Límite: Las skills pueden contener scripts inseguros o instrucciones desactualizadas. Revísalas como si fueran bibliotecas. Consulta el artículo sobre el registro de skills para conocer patrones de gobernanza.

Integraciones externas

Antes: Los agentes sugieren comandos de shell que usan curl para llamar a API de producción desde una laptop.

Después: Los hosts de MCP pueden exponer herramientas aprobadas mediante controles de autenticación, consentimiento y registro específicos de cada host.

Límite: MCP por sí mismo no hace cumplir esos controles. Amplía la superficie de ataque, por lo que es necesario leer las recomendaciones de seguridad de la especificación y el modelo de permisos de cada host.

Programación y paralelismo

Antes: Un desarrollador, una rama, un chat con un agente, tareas secuenciales.

Después: Los worktrees aíslan tareas; los subagentes paralelizan la exploración; los agentes en la nube supervisan CI.

Límite: El paralelismo sin reglas de responsabilidad reproduce conflictos de merge a velocidad de máquina. Mantén la regla de entrega paralela con Spec Kit: un flujo de tareas, una rama, un worktree, una persona responsable a la vez.

Calidad y confianza

Antes: La revisión detecta lo que las pruebas no detectan, si es que hay revisión.

Después: AGENTS.md indica a los agentes qué comprobaciones ejecutar; CI hace cumplir los requisitos para el merge; las evaluaciones opcionales califican resultados no deterministas.

Límite: Los agentes pueden aprovechar las debilidades de verificadores poco rigurosos. Para cambios de alto riesgo, separa al maker que crea el cambio de un checker independiente que lo revisa. Comienza con alcances acotados para PR automáticos (actualizaciones de dependencias, formato) antes de abordar cambios de arquitectura.

Ruta de migración: justifica cada capa

No reconstruyas un repositorio existente alrededor de los agentes en un solo pull request. Agrega la siguiente capa solo después de que la anterior resuelva un problema visible:

Stage 0: code + CI baseline
  -> Stage 1: AGENTS.md for commands, boundaries, and ownership
  -> Stage 2: skills for workflows repeated often enough to standardize
  -> Stage 3: MCP for governed external data and actions
  -> Stage 4: bounded loops for work with reliable verification

Una primera pasada de 30 minutos

1. Crea AGENTS.md con los cinco comandos que realmente usan quienes contribuyen.
2. Agrega tres límites de comportamiento: alcance, secretos y validación obligatoria.
3. Enlaza los registros de decisiones de arquitectura (ADRs) o runbooks que los agentes suelen pasar por alto.
4. Extrae un flujo de trabajo repetido y de bajo riesgo a una skill.
5. Mantén desactivado el acceso de MCP a producción.
6. Confirma que CI ejecuta de forma independiente el build y las pruebas mencionadas en AGENTS.md.

Eso es suficiente para la primera iteración. Agrega herramientas externas y loops desatendidos solo después de que las sesiones habituales con agentes sean predecibles.

Mide si está ayudando

La tesis del artículo debe ponerse a prueba dentro de cada equipo, en lugar de aceptarse por intuición. Registra una línea base antes de agregar automatización y luego monitorea:

Las líneas de código generadas y la cantidad de sesiones de agentes son métricas de actividad, no de éxito. Un repositorio prompt-first solo ayuda cuando reduce el retrabajo o el tiempo de entrega sin aumentar los defectos que llegan a producción ni el riesgo operativo.

Antipatrones

• El vertedero de instrucciones: un AGENTS.md gigante consume contexto y mezcla reglas estables con procedimientos poco frecuentes.
• Tres fuentes de verdad: AGENTS.md, CLAUDE.md y las reglas de Cursor repiten el mismo texto y se desactualizan de forma independiente.
• Seguridad basada solo en prompts: las instrucciones dicen «pregunta primero», pero las credenciales aún permiten acciones irreversibles en producción.
• Loops sin límites: no hay límite de reintentos, presupuesto de costo, estado persistente ni ruta de escalamiento.
• Cambios de alto riesgo certificados por el propio agente: el mismo agente implementa, revisa y declara el éxito.
• La apariencia de un build exitoso: la compilación pasa, pero no se prueban las migraciones, la accesibilidad, la seguridad ni el rollback.
• Ceguera ante la cadena de suministro de skills: las skills copiadas pueden contener instrucciones desactualizadas, scripts ejecutables o supuestos ocultos sobre la red.

Cuándo no usar este patrón

No agregues el stack completo a todos los repositorios. README más CI puede ser suficiente cuando el código es un experimento desechable, el uso de agentes es poco frecuente, ningún flujo de trabajo se repite o las acciones externas agregarían más costos de seguridad que valor.

Usa lo siguiente como una heurística editorial, no como un umbral universal:

Do people or agents repeatedly lose the same repo context?
  no  -> improve README and CI first
  yes -> add AGENTS.md
        Does a procedure repeat and have a stable success condition?
          yes -> add a skill
          Does the workflow require external data or action?
            yes -> add least-privilege MCP access
            Can deterministic checks bound unattended execution?
              yes -> add a loop with limits and escalation
              no  -> keep a human in the execution path

Qué sigue: preguntas abiertas

Los componentes están disponibles al July 17, 2026. El modelo operativo aún no está definido. Estas son las preguntas que incluiría en un RFC de equipo antes de llevar los repositorios prompt-first a toda una organización.

1. ¿Quién es responsable de los artefactos prompt-first?

Los equipos de aplicación son responsables del código. Los equipos de plataforma suelen ser responsables de CI. ¿Quién se encarga de AGENTS.md, las skills y las listas de servidores permitidos de MCP? Sin una responsabilidad explícita, estos artefactos pueden desactualizarse como cualquier otra documentación o configuración.

2. ¿Cómo versionamos y probamos las skills?

Versionamos paquetes y fijamos dependencias. Las skills pueden contener scripts ejecutables e instrucciones operativas, pero muchos repositorios todavía las almacenan como Markdown común. ¿Necesitamos lockfiles, semver, procedencia y validación en CI para el frontmatter de SKILL.md, de la misma manera que este repositorio valida el frontmatter de los artículos durante el build?

3. ¿Qué tan portable debería ser el repositorio?

AGENTS.md, Agent Skills y MCP proporcionan capas compartidas de contenido o protocolo, pero los archivos de reglas y configuración específicos de cada host siguen existiendo. ¿Debería un equipo optimizar para la mayor compatibilidad posible entre agentes o usar deliberadamente las funciones más sólidas de políticas y automatización de un solo host? La portabilidad tiene valor, pero una configuración basada en el mínimo común denominador puede ocultar capacidades que un equipo con una sola plataforma realmente necesita.

4. Agentes entre repositorios y en entornos polyrepo

El changelog de Cursor del April 24, 2026 presentó workspaces con múltiples raíces en Agents Window para que una sesión pueda abarcar frontend, backend y bibliotecas compartidas. Eso eleva el diseño prompt-first de un solo repositorio a un manifiesto de workspace. Al July 17, 2026, no encontré un estándar abierto ampliamente adoptado para esa capa.

5. Seguridad y cumplimiento a escala

La versión candidata de MCP 2026-07-28 alinea más estrechamente la autorización con los despliegues de OAuth y OpenID Connect, pero los equipos aún necesitan listas de servidores permitidos, reglas de clasificación de datos y registros de auditoría para las llamadas a herramientas. Los repositorios prompt-first pueden hacer que los agentes sean productivos; también pueden facilitar las vías de exfiltración si MCP está mal configurado.

6. El rol humano después de adoptar prompt-first

Si los loops se encargan de la implementación rutinaria, el trabajo humano se concentra en:

• selección de problemas y criterio de producto
• diseño de arquitectura y de modos de fallo
• diseño de verificadores (qué significa «terminado»)
• revisión de diffs y del riesgo organizacional

Esto coincide con El diseño por encima del código. Una posible especialidad emergente es la del operador de repositorio: alguien que cuida AGENTS.md, las skills, las políticas de MCP y las condiciones de salida de los loops de la misma manera que los SRE cuidan los runbooks. Esa es una inferencia editorial, no un rol establecido.

7. ¿Se convierte el repositorio en un contrato operativo ejecutable?

Históricamente, los repositorios de código fuente almacenaban código y configuración de build. Los repositorios prompt-first también almacenan intención, procedimientos, límites de herramientas, verificadores y automatización. La pregunta abierta es si esos artefactos convergerán en un contrato operativo ejecutable o seguirán siendo una colección dispersa de archivos específicos de cada host que los equipos deben conciliar continuamente.

Conclusión

Los repositorios prompt-first no reemplazan la arquitectura de software, CI ni el criterio de ingeniería. Son una forma de hacer visible y reutilizable el contexto operativo alrededor de una aplicación tanto para las personas como para los agentes.

Comienza con una fuente de instrucciones y una línea base de CI que se haga cumplir. Agrega una skill cuando un procedimiento se repita, MCP cuando una acción externa tenga un límite claro de permisos y un loop solo cuando las comprobaciones deterministas puedan acotar su ejecución. Mide el retrabajo, la carga de revisión, los defectos que llegan a producción y el tiempo de entrega antes de agregar más autonomía.

Es poco probable que la ventaja futura provenga solo de los prompts. Vendrá de repositorios que hagan legible la intención, restrinjan el acceso, automaticen la verificación y permitan fallar de forma segura.

Fuentes

Fuentes primarias y oficiales consultadas para este artículo:

• AGENTS.md — descripción general del formato abierto, archivos anidados, compatibilidad del ecosistema (Agentic AI Foundation / Linux Foundation)
• Especificación Agent Skills — estructura portable de SKILL.md, metadatos obligatorios y divulgación progresiva
• Anthropic — Cómo preparar agentes para el mundo real con Agent Skills — estructura de SKILL.md y divulgación progresiva
• Documentación de skills de Claude Code — frontmatter, invocación, skills de proyecto frente a skills personales
• Documentación de memoria de Claude Code — CLAUDE.md, importaciones, compatibilidad con AGENTS.md y el límite entre orientación y aplicación obligatoria
• Documentación de MCP de Claude Code — .mcp.json asociado al proyecto, aprobación y alcances de configuración
• Especificación de Model Context Protocol (2025-11-25) — componentes básicos del protocolo y recomendaciones de seguridad
• Blog de MCP — Anuncio de MCP Apps (January 26, 2026) — extensión de interfaz interactiva
• Blog de MCP — Versión candidata de la especificación 2026-07-28 (May 21, 2026) — núcleo sin estado, política de obsolescencia, alineación con OAuth
• Documentación de Cursor — Reglas — compatibilidad con AGENTS.md y .cursor/rules/*.mdc
• Documentación de Cursor — Agent Skills — .cursor/skills, metadatos obligatorios y descubrimiento de skills
• Documentación de Cursor — MCP — .cursor/mcp.json, autenticación y alcances de configuración
• Documentación de Cursor — Worktrees — checkouts aislados, .cursor/worktrees.json
• Documentación de Cursor — Subagentes — agentes en paralelo, subagentes en la nube, reglas de herencia de MCP
• Changelog de Cursor — Multitarea, Worktrees, Workspaces con múltiples raíces (April 24, 2026)
• Changelog de Cursor — Subagentes en la nube en Agents Window

Lecturas relacionadas en este devlog:

• Las piezas del diseño de software moderno y eficaz
• El diseño por encima del código
• Construir un agente ingeniero sénior
• De la especificación a la entrega paralela con Spec Kit, Cursor y Beads
• Cómo construir un registro de skills empresariales para agentes de IA
• Planificación adecuada para el desarrollo de ingeniería: de los prompts a Spec Kit
• Workspaces agénticos: submódulos, skills, conocimiento y entrega guiada por especificaciones
• Audita tu flujo de trabajo diario con agentes de IA