El fichero de contexto de agentes APC separa la versión del proyecto y la del formato

El fichero .apc/project.json con el que un repositorio describe su contexto de agentes tiene dos campos de versión, no uno. version responde a qué versión del proyecto describe ese metadata; apc responde a qué versión del formato APC espera el repositorio. Son preguntas diferentes y los valores pueden no coincidir.

La forma mínima que recoge la especificación del metadata de APC es esta:

{
  "name": "My Project",
  "version": "0.1.0",
  "apc": "0.1.0",
  "created": "2026-05-08T00:00:00Z"
}

name identifica el proyecto en formato legible y created registra cuándo se creó el conjunto de metadatos. Los dos números que importan apuntan a sujetos distintos, y ahí está el detalle que se suele pasar por alto.

Por qué no conviene unificarlos

Un equipo publica una funcionalidad y sube su aplicación de 0.1.0 a 0.2.0. Sus ficheros de agentes, reglas y formato de metadatos siguen en APC 0.1.0, así que apc se queda como estaba. No hay contradicción: son cosas separadas.

Ahora supongamos que ese mismo equipo actualiza sus ficheros de contexto para un formato APC más nuevo. Eso ya es una decisión de compatibilidad del contexto, y toca revisar el valor de apc junto a los ficheros, no ajustarlo para que cuadre con el número del lanzamiento de la aplicación. El metadata tiene que describir el contexto que hay realmente en disco.

Quien revisa un pull request distingue así si el cambio es un lanzamiento de la aplicación, un cambio de formato de contexto o las dos cosas a la vez. Una herramienta compatible sabe dónde buscar el fichero y qué formato declara el proyecto antes de interpretar su contexto.

APC es la capa de contexto portable que vive en el repositorio: ficheros como AGENTS.md y el directorio .apc/ viajan con el proyecto. APX es la capa de ejecución y herramientas de uso diario que lee ese contexto y lanza los agentes. El fichero pertenece al proyecto, no a una sesión de APX, y por eso credenciales, cuentas de proveedor, conversaciones, cachés y sesiones locales se quedan fuera: eso es estado del runtime o de la máquina.

La clave histórica apf

Las primeras implementaciones escribían a veces apf en lugar de apc para la versión de formato. El borrador actual de APC pide que los consumidores compatibles acepten esa clave heredada durante la migración, mientras que los proyectos nuevos escriban apc. Es una nota de compatibilidad, no un motivo para arrastrar las dos claves en cada fichero nuevo.

Hay quien empieza por aquí: un ejemplo mínimo de proyecto APC con la disposición completa de partida.

Cuando alguien abre .apc/project.json, bastan tres preguntas. ¿El campo version coincide con el lanzamiento previsto del proyecto? ¿El campo apc coincide con el formato que usan los ficheros de contexto? Y si aparece apf, ¿estamos ante un caso de migración? Un minuto de comprobación evita que el número de versión de un proyecto se convierta en una declaración de protocolo que nadie ha decidido.