Agentic Development with Claude Code
Overview
Section titled “Overview”Agentic development uses AI assistants to automate repetitive tasks, enforce coding standards, and accelerate development workflows. At Avada, we use Claude Code with a customized .claude folder containing commands, skills, and agents tailored to our development standards.
Understanding AI-Assisted Development
Section titled “Understanding AI-Assisted Development”Before diving into tools, let’s understand the evolution of AI coding assistants and why different approaches emerged.
Phase 1: The Chatbox Era (2022-2023)
Section titled “Phase 1: The Chatbox Era (2022-2023)”It started with ChatGPT (late 2022) and GitHub Copilot going mainstream. Developers could ask for code snippets, explanations, and debugging help. Copilot became autocomplete on steroids.
┌─────────────────────────────────────────────────────────┐│ The Chatbox Era │├─────────────────────────────────────────────────────────┤│ ││ Developer: "Write a function to sort an array" ││ ││ AI: Here's a sorting function... ││ function sortArray(arr) { ... } ││ ││ ───────────────────────────────────────────────────── ││ ││ • Just a chatbox in IDE ││ • Copy-paste snippets ││ • No context of YOUR codebase ││ • AI doesn't know your project structure ││ │└─────────────────────────────────────────────────────────┘The Problem: LLMs are trained on massive datasets (books, code, websites). But training is expensive and slow. You can’t retrain a model every time a new library version comes out.
LLM Training:├── Cost: Millions of dollars├── Time: Weeks to months├── Data cutoff: Always outdated└── Result: AI gives outdated answers, deprecated APIs, wrong syntaxThis led to a fundamental question: How do we give AI up-to-date knowledge without retraining?
Phase 2: RAG - The “Onboarding” Approach (2023)
Section titled “Phase 2: RAG - The “Onboarding” Approach (2023)”RAG (Retrieval Augmented Generation) solved this elegantly.
Think of it like onboarding a new employee:
- They have 16+ years of education (the pretrained model)
- You don’t retrain them from scratch
- You give them documentation to read (retrieval)
- They combine their knowledge with your docs to answer questions
┌─────────────────────────────────────────────────────────┐│ RAG = "Smart Employee Onboarding" │├─────────────────────────────────────────────────────────┤│ ││ University Graduate Your Company ││ (Pretrained LLM) (Your Codebase) ││ │ │ ││ │ ┌──────────────┐ │ ││ └───→│ Onboarding │←─────┘ ││ │ (Retrieval) │ ││ └──────┬───────┘ ││ │ ││ ▼ ││ "I know general programming AND ││ I've read your specific codebase" ││ │└─────────────────────────────────────────────────────────┘How RAG Works:
┌─────────────────────────────────────────────────────────┐│ RAG Pipeline │├─────────────────────────────────────────────────────────┤│ ││ 1. EMBED: Convert all code files → vector embeddings ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ file1.js │ → │ [0.2, ..]│ │ Vector │ ││ │ file2.js │ → │ [0.8, ..]│ → │ Database │ ││ │ file3.js │ → │ [0.1, ..]│ │ (ChromaDB)│ ││ └──────────┘ └──────────┘ └──────────┘ ││ ││ 2. QUERY: User asks "How does auth work?" ││ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││ │ Question │ → │ Embed │ → │ Find │ ││ │ │ │ Query │ │ Similar │ ││ └──────────┘ └──────────┘ └──────────┘ ││ ││ 3. RETRIEVE: Get top 5-10 most relevant files ││ ││ 4. GENERATE: Send retrieved context + question to LLM ││ │└─────────────────────────────────────────────────────────┘Phase 2.5: Cursor - The Coding Assistant (2023-2024)
Section titled “Phase 2.5: Cursor - The Coding Assistant (2023-2024)”Cursor took RAG and applied it specifically to coding. It became a true coding assistant:
┌─────────────────────────────────────────────────────────┐│ Cursor's Approach │├─────────────────────────────────────────────────────────┤│ ││ INDEXING (one-time + incremental) ││ ┌────────────────────────────────────────────────┐ ││ │ • Parse AST (Abstract Syntax Tree) │ ││ │ • Extract: functions, classes, imports │ ││ │ • Create embeddings for semantic search │ ││ │ • Store in local vector database │ ││ └────────────────────────────────────────────────┘ ││ ││ QUERY TIME ││ ┌────────────────────────────────────────────────┐ ││ │ 1. User asks question │ ││ │ 2. Search index for relevant symbols/files │ ││ │ 3. Retrieve matching code chunks │ ││ │ 4. Send to LLM with context │ ││ └────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────┘The Problem with Indexing:
As codebases grow, indexing hits limits:
- Context window: Even with retrieval, you can only fit so much in context
- Stale index: Code changes faster than re-indexing
- Chunking issues: What if the answer spans multiple files?
- Embedding quality: Semantic search isn’t always accurate for code
Your codebase: 500,000+ lines of codeContext window: ~200,000 tokens (~150,000 lines max)Index retrieval: Gets 5-10 chunks... but are they the RIGHT chunks?Phase 3: Agentic AI - Tools Over RAG (2024-2025)
Section titled “Phase 3: Agentic AI - Tools Over RAG (2024-2025)”Claude Code introduced a fundamentally different approach: be an Agent, not just an Assistant.
┌─────────────────────────────────────────────────────────┐│ Assistant vs Agent │├─────────────────────────────────────────────────────────┤│ ││ ASSISTANT (Cursor, Copilot) ││ ┌────────────────────────────────────────────────┐ ││ │ • Relies heavily on pretrained knowledge │ ││ │ • Uses RAG to retrieve context │ ││ │ • Answers based on what it "remembers" │ ││ │ • Limited by index quality │ ││ └────────────────────────────────────────────────┘ ││ ││ AGENT (Claude Code) ││ ┌────────────────────────────────────────────────┐ ││ │ • Has TOOLS to get real-time information │ ││ │ • Searches live codebase (not stale index) │ ││ │ • Can execute commands, read files, edit code │ ││ │ • Like ChatGPT calling Google instead of │ ││ │ giving outdated answers │ ││ └────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────┘The Key Insight:
Instead of trying to “remember” everything through RAG, give the AI tools to find information on-demand:
┌─────────────────────────────────────────────────────────┐│ Claude Code's Approach │├─────────────────────────────────────────────────────────┤│ ││ NO INDEXING - Uses native tools on-demand: ││ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ Grep │ │ Glob │ │ Read │ ││ │ (ripgrep) │ │ (find files)│ │ (cat file) │ ││ └─────────────┘ └─────────────┘ └─────────────┘ ││ ││ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ││ │ Bash │ │ Edit │ │ Write │ ││ │ (commands) │ │ (modify) │ │ (create) │ ││ └─────────────┘ └─────────────┘ └─────────────┘ ││ ││ WORKFLOW EXAMPLE: ││ ┌────────────────────────────────────────────────┐ ││ │ User: "How does authentication work?" │ ││ │ │ ││ │ Claude: │ ││ │ 1. Grep "auth" → finds auth-related files │ ││ │ 2. Glob "**/*auth*.js" → finds file patterns │ ││ │ 3. Read authHandler.js → understands flow │ ││ │ 4. Read authService.js → gets business logic │ ││ │ 5. Synthesizes answer from real code │ ││ └────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────┘RAG is still useful - but now it’s just one tool among many. The agent decides when to use RAG vs grep vs reading files directly.
The Evolution: From Chatbox to Multi-Agent
Section titled “The Evolution: From Chatbox to Multi-Agent”┌─────────────────────────────────────────────────────────┐│ The Evolution of AI Coding │├─────────────────────────────────────────────────────────┤│ ││ 2022-2023: CHATBOX ERA ││ └── Copy-paste snippets, no codebase awareness ││ ChatGPT, GitHub Copilot autocomplete ││ ││ 2023-2024: RAG & CODING ASSISTANT ERA ││ └── Index codebase, retrieve relevant chunks ││ Cursor, Copilot Chat - RAG + IDE integration ││ ││ 2024-2025: AGENTIC ERA ││ └── Tools over RAG, real-time exploration ││ Claude Code, Aider, Cline ││ ││ 2025+: MULTI-AGENT & ORCHESTRATION ││ └── Multiple specialized agents working together ││ Planner agent → Coder agent → Reviewer agent ││ Orchestration systems coordinate the workflow ││ │└─────────────────────────────────────────────────────────┘Comparison: Assistant vs Agent
Section titled “Comparison: Assistant vs Agent”| Aspect | Assistant (RAG-based) | Agent (Tool-based) |
|---|---|---|
| Knowledge source | Pretrained + retrieved chunks | Tools get live data |
| Codebase awareness | Index (can be stale) | Real-time search |
| Accuracy | Depends on embedding quality | Exact text matching |
| Adaptability | Limited to indexed content | Can use any tool |
| Example | Cursor | Claude Code |
| Analogy | Student with notes | Professional with Google |
Why Tools Beat Pure RAG
Section titled “Why Tools Beat Pure RAG”// RAG approach:// "Let me search my index for authentication..."// → Returns chunks that MIGHT be relevant// → May miss the actual implementation
// Agent approach:// "Let me FIND authentication code right now"grep("authentication", "src/") // Find exact matchesglob("**/*auth*.js") // Find auth-related filesread("src/handlers/authHandler.js") // Read the actual code// → Gets the REAL, CURRENT code every timeThe mental shift:
- RAG: “I’ll try to remember where I saw that…”
- Agent: “I don’t know, but I can find out right now”
Why Anthropic Models Excel at Coding
Section titled “Why Anthropic Models Excel at Coding”Claude models (especially Claude 3.5 Sonnet and Claude 4 Opus) are specifically optimized for coding tasks:
| Strength | How It Helps |
|---|---|
| Extended Thinking | Reasons through complex problems step-by-step before responding |
| Tool Use | Native ability to use tools (grep, edit, bash) reliably |
| Long Context | 200K tokens - can understand large files and codebases |
| Instruction Following | Follows coding standards and constraints precisely |
| Code Quality | Generates production-ready, idiomatic code |
The Agentic Difference
Section titled “The Agentic Difference”Traditional AI coding assistants are reactive - you ask, they answer.
Agentic AI is proactive - it can:
- Plan multi-step tasks
- Execute commands autonomously
- Learn from results and adapt
- Use tools in combination
Todo-Driven Development
Section titled “Todo-Driven Development”Claude Code uses a TodoWrite tool to break complex tasks into manageable steps. This provides:
- Visibility - You see exactly what Claude plans to do
- Progress Tracking - Each step is marked as pending → in_progress → completed
- Accountability - Claude doesn’t skip steps or forget tasks
- Interruptibility - You can pause and resume at any step
┌─────────────────────────────────────────────────────────┐│ Todo-Driven Workflow │├─────────────────────────────────────────────────────────┤│ ││ User: "Add customer points export feature" ││ ││ Claude creates Todo List: ││ ┌────────────────────────────────────────────────┐ ││ │ □ Research existing export patterns │ ││ │ □ Create exportService.js │ ││ │ □ Add export handler endpoint │ ││ │ □ Create CSV generation helper │ ││ │ □ Add export button to UI │ ││ │ □ Write tests │ ││ │ □ Run tests and verify │ ││ └────────────────────────────────────────────────┘ ││ ││ Then executes step-by-step: ││ ┌────────────────────────────────────────────────┐ ││ │ ✓ Research existing export patterns │ ││ │ ▶ Create exportService.js [in progress]│ ││ │ □ Add export handler endpoint │ ││ │ □ Create CSV generation helper │ ││ │ □ Add export button to UI │ ││ │ □ Write tests │ ││ │ □ Run tests and verify │ ││ └────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────┘Why This Matters:
- Complex tasks don’t get lost in long conversations
- You can interrupt and Claude remembers where it was
- Prevents the AI from “forgetting” subtasks
- Creates a natural checkpoint for review
┌─────────────────────────────────────────────────────────┐│ Agentic Workflow Example │├─────────────────────────────────────────────────────────┤│ ││ User: "Fix the bug where customers lose points" ││ ││ Agent: ││ ├── 1. Search for "points" in services/ ││ ├── 2. Read pointsService.js ││ ├── 3. Identify bug in calculatePoints() ││ ├── 4. Read related test file ││ ├── 5. Edit pointsService.js to fix bug ││ ├── 6. Run tests to verify fix ││ └── 7. Report results to user ││ ││ All without asking user at each step! ││ │└─────────────────────────────────────────────────────────┘Getting Started
Section titled “Getting Started”Prerequisites
Section titled “Prerequisites”- Install Claude Code CLI:
npm install -g @anthropic-ai/claude-code-
Navigate to your project directory (must contain
.claudefolder) -
Start Claude Code:
claudeFolder Structure
Section titled “Folder Structure”.claude/├── commands/ # Slash commands (/review, /debug, etc.)├── agents/ # Specialized AI agents for complex tasks├── skills/ # Domain knowledge (Firestore, Shopify, etc.)├── workflows/ # Development rules and standards└── settings.local.json # Local configurationCommands
Section titled “Commands”Commands are quick actions invoked with /command-name. They provide focused, single-purpose assistance.
Common Workflow
Section titled “Common Workflow”The typical development flow follows this pattern:
┌─────────────────────────────────────────────────────────┐│ Standard Development Workflow │├─────────────────────────────────────────────────────────┤│ ││ /plan THIS IS WHERE YOU THINK ││ │ - Research codebase & Shopify APIs ││ │ - If MCP browsing forever, give docs ││ │ - Ask Claude to write plan to .md file ││ │ - Make it as detailed as possible ││ ▼ ││ Implement WORK ALONGSIDE CLAUDE ││ │ - "Implement the plan step by step" ││ │ - Fix bugs together as they appear ││ │ - Brainstorm updates, pivot if needed ││ │ - /review can be called mid-process ││ ▼ ││ /docs DOCUMENT THE CHANGES ││ │ - If scope changed, document it ││ │ - Capture all features implemented ││ ▼ ││ /review CODE REVIEW (can use anytime) ││ │ - Check standards compliance ││ │ - Security & performance audit ││ │ - Fix any issues found ││ ▼ ││ /lint-mr FINAL CLEANUP ││ │ - ESLint fix all changed files ││ │ - Ensure CI will pass ││ ▼ ││ Ready for MR! ││ │└─────────────────────────────────────────────────────────┘The /plan Phase - This Is Where You Think
Section titled “The /plan Phase - This Is Where You Think”Don’t outsource the thinking. The planning phase is where YOU drive the direction:
> /plan add VIP tier sync to Shopify metafieldsWhat happens:
- Claude researches your codebase (grep, glob, read)
- Claude uses MCP to browse Shopify docs
- Claude proposes an approach
Your role during /plan:
┌─────────────────────────────────────────────────────────┐│ Active Planning (Not Passive!) │├─────────────────────────────────────────────────────────┤│ ││ ❌ DON'T: Just say "/plan X" and accept whatever ││ ││ ✅ DO: ││ • Guide Claude when it's stuck browsing MCP forever ││ "Here's the metafield mutation docs: [paste]" ││ ││ • Ask for specific details ││ "What about rate limiting? What if there are ││ 10,000 customers?" ││ ││ • Request the plan in a file ││ "Write this plan to docs/plans/vip-sync.md" ││ ││ • Make it detailed ││ "Include Firestore indexes needed" ││ "Add error handling strategy" ││ "List all files that will be created/modified" ││ │└─────────────────────────────────────────────────────────┘Example planning session:
> /plan add VIP tier sync to Shopify metafields
# Claude starts researching...
> Focus on bulk operations since we have 50k customers.> Here's the bulkOperationRunMutation docs: [paste URL or content]
# Claude refines the approach
> Write this plan to docs/plans/vip-tier-sync.md> Include: files to create, Firestore indexes, error handling,> rate limit strategy, and testing approach
# Claude writes detailed plan to file# YOU review the .md file, suggest changes
> Update the plan: we also need a retry queue for failed syncs
# Claude updates the plan file# When satisfied, move to implementationThe Implementation Phase - Work Alongside Claude
Section titled “The Implementation Phase - Work Alongside Claude”This is collaborative, not hands-off:
> Implement the plan in docs/plans/vip-tier-sync.md step by stepWhat to expect:
- Claude creates a Todo list from the plan
- Works through each step
- Bugs WILL happen - this is normal
- You debug together, brainstorm solutions
- Scope may change - that’s okay
┌─────────────────────────────────────────────────────────┐│ Implementation Reality │├─────────────────────────────────────────────────────────┤│ ││ You: "Implement the plan step by step" ││ ││ Claude: ✓ Creating VIPSyncService... ││ ✓ Adding Firestore indexes... ││ ▶ Implementing bulk mutation... ││ ✗ Error: Rate limit exceeded ││ ││ You: "Let's add exponential backoff. Check how we ││ handle this in klaviyoService.js" ││ ││ Claude: Found the pattern, implementing... ││ ✓ Added retry logic with backoff ││ ▶ Moving to webhook handler... ││ ││ You: "Wait, we should also handle partial failures. ││ What if 50 out of 100 items fail?" ││ ││ Claude: Good point. Let me add a failure queue... ││ ││ [This back-and-forth IS the process] ││ │└─────────────────────────────────────────────────────────┘Mid-process review is encouraged:
# After implementing a complex service> /review packages/functions/src/services/vipSyncService.js
# Claude reviews, finds issues# Fix them before continuingThe Documentation Phase - Capture What Changed
Section titled “The Documentation Phase - Capture What Changed”If scope changed during implementation (it usually does), document it:
> /docs vip-tier-sync
# Claude documents:# - What was actually implemented (vs original plan)# - New features added during implementation# - Configuration options# - Usage examplesThe Final Review Phase
Section titled “The Final Review Phase”# Review all changes> /review
# Fix any issues found
# ESLint cleanup> /lint-mr
# Ready for MR!Real-World Example Session
Section titled “Real-World Example Session”# 1. PLAN (30 min of thinking)> /plan sync customer VIP tier to Shopify customer metafield
> The bulk operations approach looks right. Can you write the> full plan to docs/plans/vip-sync.md? Include error handling> for rate limits and partial failures.
> Also add a section on how to test this locally
# 2. IMPLEMENT (work together)> Implement the plan step by step
> Hmm that webhook handler looks complex. Let's /review it now> /review packages/functions/src/handlers/vipSyncHandler.js
> Good catches. Fix those issues and continue.
> Wait, we forgot about shops with 100k+ customers.> Let's add pagination to the sync job.
# 3. DOCUMENT (if scope changed)> /docs vip-sync> We added pagination and a retry queue that wasn't in the> original plan. Make sure to document those.
# 4. FINAL CLEANUP> /review> /lint-mr
# Ready for MR!Available Commands
Section titled “Available Commands”| Command | Description | Usage |
|---|---|---|
/review | Code review following Avada standards | /review or /review path/to/file.js |
/debug [issue] | Investigate and diagnose issues | /debug webhook not firing |
/fix [issue] | Analyze and fix issues | /fix type errors in customerService |
/plan [task] | Create implementation plan | /plan add bulk tagging feature |
/test | Run tests and validate code quality | /test |
/security | Security audit (OWASP Top 10) | /security |
/perf | Performance analysis | /perf |
/impact | Analyze change impact before MR | /impact |
/label | Check UI labels for Polaris guidelines | /label CustomerPage |
/translate | Update translations after label changes | /translate |
/lint-mr | ESLint fix all files in current MR | /lint-mr |
/docs [feature] | Generate documentation for changes | /docs new-webhook-handler |
Using Commands
Section titled “Using Commands”# In Claude Code CLI> /review
# With arguments> /debug orders not syncing to Shopify
# Target specific files> /review packages/functions/src/services/customerService.jsThe /review command performs a comprehensive code review:
- Code Quality: Naming conventions, patterns, early returns
- Architecture: Layer separation (handlers → services → repositories)
- Performance: Firestore optimization, React patterns
- Security: OWASP Top 10, credential exposure
- Shopify: Polaris patterns, webhook handling
Output includes severity levels (Critical, High, Medium, Low) with specific fixes.
The /plan command creates implementation plans without writing code:
> /plan sync customer loyalty tier to Shopify metafieldOutput includes:
- Research findings (existing patterns, API strategy)
- Volume analysis and cost estimation
- Step-by-step implementation phases
- Firestore schema and indexes
- Risk assessment
Skills
Section titled “Skills”Skills provide domain-specific knowledge that Claude uses during conversations. They contain best practices, patterns, and standards for specific technologies.
Available Skills
Section titled “Available Skills”Core Skills:
| Skill | Trigger Keywords | What It Provides |
|---|---|---|
firestore | Firestore, queries, batch, TTL | Query optimization, pagination, write limits |
backend | handlers, services, repositories | Node.js/Firebase patterns, async/await |
avada-architecture | project structure, layers | Folder structure, naming conventions |
api-design | REST API, endpoints, validation | API patterns, response formats |
Shopify Skills:
| Skill | Trigger Keywords | What It Provides |
|---|---|---|
shopify-api | GraphQL, Admin API, webhooks | API patterns, rate limiting, HMAC |
shopify-bulk-operations | bulk sync, mass update, JSONL | Bulk API for 500+ items |
polaris | Polaris, Button, Card, Modal | Polaris v12+ component patterns |
scripttag | storefront, widget, Preact | Lightweight customer-facing widgets |
Infrastructure Skills:
| Skill | Trigger Keywords | What It Provides |
|---|---|---|
cloud-tasks | background jobs, queue, delayed | Async task processing, rate limit handling |
redis-caching | Redis, cache, TTL | Caching patterns, circuit breaker |
bigquery | BigQuery, analytics, SQL | Query optimization, partitioning |
security | OWASP, authentication, IDOR | Security audit patterns |
Frontend Skills:
| Skill | Trigger Keywords | What It Provides |
|---|---|---|
frontend | React admin, translations, hooks | Admin app patterns, i18n |
langchain | LangGraph, agents, tools | AI agent development patterns |
How Skills Work
Section titled “How Skills Work”Skills are automatically loaded when relevant. For example:
- Discussing Firestore queries →
firestore.mdskill activates - Working on API handlers →
backend.mdandavada-architecture.mdactivate - Shopify integration work →
shopify-api.mdskill activates
Key Patterns from Skills
Section titled “Key Patterns from Skills”// ❌ BAD: Fetch all, filter in JSconst all = await customersRef.get();const active = all.docs.filter(d => d.data().status === 'active');
// ✅ GOOD: Filter in queryconst active = await customersRef .where('status', '==', 'active') .where('shopId', '==', shopId) // Always scope by shop .limit(100) // Always limit .get();import {enqueueTask} from '../services/cloudTaskService';
// Enqueue background task with delayawait enqueueTask({ functionName: 'enqueueSubscriber', opts: {scheduleDelaySeconds: 3}, // Wait for Shopify consistency data: { type: 'syncCustomerTier', data: {shopId, customerId} }});
// Handle rate limits by re-enqueueingif (result.retryAfter) { await enqueueTask({ data: {type: 'klaviyoSync', data: {..., retryCount: retryCount + 1}}, opts: {scheduleDelaySeconds: Math.ceil(result.retryAfter)} });}import {Page, Card, BlockStack, Button, Text} from '@shopify/polaris';import {PlusIcon} from '@shopify/polaris-icons'; // v9 icons (no Minor/Major)
function CustomerPage() { return ( <Page title="Customers" primaryAction={{content: 'Add', onAction: handleAdd}}> <Card> <BlockStack gap="400"> <Text variant="headingMd">Customer List</Text> {/* ✅ Use url for navigation */} <Button url="/settings">Settings</Button> {/* ✅ Icon button */} <Button icon={PlusIcon}>Add tier</Button> </BlockStack> </Card> </Page> );}// When to use: 500+ items to update
// Step 1: Prepare JSONLconst jsonl = customers.map(c => JSON.stringify({ metafields: { key: 'points', namespace: 'loyalty', ownerId: `gid://shopify/Customer/${c.id}`, value: String(c.points), type: 'number_integer' }})).join('\n');
// Step 2: Upload via staged uploads// Step 3: Run bulkOperationRunMutation// Step 4: Handle BULK_OPERATIONS_FINISH webhookAgents
Section titled “Agents”Agents are specialized AI assistants for complex, multi-step tasks. Unlike commands, agents maintain context throughout extended workflows.
Available Agents
Section titled “Available Agents”| Agent | Purpose | When to Use |
|---|---|---|
code-reviewer | Comprehensive code review | PR reviews, architecture validation |
debugger | Issue investigation | Complex bugs, tracing execution |
planner | Implementation planning | New features, architectural decisions |
tester | Test suite validation | Pre-merge checks, coverage analysis |
security-auditor | Security analysis | Audit endpoints, data handling |
performance-reviewer | Performance optimization | Bottleneck identification |
shopify-app-tester | Shopify app testing | App store submission prep |
Agent Capabilities
Section titled “Agent Capabilities”The code-reviewer agent provides senior-level code review:
Review Focus:
- Avada Development Standards v1.0 compliance
- Architecture violations (handler/service/repository separation)
- Naming conventions (camelCase, PascalCase, UPPER_SNAKE_CASE)
- Performance bottlenecks
- Security vulnerabilities (OWASP Top 10)
- Shopify Polaris patterns
Output Format:
- Executive summary with compliance score
- Findings by severity (Critical → Low)
- Positive feedback on good patterns
- Code examples with before/after
- Pre-merge checklist
The debugger agent traces issues through your codebase:
Capabilities:
- Analyze logs and error messages
- Trace execution: handlers → services → repositories
- Identify root cause with evidence
- Provide fix recommendations
Common Debug Targets:
- Firebase Functions logs
- Shopify webhook delivery
- Firestore query performance
- API endpoint failures
- CI/CD pipeline issues
The planner agent creates comprehensive implementation plans:
Process:
- Research - Explore codebase, find existing patterns
- Shopify API Research - Use MCP tools for API discovery
- Volume Analysis - Regular API vs Bulk Operations
- Cost Analysis - Evaluate triggers and Firebase usage
- Risk Assessment - Rate limits, edge cases, multi-tenant
Output: A detailed plan saved to docs/plans/{feature-slug}.md
Workflows
Section titled “Workflows”Workflows define development rules and standards that Claude follows during all interactions.
Development Rules
Section titled “Development Rules”The development-rules.md workflow enforces:
Principles:
- YAGNI - You Aren’t Gonna Need It
- KISS - Keep It Simple, Stupid
- DRY - Don’t Repeat Yourself
Code Standards:
Naming:├── camelCase → variables, functions, properties├── PascalCase → classes, React components├── UPPER_SNAKE_CASE → constants├── verb prefix → functions (getUserData, calculatePoints)└── is/has prefix → booleans (isActive, hasPermission)
Patterns:├── Prefer const over let├── Use === instead of ==├── Prefer async/await over promises├── >3 params → use object destructuring├── Early return pattern└── Single responsibility functionsBackend Structure:
packages/functions/src/├── handlers/ # Controllers - orchestrate ONLY├── services/ # Business logic, combine repos├── repositories/ # ONE collection per repo - NEVER mix├── helpers/ # Small utilities├── presenters/ # Format output data├── const/ # Constants by domain└── config/ # ConfigurationBest Practices
Section titled “Best Practices”1. Use Mentions and Paste URLs
Section titled “1. Use Mentions and Paste URLs”Claude Code can fetch URLs directly. When discussing Shopify APIs or any documentation:
# Paste a URL - Claude will fetch it> Check this API: https://shopify.dev/docs/api/admin-graphql/2024-01/mutations/metafieldsSet
# Use @ to mention files> Review @packages/functions/src/services/customerService.js2. Always Save Plans to .md Files
Section titled “2. Always Save Plans to .md Files”Plans are valuable artifacts. Save them for reference:
> /plan add VIP tier sync
# After discussion...> Write this plan to docs/plans/vip-tier-sync.md> Include all the details we discussedWhy this matters:
- Reference during implementation
- Share with team for review
- Compare with what actually got built
- Onboard new team members
3. Paste Images for Reference
Section titled “3. Paste Images for Reference”Claude Code is multimodal. Drag-and-drop or paste images:
# Paste a screenshot of the UI you want> Here's the design mock [paste image]> Implement this layout
# Paste an error screenshot> I'm seeing this error [paste image]> What's causing it?Works great for:
- Design mocks
- Error screenshots
- Architecture diagrams
- Figma exports
4. Be Specific - Don’t Just Say “Fix It”
Section titled “4. Be Specific - Don’t Just Say “Fix It””┌─────────────────────────────────────────────────────────┐│ Good vs Bad Instructions │├─────────────────────────────────────────────────────────┤│ ││ ❌ BAD: "Fix the bug" ││ ❌ BAD: "Make it work" ││ ❌ BAD: "Improve this" ││ ││ ✅ GOOD: "The webhook handler is returning 500 when ││ shopId is null. Add null check and return ││ 400 with clear error message" ││ ││ ✅ GOOD: "This query is slow because it's fetching ││ all customers then filtering. Move the ││ filter to the Firestore query" ││ ││ ✅ GOOD: "Follow the pattern in klaviyoService.js ││ for the retry logic with exponential backoff"││ │└─────────────────────────────────────────────────────────┘Give Claude:
- The WHY (context)
- The WHAT (expected behavior)
- The DIRECTION (approach or reference)
This helps Claude become a better assistant over time.
5. Read Code Before Writing Code
Section titled “5. Read Code Before Writing Code”Every step of a good developer is still the same. You just have a friend who does the mechanics:
# First, understand the code> Read customerService.js and explain how points calculation works
# Then, understand the context> What other services call this? Check for usages
# Now, plan the change> I want to add bonus multipliers. How would you approach this?
# Finally, implement> Implement it following the existing patternsThe developer workflow doesn’t change:
- Understand existing code
- Plan your approach
- Implement
- Review and test
Claude accelerates each step, but YOU still drive the thinking.
6. Use Keyboard Shortcuts and Modes
Section titled “6. Use Keyboard Shortcuts and Modes”┌─────────────────────────────────────────────────────────┐│ Essential Shortcuts │├─────────────────────────────────────────────────────────┤│ ││ Shift + Tab Toggle auto-edit mode ││ (Claude edits without asking) ││ ││ Escape Interrupt Claude (keeps context) ││ ││ Escape x2 Edit your previous prompt ││ ││ Tab Autocomplete file paths ││ │└─────────────────────────────────────────────────────────┘Modes:
- Plan mode: Claude researches and proposes, doesn’t write code
- Auto-edit mode (Shift+Tab): Claude edits files without confirmation
7. Manage Context with /clear and /compact
Section titled “7. Manage Context with /clear and /compact”Long conversations degrade quality. Reset when needed:
# Start fresh between unrelated tasks> /clear
# Keep summary, remove details> /compactWhen to /clear:
- Starting a new feature
- Context got polluted with errors
- Claude seems confused or repetitive
8. Multi-Claude: Run Multiple Sessions
Section titled “8. Multi-Claude: Run Multiple Sessions”Run separate Claude instances on different parts of your project:
# Terminal 1: Working on backendcd packages/functions && claude
# Terminal 2: Working on frontendcd packages/scripttag && claude
# Terminal 3: Working on admincd packages/admin && claudeUsing Git Worktrees for parallel work:
# Create separate worktrees for featuresgit worktree add ../project-feature-a feature-agit worktree add ../project-feature-b feature-b
# Run Claude in eachcd ../project-feature-a && claudecd ../project-feature-b && claude9. Let Claude Read Before It Writes
Section titled “9. Let Claude Read Before It Writes”Ask Claude to explore first:
# Don't immediately ask for changes> Read the authentication flow and explain it to me
# Then ask for the plan> How would you add OAuth support?
# Then implement> Implement OAuth following that plan10. Use CLAUDE.md for Project Context
Section titled “10. Use CLAUDE.md for Project Context”Create a CLAUDE.md in your project root:
# Project: Joy Loyalty
## Quick Commands- `yarn dev` - Start development- `yarn test` - Run tests- `yarn lint` - Check linting
## Architecture- Handlers → Services → Repositories- One repo per Firestore collection
## Code Style- Use early returns- Prefer async/await- camelCase for functionsClaude automatically reads this at the start of each session.
11. Reference Patterns, Don’t Describe Them
Section titled “11. Reference Patterns, Don’t Describe Them”# ❌ BAD: Lengthy description of the pattern> Implement error handling with try-catch, log the error,> return a structured response with success: false...
# ✅ GOOD: Point to existing code> Implement error handling following the pattern in> @packages/functions/src/handlers/customerHandler.jsClaude will read the file and replicate the pattern.
12. Use Escape to Course-Correct
Section titled “12. Use Escape to Course-Correct”If Claude is going in the wrong direction:
You: Implement the sync feature
Claude: [starts writing a complex solution]
You: [Press Escape]
You: Wait, let's use a simpler approach. Just use the existing syncService pattern instead of creating new.
Claude: [adjusts approach]Pressing Escape interrupts without losing context.
More best practices: Anthropic Engineering Blog - Claude Code Best Practices
MCP Servers (Model Context Protocol)
Section titled “MCP Servers (Model Context Protocol)”MCP extends Claude Code’s capabilities by connecting to external tools and services. Think of MCP servers as “plugins” that give Claude new abilities.
What is MCP?
Section titled “What is MCP?”┌─────────────────────────────────────────────────────────┐│ MCP Architecture │├─────────────────────────────────────────────────────────┤│ ││ Claude Code ││ │ ││ ├── Built-in Tools (grep, read, edit, bash) ││ │ ││ └── MCP Servers (external capabilities) ││ │ ││ ├── shopify-dev-mcp → Shopify API docs ││ ├── chrome-devtools → Browser debugging ││ └── playwright → Browser automation ││ │└─────────────────────────────────────────────────────────┘Default MCP Configuration
Section titled “Default MCP Configuration”Add this to your ~/.claude/mcp_config.json:
{ "mcpServers": { "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] }, "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] }, "playwright": { "command": "npx", "args": ["-y", "@anthropic/mcp-playwright@latest"] } }}Available MCP Servers
Section titled “Available MCP Servers”Purpose: Access Shopify API documentation and GraphQL schema introspection
Capabilities:
search_docs_chunks- Search Shopify developer documentationintrospect_graphql_schema- Explore GraphQL types, queries, mutationsfetch_full_docs- Get complete documentation pageslearn_shopify_api- Learn about specific API features
Example Usage:
> What's the GraphQL mutation for updating customer metafields?
# Claude uses MCP to search Shopify docs and returns accurate API infoWhy It’s Essential:
- Always up-to-date API information
- No need to manually search docs
- Accurate GraphQL schema details
- Helps
/plancommand research Shopify APIs
Purpose: Debug and inspect running web applications
Capabilities:
take_snapshot- Capture current page statelist_console_messages- View console logs/errors- Inspect network requests
- Debug JavaScript execution
Example Usage:
> Check the console for errors on the current page
# Claude connects to Chrome and reads console messagesUse Cases:
- Debug storefront widget issues
- Inspect API responses
- Check for JavaScript errors
- Verify DOM structure
Purpose: Browser automation and testing
Capabilities:
browser_navigate- Go to URLsbrowser_click- Click elementsbrowser_fill_form- Fill form fieldsbrowser_snapshot- Capture accessibility treebrowser_take_screenshot- Visual screenshotsbrowser_console_messages- Read console
Example Usage:
> Navigate to our admin dashboard and check if the VIP badge displays correctly
# Claude opens browser, navigates, and verifies the UIUse Cases:
- Visual testing of UI changes
- End-to-end workflow testing
- Screenshot documentation
- Form interaction testing
MCP in Action: Planning with Shopify API Research
Section titled “MCP in Action: Planning with Shopify API Research”When you run /plan, Claude uses MCP to research Shopify APIs:
┌─────────────────────────────────────────────────────────┐│ /plan with MCP Integration │├─────────────────────────────────────────────────────────┤│ ││ > /plan sync customer tier to Shopify metafield ││ ││ Claude's Process: ││ ┌────────────────────────────────────────────────┐ ││ │ 1. Grep codebase for existing metafield code │ ││ │ │ ││ │ 2. MCP: introspect_graphql_schema │ ││ │ → Find metafieldsSet mutation │ ││ │ → Check input types │ ││ │ │ ││ │ 3. MCP: search_docs_chunks "bulk metafields" │ ││ │ → Find bulk operation patterns │ ││ │ → Check rate limits │ ││ │ │ ││ │ 4. Synthesize into implementation plan │ ││ └────────────────────────────────────────────────┘ ││ ││ Result: Accurate plan with real API details ││ │└─────────────────────────────────────────────────────────┘Setting Up MCP
Section titled “Setting Up MCP”- Create config file:
mkdir -p ~/.claudetouch ~/.claude/mcp_config.json- Add server configuration:
# Edit ~/.claude/mcp_config.json with the config above- Restart Claude Code:
# Exit and restart claudeclaude- Verify servers are loaded:
> /mcp
# Should show connected serversCustomizing Your Setup
Section titled “Customizing Your Setup”Adding a New Command
Section titled “Adding a New Command”Create a file in .claude/commands/:
---description: Short description shown in helpargument-hint: [optional arguments]---
## Instructions
Your command instructions here.
## Reference Skills- `.claude/skills/relevant-skill.md`Adding a New Skill
Section titled “Adding a New Skill”Create a file in .claude/skills/:
# Skill Name
## When to UseDescribe when this skill applies.
## Patterns
### Pattern 1```javascript// Code examplesAnti-patterns
Section titled “Anti-patterns”// What NOT to do### Adding a New Agent
Create a file in `.claude/agents/`:
```markdown---name: agent-namedescription: When and how to use this agent with examplesmodel: sonnet # or opus for complex taskscolor: blue---
# Agent Title
You are an expert in [domain]. Your responsibilities:
## Core Responsibilities- Task 1- Task 2
## Process1. Step 12. Step 2
## Output FormatDescribe expected output format.Troubleshooting
Section titled “Troubleshooting”Command Not Found
Section titled “Command Not Found”Ensure you’re in a directory with a .claude folder:
ls -la .claude/commands/Agent Not Responding as Expected
Section titled “Agent Not Responding as Expected”- Check agent description matches your use case
- Verify referenced skills exist
- Try being more specific in your request
Skills Not Loading
Section titled “Skills Not Loading”Skills load based on conversation context. Explicitly mention the technology:
> Help me optimize this Firestore queryVideo Resources
Section titled “Video Resources”Recommended Watching
Section titled “Recommended Watching”Key Takeaways
Section titled “Key Takeaways”┌─────────────────────────────────────────────────────────┐│ Agentic Development Mindset │├─────────────────────────────────────────────────────────┤│ ││ 1. PLAN IS EVERYTHING ││ Good plan → Great implementation ││ Skip planning → Waste time fixing ││ ││ 2. DON'T OUTSOURCE THE THINKING ││ YOU: Strategy, decisions, architecture ││ AI: Mechanics, implementation, boilerplate ││ ││ 3. SKILLS & COMMANDS ARE YOUR SHORTCUTS ││ /plan → Research & design ││ /review → Quality check ││ /fix → Quick fixes ││ Skills → Domain knowledge on-demand ││ ││ 4. PROTOTYPE → DEMO → LOOP ││ Build fast, show early, iterate often ││ This is the future of solution development ││ │└─────────────────────────────────────────────────────────┘The Human + AI Partnership
Section titled “The Human + AI Partnership”┌─────────────────────────────────────────────────────────┐│ ││ HUMAN (You) AI (Claude) ││ ──────────── ────────── ││ • Vision • Research ││ • Strategy • Code generation ││ • Decisions • Pattern matching ││ • Architecture • Refactoring ││ • Code review • Documentation ││ • Quality gates • Testing ││ ││ "Think like an architect, let AI be your builder" ││ │└─────────────────────────────────────────────────────────┘