Ingeniería de Software en la Era de IA: Más allá del Vibe-Coding

# framework/ai_coding_guardrails.py

from typing import Optional, List
from dataclasses import dataclass

@dataclass
class AICodeReviewChecklist:
    """Checklist para code reviews de código generado por IA"""
    
    # 1. Arquitectura y diseño
    follows_architectural_patterns: bool
    respects_layer_boundaries: bool
    has_proper_abstractions: bool
    
    # 2. Calidad del código
    has_type_hints: bool
    follows_style_guide: bool
    has_documentation: bool
    
    # 3. Testing y validación
    has_unit_tests: bool
    tests_cover_edge_cases: bool
    has_integration_tests: bool
    
    # 4. Mantenibilidad
    is_dry_compliant: bool
    has_proper_error_handling: bool
    is_configurable: bool
    
    # 5. Security
    follows_security_best_practices: bool
    sanitizes_inputs: bool
    has_proper_auth_checks: bool
    
    def score(self) -> float:
        """Calcula porcentaje de cumplimiento"""
        fields = [
            self.follows_architectural_patterns,
            self.respects_layer_boundaries,
            self.has_proper_abstractions,
            self.has_type_hints,
            self.follows_style_guide,
            self.has_documentation,
            self.has_unit_tests,
            self.tests_cover_edge_cases,
            self.has_integration_tests,
            self.is_dry_compliant,
            self.has_proper_error_handling,
            self.is_configurable,
            self.follows_security_best_practices,
            self.sanitizes_inputs,
            self.has_proper_auth_checks,
        ]
        return sum(fields) / len(fields) * 100

// BEFORE: Código generado por LLM sin revisión de arquitectura
// ❌ Antes: Violación de separation of concerns, mezcla lógica de negocio con datos

class UserService {
  async getUser(id: string) {
    // LLM generó esto - mezcla concerns
    const db = await Database.connect();
    const user = await db.query('SELECT * FROM users WHERE id = $1', [id]);
    
    // Lógica de negocio hardcodeada en el método
    if (user.is_premium) {
      const premiumFeatures = await db.query(
        'SELECT * FROM premium_features WHERE user_id = $1', 
        [id]
      );
      return { ...user, features: premiumFeatures };
    }
    
    return user;
  }
  
  async createUser(userData: any) {
    // Sin validaciones, sin transaction handling
    const db = await Database.connect();
    return await db.query('INSERT INTO users ...', [userData]);
  }
}

# BEFORE: Contrato API sin type safety
# ❌ Antes: LLM generó esto sin pensamiento en versioning o backwards compatibility

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class UserResponse(BaseModel):
    # Sin versioning, sin metadata de deprecation
    id: str
    name: str
    email: str
    preferences: dict  # ❌ Type inseguro
    
@app.get("/users/{id}")
async def get_user(id: str):
    # Sin response model, sin error handling estructurado
    user = db.get_user(id)
    return user

// ✅ Testing pyramid con LLM assistance + human design
// tests/integration/userService.integration.test.ts

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { UserService } from '@/services/UserService';
import { UserRepository } from '@/repositories/UserRepository';
import { TestDatabase } from '@/tests/utils/TestDatabase';

describe('UserService Integration Tests', () => {
  let userService: UserService;
  let testDb: TestDatabase;
  
  beforeEach(async () => {
    // LLM generó el boilerplate, pero diseñamos el setup
    testDb = new TestDatabase();
    await testDb.migrate();
    await testDb.seed();
    
    const userRepo = new UserRepository(testDb.connection);
    userService = new UserService(userRepo);
  });
  
  afterEach(async () => {
    await testDb.cleanup();
  });
  
  describe('User creation flow', () => {
    it('should create user with valid email', async () => {
      // Test generado por LLM basado en nuestros requisitos
      const userData = {
        name: 'Test User',
        email: '[email protected]',
        preferences: {}
      };
      
      const user = await userService.createUser(userData);
      
      expect(user.id).toBeDefined();
      expect(user.email).toBe(userData.email);
      
      // Verification step que el LLM no hubiera pensado
      const dbUser = await testDb.query(
        'SELECT * FROM users WHERE id = $1',
        [user.id]
      );
      expect(dbUser.length).toBe(1);
    });
    
    it('should reject invalid email format', async () => {
      // Edge case que LLM no cubre sin dirección humana
      const userData = {
        name: 'Test User',
        email: 'invalid-email', // ❌ Sin @
        preferences: {}
      };
      
      await expect(userService.createUser(userData))
        .rejects.toThrow('ValidationError');
    });
    
    it('should handle concurrent user creation', async () => {
      // Race condition que requiere testing humano
      const userData = {
        name: 'Test User',
        email: '[email protected]',
        preferences: {}
      };
      
      const promises = Array(10).fill(null).map(() => 
        userService.createUser(userData)
      );
      
      const results = await Promise.allSettled(promises);
      
      // Solo uno debería exitar, el resto throw
      const successCount = results.filter(r => r.status === 'fulfilled').length;
      expect(successCount).toBe(1);
    });
  });
});

