Workflow CDAID — Practicas de Desarrollo Asistido por IA¶
SDD: Spec-Driven Development¶
Cada cambio se implementa a traves de un SPEC formal:
Ciclo de vida del SPEC¶
1. Planning (analisis del hallazgo/feature)
└── Se crea SDD_SPEC con ID, criterios, archivos, lineas exactas
2. Implementacion (atomica)
└── Agente lee SPEC → TDD → commit con hash
3. Auditoria (cotejo spec vs codigo)
└── 8 puntos → CONFORME / DIVERGENCIA / DEFECTO
4. Registro (en resumen del sprint)
└── Tabla de progreso con commit, tests, metricas
Formato de ID de SPEC¶
SPEC-S{sprint}-{fase}{numero}
Ejemplos:
SPEC-S01-A1 → Sprint 1, Fase A, item 1
SPEC-S03-B2 → Sprint 3, Fase B, item 2
S05-01 → Sprint 5, item 01 (formato simplificado)
Protocolo de Auditoria SDD (8 puntos)¶
| Punto | Verifica |
|---|---|
| P1 | DTOs — frozen, campos, JSON serializable |
| P2 | Metodos — firma, Result[T,E], paths Success/Failure |
| P3 | Backward compat — callers no rotos |
| P4 | DI/Container — registrado correctamente |
| P5 | Interfaces — delegan correctamente |
| P6 | Tests — Success, Failure, cantidad, coverage |
| P7 | Code smells — Feature Envy, Duplicate Code eliminados |
| P8 | Patterns — Facade, DI, ROP implementados |
Clasificacion de divergencias¶
| Tipo | Significado | Accion |
|---|---|---|
| CONFORME | Codigo = spec | Ninguna |
| DIVERGENCIA JUSTIFICADA | Difiere pero es mejor | Documentar razon |
| DIVERGENCIA MENOR | Difiere en nombre/tipo | Evaluar impacto |
| DEFECTO | No cumple intencion | Corregir obligatoriamente |
Templates:
docs/templates/TEMPLATE_SDD_SPEC.md,docs/templates/TEMPLATE_AUDITORIA.md
TDD Formal (test-first con agentes)¶
Para features nuevas, seguir este orden estrictamente:
- Humano define criterios de aceptacion
- Agente escribe tests que deben FALLAR (
pytest -xconfirma fallo) - Commit tests por separado
- Agente implementa codigo hasta que tests pasen
- Commit codigo
- Gate: cobertura no puede bajar (
pytest --cov>= baseline)
Por que: Previene que el agente escriba tests que verifican comportamiento roto.
Checklist Pattern¶
Para sprints o tareas con >3 items, crear checklist operativo:
## Sprint N — Checklist
- [x] SPEC-SN-A1: Item completado — commit abc1234
- [ ] SPEC-SN-A2: Item pendiente
- [ ] SPEC-SN-B1: Item pendiente
Actualizar en tiempo real durante la sesion. No es documentacion post-hoc sino herramienta de tracking activo.
Compactacion Deliberada¶
No depender de la auto-compactacion (83.5% de capacidad). Compactar manualmente:
/compactal terminar cada fix/feature/clearal cambiar de sprint/planning/tema/compact focus on [tema actual]al iniciar tarea compleja
Las Compact Instructions de CLAUDE.md garantizan que se preservan las reglas criticas.
Hooks como Quality Gates¶
Los hooks de .claude/settings.json ejecutan quality gates en cada operacion del agente:
- PostToolUse (Edit/Write):
ruff check --fix+ruff formaten archivos.py - Deteccion inmediata de errores de estilo/lint vs esperar al pre-commit
- Si un hook falla, investigar la causa — no desactivar el hook
Verificacion Pre-Commit¶
Antes de cada commit, verificar:
pytest -x # Tests pasan
ruff check src/ # Sin errores lint
ruff format --check src/ # Formato correcto
mypy src/ --strict # Type checking (para logica de negocio)
Multi-Claude (escritor + revisor)¶
Para features complejas, usar dos instancias de Claude Code:
- Instancia A (escritor): implementa feature en worktree aislado
- Instancia B (revisor): revisa codigo con
code-revieweragent, ejecuta tests - Humano: aprueba merge al branch principal
Agentes disponibles en .claude/agents/:
| Agente | Rol | Permisos | Modelo |
|---|---|---|---|
| code-reviewer | Revisa calidad codigo | Solo lectura | sonnet |
| test-generator | Genera tests | Escribe solo en tests/ | haiku |
| doc-auditor | Verifica sync docs/codigo | Solo lectura | haiku |
| security-scanner | Audita seguridad | Solo lectura + Bash(limitado) | haiku |
| senior-architect | Decisiones arquitectonicas | Full access | sonnet |
| python-pro | Python idiomatico avanzado | Full access | haiku |
| ai-engineer | LLM, RAG, embeddings | Full access | haiku |
| prompt-engineer | Optimizacion de prompts | Write/Edit | haiku |
| refactor-planner | Identifica deuda tecnica | Solo lectura | haiku |
| dependency-checker | Audita dependencias | Lee + Bash(auditoria) | haiku |
| performance-analyzer | Profiling, bottlenecks | Lee + Bash(profiling) | haiku |
| api-reviewer | Diseno REST/GraphQL | Solo lectura | haiku |
| db-auditor | Queries, schema, indices | Solo lectura | haiku |
| onboarding-guide | Explica codebase | Solo lectura | haiku |
Trazas de Delegacion¶
Al documentar plannings/sprints, registrar decisiones de delegacion:
## Trazas de Delegacion
| Decision | Propuesta IA | Aprobacion Humano | Notas |
|----------|-------------|-------------------|-------|
| Refactorizar X | Si, 3 opciones | Opcion 2 aprobada | Opcion 1 sobre-ingenierada |
| Agregar test Y | Si | Si | — |
| Eliminar modulo Z | No, humano propuso | — | Codigo muerto confirmado |
Scope Attenuation (permisos graduados)¶
Los sub-agentes tienen permisos restringidos segun su rol:
| Agente | Read | Grep | Write | Edit | Bash | Modelo |
|---|---|---|---|---|---|---|
| code-reviewer | si | si | NO | NO | NO | sonnet |
| doc-auditor | si | si | NO | NO | NO | haiku |
| security-scanner | si | si | NO | NO | limitado | haiku |
| test-generator | si | si | tests/ | NO | si | haiku |
| refactor-planner | si | si | NO | NO | NO | haiku |
| dependency-checker | si | si | NO | NO | auditoria | haiku |
| performance-analyzer | si | si | NO | NO | profiling | haiku |
| api-reviewer | si | si | NO | NO | NO | haiku |
| db-auditor | si | si | NO | NO | NO | haiku |
| onboarding-guide | si | si | NO | NO | NO | haiku |
| senior-architect | si | si | si | si | si | sonnet |
| python-pro | si | si | si | si | si | haiku |
| ai-engineer | si | si | si | si | si | haiku |
| prompt-engineer | si | si | si | si | NO | haiku |
Principio: cada agente recibe los permisos minimos necesarios para su tarea.
Skills de Proyecto¶
Skills reutilizables en .claude/skills/:
| Skill | Activacion | Proposito |
|---|---|---|
| systematic-debugging | Bugs, errores, crashes | 4 fases root-cause-first |
| refactoring | Code smells, mejorar codigo | 22 smells + 66 tecnicas |
| design-patterns | Decisiones de diseno | 22 patrones GoF + SOLID |
| python-testing-patterns | Tests, fixtures, mocking | pytest + TDD completo |
| _template-domain-skill | (template) | Crear skills especificos |
Notebooks como Quick Wins¶
Patron para explorar antes de implementar:
1. Crear notebook en docs/notebooks/NN_tema/
2. Experimentar con datos reales (quick win visible)
3. Validar que funciona en entorno aislado
4. Escribir tests basados en lo aprendido
5. Migrar codigo limpio a src/ (refactorizar)
6. Marcar notebook como referencia o archivar
Guia completa:
docs/notebooks/README.md