Conocimiento del proyecto - dstanziola/app16 GitHub Wiki

INSTRUCCIONES PARA CLAUDE - SISTEMA INVENTARIO v3.0

Proyecto: Sistema de Inventario Python
Nombre de la aplicación: COPY-INV Ubicación: D:\inventario_app2
Modelo: Claude Opus 4 — estilo formal, pensamiento extendido, temperatura 0.2, sin emojis
Objetivo: Desarrollar funcionalidades atómicas del sistema bajo metodología estructurada
Versión Instrucciones: 3.0 (2025-07-20)

CONFIGURACIÓN GENERAL

Arquitectura y Estándares

Arquitectura: Clean Architecture
Estilo de Código: PEP8 estricto
Principios: DRY, SOLID, KISS, YAGNI
Testing: TDD obligatorio, cobertura ≥ 95%
Validaciones: pytest, flake8, pylint, black, isort, mypy
Control de versiones: Git (commits atómicos, mensajes conventional: feat:, fix:, refactor:, docs:)
Documentación: Obligatoria en .md, changelog automático, backups cada milestone
Archivos del contexto en: "D:\inventario_app2\docs"

Restricciones Críticas

PROHIBIDO: Cambios no solicitados, modificaciones fuera del protocolo, side-effects ocultos
OBLIGATORIO: Seguir protocolo secuencial, validar antes de actuar, documentar decisiones

PROTOCOLO DE EJECUCIÓN - OBLIGATORIO Y SECUENCIAL

FASE 0: IDENTIFICACIÓN DE CONTEXTO (CRÍTICO)

A. Determinación del Tipo de Sesión

EVALUAR:
1. ¿Contiene el prompt palabras clave de continuación? 
   - "continuar", "seguir", "completar", "retomar", "desde donde"
2. ¿Se mencionan archivos específicos o tareas previas?
3. ¿Hay referencias a estados anteriores o funcionalidades parciales?

SI (1 O 2 O 3) = TRUE → SESIÓN DE CONTINUACIÓN
ELSE → NUEVA SESIÓN

B. Protocolo de Continuación (SI ES CONTINUACIÓN)

Identificar último estado:
- Buscar change_log.md (último entry)
- Revisar features_backlog.md (status: in_progress)
- Verificar archivos mencionados en el prompt
Validar integridad del contexto:
- Confirmar existencia de archivos mencionados
- Verificar consistencia entre documentación y código
- Detectar archivos truncados o incompletos

Generar resumen de estado:

ESTADO ANTERIOR DETECTADO:
- Tarea: [descripción]
- Fase completada: [X de Y]
- Archivos afectados: [lista]
- Pendientes: [lista específica]
- Riesgos identificados: [si aplica]

C. Protocolo de Nueva Sesión (SI ES NUEVA)

Cargar contexto mínimo obligatorio:
- architecture.md
- claude_instructions_v3.md (este archivo)
- features_backlog.md
- inventory_system_directory.md
- Requerimientos_Sistema_Inventario_v6_0.md
Cargar contexto adicional según tarea:
- Testing: app_test_plan.md, coverage_report.md
- Configuración: config_reference.md
- Seguridad: security_policy.md
- Comandos: claude_commands.md

FASE 1: VALIDACIÓN PREVIA AL DESARROLLO

A. Verificación de Duplicidad

PROCESO DE VALIDACIÓN:
1. Generar hash semántico de la funcionalidad solicitada
2. Comparar con entries en features_backlog.md (campo hash_semantic)
3. Buscar similitudes en inventory_system_directory.md
4. Si similitud > 80% → PAUSAR y solicitar confirmación

B. Análisis de Consistencia Nomenclatural

VALIDACIONES:
1. Verificar convenciones de naming contra architecture.md
2. Comprobar no conflicto con nombres existentes
3. Validar que el naming sugiera la funcionalidad real
4. Si inconsistencia detectada → PAUSAR y proponer corrección

FASE 2: DESARROLLO ATÓMICO

A. Diseño de Pruebas (TDD Estricto)

Crear pruebas específicas primero:
- Casos de éxito (happy path)
- Casos de error (edge cases)
- Casos límite (boundary conditions)
- Actualizar app_test_plan.md
Validar diseño de pruebas:
- ¿Cubren todos los requerimientos?
- ¿Son independientes entre sí?
- ¿Tienen assertions claros?

B. Implementación Mínima

Escribir código mínimo para pasar pruebas
Documentar cada decisión arquitectónica
Mantener atomicidad (una responsabilidad por función)

C. Validación de Calidad

CHECKLIST OBLIGATORIO:
□ flake8 sin errores
□ black aplicado correctamente
□ isort ordenamiento correcto
□ pylint score ≥ 9.0
□ mypy sin errores de tipo
□ pytest cobertura ≥ 95%
□ Documentación actualizada

FASE 3: INTEGRACIÓN Y DOCUMENTACIÓN

A. Commit Atómico

FORMATO DE COMMIT:
tipo(scope): descripción breve

Detalles:
- Cambios específicos realizados
- Archivos afectados: [lista]
- Tests agregados: [número]
- Cobertura actual: [porcentaje]
- Breaking changes: [si/no]

Refs: #issue_number

B. Actualización de Documentación

Actualizar change_log.md:

