# 🎮 Ejemplo práctico en un proyecto real ## Walkthrough completo: De proyecto desconocido a dominio total Esta lección te lleva paso a paso a través de un análisis completo de un proyecto real, aplicando todas las técnicas que has aprendido. Verás cómo un desarrollador experto aborda un codebase desconocido usando Claude Code. --- ## 🎯 Proyecto de ejemplo: E-commerce Platform ### Contexto del proyecto **Escenario realista:** - Acabas de unirte a un equipo - Proyecto: Plataforma de e-commerce en Node.js + React - 150+ archivos, 50k líneas de código - 3 años de desarrollo, múltiples desarrolladores - Necesitas entender rápidamente para implementar nueva feature - Deadline: 2 semanas **Tu misión:** Implementar un sistema de descuentos dinámicos que se integre con: - Sistema de autenticación existente - Carrito de compras actual - Procesamiento de pagos - Notificaciones por email --- ## 📋 Fase 1: Exploración inicial (15 minutos) ### Primer contacto con el proyecto ```bash # Paso 1: Navegar al proyecto cd ecommerce-platform ls -la # Estructura inicial visible: # .env.example # package.json # src/ # tests/ # docs/ # docker-compose.yml # README.md (desactualizado) ``` ### Análisis panorámico ```bash # Paso 2: Iniciar Claude y hacer exploración general claude . # Comando clave: Exploración completa del proyecto claude explore ``` **Output de exploración:** ```markdown # 📊 Project Analysis: E-commerce Platform ## 🏗️ Architecture Overview - **Type**: Full-stack JavaScript application - **Backend**: Node.js 18 + Express.js + PostgreSQL - **Frontend**: React 18 + Next.js 13 (App Router) - **State Management**: Redux Toolkit + RTK Query - **Authentication**: JWT + Passport.js - **Payments**: Stripe integration - **Email**: SendGrid for notifications ## 📁 Key Directory Structure ``` src/ ├── backend/ │ ├── controllers/ # API endpoint handlers │ ├── services/ # Business logic layer │ ├── models/ # Database models (Sequelize) │ ├── middleware/ # Auth, validation, error handling │ └── routes/ # API route definitions ├── frontend/ │ ├── app/ # Next.js 13 App Router pages │ ├── components/ # Reusable React components │ ├── store/ # Redux store and slices │ ├── hooks/ # Custom React hooks │ └── utils/ # Helper functions └── shared/ ├── types/ # TypeScript type definitions └── constants/ # Shared constants ``` ## 🎯 Core Business Modules Identified 1. **User Management** (`src/backend/services/userService.js`) 2. **Product Catalog** (`src/backend/services/productService.js`) 3. **Shopping Cart** (`src/backend/services/cartService.js`) 4. **Order Processing** (`src/backend/services/orderService.js`) 5. **Payment Processing** (`src/backend/services/paymentService.js`) 6. **Email Notifications** (`src/backend/services/emailService.js`) ## 🔗 Key Dependencies ### Backend - express@4.18.2 → Web server framework - sequelize@6.28.0 → ORM for PostgreSQL - stripe@11.1.0 → Payment processing - @sendgrid/mail@7.7.0 → Email service - passport-jwt@4.0.1 → JWT authentication ### Frontend - next@13.1.6 → React framework - @reduxjs/toolkit@1.9.1 → State management - @stripe/stripe-js@1.46.0 → Payment UI - react-hook-form@7.43.1 → Form handling ## 💡 Architecture Patterns Found ✅ **Clean Architecture**: Well-separated layers ✅ **Repository Pattern**: Data access abstraction ✅ **Service Layer**: Business logic encapsulation ✅ **API Versioning**: /api/v1/ structure ⚠️ **Some inconsistencies**: Mixed patterns in older code ## 🚀 Recommended Entry Points for New Feature 1. **Start with**: `src/backend/services/cartService.js` (discount logic will integrate here) 2. **Review**: `src/backend/models/` (understand data structure) 3. **Check**: `src/frontend/store/cartSlice.js` (frontend state management) 4. **Examine**: `src/backend/services/paymentService.js` (integration point) ``` ### Insights clave del análisis inicial **Lo que aprendimos en 2 minutos:** - ✅ Arquitectura limpia y bien estructurada - ✅ Tecnologías modernas y actualizadas - ✅ Separación clara entre frontend y backend - ⚠️ Algún código legacy que necesita atención - 🎯 **Punto de entrada claro**: cartService.js para nuestra feature --- ## 🔍 Fase 2: Deep dive en módulos relevantes (30 minutos) ### Análisis del sistema de carrito ```bash # Analizar el servicio de carrito específicamente claude analyze src/backend/services/cartService.js ``` **Output detallado:** ````markdown # 📊 Deep Analysis: cartService.js ## 🏗️ Service Structure - **Type**: ES6 Class with static methods - **Lines**: 234 (medium complexity) - **Dependencies**: 5 external, 3 internal - **Test Coverage**: 78% (good) ## 🎯 Main Responsibilities 1. **Cart Management**: Add, remove, update items 2. **Price Calculation**: Subtotal, tax, shipping 3. **Validation**: Stock availability, user permissions 4. **Persistence**: Database operations via CartModel ## 🔧 Key Methods Analysis ### calculateCartTotal(cartId, userId) ```javascript static async calculateCartTotal(cartId, userId) { const cart = await CartModel.findByPk(cartId, { include: [{ model: CartItem, include: [Product] }] }) let subtotal = 0 for (const item of cart.CartItems) { subtotal += item.quantity * item.Product.price } const tax = subtotal * 0.08 // ⚠️ Hardcoded tax rate const shipping = this.calculateShipping(subtotal) return { subtotal, tax, shipping, total: subtotal + tax + shipping } } ``` ```` ### 🎯 Perfect Integration Point for Discounts! **Line 67-89**: Price calculation logic is centralized here **Opportunity**: Add discount calculation before tax computation **Impact**: Changes here will automatically reflect in checkout flow ## 🔗 Integration Points Found ### Database Models - **CartModel** (`src/backend/models/Cart.js`) - Main cart entity - **CartItemModel** (`src/backend/models/CartItem.js`) - Individual items - **ProductModel** (`src/backend/models/Product.js`) - Product information ### Frontend Integration - **Redux Slice**: `src/frontend/store/cartSlice.js` - **Cart Component**: `src/frontend/components/Cart/CartSummary.jsx` - **Checkout Flow**: `src/frontend/app/checkout/page.tsx` ## 🚨 Issues Found 1. **Hardcoded tax rate** (line 78) - should be configurable 2. **No discount system** - perfect opportunity for our feature 3. **Basic error handling** - could be improved 4. **N+1 query potential** - includes are not optimized ## 🚀 Feature Implementation Strategy ### Phase 1: Database Schema - Add `discounts` table with rules and conditions - Add `user_discounts` table for user-specific discounts - Add `discount_id` foreign key to CartItem model ### Phase 2: Service Layer - Create `DiscountService.js` for business logic - Modify `calculateCartTotal()` to include discount calculation - Add discount validation methods ### Phase 3: API Layer - Add `/api/v1/discounts` endpoints - Modify cart endpoints to include discount information - Add discount application endpoint ### Phase 4: Frontend Integration - Update Redux store to handle discounts - Modify CartSummary component to display discounts - Add discount code input in checkout flow ```` ### Análisis del sistema de autenticación ```bash # Entender cómo funciona la autenticación (necesario para validar descuentos por usuario) claude analyze src/backend/middleware/auth.js --focus security ```` **Insights de autenticación:** ````markdown # 🔒 Authentication Analysis ## 🛡️ Current Implementation - **JWT Tokens**: RS256 signing algorithm - **Refresh Tokens**: Stored in database with expiration - **User Roles**: Basic role-based access control - **Session Management**: Stateless with token validation ## 🎯 Integration Points for Discounts ### User Context Available ```javascript // In any protected route, user info is available as: req.user = { id: '123e4567-e89b-12d3-a456-426614174000', email: 'user@example.com', role: 'customer', // or 'premium', 'admin' createdAt: '2023-01-15T10:30:00Z', } ``` ```` ### Permission Checks - **User-specific discounts**: Can check `req.user.id` - **Role-based discounts**: Can check `req.user.role` - **Membership discounts**: Can check account age via `req.user.createdAt` ## 🔧 Discount Validation Strategy 1. **User Authentication**: Already handled by existing middleware 2. **Permission Validation**: Extend existing role checking 3. **Usage Tracking**: Can link to existing user audit system ```` --- ## 📊 Fase 3: Análisis de dependencias e impacto (20 minutos) ### Mapeo de dependencias para la nueva feature ```bash # Analizar qué módulos se verán afectados por los cambios de discounts claude dependencies src/backend/services/cartService.js --full ```` **Dependency analysis:** ```markdown # 🔗 Impact Analysis for Discount Feature ## 📤 Services that depend on cartService.js 1. **OrderService** - Uses cart total for order creation 2. **PaymentService** - Uses cart total for Stripe integration 3. **EmailService** - Sends cart abandonment emails 4. **AnalyticsService** - Tracks cart metrics ## 📥 Dependencies cartService.js uses 1. **CartModel** - Will need to extend for discount_id 2. **ProductModel** - No changes needed 3. **UserModel** - May need for user-specific discounts ## 💥 Change Impact Estimation ### High Impact (Requires Updates) - **Frontend Cart Components** - Display discount information - **Checkout Flow** - Include discount in final calculations - **Order Service** - Store discount information in orders - **Email Templates** - Show discounts in order confirmations ### Medium Impact (May Need Updates) - **Analytics Service** - Track discount usage metrics - **Payment Service** - Handle discounted amounts - **API Documentation** - Update with new endpoints ### Low Impact (Minimal Changes) - **Product Service** - No direct integration needed - **User Service** - May add discount-related user fields ## 🎯 Implementation Risk Assessment - **Risk Level**: MEDIUM - **Affected Files**: ~15 files estimated - **Breaking Changes**: None (additive feature) - **Test Coverage**: Need to add ~25 new tests ``` ### Búsqueda de patterns existentes ```bash # Buscar si ya existe algún sistema de descuentos o promociones claude search "discount OR promotion OR coupon OR promo" ``` **Search results:** ````markdown # 🔍 Search Results: Existing Discount/Promotion Code ## 📊 No Existing Implementation Found - **0 matches** for discount logic - **0 matches** for coupon systems - **0 matches** for promotional codes ## 💡 Similar Patterns Found (2 matches) 1. **src/backend/services/orderService.js:145** ```javascript // Tax calculation pattern (similar to what we need for discounts) const taxAmount = subtotal * taxRate ``` ```` 2. **src/frontend/components/Cart/CartSummary.jsx:78** ```javascript // Price breakdown display (where we'll show discounts)

