Lineamientos y procesos de IA — CumplePLD

Documento interno · enfoque exclusivo en cómo trabajamos con IA (Claude Code) — no describe el producto. Última edición: junio 2026.

1. Contexto y restricciones

2. Economía de tokens (principio transversal)

Cada decisión de tooling se evalúa por una pregunta: ¿cuántos tokens consume por unidad de valor?

• Sin MCPs verbosos. El MCP de ClickUp/GitHub trae payloads grandes en cada turno. gh issue create / gh pr create hacen lo mismo gastando una fracción.
• Grafo antes que grep. Un graphify query devuelve un subgrafo acotado en lugar de volcar archivos enteros al contexto (§6).
• Carga bajo demanda. plan/INDEX.md y las reglas de CLAUDE.md indican no cargar la base de conocimiento completa por defecto; solo el archivo que la tarea concreta necesita.
• Modelo según fase. Subagentes de solo lectura (Explore) corren en haiku; el diseño de propuestas openspec recomienda Opus. Se elige el modelo más barato que sirva.
• Compactar entre fases de OpenSpec. Concretamente entre opsx:propose y opsx:apply corremos /compact: la fase de propuesta acumula mucho contexto de diseño que la fase de implementación no necesita arrastrar. Compactar ahí evita el costo de >150k tokens de contexto.
• Tickets chicos directos. Un ticket S/XS con spec completa se implementa directo, sin subagente de planificación; el peso pesado se reserva para features L/XL con arquitectura genuinamente incierta.

3. Proceso de creación de tickets

3.1 De dónde salen los tickets

No inventamos trabajo. Cada ticket se deriva de dos fuentes:

• El PRD del cliente — qué necesita el negocio.
• Los steps del MVP que armó nuestro manager (Pablo) — el orden y los hitos de entrega.

Cruzar ambos nos dio un flujo para priorizar y dividir tareas importantes que dependen unas de otras. El número de ticket es el orden de construcción (número menor = se hace primero), alineado a la secuencia de plan/knowledge/v10-gaps.md y al ROADMAP.

3.2 Dos tracks con dependencia explícita

Cada feature se parte en dos tickets:

El ticket de UI depende de su ticket de API: primero se hace el API. Esto evita construir contra "endpoints fantasma" que todavía no existen.

3.3 Anatomía de un ticket

Cada ticket es un archivo Markdown con metadata fija. Ejemplo real (API-46):

# API-46 — screening auto-close: doc fix + audit-assertion test

