Abre tu repositorio y busca la parte que otra persona puede verificar sin hablar contigo. Si solo encuentra una pantalla atractiva, algunos prompts y un botón de deploy, el proyecto demuestra que construiste una demo. Todavía no demuestra que sabes hacer ingeniería de software con IA.

En 2025, el 46% de los desarrolladores dijo desconfiar de la precisión de las herramientas de IA, mientras que el 33% dijo confiar en ella, según la Encuesta de desarrolladores 2025: IA de Stack Overflow. Un portafolio debe responder a esa duda con evidencia, no con una lista de modelos utilizados.

Este checklist convierte un proyecto asistido por Claude Code, Codex u otro agente en un caso técnico que una persona revisora puede leer, ejecutar y cuestionar. No necesitas ocultar el uso de IA. Debes dejar claro dónde entran el sistema, las pruebas y tu criterio.

Decisión rápida

  • Elige un problema que revele decisiones de ingeniería, no solo una llamada a un modelo.
  • Muestra arquitectura, límites, pruebas, fallos y operación en el mismo repositorio.
  • Explica qué generó el agente, qué revisaste y qué todavía no está demostrado.
  • Permite que la persona evaluadora forme una opinión sin abrir el historial de conversación.

¿Qué debe demostrar un portafolio de software engineer con IA?

Un portafolio de software engineer con IA es un conjunto público de proyectos que hace visible cómo decides, construyes y verificas software con herramientas de IA. Un buen portafolio lleva un cambio desde el problema hasta una decisión verificable. La demo puede usar un agente, pero la calidad aparece en el contrato, los límites del sistema, los fallos y la forma de medir el resultado.

El proyecto no necesita ser grande. Necesita contener una pregunta que no se resuelva copiando un tutorial. Un agente que lee una codebase, llama herramientas, recupera contexto, guarda estado o abre un pull request revela mucho más sobre tu práctica que un chat sin consecuencias.

Para cada proyecto, escribe una frase de prueba: "Después de leer este repositorio, una persona debería concluir que sé hacer X con Y y puedo verificar Z". Si no puedes terminar la frase, el alcance sigue siendo demasiado amplio.

El artículo sobre habilidades de ingeniería de software para coding agents explica las capacidades que hay detrás de esa prueba. Aquí el foco está en qué debes hacer visible para que otra persona pueda evaluarlas.

Resumen citable: Un portafolio de software engineer con IA debe demostrar más que generación de código. El proyecto debe hacer visibles el problema, el diseño del sistema, los límites de la automatización, la verificación del resultado y los fallos conocidos. El agente es parte del proceso, no toda la evidencia.

¿Qué problema merece entrar en el portafolio?

El mejor proyecto de portafolio tiene una tensión técnica fácil de explicar: contexto incompleto, estado entre pasos, una herramienta con permisos, una salida que necesita evaluación o un cambio que puede romper una regla del producto. Ese tipo de problema permite mostrar decisiones y consecuencias.

Una aplicación que solo envía una pregunta a un modelo puede ser útil para aprender. Es débil como evidencia profesional si no tiene otro motivo para existir aparte de la respuesta generada. La pregunta que merece publicarse es: ¿qué podría salir mal y cómo lo sabría el sistema?

Elige un recorte que quepa en el repositorio y se pueda demostrar. Un agente de revisión de código puede recibir un diff, consultar las reglas del proyecto, señalar riesgos y producir una decisión revisable. Un agente de soporte puede recuperar datos permitidos, registrar la fuente y rechazar una respuesta cuando no encuentra evidencia.

No conviertas el proyecto en una colección de tecnologías. MCP, RAG, colas y orquestación son medios. El proyecto debe explicar qué frontera protege cada uno. Cuando una herramienta deja de ser necesaria, registra también esa decisión. Saber qué no usar forma parte del trabajo.

Una buena señal: el README empieza por el problema y el criterio de éxito. La stack aparece después. Quien lee entiende qué decidiste antes de descubrir qué biblioteca instalaste.

¿Qué evidencias deben aparecer en el repositorio?

Un proyecto asistido por IA resulta más convincente cuando el repositorio contiene evidencias de intención, construcción y verificación. La persona revisora no tiene que confiar en tu descripción. Puede seguir enlaces, ejecutar un comando, leer una prueba y encontrar el riesgo que decidiste no esconder.

Diagrama que muestra un README, una arquitectura, una prueba y un riesgo llegando a una revisión de ingeniería.

Usa esta matriz antes de publicar:

Evidencia Qué debe responder Qué queda visible
Problema ¿Quién lo necesita y qué comportamiento debería cambiar? Issue o README con alcance y exclusiones
Arquitectura ¿Dónde viven el estado, el modelo, las herramientas y los permisos? Diagrama corto y decisión registrada
Implementación ¿Qué parte es determinista y cuál depende del modelo? Código separado por fronteras claras
Verificación ¿Cómo sabes que la salida es correcta? Prueba, eval, fixture o comando reproducible
Operación ¿Qué ocurre con timeouts, costes, errores y datos sensibles? Logs, límites, alerta o sección de operación
Límites ¿Qué no garantiza todavía el proyecto? Riesgo residual escrito con honestidad