Subtotal: ${subtotal}

Tax: ${tax}

Shipping: ${shipping}

Total: ${total}

``` ## 🚀 Implementation Advantage - **Clean slate**: No conflicting existing code - **Consistent patterns**: Can follow existing tax calculation approach - **UI ready**: Price breakdown component easily extensible ```` --- ## 🛠️ Fase 4: Planificación de implementación (25 minutos) ### Diseño de la solución Basado en el análisis completo, diseñamos la implementación: ```bash # Generar documentación de arquitectura para la nueva feature claude document . --type architecture --focus discount-system ```` **Architecture design:** ````markdown # 🏗️ Discount System Architecture Design ## 📋 Requirements Summary Based on codebase analysis, the discount system should: - ✅ Integrate seamlessly with existing cart calculation - ✅ Support multiple discount types (percentage, fixed amount, BOGO) - ✅ Handle user-specific and general discounts - ✅ Maintain audit trail for business analytics - ✅ Scale with existing database and API patterns ## 🗄️ Database Schema Design ### discounts table ```sql CREATE TABLE discounts ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), code VARCHAR(50) UNIQUE NOT NULL, name VARCHAR(100) NOT NULL, description TEXT, type discount_type NOT NULL, -- 'percentage', 'fixed_amount', 'bogo' value DECIMAL(10,2) NOT NULL, min_purchase_amount DECIMAL(10,2), max_discount_amount DECIMAL(10,2), usage_limit INTEGER, usage_count INTEGER DEFAULT 0, user_specific BOOLEAN DEFAULT false, valid_from TIMESTAMP NOT NULL, valid_until TIMESTAMP NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ```` ### user_discounts table (for user-specific discounts) ```sql CREATE TABLE user_discounts ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), user_id UUID NOT NULL REFERENCES users(id), discount_id UUID NOT NULL REFERENCES discounts(id), used_at TIMESTAMP, order_id UUID REFERENCES orders(id), created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ### cart_discounts table (applied discounts) ```sql CREATE TABLE cart_discounts ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), cart_id UUID NOT NULL REFERENCES carts(id), discount_id UUID NOT NULL REFERENCES discounts(id), discount_amount DECIMAL(10,2) NOT NULL, applied_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` ## 🔧 Service Layer Design ### DiscountService.js ```javascript class DiscountService { // Validate and apply discount code to cart static async applyDiscount(cartId, discountCode, userId) { // 1. Validate discount code exists and is active // 2. Check user eligibility and usage limits // 3. Calculate discount amount based on cart contents // 4. Apply discount to cart (save to cart_discounts) // 5. Return updated cart totals } // Remove discount from cart static async removeDiscount(cartId, discountId) { // 1. Remove from cart_discounts table // 2. Recalculate cart totals // 3. Return updated cart } // Calculate discount amount static calculateDiscountAmount(discount, cartSubtotal, cartItems) { switch (discount.type) { case 'percentage': return Math.min( cartSubtotal * (discount.value / 100), discount.max_discount_amount || Infinity ) case 'fixed_amount': return Math.min(discount.value, cartSubtotal) case 'bogo': return this.calculateBOGODiscount(discount, cartItems) default: throw new Error('Unknown discount type') } } } ``` ## 🌐 API Endpoints Design ### New Endpoints - `POST /api/v1/discounts/apply` - Apply discount code to cart - `DELETE /api/v1/discounts/remove` - Remove discount from cart - `GET /api/v1/discounts/validate/:code` - Validate discount code - `GET /api/v1/user/discounts` - Get user's available discounts ### Modified Endpoints - `GET /api/v1/cart/:id` - Now includes applied discounts - `POST /api/v1/orders` - Store discount information in order ## ⚛️ Frontend Integration ### Redux Store Updates ```javascript // cartSlice.js additions const cartSlice = createSlice({ name: 'cart', initialState: { items: [], subtotal: 0, tax: 0, shipping: 0, discounts: [], // New field discountTotal: 0, // New field total: 0, }, reducers: { applyDiscount: (state, action) => { state.discounts.push(action.payload) state.discountTotal = state.discounts.reduce( (sum, d) => sum + d.amount, 0 ) state.total = state.subtotal + state.tax + state.shipping - state.discountTotal }, removeDiscount: (state, action) => { state.discounts = state.discounts.filter(d => d.id !== action.payload) state.discountTotal = state.discounts.reduce( (sum, d) => sum + d.amount, 0 ) state.total = state.subtotal + state.tax + state.shipping - state.discountTotal }, }, }) ``` ### Component Updates ```jsx // CartSummary.jsx modifications function CartSummary({ cart }) { return (