## [Fecha] - [Tipo de cambio]
- **Funcionalidad:** [descripción]
- **Archivos:** [lista]
- **Tests:** [cantidad] pruebas agregadas
- **Cobertura:** [porcentaje]
- **Tiempo:** [minutos invertidos]
- **Hash semántico:** [hash]

Actualizar inventory_system_directory.md:
- Ejecutar diff antes de modificar
- Agregar nuevas funciones/clases
- Actualizar dependencias
- Marcar cambios con timestamp
Actualizar features_backlog.md:
- Cambiar status: in_progress → completed
- Agregar métricas de desarrollo
- Actualizar estimaciones si es necesario

FASE 4: CHECKPOINT Y CONFIRMACIÓN

A. Generación de Checkpoint

CHECKPOINT AUTOMÁTICO:
Session ID: [timestamp-hash]
Tarea completada: [descripción]
Archivos modificados: [lista con hashes]
Estado del sistema: [funcional/parcial/en_desarrollo]
Próximo paso recomendado: [descripción]
Comando de continuación: [prompt exacto]

B. Solicitud de Confirmación

CONFIRMACIÓN REQUERIDA:
✓ Funcionalidad implementada según especificación
✓ Todas las pruebas pasan
✓ Documentación actualizada
✓ Sin regresiones detectadas

¿Proceder con siguiente funcionalidad o requiere ajustes?

REGLAS DE SEGURIDAD Y CALIDAD AMPLIADAS

Prohibiciones Absolutas

Modificar arquitectura sin autorización explícita
Crear funciones redundantes (validar hash semántico)
Cambiar nombres establecidos sin análisis de impacto
Introducir dependencias externas sin validación
Realizar commits con código que no pase todas las validaciones
Omitir o modificar pasos del protocolo
Crear side-effects no documentados

Obligaciones Críticas

Ejecutar diff antes de modificar cualquier .md
Solicitar confirmación ante ambigüedades
Mantener trazabilidad completa de cambios
Documentar decisiones arquitectónicas
Validar consistencia entre código y documentación
Generar backups automáticos en milestones

Sistema de Recovery

SI ERROR DETECTADO:
1. PAUSAR desarrollo inmediatamente
2. Documentar error en change_log.md
3. Evaluar impacto en funcionalidades existentes
4. Proponer estrategia de recovery:
   - Rollback al último checkpoint válido
   - Fix incremental con validación
   - Refactoring si es arquitectónico
5. Solicitar autorización antes de proceder

GESTIÓN DE TOKENS Y CONTINUIDAD AVANZADA

MANTENER ACTIVADO Sistema de persistencia de contexto mediante archivos de estado.

Detección de Límites

SI contenido > 80% límite de tokens:
1. Finalizar en punto lógico seguro
2. Generar checkpoint completo
3. Crear prompt de continuación exacto:

"CONTINUACIÓN AUTOMÁTICA - Session ID: [id]
Retomar desarrollo desde checkpoint: [descripción]
Estado actual: [detalle]
Archivos pendientes: [lista]
Próximo paso: [acción específica]
USAR PROTOCOLO FASE [número] directamente"

Archivos de Contexto Dinámico

CONTEXTO BÁSICO (siempre cargar):
- architecture.md
- claude_instructions_v3.md  
- features_backlog.md
- inventory_system_directory.md
- change_log.md

CONTEXTO ESPECÍFICO (cargar según tarea):
Testing: app_test_plan.md, coverage_report.md
Config: config_reference.md
Security: security_policy.md
Development: claude_development_strategy.md

MÉTRICAS Y MONITOREO

Métricas por Sesión

Tiempo de desarrollo (estimado)
Líneas de código agregadas/modificadas
Número de tests creados
Cobertura de código alcanzada
Número de commits realizados
Archivos de documentación actualizados

Indicadores de Calidad

Score de pylint ≥ 9.0
Cobertura de tests ≥ 95%
Tiempo de ejecución de tests < 30s
Zero warnings en flake8
Conformidad 100% con black/isort
Documentación actualizada en 100% de cambios

SISTEMA DE LOGGING DETALLADO

FORMATO DE LOG:
[TIMESTAMP] [FASE] [ACCIÓN] - [RESULTADO]

Ejemplo:
[2025-07-20 10:30:15] [FASE1] [VALIDACIÓN_DUPLICIDAD] - OK: No duplicados detectados
[2025-07-20 10:31:22] [FASE2] [DISEÑO_PRUEBAS] - OK: 5 pruebas diseñadas
[2025-07-20 10:35:45] [FASE2] [IMPLEMENTACIÓN] - OK: Función user_login completada
[2025-07-20 10:36:12] [FASE3] [VALIDACIÓN] - OK: Todos los checks pasados
[2025-07-20 10:37:00] [FASE4] [CHECKPOINT] - OK: Checkpoint generado

COMANDOS DE EMERGENCIA

Rollback Inmediato

EMERGENCY_ROLLBACK: Revertir al último checkpoint funcional

Validación Completa

FULL_VALIDATION: Ejecutar todas las validaciones del sistema

Estado del Sistema

SYSTEM_STATUS: Generar reporte completo del estado actual

Recovery Automático

AUTO_RECOVERY: Intentar recuperación automática del último estado válido

VERSIÓN: 3.0
ÚLTIMA ACTUALIZACIÓN: 2025-07-20
PRÓXIMA REVISIÓN: Según feedback de uso

Estas instrucciones son obligatorias y no pueden ser modificadas sin autorización explícita del desarrollador principal.