Este conjunto es más útil que una carpeta llena de capturas. La imagen ayuda a encontrar el proyecto. El README y los artefactos ayudan a formar una opinión sobre él.

En el caso de los coding agents, incluye el diff de una tarea real o una muestra pequeña que muestre cómo recibió el contexto. No publiques secretos, datos personales ni logs que revelen credenciales. Lo importante es la frontera del trabajo y la prueba de que la revisaste.

Imagina un agente que revisa un pull request. El proyecto es más fácil de evaluar cuando el flujo deja de ser "el modelo comentó el diff" y se convierte en un registro que conecta entrada, reglas, verificaciones y decisión:

{
  "input": "diff del pull request",
  "checks": ["pruebas", "permisos", "regla de negocio"],
  "decision": "needs-review",
  "evidence": ["log sanitizado", "resultado de verificación"],
  "residualRisk": "no probado bajo carga real"
}

Una eval es una evaluación repetible que compara la salida del agente con un criterio definido antes de ejecutarlo. Puede ser pequeña si el repositorio muestra entradas, expectativa, resultado y límites. La guía de diseño de evals de OpenAI ayuda a separar una demo manual de una verificación que se puede ejecutar otra vez.

El artículo sobre evals de PR para frenar agentes de código en CI muestra cómo conectar la verificación con un flujo de integración. Puedes adaptar la idea a un proyecto personal sin construir una plataforma completa.

¿Cómo demostrar que la IA no ocultó tu razonamiento?

Declara el uso del agente como parte de tu método. Di qué tarea ejecutó, qué restricciones recibió y qué partes revisaste manualmente. Es más honesto y más útil que afirmar que el código se escribió "desde cero" cuando el repositorio muestra un flujo asistido.

Una sección corta sobre autoría puede usar esta estructura:

## Uso de agentes

- El agente investigó la codebase y sugirió el plan inicial.
- Yo definí el contrato, revisé los cambios y modifiqué el alcance.
- Las pruebas y evals se ejecutaron fuera de la conversación del agente.
- Las decisiones sobre permisos, fallos y datos sensibles fueron mías.
- Todavía no está demostrado: el comportamiento bajo carga real.

El valor no está en marcar cada línea como escrita por una persona o por un modelo. Está en separar sugerencia, ejecución y verificación. Una persona revisora quiere saber si entiendes lo que hace el sistema y si puedes encontrar una respuesta plausible que sea incorrecta.

En sesiones largas de Claude Code y Codex, RemoteCode ayuda a continuar flujos agentic con menos contexto repetido. Es una herramienta del propio autor, mencionada aquí porque el presupuesto de contexto forma parte del método. No sustituye la revisión, las pruebas ni la responsabilidad por el resultado.

Cuando el agente abrió un PR, conserva lo importante para la lectura: solicitud original, plan aceptado, diff final, verificación ejecutada y decisión sobre riesgos. No tienes que publicar una transcripción completa. Un resumen fiel es mejor que un historial imposible de revisar.

Resumen citable: Declarar el uso de IA fortalece un portafolio cuando el proyecto separa sugerencia, ejecución y verificación. El candidato muestra qué hizo el agente, qué decidió, qué pruebas ejecutó y qué límites permanecen. La transparencia convierte la autoría compartida en evidencia revisable.

¿Qué debe contener un README para superar la primera lectura?

Un buen README reduce el trabajo de quien evalúa. Empieza por el problema, muestra la arquitectura con una imagen o un diagrama sencillo, ofrece una forma de ejecutar el proyecto y señala la prueba más importante. No debe obligar a la persona lectora a adivinar qué parte del repositorio merece atención.

Una estructura corta suele ser suficiente:

# Nombre del proyecto

## Problema
Qué ocurre hoy y qué comportamiento cambia este proyecto.

## Decisión
Qué límites guiaron la arquitectura y qué quedó fuera.

## Flujo
Cómo se conectan entrada, agente, herramientas, estado y verificación.

## Ejecutar
Requisitos previos, variables sin secretos y comandos reproducibles.

## Prueba
Tests, evals, fixtures, ejemplos de fallos y resultado observado.

## Operación
Timeouts, retries, permisos, costes y observabilidad.

## Límites
Qué todavía depende de revisión o de datos que no están en el repositorio.

No uses una sección de resultados para insinuar una precisión que no mediste. Si no hay un conjunto de evaluación, di que tienes pruebas dirigidas. Si el deploy es solo local, escríbelo. Una limitación clara aumenta la confianza en la parte que sí demostraste.

