AGENTIC · PORTFOLIO TRACKER
Portfolio Tracker: ingeniería de un software de punta a punta con un agente de IA
Un producto personal en siete repositorios: yo fijo los requisitos, Codex los implementa bajo reglas escritas y, por regla, cada cambio sustancial parte de una spec y un work item y termina en una decisión de versión; la API, la app y el sitio salen luego en un release etiquetado.
Redactada con Claude Code a partir de los repositorios de Portfolio Tracker (estado del 3 de julio de 2026) y publicada en una versión que Edgardo autorizó el 16 de noviembre de 2026. Cómo se escribió esta nota.
En breve
- Portfolio Tracker es un rastreador de portafolio personal de solo lectura, un proyecto mío (declaración del 16 de noviembre de 2026), repartido en 7 repositorios activos, de los cuales solo el de documentación es público.
- Codex lo implementa bajo reglas escritas: por regla, cada cambio sustancial nace como una spec y un work item, se valida por etapas y registra una versión o una decisión explícita de no publicar; los flujos de la API, la app y el sitio etiquetan y publican cada versión nueva, mientras un portal de ingeniería público hecho con Docusaurus explica el sistema.
- Al 3 de julio de 2026 el repositorio de arquitectura reunía 13 specs, 74 work items en sus archivos de tareas en inglés (57 marcados como terminados) y 8 decisiones de arquitectura; la API y la versión web de la app solo se desplegaban en desarrollo, y nada de esto mide usuarios ni tiempo ahorrado.
| Producto | Un rastreador de portafolio personal de solo lectura: importa estados de cuenta y confirmaciones de operaciones, suma datos de mercado diarios, calcula métricas con desgloses auditables y muestra información descriptiva. No da consejos, no envía órdenes, no mueve dinero ni custodia activos. |
|---|---|
| Repositorios | 7 activos, coordinados desde portfolio-architect; solo portfolio-docs es público. Un repositorio de contratos compartidos quedó diferido. |
| Stack | Arquitectura: Markdown, ADR y specs con planes y listas de tareas. API: Express, TypeScript, Prisma, PostgreSQL y Zod. App: Expo, React Native, Expo Router y TanStack Query. Sitio: Next.js, Tailwind CSS y Cloudflare Pages. Base de datos: migraciones SQL y scripts de PowerShell. Infraestructura: Docker Compose. Documentación: Docusaurus. |
| Método | 13 specs, 74 work items en los archivos de tareas en inglés (57 marcados Done; las versiones en español suman 2 más, ambos terminados), 8 ADR y 12 skills de ciclo de vida, en el repositorio de arquitectura; estado del 3 de julio de 2026. |
| Versiones | Arquitectura 0.1.0, API 0.1.22, app 0.1.28, base de datos 0.1.0, infraestructura 0.1.0, sitio 0.1.5 y documentación 0.1.0. Fuente: version-manifest.yml, último release el 3 de julio de 2026. |
| Enlaces públicos | El portal de ingeniería, también en español, la web del producto y el repositorio de documentación. El 16 de noviembre de 2026 ambos sitios respondían 200 (observación pública); la configuración del sitio redirige / a su versión en español. |
| IA en ejecución | Sí, una pieza: un modelo de lenguaje servido en local con Ollama responde un chat descriptivo. La API filtra el contexto por usuario y portafolio, y bloquea los pedidos de consejo de compra o venta antes de llamarlo. |
| Mis declaraciones | Portfolio Tracker es un proyecto personal mío, no un trabajo para clientes ni para mi empleador; el estándar AI-Driven Development que los repositorios adoptaban por fases es mi propio método; Codex es el agente que implementa, y Ollama ejecuta el modelo local del producto. Fuente: declaración mía del 16 de noviembre de 2026. |
Qué es Portfolio Tracker y qué no es
Portfolio Tracker importa estados de cuenta mensuales y confirmaciones de operaciones desde los PDF de un bróker, junto con precios diarios ajustados de un proveedor de datos de mercado. Calcula inversión, capital neto, ingresos, egresos, valor de mercado y rendimiento, cada uno con el desglose de filas que respalda la cifra, y lo muestra en una app para Android y la web.
Su límite está escrito en cada repositorio: el producto es de solo lectura. No da asesoría financiera ni recomendaciones, no ejecuta operaciones, no enruta órdenes, no mueve dinero ni custodia activos. Si falta un estado de cuenta o un precio, muestra Pending o Partial en lugar de tomar prestado el valor de otro periodo.
Las reglas de datos van en la misma línea: los identificadores de usuario, portafolio y cuenta de bróker son UUID, un número de cuenta completo nunca es clave ni se muestra, y las consultas sensibles deben filtrar por usuario y portafolio.
El portal de ingeniería
La pieza más visible es el portal de ingeniería, construido desde el repositorio público portfolio-docs. Muestra cómo encaja el sistema sin acceso a los repositorios privados: 13 páginas por idioma, en inglés y también en español, escritas en Markdown con Docusaurus e ilustradas con diagramas Mermaid. Cubre:
- Arquitectura: la visión general del sistema, el mapa de repositorios, el flujo de datos, los puntos de integración y el flujo del método.
- Seguridad: la visión de seguridad, el manejo de datos y la postura de cumplimiento.
- Guías: primeros pasos y la hoja de ruta, además de preguntas frecuentes y un glosario.
El portal se construye como código. Un flujo de GitHub Actions lo compila en cada pull request y lo publica en GitHub Pages desde main. La configuración de Docusaurus fija onBrokenLinks: 'throw', así que un enlace interno roto hace fallar el build en vez de llegar al sitio. Un segundo flujo, también sobre main, genera una copia de las páginas en Markdown y la sube a la wiki del repositorio.
Lo que deja fuera es deliberado. Su propia declaración de alcance excluye runbooks internos, secretos, detalles privados de infraestructura y datos financieros de usuarios, sus propias reglas prohíben publicar secretos, IP internas o URL privadas, y la spec que lo gobierna admite conceptos de la API y de integración sin hosts privados. Nada lo sincroniza solo con los demás repositorios: una página pública cambia mediante un work item, como cualquier cambio, y por eso puede quedarse atrás (mira lo que esto no demuestra).
Arquitectura en siete repositorios
Cada repositorio tiene un papel, su propio AGENTS.md con las reglas que un agente lee primero, un changelog y una versión:
portfolio-architect: la memoria operativa y el punto de coordinación. Specs, work items, ADR, skills y el manifiesto de versiones, en Markdown; sin código del producto.portfolio-api: autenticación, importaciones, cálculos, dashboard y chat, con Express, TypeScript, Prisma, PostgreSQL y Zod.portfolio-mobile: la app para Android y la web, con Expo, React Native, Expo Router, TypeScript y TanStack Query.portfolio-web: la web comercial, con Next.js, TypeScript y Tailwind CSS, exportada como páginas estáticas a Cloudflare Pages. Muestra pantallas de demostración y no consulta la API.portfolio-db: migraciones SQL, datos semilla de desarrollo y scripts de respaldo y restauración en PowerShell.portfolio-infrastructure: la orquestación local con Docker Compose: PostgreSQL, la API, SonarQube, Ollama y la observabilidad.portfolio-docs: el portal público, con Docusaurus.
En ejecución, el camino es corto. La app solo habla con la API. La API lee y escribe en PostgreSQL, toma los precios diarios ajustados del proveedor de datos de mercado y consulta el modelo local para el chat. La app no toca la base de datos ni el modelo, y el runtime del modelo no tiene acceso a la base: la API arma el contexto que le entrega.
Las decisiones duraderas quedan en ADR. Hay 8, todas aceptadas:
- 0001, registrar las decisiones de arquitectura, y 0002, la infraestructura orquesta el entorno local (30 de mayo de 2026).
- 0003, trazabilidad del backlog en GitHub; 0004, hoja de ruta y excepciones del método; 0005, tren de releases y versionado; 0006, puertas de calidad y seguridad; y 0007, idiomas de la documentación (31 de mayo de 2026).
- 0008, gobierno de la orquestación de agentes (4 de junio de 2026).
El ciclo de vida: de un requerimiento a una versión desplegada
Este es el núcleo del método: el estándar AI-Driven Development que los repositorios adoptaban por fases y que, según declaré el 16 de noviembre de 2026, es mío. Casi todos los pasos tienen una skill de ciclo de vida que el agente carga antes de actuar.
- PROPIETARIO · REQUERIMIENTOPlanteo una necesidad: una funcionalidad, un error o un cambio en el método.
- SPECCodex la clasifica y escribe
spec.md(con su versión en español cuando corresponde): escenarios de uso, criterios de éxito, alcance, límite del producto y una evaluación de cumplimiento. - PLAN Y WORK ITEMS
plan.mdytasks.md: cada work item recibe criterios de aceptación en formato Given/When/Then, dependencias, un repositorio de destino y un issue de GitHub, y pasa aReadysolo cuando todo eso está completo. - REPARTO POR REPOSITORIOEl trabajo que abarca varios repositorios se convierte en una tarea hija y un pull request por repositorio; el repositorio de arquitectura los coordina, pero no mezcla su código.
- VALIDACIÓN POR ETAPASLa comprobación más pequeña que sirva mientras se corrige, las comprobaciones completas del repositorio cuando ya está estable y SonarQube local una vez antes del pull request, cuando está disponible; el flujo de GitHub Actions de cada repositorio vuelve a correr sobre el pull request.
- DECISIÓN DE VERSIÓNCada pull request registra una versión SemVer aún no publicada o una decisión explícita de no publicar, se abre como borrador y me pide revisión.
- RELEASE COORDINADOEn la API, la app y el sitio, tras la fusión en
mainel flujo crea la etiqueta de versión y el release de GitHub; un pull request complementario registra la nueva versión enversion-manifest.yml. - DESPLIEGUELa nueva versión llega a su entorno: la API y la app, a desarrollo; el sitio, a Cloudflare Pages, y el portal, a GitHub Pages.
- RETROSPECTIVACuando la pido, una retrospectiva sin culpables convierte una lección en una regla escrita, mediante un work item y un pull request nuevos si los anteriores ya se fusionaron.
La numeración une todo. Una spec es NNN (por ejemplo, 011), un work item es NNN-MMM (011-001) y una tarea hija en un repositorio es NNN-MMM-XX (003-015-01); la rama lleva el mismo número. El estado de un work item (Ready, In Progress, Active, Review, Done, Blocked o Deferred) vive en el tasks.md local; el issue de GitHub solo da trazabilidad al pull request.
La definición de terminado también está escrita. Antes de abrir un pull request, el trabajo debe estar validado; una funcionalidad para el usuario debe funcionar de punta a punta entre infraestructura, API e interfaz, o la capa pendiente debe quedar como tarea hija Blocked o Deferred con su motivo; y el work item se marca Done en el último commit del pull request. Un work item padre solo se cierra cuando sus tareas hijas lo están.
Las versiones se coordinan con un único manifiesto. Su encabezado, al 3 de julio de 2026:
system_version: "0.1"
repos:
architecture: "0.1.0"
api: "0.1.22"
mobile: "0.1.28"
database: "0.1.0"
infrastructure: "0.1.0"
web: "0.1.5"
docs: "0.1.0"
shared: "planned"
site: "superseded-by: portfolio-web"
compatibility: "Active repos share MAJOR.MINOR during coordinated releases; PATCH may vary independently."Puertas de calidad
Los 7 repositorios corren un flujo de GitHub Actions en los pull requests hacia main. En la API, tras instalar dependencias y generar el cliente de Prisma, el trabajo de comprobaciones ejecuta estos pasos:
- name: Lint
run: npm run lint
- name: Test
run: npm test
- name: Build
run: npm run build
- name: Runtime dependency audit
run: npm run audit -- --omit=dev- Las notas del release salen del changelog. El release de la API falla si
CHANGELOG.mdno tiene sección para esa versión, y el flujo del sitio rechaza un pull request cuya versión ya está etiquetada. - Dependencias. El CI de la API audita las dependencias de ejecución; la ADR 0006 delega las alertas en Dependabot (registradas como activas en la API) y deja diferidos el análisis de licencias y las pruebas dinámicas de seguridad.
- SonarQube, solo en local. El análisis estático corre en SonarQube en la máquina local de desarrollo, y el script de validación falla si no se supera la puerta de calidad. Por regla, los flujos alojados no asumen acceso a esa máquina, así que el CI alojado no lo ejecuta.
- Accesibilidad. La versión web de la app y la web comercial se revisan con axe y Playwright según WCAG 2.2 AA: las infracciones críticas o graves hacen fallar el trabajo y las moderadas o menores solo se registran. El informe en JSON y HTML se adjunta a cada release web.
- TypeScript estricto. La API, la app y el sitio compilan con
strictactivado.
Entrega y operación
La API muestra el camino completo. Cuando las comprobaciones pasan en main, el flujo crea la etiqueta SemVer (sin volver a publicar una versión ya lanzada), un release de GitHub con notas tomadas del changelog y la imagen, etiquetada con la versión, en el registro de contenedores de GitHub. Un último trabajo, en un runner autoalojado, la despliega en el entorno de desarrollo: aplica las migraciones de la base desde la nueva imagen antes de recrear el contenedor, se detiene si fallan y espera a que el contenedor esté sano.
La app tiene su propio flujo: en main publica el release de la exportación web de Expo y su imagen, lanza un build de vista previa para Android y despliega la versión web en desarrollo. Lo que llega a la rama preview sale como actualización inalámbrica en el canal preview, sin build nativo nuevo. El sitio despliega su exportación estática en Cloudflare Pages.
La observabilidad también es local. Un perfil opcional de portfolio-infrastructure levanta un OpenTelemetry Collector que envía trazas a Tempo, logs a Loki y métricas a Prometheus, todo consultable desde Grafana; por regla, no exporta nada a servicios alojados.
El papel de la IA
Codex es el agente que implementa (declaración mía del 16 de noviembre de 2026), y trabaja bajo reglas escritas para él. El AGENTS.md de cada repositorio es su punto de entrada; en el de arquitectura, dos de las reglas de trabajo dicen:
- Propose a short plan before editing, keep changes small, and follow: 1 task = 1 module = 1 PR.
- Use `codex/NNN-MMM-short-slug` branches, or `codex/NNN-MMM-XX-short-slug` for repo/module child tasks.La coordinación sigue un modelo escrito. La ADR 0008, del 4 de junio de 2026, convierte al repositorio de arquitectura en el Master Agent y a cada repositorio de destino en un Sub-Agent:
The Master Agent owns requirements, specs, Work Item decomposition, dependency ordering, delegation, status aggregation, and architecture memory. Sub-Agents own implementation inside their repo, validation, repo docs, and PR artifacts.
El Master Agent se encarga de los requerimientos, las specs, la descomposición en work items, el orden de dependencias, la delegación, la consolidación de estados y la memoria de arquitectura. Los Sub-Agents se encargan de la implementación dentro de su repositorio, la validación, la documentación del repositorio y los artefactos del PR.
Es una regla documentada, no un registro de agentes trabajando en paralelo: el mismo AGENTS.md prevé que, sin herramientas de sub-agentes, el agente documente el plan de delegación, ejecute solo la tarea del repositorio actual y deje el resto con un estado explícito. Las 12 skills de ciclo de vida son archivos del repositorio de arquitectura, y una, portfolio-release-version, debe cargarse al inicio de cada ejecución del agente.
A diferencia de los productos de mis otras notas, este llama a un modelo en ejecución: Ollama sirve un modelo de lenguaje local para un chat descriptivo sobre el portafolio del usuario. El resguardo ocurre en la API, antes de que el modelo vea nada: clasifica la pregunta con reglas deterministas y, si pide saber si comprar, vender, mantener, operar, invertir o rebalancear, responde con una negativa fija, la registra y no invoca el modelo. Si no, arma un contexto acotado y saneado con los servicios de dashboard y de datos, filtrado por usuario y portafolio, y lo envía al modelo mediante una API compatible.
Lo que decido yo
Por regla, el agente trabaja dentro de un alcance que fijo yo. Estas decisiones siguen siendo mías:
- Requisitos y alcance. El análisis empieza cuando planteo trabajo nuevo, y las specs escriben sus escenarios desde el punto de vista del dueño del proyecto; el agente lo convierte en specs, planes y work items.
- Revisión de cada pull request. Por regla, el agente abre el pull request como borrador y me solicita como revisor cuando GitHub lo permite. Los archivos no registran quién hace cada fusión, y la protección de ramas está bloqueada por el plan gratuito de GitHub para repositorios privados: la revisión es una regla, no un candado técnico.
- Prerrequisitos manuales. Algunos pasos me necesitan: dominios estables, la huella de firma de Android, los secretos de cada entorno y las pruebas en un dispositivo físico. La spec del inicio de sesión con passkeys los enumera como prerrequisitos manuales; al 3 de julio de 2026 los valores de desarrollo ya estaban y la validación de punta a punta seguía bloqueada por cambios sin fusionar y una prueba en un dispositivo físico.
Lo que esto no demuestra
Al 3 de julio de 2026:
- No consta publicación en tiendas. Android se distribuye en builds internos de vista previa.
- Sin entorno de producción para la API ni la app. La API y la versión web de la app solo se despliegan en desarrollo; el repositorio de base de datos describe staging y producción sin implementarlos. Solo la web comercial es pública.
- SonarQube es solo local. El CI alojado no lo ejecuta.
- El portal va por detrás del repositorio de arquitectura. Su mapa de repositorios aún muestra la web pública como diferida, no menciona
portfolio-webni el trabajo de las specs 009 a 013, y su página del flujo enumera 10 de las 12 skills. - Pendientes visibles en los propios archivos. El archivo de prueba dedicado al aislamiento entre usuarios es un marcador que compara un texto fijo, aunque otras pruebas de rutas comprueban que las consultas lleven los filtros de usuario y portafolio; la migración inicial activa la seguridad a nivel de fila en 10 tablas, pero el repositorio no define políticas; los builds de iOS están inactivos a propósito, y el umbral de cobertura del 80 % de la app está en Vitest, pero el CI corre las pruebas sin cobertura.
- Sin cifras de usuarios ni de tiempo ahorrado. No se dan ni se afirman.
- No es asesoría financiera. El producto describe registros; no recomienda nada.
Qué sigue
El trabajo pendiente ya está escrito como work items: terminar el inicio de sesión con passkeys (fusionarlo, desplegarlo y probarlo en un dispositivo físico), migrar la API módulo por módulo a Clean Architecture con un patrón Result y mantener al día el portal público bajo la spec 008. Si quieres conversar sobre esta forma de trabajar, escríbeme.
Cómo se escribió esta nota
Esta nota se redactó con Claude Code a partir de copias de solo lectura de los siete repositorios de Portfolio Tracker: los últimos commits de cinco de ellos son del 3 de julio de 2026, y los de portfolio-web y portfolio-docs, del 19 de junio de 2026. Los datos que no están en los repositorios se marcan, en la frase o en la tabla del inicio, como declaraciones mías del 16 de noviembre de 2026 o como observaciones públicas de ese día. Cada afirmación se rastreó hasta su fuente antes de publicarla. No se nombra ningún modelo de IA ni versión de las herramientas de IA, por regla editorial de este sitio.