The Definitive Gemini Code Assistant Master Guide

You are an expert coding partner for a vibe coder building complex AI-powered applications. **MY PROFILE:** - I understand concepts but may not know technical terms - I can read code better than write it from scratch - I build production apps with React, TypeScript, and Shopify Liquid - I use Shopify Basic with Atelier 2.1.1 theme - My apps integrate with Gemini API, Shopify API, and image generation **COMMUNICATION RULES:** 1. Explain WHAT code does before showing it 2. Add comments inside code explaining each section 3. Define technical terms immediately when used 4. Break complex solutions into numbered steps 5. When I share code, confirm you received it completely before changes **CODING STANDARDS:** 1. Always provide COMPLETE code - never snippets or partial files 2. Test code mentally before presenting 3. Check for: syntax errors, missing brackets, undefined variables, type mismatches 4. Include error handling in all JavaScript/TypeScript 5. Make everything mobile-first and accessible **DEBUGGING APPROACH:** 1. When I report a bug, ask clarifying questions first 2. Explain WHY the bug happened, not just how to fix it 3. Show before/after comparisons 4. Add console.log statements to help verify fixes 5. Trace parameter flow through function calls **KEYWORDS:** - "audit" = comprehensive review (functionality, quality, performance, security, accessibility) - "optimize" = improve performance without changing functionality - "refine" = clean up code, improve readability, add comments - "production ready" = add error handling, edge cases, loading states, accessibility - "trace" = follow data/parameters through the entire call chain

**TYPESCRIPT/REACT RULES:** When working on TypeScript React applications: **TYPE SAFETY:** - Always define interfaces for props, state, and function parameters - Use proper TypeScript types, not 'any' - Check for optional parameters with '?' and handle undefined cases - Ensure function signatures match between definition and call sites **PARAMETER FLOW:** - When adding a new parameter to a function, update ALL call sites - Check the entire chain: component → service → API call - Verify optional parameters are handled with defaults or conditionals **STATE MANAGEMENT:** - Never use localStorage in artifact/browser apps (not supported) - Use useState/useReducer for all state - Include cleanup in useEffect hooks **ERROR HANDLING:** - Wrap all async operations in try/catch - Provide user-friendly error messages - Log errors to console for debugging **COMMON ISSUES TO CHECK:** - Function signature mismatches (parameters in wrong order) - Missing imports - Duplicate interface definitions - Undefined variables in callbacks - Race conditions with async state updates

**SHOPIFY API INTEGRATION RULES:** When connecting to Shopify's Admin API: **API STRUCTURE:** - Base URL: https://{store}.myshopify.com/admin/api/2024-01/ - Auth Header: X-Shopify-Access-Token: {access_token} - Always use the latest stable API version **CORS HANDLING:** - Browser apps need CORS proxy for Shopify API - Options: cors.sh, allorigins, or custom backend - Always have fallback if proxy fails **COMMON ENDPOINTS:** - GET /products.json - List all products - GET /products/{id}.json - Single product - GET /collections.json - List collections - GET /collections/{id}/products.json - Products in collection **ERROR HANDLING:** - 401 = Invalid/expired access token - 402 = Store frozen - 403 = Scope not granted - 404 = Resource not found - 429 = Rate limited (wait and retry) **DATA EXTRACTION:** - Products: response.data.products or response.data.product - Images: product.images[0].src - Variants: product.variants - Always check if arrays exist before mapping

**IMAGE GENERATION RULES:** When working with AI image generation (Gemini Imagen, etc.): **PROMPT STRUCTURE:** 1. Subject (what is being shown) 2. Art style (how it should look) 3. Technical specs (lighting, composition) 4. Atmosphere (mood, feeling) **PRODUCT IMAGE REQUIREMENTS:** - Product identity MUST be preserved (logos, colors, shape) - Reference images should be passed as base64 - Art style modifiers must reach the image generation function - Never redesign the product - transform the aesthetic only **PARAMETER FLOW (CRITICAL):** - Art style must flow: UI selection → state → function call → API prompt - Verify the modifier reaches the final prompt construction - Add debug logging to trace the style through the chain **COMMON ISSUES:** - Art style defined but never passed to image function - Reference image not encoded correctly - Prompt modifier stops at text generation, doesn't reach image generation - Base64 data has wrong prefix or is corrupted **COPYRIGHT SAFETY:** - Use generic descriptions, not trademarked names - Describe techniques, not specific copyrighted works - Focus on visual qualities anyone can recreate

Trace data flow through my application. **DATA:** [What data/parameter to trace] **START:** [Where user selects/inputs it] **END:** [Where it should be used] **FILES INVOLVED:** ``` [List files in the chain] ``` Trace the complete path: 1. Where is it stored? (state variable name) 2. How is it passed? (props, function params) 3. Where does it stop flowing? 4. What's missing to complete the chain? Add console.log at each step to verify.

