Workflow CDAID — Prácticas de Desarrollo Asistido por IA¶

TDD Formal (test-first con agentes)¶

Para features nuevas, seguir este orden:

Humano define criterios de aceptación
Agente escribe tests que deben FALLAR (pytest -x confirma fallo)
Commit tests por separado
Agente implementa código hasta que tests pasen
Commit código
Gate: cobertura no puede bajar (pytest --cov >= baseline)

Por qué: Previene que el agente escriba tests que verifican comportamiento roto. La investigación reporta resultados "dramáticamente mejores" con TDD + agentes.

Checklist Pattern¶

Para sprints o tareas con >3 items, crear checklist operativo:

## Sprint N — Checklist

- [x] Item completado
- [ ] Item pendiente
- [ ] Item pendiente

Actualizar en tiempo real durante la sesión. No es documentación post-hoc sino herramienta de tracking activo.

Compactación Deliberada¶

No depender de la auto-compactación (83.5% de capacidad). Compactar manualmente:

/compact al terminar cada fix/feature
/clear al cambiar de sprint/planning/tema
/compact focus on [tema actual] al iniciar tarea compleja

Hooks como Quality Gates¶

Los hooks de .claude/settings.json ejecutan quality gates en cada operación del agente, no solo al commit:

PostToolUse (Edit/Write): ruff check --fix + ruff format en archivos .py
Detección inmediata de errores de estilo/lint vs esperar al pre-commit
Si un hook falla, investigar la causa — no desactivar el hook

Verificación Pre-Commit¶

Antes de cada commit, verificar:

pytest -x                    # Tests pasan
ruff check src/              # Sin errores lint
ruff format --check src/     # Formato correcto

Para cambios en lógica de negocio, agregar también:

mypy src/sherlock_docs/       # Type checking

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 código con code-reviewer agent, ejecuta tests
Humano: aprueba merge al branch principal

Agentes disponibles en .claude/agents/: - security-scanner — audita seguridad (solo lectura) - doc-auditor — verifica sincronización docs/código (solo lectura) - test-generator — genera tests (solo escribe en tests/) - code-reviewer — revisa código (solo lectura, modelo sonnet)

Trazas de Delegación¶

Al documentar plannings/sprints, registrar decisiones de delegación:

## Trazas de Delegación

| Decisión | Propuesta IA | Aprobación Humano | Notas |
|----------|-------------|-------------------|-------|
| Refactorizar X | Sí, 3 opciones | Opción 2 aprobada | Opción 1 sobre-ingenierada |
| Agregar test Y | Sí | Sí | — |
| Eliminar módulo Z | No, humano propuso | — | Código muerto confirmado |

Esto permite trackear: - Qué propuso la IA vs qué aprobó el humano - Decisiones rechazadas y razón - Ratio de aceptación de propuestas IA

Scope Attenuation (permisos graduados)¶

Los sub-agentes tienen permisos restringidos según su rol:

Agente	Read	Grep	Write	Edit	Bash	Modelo
security-scanner	si	si	NO	NO	limitado	haiku
doc-auditor	si	si	NO	NO	NO	haiku
test-generator	si	si	tests/	NO	si	haiku
code-reviewer	si	si	NO	NO	NO	sonnet

Principio: cada agente recibe los permisos mínimos necesarios para su tarea.