**Status:** ✅ done
**GitHub issue:** [#189](https://github.com/Clarolab-Junin/cumplepld/issues/189)
**Size:** XS
**Type:** Bug (doc) + Test gap
**Spotted during:** QA validation of API-44
**Parent:** API-44

## Problem        ← qué está mal / qué falta, con refs a file:línea
## Scope          ← qué se va a tocar, acotado
## Acceptance criteria   ← checklist verificable (incluye `make test` green)
## References     ← rutas exactas a código, contratos, specs, QA report

La regla clave: las referencias apuntan a archivo:línea. Eso le permite a Claude ir directo al punto sin explorar a ciegas (otra vez, economía de tokens).

3.4 Ticket ↔ GitHub issue (al mismo tiempo)

El procedimiento, solo con gh CLI (sin MCP):

gh issue create --title "API-46: screening auto-close doc fix" --body "..."

1. Crear el issue con contexto, criterios de aceptación y link al archivo del ticket.
2. Agregar - **GitHub issue:** #NN al archivo del ticket.
3. Agregar el número de issue a la fila del README.md del índice correspondiente.

Al empezar a trabajar un ticket, se autoasigna el issue: gh issue edit <N> --add-assignee @me.

4. Flujo de ramas y PRs (sin tablero, sin CI)

• Nunca commit/push directo a dev ni main — ni siquiera para docs. Siempre rama desde dev.
• Los PR apuntan a dev (--base dev); main se promueve aparte.
• Cada PR linkea su issue con Closes #N / Refs #N. Ojo: como mergeamos a dev (no a la branch default), GitHub no autocierra el issue — se cierra a mano después del merge confirmado.
• Nunca cerrar un issue antes de que su PR esté mergeado.

5. OpenSpec — especificación dirigida por IA

Usamos OpenSpec para que los cambios pasen por un flujo de artefactos antes de tocar código. Vive en openspec/.

5.1 Configuración

5.2 Flujo de trabajo

Skills dedicadas manejan cada fase: opsx:propose → opsx:apply → opsx:archive (y opsx:explore / opsx:sync de apoyo).

• Propose: genera propuesta + specs delta + design + tasks de una. El schema recomienda Opus para la fase de propuesta (más capaz para diseño).
• Apply: implementa las tasks del change.
• Archive: finaliza y mueve el change a archive/.

5.3 Loop benéfico: el plan genera tickets nuevos

5.4 Mantener el fork al día: /update-openspec

Nuestro schema clarolab-workflow es un fork del workflow base de OpenSpec (@fission-ai/openspec, antes spec-driven). Como cualquier fork, el upstream sigue mejorando después de que lo bifurcamos. La skill /update-openspec es la herramienta para mantener ese fork sincronizado — no es una skill de "consulta de conocimiento", es de mantenimiento de infraestructura.

Qué hace, paso a paso:

1. openspec update — regenera los archivos de instrucciones del paquete para la versión instalada.
2. Ubica el commit del fork (snapshot del upstream al momento de bifurcar) y la ruta del upstream actual en el store de pnpm.
3. Diff de mejoras upstream: compara el upstream-al-forkear contra el upstream-de-hoy → qué mejoró el paquete desde que lo forkeamos.
4. Diff de nuestra divergencia: compara el baseline del fork contra nuestro schema actual → qué customizamos nosotros.
5. Merge guiado: muestra los dos diffs lado a lado para incorporar las mejoras upstream sin pisar nuestras customizaciones.

El resultado: el fork se beneficia de las nuevas versiones de OpenSpec de forma controlada, manteniendo nuestras reglas propias (ej. la recomendación de Opus para la fase de propuesta).

6. Graphify — grafo de conocimiento del repo

El repo tiene un grafo de conocimiento persistente en graphify-out/ (god nodes, detección de comunidades, relaciones cross-file). Sirve para responder preguntas de arquitectura devolviendo un subgrafo acotado en lugar de volcar archivos enteros al contexto.

6.1 Costo inicial vs. mantenimiento

6.2 Cómo lo usamos

• Para preguntas de código: primero graphify query "<pregunta>"; graphify path "<A>" "<B>" para relaciones; graphify explain "<concepto>" para algo puntual.
• Para navegación amplia: graphify-out/wiki/index.md en vez de browsear el código crudo.
• GRAPH_REPORT.md solo para revisión de arquitectura amplia.
• Tras modificar código: make graph y commitear graph.json + GRAPH_REPORT.md.

6.3 Forzado por hooks

En .claude/settings.json hay hooks PreToolUse que, cuando existe graph.json, obligan a orientar con graphify antes de hacer grep o leer archivos de código. Si Claude intenta grepear o leer un .py/.ts directo, el hook inyecta un recordatorio mandatorio de usar graphify primero. Esto baja el consumo de tokens de exploración de forma automática, incluso en subagentes.

7. Superpowers y skills

Usamos Superpowers (framework de skills) más skills propias del proyecto. La regla: si una skill aplica, se usa antes de responder.

Las skills "rígidas" (TDD, debugging sistemático) se siguen al pie de la letra; las "flexibles" se adaptan. La prioridad: skills del usuario/proyecto > skills de Superpowers > comportamiento por defecto.

8. Sin CI: qué implica y cómo lo compensamos

Lo que la suple:

• Todo corre en Docker vía make (make test, make migrate, make simulate...). Postgres únicamente — no existe fallback a SQLite y no se agrega.
• Git hooks locales (Husky), que actúan como mini-CI:

  Hook	Cuándo	Qué hace
  .husky/pre-commit	cada commit	UI: pnpm lint-staged + typecheck
  .husky/pre-push	cada push	Backend: make test-push (levanta el stack, corre pytest, lo baja)

• Gate pre-PR (en orden, no se saltea): capturar aprendizajes en docs → checklist de docs → checklist de fixtures → code review del diff → recién ahí commit/push/PR.
• Fixtures como verificación de capacidad: cualquier cambio de capacidad de la API actualiza make simulate / make populate en el mismo commit. Sin CI, los fixtures son la prueba viva de que el endpoint funciona end-to-end.
• Docs en el mismo commit que el comportamiento: los contratos en plan/api/contracts/ son la única fuente de verdad de la API implementada. Sirven para sincronizar la API con el frontend: cuando Claude cablea una pantalla de UI, lee el contrato en vez del código del backend — más barato en tokens y más estable que parsear los controllers. Por eso el contrato tiene que reflejar el código en cada commit.

9. Reglas que le metimos a Claude

Las reglas viven en archivos versionados y se cargan automáticamente:

Qué NO tocar / qué evitar

• No agregar fallback a SQLite — Postgres only.
• No commitear/pushear a dev ni main.
• No construir contra endpoints de specs/tickets sin verificarlos en los contratos.
• No correr graphify hook install (rompe al equipo).
• No cargar la base de conocimiento completa por defecto.
• No cerrar issues antes del merge.

10. Cómo sería esto con tokens y presupuesto infinitos en construcción

Sección viva — la vamos completando juntos. Idea: registrar qué decisiones tomamos por la restricción de tokens, y qué haríamos si esa restricción desapareciera.

Qué conservaríamos igual (no es deuda — es así por elección)

Qué mejoraríamos

Preguntas abiertas para llenar entre los dos:
• ¿Cuánto de la calidad actual viene justamente de que los tokens escasos nos obligan a ser precisos?
• ¿Qué automatizaríamos primero si pudiéramos: CI, sync de issues, o rebuild del grafo?

Documento de proceso de IA · CumplePLD · mantener junto al código. Editar y versionar como cualquier otra doc del repo.