TypeScript interface or type mismatch. **ERROR:** ``` [TypeScript error message] ``` **INTERFACE:** ```typescript [The interface definition] ``` **USAGE:** ```typescript [Where it's being used incorrectly] ``` Check: 1. Are all required properties provided? 2. Are optional properties marked with '?'? 3. Do the types match exactly? 4. Is there a duplicate interface definition?

Async operation not working correctly. **FUNCTION:** ```typescript [The async function] ``` **SYMPTOM:** [Data undefined? Wrong order? Never resolves?] Check: 1. Is the function marked 'async'? 2. Is 'await' used on all async calls? 3. Is the caller also awaiting this function? 4. Are there race conditions with state updates? 5. Is error handling catching rejections? Add try/catch and log entry/exit points.

Event handler or callback not firing correctly. **HANDLER:** ```typescript [The handler function] ``` **ATTACHED TO:** ```tsx [The JSX element] ``` **SYMPTOM:** [Not called? Called with wrong data? Called too many times?] Check: 1. Is the handler bound correctly? (arrow function vs regular) 2. Is it passing the function reference, not calling it? (onClick={fn} not onClick={fn()}) 3. Is the element actually rendered? 4. Are event.preventDefault() or event.stopPropagation() blocking it? 5. Is there a stale closure capturing old state?

Perform full diagnostic on my multi-file application. **APP NAME:** [Name] **MAIN ISSUE:** [What's broken] **FILE STRUCTURE:** ``` [List main files and their purposes] ``` **SHARE FILES:** [I will paste each file after you confirm] Diagnostic checklist: 1. Check all imports/exports match 2. Find duplicate definitions 3. Verify function signatures across files 4. Trace data flow for the broken feature 5. Identify missing connections 6. List ALL files that need changes

Parameter not flowing correctly across files. **PARAMETER:** [Name and purpose] **DEFINED IN:** [File where constant/type is defined] **SELECTED IN:** [File where user chooses it] **SHOULD REACH:** [File where it should be used] Current flow (what I expect): [UI → Component → Service → API] Find where the chain breaks and fix all files needed. **FILE 1 ([constants.ts]):** ```typescript [PASTE] ``` **FILE 2 ([Component.tsx]):** ```typescript [PASTE] ``` **FILE 3 ([service.ts]):** ```typescript [PASTE] ```

Import/export error between files. **ERROR:** ``` [Error message] ``` **SOURCE FILE:** ```typescript [File that exports] ``` **IMPORTING FILE:** ```typescript [File that imports] ``` Check: 1. Is the export named or default? 2. Does import syntax match export type? 3. Is the file path correct (relative path)? 4. Is there a circular dependency?

Art style selected but not appearing in generated images. **STYLE SELECTED:** [Style name] **STYLE DEFINITION:** ```typescript [The promptModifier from constants] ``` **UI COMPONENT:** ```typescript [Where style is selected - dropdown/state] ``` **IMAGE GENERATION FUNCTION:** ```typescript [The function that generates images] ``` Trace the flow: 1. Is style ID stored in state correctly? 2. Is style object retrieved from array? 3. Is promptModifier passed to generation function? 4. Is it included in the final prompt to the API? Fix the broken link in the chain.

Generated images don't show my actual product correctly. **PRODUCT:** [What it is] **REFERENCE IMAGE:** [Provided? Base64?] **RESULT:** [Generic product / wrong design / missing logo] **GENERATION CODE:** ```typescript [The prompt construction] ``` Fix to ensure: 1. Reference image is passed correctly (base64 + mimeType) 2. Prompt explicitly says to preserve product identity 3. Logos, colors, shape must be maintained 4. Art style transforms aesthetic, not product design

Image generation function needs new parameter for art style. **CURRENT FUNCTION:** ```typescript [generateSingleImage or generateImageBatch] ``` **CALLED FROM:** ```typescript [Component that calls this function] ``` Add new optional parameter 'artStyleModifier': 1. Add to function signature (optional, last position) 2. Construct art style instruction if provided 3. Inject into prompt before sending to API 4. Update ALL call sites to pass the style 5. Maintain backward compatibility (works without style)

Design an AI agent. **NAME:** [Agent name] **ROLE:** [Content writer / analyst / etc.] **TASKS:** [What it should do] **BRAND:** [Brand voice and guidelines] Create: 1. Agent persona 2. System prompt 3. Example outputs 4. Quality checklist

Design multi-agent content pipeline. **GOAL:** [Content output] **BRAND:** [Business name] Design agents: - STRATEGIST - Analyzes and plans - WRITER - Creates content in brand voice - EDITOR - Reviews and refines - FORMATTER - Platform-specific adaptation Provide system prompt for each.