Subtotal: ${cart.subtotal}

{/* New discount section */} {cart.discounts.map(discount => (

{discount.name}: -${discount.amount}

))}

Tax: ${cart.tax}

Shipping: ${cart.shipping}

Total: ${cart.total}

) } ``` ```` ### Timeline de implementación ```markdown # 📅 Implementation Timeline (2 weeks) ## Week 1: Backend Foundation ### Days 1-2: Database & Models - Create database migrations - Implement Discount, UserDiscount, CartDiscount models - Write model tests ### Days 3-4: Service Layer - Implement DiscountService with all business logic - Integrate with existing CartService - Write comprehensive unit tests ### Day 5: API Layer - Create discount endpoints - Update existing cart endpoints - Write integration tests ## Week 2: Frontend Integration & Testing ### Days 6-7: Frontend Implementation - Update Redux store for discount handling - Create DiscountCodeInput component - Update CartSummary to display discounts ### Days 8-9: UI/UX Polish - Add loading states and error handling - Implement discount validation feedback - Add accessibility features ### Day 10: Testing & Deployment - End-to-end testing - Performance testing - Documentation updates - Deploy to staging and production ```` --- ## 🚀 Fase 5: Implementación guiada (Opcional - 60 minutos) ### Paso a paso de implementación real Si tienes tiempo, puedes ver la implementación paso a paso: ```bash # 1. Crear la migración de base de datos claude generate migration --name "add_discount_system" --type database # 2. Crear el modelo de datos claude generate model --name "Discount" --fields "code:string,type:enum,value:decimal" # 3. Implementar el servicio claude generate service --name "DiscountService" --methods "applyDiscount,calculateDiscount" # 4. Crear endpoints de API claude generate controller --name "DiscountController" --routes "apply,remove,list" # 5. Actualizar frontend claude generate component --name "DiscountCodeInput" --type react ``` ### Validación y testing ```bash # Generar tests automáticamente claude generate tests --for "DiscountService" --type unit # Documentar la nueva feature claude document src/services/DiscountService.js --include-examples # Verificar integración claude test integration --feature "discount-system" ``` --- ## 📊 Resumen del walkthrough ### Lo que logramos en 90 minutos **✅ Comprensión completa del proyecto:** - Arquitectura general y patrones utilizados - Módulos relevantes para nuestra feature - Dependencias e impacto de cambios - Oportunidades de integración **✅ Planificación detallada:** - Diseño de base de datos - Arquitectura de servicios - API endpoints necesarios - Integración frontend - Estrategia de testing **✅ Roadmap de implementación:** - Timeline realista de 2 semanas - Fases bien definidas - Métricas de éxito claras - Estrategia de deployment ### Comparación con enfoque tradicional **Enfoque tradicional (sin Claude Code):** - 📅 **Tiempo de comprensión**: 2-3 días - 🔍 **Análisis de dependencias**: 1 día adicional - 📋 **Planificación**: 1 día adicional - 🎯 **Total**: ~1 semana antes de escribir código **Con Claude Code:** - ⚡ **Tiempo total**: 90 minutos - 🎯 **Comprensión**: Inmediata y profunda - 📊 **Análisis**: Automático y exhaustivo - 🚀 **Ready to code**: Mismo día **Ahorro de tiempo: 95%** 🤯 --- ## ✅ Ejercicios prácticos ### 🏋️‍♂️ Ejercicio 1: Análisis de tu proyecto (45 min) **Complete project walkthrough:** 1. Aplica el mismo proceso a tu proyecto principal 2. Identifica una nueva feature que quieras implementar 3. Sigue todos los pasos del walkthrough 4. Crea un plan de implementación detallado ### 🏋️‍♂️ Ejercicio 2: Análisis competitivo (30 min) **Compare different projects:** 1. Analiza 2 proyectos diferentes con Claude Code 2. Compara arquitecturas y patrones utilizados 3. Identifica best practices de cada uno 4. Propón mejoras cruzadas ### 🏋️‍♂️ Ejercicio 3: Documentación del proceso (20 min) **Document your workflow:** 1. Documenta tu proceso de análisis personal 2. Crea un template para futuros análisis 3. Define métricas para medir efectividad 4. Comparte con tu equipo --- ## 📈 Próximo paso En la **Lección 8** aprenderás las mejores prácticas para aplicar todas estas técnicas de manera consistente y efectiva en tu trabajo diario. **Te esperan:** - Best practices consolidadas - Workflows optimizados - Tips para equipos - Evitar errores comunes > **💡 Key insight**: El poder de Claude Code no está solo en los comandos individuales, sino en cómo los combinas para crear un workflow de análisis sistemático y completo.