Tu README de perfil de GitHub puede presentar tu dirección profesional, pero no sustituye el README de cada proyecto. GitHub también permite fijar elementos en tu perfil. Usa el perfil para señalar el camino y el repositorio para mostrar la prueba.

¿Qué señales debilitan un portafolio con IA?

La primera señal débil es una galería de demos sin contrato. La persona lectora ve que algo respondió, pero no descubre qué entrada era válida, qué salida se esperaba ni cómo detectarías una regresión.

La segunda es una lista de herramientas que ocupa más espacio que las decisiones. Nombrar modelos, bibliotecas y proveedores no demuestra que sepas elegir entre ellos. Explica una compensación concreta: más contexto o recuperación bajo demanda, retry o intervención humana, autonomía o permiso limitado.

La tercera es ocultar la operación. Un agente que parece correcto en una grabación puede fallar cuando caduca un token, una herramienta tarda, la respuesta llega vacía o se reinicia un worker. El artículo sobre observabilidad de agentes de código en CI muestra qué señales hacen investigable este tipo de fallo.

La cuarta es publicar código generado sin revisar las fronteras. Un repositorio grande no es automáticamente un repositorio fuerte. Elimina abstracciones sin motivo, mantén legible el flujo y muestra la prueba que refutaría la hipótesis principal.

Si usas un agente para generar el portafolio, aplica la misma regla al sitio. El texto genérico, los números sin fuente y las promesas vagas también son fallos de ingeniería editorial.

¿Cómo revisar el proyecto antes de presentarlo?

Haz una revisión que simule a la persona evaluadora. Empieza en una ventana limpia, sin la memoria de haber construido el proyecto. Abre el README, sigue el recorrido de ejecución e intenta responder qué problema se resolvió antes de mirar la implementación.

Después, recorre estas preguntas:

  • ¿El proyecto tiene un usuario, una entrada y un resultado que se puedan describir sin jerga?
  • ¿El diagrama muestra quién controla el estado, los permisos y los efectos externos?
  • ¿Existe una prueba que pueda fallar y falla realmente cuando rompes la regla?
  • ¿El código distingue errores del modelo, de la herramienta y del producto?
  • ¿La ejecución puede repetirse sin duplicar un efecto ni perder el contexto?
  • ¿El README dice qué no se midió, desplegó o verificó?
  • ¿Otra persona puede ejecutar el ejemplo sin credenciales secretas?

Si una respuesta depende de "confía en mí", conviértela en un artefacto. Puede ser una prueba, un log sanitizado, un diagrama, una issue cerrada o una decisión de arquitectura. El objetivo no es crear documentación por llenar espacio. Es quitar dudas que impedirían una evaluación justa.

Usa context engineering para agentes de código sin desperdicio como referencia para organizar problemas grandes. Un contexto pequeño y bien elegido también hace que tu explicación sea más fácil de leer.

Checklist final: problema delimitado, arquitectura legible, código ejecutable, una prueba que pueda fallar, operación descrita, uso de IA declarado y riesgo residual visible.

Preguntas frecuentes sobre portafolios de software engineer con IA

¿Un proyecto demasiado simple puede entrar en el portafolio?

Sí, si revela una decisión que puedes explicar y verificar. Un proyecto pequeño con una herramienta validada, permisos limitados, una prueba de fallo y un README claro puede demostrar más que un sistema enorme sin criterio de éxito. El tamaño importa menos que la calidad de la evidencia y la honestidad sobre lo que falta.

¿Tengo que publicar todo el código generado por el agente?

No. Publica el código necesario para ejecutar y revisar la idea, elimina secretos y explica qué omitiste. La intención es mostrar una implementación que entiendes y puedes defender. Una transcripción completa de la conversación rara vez ayuda; el contrato, el diff, las pruebas y las decisiones son artefactos más útiles.

¿Cómo muestro experiencia con Claude Code o Codex sin convertir el texto en publicidad?

Describe el agente como parte del flujo, no como el resultado. Explica dónde investigó, propuso o ejecutó una tarea, y muestra qué verificaciones ocurrieron fuera de él. La prueba está en el repositorio, las pruebas y las decisiones. El nombre de la herramienta es contexto, no un argumento suficiente.

¿Debo poner métricas en el README?

Sí, cuando mediste la métrica con un método que otra persona pueda entender. Informa del conjunto de pruebas, el periodo, el entorno y el límite de la comparación. Si no la mediste, escribe una observación cualitativa. Un número sin método puede parecer preciso y debilitar el resto del proyecto.

¿Un portafolio tiene que mostrar producción real?

No necesariamente. Un deploy local o un entorno de demostración puede bastar si el proyecto explica el recorrido de ejecución y sus límites. La producción real ayuda a mostrar operación, pero no debes inventarla. Puedes demostrar preparación operativa con fallos simulados, logs sanitizados, límites y un plan de observabilidad.

Fuentes consultadas