# ✅ Better approach: Iterative development with checkpoints

class CodeGenerationStrategy:
    """Estrategia de codegen con checkpoints humanos"""
    
    def __init__(self, llm_client):
        self.llm = llm_client
        self.checkpoints = []
    
    def generate_feature(self, feature_spec: dict) -> str:
        """Genera código con checkpoints de revisión"""
        
        # Step 1: Architectural design (human review required)
        architecture_prompt = self._build_architecture_prompt(feature_spec)
        architecture = self.llm.generate(architecture_prompt)
        
        # Checkpoint 1: Architecture review
        self.checkpoints.append({
            'step': 'architecture',
            'output': architecture,
            'requires_review': True
        })
        
        # Step 2: Interface definitions (can be auto-accepted)
        interfaces = self._generate_interfaces(architecture)
        
        # Checkpoint 2: Interface validation
        self.checkpoints.append({
            'step': 'interfaces',
            'output': interfaces,
            'requires_review': False  # Auto-accept with patterns
        })
        
        # Step 3: Implementation (human review for complex logic)
        implementation = self._generate_implementation(interfaces)
        
        # Checkpoint 3: Code review (especially for business logic)
        self.checkpoints.append({
            'step': 'implementation',
            'output': implementation,
            'requires_review': True  # Business logic always reviewed
        })
        
        return self._merge_outputs()

// ✅ Bounded context prompting

// Prompt 1: Domain models only
// "Generate TypeScript interfaces for a user management domain with authentication,
// authorization, and preferences. Include type-safe enums and validation rules."

interface UserDomain {
  // Domain models, no implementation
}

// Prompt 2: Repository interfaces only
// "Based on these domain models, generate repository interfaces with clear separation
// of concerns between users, preferences, and authentication."

interface UserRepository {
  // Interface contracts, no implementation
}

// Prompt 3: Service layer implementation
// "Implement the UserService using these repository interfaces. Focus on business logic,
// not data access details. Include proper error handling and transaction management."

class UserService {
  // Business logic implementation
}

// Prompt 4: Infrastructure implementation
// "Implement the UserRepository using PostgreSQL. Focus on data access, queries,
// and connection management. No business logic here."

class PostgresUserRepository {
  // Data access implementation
}

# ✅ Test-first development with LLM assistance

class TestDrivenLLMWorkflow:
    """Workflow TDD asistido por LLM"""
    
    def develop_feature(self, feature_spec: dict):
        """Desarrolla feature con enfoque TDD"""
        
        # Step 1: Human defines requirements
        requirements = feature_spec['requirements']
        
        # Step 2: LLM generates test scenarios
        test_scenarios = self.llm.generate_test_scenarios(
            requirements=requirements,
            include_edge_cases=True,
            include_security_tests=True
        )
        
        # Step 3: Human reviews and refines test scenarios
        approved_scenarios = self.review_test_scenarios(test_scenarios)
        
        # Step 4: LLM generates test code based on approved scenarios
        test_code = self.llm.generate_test_code(
            scenarios=approved_scenarios,
            test_framework='pytest'
        )
        
        # Step 5: Tests fail (red phase) - verify they fail as expected
        self._run_tests(test_code)
        assert self._tests_are_failing(), "Tests should fail initially"
        
        # Step 6: LLM generates implementation to pass tests
        implementation = self.llm.generate_implementation(
            requirements=requirements,
            failing_tests=test_code
        )
        
        # Step 7: Tests pass (green phase)
        self._run_tests_with_implementation(test_code, implementation)
        assert self._tests_are_passing(), "Implementation should pass tests"
        
        # Step 8: Human reviews implementation
        self._code_review(implementation)
        
        return {
            'tests': test_code,
            'implementation': implementation
        }

def calculate_crqs(review: dict) -> float:
    """Calcula calidad de code review de código LLM-gen"""
    
    scores = {
        'architecture_adherence': 0.30,  # ¿Respeta patrones arquitectónicos?
        'error_handling': 0.20,          # ¿Manejo de errores robusto?
        'security_practices': 0.15,     # ¿Sigue security best practices?
        'test_coverage': 0.15,          # ¿Tests apropiados?
        'documentation': 0.10,          # ¿Documentación clara?
        'maintainability': 0.10         # ¿Code legible y mantenible?
    }
    
    total_score = sum(
        review.get(criterion, 0) * weight
        for criterion, weight in scores.items()
    )
    
    return total_score

# Usage: solo merge código LLM-gen con CRQS > 0.80