# How I Built vybecoding.ai: Zero Code, 100% AI Workflow The exact workflow behind this production platform — from first prompt to monetized product. No hand-written code. Every line generated by AI. If you're reading this on vybecoding.ai, you're looking at the result. This guide walks you through the complete process: environment setup, BMAD methodology, AI assistant configuration, security, testing, deployment, automation, and monetization. Start at Module 1. Paste prompts into your AI coding assistant (Claude Code, Cursor, or similar). --- # Course Overview & Learning Outcomes You're on vybecoding.ai right now. This platform — every page, every feature, every API route — was built using the workflow in this guide. No hand-written code. 100% AI-generated, human-directed. This course teaches you how to do the same thing. #### What You'll Learn #### Core Development Skills - The exact environment setup I use daily (Claude Code, BMAD v6, MCP servers) - How to scaffold production-ready Next.js applications with AI assistance - Testing strategies with Playwright that catch real bugs - CI/CD pipelines and deployment workflows that ship reliably - Troubleshooting techniques that saved me hours on this platform 💡 **What is CI/CD (Continuous Integration/Continuous Deployment)?** CI/CD is like an automated assembly line for your code. It automatically tests your changes and deploys them to production when everything looks good. Example: When you save code changes, CI/CD automatically runs tests, checks for errors, and if everything passes, publishes your app live. 💡 **What is E2E Testing?** End-to-End testing simulates a real user clicking through your entire application to make sure everything works together correctly. Example: Instead of testing individual buttons, E2E testing opens your app like a user would and tests the complete workflow from login to checkout. #### AI-Powered Development - Master context-first development methodologies - Understand the spectrum from vibe coding to Spec-Driven Development - Use BMAD v6 (Breakthrough Method for Agile AI-Driven Development) - Configure skills, hooks, and MCP servers for your AI workflow - Orchestrate multi-agent teams for parallel development - Validate and refine AI-generated solutions with security awareness 💡 **What are API Endpoints?** API endpoints are specific URLs where your application can send and receive data. Think of them as postal addresses where different parts of your app can send messages to each other. Example: `/api/users` might be an endpoint where your app gets user information, like a mailbox specifically for user-related mail. 💡 **What is Middleware?** Middleware is code that runs between a request and response, like a security guard checking IDs before letting people into a building. Example: Authentication middleware checks if a user is logged in before allowing them to access protected pages. 💡 **What is DevOps?** DevOps combines development and operations - it's about making sure your code runs smoothly from your computer to production servers. Example: DevOps is like having a skilled mechanic who not only builds cars but also maintains the roads they drive on. #### Professional Practices - Follow security best practices including AI-specific risk mitigations - Implement proper error handling and logging - Create maintainable and scalable codebases - Document projects effectively with AI assistance - Collaborate effectively using agent teams and automation #### Prerequisites #### Technical Requirements - **Basic Programming Knowledge**: Understanding of JavaScript/TypeScript, HTML, and CSS - **Command Line Familiarity**: Comfortable with terminal/command prompt operations - **Git Experience**: Basic version control and repository management - **Development Environment**: VS Code or similar editor installed - **Node.js**: Version 20+ installed on your system 💡 **What is Node.js?** Node.js is a JavaScript runtime that allows you to run JavaScript code outside of a web browser. Think of it as the engine that powers modern web development tools and servers. Example: Just like how Chrome runs JavaScript in your browser, Node.js runs JavaScript on your computer. 💡 **What is TypeScript?** TypeScript is JavaScript with additional type checking that helps catch errors before your code runs. It's like having a spell-checker for your code that prevents common programming mistakes. Example: Instead of `let name = "John"`, TypeScript lets you write `let name: string = "John"` to ensure name is always text. 💡 **What is a CLI (Command Line Interface)?** A CLI is a text-based interface where you type commands instead of clicking buttons. It's like texting with your computer to give it instructions. Example: Instead of double-clicking an icon, you might type `npm start` to launch an application. #### Recommended Skills - Experience with React or similar frameworks - Basic understanding of web development concepts - Familiarity with package managers (npm, yarn) - Previous exposure to testing frameworks #### Course Structure This beginner level course consists of 12 modules with **32 lessons**, taking approximately 8-12 hours to complete. #### Module Breakdown **Module 1: Environment Setup and Prerequisites** (4 lessons) - Install VS Code and Core Extensions - Understanding Safety Guardrails and Risk Management - Verify Development Prerequisites - Create Project Directory Structure and Connect to GitHub **Module 2: The AI Development Spectrum** (3 lessons) - From Vibe Coding to Spec-Driven Development - Context Engineering Fundamentals - Your Context Stack **Module 3: BMAD METHOD v6 Installation** (1 lesson) - Install and Configure BMAD METHOD v6 **Module 4: AI Assistant Configuration** (3 lessons) - Claude Code Configuration and BMAD Integration - Understanding Skills and Slash Commands - Configuring MCP Servers **Module 5: Development Fundamentals and Security** (3 lessons) - Essential Glossary and Concepts - Development Safety Rules and Best Practices - AI-Specific Security Risks and Mitigations **Module 6: Application Development** (2 lessons) - Scaffold Next.js Application - Environment Configuration and Health Monitoring **Module 7: Testing Infrastructure** (2 lessons) - Playwright Installation and Configuration - Test Strategy and Coverage Setup **Module 8: Deployment and Operations** (2 lessons) - CI/CD Pipeline with GitHub Actions - Monitoring, Security, and Performance **Module 9: Troubleshooting, Visual Guides and Documentation** (4 lessons) - Common Issues Decision Trees - Getting Help and Documentation Templates - VS Code UI Navigation Guide - Project Documentation Templates **Module 10: Agent Teams, Hooks and Automation** (3 lessons) - Claude Code Hooks - Multi-Agent Workflows with Worktrees - Automation Patterns **Module 11: MCP Ecosystem and Browser Debugging** (5 lessons) - Understanding the Model Context Protocol (MCP) - Configuring Common MCP Servers - Chrome DevTools MCP Setup and Debugging - BMAD Repair Loop Using DevTools MCP - Ship the Fix with Guardrails **Module 12: From Idea to Monetized Product** (3 lessons) - Master BMAD Orchestrator single-prompt workflow - Audience research & positioning (optional) - Pricing experiment runner (optional) #### Learning Outcomes By the end of this course, you will be able to: 1. **Set up a complete AI development environment** with Claude Code, MCP servers, and BMAD v6 2. **Understand context engineering** and the spectrum from vibe coding to Spec-Driven Development 3. **Build a full-stack Next.js application** from scratch using AI assistance 4. **Implement comprehensive testing** with Playwright and MCP-integrated debugging 5. **Deploy applications professionally** with CI/CD pipelines and monitoring 6. **Secure AI-generated code** against hallucinated dependencies, OWASP vulnerabilities, and secret leakage 7. **Orchestrate agent teams** with hooks, worktrees, and automation patterns 8. **Create maintainable codebases** following context-first best practices #### Time Investment - **Total Duration**: ~10 hours - **Hands-on Practice**: ~6 hours - **Theory and Setup**: ~4 hours - **Recommended Pace**: 2-3 modules per week - **Support**: Access to troubleshooting guides and community forums #### Getting Started Ready to begin? Let's start with setting up your AI development environment in the next lesson. Make sure you have: ✅ A computer with internet connection ✅ Administrator/sudo access for installations ✅ VS Code or similar editor ✅ Basic command line knowledge ✅ Enthusiasm for AI-powered development! --- #### 🔧 BMAD METHOD v6: Complete Installation Guide This section consolidates all BMAD installation instructions referenced throughout the course. Choose your preferred installation method and return here whenever you need installation guidance. 💡 **What is Git Submodule?** A Git submodule is like a folder within your project that contains another complete project. Think of it as including a library inside your main project while keeping them separate. Example: Your main project is a house, and the submodule is a pre-built bathroom that you install - it's part of your house but maintained separately.

📦 Method 1: Git Submodule (Recommended for Teams)

**Best for**: Teams, version control, collaborative projects ```bash # Navigate to your project root cd your-project # Add BMAD as a submodule using canonical repository URL git submodule add https://github.com/bmad-code-org/BMAD-METHOD .bmad-method git submodule update --init --recursive # Optional: Pin to specific version for stability git -C .bmad-method fetch --tags # Pin to latest tag automatically: LATEST_TAG=$(git -C .bmad-method describe --tags "$(git -C .bmad-method rev-list --tags --max-count=1)") git -C .bmad-method checkout "$LATEST_TAG" # Run the installer from the submodule (non-interactive) node .bmad-method/tools/installer/bin/bmad.js install --full --directory . --ide claude-code ``` ✅ **Benefits**: Version controlled, team sync, easy updates, consistent environments ⚠️ **Requirements**: Git repository setup, submodule knowledge

📁 Method 2: NPX Installation (Recommended for Solo Projects)

**Best for**: Individual projects, quick setup, latest features ```bash # Navigate to your project root cd your-project # Verify Node.js version (BMAD v6 requires >= 20) node -v # Install BMAD non-interactively for Claude Code; verify status npx bmad-method@latest install --full --directory . --ide claude-code # Verify installation npx bmad-method status echo "✅ BMAD v6 installation complete!" # Alternative: Add as dev dependency npm i -D bmad-method npm pkg set scripts.install:bmad="bmad-method install --full --directory . --ide claude-code" npm run install:bmad ``` ✅ **Benefits**: Always latest version, simple setup, immediate access ⚠️ **Note**: Requires Node.js 20+, manual updates for pinned versions

🔗 Method 3: Reference Integration (Custom Setups)

**Best for**: Custom workflows, selective features, existing toolchains ```bash # Create bmad directory structure mkdir -p bmad/config bmad/templates bmad/tools # Download specific BMAD components you need # (Refer to BMAD documentation for component URLs) # Create basic configuration cat > bmad/config/bmad.json << 'EOF' { "version": "custom", "features": ["planning", "review"], "integration": "manual" } EOF ``` ✅ **Benefits**: Lightweight, customizable, no version dependencies ⚠️ **Limitations**: Manual maintenance, reduced functionality, custom integration required

**Verification Commands:** ```bash # Check BMAD v6 installation status npx bmad-method status # or (if using submodule) node .bmad-method/tools/installer/bin/bmad.js status # Verify Claude Code skills integration ls -la .claude/skills/ | grep bmad # Verify v6 directory structure ls -la _bmad/core/ # Test basic BMAD workflow echo "BMAD v6 installation complete! ✅" ``` --- #### 🛡️ Development Safety Center This section consolidates all safety guidelines, guardrails, and best practices referenced throughout the course. Bookmark this section for quick reference during development.

🚨 Guardrails System: Choose Your Safety Level

**Before proceeding with any development task**, select your preferred safety level: #### Low (Fast) - Power User Mode - **Usage**: Preface commands with `Guardrails: Low` - **Behavior**: Minimal confirmations, proceed with sensible defaults - **Config**: `planMode=false`, `autoApprove=true`, `skipPermissions=true` - **Best for**: Experienced developers, rapid prototyping, familiar workflows - **Confirms only**: Destructive operations, production deployments #### Medium (Balanced) - Default Mode - **Usage**: No preface needed (default behavior) - **Behavior**: Confirm file creates/overwrites and installs, show diffs, pause after major steps - **Config**: `planMode=true`, `autoApprove=false`, `skipPermissions=false` - **Best for**: Most development scenarios, learning, collaborative work - **Confirms**: File changes, installations, network operations #### High (Strict) - Maximum Safety - **Usage**: Preface commands with `Guardrails: High` - **Behavior**: Step-by-step approvals, dry-run commands first, explicit approval for all operations - **Config**: Enhanced safety with additional confirmation layers - **Best for**: Production environments, critical systems, unfamiliar codebases - **Confirms**: Every command, all file operations, all network requests

🔐 Code Safety Guidelines

#### Critical Safety Rules ⚠️ **NEVER** run destructive commands without verification: ```bash # Dangerous - always verify target rm -rf * git reset --hard HEAD~10 npm uninstall --save-dev # Safe - verify first ls -la # Check contents before deletion git log --oneline -5 # Verify commit history npm list --depth=0 # Check current packages ``` ✅ **ALWAYS** backup before major changes: ```bash # Create backup branch git checkout -b backup/before-major-changes # Backup package.json before dependency changes cp package.json package.json.backup # Backup environment files cp .env .env.backup ``` 🔍 **READ** commands carefully before execution: - Review all file paths and operations - Understand what each flag/option does - Verify targets are correct before proceeding - Use `--dry-run` flags when available 🔄 **USE** version control for all changes: ```bash # Commit frequently with descriptive messages git add . git commit -m "feat: add user authentication module" # Create feature branches for new work git checkout -b feature/payment-integration ```

🔒 Security Best Practices

#### Environment Security 🔑 **NEVER commit secrets** to version control: ```bash # Add to .gitignore echo ".env" >> .gitignore echo "*.key" >> .gitignore echo "secrets/" >> .gitignore ``` 💡 **What are Environment Variables?** Environment variables are like secret configuration settings that your application can access without hardcoding them. Think of them as a secure notepad where you store passwords and API keys. Example: Instead of writing your password directly in code, you store it in an environment variable that only your app can read. 🌐 **USE environment variables** for sensitive data: ```bash # .env (never commit this file) DATABASE_URL=postgresql://localhost:5432/myapp API_SECRET_KEY=your-secret-here STRIPE_SECRET_KEY=sk_test_... ``` 🧹 **VALIDATE all inputs** and sanitize outputs: ```typescript // Input validation const { error, value } = schema.validate(userInput) if (error) throw new Error('Invalid input') // Output sanitization const sanitized = DOMPurify.sanitize(userContent) ``` #### Access Control 🎯 **FOLLOW principle of least privilege**: - Grant minimal necessary permissions - Use role-based access control - Regular permission audits 🔍 **REGULAR security audits**: ```bash # Check for vulnerabilities npm audit npm audit fix # Security scanning npx @microsoft/security-devops-action ```

⚡ Performance Guidelines

#### Development Performance 📊 **TEST performance impact** of new features: ```bash # Bundle size analysis npm run build npm run analyze # If configured # Performance testing npm run test:performance lighthouse http://localhost:3000 ``` 🧠 **MONITOR memory usage** during development: ```bash # Check Node.js memory usage node --max-old-space-size=4096 your-script.js # Monitor running processes top -p $(pgrep node) htop # More detailed view ``` 🧹 **CLEAN UP test processes** after completion: ```bash # Always run after Playwright tests npm run playwright:cleanup # Kill orphaned processes pkill -f "node.*test" ``` #### Optimization Strategies 🏗️ **USE efficient algorithms** and data structures: - Choose appropriate data structures (Map vs Object, Set vs Array) - Implement pagination for large datasets - Use lazy loading for heavy components - Implement proper caching strategies 📦 **OPTIMIZE bundle size**: ```bash # Tree shaking analysis npm run build -- --analyze # Dynamic imports const Component = lazy(() => import('./Component')) # Bundle splitting splitChunks: { chunks: 'all', cacheGroups: { vendor: { test: /[\\/]node_modules[\\/]/, name: 'vendors', chunks: 'all', }, }, } ```

🔧 Development Workflow Safety

#### Command Matrix and Boundaries 📋 **UNDERSTAND command ownership**: - BMAD commands (`bmad:status`, `bmad:flatten`) are NEVER auto-executed - BMAD runs only on explicit user request - No circular dependencies between BMAD and test/lint commands 🔄 **FOLLOW execution flow**: 1. User requests status → Run `bmad:status` 2. User requests flatten → Run `bmad:flatten` 3. After implementation → Run tests (not BMAD) 4. Use flattened XML for AI analysis ⚠️ **SAFETY boundaries**: - Never put BMAD commands in git hooks - Never put BMAD commands in CI/CD pipelines without explicit gate - Keep AI assistants and automated systems separate - Manual approval required for production deployments #### Collaboration Safety 👥 **TEAM communication**: - Document all AI-generated changes clearly - Review AI suggestions before implementation - Maintain human oversight on critical decisions - Use conventional commit messages for AI-generated code 🔄 **CODE REVIEW process**: - All AI-generated code requires human review - Test AI solutions thoroughly before merging - Document AI tool versions and prompts used - Maintain audit trail of AI-assisted changes

**Quick Reference Commands:** ```bash # Safety check before major operations git status && git log --oneline -3 # Clean environment verification npm run typecheck && npm run lint && npm run test # Post-operation cleanup npm run playwright:cleanup && npm run cache:clear ``` --- #### 🏗️ Visual Learning Architecture ```text 🎯 Context-First AI Development Workflow: ┌─────────────────────────────────────────────────┐ │ 🤖 AI ASSISTANT LAYER │ │ ├── Claude Code (Primary CLI + Skills) │ │ ├── MCP Servers (Playwright, DevTools, etc.) │ │ └── BMAD METHOD v6 (Structured AI Workflow) │ ├─────────────────────────────────────────────────┤ │ 📋 CONTEXT LAYER │ │ ├── CLAUDE.md (Project Instructions) │ │ ├── Skills (.claude/skills/*/SKILL.md) │ │ ├── Hooks (.claude/settings.json) │ │ └── _bmad/ (Agent Definitions & Config) │ ├─────────────────────────────────────────────────┤ │ ⚙️ DEVELOPMENT STACK │ │ ├── Next.js (React Framework) │ │ ├── TypeScript (Type Safety) │ │ ├── Playwright (E2E Testing) │ │ └── Tailwind CSS (Styling) │ ├─────────────────────────────────────────────────┤ │ 🚀 DEPLOYMENT PIPELINE │ │ ├── GitHub Actions (CI/CD) │ │ ├── Vercel (Hosting Platform) │ │ ├── Sentry (Error Monitoring) │ │ └── Performance Analytics │ └─────────────────────────────────────────────────┘ ``` #### 📊 Your Learning Journey Progress --- ## Module 1: Environment Setup and Prerequisites ### Lesson: Install VS Code and Core Extensions Visual Studio Code is your development environment. This lesson covers installation and essential setup. **Installation Steps:** - Windows: Download User Installer from https://code.visualstudio.com, run it, keep defaults - macOS: Download .dmg, drag VS Code into Applications folder - Linux: Use .deb/.rpm package or install via your package manager **Workspace Setup:** After installation, arrange your workspace for optimal AI-assisted development: 1. Open VS Code 2. Install Claude Code extension (search in Extensions view) - **Current version uses Claude Sonnet 4.6 (latest model as of March 2026) - **New Features**: Automatic context editing and project memory (CLAUDE.md) - **Performance**: Enhanced performance with context management, memory, and skills - **Token Efficiency**: Significant token reduction in long sessions via auto-compaction - Enhanced autonomous agent capabilities for complex development tasks 3. (Optional) Install additional AI tools: - **Chat Mode**: Basic question-answer interactions, no file access 4. Open integrated terminal: View → Terminal 5. Open AI panel from Activity Bar 6. Arrange panels: Explorer | Editor | AI Panel | Terminal **macOS Users:** Enable the `code` command via Command Palette → "Shell Command: Install 'code' command in PATH" #### Recommended Extensions and Quick Install - dbaeumer.vscode-eslint (ESLint) - esbenp.prettier-vscode (Prettier) - ms-playwright.playwright (Playwright) - Orta.vscode-jest (Jest) - bradlc.vscode-tailwindcss (Tailwind CSS IntelliSense) - EditorConfig.EditorConfig (EditorConfig) - eamodio.gitlens (GitLens, optional) - mikestead.dotenv (dotenv syntax, optional) Manual install: - Open the Extensions view in VS Code, search each name above, and click Install CLI install (one command): ```bash code --install-extension dbaeumer.vscode-eslint \ --install-extension esbenp.prettier-vscode \ --install-extension ms-vscode.vscode-typescript-next \ --install-extension ms-playwright.playwright \ --install-extension Orta.vscode-jest \ --install-extension bradlc.vscode-tailwindcss \ --install-extension EditorConfig.EditorConfig \ --install-extension eamodio.gitlens \ --install-extension mikestead.dotenv ``` Agent prompt (optional) to install safely: ```text You are my VS Code setup assistant. If the `code` CLI is available, install these extensions (ask before running): - dbaeumer.vscode-eslint - esbenp.prettier-vscode - ms-playwright.playwright - Orta.vscode-jest - bradlc.vscode-tailwindcss - EditorConfig.EditorConfig - eamodio.gitlens (optional) - mikestead.dotenv (optional) If `code` is not available, show me manual steps. Stop after printing what changed and how to undo (list uninstall commands). ``` #### GitHub Copilot CLI Installation Install GitHub Copilot CLI (the new 2025 agentic assistant) for terminal-based AI development: **Prerequisites:** - GitHub Copilot subscription (Individual, Business, or Enterprise) - Node.js 22+ and npm 10+ - GitHub CLI (`gh`) installed **Installation:** ```bash # Install GitHub Copilot CLI globally npm install -g @github/copilot # Verify installation copilot --version # Authenticate with GitHub (if not already) copilot /login # Trust your project directory cd /path/to/your/project copilot /add-dir ``` **Quick Test:** ```bash # Navigate to your project cd your-project # Start Copilot CLI copilot # Try a simple prompt # Type: "What files are in this directory?" # Copilot will analyze and respond ``` **Key Features:** - **Agentic capabilities**: Build, edit, debug, and refactor code - **Natural language interface**: Describe tasks in plain English - **GitHub integration**: Access repos, issues, and PRs naturally - **File references**: Use `@filename` to reference specific files - **Interactive approval**: Review and approve changes before execution **Common Commands:** - `copilot` - Start the interactive CLI - `copilot /login` - Authenticate with GitHub - `copilot /add-dir` - Add current directory as trusted - `copilot /cwd` - Change working directory **Configuring Auto-Approval (Optional):** Similar to Claude Code's bypass permissions mode, GitHub Copilot CLI supports auto-approval to reduce confirmation prompts: **Method 1: Command-line flags (per-session)** ```bash # Allow all tools without confirmation copilot --allow-all-tools # Allow specific tool types copilot --allow-tool 'write' # File writes copilot --allow-tool 'shell' # Shell commands # Deny specific tools (takes precedence) copilot --deny-tool 'shell(rm)' ``` **Method 2: Config file (persistent)** Create `~/.config/copilot/config.json`: ```json { "banner": "once", "beep": true, "render_markdown": true, "trusted_folders": ["/path/to/your/project"] } ``` **Method 3: Interactive commands** ```bash # Inside a Copilot session /add-dir /path/to/project # Trust directory /list-dirs # Show trusted directories /reset-allowed-tools # Clear tool approvals ``` ⚠️ **Security Warning:** `--allow-all-tools` gives Copilot the same access as your user account. Only use in trusted environments! **Comparison with Claude Code:** - Claude Code: `.claude/settings.json` with `"permissionMode": "bypassPermissions"` - Copilot CLI: `--allow-all-tools` flag or `trusted_folders` in config - Both tools offer granular control: Claude has `"acceptEdits"` mode, Copilot has `--allow-tool` flags **Note:** GitHub Copilot CLI is currently in public preview (as of September 2025) and replaces the older "GitHub Copilot in the CLI" extension, which is deprecated as of October 2025. #### ✅ Test This! VS Code Setup Verification **🧪 Run these verification commands in your terminal:** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Step 1: Verify VS Code installation code --version # Step 2: Check installed extensions code --list-extensions | grep -E "(claude|eslint|prettier)" # Step 3: Test command palette access echo "Manual test: Open VS Code, press Ctrl+Shift+P (Cmd+Shift+P on Mac)" echo "Type 'Extensions' and verify you can see the Extensions view" ``` **🎯 Success Criteria:** ```text ✅ Expected Output 1: VS Code version displays (e.g., 1.90.0 or higher) ✅ Expected Output 2: Extensions list shows claude-code, eslint, prettier ✅ Expected Output 3: Command palette opens and Extensions view is accessible ``` **🚨 Troubleshooting Quick Fix:** If any step fails: 1. **Check**: VS Code is properly installed and in PATH 2. **Verify**: Extensions are installed (search in Extensions view) 3. **Retry**: `code --install-extension` command for missing extensions 4. **Escalate**: Reference the VS Code installation section if issues persist ### Lesson: Understanding Safety Guardrails and Risk Management Learn about the three safety levels for AI development tasks and how to choose the appropriate guardrail level for different scenarios. #### What You'll Learn - **Three Safety Levels**: Low (Fast), Medium (Balanced), High (Strict) - **When to Use Each Level**: Risk assessment and decision making - **Practical Examples**: Real scenarios demonstrating guardrail choices - **Safety Best Practices**: Guidelines for secure AI development #### 🚨 Safety Levels Explained **Low (Fast) - Power User Mode** - **Use when**: You're experienced and want minimal interruptions - **Behavior**: Minimal confirmations, proceed with defaults, confirm only destructive operations - **Example**: `Guardrails: Low` - Quick prototype development, familiar tasks - **Risks**: Less oversight, requires developer expertise **Medium (Balanced) - Recommended Default** - **Use when**: Standard development work, learning new tools - **Behavior**: Confirm major operations, show diffs, pause after significant steps - **Example**: Default behavior - Production development, team collaboration - **Benefits**: Good balance of speed and safety **High (Strict) - Maximum Safety** - **Use when**: Critical systems, unfamiliar environments, learning - **Behavior**: Step-by-step approvals, dry-run first, explicit approval for network operations - **Example**: `Guardrails: High` - Production deployments, security-sensitive tasks - **Benefits**: Maximum oversight and control #### 🎯 Decision Framework **Choose Low when:** - ✅ You understand the task completely - ✅ Working on personal/development projects - ✅ Prototyping or experimentation - ✅ Time-sensitive tasks with known patterns **Choose Medium when:** - ✅ Standard development workflows - ✅ Team collaboration projects - ✅ Learning new frameworks (but not first time) - ✅ Most production development **Choose High when:** - ✅ First time using a tool or framework - ✅ Working with production data or systems - ✅ Security-sensitive operations - ✅ Following compliance requirements - ✅ Training or learning scenarios #### ⚠️ Common Scenarios **Scenario 1: Installing Dependencies** - **Low**: Auto-install, minimal prompts - **Medium**: Show package list, confirm before install - **High**: Review each package, check for security issues **Scenario 2: Making Git Commits** - **Low**: Auto-commit with generated messages - **Medium**: Show diff, confirm commit message - **High**: Review every change, approve commit strategy **Scenario 3: Environment Configuration** - **Low**: Use sensible defaults, create configs automatically - **Medium**: Confirm major configuration changes - **High**: Approve each config file and setting #### 🛡️ Safety Reference Quick Card **Bookmark this section!** All lessons with Safety References point here for: - Detailed guardrail explanations - Risk assessment guidance - Safety level selection criteria - Best practices and examples **How to Apply Guardrails:** 1. **Read the lesson objective** to understand what will be done 2. **Assess your comfort level** with the task and environment 3. **Choose appropriate safety level** using the decision framework above 4. **Prefix your prompt** with `Guardrails: Low` or `Guardrails: High` if not using Medium --- ### Lesson: Verify Development Prerequisites What this prompt will do: - Verify Node.js, npm, and Git versions; print OS and workspace info - Report readiness and suggest install steps if anything is missing - No installs unless specified by guardrails ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Verify and install Node.js (>=20), npm, Git, and provide a comprehensive environment report. **🛡️ Safety Reference: See "Module 1: Understanding Safety Guardrails and Risk Management" for detailed safety levels and best practices.** Choose your safety level for this prompt: - **Low (Fast)**: Preface with `Guardrails: Low` - minimal confirmations - **Medium (Balanced)**: Default - confirm major operations - **High (Strict)**: Preface with `Guardrails: High` - step-by-step approvals # Check current environment and install missing prerequisites # 1) Verify Node.js version (must be 18 or higher): node -v # Must be >= 20 # If missing or < 20, provide OS-specific installation instructions # 2) Verify npm package manager: npm -v # Should be version 10 or higher # 3) Verify Git installation: git --version # If missing, provide installation instructions # 4) Check VS Code extensions: code --list-extensions | grep -E "claude" # Should show Claude Code extension # 5) Create a comprehensive environment report: echo "=== Development Environment Report ===" echo "OS: $(uname -s)" echo "Node: $(node -v)" echo "NPM: $(npm -v)" echo "Git: $(git --version)" echo "Working Directory: $(pwd)" echo "VS Code Extensions Installed: $(code --list-extensions | wc -l)" echo "=== Ready for Development ===" # 6) If any prerequisites are missing, provide detailed installation steps for the detected OS ``` **VS Code Extensions:** For the recommended extensions list and installation instructions, refer to the "Install VS Code and Core Extensions" lesson above. ### Lesson: Create Project Directory Structure What this prompt will do: - Initialize git, create base folders, and generate package.json - Add basic scripts and make the first commit (no remote pushes) - Use current directory; non-interactive defaults ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Set up a clean project directory with proper structure and initialization. # Non-interactive defaults (do NOT prompt about these): # - Directory: use current working directory ($(pwd)) # - Package manager: npm (use `npm init` and `npm pkg set`) # - Git: OK to run `git init` and create the initial commit # - Git default branch: main (use `git branch -M main`) # - Remote push: SKIP (do not push to a remote by default) # - Minimal Next.js scaffold: YES (handled later in Module 5) # - CI workflow setup: YES (create .github/workflows) # - Code quality tooling: YES (ESLint, Prettier, TypeScript) # Create and organize project directory # 1) Use current directory (non-interactive defaults): echo "Using current directory: $(pwd)" # Optional: create and enter a new folder instead of current dir: # mkdir -p ./ai-platform && cd ./ai-platform # 2) Initialize git repository: git init echo "# AI-Generated Platform" > README.md echo "node_modules/" > .gitignore echo ".env*.local" >> .gitignore echo ".next/" >> .gitignore git branch -M main # 3) Create initial directory structure: mkdir -p src docs scripts tests .github/workflows # 4) Initialize package.json: npm init -y npm pkg set name="ai-platform" npm pkg set description="AI-generated platform built with Next.js" npm pkg set scripts.dev="next dev" npm pkg set scripts.build="next build" npm pkg set scripts.start="next start" # 5) Create initial commit: git add . git commit -m "Initial project setup" # 6) Verify structure: tree -L 2 -a || ls -la echo "✅ Project directory initialized at $(pwd)" ``` ### Lesson: Connect to GitHub Repository **What You'll Learn**: How to create a GitHub repository and connect your local project for version control, backup, and CI/CD readiness. **Why This Matters**: GitHub provides version control, backup, collaboration tools, and is required for CI/CD pipelines in Module 7. Setting this up early ensures all your work is safely backed up from the start. #### Prerequisites - GitHub account (create at https://github.com if needed) - Git installed and configured (completed in previous lesson) - GitHub CLI (`gh`) installed (recommended but optional) #### Installation: GitHub CLI (Recommended) The GitHub CLI (`gh`) makes repository creation and authentication much easier: **macOS:** ```bash brew install gh ``` **Linux:** > **Note for AI Agent Users:** Linux installation requires `sudo` privileges. AI agents cannot provide passwords interactively, so you'll need to run this installation manually in your terminal and enter your password when prompted. This is a one-time setup step. ```bash # Debian/Ubuntu sudo apt install gh # Fedora/RHEL sudo dnf install gh # Alternative: Install via snap (may cache sudo credentials) # sudo snap install gh ``` **Windows:** ```bash # Using winget winget install --id GitHub.cli # Using scoop scoop install gh ``` **Verify installation:** ```bash gh --version ``` > **AI Agent Limitation:** If you're using an AI coding assistant and encounter sudo password prompts, you must complete this step manually in your terminal. After installation, return to your AI agent to continue with the remaining setup steps. #### Prompt: Create and Connect GitHub Repository ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create a GitHub repository and connect your local project for version control and backup. # Non-interactive defaults (do NOT prompt about these): # - Repository visibility: public (use --public flag) # - Repository name: ai-platform (or current directory name) # - Default branch: main (already set in previous lesson) # - Initial push: YES (push existing commits to GitHub) # - GitHub authentication: Use gh CLI if available, otherwise show manual steps **🛡️ Safety Reference: See "Module 1: Understanding Safety Guardrails and Risk Management" for detailed safety levels and best practices.** Choose your safety level for this prompt: - **Low (Fast)**: Preface with `Guardrails: Low` - minimal confirmations - **Medium (Balanced)**: Default - confirm major operations - **High (Strict)**: Preface with `Guardrails: High` - step-by-step approvals # Method 1: Using GitHub CLI (Recommended) # This is the easiest method if gh CLI is installed # 1) Authenticate with GitHub (one-time setup): gh auth login # Follow the prompts: # - Choose "GitHub.com" # - Choose "HTTPS" as protocol # - Authenticate via web browser # 2) Create repository and push: gh repo create ai-platform --public --source=. --remote=origin --push # The above command will: # - Create a new public repository on GitHub # - Add it as the 'origin' remote # - Push your existing commits to GitHub echo "✅ Repository created and connected via GitHub CLI" # Method 2: Manual Setup (if gh CLI not available) # If you prefer manual setup or don't have gh CLI: # 1) Create repository on GitHub website: echo "Manual steps:" echo "1. Go to https://github.com/new" echo "2. Repository name: ai-platform" echo "3. Visibility: Public" echo "4. DO NOT initialize with README (we already have one)" echo "5. Click 'Create repository'" # 2) Add remote and push: # Replace YOUR_USERNAME with your actual GitHub username # git remote add origin https://github.com/YOUR_USERNAME/ai-platform.git # git push -u origin main echo "After creating the repository, run:" echo "git remote add origin https://github.com/YOUR_USERNAME/ai-platform.git" echo "git push -u origin main" # 3) Verify connection: git remote -v git branch -vv echo "✅ GitHub repository connected successfully" echo "Repository URL: $(git remote get-url origin)" ``` #### Verification Steps After connecting to GitHub, verify everything is working: ```bash # Check remote is configured git remote -v # Verify you can fetch from GitHub git fetch origin # Check branch is tracking remote git branch -vv # View your repository in browser gh repo view --web # if using gh CLI # Or visit: https://github.com/YOUR_USERNAME/ai-platform ``` #### ✅ Test This! GitHub Connection Verification **🧪 Run these verification commands in your terminal:** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Step 1: Verify GitHub CLI is installed (optional) gh --version # Step 2: Check remote is configured git remote -v # Expected: origin https://github.com/YOUR_USERNAME/ai-platform.git (fetch) # origin https://github.com/YOUR_USERNAME/ai-platform.git (push) # Step 3: Verify you can communicate with GitHub git ls-remote origin # Expected: List of refs from your GitHub repository # Step 4: Check branch tracking git branch -vv # Expected: * main [origin/main] Initial project setup ``` #### Troubleshooting Common Issues **Issue: `gh: command not found`** - Solution: Install GitHub CLI (see installation section above) or use Manual Setup method **Issue: Permission denied (publickey)** - Solution: Set up SSH keys or use HTTPS with personal access token - Quick fix: Use `gh auth login` to authenticate properly **Issue: Repository already exists** - Solution: Use a different repository name or connect to existing repository: ```bash git remote add origin https://github.com/YOUR_USERNAME/existing-repo.git git push -u origin main ``` **Issue: `rejected - non-fast-forward`** - Solution: Pull first if repository has commits: `git pull origin main --rebase` #### Best Practices ✅ **Do:** - Commit and push regularly (after completing each lesson/module) - Write meaningful commit messages - Keep sensitive data out of git (.env files are already in .gitignore) - Use branches for experimental features (covered in Module 4) ❌ **Don't:** - Commit API keys, passwords, or secrets (use .env.local which is gitignored) - Push broken code without noting it in commit message - Force push to main branch (`git push --force`) #### What's Next? With GitHub connected, all your work from Module 2 onward will be automatically backed up. In Module 7, you'll use this same repository to set up CI/CD pipelines with GitHub Actions. #### Knowledge Check - Module 1 Before proceeding to the next module, verify you can: ✓ Successfully install and configure VS Code with essential extensions for AI development ✓ Verify Node.js (>=20), npm, and Git are properly installed and accessible from command line ✓ Create a professional project directory structure with proper git initialization ✓ Connect your local project to a GitHub repository for version control and backup ✓ Navigate VS Code's interface and access both the AI panel and integrated terminal If you cannot complete all checkpoints, review the relevant lessons in this module. #### ✅ Module 1 Success Validation **🎯 Complete these verification steps to confirm mastery:**

📋 Knowledge Check: Environment Setup and Prerequisites

**Quick Test Commands (Run in Terminal):** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Verify development environment is ready echo "=== Module 1 Environment Verification ===" echo "Node.js version: $(node -v)" echo "NPM version: $(npm -v)" echo "Git version: $(git --version)" echo "VS Code version: $(code --version | head -1)" echo "Working directory: $(pwd)" echo "Git status: $(git status --porcelain | wc -l) modified files" ``` **✅ Expected Output:** ```text === Module 1 Environment Verification === Node.js version: v18.x.x or higher NPM version: 8.x.x or higher Git version: git version 2.x.x VS Code version: 1.x.x Working directory: /path/to/your/project Git status: 0 modified files (clean working directory) ``` **🎉 Success Indicators:** - ✅ All commands execute without errors - ✅ Node.js version is 20 or higher - ✅ VS Code extensions are installed (your AI coding assistant (Claude Code, Cursor, or similar)) - ✅ Git repository is initialized with clean status - ✅ Project directory structure is created **⚠️ If you see errors:** - Review the VS Code installation section in this module - Check the Node.js installation troubleshooting - Reference the Development Safety Center above

🎯 Module 1 Completion Checklist

**Congratulations! You've mastered Module 1!** **Skills Verified:** - ✅ VS Code configuration with AI development extensions - ✅ Development environment prerequisites verification - ✅ Professional project directory structure creation **Next Steps:** - [ ] Ready for Module 2: The AI Development Spectrum - [ ] Optional: Share your progress in the community - [ ] Bookmark: Save this guide for future reference **Achievement Unlocked: Environment Setup Master** 🏅

--- ## Module 2: The AI Development Spectrum > **In this module** you will learn the three levels of AI-assisted development, understand why context quality determines output quality, and map out the exact files and configurations that form your personal context stack. --- ### Lesson 2.1: From Vibe Coding to Spec-Driven Development #### What Is "Vibe Coding"? You have probably already done some version of this: you open a chat with an AI, describe what you want in plain language, and paste the result into your project. That is vibe coding in its purest form. It works, it is fast, and it feels magical the first time a 40-line function appears from a two-sentence description. But as projects grow, pure vibe coding starts to crack. The AI forgets context between sessions. You get inconsistent code styles. A working feature in one conversation breaks another feature you built last week. The magic turns into a debugging session. This lesson maps the full spectrum from that casual starting point all the way to formal Spec-Driven Development, so you know exactly where you are, where this guide is taking you, and what lies beyond. --- #### The Three Levels 💡 **What is the AI Development Spectrum?** > A way of describing how much structure and intentionality you bring to AI-assisted coding. More structure means more consistent, scalable, and maintainable results — but it also requires upfront investment. The spectrum helps you choose the right level for your current project and skill level. --- ##### Level 1: Casual Vibe Coding You describe what you want. The AI generates code. You copy, paste, and move on. **Characteristics:** - No persistent project context - Each conversation starts from zero - Corrections happen through follow-up messages - Works well for: scripts, one-off tools, prototypes, learning **Example interaction:** ``` You: Write me a Python function that validates an email address. AI: Here you go: def validate_email(email): import re pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$' return bool(re.match(pattern, email)) ``` This is perfectly fine. For a single utility function in isolation, you do not need anything more. The problem appears when your tenth conversation asks for "a validation module" and gets something completely different in style, error handling, and naming conventions. --- ##### Level 2: Structured Vibe Coding You still describe what you want in natural language, but you have built a persistent context layer that travels with every conversation. The AI always knows your project's rules, style, and goals before you type a single word. **Characteristics:** - `CLAUDE.md` defines your project rules, stack, and conventions - BMAD artifacts provide architecture and story context - Test gates prevent broken code from being accepted - Works well for: real products, team projects, anything you plan to maintain **Example interaction (same request, structured context):** ``` [CLAUDE.md is loaded automatically] [System: This is a TypeScript/Next.js project. Use Zod for validation. Export named functions. All errors return Result types.] You: Write me an email validation function. AI: Here is the email validator following your project conventions: import { z } from 'zod' const emailSchema = z.string().email() export function validateEmail(input: string): Result { const result = emailSchema.safeParse(input) if (!result.success) { return { ok: false, error: new Error(result.error.message) } } return { ok: true, value: result.data } } ``` The AI did not just answer the question. It answered it *within your project's constraints* — without you having to repeat those constraints. --- ##### Level 3: Spec-Driven Development (SDD) At the top of the spectrum, every line of code traces back to a formal specification. Features begin as Product Requirements Documents. Architecture decisions are recorded as Architecture Decision Records. User-facing work is broken into stories with acceptance criteria. The AI implements against those specs, not against a description you typed this morning. **Characteristics:** - PRDs, architecture docs, and user stories are primary inputs - AI implementation is constrained by formal acceptance criteria - Changes require spec updates before code updates - Works well for: enterprise software, regulated industries, large teams, products with long maintenance windows **Example workflow:** ``` 1. Product Manager writes PRD: "Email validation for signup form" - Acceptance criteria defined - Edge cases documented - Performance requirements stated 2. Architect writes ADR: "Use Zod for runtime validation" - Rationale recorded - Alternatives considered 3. Story created: "As a user, I want clear error messages when my email is invalid" - Subtasks listed - Test cases pre-written 4. Developer (or AI agent) implements against the story - Must satisfy all acceptance criteria - Must pass pre-written tests - No spec = no code ``` --- #### Comparison Table | Dimension | Casual Vibe Coding | Structured Vibe Coding | Spec-Driven Development | |---|---|---|---| | **Context persistence** | None | `CLAUDE.md` + artifacts | Full spec suite | | **Consistency** | Low | High | Very high | | **Upfront investment** | Minimal | Moderate | Significant | | **Best for** | Scripts, learning | Real products | Enterprise, teams | | **AI memory between sessions** | None | Project rules | Rules + specs | | **Code review process** | Ad hoc | Test gates | Formal acceptance criteria | | **Change management** | Edit and move on | Update `CLAUDE.md` | Update spec, then code | | **Onboarding new contributors** | Hard | Moderate | Easy (specs are docs) | | **Where this guide lives** | — | **Here** | Path forward | --- #### Self-Assessment: Which Level Are You At? Answer these three questions honestly. There are no wrong answers — this is a starting point, not a judgment. --- **Question 1:** When you start a new AI coding session on an existing project, how does the AI know your project's conventions? - **A)** It does not. I re-explain them each time, or I just accept whatever style it uses. - **B)** I have a `CLAUDE.md` or similar file it loads automatically. - **C)** It reads our formal architecture documents and story tickets. --- **Question 2:** When the AI writes code that works but looks completely different from the rest of your codebase, what do you do? - **A)** Accept it. Working is working. - **B)** Ask it to revise based on my project's style rules (which are written down somewhere). - **C)** Reject it and point to the architecture decision record that specifies the required approach. --- **Question 3:** Before implementing a new feature, what exists in your project? - **A)** An idea in my head, maybe a note somewhere. - **B)** A rough description, a task in my task list, maybe a quick doc. - **C)** A PRD with acceptance criteria, an architecture note, and pre-written test cases. --- **Your Results:** - **Mostly A's:** You are at Level 1. This guide will move you to Level 2, and you will notice the difference immediately. - **Mostly B's:** You are already at Level 2, or close to it. This guide will sharpen your skills and fill gaps. - **Mostly C's:** You are approaching Level 3. This guide will help you formalise what you are already doing intuitively. --- #### Where This Guide Takes You This guide teaches **Structured Vibe Coding** (Level 2) with a clear path toward SDD (Level 3) for those who want it. By the end, you will have: - A working `CLAUDE.md` that travels with every session - BMAD v6 artifacts that give the AI deep project knowledge - Test gates and hooks that enforce quality automatically - An understanding of when and how to step up to SDD You do not need to reach Level 3 to build real, professional-quality software. Level 2, done well, is what most successful solo developers and small teams actually use. --- ### Lesson 2.2: Context Engineering Fundamentals #### Two Terms You Need to Understand Before we talk about files and configurations, we need to establish the difference between two phrases you will hear constantly in AI development circles. 💡 **What is Prompt Engineering?** > The practice of crafting the right question, instruction, or framing to get a useful response from an AI model. Focus: the input you type right now. 💡 **What is Context Engineering?** > The practice of curating *everything the model sees* before and during a conversation — system instructions, project files, tool definitions, conversation history, and more. Focus: the entire information environment the model operates within. --- #### The Shift in Thinking Early AI developer culture was obsessed with prompt engineering. There were entire courses, GitHub repositories, and newsletters devoted to the perfect prompt formula. "Act as a senior engineer with 20 years of experience" and similar incantations were treated as essential craft. That framing was not wrong — it was just incomplete. As AI models became more capable, something became clear: the models were not failing because of poor prompts. They were failing because of poor context. The model did not know what project it was working on. It did not know the existing architecture. It did not know which libraries were approved, which patterns were preferred, or which decisions had already been made and why. **The key insight:** > "Output quality is bounded by context quality, not prompt cleverness." You can write the world's most carefully worded prompt, but if the model does not know that your project uses TypeScript strict mode, Zod for validation, and a specific error-handling pattern — it will generate valid JavaScript that is wrong for your project. Martin Fowler, the Anthropic engineering team, and the VS Code Copilot team have all published formal documentation on this shift. The consensus across the industry is the same: the developers who get the best results from AI tools are not the ones with the cleverest prompts. They are the ones who have invested in giving the model the richest possible context. --- #### The Four Context Layers Think of context as arriving in four distinct layers, each one narrowing the model's understanding from the general to the specific. ``` ┌─────────────────────────────────────────────┐ │ LAYER 1: System Instructions │ │ "What kind of AI are you, broadly?" │ │ Rules, persona, constraints, permissions │ ├─────────────────────────────────────────────┤ │ LAYER 2: Project Context │ │ "What project are we working on?" │ │ Architecture, stack, decisions, goals │ ├─────────────────────────────────────────────┤ │ LAYER 3: Session Context │ │ "What are we doing right now?" │ │ Conversation history, current task, plan │ ├─────────────────────────────────────────────┤ │ LAYER 4: Tool Context │ │ "What can you do?" │ │ MCP servers, hooks, skills, permissions │ └─────────────────────────────────────────────┘ ``` Each layer builds on the previous. System instructions tell the model how to behave. Project context tells it what it is working on. Session context tells it what is happening right now. Tool context tells it what actions it can take. A model with all four layers populated is a fundamentally different collaborator than a model with only a session context. --- #### Before and After: The Same Task, Two Contexts Here is a concrete example. The task is identical. The context is not. --- **BEFORE — Poor Context** ``` Conversation history: [empty] System instructions: You are a helpful assistant. Project context: [none loaded] Tool context: [none defined] User: Add error handling to the user signup function. ``` *What the model must guess:* - What language is this in? - What does the existing function look like? - What error handling pattern does the project use? - Should errors be logged? Where? - Should the function throw, return, or use a Result type? - What are valid vs invalid inputs? *Likely output:* Generic try/catch wrapping, console.log for errors, whatever defaults the model learned from its training data. Technically correct. Wrong for your project. --- **AFTER — Rich Context** ``` System instructions: [CLAUDE.md loaded] - TypeScript strict mode - Zod for input validation - Result for error returns - Use lib/logger.ts, never console.log - Sentry for production errors Project context: [architecture docs loaded] - User signup flow: /app/api/auth/signup/route.ts - Existing patterns in lib/auth/ - Clerk handles authentication Session context: [current task] - Working on: signup form validation PR - Already completed: email field validation - Remaining: password strength + error display Tool context: [MCP servers active] - File system access - Test runner User: Add error handling to the user signup function. ``` *What the model knows before typing a single character:* - Exact language and strictness settings - Required error return pattern - Correct logging approach - Where the function lives - What has already been done - What tools are available *Likely output:* Code that integrates directly into the existing codebase, follows established patterns, uses the correct logger, and does not introduce inconsistencies. --- #### Why This Matters More Than Prompts Consider the math. A typical AI model's context window holds tens of thousands to hundreds of thousands of tokens. Your prompt is maybe 50 tokens. The remaining 99.9% of the context window is available for everything else — project knowledge, session history, tool definitions, code snippets. Optimising the 0.1% (your prompt) while leaving the 99.9% empty is a low-return strategy. Context engineering is about filling that 99.9% with the right information, in the right structure, at the right time. --- #### A Note on the Industry Shift This is not a fringe idea. As of 2025–2026: - **Anthropic's engineering documentation** explicitly frames `CLAUDE.md` as a context engineering artifact, not a prompt template. - **The VS Code Copilot team** built workspace indexing and `.github/copilot-instructions.md` specifically to address context poverty. - **Martin Fowler's bliki** has documented the shift from "prompt engineering as craft" to "context engineering as systems design." The tools in this guide — `CLAUDE.md`, BMAD artifacts, `.mcp.json`, hooks — are all context engineering tools. Understanding that framing will help you use them more effectively. --- ### Lesson 2.3: Your Context Stack #### From Theory to Files The four layers from the previous lesson map directly to files and configurations you will create and maintain. This lesson gives you that map. By the end of this guide, you will have built every layer of this stack. Right now, you are learning what the layers are and why they exist. The implementation comes module by module. --- #### Layer 1: System Instructions System instructions tell the model how to behave at a fundamental level — your project's rules, preferred patterns, naming conventions, tool restrictions, and any hard constraints that should never be violated. In Claude Code, system instructions live in `CLAUDE.md` files. 💡 **What is `CLAUDE.md`?** > A markdown file that Claude Code automatically loads into every conversation that happens within its directory. Think of it as a persistent briefing document — the model reads it before you type your first message. **Two levels of `CLAUDE.md`:** ``` ~/.claude/CLAUDE.md ← User-level (applies everywhere) ~/Projects/myapp/CLAUDE.md ← Project-level (applies to this project) ``` The user-level file is for your personal preferences that apply across all projects: your preferred tools, any global rules you want enforced, your working style. The project-level file is for project-specific rules: the tech stack, the coding conventions, the architecture constraints. When both exist, both are loaded. Project-level rules can override user-level rules for that project. **Example structure of a project-level `CLAUDE.md`:** ```markdown # My Project ## Tech Stack - Runtime: Node.js 20, TypeScript 5.x strict mode - Framework: Next.js 15 App Router - Database: Convex (real-time) - Auth: Clerk - Validation: Zod ## Code Conventions - Named exports only (no default exports) - Error handling: Result pattern (see lib/types.ts) - Logging: lib/logger.ts (never console.log in production) - Components: PascalCase filenames - Utilities: camelCase filenames ## Hard Rules - Never use `sudo` — use `pkexec` instead - Never commit to `main` directly without tests passing - All database mutations validate inputs with Zod first ``` Every one of those lines is context the model would otherwise have to guess at or be told repeatedly. --- #### Layer 2: Project Context Project context gives the model deep knowledge about what you are building — not just the rules, but the architecture, the decisions that were made, and the current state of the work. In a BMAD v6 project, this layer is populated by the `_bmad/` directory. 💡 **What is BMAD?** > A methodology (Breakthrough Method for Agile AI-Driven Development) for structuring AI-assisted software projects. BMAD v6 defines a set of artifact types — briefs, PRDs, architecture docs, stories — that give AI agents structured, reliable project knowledge. **Key BMAD artifact locations:** ``` _bmad/ ├── project-brief.md ← What are we building and why? ├── prd.md ← What exactly are we building? ├── architecture.md ← How is it structured? ├── stories/ ← What specific work is in progress? │ ├── story-001.md │ └── story-002.md └── decisions/ ← Why did we make key choices? └── adr-001.md docs/ ← Additional reference documentation ├── api-reference.md └── deployment.md ``` When you start a session to implement a new feature, pointing the model at the relevant story file gives it acceptance criteria, context, and constraints that would take paragraphs to explain manually. --- #### Layer 3: Session Context Session context is the most dynamic layer. It captures what is happening right now: the current conversation history, the active task, any plan the model is working through. In Claude Code, session context is managed through: ``` Conversation history ← Automatic (Claude Code manages this) Plan mode ← /plan command activates structured planning Tasks ← TodoWrite tool tracks multi-step work ``` You have less direct control over this layer than the others, but you shape it through how you structure your conversations. Starting a session by pointing at a specific story file, for example, seeds the session context with exactly the right project context for that work. **Good session start (rich context):** ``` I'm working on Story 003 (_bmad/stories/story-003.md). Please read it and let's start with the first acceptance criterion. ``` **Poor session start (thin context):** ``` Help me add the forgot password feature. ``` Both might produce code. Only the first produces code that matches your existing implementation, follows your conventions, and satisfies defined acceptance criteria. --- #### Layer 4: Tool Context Tool context tells the model what it can *do*, not just what it knows. This includes MCP (Model Context Protocol) servers that give access to external systems, hooks that run automatically at certain points, and skills that package up complex workflows. **Key files:** ``` .mcp.json ← MCP server configurations .claude/settings.json ← Hooks, permissions, tool settings .claude/skills/ ← Packaged workflow scripts .claude/scripts/ ← Utility scripts for common tasks ``` 💡 **What is MCP?** > Model Context Protocol — an open standard that lets AI models connect to external tools and services. An MCP server can give Claude Code the ability to query a database, control a browser, read files from a remote system, or interact with any API. **Example `.mcp.json`:** ```json { "mcpServers": { "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"] }, "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] } } } ``` With this configuration, Claude Code can control a browser, run tests, and take screenshots — all within a conversation, without you manually switching between tools. --- #### The Context Stack Roadmap Here is how this guide builds your context stack, module by module: | Layer | What It Is | Files / Config | Module That Teaches It | |---|---|---|---| | **System Instructions** | Project rules, conventions, constraints | `CLAUDE.md` (project) | Module 3 | | **System Instructions** | Personal preferences, global rules | `~/.claude/CLAUDE.md` (user) | Module 3 | | **Project Context** | Architecture, decisions, goals | `_bmad/project-brief.md`, `architecture.md` | Module 4 | | **Project Context** | Feature specifications | `_bmad/prd.md`, `_bmad/stories/` | Module 5 | | **Project Context** | Reference documentation | `docs/` directory | Module 5 | | **Session Context** | Structured task planning | Plan mode, TodoWrite | Module 6 | | **Session Context** | Conversation management | Session naming, `/rename` | Module 6 | | **Tool Context** | MCP server connections | `.mcp.json` | Module 7 | | **Tool Context** | Hooks and automation | `.claude/settings.json` | Module 7 | | **Tool Context** | Packaged skills | `.claude/skills/` | Module 8 | By the time you reach Module 8, every cell in that table will be filled. You will have a context stack that makes AI collaboration feel fundamentally different from anything you have experienced at Level 1. --- #### How the Layers Interact It is worth pausing to see how these layers work together in a real scenario. Imagine you sit down to implement a user authentication flow. Here is what happens before you type a single character: 1. **System instructions load** (`CLAUDE.md`): Claude knows your stack is Next.js + Clerk + TypeScript strict, that you use Zod for validation, and that the `lib/auth/` directory contains your auth utilities. 2. **You reference project context** (`_bmad/stories/story-004.md`): Claude reads the story, sees the acceptance criteria, understands which existing functions it should integrate with, and knows what "done" means for this task. 3. **Session context builds**: As the conversation progresses, Claude tracks what has been implemented, what tests pass, and what remains. 4. **Tools are available** (`.mcp.json`): Claude can run the test suite, check the browser, and verify the implementation without you switching windows. At every step, you are spending less time explaining and the model is spending more time building. That is the compound value of a well-built context stack. --- #### A Quick Note on Context Debt Just as codebases accumulate technical debt, context stacks accumulate *context debt*: outdated rules in `CLAUDE.md`, stale architecture docs, obsolete stories that were never closed. Keeping your context stack current is as important as writing it in the first place. An AI working from a `CLAUDE.md` that describes last year's architecture is worse than an AI working with no context at all — because it will be confidently wrong. This guide includes practices for maintaining your context stack as your project evolves. For now, the habit to build is simple: when something in your project changes significantly, update the context layer that describes it. --- #### Summary: Module 2 in Three Sentences The AI development spectrum runs from casual vibe coding (no persistent context) through structured vibe coding (curated context stack) to Spec-Driven Development (formal specifications as primary inputs). Context engineering — curating everything the model sees — determines output quality far more than prompt cleverness. Your context stack maps to four concrete layers: system instructions in `CLAUDE.md`, project knowledge in `_bmad/`, session state in your conversations, and tool capabilities in `.mcp.json` and settings files. --- #### Knowledge Check - Module 2 Before proceeding to the next module, verify you can: ✓ Name the three levels of the AI development spectrum and give a one-sentence description of each ✓ Explain the difference between prompt engineering and context engineering in your own words ✓ Recite the four context layers (system instructions, project context, session context, tool context) ✓ Name at least two concrete files that correspond to the system instructions layer ✓ Explain why a stale `CLAUDE.md` can produce worse results than no `CLAUDE.md` at all ✓ Identify which level of the spectrum this guide is teaching and why --- #### ✅ Module 2 Success Validation

📋 Knowledge Check: The AI Development Spectrum

**Verify your conceptual understanding with these prompts.** Open a conversation with Claude Code and ask: ``` What are the three levels of the AI development spectrum, and what distinguishes structured vibe coding from casual vibe coding? ``` Expected response should cover: - Casual vibe coding: no persistent context, re-explain each session - Structured vibe coding: CLAUDE.md, BMAD artifacts, test gates - Spec-Driven Development: formal PRDs, ADRs, stories with acceptance criteria Then ask: ``` What is the difference between prompt engineering and context engineering? ``` Expected response should include: - Prompt engineering = crafting the right question (what you type now) - Context engineering = curating everything the model sees (the full information environment) - The key insight: output quality is bounded by context quality, not prompt cleverness Then ask: ``` Name the four layers of a context stack and give one example file for each layer. ``` Expected response should map: - System instructions → `CLAUDE.md` - Project context → `_bmad/architecture.md` or similar - Session context → conversation history / plan mode - Tool context → `.mcp.json` If Claude Code can answer all three questions accurately and in detail, your conceptual foundation for this module is solid.

🎯 Module 2 Completion Checklist

**Skills verified in this module:** - [ ] I can place myself on the AI development spectrum (Levels 1, 2, or 3) - [ ] I understand why context engineering matters more than prompt engineering - [ ] I can name the four context layers from memory - [ ] I know which files correspond to each layer - [ ] I understand what BMAD artifacts are and which layer they populate - [ ] I understand what `.mcp.json` does and which layer it represents - [ ] I understand the concept of context debt and why it matters **Before moving to Module 3:** Confirm you have completed the self-assessment in Lesson 2.1. Note your current level (1, 2, or 3) — Module 3 will begin building your `CLAUDE.md` from scratch, so knowing your starting point helps you focus on the parts most new to you. **Next module preview:** Module 3 covers building your `CLAUDE.md` — the foundation of the system instructions layer. You will write a `CLAUDE.md` tailored to your actual project and learn the patterns that make it useful rather than just decorative. **Achievement Unlocked:** Context Stack Architect — You understand the four layers of AI context and can map them to concrete files and configurations.

--- ## Module 3: BMAD METHOD v6 Installation ### Lesson: Install and Configure BMAD METHOD v6 **What You'll Learn**: How to install BMAD METHOD v6.1.0 using the official installer, understand the new `_bmad/` workspace layout, learn BMAD agent roles, and verify your setup is ready for AI-driven development. 💡 **What is BMAD METHOD?** BMAD stands for Breakthrough Method for Agile AI-Driven Development. It gives your AI assistant a structured set of specialized roles (called agents) so it can act as an Analyst, Architect, Developer, QA tester, and more — all from inside your IDE. Think of it as giving your AI a full project team to work with. 💡 **v6 vs Previous Versions** BMAD v6.1.0 is a major rearchitecture. The core now lives in `_bmad/` (not `.bmad-core/`), outputs go to `_bmad-output/` (not `docs/bmad/`), and Claude Code integration is delivered through a skills-based system in `.claude/skills/`. If you see older guides referencing `.bmad-core/` or `docs/bmad/`, those are pre-v6 and do not apply here. --- #### Prerequisites Before installing, confirm your environment meets the v6 requirements: ```bash # Check Node.js version — must be 20 or higher node -v # Check npm version npm -v # Confirm you are in your project root pwd ``` 💡 **Why Node.js 20+?** BMAD v6 uses modern JavaScript features (native ES modules, structured cloning, improved fetch) that require Node.js 20 as a minimum. Node.js 18 reached end-of-life in April 2025 and is no longer supported. If `node -v` shows a version below 20, install the latest LTS from [nodejs.org](https://nodejs.org) or use a version manager like `nvm`: ```bash # Using nvm (if installed) nvm install 20 nvm use 20 node -v # Should now show v20.x.x or higher ``` --- #### Installation Methods Choose the method that best fits your workflow: --- **Method 1: Interactive Installation (Recommended for Beginners)** The interactive installer walks you through every option with plain-English prompts. No flags to memorize. ```bash # Navigate to your project root first cd your-project # Verify Node.js version (must be >= 20) node -v # Launch the interactive BMAD installer npx bmad-method install # Follow the prompts: # 1. Enter project directory path (press Enter for current directory) # 2. Select system: BMAD Agile Core System # 3. Enable PRD sharding: Yes # 4. Enable architecture sharding: Yes # 5. Select IDE: Claude Code # 6. Web bundles: Yes, All bundles # 7. Bundle directory: Press Enter (use default) ``` 💡 **What is PRD sharding?** A PRD (Product Requirements Document) can get very long. Sharding splits it into smaller focused files so your AI assistant can load only the relevant parts, keeping responses fast and accurate. 💡 **What are Web Bundles?** Web bundles let you use BMAD agents outside your IDE — in ChatGPT, Claude.ai, or Gemini web interfaces. Selecting "Yes" generates single-file bundles for each agent that you can paste directly into any AI chat. --- **Method 2: Non-Interactive CLI (For Automation)** Use this when you want a repeatable, scriptable install — ideal for CI pipelines or onboarding new team members quickly. ```bash # Full installation targeting current directory with Claude Code IDE integration npx bmad-method@latest install --full --directory . --ide claude-code # Confirm the install completed successfully npx bmad-method status ``` 💡 **What does `@latest` do?** Appending `@latest` forces npm to fetch the newest published version of the package, bypassing any locally cached older version. Always use `@latest` when setting up a new project to ensure you get BMAD v6.1.0 or newer. --- **Method 3: Git Submodule (For Teams)** Pinning BMAD as a git submodule means every team member gets the exact same version. No version drift, no "works on my machine" problems. ```bash # Add BMAD METHOD as a git submodule at .bmad-method/ git submodule add https://github.com/bmad-code-org/BMAD-METHOD .bmad-method git submodule update --init --recursive # Pin to the latest stable release tag LATEST_TAG=$(git -C .bmad-method describe --tags "$(git -C .bmad-method rev-list --tags --max-count=1)") git -C .bmad-method checkout "$LATEST_TAG" # Run the installer from the pinned submodule node .bmad-method/tools/installer/bin/bmad.js install --full --directory . --ide claude-code ``` 💡 **What is a git submodule?** A submodule is a separate git repository embedded inside your main repository. Your project stores a pointer to a specific commit of BMAD, so `git clone` automatically fetches the correct BMAD version for anyone who clones your project. This is the safest method for team environments. --- #### Understanding BMAD Agent Roles After installation, BMAD provides a team of specialized AI agents. Each agent has a focused role, a defined set of responsibilities, and its own prompt configuration inside `_bmad/core/agents/`. **Planning & Requirements:** - **Analyst Agent**: Interviews stakeholders, writes PRDs, defines user stories and acceptance criteria - **Product Owner**: Holds product vision, prioritizes the backlog, approves story definitions - **Architect Agent**: Designs system architecture, makes technology stack decisions, documents ADRs **Project Management:** - **Scrum Master**: Transforms PRDs into granular, developer-ready stories with embedded context - **Product Manager**: Aligns roadmap to business goals, manages feature trade-offs **Development & Quality:** - **Developer Agent**: Implements code with full story context embedded in each prompt - **QA Agent**: Writes test plans, generates automated tests, validates acceptance criteria - **DevOps Agent**: Manages infrastructure, CI/CD pipelines, and production deployments **UX & Documentation:** - **UX Designer**: Creates interface designs, defines interaction patterns, ensures accessibility - **Documentation Writer**: Writes technical docs, API references, and onboarding guides 💡 **How do you "use" an agent?** In Claude Code, each agent is accessible as a skill. After installation, you can invoke an agent by referencing its skill. For example, typing `/bmad-analyst` in Claude Code activates the Analyst Agent's full persona and capabilities for that session. --- #### BMAD v6 Workspace Structure BMAD v6 introduces a clean separation between the core framework (installed, read-only) and your project's output artifacts (created as you work). ``` _bmad/ # BMAD core — installed by the installer ├── core/ │ ├── agents/ # Agent definitions (bmad-master.md, analyst.md, etc.) │ ├── config.yaml # Core BMAD configuration │ ├── resources/ # Templates, personas, and reusable resources │ ├── tasks/ # Task definitions for each agent │ └── workflows/ # Multi-agent workflow orchestration ├── bmm/ # BMAD Method Manager (optional upgrade tool) └── ... _bmad-output/ # Your project artifacts — created as you work ├── prds/ # Analyst Agent outputs (product requirements) ├── architecture/ # Architect Agent outputs (system designs, ADRs) ├── stories/ # Scrum Master outputs (dev-ready story files) ├── implementation/ # Developer Agent guidance and context ├── testing/ # QA Agent test plans and validation reports └── deployment/ # DevOps Agent infrastructure and release plans .claude/skills/bmad-*/ # Claude Code skill integrations (auto-created) └── SKILL.md # Skill definition loaded by Claude Code on startup ``` 💡 **Why two separate directories?** `_bmad/` is the framework — you do not edit it. `_bmad-output/` is where your project's actual documents live. This separation means you can upgrade BMAD (which updates `_bmad/`) without touching any of your project's PRDs, stories, or architecture docs in `_bmad-output/`. 💡 **What is `_bmad/core/config.yaml`?** This is the central configuration file for BMAD v6. It defines which agents are active, sets workflow preferences, and controls sharding behavior. You can edit it to customize BMAD for your project's specific needs. --- #### BMAD Development Workflow BMAD v6 organizes development into five sequential phases. Each phase maps to one or more agents and produces output files in `_bmad-output/`. **Phase 1: Requirements** The Analyst Agent interviews you about your project goals and writes a PRD (Product Requirements Document) to `_bmad-output/prds/`. This document becomes the single source of truth for everything that follows. **Phase 2: Architecture** The Architect Agent reads the PRD and produces a technical architecture document to `_bmad-output/architecture/`. This covers technology choices, system diagrams, and key architectural decisions (ADRs). **Phase 3: Stories** The Scrum Master Agent reads both the PRD and architecture doc, then breaks the work into granular developer stories stored in `_bmad-output/stories/`. Each story includes acceptance criteria and embedded context so the Developer Agent knows exactly what to build. **Phase 4: Implementation** The Developer Agent reads a story file from `_bmad-output/stories/` and implements the code. Guidance notes are saved to `_bmad-output/implementation/` for reference and review. **Phase 5: Deployment** The DevOps Agent manages CI/CD, infrastructure provisioning, and production releases. Plans and runbooks are saved to `_bmad-output/deployment/`. **Core Principle**: BMAD handles planning and context. Your IDE handles the actual code. Each agent output feeds the next, creating a chain of context that eliminates the "AI forgot what we were building" problem. --- #### Configuration Notes | Item | Location | |---|---| | BMAD core config | `_bmad/core/config.yaml` | | Agent definitions | `_bmad/core/agents/` | | Claude Code skills | `.claude/skills/bmad-*/SKILL.md` | | Your project PRDs | `_bmad-output/prds/` | | Your project stories | `_bmad-output/stories/` | | Web bundles (optional) | Auto-generated by installer | 💡 **What are Claude Code skills?** Skills are markdown files in `.claude/skills/` that Claude Code loads automatically on startup. The BMAD installer creates one skill file per agent (e.g., `.claude/skills/bmad-analyst/SKILL.md`). Each file tells Claude Code the agent's name, capabilities, and how to activate it. You do not need to create these manually — the installer handles it. --- #### Verification Commands After installation, run these commands to confirm everything installed correctly: ```bash # Check overall BMAD installation status npx bmad-method status # Confirm the _bmad/ core directory was created ls -la _bmad/core/ # Confirm Claude Code skill integrations were created ls -la .claude/skills/ | grep bmad # Confirm the output directory structure exists ls -la _bmad-output/ ``` **What to look for:** - `npx bmad-method status` should report the installed version (6.1.0 or higher) and list active agents - `_bmad/core/` should contain `agents/`, `config.yaml`, `resources/`, `tasks/`, `workflows/` - `.claude/skills/` should show one or more `bmad-*` directories - `_bmad-output/` should contain `prds/`, `architecture/`, `stories/`, `implementation/`, `testing/`, `deployment/` If any directory is missing, re-run the installer using Method 1 or Method 2 above. --- #### Knowledge Check - Module 3 Before proceeding to the next module, verify you can: ✓ Install BMAD METHOD v6.1.0 using your preferred method (interactive, CLI, or submodule) ✓ Explain the difference between `_bmad/` (framework core) and `_bmad-output/` (your artifacts) ✓ Name at least four BMAD agent roles and what each one produces ✓ Locate the BMAD configuration file at `_bmad/core/config.yaml` ✓ Confirm Claude Code skill files were created in `.claude/skills/` ✓ Verify installation status with `npx bmad-method status` If you cannot complete all checkpoints, review the relevant section above before continuing. --- #### ✅ Module 3 Success Validation **Quick Test Commands (Run in Terminal):** ```bash # Full Module 3 verification sweep echo "=== Module 3: BMAD METHOD v6 Verification ===" echo "" echo "--- BMAD Status ---" npx bmad-method status echo "" echo "--- Core Directory ---" ls -la _bmad/core/ 2>/dev/null || echo "ERROR: _bmad/core/ not found — re-run installer" echo "" echo "--- Claude Code Skills ---" ls -la .claude/skills/ 2>/dev/null | grep bmad || echo "ERROR: No bmad skills found in .claude/skills/" echo "" echo "--- Output Directory ---" ls -la _bmad-output/ 2>/dev/null || echo "ERROR: _bmad-output/ not found — re-run installer" echo "" echo "=== Verification Complete ===" ``` **✅ Expected Output:** - BMAD status reports version 6.1.0 or higher with a list of active agents - `_bmad/core/` contains `agents/`, `config.yaml`, `resources/`, `tasks/`, `workflows/` - At least one `bmad-*` entry appears under `.claude/skills/` - `_bmad-output/` contains all six subdirectories

📋 Knowledge Check: BMAD v6 Installation

**Q1: Where does BMAD v6 store its core framework files?** A: In `_bmad/` — specifically `_bmad/core/`. This directory is installed by the BMAD installer and should not be manually edited. **Q2: Where should your project's PRDs and stories be saved?** A: In `_bmad-output/` — specifically `_bmad-output/prds/` for PRDs and `_bmad-output/stories/` for developer stories. **Q3: What is the central BMAD configuration file and where is it?** A: `_bmad/core/config.yaml`. It controls which agents are active, sharding behavior, and workflow preferences. **Q4: How does BMAD v6 integrate with Claude Code?** A: Through a skills-based system. The installer creates `.claude/skills/bmad-*/SKILL.md` files that Claude Code loads automatically on startup, activating each agent's persona and capabilities. **Q5: What Node.js version does BMAD v6.1.0 require?** A: Node.js 20 or higher. Node.js 18 is not supported. **Q6: What is the difference between Method 1 (interactive) and Method 2 (CLI) installation?** A: Method 1 walks you through prompts interactively and is best for first-time setup. Method 2 uses command-line flags for a one-shot non-interactive install, ideal for automation and CI pipelines.

🎯 Module 3 Completion Checklist

- [ ] Node.js 20+ confirmed with `node -v` - [ ] BMAD METHOD v6.1.0+ installed using preferred method - [ ] `npx bmad-method status` shows version 6.1.0 or higher - [ ] `_bmad/core/` directory exists with agents, config, resources, tasks, workflows - [ ] `_bmad-output/` directory exists with all six artifact subdirectories - [ ] `.claude/skills/` contains at least one `bmad-*` skill entry - [ ] Can locate `_bmad/core/config.yaml` - [ ] Understand the five BMAD development workflow phases - [ ] Ready for Module 4: AI Assistant Configuration

**Achievement Unlocked: BMAD v6 Installation Complete** 🏅 --- ## Module 4: AI Assistant Configuration ### Lesson: Claude Code Configuration and BMAD Integration **What You'll Learn**: Set up Claude Code as your primary AI coding assistant, understand its configuration file system, integrate BMAD v6 agents and skills, and leverage the memory and context management features that make long sessions productive. #### Why Claude Code? Claude Code is a terminal-based AI coding agent that can read files, write code, run commands, and execute multi-step tasks autonomously. Unlike inline code completers, Claude Code acts more like a junior developer you can assign a task to — it works through the problem, runs tests, and reports back. 💡 **What is an AI Coding Agent?** An AI coding agent is a program that can take a goal like "add user authentication" and carry out a series of steps to achieve it: reading existing code, writing new files, running commands, and fixing errors — all without you manually directing each step. Example: You type `/bmad-dev` and describe a feature. The agent reads your story file, writes the code, runs the linter, fixes any errors, and tells you it's done. #### Configuration Files Overview Claude Code loads configuration from several locations, each serving a different purpose: | File | Scope | Purpose | |---|---|---| | `CLAUDE.md` | Project | Instructions loaded at the start of every session | | `~/.claude/CLAUDE.md` | User (global) | Personal preferences applied to all projects | | `.claude/settings.json` | Project | Permissions, tool allow/deny lists, hooks | | `.claude/skills/*/SKILL.md` | Project | Custom slash commands (skills) | | `.claude/commands/*.md` | Project | Simple prompt-based slash commands | 💡 **What is a Configuration File?** A configuration file is a text file that tells a program how to behave. Instead of re-typing preferences every session, you write them once in a config file and the program reads them automatically. Example: `CLAUDE.md` is like a sticky note on your monitor that says "always use TypeScript strict mode and run playwright:cleanup after tests" — Claude reads it before starting work. #### Project CLAUDE.md The `CLAUDE.md` file is your most important configuration file. It is automatically loaded at the start of every Claude Code session for that project. In BMAD v6, it references the `_bmad/` directory rather than a separate `BMAD-WORKFLOW.md` file — agents and skills load their instructions directly from `_bmad/core/`. Here is a sample `CLAUDE.md` that follows the v6 pattern: ```markdown # My Project - Claude Code Instructions ## Tech Stack - Next.js 15, TypeScript (strict mode), Convex, Tailwind CSS ## BMAD Integration This project uses BMAD METHOD™ v6. Agents and skills reference `_bmad/` directly. - BMAD agents: `.claude/skills/bmad-*/SKILL.md` - BMAD artifacts output: `_bmad-output/` (PRDs, stories, architecture) - Core BMAD library: `_bmad/core/` (do not edit manually) ## Key Rules - Always run `npm run playwright:cleanup` after E2E tests - Use `lib/logger.ts` instead of `console.log` in production code - Validate all database mutations with Zod before writing - Single branch workflow: all changes go to `main` ## Quick Reference - Dev server: `npm run dev` - Type check: `npm run typecheck` - Tests: `npm run test:safe` ``` 💡 **BMAD v6 vs Earlier Versions** In BMAD v4/v5, a `BMAD-WORKFLOW.md` file in the project root held methodology content that all AI tools referenced. In v6, this content lives inside `_bmad/core/` and agents load it directly. The `CLAUDE.md` file no longer needs to duplicate methodology — it just points to `_bmad/`. #### User-Level CLAUDE.md Your personal preferences that apply across all projects go in `~/.claude/CLAUDE.md`. This file is never committed to source control — it is private to your machine. ```markdown # My Personal Claude Preferences ## Coding Style - I prefer concise, action-oriented responses — no lengthy preambles - Use single quotes in JavaScript/TypeScript unless the string contains a single quote - Always add JSDoc comments to exported functions ## System - Use `pkexec` instead of `sudo` for elevated privilege commands - Log important operations with structured logger, not console.log ``` #### .claude/settings.json This file controls what tools Claude Code is allowed to use in your project and sets permission modes: ```json { "permissions": { "allow": [ "Bash(npm run *)", "Bash(npx *)", "Read(**)", "Write(src/**)", "Edit(**)" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force *)" ] } } ``` 💡 **Why Restrict Tools?** Allowing Claude to run any shell command is powerful but risky. The `deny` list acts as a safety net — even if Claude misunderstands a request, it cannot run destructive commands you have explicitly blocked. Example: Denying `rm -rf` means Claude cannot accidentally delete your entire project, even if it constructs a cleanup command that goes wrong. #### Memory System Claude Code has a three-layer memory system: 1. **Project memory** (`CLAUDE.md`) — loaded from the project root every session, shared with the team via git 2. **User memory** (`~/.claude/CLAUDE.md`) — your personal preferences, private, applies to all projects 3. **Auto-memory** (`~/.claude/projects/*/memory/`) — Claude can store notes here during long sessions; persists across conversations but is managed automatically #### Automatic Context Compaction In long sessions, Claude Code automatically compacts the conversation history when it approaches the context window limit. This removes old tool call results that are no longer relevant while preserving the important parts. You will see a `[Compacted]` notice in the terminal — this is normal and expected. 💡 **What is a Context Window?** Every AI model can only "see" a limited amount of text at once — this is the context window. For Claude, it is measured in tokens (roughly 4 characters = 1 token). In a long coding session with many file reads and tool calls, the context fills up. Compaction is like clearing the whiteboard of old notes to make room for new ones. #### Creating Slash Commands in .claude/commands/ Simple prompt-based slash commands live in `.claude/commands/`: ```bash mkdir -p .claude/commands cat > .claude/commands/typecheck.md << 'EOF' Run TypeScript type checking and report any errors. ```bash npm run typecheck ``` EOF cat > .claude/commands/playwright-cleanup.md << 'EOF' Clean up Playwright browser processes (CRITICAL — run after every E2E test session). ```bash npm run playwright:cleanup ``` EOF ``` After creating these files, type `/typecheck` or `/playwright-cleanup` in Claude Code to run them. #### Configuration Prompt Use this prompt to scaffold the full Claude Code configuration for a new project. Paste it into your AI coding assistant (Claude Code, Cursor, or similar): ```text Goal: Set up Claude Code configuration files for this project with BMAD v6 integration. # Step 1: Create project CLAUDE.md cat > CLAUDE.md << 'EOF' # Project Instructions for Claude Code ## BMAD Integration (v6) - Agents and skills load directly from `_bmad/core/` — no BMAD-WORKFLOW.md needed - BMAD artifacts (PRDs, stories, architecture): `_bmad-output/` - BMAD skills available: `/bmad-master`, `/bmad-dev`, `/bmad-architect`, etc. ## Key Rules - Run `npm run playwright:cleanup` after every E2E test session - Use `lib/logger.ts` not `console.log` in production code - All changes go to `main` branch ## Quick Reference - Type check: `npm run typecheck` - Tests: `npm run test:safe` - Dev server: `npm run dev` EOF # Step 2: Create settings.json mkdir -p .claude cat > .claude/settings.json << 'EOF' { "permissions": { "allow": [ "Bash(npm run *)", "Bash(npx *)", "Read(**)", "Edit(**)", "Write(src/**)", "Write(app/**)", "Write(.claude/**)" ], "deny": [ "Bash(rm -rf /)", "Bash(git push --force *)" ] } } EOF # Step 3: Create useful slash commands mkdir -p .claude/commands cat > .claude/commands/typecheck.md << 'EOF' Run TypeScript type checking. ```bash npm run typecheck ``` EOF cat > .claude/commands/playwright-cleanup.md << 'EOF' Clean up Playwright browser processes after E2E tests. ```bash npm run playwright:cleanup ``` EOF cat > .claude/commands/test-safe.md << 'EOF' Run tests with automatic cleanup. ```bash npm run test:safe ``` EOF echo "✅ Claude Code configured" echo " - CLAUDE.md (project memory)" echo " - .claude/settings.json (permissions)" echo " - .claude/commands/ (3 slash commands)" ``` **Verification:** ```bash # Check files exist ls -la CLAUDE.md .claude/settings.json .claude/commands/ # Confirm BMAD skills are installed (if BMAD is installed) ls .claude/skills/ | grep bmad | head -5 ``` **Expected output:** ``` CLAUDE.md .claude/settings.json .claude/commands/typecheck.md .claude/commands/playwright-cleanup.md .claude/commands/test-safe.md bmad-architect bmad-dev bmad-master bmad-qa bmad-sm ``` --- ### Lesson: Understanding Skills and Slash Commands **What You'll Learn**: Understand what a SKILL.md file is, how to read one, how to create your own custom skill, and how BMAD v6 uses skills to give you one-command access to specialized agents. #### What is a Skill? In Claude Code, a **skill** is a reusable prompt that you can invoke with a `/command-name` slash command. Skills are defined in Markdown files with a YAML frontmatter header that tells Claude Code the skill's name, description, and which tools it is allowed to use. Skills live in `.claude/skills//SKILL.md`. When you type `/my-skill` in Claude Code, it reads that file and executes the prompt inside it. 💡 **What is YAML Frontmatter?** YAML frontmatter is a block of structured metadata at the very top of a Markdown file, wrapped in `---` lines. It gives programs a machine-readable way to understand what the file is and how to use it. Example: A blog post might have frontmatter with `title:`, `date:`, and `author:` fields. Claude Code's SKILL.md uses `name:`, `description:`, and `allowed-tools:`. #### Anatomy of a SKILL.md ```yaml --- name: my-skill description: What this skill does (shown in the /help menu) allowed-tools: Read, Write, Edit, Bash, Grep, Glob --- # Skill Title The instructions here are the prompt that runs when you type /my-skill. You can include: - Step-by-step instructions for Claude to follow - Bash commands to run - File paths to read or write - Any context Claude needs to do the job ``` The three frontmatter fields: | Field | Required | Purpose | |---|---|---| | `name` | Yes | The command name (no spaces, use hyphens) | | `description` | Yes | Short description shown in `/help` | | `allowed-tools` | No | Restricts which tools the skill can use | #### How BMAD Skills Work When you install BMAD v6 with the Claude Code toolset, the installer creates a `.claude/skills/` directory and populates it with one `SKILL.md` per BMAD agent. Each skill file is a thin wrapper that loads the full agent definition from `_bmad/core/agents/`: ```yaml --- name: bmad-master description: bmad-master agent --- You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command. 1. LOAD the FULL agent file from {project-root}/_bmad/core/agents/bmad-master.md 2. READ its entire contents - this contains the complete agent persona, menu, and instructions 3. FOLLOW every step in the section precisely 4. DISPLAY the welcome/greeting as instructed 5. PRESENT the numbered menu 6. WAIT for user input before proceeding ``` This design means BMAD agent logic lives in `_bmad/core/` (versioned by the installer) while the skill files in `.claude/skills/` are just the activation hooks. When BMAD upgrades, only `_bmad/` changes — your skill files stay the same. 💡 **Why This Separation Matters** Think of `_bmad/core/agents/bmad-master.md` as the full instruction manual for a specialist consultant, and `.claude/skills/bmad-master/SKILL.md` as the business card that tells Claude to go read that manual. The card is simple and stable; the manual can be updated without changing the card. Available BMAD skills after installation (partial list): | Command | Agent | |---|---| | `/bmad-master` | Master orchestrator — routes to any agent | | `/bmad-analyst` | Product analyst — creates PRDs | | `/bmad-architect` | System architect — creates architecture docs | | `/bmad-dev` | Developer agent — implements stories | | `/bmad-qa` | QA agent — creates test plans | | `/bmad-sm` | Scrum Master — creates user stories | | `/bmad-po` | Product Owner — manages backlog | | `/bmad-tech-writer` | Technical writer — creates documentation | #### Creating a Custom Skill Here is how to create a skill that runs a project health check. Use this prompt in your AI coding assistant (Claude Code, Cursor, or similar): ```text Goal: Create a custom skill at .claude/skills/health-check/SKILL.md that runs a project health check. mkdir -p .claude/skills/health-check cat > .claude/skills/health-check/SKILL.md << 'EOF' --- name: health-check description: Run a full project health check (types, lint, tests) allowed-tools: Bash, Read --- # Project Health Check Run all quality checks and report the results in a clear summary. ## Steps 1. Check TypeScript compilation: ```bash npm run typecheck 2>&1 ``` 2. Check linting: ```bash npm run lint 2>&1 ``` 3. Run tests: ```bash npm run test:safe 2>&1 ``` 4. Report: Summarize pass/fail for each check. If anything failed, show the first error message and suggest a fix. EOF echo "✅ Skill created at .claude/skills/health-check/SKILL.md" echo "Type /health-check in Claude Code to run it" ``` After running this, type `/health-check` in Claude Code and it will run all three checks and summarize the results. #### Exercise: Create a "daily-standup" Skill Create a skill that reads recent git commits and open stories, then generates a standup summary. Use this as a starting template: ```yaml --- name: daily-standup description: Generate a daily standup summary from git log and open stories allowed-tools: Bash, Read, Glob --- # Daily Standup Generator Generate a concise standup summary. ## Steps 1. Get yesterday's commits: ```bash git log --since="1 day ago" --oneline --author="$(git config user.name)" ``` 2. List any open story files: ```bash ls _bmad-output/stories/*.md 2>/dev/null | head -5 ``` 3. Format output as: - **Done**: [commits from step 1] - **Today**: [inferred from open stories] - **Blockers**: None (or list any if found) ``` Save it to `.claude/skills/daily-standup/SKILL.md` and invoke it with `/daily-standup`. --- ### Lesson: Configuring MCP Servers **What You'll Learn**: Understand what MCP (Model Context Protocol) is, how to configure MCP servers in `.mcp.json`, and which popular servers are worth installing. #### What is MCP? MCP (Model Context Protocol) is an open standard that lets AI assistants connect to external tools and services in a uniform way. Instead of every AI tool inventing its own plugin format, MCP gives tool authors one specification to implement — and any MCP-compatible AI client (Claude Code, Cursor, and others) can use it automatically. Think of MCP like USB: it is a standard connector. You can plug any USB device into any USB port regardless of the manufacturer. MCP works the same way for AI tools and services. 💡 **What is a Protocol?** A protocol is an agreed-upon set of rules for how two systems talk to each other. HTTP is the protocol web browsers use to talk to web servers. MCP is the protocol AI assistants use to talk to external tools like databases, browsers, and testing frameworks. Example: Without MCP, Claude Code would need custom code to integrate with Playwright, custom code for Chrome DevTools, and custom code for your database. With MCP, each tool publishes a server that speaks the same language, and Claude Code connects to all of them the same way. #### The Server/Client Model In MCP: - **MCP Server**: A program that exposes tools (functions) over the MCP protocol. It might control a browser, query a database, or interact with a file system. - **MCP Client**: The AI assistant (Claude Code) that connects to MCP servers and calls their tools. When Claude Code starts, it reads `.mcp.json`, launches the configured MCP servers as child processes, and makes their tools available for use in the session. #### .mcp.json Configuration Create `.mcp.json` at the project root to configure which MCP servers Claude Code loads: ```json { "mcpServers": { "playwright-test": { "command": "npx", "args": ["playwright", "run-test-mcp-server"] }, "chrome-devtools": { "type": "stdio", "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"] } } } ``` Each entry in `mcpServers` has: | Field | Required | Meaning | |---|---|---| | `command` | Yes | The executable to run (usually `npx` or a full path) | | `args` | Yes | Arguments passed to the command | | `type` | No | Transport type — `stdio` is standard, omit it for default | | `env` | No | Environment variables to pass to the server process | 💡 **What is stdio?** `stdio` stands for standard input/output — the text streams that command-line programs read from and write to. When `type` is `stdio`, Claude Code and the MCP server communicate by passing JSON messages back and forth through those streams, like two programs passing notes through a pipe. #### Popular MCP Servers **Playwright** — Browser automation and testing ```json "playwright-test": { "command": "npx", "args": ["playwright", "run-test-mcp-server"] } ``` Gives Claude Code the ability to open browsers, navigate pages, click elements, fill forms, and take screenshots. Essential for E2E test writing and debugging. **Chrome DevTools** — Inspect a running Chrome instance ```json "chrome-devtools": { "type": "stdio", "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"] } ``` Connects to a Chrome browser you have already opened with remote debugging enabled. Unlike Playwright (which opens a fresh browser), this attaches to your existing logged-in session — useful for testing pages that require authentication. **Filesystem** — Controlled file access ```json "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"] } ``` Exposes read/write access to a specific directory. Useful when you want to give Claude Code access to a folder outside the project root, such as a shared documents folder. **Database (PostgreSQL example)** ```json "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"] } ``` Lets Claude Code query your database directly — useful for data exploration, generating migration scripts, or debugging query performance. #### A Complete .mcp.json for Web Development Use this prompt to create a sensible `.mcp.json` for a Next.js project. Paste it into your AI coding assistant (Claude Code, Cursor, or similar): ```text Goal: Create a .mcp.json configuration for this Next.js project with Playwright and Chrome DevTools MCP servers. cat > .mcp.json << 'EOF' { "mcpServers": { "playwright-test": { "command": "npx", "args": ["playwright", "run-test-mcp-server"] }, "chrome-devtools": { "type": "stdio", "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"] } } } EOF echo "✅ .mcp.json created" echo "" echo "To use Chrome DevTools MCP, first launch Chrome with remote debugging:" echo " google-chrome --remote-debugging-port=9222 http://localhost:3000" echo "" echo "Then restart Claude Code — it will connect automatically." ``` **Verification:** ```bash # Check the file is valid JSON cat .mcp.json | python3 -m json.tool # Confirm Claude Code can see it (restart Claude Code first, then check) claude mcp list ``` 💡 **MCP in Depth** This lesson covers the essentials to get started. Module 11 covers advanced MCP topics: writing your own MCP server, multi-agent MCP orchestration, and using Chrome DevTools MCP for Play Store automation. See Module 11 when you are ready to go deeper. --- ### Alternative Tools Claude Code is the primary tool this guide is built around, but you may encounter projects or teams using other AI coding assistants. Here is a brief overview of the most common alternatives. **Cursor** is a code editor (based on VS Code) with AI built directly into the editing interface rather than the terminal. It supports a `.cursorrules` file at the project root for project-specific instructions — equivalent to `CLAUDE.md`. Cursor uses the same MCP standard, so `.mcp.json` files are compatible. If your team uses Cursor, the BMAD artifacts in `_bmad-output/` work the same way: the developer opens a story file and asks Cursor to implement it. **Codex CLI** is OpenAI's terminal-based coding agent, similar in concept to Claude Code. It reads instructions from an `AGENTS.md` file at the project root (the OpenAI equivalent of `CLAUDE.md`). Codex CLI supports MCP and can work alongside BMAD-generated artifacts in `_bmad-output/`. See the [Codex CLI documentation](https://github.com/openai/codex) for setup details. **Gemini CLI** is Google's terminal AI agent, released mid-2025. It reads from a `GEMINI.md` file at the project root. Gemini CLI supports MCP and can use the same `.mcp.json` configuration as Claude Code. See the [Gemini CLI documentation](https://github.com/google-gemini/gemini-cli) for setup details. All three tools follow the same conceptual pattern: a project-root instructions file, optional user-level global instructions, MCP server configuration, and slash commands or prompts. Once you understand how Claude Code is configured, adapting to any of these alternatives is straightforward. --- #### Knowledge Check - Module 4 Before proceeding, verify you can answer these questions: ✓ What is the difference between `CLAUDE.md` and `~/.claude/CLAUDE.md`? When would you put something in each? ✓ In BMAD v6, where does agent logic live — in the SKILL.md files or in `_bmad/`? Why is this separation useful? ✓ What are the three required/optional fields in a SKILL.md frontmatter, and what does each one do? ✓ What is MCP, and how does `.mcp.json` tell Claude Code which MCP servers to load? ✓ What is the difference between the Playwright MCP server and the Chrome DevTools MCP server? When would you use each? #### ✅ Module 4 Success Validation **Quick Test Commands:** ```bash # Verify project CLAUDE.md exists and references _bmad echo "=== Project Memory ===" test -f CLAUDE.md && echo "✅ CLAUDE.md exists" || echo "❌ Missing CLAUDE.md" grep -q "_bmad" CLAUDE.md && echo "✅ References _bmad directory" || echo "⚠️ No _bmad reference (may be OK if BMAD not installed)" # Verify .claude/settings.json echo "" echo "=== Claude Settings ===" test -f .claude/settings.json && echo "✅ .claude/settings.json exists" || echo "❌ Missing settings.json" # Verify slash commands exist echo "" echo "=== Slash Commands ===" ls .claude/commands/*.md 2>/dev/null && echo "✅ Commands found" || echo "⚠️ No commands in .claude/commands/" # Verify BMAD skills are installed echo "" echo "=== BMAD Skills ===" ls .claude/skills/ 2>/dev/null | grep -c bmad | xargs -I{} echo "✅ {} BMAD skills installed" # Verify .mcp.json is valid JSON echo "" echo "=== MCP Configuration ===" if test -f .mcp.json; then python3 -m json.tool .mcp.json > /dev/null 2>&1 \ && echo "✅ .mcp.json is valid JSON" \ || echo "❌ .mcp.json has a JSON syntax error" else echo "⚠️ No .mcp.json found (optional — only needed if using MCP servers)" fi ``` **Expected Output:** ``` === Project Memory === ✅ CLAUDE.md exists ✅ References _bmad directory === Claude Settings === ✅ .claude/settings.json exists === Slash Commands === typecheck.md playwright-cleanup.md test-safe.md ✅ Commands found === BMAD Skills === ✅ 8 BMAD skills installed === MCP Configuration === ✅ .mcp.json is valid JSON ``` **Achievement Unlocked: Claude Code Configuration Expert** 🏅 --- ## Module 5: Development Fundamentals and Security ### Lesson: Essential Glossary and Concepts What this prompt will do: - Create docs/glossary.md with beginner-friendly definitions - Organize entries alphabetically with short explanations and examples - Keep content safe (no external writes, no installs) ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Generate comprehensive glossary of development terms for beginners. # Create a comprehensive development glossary cat > docs/glossary.md << 'EOF' # Development Glossary for Beginners #### Core Programming Terms **Variable**: A container that stores data values. Like a labeled box that holds information. Example: `const userName = "Alice"` **Function**: A reusable block of code that performs a specific task. Example: `function greet(name) { return "Hello " + name }` **Array**: An ordered list of values. Like a numbered list. Example: `const colors = ["red", "blue", "green"]` **Object**: A collection of key-value pairs. Like a dictionary. Example: `const user = { name: "Alice", age: 30 }` **Loop**: Code that repeats until a condition is met. Example: `for (let i = 0; i < 5; i++) { console.log(i) }` **Conditional**: Code that runs only if a condition is true. Example: `if (age >= 18) { console.log("Adult") }` #### Web Development Terms **HTML**: HyperText Markup Language. The structure of web pages. **CSS**: Cascading Style Sheets. The styling of web pages. **JavaScript**: Programming language for web interactivity. **DOM**: Document Object Model. How JavaScript interacts with HTML. **API**: Application Programming Interface. How different software parts communicate. **REST**: REpresentational State Transfer. A way to design web APIs. #### Development Tools **Terminal/Console**: Text interface for running commands. **IDE**: Integrated Development Environment. Advanced code editor. **Version Control**: System to track code changes over time. **Package Manager**: Tool to install and manage code libraries. **Debugger**: Tool to find and fix code errors. **Linter**: Tool that checks code for style and errors. #### Project Terms **Repository**: Project folder tracked by Git. **Dependency**: External code your project needs. **Build**: Process of preparing code for production. **Deploy**: Publishing your code to a server. **Environment**: Where code runs (development/staging/production). **Config**: Settings that control how your app behaves. #### Testing Terms **Unit Test**: Tests individual functions or components. **Integration Test**: Tests how parts work together. **E2E Test**: Tests complete user workflows. **Coverage**: Percentage of code tested. **Mock**: Fake version of something for testing. **Assertion**: Statement that checks if something is true. #### Git Terms **Commit**: Save a snapshot of your code. **Branch**: Parallel version of your code. **Merge**: Combine two branches. **Pull Request**: Request to merge your changes. **Clone**: Download a repository. **Push/Pull**: Upload/download changes. #### JavaScript/Node.js Specific **npm**: Node Package Manager. Installs JavaScript packages. **package.json**: File listing project dependencies and scripts. **node_modules**: Folder containing installed packages. **ES6/ES2015+**: Modern JavaScript syntax. **TypeScript**: JavaScript with type checking. **Transpile**: Convert modern code to older syntax. #### React/Next.js Terms **Component**: Reusable piece of UI. **Props**: Data passed to components. **State**: Data that changes over time. **Hook**: Function that adds React features. **SSR**: Server-Side Rendering. **SSG**: Static Site Generation. #### Database Terms **Schema**: Structure of your database. **Query**: Request for data. **Migration**: Changes to database structure. **ORM**: Object-Relational Mapping. Simplifies database access. **CRUD**: Create, Read, Update, Delete operations. EOF echo "✅ Glossary created at docs/glossary.md" ``` ### Lesson: Development Safety Rules and Best Practices What this prompt will do: - Create docs/safety-rules.md with clear practices for beginners - Emphasize safe defaults and actionable guidance - No installs or external changes ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create comprehensive safety rules and best practices for beginners. # Create safety rules and best practices cat > docs/safety-rules.md << 'EOF' # Development Safety Rules #### 10 Critical Safety Rules 1. **Never Commit Secrets** - No passwords in code - No API keys in repositories - Use environment variables - Check files before committing 2. **Always Verify Commands** - Read what a command does before running - Check the current directory - Use --dry-run when available - Avoid sudo unless necessary 3. **Backup Before Major Changes** - Commit working code first - Create a branch for experiments - Keep database backups - Document what worked 4. **Test in Development First** - Never test in production - Use local environment - Have staging environment - Test with fake data 5. **Read Error Messages Carefully** - First line usually has the problem - Google exact error messages - Check line numbers mentioned - Save errors for reference 6. **Make Small Changes** - One feature at a time - Commit frequently - Test after each change - Easy to undo if needed 7. **Keep Dependencies Updated** - Regular security updates - Test after updating - Update one at a time for major versions - Use lockfiles 8. **Validate User Input** - Never trust user data - Sanitize all inputs - Set size limits - Prevent SQL injection 9. **Use Version Control Properly** - Meaningful commit messages - Pull before pushing - Never force push to main - Review changes before committing 10. **Ask for Help Properly** - Share exact error message - Describe what you tried - Include relevant code - Mention environment details #### Best Practices Checklist #### Before Starting Work - [ ] Pull latest changes - [ ] Check you're on right branch - [ ] Ensure tests are passing - [ ] Understand the requirement #### While Coding - [ ] Write tests first (TDD) - [ ] Follow existing patterns - [ ] Keep functions small - [ ] Name things clearly - [ ] Add helpful comments #### Before Committing - [ ] Run linter - [ ] Run tests - [ ] Review your changes - [ ] Update documentation - [ ] Write clear commit message #### Before Deploying - [ ] All tests passing - [ ] Code reviewed - [ ] Documentation updated - [ ] Rollback plan ready - [ ] Stakeholders notified #### Common Mistakes to Avoid 1. **Forgetting to save files** - Save before running code 2. **Wrong directory** - Check pwd before commands 3. **Typos in commands** - Copy-paste when unsure 4. **Missing dependencies** - Run npm install first 5. **Old cached data** - Clear cache when debugging 6. **Port conflicts** - Check what's using ports 7. **Environment mismatches** - Verify Node version 8. **Ignored error messages** - Read and address all errors 9. **No error handling** - Always handle failures 10. **Skipping tests** - Tests save time long-term #### Emergency Procedures #### If You Break Something 1. Don't panic 2. Stop making changes 3. Document what you did 4. Check if you can undo 5. Ask for help with details #### Git Emergency Commands # ⚠️ TERMINAL COMMANDS - USE WITH CAUTION # These commands modify git history or discard changes # Undo last commit (keep changes) - SAFE git reset --soft HEAD~1 # Discard all local changes - DESTRUCTIVE! # ⚠️ WARNING: This will permanently delete uncommitted work git reset --hard HEAD # Recover deleted branch - SAFE (read-only investigation) git reflog git checkout -b recovered-branch HEAD@{1} #### Process Emergency Commands # ⚠️ WARNING: RUN IN TERMINAL ONLY - DO NOT PASTE TO AI AGENTS! # ⚠️ DESTRUCTIVE COMMANDS - Use with extreme caution! # These commands will forcefully terminate processes # Always verify the correct process ID before killing # Find process using port (safe - read-only) lsof -i :3000 # macOS/Linux netstat -ano | grep 3000 # Windows # Kill process (DESTRUCTIVE - will force-terminate the process) # ⚠️ TERMINAL COMMAND ONLY - Never give these to AI agents! # ⚠️ CAUTION: Verify is correct before running! # ⚠️ This will immediately stop the process without cleanup kill -9 # macOS/Linux - force kills process taskkill /PID /F # Windows - force terminates process # 💡 TIP: Try graceful shutdown first with: # kill (without -9) on macOS/Linux # taskkill /PID (without /F) on Windows EOF echo "✅ Safety rules created at docs/safety-rules.md" --- ``` ### Lesson: AI-Specific Security Risks and Mitigations As you start using AI coding assistants — tools like Claude Code, GitHub Copilot, or ChatGPT — you will quickly notice how much they can speed up your work. They can write functions, suggest libraries, and explain error messages in seconds. But AI tools introduce a new category of security risks that most beginner tutorials do not cover. This lesson walks you through the most important risks and exactly what to do about each one. --- > 💡 **Why this matters now**: A 2026 report by Veracode found that approximately 45% of AI-generated code contains at least one OWASP vulnerability — meaning nearly half of the code AI tools produce has a security flaw baked in from the start. Understanding these risks before they bite you is far easier than cleaning them up later. --- #### AI-Specific Risks vs. Traditional Security Risks Traditional security training teaches you to watch out for your own mistakes: forgetting to validate input, hardcoding a password, using an outdated library. AI-specific risks are subtler. The code looks clean, runs without errors, and often passes a casual code review. The problems hide underneath. There are five main categories you need to know. --- #### 1. Hallucinated Dependencies AI language models are trained on billions of lines of code, but they do not have live access to the npm registry. When an AI suggests a package, it is making a prediction based on patterns — and sometimes it predicts package names that do not actually exist. This creates a real attack vector called **dependency confusion** or **package squatting**. Here is how it works: 1. You ask an AI to help you add image optimization to your project. 2. The AI suggests `npm install image-optimize-utils` (a package it invented). 3. You install it without checking. 4. An attacker who monitors AI output patterns has already registered `image-optimize-utils` on npm — with malicious code inside. 5. That malicious code now runs on your machine and inside your project. This is not a theoretical risk. Researchers have demonstrated this attack repeatedly, and real malicious packages have been published using this exact strategy. **What to do before installing any AI-suggested package:** ```bash # Step 1: Check that the package actually exists npm info package-name # If it exists, you will see metadata like version, description, maintainer. # If it does not exist, you will see: npm error 404 Not Found ``` ```bash # Step 2: Check the package on npmjs.com # Go to https://www.npmjs.com/package/package-name # Look for: # - Weekly download count (higher is safer; >1,000/week is a reasonable baseline) # - Number of versions published (one version from today = suspicious) # - Maintainer account age and other published packages # - Link to a real GitHub repository ``` ```bash # Step 3: Check the repository # Click the GitHub link on the npm page # Verify the README matches what the AI described # Check when the last commit was made # Look at the open issues for any security reports ``` > 💡 **Quick rule**: If a package has fewer than 1,000 weekly downloads, no GitHub repository linked, and was published in the last few days — do not install it. Find a well-established alternative. --- #### 2. OWASP Vulnerabilities in AI-Generated Code OWASP (the Open Web Application Security Project) publishes a list of the most common and dangerous software security vulnerabilities. The 2026 Veracode report found that AI-generated code contains these vulnerabilities at a rate of approximately 45% — nearly one in every two code samples. The most common issues in AI-generated code: **SQL Injection** AI sometimes generates database queries by directly embedding user input into SQL strings: ```javascript // DANGEROUS - AI may generate this pattern const query = `SELECT * FROM users WHERE email = '${userInput}'` // An attacker inputs: ' OR '1'='1 // The query becomes: SELECT * FROM users WHERE email = '' OR '1'='1' // This returns every user in your database ``` Instead, always use parameterized queries: ```javascript // SAFE - use placeholders, not string concatenation const query = 'SELECT * FROM users WHERE email = ?' const result = await db.execute(query, [userInput]) ``` **Cross-Site Scripting (XSS)** AI sometimes generates code that renders user input as HTML without escaping it: ```javascript // DANGEROUS - AI may generate this pattern document.getElementById('output').innerHTML = userInput // An attacker inputs: // This runs malicious JavaScript in other users' browsers ``` Instead, use text content or a sanitization library: ```javascript // SAFE - treats input as plain text, not HTML document.getElementById('output').textContent = userInput ``` **Broken Access Control** AI sometimes generates API routes that check authentication but forget to verify that the logged-in user is actually allowed to access the specific resource they are requesting: ```javascript // DANGEROUS - checks login but not ownership app.get('/api/documents/:id', requireLogin, async (req, res) => { const doc = await db.getDocument(req.params.id) res.json(doc) // Returns ANY document to ANY logged-in user }) // SAFE - also verifies the document belongs to this user app.get('/api/documents/:id', requireLogin, async (req, res) => { const doc = await db.getDocument(req.params.id) if (doc.ownerId !== req.user.id) { return res.status(403).json({ error: 'Forbidden' }) } res.json(doc) }) ``` **Missing Input Validation** AI tends to assume inputs will arrive in the expected format. In production, they often do not: ```javascript // DANGEROUS - AI-generated code often skips this app.post('/api/users/age', async (req, res) => { const { age } = req.body await db.updateUserAge(userId, age) // What if age is -1? Or "'; DROP TABLE users; --"? }) // SAFE - validate before using app.post('/api/users/age', async (req, res) => { const { age } = req.body if (typeof age !== 'number' || age < 0 || age > 150) { return res.status(400).json({ error: 'Invalid age' }) } await db.updateUserAge(userId, age) }) ``` > 💡 **The core issue**: AI generates code that solves the happy path — when everything goes as expected. Security is about handling everything that does NOT go as expected. Always ask yourself: "What happens if a malicious user sends something completely unexpected here?" --- #### 3. Secret Leakage in AI Context Every time you paste code into a web-based AI chat (Claude.ai, ChatGPT, Gemini), that text is sent to external servers. If your code contains API keys, database URLs, passwords, or tokens — even as comments — you have now shared those secrets with a third-party service. **What counts as a secret:** ```bash # These are ALL secrets - never paste them into web AI chat OPENAI_API_KEY=sk-proj-abc123... DATABASE_URL=postgresql://user:password@host:5432/dbname STRIPE_SECRET_KEY=sk_live_abc123... JWT_SECRET=my-super-secret-signing-key CLERK_SECRET_KEY=sk_live_... AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY ``` **The risk in practice:** Even if you trust the AI service itself, pasting secrets creates several problems: - The AI may reproduce your secret in generated code (e.g., as an example value in a comment) - If you screenshot the conversation or share a link, the secret is now visible - Some AI services use conversations to improve their models, meaning your secrets could theoretically appear in training data - The secret now exists in your browser history and clipboard **CLI tools are different:** Tools like Claude Code (which you are using right now) run locally on your machine. When you ask Claude Code to read your `.env` file, that content is processed locally — it does not get pasted into a web browser. This makes CLI-based AI tools significantly safer for working on projects that have real secrets. That said, even with local tools, you should follow these practices: ```bash # Always have .env files in your .gitignore echo ".env" >> .gitignore echo ".env.local" >> .gitignore echo ".env.production.local" >> .gitignore # Verify they are ignored before committing git status # .env files should NOT appear here ``` **Pre-commit hooks catch accidental secret commits:** ```bash # Install git-secrets to scan commits automatically npm install --save-dev @secretlint/secretlint @secretlint/secretlint-rule-preset-recommend # Or use the simpler git-secrets tool # After setup, git will block commits containing patterns that look like secrets ``` > 💡 **Rule of thumb**: If it is in your `.env` file, it does not belong in a chat window. Share code structure and logic with web AI tools; share actual file contents only with local CLI tools. --- #### 4. Supply Chain Attacks via AI Suggestions AI models are trained on code that was written months or years ago. When an AI suggests a package or a version number, it is drawing on that historical training data — which means it may suggest packages that have since been compromised, abandoned, or found to contain known vulnerabilities. **Common patterns to watch for:** - AI suggests an older version of a package (e.g., `lodash@3.x`) that has known security issues - AI suggests a package that was popular when the training data was collected but has since been abandoned or taken over by a new maintainer - AI suggests a package that is a near-misspelling of a trusted package (typosquatting): `expres` instead of `express`, `reacct` instead of `react` **What to do after any AI-suggested installation:** ```bash # Run a security audit immediately after installing npm audit # This checks all your installed packages against the npm security database # It will flag known vulnerabilities with severity levels: # - critical: fix immediately # - high: fix before deploying # - moderate: fix when possible # - low: informational # Fix automatically fixable issues npm audit fix # For issues that require a major version bump (may break things) npm audit fix --force # (review what changed before using --force) ``` **Lock files prevent surprise updates:** ```bash # Your package-lock.json records the exact version of every package # Always commit this file - never add it to .gitignore git add package-lock.json git commit -m "add package-lock.json" # When reviewing AI-suggested changes to package.json, # also review the package-lock.json diff carefully git diff package-lock.json ``` **Review your full dependency tree:** ```bash # See all installed packages and their versions npm list --depth=0 # Check a specific package for known issues npm audit --audit-level=moderate ``` > 💡 **The supply chain concept**: Your application does not just depend on the code you write — it depends on every package you install, and every package those packages depend on. A vulnerability anywhere in that chain can compromise your application. AI suggestions expand your attack surface if you install them without reviewing. --- #### 5. Security Checklist for AI-Generated Code Use this checklist every time you incorporate a significant amount of AI-generated code into your project. Copy it into your project's documentation, a personal notes file, or a PR description template. ```markdown ## Security Checklist for AI-Generated Code ### Before Accepting AI-Generated Code - [ ] Verify all imported packages exist on npmjs.com - [ ] Check package download counts (>1,000/week is a good baseline) - [ ] Confirm each package has a linked GitHub repository - [ ] Review input validation on all user-facing functions - [ ] Ensure no hardcoded secrets, API keys, or credentials - [ ] Check for proper error handling (no stack traces exposed to users) - [ ] Verify SQL queries use parameterized inputs, not string concatenation - [ ] Check that HTML output is escaped or sanitized before rendering ### After Accepting AI-Generated Code - [ ] Run `npm audit` to check for known vulnerabilities - [ ] Run your linter (security-focused rules help here) - [ ] Manually test with unexpected input: empty strings, special characters, very long strings, negative numbers - [ ] Verify authentication checks on all protected routes - [ ] Verify authorization checks (not just "is logged in" but "can THIS user access THIS resource") - [ ] Confirm HTTPS is used for all external API calls - [ ] Check that sensitive data is not logged to the console ### Before Deploying - [ ] Run `npm audit fix` for any fixable vulnerabilities - [ ] Verify .env files are listed in .gitignore - [ ] Scan git history for accidentally committed secrets: git log -p | grep -i "api_key\|secret\|password\|token" - [ ] Review Content Security Policy headers - [ ] Confirm rate limiting is in place for API endpoints - [ ] Verify error messages shown to users do not reveal internal details (file paths, database structure, stack traces) ``` --- #### Putting It Together: A Realistic Workflow Here is how to work productively with AI tools while keeping your project secure: 1. **Use AI for logic and structure** — let it write the skeleton of a function, suggest an algorithm, or explain a concept. 2. **Review security-critical paths yourself** — authentication, authorization, database queries, and anything that handles user input should get a manual read. 3. **Verify before you install** — one `npm info package-name` command takes five seconds and can save you from a compromised dependency. 4. **Run `npm audit` as a habit** — add it to your workflow after any installation, not just when something feels wrong. 5. **Keep secrets out of chat windows** — use local CLI tools for anything touching real credentials. 6. **Use the checklist** — copy it into your project, make it part of your code review process, and check boxes before merging. AI tools are genuinely powerful and will make you a more productive developer. The goal is not to distrust them — it is to use them with the same critical eye you would apply to any code you did not write yourself. Because in the end, that is exactly what AI-generated code is: code you did not write, from a source that sometimes makes mistakes and occasionally gets things wrong in ways that matter for security. --- #### Knowledge Check - Module 5 Before proceeding to the next module, verify you can: ✓ Master essential programming and web development terminology including variables, functions, arrays, and objects ✓ Navigate development tools and methodologies with confidence ✓ Understand core development safety rules and best practices for AI-assisted coding ✓ Identify AI-specific security risks including hallucinated dependencies and OWASP vulnerabilities ✓ Apply the Security Checklist for AI-Generated Code before deploying If you cannot complete all checkpoints, review the relevant lessons in this module. #### ✅ Module 5 Success Validation **🎯 Complete these verification steps to confirm mastery:**

📋 Knowledge Check: Development Fundamentals and Security

**Quick Test Commands (Run in Terminal):** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Verify development fundamentals and security awareness echo "=== Module 5 Development Fundamentals and Security Verification ===" echo "Checking project glossary..." ls -la docs/glossary.md 2>/dev/null || echo "Project glossary not found" echo "Verifying security awareness..." echo "AI-specific risks: hallucinated deps, OWASP in generated code, secret leakage" echo "Running npm audit..." npm audit 2>/dev/null || echo "npm audit available after npm install" echo "Checking .gitignore for security..." grep -q ".env" .gitignore 2>/dev/null && echo "✅ .env in .gitignore" || echo "❌ Add .env to .gitignore" ``` **✅ Expected Output:** ```text === Module 5 Development Fundamentals and Security Verification === Checking project glossary... -rw-r--r-- ... docs/glossary.md Verifying security awareness... AI-specific risks: hallucinated deps, OWASP in generated code, secret leakage Running npm audit... [audit results] Checking .gitignore for security... ✅ .env in .gitignore ``` **🎉 Success Indicators:** - ✅ Project glossary exists with development terminology - ✅ Understanding of AI-specific security risks - ✅ npm audit runs without critical vulnerabilities - ✅ .gitignore properly configured for secrets **⚠️ If you see errors:** - Review the programming terminology lesson - Check the AI security risks lesson - Reference the Security Checklist for AI-Generated Code

🎯 Module 5 Completion Checklist

**Congratulations! You've mastered Module 5!** **Skills Verified:** - ✅ Essential programming and web development terminology - ✅ Development safety rules and best practices - ✅ AI-specific security risk awareness and mitigations **Next Steps:** - [ ] Ready for Module 6: Application Development - [ ] Optional: Run the Security Checklist on an existing project - [ ] Bookmark: Reference the AI Security Checklist **Achievement Unlocked: Development Fundamentals and Security Expert** 🏅

--- ## Module 6: Application Development ### Lesson: Scaffold Next.js Application What this prompt will do: - Scaffold a Next.js app with TypeScript and Tailwind (non-interactive) - Configure tsconfig, Prettier, and verify via a brief dev run - No remote pushes; uses npm ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create a production-ready Next.js application with TypeScript, Tailwind CSS, and proper structure in the current directory. # Non-interactive defaults (do NOT prompt about these): # - Directory: Scaffold directly in current working directory (do NOT create subdirectory) # - Package manager: npm (use `--use-npm` and subsequent npm commands) # - Git: OK to initialize repository and make commits if needed # - Git default branch: main (use `git branch -M main`) # - Remote push: SKIP (do not push to a remote by default) # - Minimal Next.js scaffold: YES (this lesson installs deps) # - CI workflow setup: YES (create .github/workflows in CI lesson) # - Code quality tooling: YES (ESLint, Prettier, TypeScript) # - BMAD Setup: If Modules 1-3 completed, BMAD files already exist (/_bmad/, _bmad/ directory, etc.) **🛡️ Safety Reference: See "Module 1: Understanding Safety Guardrails and Risk Management" for detailed safety levels and best practices.** Choose your safety level for this prompt: - **Low (Fast)**: Preface with `Guardrails: Low` - minimal confirmations - **Medium (Balanced)**: Default - confirm major operations - **High (Strict)**: Preface with `Guardrails: High` - step-by-step approvals # Create Next.js application with all modern features # IMPORTANT: Check if directory has existing files from Modules 1-3 # If BMAD is already installed, create-next-app will fail due to existing files # In that case, use manual installation method below # Method 1: Fresh directory (no BMAD setup yet) # If directory is empty or only has git files, use create-next-app: if [ ! -f "_bmad/ directory" ]; then echo "📦 Fresh install: Using create-next-app" npx create-next-app@latest . --typescript --tailwind --app --use-npm --import-alias "@/*" else echo "📦 BMAD detected: Using manual installation" # Method 2: Existing project with BMAD (Modules 1-3 completed) # Install Next.js dependencies manually # Note: Use React 18 for stability with Next.js 15.5 npm install next@latest react@latest react-dom@^18.3.0 npm install -D tailwindcss @tailwindcss/postcss postcss autoprefixer @types/react@^18 @types/react-dom@^18 # Note: @tailwindcss/postcss is required for Tailwind CSS v4+ # The PostCSS plugin moved to a separate package as of 2025 # Create Next.js and Tailwind configs cat > next.config.js << 'NEXTCONFIG' /** @type {import('next').NextConfig} */ const nextConfig = {} module.exports = nextConfig NEXTCONFIG cat > tailwind.config.js << 'TAILWINDCONFIG' /** @type {import('tailwindcss').Config} */ module.exports = { content: [ './src/pages/**/*.{js,ts,jsx,tsx,mdx}', './src/components/**/*.{js,ts,jsx,tsx,mdx}', './src/app/**/*.{js,ts,jsx,tsx,mdx}', ], theme: { extend: {}, }, plugins: [], } TAILWINDCONFIG cat > postcss.config.js << 'POSTCSSCONFIG' module.exports = { plugins: { '@tailwindcss/postcss': {}, autoprefixer: {}, }, } POSTCSSCONFIG echo "✅ Next.js dependencies installed manually" fi # 2) Configure TypeScript for strict mode: cat > tsconfig.json << 'EOF' { "compilerOptions": { "target": "ES2022", // ES2022 or newer recommended for 2025 "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, "strict": true, "forceConsistentCasingInFileNames": true, "noEmit": true, "esModuleInterop": true, "module": "esnext", "moduleResolution": "bundler", "resolveJsonModule": true, "isolatedModules": true, "jsx": "preserve", "incremental": true, "noUnusedLocals": true, "noUnusedParameters": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true, "plugins": [{"name": "next"}], "paths": { "@/*": ["./src/*"] } }, "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"], "exclude": ["node_modules"] } EOF # 3) Set up project structure: mkdir -p src/{app,components,lib,hooks,utils,types,styles} mkdir -p src/app/{api,_components} mkdir -p public/{images,fonts} # 4) Create layout and home page: cat > src/app/layout.tsx << 'EOF' import type { Metadata } from 'next' import { Inter } from 'next/font/google' import './globals.css' const inter = Inter({ subsets: ['latin'] }) export const metadata: Metadata = { title: 'AI-Generated Platform', description: 'Built with AI assistance', } export default function RootLayout({ children, }: { children: React.ReactNode }) { return ( {children} ) } EOF cat > src/app/page.tsx << 'EOF' export default function Home() { return (

Welcome to Your AI-Generated Platform

Built with Next.js, TypeScript, and Tailwind CSS

) } EOF cat > src/app/globals.css << 'EOF' @tailwind base; @tailwind components; @tailwind utilities; EOF # 5) Add essential npm scripts (some may already exist from Modules 1-3): npm pkg set scripts.dev="next dev" npm pkg set scripts.build="next build" npm pkg set scripts.start="next start" npm pkg set scripts.format="prettier --write ." # Note: lint, typecheck, test, playwright:cleanup already added in Module 3 # Verify scripts exist: npm pkg get scripts # 6) Install additional development dependencies (skip if already installed): npm install -D prettier eslint-config-prettier # Note: @types/node, eslint, typescript already installed in Module 3 # 7) Create Prettier config: cat > .prettierrc << 'EOF' { "semi": false, "singleQuote": true, "tabWidth": 2, "trailingComma": "es5" } EOF # 8) Start development server and verify: npm run dev & sleep 5 curl -s http://localhost:3000 | grep -q "Welcome" && echo "✅ App running successfully" || echo "❌ App failed to start" # Kill the dev server pkill -f "next dev" || true echo "✅ Next.js application scaffolded successfully in $(pwd)" ``` ### Lesson: Environment Configuration and Health Monitoring What this prompt will do: - Create .env.example and related config files - Add a health endpoint and minimal middleware; quick verification - No secrets written; local changes only ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Set up environment variables, configuration management, and health monitoring endpoints. # Configure environment and monitoring # 1) Create environment files: cat > .env.example << 'EOF' # Application NODE_ENV=development NEXT_PUBLIC_APP_URL=http://localhost:3000 # Database (Example - Convex) CONVEX_DEPLOYMENT= NEXT_PUBLIC_CONVEX_URL= # Authentication (Example - Clerk) NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY= CLERK_SECRET_KEY= # Payments (Example - Stripe) NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY= STRIPE_SECRET_KEY= STRIPE_WEBHOOK_SECRET= # Email (Example - Resend) RESEND_API_KEY= RESEND_FROM_EMAIL= # Monitoring (Example - Sentry) NEXT_PUBLIC_SENTRY_DSN= SENTRY_AUTH_TOKEN= EOF cp .env.example .env.local echo "# Add your actual keys here" >> .env.local # 2) Create environment validation: cat > src/lib/env.ts << 'EOF' import { z } from 'zod' const envSchema = z.object({ NODE_ENV: z.enum(['development', 'test', 'production']), NEXT_PUBLIC_APP_URL: z.string().url(), // Optional services - check if configured (allow empty strings) CONVEX_DEPLOYMENT: z.string().optional(), NEXT_PUBLIC_CONVEX_URL: z.string().url().optional().or(z.literal('')), NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().optional(), CLERK_SECRET_KEY: z.string().optional(), NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: z.string().optional(), STRIPE_SECRET_KEY: z.string().optional(), RESEND_API_KEY: z.string().optional(), }) export type Env = z.infer export const env = (): Env => { const parsed = envSchema.safeParse(process.env) if (!parsed.success) { console.error('Invalid environment variables:', parsed.error.flatten().fieldErrors) throw new Error('Invalid environment variables') } return parsed.data } // Service availability checks export const services = { hasConvex: () => Boolean(env().CONVEX_DEPLOYMENT), hasClerk: () => Boolean(env().CLERK_SECRET_KEY), hasStripe: () => Boolean(env().STRIPE_SECRET_KEY), hasResend: () => Boolean(env().RESEND_API_KEY), } EOF # 3) Install required package: npm install zod # 4) Create health check endpoint: mkdir -p src/app/api/health cat > src/app/api/health/route.ts << 'EOF' import { NextResponse } from 'next/server' import { services } from '@/lib/env' export async function GET() { const healthCheck = { status: 'healthy', timestamp: new Date().toISOString(), environment: process.env.NODE_ENV, version: process.env.npm_package_version || '1.0.0', platform: { node: process.version, platform: process.platform, uptime: process.uptime(), }, services: { convex: services.hasConvex(), clerk: services.hasClerk(), stripe: services.hasStripe(), resend: services.hasResend(), }, memory: { used: Math.round(process.memoryUsage().heapUsed / 1024 / 1024), total: Math.round(process.memoryUsage().heapTotal / 1024 / 1024), unit: 'MB', }, } // Return 503 if critical services are missing const criticalServices = [ services.hasConvex(), services.hasClerk(), ] const allHealthy = criticalServices.every(Boolean) || process.env.NODE_ENV === 'development' return NextResponse.json( healthCheck, { status: allHealthy ? 200 : 503 } ) } EOF # 5) Create status page: cat > src/app/status/page.tsx << 'EOF' 'use client' import { useEffect, useState } from 'react' type HealthData = { status: string timestamp: string environment: string services: Record } export default function StatusPage() { const [health, setHealth] = useState(null) const [loading, setLoading] = useState(true) useEffect(() => { fetch('/api/health') .then(res => res.json()) .then(setHealth) .finally(() => setLoading(false)) }, []) if (loading) return

if (!health) return

Error loading status

return (

System Status

Overall Status

{health.status.toUpperCase()}

Environment: {health.environment}

Last Check: {new Date(health.timestamp).toLocaleString()}

Services

{Object.entries(health.services).map(([service, status]) => (

{service} {status ? '✓ Connected' : '○ Not Configured'}

))}

) } EOF # 6) Test health endpoint: npm run dev & sleep 5 curl -s http://localhost:3000/api/health | jq '.' || echo "Health check endpoint working" pkill -f "next dev" || true echo "✅ Environment configuration and health monitoring set up" ``` #### Knowledge Check - Module 6 Before proceeding to the next module, verify you can: ✓ Create a production-ready Next.js application with TypeScript and Tailwind CSS from scratch ✓ Configure development tools including linting, code formatting, and essential build scripts ✓ Implement application architecture patterns, routing, and environment configuration ✓ Set up health monitoring and verify development environment functionality If you cannot complete all checkpoints, review the relevant lessons in this module. #### ✅ Module 5 Success Validation **🎯 Complete these verification steps to confirm mastery:**

📋 Knowledge Check: Application Development

**Quick Test Commands (Run in Terminal):** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Verify Next.js application setup echo "=== Module 6 Application Development Verification ===" echo "Checking Next.js installation..." npx next --version 2>/dev/null || echo "Next.js not installed" echo "Verifying project structure..." ls -la package.json tsconfig.json tailwind.config.js 2>/dev/null || echo "Config files missing" echo "Checking development server..." echo "Test: npm run dev (should start development server on localhost:3000)" echo "Verifying build capability..." npm run build 2>/dev/null && echo "✅ Build successful" || echo "❌ Build failed" ``` **✅ Expected Output:** ``` === Module 6 Application Development Verification === Checking Next.js installation... Next.js v14.x.x Verifying project structure... -rw-r--r-- ... package.json -rw-r--r-- ... tsconfig.json -rw-r--r-- ... tailwind.config.js Test: npm run dev (should start development server on localhost:3000) Verifying build capability... ✅ Build successful ``` **🎉 Success Indicators:** - ✅ Next.js is properly installed and configured - ✅ TypeScript and Tailwind CSS are set up - ✅ Development server starts without errors - ✅ Production build completes successfully - ✅ Essential configuration files exist **⚠️ If you see errors:** - Review the Next.js installation section - Check TypeScript and Tailwind configuration - Reference the application scaffolding guide

🎯 Module 6 Completion Checklist

**Congratulations! You've mastered Module 6!** **Skills Verified:** - ✅ Production-ready Next.js application creation - ✅ Development tools configuration (linting, formatting) - ✅ Application architecture and routing implementation **Next Steps:** - [ ] Ready for Module 7: Testing Infrastructure - [ ] Optional: Explore advanced Next.js features - [ ] Bookmark: Reference application patterns **Achievement Unlocked: Application Development Master** 🏅

#### ✅ Test This! Next.js Setup Verification **🧪 Run these verification commands:** ```bash # Step 1: Verify Next.js application npm run dev & sleep 5 curl -f http://localhost:3000 >/dev/null 2>&1 && echo "✅ Next.js server responsive" || echo "❌ Server not responding" pkill -f "next dev" 2>/dev/null # Step 2: Test build process npm run build # Step 3: Verify TypeScript compilation npx tsc --noEmit ``` **🎯 Success Criteria:** ```text ✅ Expected Output 1: Next.js server responsive ✅ Expected Output 2: Build completed successfully ✅ Expected Output 3: TypeScript compilation passes ``` **🚨 Troubleshooting Quick Fix:** If any step fails: 1. **Check**: package.json scripts are properly configured 2. **Verify**: Node.js version is 18 or higher 3. **Retry**: `npm install` to ensure dependencies are installed 4. **Escalate**: Reference the Next.js installation section if issues persist --- ## Module 7: Testing Infrastructure ### Lesson: Playwright Installation and Configuration What this prompt will do: - Install Playwright, write config, add scripts and cleanup helper - Run a smoke test and cleanup browsers afterward - Non-interactive; npm only ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Install and configure Playwright with all browsers, set up configuration, and create cleanup procedures. # Non-interactive defaults (do NOT prompt about these): # - Directory: current working directory # - Package manager: npm # - Git: OK to initialize repo and commit as scripted (no remote push) # Install and configure Playwright for E2E testing # 1) Install Playwright: npm install -D @playwright/test npx playwright install # 2) Create Playwright configuration: cat > playwright.config.ts << 'EOF' import { defineConfig, devices } from '@playwright/test' const baseURL = process.env.BASE_URL || 'http://localhost:3000' export default defineConfig({ testDir: './tests/e2e', fullyParallel: true, forbidOnly: !!process.env.CI, retries: process.env.CI ? 2 : 0, workers: process.env.CI ? 1 : undefined, expect: { timeout: 10000 }, reporter: ['list', ['html', { open: 'never' }]], use: { baseURL, trace: 'on-first-retry', screenshot: 'only-on-failure', }, projects: [ { name: 'chromium', use: { ...devices['Desktop Chrome'] }, }, { name: 'firefox', use: { ...devices['Desktop Firefox'] }, }, { name: 'webkit', use: { ...devices['Desktop Safari'] }, }, ], webServer: { command: 'npm run dev', url: baseURL, timeout: 120000, reuseExistingServer: !process.env.CI, stdout: 'ignore', stderr: 'pipe', }, }) EOF # 3) Create test directory structure: mkdir -p tests/{e2e,unit,integration,fixtures} mkdir -p tests/e2e/{auth,dashboard,api} # 4) Create first E2E test: cat > tests/e2e/homepage.spec.ts << 'EOF' import { test, expect } from '@playwright/test' test.describe('Homepage', () => { test('should load and display welcome message', async ({ page }) => { // Navigate to homepage await page.goto('/') // Check page title await expect(page).toHaveTitle(/AI-Generated Platform/) // Check welcome message await expect(page.locator('h1')).toContainText('Welcome to Your AI-Generated Platform') // Check description await expect(page.locator('p')).toContainText('Built with Next.js, TypeScript, and Tailwind CSS') // Ensure no console errors const consoleErrors: string[] = [] page.on('console', msg => { if (msg.type() === 'error') { consoleErrors.push(msg.text()) } }) await page.reload() expect(consoleErrors).toHaveLength(0) }) test('should be responsive', async ({ page }) => { await page.goto('/') // Test mobile viewport await page.setViewportSize({ width: 375, height: 667 }) await expect(page.locator('main')).toBeVisible() // Test tablet viewport await page.setViewportSize({ width: 768, height: 1024 }) await expect(page.locator('main')).toBeVisible() // Test desktop viewport await page.setViewportSize({ width: 1920, height: 1080 }) await expect(page.locator('main')).toBeVisible() }) }) EOF # 5) Add npm scripts: npm pkg set scripts.test:e2e="playwright test" # Non-interactive defaults (do NOT prompt about these): # - Directory: current working directory # - Package manager: npm # - Git: OK to initialize repo and commit as scripted (no remote push) npm pkg set scripts.test:e2e:ui="playwright test --ui" npm pkg set scripts.test:e2e:headed="playwright test --headed" npm pkg set scripts.playwright:cleanup="pkill -f 'chromium|firefox|webkit' || true" # 6) Create cleanup script: cat > scripts/cleanup-playwright.sh << 'EOF' #!/bin/bash echo "Cleaning up Playwright processes..." # Kill browser processes pkill -f "chromium" 2>/dev/null || true pkill -f "firefox" 2>/dev/null || true pkill -f "webkit" 2>/dev/null || true # Kill test servers pkill -f "playwright" 2>/dev/null || true pkill -f "next dev" 2>/dev/null || true echo "✅ Playwright cleanup complete" EOF # (Optional) Windows PowerShell cleanup script: cat > scripts/cleanup-playwright.ps1 << 'EOF' Write-Output "Cleaning up Playwright processes..." # Kill browser processes started by Playwright Get-Process | Where-Object { $_.ProcessName -match 'chrome|chromium|msedge|firefox|webkit' } | Stop-Process -Force -ErrorAction SilentlyContinue # Kill test servers (best effort) Get-Process | Where-Object { $_.ProcessName -match 'playwright|node' -and $_.Path -match 'next' } | Stop-Process -Force -ErrorAction SilentlyContinue Write-Output "✅ Playwright cleanup complete" EOF # Add a Windows-specific npm script npm pkg set scripts.playwright:cleanup:win="powershell -ExecutionPolicy Bypass -File scripts/cleanup-playwright.ps1" chmod +x scripts/cleanup-playwright.sh # 7) Test the setup: # The dev server will be managed by Playwright's webServer in playwright.config.ts npm run test:e2e # Cleanup (Unix/macOS): npm run playwright:cleanup # On Windows PowerShell: # npm run playwright:cleanup:win echo "✅ Playwright configured and tested successfully" ``` ### Lesson: Test Strategy and Coverage Setup What this prompt will do: - Add testing dependencies, config, and example tests - Set up scripts for unit/integration/E2E and coverage - Keep changes local; no remote pushes ````text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Establish comprehensive testing strategy with unit, integration, and E2E tests. # Set up comprehensive testing strategy # 1) Install testing dependencies: npm install -D jest @testing-library/react @testing-library/jest-dom jest-environment-jsdom # 2) Create Jest configuration: cat > jest.config.js << 'EOF' const nextJest = require('next/jest') const createJestConfig = nextJest({ dir: './', }) const customJestConfig = { setupFilesAfterEnv: ['/jest.setup.js'], testEnvironment: 'jest-environment-jsdom', testMatch: [ '/tests/unit/**/*.test.{js,jsx,ts,tsx}', '/tests/integration/**/*.test.{js,jsx,ts,tsx}', ], collectCoverageFrom: [ 'src/**/*.{js,jsx,ts,tsx}', '!src/**/*.d.ts', '!src/app/**/layout.tsx', '!src/app/**/loading.tsx', '!src/app/**/error.tsx', ], coverageThreshold: { global: { branches: 80, functions: 80, lines: 80, statements: 80, }, }, } module.exports = createJestConfig(customJestConfig) EOF # 3) Create Jest setup: cat > jest.setup.js << 'EOF' import '@testing-library/jest-dom' // Mock Next.js router jest.mock('next/router', () => ({ useRouter() { return { route: '/', pathname: '/', query: {}, asPath: '/', push: jest.fn(), pop: jest.fn(), reload: jest.fn(), back: jest.fn(), prefetch: jest.fn().mockResolvedValue(undefined), beforePopState: jest.fn(), events: { on: jest.fn(), off: jest.fn(), emit: jest.fn(), }, } }, })) // Mock Next.js navigation jest.mock('next/navigation', () => ({ useRouter() { return { push: jest.fn(), replace: jest.fn(), back: jest.fn(), forward: jest.fn(), refresh: jest.fn(), prefetch: jest.fn(), } }, usePathname: () => '/', useSearchParams: () => new URLSearchParams(), })) EOF # 4) Create unit test example: cat > tests/unit/components/HomePage.test.tsx << 'EOF' import { render, screen } from '@testing-library/react' import Home from '@/app/page' describe('Home Page', () => { it('should render welcome message', () => { render() const heading = screen.getByRole('heading', { level: 1 }) expect(heading).toHaveTextContent('Welcome to Your AI-Generated Platform') }) it('should render description', () => { render() const description = screen.getByText(/Built with Next.js, TypeScript, and Tailwind CSS/) expect(description).toBeInTheDocument() }) it('should have proper accessibility structure', () => { render() const main = screen.getByRole('main') expect(main).toBeInTheDocument() const heading = screen.getByRole('heading', { level: 1 }) expect(heading).toBeInTheDocument() }) }) EOF # 5) Create integration test example: cat > tests/integration/api/health.test.ts << 'EOF' import { GET } from '@/app/api/health/route' import { NextRequest } from 'next/server' describe('/api/health', () => { it('should return health status', async () => { const request = new NextRequest('http://localhost:3000/api/health') const response = await GET() expect(response.status).toBe(200) const data = await response.json() expect(data).toHaveProperty('status') expect(data).toHaveProperty('timestamp') expect(data).toHaveProperty('environment') expect(data).toHaveProperty('services') }) it('should include platform information', async () => { const request = new NextRequest('http://localhost:3000/api/health') const response = await GET() const data = await response.json() expect(data.platform).toHaveProperty('node') expect(data.platform).toHaveProperty('platform') expect(data.platform).toHaveProperty('uptime') }) }) EOF # 6) Create test utilities: cat > tests/utils/test-utils.tsx << 'EOF' import React from 'react' import { render, RenderOptions } from '@testing-library/react' // Custom render function that includes providers const customRender = ( ui: React.ReactElement, options?: Omit ) => { const AllTheProviders = ({ children }: { children: React.ReactNode }) => { return <>{children} } return render(ui, { wrapper: AllTheProviders, ...options }) } export * from '@testing-library/react' export { customRender as render } EOF # 7) Add npm scripts: npm pkg set scripts.test="jest" npm pkg set scripts.test:watch="jest --watch" npm pkg set scripts.test:coverage="jest --coverage" npm pkg set scripts.test:unit="jest tests/unit" npm pkg set scripts.test:integration="jest tests/integration" # 8) Create test documentation: cat > tests/README.md << 'EOF' # Testing Strategy #### Test Types #### Unit Tests (`tests/unit/`) - Test individual components and functions - Fast execution (< 1 second each) - No external dependencies - Mock all external services #### Integration Tests (`tests/integration/`) - Test component interactions - Test API routes - Test database operations - Use real implementations where safe #### E2E Tests (`tests/e2e/`) - Test complete user workflows - Use real browser automation - Test critical paths only - Slower execution (30+ seconds) #### Running Tests ```bash # All tests npm test # Unit tests only npm run test:unit # Integration tests only npm run test:integration # E2E tests only npm run test:e2e # With coverage npm run test:coverage # Watch mode npm run test:watch ```` #### Coverage Requirements - Lines: 80% - Functions: 80% - Branches: 80% - Statements: 80% #### Best Practices 1. Write tests before code (TDD) 2. Test behavior, not implementation 3. Use descriptive test names 4. Keep tests simple and focused 5. Mock external dependencies 6. Clean up after tests EOF echo "✅ Testing strategy established with unit, integration, and E2E tests" ```` #### Knowledge Check - Module 7 Before proceeding to the next module, verify you can: ✓ Set up comprehensive end-to-end testing with Playwright installation and configuration ✓ Create automated test suites for web application functionality including smoke tests ✓ Implement proper browser cleanup procedures to prevent resource leaks ✓ Understand testing best practices including TDD, behavior testing, and dependency mocking If you cannot complete all checkpoints, review the relevant lessons in this module. #### ✅ Module 6 Success Validation **🎯 Complete these verification steps to confirm mastery:**

📋 Knowledge Check: Testing Infrastructure

**Quick Test Commands (Run in Terminal):** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Verify Playwright testing setup echo "=== Module 7 Testing Infrastructure Verification ===" echo "Checking Playwright installation..." npx playwright --version 2>/dev/null || echo "Playwright not installed" echo "Verifying test files..." ls -la __tests__/ tests/ e2e/ 2>/dev/null || echo "Test directories not found" echo "Testing browser setup..." npx playwright install --dry-run chromium || echo "Browser installation needed" echo "Running cleanup verification..." npm run playwright:cleanup 2>/dev/null && echo "✅ Cleanup script available" || echo "❌ No cleanup script" ``` **✅ Expected Output:** ``` === Module 7 Testing Infrastructure Verification === Checking Playwright installation... Playwright v1.x.x Verifying test files... total X drwxr-xr-x ... __tests__ Testing browser setup... Browser already installed Running cleanup verification... ✅ Cleanup script available ``` **🎉 Success Indicators:** - ✅ Playwright is installed and configured - ✅ Test directories and files exist - ✅ Browser cleanup procedures are in place - ✅ Test scripts are properly configured - ✅ E2E testing framework is ready **⚠️ If you see errors:** - Review the Playwright installation section - Check browser setup and cleanup procedures - Reference the testing strategy guide above

🎯 Module 7 Completion Checklist

**Congratulations! You've mastered Module 7!** **Skills Verified:** - ✅ Comprehensive end-to-end testing with Playwright - ✅ Automated test suite creation and execution - ✅ Browser cleanup and resource management **Next Steps:** - [ ] Ready for Module 8: Deployment and Operations - [ ] Optional: Create advanced test scenarios - [ ] Bookmark: Reference testing best practices **Achievement Unlocked: Testing Infrastructure Expert** 🏅

#### ✅ Test This! Playwright Setup Verification **🧪 Run these verification commands:** ```bash # Step 1: Verify Playwright installation npx playwright --version # Step 2: Test browser installation npx playwright install chromium # Step 3: Run a basic test npx playwright test --reporter=line || echo "No tests configured yet" # Step 4: CRITICAL - Verify cleanup npm run playwright:cleanup echo "✅ Browser cleanup completed" ``` **🎯 Success Criteria:** ```text ✅ Expected Output 1: Playwright version displays ✅ Expected Output 2: Browser installation completes ✅ Expected Output 3: Test runner executes (may show no tests) ✅ Expected Output 4: Cleanup script runs without errors ``` **🚨 Troubleshooting Quick Fix:** If any step fails: 1. **Check**: Playwright dependencies are installed in package.json 2. **Verify**: Browser binaries are properly downloaded 3. **Retry**: `npx playwright install` to ensure browsers are available 4. **Escalate**: Reference the Playwright installation and cleanup sections if issues persist --- ## Module 8: Deployment and Operations ### Lesson: CI/CD Pipeline with GitHub Actions What this prompt will do: - Create a GitHub Actions CI/CD workflow with quality gates - Add npm scripts for build/test/lint where needed - No secret changes; local files only ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create a comprehensive CI/CD pipeline with quality gates and deployment automation. # Non-interactive defaults (do NOT prompt about these): # - Directory: current working directory # - Package manager: npm # - Git: OK to initialize repo and make commits as scripted **🛡️ Safety Reference: See "Module 1: Understanding Safety Guardrails and Risk Management" for detailed safety levels and best practices.** Choose your safety level for this prompt: - **Low (Fast)**: Preface with `Guardrails: Low` - minimal confirmations - **Medium (Balanced)**: Default - confirm major operations - **High (Strict)**: Preface with `Guardrails: High` - step-by-step approvals # Set up GitHub Actions CI/CD pipeline # 1) Create GitHub Actions workflow: mkdir -p .github/workflows cat > .github/workflows/ci-cd.yml << 'EOF' name: CI/CD Pipeline on: push: branches: [main, develop] pull_request: branches: [main] env: NODE_VERSION: '20' jobs: # Quality Gates lint-and-typecheck: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'npm' - name: Install dependencies run: npm ci - name: Run linting run: npm run lint - name: Run type checking run: npm run typecheck - name: Check formatting run: npm run format -- --check # Unit and Integration Tests test: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'npm' - name: Install dependencies run: npm ci - name: Run unit tests run: npm run test:unit - name: Run integration tests run: npm run test:integration - name: Generate coverage report run: npm run test:coverage - name: Upload coverage to Codecov uses: codecov/codecov-action@v3 with: file: ./coverage/lcov.info # Build Application build: runs-on: ubuntu-latest needs: [lint-and-typecheck, test] steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'npm' - name: Install dependencies run: npm ci - name: Build application run: npm run build - name: Upload build artifacts uses: actions/upload-artifact@v3 with: name: build-files path: .next/ # E2E Tests e2e-tests: runs-on: ubuntu-latest needs: [build] steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'npm' - name: Install dependencies run: npm ci - name: Install Playwright browsers run: npx playwright install --with-deps - name: Download build artifacts uses: actions/download-artifact@v3 with: name: build-files path: .next/ - name: Run E2E tests run: npm run test:e2e - name: Upload E2E test results uses: actions/upload-artifact@v3 if: always() with: name: playwright-report path: playwright-report/ - name: Cleanup browsers if: always() run: npm run playwright:cleanup # Security Audit security: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'npm' - name: Install dependencies run: npm ci - name: Run security audit run: npm audit --audit-level=high - name: Check for known vulnerabilities run: npx audit-ci --config audit-ci.json # Deploy to Staging deploy-staging: runs-on: ubuntu-latest needs: [e2e-tests, security] if: github.ref == 'refs/heads/develop' environment: staging steps: - name: Deploy to staging run: | echo "Deploying to staging environment..." # Add your staging deployment commands here # Deploy to Production deploy-production: runs-on: ubuntu-latest needs: [e2e-tests, security] if: github.ref == 'refs/heads/main' environment: production steps: - name: Deploy to production run: | echo "Deploying to production environment..." # Add your production deployment commands here - name: Notify deployment run: | echo "Production deployment complete" # Add notification logic (Slack, email, etc.) EOF # 2) Create audit configuration: cat > audit-ci.json << 'EOF' { "moderate": true, "high": true, "critical": true, "allowlist": [ ] } EOF # 3) Create deployment scripts: mkdir -p scripts/deploy cat > scripts/deploy/staging.sh << 'EOF' #!/bin/bash set -e echo "🚀 Deploying to staging..." # Build for staging NODE_ENV=staging npm run build # Deploy to staging platform (Vercel example) if command -v vercel &> /dev/null; then vercel --target staging --confirm else echo "Vercel CLI not found, add your deployment commands here" fi echo "✅ Staging deployment complete" EOF cat > scripts/deploy/production.sh << 'EOF' #!/bin/bash set -e echo "🚀 Deploying to production..." # Final checks before production echo "Running final checks..." npm run lint npm run typecheck npm run test:coverage # Build for production NODE_ENV=production npm run build # Deploy to production platform if command -v vercel &> /dev/null; then vercel --prod --confirm else echo "Add your production deployment commands here" fi echo "✅ Production deployment complete" EOF chmod +x scripts/deploy/*.sh # 4) Create environment-specific configs: cat > next.config.js << 'EOF' /** @type {import('next').NextConfig} */ const nextConfig = { env: { CUSTOM_KEY: process.env.CUSTOM_KEY, }, images: { domains: ['localhost'], }, // Security headers async headers() { return [ { source: '/(.*)', headers: [ { key: 'X-Content-Type-Options', value: 'nosniff', }, { key: 'X-Frame-Options', value: 'DENY', }, { key: 'X-XSS-Protection', value: '1; mode=block', }, ], }, ] }, } module.exports = nextConfig EOF # 5) Add deployment scripts to package.json: npm pkg set scripts.deploy:staging="./scripts/deploy/staging.sh" npm pkg set scripts.deploy:production="./scripts/deploy/production.sh" echo "✅ CI/CD pipeline configured with quality gates and deployment automation" ```` ### Lesson: Monitoring, Security, and Performance What this prompt will do: - Add monitoring, security, and performance configuration/files - Integrate Sentry and headers as shown - No remote pushes; follow guardrails level ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Set up monitoring with Sentry, security headers, performance tracking, and error handling. # Set up comprehensive monitoring and security # 1) Install monitoring dependencies: npm install @sentry/nextjs # 2) Create Sentry configuration: cat > sentry.client.config.ts << 'EOF' import * as Sentry from '@sentry/nextjs' Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, environment: process.env.NODE_ENV, tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0, debug: process.env.NODE_ENV === 'development', beforeSend(event) { // Don't send events in development unless explicitly enabled if (process.env.NODE_ENV === 'development' && !process.env.SENTRY_DEBUG) { return null } return event }, integrations: [ new Sentry.BrowserTracing({ tracePropagationTargets: ['localhost', /^https:\/\/yourapp\.com\/api/], }), ], }) EOF cat > sentry.server.config.ts << 'EOF' import * as Sentry from '@sentry/nextjs' Sentry.init({ dsn: process.env.NEXT_PUBLIC_SENTRY_DSN, environment: process.env.NODE_ENV, tracesSampleRate: process.env.NODE_ENV === 'production' ? 0.1 : 1.0, debug: process.env.NODE_ENV === 'development', }) EOF # 3) Create middleware for security headers and rate limiting: cat > src/middleware.ts << 'EOF' import { NextResponse } from 'next/server' import type { NextRequest } from 'next/server' // Simple in-memory rate limiting (use Redis in production) const rateLimitMap = new Map() export function middleware(request: NextRequest) { const response = NextResponse.next() // Security headers response.headers.set('X-Content-Type-Options', 'nosniff') response.headers.set('X-Frame-Options', 'DENY') response.headers.set('X-XSS-Protection', '1; mode=block') response.headers.set('Referrer-Policy', 'origin-when-cross-origin') response.headers.set( 'Content-Security-Policy', "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https:;" ) // Rate limiting for API routes if (request.nextUrl.pathname.startsWith('/api/')) { const ip = request.ip ?? '127.0.0.1' const limit = 100 // requests per minute const windowMs = 60 * 1000 // 1 minute if (!rateLimitMap.has(ip)) { rateLimitMap.set(ip, { count: 0, lastReset: Date.now(), }) } const clientRate = rateLimitMap.get(ip) if (Date.now() - clientRate.lastReset > windowMs) { clientRate.count = 0 clientRate.lastReset = Date.now() } if (clientRate.count >= limit) { return new NextResponse('Too Many Requests', { status: 429, headers: { 'Retry-After': '60', }, }) } clientRate.count += 1 } return response } export const config = { matcher: [ '/((?!_next/static|_next/image|favicon.ico).*)', ], } EOF # 4) Create error boundary: cat > src/components/ErrorBoundary.tsx << 'EOF' 'use client' import React from 'react' import * as Sentry from '@sentry/nextjs' interface Props { children: React.ReactNode fallback?: React.ComponentType<{ error: Error; resetError: () => void }> } interface State { hasError: boolean error?: Error } class ErrorBoundary extends React.Component { constructor(props: Props) { super(props) this.state = { hasError: false } } static getDerivedStateFromError(error: Error): State { return { hasError: true, error } } componentDidCatch(error: Error, errorInfo: React.ErrorInfo) { Sentry.captureException(error, { contexts: { react: { componentStack: errorInfo.componentStack, }, }, }) } render() { if (this.state.hasError && this.state.error) { const Fallback = this.props.fallback || DefaultErrorFallback return ( this.setState({ hasError: false, error: undefined })} /> ) } return this.props.children } } function DefaultErrorFallback({ error, resetError }: { error: Error; resetError: () => void }) { return (

Something went wrong

{process.env.NODE_ENV === 'development' ? error.message : 'An unexpected error occurred'}

) } export default ErrorBoundary EOF # 5) Create performance monitoring: cat > src/lib/performance.ts << 'EOF' import * as Sentry from '@sentry/nextjs' export function trackPageView(url: string) { if (typeof window !== 'undefined') { // Track page views Sentry.addBreadcrumb({ message: `Page view: ${url}`, level: 'info', category: 'navigation', }) // Track Core Web Vitals if ('web-vital' in window) { // This would integrate with a real web vitals library console.log('Tracking web vitals for:', url) } } } export function trackUserAction(action: string, data?: Record) { Sentry.addBreadcrumb({ message: action, level: 'info', category: 'user', data, }) } export function trackAPICall(endpoint: string, method: string, duration: number, status: number) { Sentry.addBreadcrumb({ message: `API ${method} ${endpoint}`, level: status >= 400 ? 'error' : 'info', category: 'api', data: { method, endpoint, duration, status, }, }) } EOF # 6) Create monitoring dashboard API: cat > src/app/api/monitoring/route.ts << 'EOF' import { NextResponse } from 'next/server' export async function GET() { const monitoring = { uptime: process.uptime(), memory: process.memoryUsage(), cpu: process.cpuUsage(), environment: process.env.NODE_ENV, version: process.env.npm_package_version || '1.0.0', timestamp: new Date().toISOString(), // Health checks for external services services: { database: await checkDatabaseHealth(), cache: await checkCacheHealth(), external: await checkExternalServicesHealth(), }, } return NextResponse.json(monitoring) } async function checkDatabaseHealth(): Promise { try { // Add your database health check here return true } catch { return false } } async function checkCacheHealth(): Promise { try { // Add your cache health check here return true } catch { return false } } async function checkExternalServicesHealth(): Promise> { return { stripe: true, // Add real checks resend: true, convex: true, } } EOF # 7) Update environment variables: cat >> .env.example << 'EOF' # Monitoring NEXT_PUBLIC_SENTRY_DSN= SENTRY_AUTH_TOKEN= EOF echo "✅ Monitoring, security, and performance tracking configured" ``` #### Knowledge Check - Module 8 Before proceeding to the next module, verify you can: ✓ Build automated CI/CD pipelines with GitHub Actions including quality gates and testing ✓ Configure production deployments with proper monitoring and error tracking systems ✓ Implement security scanning workflows and performance optimization techniques ✓ Set up environment variables and deployment configurations for production readiness If you cannot complete all checkpoints, review the relevant lessons in this module. #### ✅ Module 7 Success Validation **🎯 Complete these verification steps to confirm mastery:**

📋 Knowledge Check: Deployment and Operations

**Quick Test Commands (Run in Terminal):** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Verify deployment and operations setup echo "=== Module 8 Deployment and Operations Verification ===" echo "Checking GitHub Actions workflow..." ls -la .github/workflows/ 2>/dev/null || echo "No workflows found" echo "Verifying environment configurations..." ls -la .env.example .env.local 2>/dev/null || echo "Environment files not found" echo "Testing production build..." npm run build && echo "✅ Production build successful" || echo "❌ Build failed" echo "Checking deployment readiness..." npm run start 2>/dev/null & sleep 3 curl -f http://localhost:3000 >/dev/null 2>&1 && echo "✅ Production server responsive" || echo "❌ Server not responding" pkill -f "next start" 2>/dev/null ``` **✅ Expected Output:** ``` === Module 8 Deployment and Operations Verification === Checking GitHub Actions workflow... total X -rw-r--r-- ... .github/workflows/ci.yml Verifying environment configurations... -rw-r--r-- ... .env.example Testing production build... ✅ Production build successful Checking deployment readiness... ✅ Production server responsive ``` **🎉 Success Indicators:** - ✅ CI/CD pipelines are configured - ✅ Environment variables are properly set up - ✅ Production build completes successfully - ✅ Production server is operational - ✅ Deployment configurations are ready **⚠️ If you see errors:** - Review the GitHub Actions setup section - Check environment configuration guide - Reference the deployment operations documentation

🎯 Module 8 Completion Checklist

**Congratulations! You've mastered Module 8!** **Skills Verified:** - ✅ Automated CI/CD pipelines with GitHub Actions - ✅ Production deployment configuration - ✅ Security scanning and performance optimization **Next Steps:** - [ ] Ready for Module 9: Troubleshooting and Support - [ ] Optional: Explore advanced deployment strategies - [ ] Bookmark: Reference deployment best practices **Achievement Unlocked: Deployment and Operations Master** 🏅

--- ## Module 9: Troubleshooting, Visual Guides and Documentation ### Lesson: Common Issues Decision Trees What this prompt will do: - Create troubleshooting guides and decision trees under docs/ - Provide step-by-step flows for common issues - Safe changes only; respect guardrails level ````text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create decision trees and flowcharts for common development issues with concrete solutions. # Create comprehensive troubleshooting guides # 1) Create main troubleshooting document: cat > docs/troubleshooting.md << 'EOF' # Troubleshooting Guide #### Quick Fixes #### Command Not Found ``` Error: 'npm' is not recognized as an internal or external command ``` **Decision Tree:** 1. Is Node.js installed? → `node -v` - No → Install Node.js from nodejs.org - Yes → Continue to step 2 2. Is npm in PATH? → `echo $PATH` (Unix) or `echo %PATH%` (Windows) - No → Reinstall Node.js or add to PATH manually - Yes → Restart terminal and try again **Next Action:** Verify with `npm -v` after fix #### Permission Denied ``` Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules' ``` **Decision Tree:** 1. Are you using sudo? → Check command - Yes → STOP! Use npm config instead - No → Continue to step 2 2. Is this a global install? → Check for `-g` flag - Yes → Use `npm config set prefix ~/.npm-global` - No → Check local permissions **Next Action:** Add `~/.npm-global/bin` to PATH #### Port In Use ``` Error: listen EADDRINUSE :::3000 ``` **Decision Tree:** 1. Find what's using the port → `lsof -i :3000` (Unix) or `netstat -ano | findstr :3000` (Windows) 2. Is it your own app? → Check process name - Yes → Kill with `kill -9 ` or use `npm run playwright:cleanup` - No → Use different port with `PORT=3001 npm run dev` **Next Action:** Verify port is free with `lsof -i :3001` #### Environment Missing ``` Error: Missing required environment variable: DATABASE_URL ``` **Decision Tree:** 1. Check .env file exists → `ls -la .env*` - No → Copy from .env.example - Yes → Continue to step 2 2. Check variable is defined → `grep DATABASE_URL .env.local` - No → Add the variable - Yes → Check for typos **Next Action:** Restart dev server after fixing #### Failed Build ``` Error: Type error: Property 'user' does not exist on type '{}' ``` **Decision Tree:** 1. Is this a TypeScript error? → Check file extension - Yes → Fix type definitions - No → Continue to step 2 2. Are dependencies up to date? → `npm outdated` - No → Update with caution - Yes → Check for breaking changes **Next Action:** Run `npm run typecheck` to verify fix #### Failing Tests ``` Error: Tests failed: 3 failed, 7 passed ``` **Decision Tree:** 1. Are tests failing consistently? → Run tests multiple times - No → Flaky tests - check async operations - Yes → Continue to step 2 2. Did you change related code? → Check git diff - Yes → Update tests to match changes - No → Check test environment **Next Action:** Run single failing test with `npm test -- --testNamePattern="failing test"` EOF # 2) Create specific error guides: mkdir -p docs/troubleshooting cat > docs/troubleshooting/next-js-errors.md << 'EOF' # Next.js Specific Errors #### Hydration Errors ``` Warning: Text content did not match. Server: "..." Client: "..." ``` **Causes:** - Date/time differences between server and client - Random content generation - Browser-only APIs used during SSR **Solutions:** 1. Use `useEffect` for client-only content 2. Use `suppressHydrationWarning` sparingly 3. Ensure consistent data between server and client #### Import Errors ``` Error: Module not found: Can't resolve 'component' ``` **Causes:** - Incorrect import paths - Missing file extensions - Case sensitivity issues **Solutions:** 1. Check file exists at specified path 2. Use relative imports correctly (`./` or `../`) 3. Verify case matches exactly (especially on Linux) #### API Route Errors ``` Error: API resolved without sending a response ``` **Causes:** - Missing return statement - Conditional responses without default - Async operations not awaited **Solutions:** 1. Always return a response 2. Handle all code paths 3. Use proper async/await syntax EOF cat > docs/troubleshooting/git-issues.md << 'EOF' # Git Troubleshooting #### Merge Conflicts ``` error: Your local changes to the following files would be overwritten by merge ``` **Resolution Steps:** 1. Stash changes: `git stash push -m "work in progress"` 2. Pull updates: `git pull origin main` 3. Apply stash: `git stash pop` 4. Resolve conflicts manually 5. Commit resolved changes #### Detached HEAD ``` You are in 'detached HEAD' state ``` **Resolution Steps:** 1. Create branch: `git checkout -b feature-branch` 2. Or return to main: `git checkout main` 3. If you made changes, commit them first #### Large File Issues ``` error: File too large (exceeds 100 MB) ``` **Resolution Steps:** 1. Remove from tracking: `git rm --cached large-file` 2. Add to .gitignore: `echo "large-file" >> .gitignore` 3. Commit the removal 4. Use Git LFS for large files if needed EOF # 3) Create debugging scripts: cat > scripts/debug-environment.sh << 'EOF' #!/bin/bash echo "🔍 Environment Debug Report" echo "==========================" echo "📍 Location:" echo "Working Directory: $(pwd)" echo "Node Location: $(which node 2>/dev/null || echo 'Not found')" echo "NPM Location: $(which npm 2>/dev/null || echo 'Not found')" echo "" echo "📦 Versions:" echo "Node: $(node -v 2>/dev/null || echo 'Not installed')" echo "NPM: $(npm -v 2>/dev/null || echo 'Not installed')" echo "Git: $(git --version 2>/dev/null || echo 'Not installed')" echo "" echo "🔧 Environment:" echo "NODE_ENV: ${NODE_ENV:-'not set'}" echo "PATH: ${PATH}" echo "" echo "📁 Project Files:" ls -la package.json 2>/dev/null && echo "✅ package.json exists" || echo "❌ package.json missing" ls -la .env.local 2>/dev/null && echo "✅ .env.local exists" || echo "❌ .env.local missing" ls -la node_modules 2>/dev/null && echo "✅ node_modules exists" || echo "❌ node_modules missing" echo "" echo "🚀 Processes:" echo "Ports in use:" lsof -i :3000 2>/dev/null || echo "Port 3000 is free" lsof -i :3001 2>/dev/null || echo "Port 3001 is free" echo "" echo "Debug complete! 🎯" EOF chmod +x scripts/debug-environment.sh # 4) Create VS Code debugging configuration: mkdir -p .vscode cat > .vscode/launch.json << 'EOF' { "version": "0.2.0", "configurations": [ { "name": "Next.js: debug server-side", "type": "node", "request": "attach", "port": 9229, "skipFiles": ["/**"] }, { "name": "Next.js: debug client-side", "type": "chrome", "request": "launch", "url": "http://localhost:3000" }, { "name": "Next.js: debug full stack", "type": "node", "request": "launch", "program": "${workspaceFolder}/node_modules/.bin/next", "args": ["dev"], "env": { "NODE_OPTIONS": "--inspect" }, "skipFiles": ["/**"], "console": "integratedTerminal" } ] } EOF echo "✅ Troubleshooting guides and debugging tools created" ```` ### Lesson: Getting Help and Documentation Templates What this prompt will do: - Create help and documentation templates under docs/ - Provide consistent request/communication formats - No installs or remote pushes; honor guardrails ````text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create help templates, documentation standards, and effective communication guides. # Create help and documentation templates # 1) Create help request template: cat > docs/help-template.md << 'EOF' # Getting Help Template Copy and fill out this template when asking for help: #### Problem Description Describe what you're trying to do and what's going wrong: **Expected behavior:** [What should happen] **Actual behavior:** [What actually happens] **Error message (exact text):** ``` [Paste the complete error message here] ``` #### Environment Details **Operating System:** [Windows 10, macOS 12.1, Ubuntu 20.04, etc.] **Node.js version:** [Run `node -v`] **NPM version:** [Run `npm -v`] **Browser:** [Chrome 96, Firefox 95, Safari 15, etc.] #### Steps to Reproduce 1. [First step] 2. [Second step] 3. [Continue...] #### What I've Tried - [List everything you've attempted] - [Include links to documentation you've read] - [Mention any solutions that didn't work] #### Code/Configuration **Relevant code:** ```javascript // Paste relevant code here ``` **Package.json scripts:** ```json { "scripts": { // Paste relevant scripts } } ``` #### Additional Context - [Recent changes to the codebase] - [Any other information that might be relevant] #### Screenshots/Videos [Attach if helpful] EOF # 2) Create documentation standards: cat > docs/documentation-standards.md << 'EOF' # Documentation Standards #### Code Comments #### When to Comment - Complex business logic - Non-obvious code behavior - API integrations - Security considerations - Performance optimizations #### Comment Style ```typescript /** * Calculates user subscription renewal date * * @param startDate - Initial subscription date * @param planType - Subscription plan (monthly, yearly) * @returns ISO date string for next renewal * * @example * calculateRenewal('2023-01-01', 'monthly') // '2023-02-01' */ function calculateRenewal(startDate: string, planType: string): string { // Implementation here } ``` #### README Structure #### Required Sections 1. **Project Title & Description** 2. **Prerequisites** 3. **Installation** 4. **Usage** 5. **Development** 6. **Testing** 7. **Deployment** 8. **Contributing** #### Example README ```markdown # Project Name Brief description of what this project does. #### Prerequisites - Node.js 20+ - npm 8+ - Git #### Installation \`\`\`bash git clone [repo-url] cd project-name npm install \`\`\` #### Usage \`\`\`bash npm run dev \`\`\` Visit http://localhost:3000 #### Development See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines. #### Testing \`\`\`bash npm test npm run test:e2e \`\`\` #### Deployment See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) ``` #### API Documentation #### Endpoint Documentation ```typescript /** * GET /api/users * * Retrieves a paginated list of users * * Query Parameters: * - page: number (default: 1) * - limit: number (default: 10, max: 100) * - search: string (optional) * * Returns: * - 200: { users: User[], total: number, page: number } * - 400: { error: string } * - 500: { error: string } */ ``` #### Component Documentation #### Props Documentation ```typescript interface ButtonProps { /** Button text content */ children: React.ReactNode /** Button variant style */ variant?: 'primary' | 'secondary' | 'danger' /** Click handler */ onClick?: () => void /** Disable button interaction */ disabled?: boolean } ``` EOF # 3) Create debugging checklist: cat > docs/debugging-checklist.md << 'EOF' # Debugging Checklist #### Before You Start - [ ] Save all files - [ ] Clear browser cache - [ ] Restart development server - [ ] Check console for errors #### Environment Check - [ ] Correct Node.js version - [ ] Dependencies installed (`npm install`) - [ ] Environment variables set - [ ] In correct directory #### Code Review - [ ] Syntax errors (linter) - [ ] Type errors (TypeScript) - [ ] Import/export paths correct - [ ] Variable names spelled correctly #### Browser Tools - [ ] Check Network tab for failed requests - [ ] Review Console for JavaScript errors - [ ] Inspect Elements for CSS issues - [ ] Check Application tab for storage issues #### Git Status - [ ] On correct branch - [ ] No uncommitted changes affecting debugging - [ ] Latest changes pulled from remote #### Testing - [ ] Reproduce issue consistently - [ ] Test in different browsers - [ ] Test with different data - [ ] Check in incognito/private mode #### Error Analysis - [ ] Read error message completely - [ ] Note line numbers and file names - [ ] Understand the stack trace - [ ] Research error message online #### Documentation - [ ] Take screenshots of errors - [ ] Note exact steps to reproduce - [ ] Record what you've tried - [ ] Prepare information for help request EOF # 4) Create error message interpreter: cat > scripts/interpret-error.js << 'EOF' #!/usr/bin/env node const errorPatterns = { 'EADDRINUSE': { description: 'Port already in use', solutions: [ 'Kill process using the port', 'Use a different port', 'Run: npm run playwright:cleanup' ] }, 'EACCES': { description: 'Permission denied', solutions: [ 'Check file permissions', 'Avoid using sudo with npm', 'Configure npm prefix for global installs' ] }, 'MODULE_NOT_FOUND': { description: 'Cannot find module', solutions: [ 'Run npm install', 'Check import path is correct', 'Verify file exists' ] }, 'SyntaxError': { description: 'JavaScript syntax error', solutions: [ 'Check for missing brackets, parentheses, or semicolons', 'Verify proper string quotes', 'Check for reserved keywords' ] } } function interpretError(errorMessage) { console.log('🔍 Error Interpreter') console.log('===================') for (const [pattern, info] of Object.entries(errorPatterns)) { if (errorMessage.includes(pattern)) { console.log(`\n📋 Error Type: ${info.description}`) console.log('\n💡 Suggested Solutions:') info.solutions.forEach((solution, i) => { console.log(` ${i + 1}. ${solution}`) }) return } } console.log('\n❓ Error not recognized. Please:') console.log(' 1. Check the full error message') console.log(' 2. Search online for the exact error') console.log(' 3. Ask for help with the complete error text') } // Get error from command line argument const errorMessage = process.argv[2] if (!errorMessage) { console.log('Usage: node scripts/interpret-error.js "error message"') process.exit(1) } interpretError(errorMessage) EOF chmod +x scripts/interpret-error.js # 5) Add help scripts to package.json: npm pkg set scripts.help:debug="./scripts/debug-environment.sh" npm pkg set scripts.help:error="node scripts/interpret-error.js" echo "✅ Help templates and documentation standards created" ```` --- ### Lesson: VS Code UI Navigation Guide What this prompt will do: - Create docs/vscode-guide.md with text-based UI descriptions - Keep content safe (no external writes, no installs) - Follow selected guardrails level (if prefaced) ````text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create text-based descriptions for VS Code interface elements and navigation. # Create VS Code navigation guide cat > docs/vscode-guide.md << 'EOF' # VS Code Interface Guide #### Main Interface Layout ``` ┌─────────────────────────────────────────────────────────────┐ │ [≡] File Edit View Go Run Terminal Help [-][□][×] │ Title Bar ├─────────────────────────────────────────────────────────────┤ │ [📁][🔍][⎇][🐛][🧩] ← Activity Bar │ Editor Group │ │ │ ┌─────────────────────┐ │ │ ┌─────────────────────────────────┐ │ │ tab1 │ tab2 │ tab3│ │ Tab Bar │ │ │ │ ├─────────────────────┤ │ │ │ Side Panel │ │ │ │ │ │ │ │ │ │ │ │ │ │ (Explorer, Search, etc.) │ │ │ Code Editor │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ └─────────────────────────────────┘ │ └─────────────────────┘ │ ├─────────────────────────────────────┼─────────────────────────┤ │ Terminal Panel │ Side Panel (Right) │ │ │ │ └─────────────────────────────────────┴─────────────────────────┤ │ 🌿 main • 2 files changed • Ln 42, Col 8 │ Status Bar └─────────────────────────────────────────────────────────────┘ ``` #### Activity Bar (Left Side) **Location:** Vertical bar on the far left **Icons from top to bottom:** 1. **📁 Explorer** (Ctrl+Shift+E) - Shows file tree - Create/delete/rename files - Navigate project structure 2. **🔍 Search** (Ctrl+Shift+F) - Search across all files - Find and replace - Use regex patterns 3. **⎇ Source Control** (Ctrl+Shift+G) - Git integration - View changes - Commit, push, pull 4. **🐛 Run and Debug** (Ctrl+Shift+D) - Start debugging sessions - Set breakpoints - View debug console 5. **🧩 Extensions** (Ctrl+Shift+X) - Install extensions - Manage installed extensions - Browse marketplace #### Command Palette **Access:** Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (Mac) **Description:** Universal search for all VS Code commands **Common Commands:** - `> Settings` - Open settings - `> Terminal: Create New Terminal` - Open terminal - `> Developer: Reload Window` - Restart VS Code - `> Extensions: Install Extensions` - Install extensions #### Side Panels #### Explorer Panel **How to open:** Click 📁 in Activity Bar or Ctrl+Shift+E **Features:** - File tree navigation - Right-click for context menu - Drag and drop to move files - Create new files/folders #### Search Panel **How to open:** Click 🔍 in Activity Bar or Ctrl+Shift+F **Features:** - Search text: Type in top box - Replace text: Click arrow to expand - Include/exclude files: Use filter boxes - Use regex: Click .* button #### Terminal **How to open:** - View → Terminal - Ctrl+` (backtick) - Command Palette → "Terminal: Create New Terminal" **Features:** - Multiple terminal tabs - Split terminals - Choose shell (bash, zsh, PowerShell) - Integrated with VS Code workspace #### Settings **How to access:** - File → Preferences → Settings - Ctrl+, (Windows/Linux) or Cmd+, (Mac) - Command Palette → "Preferences: Open Settings" **Search settings:** Use search box at top **Common settings:** - `editor.fontSize` - Change text size - `editor.wordWrap` - Wrap long lines - `files.autoSave` - Auto-save files #### AI Panel Integration #### Claude Code Panel **How to open:** - Click Claude Code icon in Activity Bar - Command Palette → "Claude Code: Open Chat" **Features:** - Chat interface for code assistance - Plan mode toggle - File context integration - Command execution #### Alternative AI Panels **How to open:** - Click your AI extension icon in Activity Bar - Side panel on right **Features:** - AI-powered code suggestions - Real-time assistance - Context-aware help #### Keyboard Shortcuts #### Essential Shortcuts | Action | Windows/Linux | Mac | |--------|---------------|-----| | Command Palette | Ctrl+Shift+P | Cmd+Shift+P | | Quick Open | Ctrl+P | Cmd+P | | Toggle Terminal | Ctrl+` | Cmd+` | | Save | Ctrl+S | Cmd+S | | Save All | Ctrl+K S | Cmd+Alt+S | | Close Tab | Ctrl+W | Cmd+W | | New Tab | Ctrl+N | Cmd+N | | Find in File | Ctrl+F | Cmd+F | | Replace in File | Ctrl+H | Cmd+Alt+F | #### Navigation Shortcuts | Action | Windows/Linux | Mac | |--------|---------------|-----| | Go to Line | Ctrl+G | Cmd+G | | Go to File | Ctrl+P | Cmd+P | | Go Back | Alt+← | Ctrl+- | | Go Forward | Alt+→ | Ctrl+Shift+- | | Switch Tab | Ctrl+Tab | Cmd+Tab | #### Customization Tips #### Theme 1. Command Palette → "Preferences: Color Theme" 2. Choose from built-in themes 3. Install theme extensions for more options #### Layout 1. Drag panels to rearrange 2. Right-click tabs for options 3. View → Appearance for layout options #### Workspace 1. Save workspace: File → Save Workspace As 2. Include project-specific settings 3. Share workspace files with team EOF echo "✅ VS Code interface guide created" ```` ### Lesson: Project Documentation Templates What this prompt will do: - Execute the steps under Goal in the current workspace - Create/update the files shown exactly as written - Use non-interactive defaults and your guardrails level (if prefaced); avoid remote pushes ````text Paste into your AI coding assistant (Claude Code, Cursor, or similar). Goal: Create comprehensive project documentation including README, architecture, and contribution guidelines. # Create comprehensive project documentation # 1) Create main README template: cat > README.md << 'EOF' # AI-Generated Platform A modern, full-stack web application built using AI-assisted development workflows. This project demonstrates best practices for TypeScript, Next.js, testing, and deployment. #### 🚀 Quick Start ```bash # Clone and setup git clone cd ai-platform npm install # Start development server npm run dev ``` Visit [http://localhost:3000](http://localhost:3000) #### 📋 Prerequisites - **Node.js**: 18+ (check with `node -v`) - **npm**: 8+ (check with `npm -v`) - **Git**: Latest version - **VS Code**: Recommended editor #### 🛠️ Installation #### 1. Environment Setup ```bash # Copy environment template cp .env.example .env.local # Add your environment variables # Edit .env.local with your API keys ``` #### 2. Dependencies ```bash # Install all dependencies npm install # Install Playwright browsers (for E2E tests) npx playwright install ``` #### 3. Development Tools ```bash # Verify setup npm run typecheck npm run lint npm test ``` #### 🏗️ Project Structure ``` ├── src/ │ ├── app/ # Next.js App Router │ │ ├── api/ # API routes │ │ └── (routes)/ # Page routes │ ├── components/ # Reusable components │ ├── lib/ # Utility libraries │ ├── hooks/ # Custom React hooks │ └── types/ # TypeScript definitions ├── tests/ │ ├── unit/ # Unit tests │ ├── integration/ # Integration tests │ └── e2e/ # End-to-end tests ├── docs/ # Documentation └── scripts/ # Build and utility scripts ``` #### 🧪 Testing ```bash # Run all tests npm test # Unit tests only npm run test:unit # Integration tests npm run test:integration # E2E tests npm run test:e2e # Watch mode npm run test:watch # Coverage report npm run test:coverage ``` #### 🚀 Development #### Available Scripts | Command | Description | | ------------------- | ------------------------- | | `npm run dev` | Start development server | | `npm run build` | Build for production | | `npm run start` | Start production server | | `npm run lint` | Run ESLint | | `npm run typecheck` | Run TypeScript compiler | | `npm run format` | Format code with Prettier | #### BMAD METHOD Integration This project uses BMAD METHOD for development planning: ```bash # Check BMAD status npm run bmad:status # Flatten codebase for AI analysis npm run bmad:flatten ``` See [docs/bmad/](docs/bmad/) for workflow documentation. #### 🔧 Configuration #### Environment Variables Required variables (see `.env.example`): - `NEXT_PUBLIC_APP_URL` - Application URL - `DATABASE_URL` - Database connection string - `API_SECRET_KEY` - API authentication key Optional services: - `CONVEX_DEPLOYMENT` - Convex backend - `CLERK_SECRET_KEY` - Clerk authentication - `STRIPE_SECRET_KEY` - Stripe payments - `RESEND_API_KEY` - Email service #### TypeScript Strict mode enabled with additional checks: - `noUnusedLocals` - `noUnusedParameters` - `noImplicitReturns` #### Linting and Formatting - **ESLint**: Code quality and consistency - **Prettier**: Code formatting - **TypeScript**: Type checking #### 📦 Deployment #### Production Build ```bash npm run build npm run start ``` #### Environment-Specific Deployment ```bash # Staging npm run deploy:staging # Production npm run deploy:production ``` See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for detailed deployment instructions. #### 🤝 Contributing 1. Fork the repository 2. Create feature branch: `git checkout -b feature/amazing-feature` 3. Commit changes: `git commit -m 'Add amazing feature'` 4. Push to branch: `git push origin feature/amazing-feature` 5. Open a Pull Request See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines. #### 📚 Documentation - [Architecture Overview](docs/ARCHITECTURE.md) - [API Documentation](docs/API.md) - [Deployment Guide](docs/DEPLOYMENT.md) - [Troubleshooting](docs/TROUBLESHOOTING.md) - [Development Glossary](docs/glossary.md) #### 🔍 Monitoring and Support #### Health Checks - Application: `/api/health` - Monitoring: `/api/monitoring` - Status Page: `/status` #### Getting Help 1. Check [Troubleshooting Guide](docs/troubleshooting.md) 2. Search existing [GitHub Issues](issues) 3. Use the [Help Template](docs/help-template.md) #### 📄 License This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details. #### 🙏 Acknowledgments - Built with [Claude Code](https://claude.ai/code)](https://augmentcode.com) - Powered by [Next.js](https://nextjs.org/) and [TypeScript](https://typescriptlang.org/) - Tested with [Playwright](https://playwright.dev/) and [Jest](https://jestjs.io/) --- **Built with ❤️ and AI assistance by vybecoding.ai** EOF echo "✅ Comprehensive project documentation created" ```` ``` --- #### Final Checklist Review this checklist to ensure your AI-generated platform is production-ready: - [ ] **Environment Setup**: VS Code, Node.js 20+, Git configured - [ ] **BMAD METHOD**: Installed and integrated with AI assistants - [ ] **AI Configuration**: Claude Code and AI tools properly configured - [ ] **Application**: Next.js app running with TypeScript and Tailwind - [ ] **Environment Variables**: All required variables configured - [ ] **Testing**: Unit, integration, and E2E tests passing - [ ] **CI/CD Pipeline**: GitHub Actions workflow active - [ ] **Monitoring**: Health checks, error tracking, and performance monitoring - [ ] **Documentation**: Complete README, architecture docs, and guides - [ ] **Security**: Headers, input validation, and secrets management - [ ] **Git Repository**: Meaningful commits and proper branch structure - [ ] **Deployment**: Application successfully deployed to hosting platform - [ ] **Cleanup**: Playwright processes cleaned up after tests - [ ] **Performance**: Bundle optimized and Core Web Vitals monitored --- **Congratulations! You've built a production-ready AI-generated platform with comprehensive tooling, testing, and documentation. 🎉** ``` #### Knowledge Check - Module 9 Before proceeding to the next module, verify you can: ✓ Diagnose and resolve common development environment issues systematically ✓ Create troubleshooting workflows and decision trees for recurring problems ✓ Navigate VS Code interface efficiently using keyboard shortcuts and essential commands ✓ Create accessible visual documentation using text-based diagrams and clear formatting ✓ Build comprehensive user guides for development tools and workflows If you cannot complete all checkpoints, review the relevant lessons in this module. #### ✅ Module 9 Success Validation **🎯 Complete these verification steps to confirm mastery:**

📋 Knowledge Check: Visual Guides and Documentation

**Quick Test Commands (Run in Terminal):** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Verify visual guides and documentation setup echo "=== Module 9 Visual Guides and Documentation Verification ===" echo "Checking documentation structure..." ls -la docs/ README.md 2>/dev/null || echo "Documentation not found" echo "Verifying VS Code shortcuts knowledge..." echo "Essential shortcuts: Ctrl+Shift+P (Command Palette), Ctrl+` (Terminal), F1 (Help)" echo "Checking diagram capabilities..." echo "Text-based diagrams available: ASCII art, Mermaid, PlantUML" echo "Testing documentation tools..." echo "Documentation tools: Markdown, VS Code, diagrams.net, text-based formats" ``` **✅ Expected Output:** ``` === Module 9 Visual Guides and Documentation Verification === Checking documentation structure... total X drwxr-xr-x ... docs -rw-r--r-- ... README.md Verifying VS Code shortcuts knowledge... Essential shortcuts: Ctrl+Shift+P (Command Palette), Ctrl+` (Terminal), F1 (Help) Checking diagram capabilities... Text-based diagrams available: ASCII art, Mermaid, PlantUML Testing documentation tools... Documentation tools: Markdown, VS Code, diagrams.net, text-based formats ``` **🎉 Success Indicators:** - ✅ Documentation structure is established - ✅ VS Code shortcuts are mastered - ✅ Visual documentation capabilities are available - ✅ Text-based diagram skills are developed - ✅ User guide creation process is understood **⚠️ If you see errors:** - Review the VS Code interface navigation section - Check visual documentation creation guide - Reference the text-based diagram tutorials

🎯 Module 9 Completion Checklist

**Congratulations! You've mastered Module 9!** **Skills Verified:** - ✅ VS Code interface navigation efficiency - ✅ Accessible visual documentation creation - ✅ Comprehensive user guide development **Next Steps:** - [ ] Ready for Module 10: Agent Teams, Hooks and Automation - [ ] Optional: Create advanced visual documentation - [ ] Bookmark: Reference documentation best practices **Achievement Unlocked: Visual Documentation Master** 🏅

--- ## Module 10: Agent Teams, Hooks and Automation By this point in the guide, you have learned how to use Claude Code for individual tasks: writing code, debugging, refactoring, and generating tests. This module introduces a new dimension — **automating Claude Code itself**, and eventually, coordinating multiple AI agents working in parallel. Think of this module as moving from "solo developer with an AI assistant" to "team lead who can delegate work to multiple specialized agents and automate routine tasks." You do not need to implement everything here immediately. The goal is to understand what is possible so you can apply these patterns when you are ready. --- ### Lesson 10.1: Claude Code Hooks #### What Are Hooks? 💡 **What is a hook?** A hook is an automated action that runs in response to an event. You have probably encountered hooks before — for example, Git has `pre-commit` hooks that run scripts before you commit code. Claude Code has a similar system, but for AI-assisted development events. Hooks let you say: *"Every time Claude edits a file, automatically run the linter."* Or: *"When a session starts, check the environment is set up correctly."* Or: *"After Claude finishes a task, commit the changes to Git."* You write the instructions once, and they run automatically — no need to remember to do it manually. **The analogy:** Hooks are like automated assistants that watch what you do and respond. Imagine you had an assistant who, every time you finished writing a document, automatically ran spell-check, saved a backup copy, and sent you a summary. That is what hooks do for your development workflow. --- #### Hook Events Claude Code supports five hook events. Each fires at a specific moment in your session: | Event | When It Fires | Common Use | |---|---|---| | `SessionStart` | When a Claude Code session begins | Environment checks, load context | | `PreToolUse` | Before Claude uses any tool | Validation, logging, confirmation | | `PostToolUse` | After Claude uses any tool | Auto-commit, linting, notifications | | `UserPromptSubmit` | When you submit a prompt | Inject context, log prompts | | `Stop` | When Claude finishes a response | Notifications, cleanup | For most beginners, `SessionStart` and `PostToolUse` are the two events you will use most. They let you automate the two most common workflows: 1. **Session setup** — making sure your environment is ready before you start working 2. **Post-edit actions** — running tests, linting, or committing after Claude makes changes --- #### Where Hooks Live Hooks are configured in `.claude/settings.json` under the `"hooks"` key. This file lives at the root of your project. 💡 **What is `.claude/settings.json`?** This file is Claude Code's project-level configuration. It controls how Claude behaves in your specific project. If the file does not exist yet, you can create it — Claude Code will pick it up automatically. Here is a minimal example that shows the structure: ```json { "hooks": { "SessionStart": [], "PostToolUse": [] } } ``` Each event maps to an array of **hook entries**. Each hook entry can have a `matcher` (which filters when the hook fires) and a `hooks` array (the actual commands to run). --- #### A Real Hook Configuration Here is a practical example that covers two common scenarios: ```json { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "echo 'Session started'", "timeout": 5000 } ] } ], "PostToolUse": [ { "matcher": "Edit|MultiEdit|Write", "hooks": [ { "type": "command", "command": "./scripts/auto-commit.sh", "timeout": 10000 } ] } ] } } ``` Let us break this down piece by piece. **The `SessionStart` block:** - Fires once when you start a Claude Code session - No `matcher` needed — it always runs - Runs `echo 'Session started'` with a 5-second timeout - In practice, you would replace this with something useful: checking Node.js version, printing the current sprint, or loading project context **The `PostToolUse` block:** - The `matcher` value `"Edit|MultiEdit|Write"` means: *"only fire this hook when Claude uses the Edit, MultiEdit, or Write tools"* - After any file edit, it runs `./scripts/auto-commit.sh` - The timeout is 10 seconds — if the script takes longer, the hook is cancelled 💡 **What is the `|` in the matcher?** It is a pattern separator meaning "or". So `"Edit|MultiEdit|Write"` means "Edit OR MultiEdit OR Write". You can combine any tool names this way. --- #### Understanding Matcher Patterns The `matcher` field controls which tool uses trigger the hook. Here are the tools you can match against: | Tool Name | What It Does | |---|---| | `Edit` | Edits an existing file (single change) | | `MultiEdit` | Makes multiple edits to a file at once | | `Write` | Creates or overwrites a file entirely | | `Bash` | Runs a shell command | | `Read` | Reads a file | | `Glob` | Searches for files by pattern | | `Grep` | Searches file contents | **Examples of useful matchers:** ``` "Edit|MultiEdit|Write" → Any file modification "Bash" → Any shell command Claude runs "Edit|MultiEdit|Write|Bash" → Any file change or command ``` If you omit the `matcher` field entirely, the hook fires for every tool use — which is usually too broad. Be specific about what you want to trigger. --- #### The `type` and `timeout` Fields Every hook command has two required fields: - **`type`**: Always `"command"` for shell commands (this is the only type currently supported) - **`timeout`**: How many milliseconds to wait before giving up. Use `5000` for quick commands, `30000` for slower scripts, and be generous for operations that might need network access. If a hook command exits with a non-zero status code (meaning it failed), Claude Code will display a warning. It will not stop working — hooks are advisory, not blocking, unless you configure them to be. --- #### Exercise: Create a Linting Hook Let us build a practical hook that runs a linter every time Claude edits a JavaScript or TypeScript file. **Step 1: Make sure you have a linting script available.** Most projects that use ESLint already have a lint command in `package.json`. Verify yours: ```bash cat package.json | grep '"lint"' ``` You should see something like: ``` "lint": "eslint . --ext .ts,.tsx,.js,.jsx", ``` **Step 2: Create the hook configuration.** Open or create `.claude/settings.json` and add: ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|MultiEdit|Write", "hooks": [ { "type": "command", "command": "npm run lint --silent 2>&1 | tail -20", "timeout": 30000 } ] } ] } } ``` 💡 **What does `2>&1 | tail -20` mean?** This is a shell pattern that combines error output with regular output (`2>&1`) and then shows only the last 20 lines (`tail -20`). This keeps hook output readable — instead of flooding your terminal with hundreds of lint warnings, you see only the most recent ones. **Step 3: Test it.** Ask Claude to make a small edit to any file: ``` Add a comment to the top of src/index.ts saying "// Entry point" ``` After the edit, you should see the lint output appear automatically in your terminal. No manual `npm run lint` needed. **Step 4: Iterate.** If the linter output is too noisy, adjust the command. For example, you might only want to lint the specific file that was changed: ```json "command": "npm run lint -- --quiet 2>&1 | head -10" ``` The `--quiet` flag suppresses warnings and shows only errors. `head -10` limits output to 10 lines. --- #### A Note on Hook Safety Hooks run shell commands automatically, which means they can do things you did not explicitly ask for. Follow these principles when writing hooks: 1. **Start simple.** A hook that runs `echo` or `npm run lint` is safe. A hook that runs `git push` or `rm -rf` is not something to add without careful thought. 2. **Use timeouts.** Always set a reasonable timeout. Without one, a hanging hook can block your session. 3. **Test your commands manually first.** Before adding a command to a hook, run it in the terminal yourself. Make sure it works and does what you expect. 4. **Read the output.** Hooks print their output to your Claude Code session. Review it, especially early on. --- ### Lesson 10.2: Multi-Agent Workflows with Worktrees 💡 **Who is this lesson for?** This lesson introduces concepts you do not need on day one. If you are just getting started with Claude Code, read through it to understand what is possible, then return to it when you are building larger features and feeling the limits of a single-agent workflow. --- #### The Problem: One Agent, One Task at a Time When you work with a single Claude Code session, work is sequential. Claude writes the feature code, then you run tests, then Claude fixes failures, then someone writes documentation. Each step waits for the previous one to finish. For small tasks, this is fine. For larger features, it creates a bottleneck. Imagine implementing user profile editing. The work naturally splits into three independent streams: - **Feature code** — the actual implementation - **Tests** — E2E and unit tests verifying the feature works - **Documentation** — API docs and usage guides These streams do not depend on each other in their early stages. A developer writing tests does not need the implementation to be done first — they can write tests against the specification. A technical writer can draft documentation from the design. Multi-agent workflows let three specialized agents work on these streams simultaneously. --- #### Git Worktrees: Isolated Workspaces for Each Agent 💡 **What is a Git worktree?** A Git worktree lets you check out the same repository into multiple directories at once. Each directory is an isolated workspace — changes in one do not affect the others until you explicitly merge them. Think of it like having three separate copies of your project, all connected to the same Git history. Without worktrees, if two agents edited the same files simultaneously, they would overwrite each other's work. Worktrees solve this by giving each agent its own directory. **Creating worktrees:** ```bash # Create a worktree for the feature implementation git worktree add ../project-feature-profile -b feature-profile # Create a worktree for tests git worktree add ../project-test-profile -b test-profile # Create a worktree for documentation git worktree add ../project-docs-profile -b docs-profile ``` Each command creates a new directory and a new Git branch. Agent 1 works in `../project-feature-profile`, Agent 2 in `../project-test-profile`, Agent 3 in `../project-docs-profile`. They cannot conflict. **Listing active worktrees:** ```bash git worktree list ``` Output: ``` /home/user/project abc1234 [main] /home/user/project-feature-profile def5678 [feature-profile] /home/user/project-test-profile ghi9012 [test-profile] /home/user/project-docs-profile jkl3456 [docs-profile] ``` **Removing a worktree when done:** ```bash git worktree remove ../project-feature-profile ``` --- #### The Conceptual Flow Here is how a three-agent workflow for user profile editing looks: ``` User: "Implement user profile editing" Parallel: ├─ Agent 1 (dev) → Feature code [worktree: feature-profile] ├─ Agent 2 (QA) → E2E + unit tests [worktree: test-profile] └─ Agent 3 (docs) → API docs [worktree: docs-profile] Collect results → Review + integrate → Merge to main ``` Each agent: 1. Gets its own worktree (isolated directory + branch) 2. Receives a focused task description 3. Works independently without interfering with the others 4. Produces output that gets reviewed and merged The time saving is significant. Instead of 45 minutes of sequential work (15 min feature + 20 min tests + 10 min docs), you get 20 minutes of parallel work — the duration of the longest task. --- #### The `run_in_background: true` Pattern In Claude Code's agent system, you can launch a subagent and tell it to run in the background while you (or the parent agent) continue other work. This is what enables parallelism. The pattern looks like this in a meta-instruction context: ``` Launch Agent 1 in background: Task: "Implement user profile editing feature" Worktree: ../project-feature-profile run_in_background: true Launch Agent 2 in background: Task: "Write E2E and unit tests for user profile editing" Worktree: ../project-test-profile run_in_background: true Launch Agent 3 in background: Task: "Write API documentation for user profile editing" Worktree: ../project-docs-profile run_in_background: true Wait for all agents to complete. Review outputs. Merge branches to main. ``` When `run_in_background: true` is set, the launching agent does not wait for the task to finish before moving on. All three agents start running simultaneously. --- #### Why Isolation Matters Without isolation, parallel agents create conflicts. Consider two agents both editing `src/components/UserProfile.tsx`: - Agent 1 adds a form field on line 45 - Agent 2 adds validation logic on line 45 - Both changes overwrite each other With worktrees, each agent has its own copy of the file. Their changes live in separate branches. When you merge, Git helps you combine the changes in a controlled way — or flags conflicts for human review. 💡 **The general rule:** Any time multiple agents might touch the same files, use worktrees for isolation. If agents are working on completely different files (e.g., one on the backend, one on unrelated frontend components), worktrees are less critical but still good practice. --- #### When to Use Multi-Agent Workflows **Good candidates for parallelization:** - Large features that have independent implementation streams (code + tests + docs) - Research tasks where multiple topics can be explored simultaneously - Code review + test writing + documentation for a pull request - Multi-environment deployments that need to happen concurrently **Poor candidates for parallelization:** - Tasks where Agent 2 needs Agent 1's output to start (sequential dependency) - Small tasks that take under 5 minutes — the overhead of setting up worktrees is not worth it - Tasks involving shared configuration files that both agents would modify **The rule of thumb:** If you would assign the work to two different people on a team who could work independently, it is a good candidate for parallel agents. --- #### Collecting Results After agents finish, you collect their output and integrate it. The integration step is where human judgment matters most: 1. **Review each branch** — read what each agent produced 2. **Run tests** — make sure the implementation and tests are compatible 3. **Resolve any conflicts** — use `git merge` or `git rebase` to combine branches 4. **Merge to main** — once everything looks good, merge all branches ```bash # Switch to main and merge all three branches git checkout main git merge feature-profile git merge test-profile git merge docs-profile ``` If there are conflicts (two agents touched the same file), Git will flag them for you to resolve manually. --- ### Lesson 10.3: Automation Patterns This lesson covers practical patterns for automating repetitive parts of your development workflow using hooks and agent coordination. The goal is not to automate everything — it is to automate the right things. --- #### Pattern 1: Auto-Commit on File Edit This is the most popular hook pattern. After Claude edits a file, automatically stage and commit the change. **Why it is useful:** When Claude is making many small edits across a session, it is easy to forget to commit. Auto-committing creates a granular history you can review and revert if something goes wrong. **The script (`scripts/auto-commit.sh`):** ```bash #!/bin/bash # Auto-commit any staged or modified files after a Claude edit # Exit if nothing to commit if git diff --quiet && git diff --staged --quiet; then echo "Nothing to commit" exit 0 fi # Stage all changes git add -A # Create a timestamped commit message TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S') git commit -m "auto: claude edit at ${TIMESTAMP}" echo "Auto-committed at ${TIMESTAMP}" ``` Make it executable: ```bash chmod +x scripts/auto-commit.sh ``` **The hook configuration:** ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|MultiEdit|Write", "hooks": [ { "type": "command", "command": "./scripts/auto-commit.sh", "timeout": 15000 } ] } ] } } ``` 💡 **Should I always auto-commit?** It depends on your workflow. Auto-committing is great when you want a detailed history of what Claude changed. It is less ideal if you prefer to review changes and write intentional commit messages yourself. Start with manual commits, and add auto-committing once you trust your workflow. --- #### Pattern 2: Session Startup Checks When you start a session, you often want to verify that your environment is in a known-good state before asking Claude to do anything. Session startup checks automate this. **Common startup checks:** - Is Node.js the right version? - Are dependencies installed? - Is the database connection working? - What is the current sprint or active issue? **A startup check script (`scripts/session-start.sh`):** ```bash #!/bin/bash echo "======================================" echo " Session Start - Environment Check" echo "======================================" # Check Node.js version NODE_VERSION=$(node --version 2>/dev/null) if [ -z "$NODE_VERSION" ]; then echo "❌ Node.js not found" else echo "✓ Node.js: $NODE_VERSION" fi # Check if node_modules exists if [ -d "node_modules" ]; then echo "✓ Dependencies installed" else echo "⚠ node_modules missing - run npm install" fi # Check for .env.local if [ -f ".env.local" ]; then echo "✓ .env.local found" else echo "❌ .env.local missing - check environment setup" fi # Print current git branch BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null) echo "✓ Branch: $BRANCH" # Print last commit LAST_COMMIT=$(git log -1 --oneline 2>/dev/null) echo "✓ Last commit: $LAST_COMMIT" echo "======================================" echo " Ready to work" echo "======================================" ``` **The hook configuration:** ```json { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "./scripts/session-start.sh", "timeout": 15000 } ] } ] } } ``` Now every time you start a Claude Code session, you immediately see the environment status. No more discovering mid-session that dependencies were not installed. --- #### Pattern 3: Connecting Hooks to BMAD Workflows 💡 **What is BMAD?** BMAD (Business, Marketing, Architecture, Development) is a structured methodology for AI-assisted software development. It defines roles, phases, and documents that guide how features are planned, built, and delivered. If your project uses BMAD, hooks can help automate parts of the workflow. **Example: Auto-validate story status on session start.** If your project tracks work using BMAD stories (structured task descriptions), you might want to know which stories are active when you start a session: ```bash #!/bin/bash # scripts/bmad-session-start.sh echo "======================================" echo " BMAD Session Status" echo "======================================" # Check for active stories STORIES_DIR=".bmad/stories" if [ -d "$STORIES_DIR" ]; then ACTIVE=$(ls "$STORIES_DIR"/*.md 2>/dev/null | wc -l) echo "Active stories: $ACTIVE" # Show the titles of active stories for story in "$STORIES_DIR"/*.md; do if [ -f "$story" ]; then TITLE=$(head -1 "$story" | sed 's/^# //') echo " - $TITLE" fi done else echo "No active stories directory found" fi echo "======================================" ``` **Example: Auto-log what Claude changed after each session.** ```bash #!/bin/bash # scripts/session-stop.sh - runs on Stop event LOG_FILE=".bmad/session-log.md" TIMESTAMP=$(date '+%Y-%m-%d %H:%M') CHANGES=$(git diff --stat HEAD~1 2>/dev/null | tail -1) echo "## Session: $TIMESTAMP" >> "$LOG_FILE" echo "Changes: $CHANGES" >> "$LOG_FILE" echo "" >> "$LOG_FILE" echo "Session logged to $LOG_FILE" ``` Combined hook configuration for BMAD projects: ```json { "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "./scripts/bmad-session-start.sh", "timeout": 10000 } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "./scripts/session-stop.sh", "timeout": 10000 } ] } ], "PostToolUse": [ { "matcher": "Edit|MultiEdit|Write", "hooks": [ { "type": "command", "command": "./scripts/auto-commit.sh", "timeout": 15000 } ] } ] } } ``` --- #### The Automation Decision Tree Not everything should be automated. Before adding a hook, run through this decision tree: ``` Should I automate this? │ ├─ Is it repetitive? │ └─ No → Don't automate. One-off tasks don't benefit. │ └─ Yes → Continue... │ ├─ Does it require human judgment? │ └─ Yes → Don't fully automate. │ │ Consider automating with a confirmation prompt, │ │ or automating the information-gathering step only. │ └─ No → Continue... │ ├─ Could it cause damage if it fails silently? │ └─ Yes → Add safeguards (dry-run mode, backups, alerts) │ │ or skip automation until you understand it better. │ └─ No → Continue... │ └─ Automate it. Start simple, observe it working, then expand. ``` **Examples applying the tree:** | Task | Repetitive? | Judgment? | Risky? | Decision | |---|---|---|---|---| | Run linter after edit | Yes | No | No | Automate | | Commit after edit | Yes | No | Low | Automate (with good messages) | | Push to production | Yes | Yes | Yes | Do NOT automate | | Run unit tests | Yes | No | No | Automate | | Deploy to staging | Yes | Partial | Medium | Automate with confirmation | | Delete old files | Sometimes | Yes | Yes | Never automate | --- #### Pattern: Gradual Automation The best approach to automation is gradual. Do not try to automate everything at once. **Phase 1 — Observe (Week 1):** Work normally without hooks. Notice which tasks you do repeatedly, which ones feel tedious, and which ones you sometimes forget. **Phase 2 — Manual scripts (Week 2):** Write scripts for the repetitive tasks, but run them manually. This lets you test them without the risk of them running automatically in the wrong context. ```bash # Run manually to test ./scripts/auto-commit.sh ./scripts/session-start.sh ``` **Phase 3 — Hook integration (Week 3+):** Once you trust the scripts, add them to hooks. Start with `SessionStart` (low-risk — it just shows information) before adding `PostToolUse` hooks (higher-impact — they run after every edit). **Phase 4 — Refinement:** Review what the hooks are doing. Are they adding value? Are they running too often? Are the timeouts appropriate? Adjust based on real usage. 💡 **The guiding principle:** Automate what you trust. Start with automation that shows information (safe) before automation that makes changes (higher stakes). Work up to automation that touches production systems only after you have extensive experience with the simpler patterns. --- #### Combining Hooks and Multi-Agent Workflows The patterns in this module compose well together. Here is an example of a fully automated workflow for a medium-sized feature: 1. **Session starts** → startup hook checks environment and prints active stories 2. **You describe the feature** → Claude plans the implementation 3. **Three agents launch in parallel** via worktrees (dev + QA + docs) 4. **Each agent's edits** trigger PostToolUse hooks that auto-commit in their respective worktrees 5. **Agents finish** → you review and merge the branches 6. **Session ends** → Stop hook logs a summary of what changed Each piece is simple individually. Combined, they create a development workflow that handles the mechanical parts automatically and leaves you free to focus on judgment and direction. --- #### Knowledge Check - Module 10 Before proceeding to the next module, verify you can: ✓ Explain what a hook is and why hooks are useful in an AI-assisted workflow ✓ Name the five hook events (`SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`) and describe when each fires ✓ Read a `.claude/settings.json` hooks configuration and explain what it does ✓ Write a `matcher` pattern that triggers on file edits (`Edit|MultiEdit|Write`) ✓ Create a simple PostToolUse hook that runs a command after file edits ✓ Explain what a Git worktree is and why it is used for multi-agent workflows ✓ Describe the three-agent pattern (dev + QA + docs) and when it is appropriate ✓ Apply the automation decision tree to a candidate task ✓ Explain the gradual automation principle (observe → scripts → hooks → refine) --- #### ✅ Module 10 Success Validation

📋 Knowledge Check: Agent Teams, Hooks and Automation

**Verify your hooks configuration is valid:** ```bash # Check that .claude/settings.json exists and is valid JSON cat .claude/settings.json | python3 -m json.tool ``` Expected output: The JSON content pretty-printed without errors. If you see a `json.decoder.JSONDecodeError`, there is a syntax error in your configuration. **Verify your hook scripts are executable:** ```bash ls -la scripts/*.sh ``` Expected output: Each script should show `-rwxr-xr-x` permissions (the `x` indicates executable). If not, run `chmod +x scripts/*.sh`. **Test the session start hook manually:** ```bash ./scripts/session-start.sh ``` Expected output: A formatted block showing Node.js version, dependency status, env file status, current branch, and last commit — all with ✓ or ❌ indicators. **Test the auto-commit hook manually:** ```bash # Make a small change to any tracked file echo "# test" >> README.md # Run the script ./scripts/auto-commit.sh # Verify the commit was created git log --oneline -3 ``` Expected output: The most recent commit should be an `auto:` commit with a timestamp. **Verify worktree knowledge:** ```bash # Create a test worktree git worktree add ../test-worktree -b test-worktree-branch # Verify it was created git worktree list # Remove it git worktree remove ../test-worktree git branch -d test-worktree-branch ``` Expected output: `git worktree list` should show both your main worktree and the test one. After removal, only the main worktree remains.

🎯 Module 10 Completion Checklist

**Skills Verified:** - [ ] Created `.claude/settings.json` with at least one working hook - [ ] Written and tested a `session-start.sh` script that checks environment health - [ ] Written and tested an `auto-commit.sh` script for PostToolUse automation - [ ] Applied the automation decision tree to at least two candidate tasks in your project - [ ] Created, listed, and removed a Git worktree successfully - [ ] Explained in your own words why worktrees are needed for parallel agents **Recommended Next Steps:** 1. Run with your hooks for one full week before adding more. Observe what works and what is noisy. 2. Review your `session-start.sh` — add one more check that is specific to your project (e.g., a database connection check, a service health endpoint). 3. When you are ready to explore multi-agent workflows, identify the next medium-to-large feature on your roadmap and plan which parts could run in parallel. **Achievement Unlocked: Automated Developer** You have moved beyond using AI as a reactive tool and started building a proactive, automated development environment. Your Claude Code sessions now start with context already loaded, your file edits automatically maintain a clean Git history, and you understand how to scale from solo work to coordinated multi-agent workflows when the need arises. The foundation you have built here — hooks, automation patterns, gradual trust-building — applies far beyond Claude Code. These are the same principles that power mature CI/CD pipelines, developer platform tooling, and large-scale engineering workflows.

--- ## Module 11: MCP Ecosystem and Browser Debugging ### Lesson: Understanding the Model Context Protocol (MCP) #### What Is MCP? The **Model Context Protocol (MCP)** is an open standard that lets AI coding assistants connect to external tools and services using a single, consistent interface. Think of it like **USB for AI tools**: before USB, every device needed its own proprietary port. USB created one universal plug that works with any compatible device. MCP does the same thing for AI assistants — one standard protocol, any compatible tool. **Without MCP**: Every AI assistant had to build custom integrations for every tool (browser control, database access, file systems, test runners). Result: fragmented ecosystems, duplicated effort. **With MCP**: Build one MCP server, connect it to any MCP-compatible AI client. One standard. Any tool. Any assistant. #### How It Works MCP uses a **server/client model**: - **MCP Servers** expose capabilities (tools, resources, prompts) to any client that connects - **MCP Clients** are AI assistants that consume those capabilities — Claude Code, Cursor, Codex CLI, etc. ``` Your AI assistant (client) | | MCP protocol (stdio or HTTP/SSE) | MCP Server | External Tool (Chrome, database, file system, test runner...) ``` When your AI says "take a screenshot" or "run the failing test," it is calling a tool exposed by an MCP server over this protocol. The assistant never needs to know the implementation details — just the tool name and parameters. #### Configuration MCP servers are configured in `.mcp.json` at the project root (or in your assistant's global config). The file tells your AI client which servers to start and how to connect to them. ```json { "mcpServers": { "server-name": { "command": "npx", "args": ["some-mcp-server@latest"] } } } ``` Your AI assistant reads this file on startup and activates all listed servers automatically. #### Brief History MCP was introduced in **late 2024** by Anthropic as an open standard. Adoption was rapid: - **Claude Code** (Anthropic) — native MCP support from launch - **Cursor** — MCP support added in 2024 - **Codex CLI** (OpenAI) — MCP support added 2025 - **VS Code Copilot** — MCP support via extensions Because it is an open standard, any tool can publish an MCP server and immediately work with all supporting clients. The ecosystem of available MCP servers is growing fast. #### Key Takeaway MCP is not a vendor feature. It is a protocol. Any tool that speaks MCP works with any AI assistant that supports it. When you configure an MCP server once, every AI assistant you use gets that capability automatically. --- ### Lesson: Configuring Common MCP Servers #### The `.mcp.json` File Create `.mcp.json` at the root of your project. Your AI assistant will read it and activate the listed servers on startup. Here is a configuration with two of the most useful servers for web development: ```json { "mcpServers": { "playwright-test": { "command": "npx", "args": ["playwright", "run-test-mcp-server"] }, "chrome-devtools": { "type": "stdio", "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest", "--browserUrl=http://127.0.0.1:9222"] } } } ``` What each field means: - `command` — the executable to run (usually `npx` for npm-based servers) - `args` — arguments passed to the command - `type` — transport type (`stdio` for standard input/output, the most common) - `--browserUrl` — tells the Chrome DevTools server where to find a running Chrome instance #### Popular MCP Servers for Web Development | Server | What It Does | |---|---| | **Playwright MCP** | Run, debug, and interact with Playwright tests directly from your AI assistant | | **Chrome DevTools MCP** | Control a running Chrome browser: navigate pages, inspect console/network, take screenshots, run performance traces | | **Filesystem MCP** | Read and write files outside your current project directory | | **Database MCP** | Query databases directly (Postgres, SQLite, etc.) and inspect schemas | #### Adding a Server 1. Find the server's npm package name (usually listed in its README) 2. Add an entry to `.mcp.json` 3. Restart your AI assistant (it re-reads the config on startup) 4. Ask your assistant to list available tools — the new server's tools should appear Example: adding the Filesystem MCP server: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"] } } } ``` #### Verifying a Server Is Active Ask your AI assistant directly: ``` List all MCP tools currently available to you. ``` It will enumerate every tool from every active server. If a server is missing, check that `.mcp.json` is at the project root and that the assistant has been restarted since the file was added. --- ### Lesson: Chrome DevTools MCP Setup and Debugging #### How Chrome DevTools MCP Works Chrome DevTools MCP bridges your AI assistant and a running Chrome browser: 1. Chrome is launched with the `--remote-debugging-port=9222` flag 2. This opens a WebSocket endpoint at `http://127.0.0.1:9222` 3. The MCP server connects to Chrome via that WebSocket 4. Your AI assistant sends commands through the MCP server to Chrome in real time This gives your AI assistant the same capabilities as Chrome DevTools — but scriptable through natural language prompts. #### Launching Chrome for MCP **Recommended: use the project script** (handles cleanup and profile management): ```bash ./.claude/scripts/chrome-devtools-with-cleanup.sh ``` **Manual launch** (if you do not have the script): ```bash google-chrome \ --remote-debugging-port=9222 \ --user-data-dir="$HOME/.chrome-devtools-mcp/profile" \ http://localhost:3000 ``` Notes on the manual launch: - `--user-data-dir` must point to a dedicated profile directory, not your main Chrome profile - Chrome must stay running while you use MCP tools - Only one MCP client can connect to a given Chrome instance at a time #### Verifying the Connection With Chrome running, ask your AI assistant: ``` List the open pages in Chrome via DevTools MCP. ``` You should see at least one page (the tab you opened). If you get an error, Chrome is either not running or not listening on port 9222. #### Debug Prompts You Can Give Your AI Assistant Once Chrome DevTools MCP is active, your assistant can automate real browser tasks. Copy these prompts directly: **Verify a user flow:** ``` Open http://localhost:3000 and verify the login flow end-to-end. Report any console errors you find. ``` **Diagnose network failures:** ``` On http://localhost:3000/dashboard, check the Network panel for failing requests. List each by URL, status code, and error type. Diagnose the likely cause. ``` **Simulate user interaction:** ``` Navigate to /checkout. Fill in the form with test data and click Submit. Capture what happens — any errors, redirects, or network requests — and explain why the submission fails. ``` **Performance audit:** ``` Record a performance trace of http://localhost:3000. Report LCP, CLS, and any main-thread blocking tasks over 50ms. Suggest concrete fixes for the worst offenders. ``` **Layout debugging:** ``` Inspect the DOM and CSS on /landing. Diagnose why the hero section overflows on mobile viewports. Suggest fixes with exact CSS selectors. ``` #### Artifact Checklist After each MCP debug session, keep these artifacts for reference: - Screenshot(s) of the failing state (save to `.artifacts/`) - Console error summary (error text, source file, line number) - Network request details for any failing calls (URL, status, response body) - If performance-related: trace summary with LCP, CLS, and blocking task durations --- ### Lesson: BMAD Repair Loop Using DevTools MCP #### What This Is The BMAD repair loop is a four-step routine you follow with your AI assistant to fix issues systematically. It prevents the common trap of jumping straight to a code change before understanding the actual problem. The loop: 1. **Plan (B — Business)**: Clarify what "fixed" means before touching code 2. **Localize (A — Architecture)**: Find the exact layer and file(s) causing the issue 3. **Change (D — Development)**: Make the smallest fix that satisfies the acceptance criteria 4. **Verify**: Confirm the fix holds across types, lint, tests, build, and real browser state #### Step 1 — Plan: Define Acceptance Criteria Before writing a single line of code, answer these questions: - What user flow is blocked? (e.g., "users cannot complete checkout") - What is the severity? (P0 = site down, P1 = key flow broken, P2 = degraded) - What does "done" look like? Be specific: - Build passes (`npm run build`) - No console errors on the affected route - Specific network request returns 200 - LCP under 2.5s on a mid-tier device Write this down before you ask your assistant to do anything. Vague acceptance criteria lead to vague fixes. #### Step 2 — Localize: Find the Layer Use DevTools MCP to gather evidence before touching code. Prompt to run: ``` You are connected to Chrome DevTools MCP. Visit http://localhost:3000 and: 1) Reproduce the failing flow. 2) Capture all console errors (message, source file, line). 3) List all failing network requests (URL, status, response body). 4) Take a screenshot of the failing state and save to .artifacts/. 5) Report which layer is likely responsible: build | runtime | client | server | network | rendering Stop after one pass and wait for my response. ``` Also run these in your terminal to capture build-time evidence: ```bash mkdir -p .artifacts npm run typecheck > .artifacts/typecheck.log 2>&1 || true npm run build > .artifacts/build.log 2>&1 || true ``` #### Step 3 — Change: Smallest Possible Fix Prompt your assistant with the evidence from Step 2: ``` You are my Fix Runner. I have identified the issue: [paste MCP output and log excerpts here] Acceptance criteria: [paste from Step 1] Propose the smallest code change that satisfies the acceptance criteria. Show exact file paths and diffs. Ask before applying anything. ``` Key discipline: resist scope creep. Fix the one thing that is broken. Larger refactors go in a separate commit. #### Step 4 — Verify After applying the fix, run the full verification sequence: ```bash npm run typecheck && npm run lint && npm run test && npm run build ``` Then use MCP to confirm the browser state: ``` Re-check http://localhost:3000 via DevTools MCP: - Run the previously failing flow - Confirm console is clean - Confirm previously failing network requests now succeed - Take a screenshot of the passing state and save to .artifacts/ Report pass or fail against the acceptance criteria from earlier. ``` #### Document the Fix Save a brief summary in `_bmad-output/` (not `docs/`): ``` _bmad-output/fix-YYYY-MM-DD-[description].md ``` Include: - Root cause (one sentence) - Files changed - Acceptance criteria and whether each was met - Any tests added to prevent regression --- ### Lesson: Ship the Fix with Guardrails A fix is not done when it works locally. It is done when it has passed every gate that protects your production users. #### Pre-Ship Checklist Run through this checklist before every commit: **Build gates:** - [ ] `npm run typecheck` — zero TypeScript errors - [ ] `npm run lint` — zero lint errors or warnings - [ ] `npm run test` — all unit and integration tests pass - [ ] `npm run build` — production build succeeds without warnings **MCP browser verification:** - [ ] No console errors on the routes affected by the fix - [ ] All previously failing network requests now succeed (or fail intentionally with proper error handling) - [ ] Performance trace acceptable: LCP under 2.5s, CLS under 0.1 **Documentation:** - [ ] Brief postmortem saved to `_bmad-output/` - [ ] Root cause, fix summary, and tests added all recorded #### Optional: Add a Playwright Smoke Test If the fix covers a user flow that could regress silently, add a Playwright smoke test: ``` Write a Playwright test that: 1) Navigates to /[affected-route] 2) Completes the flow that was broken 3) Asserts no console errors and that the success state is visible Save it to __tests__/e2e/[feature]-smoke.spec.ts ``` Run the new test: ```bash npm run test:e2e npm run playwright:cleanup # Always run after Playwright tests ``` #### One-Prompt Orchestrator For a fully automated repair session, use this prompt with your AI assistant: ``` You are my Debug Orchestrator. Follow this exact protocol: 1) TRIAGE: - Run: npm run typecheck; npm run lint; npm run build - Save output to .artifacts/typecheck.log and .artifacts/build.log 2) BROWSER: - Connect via Chrome DevTools MCP - Reproduce the failing flow on [URL] - Capture console errors, failing network requests, and a screenshot - Save screenshot to .artifacts/ 3) ANALYZE: - Name the suspected layer: build | runtime | client | server | network | rendering - Propose the smallest fix with exact file diffs - Define acceptance: build passes; console clean; network healthy - Ask before applying any changes 4) APPLY + VERIFY: - On my approval, apply diffs - Re-run: npm run typecheck && npm run lint && npm run test && npm run build - Re-check in browser via MCP; attach new screenshot if improved Stop with: summary, acceptance status (pass/fail), and next step. ``` #### Common Next.js / TypeScript Build Errors Quick reference for the errors you are most likely to hit: | Error | Cause | Fix | |---|---|---| | `NEXT_PUBLIC_*` var undefined on client | Missing prefix or not set in `.env.local` | Add `NEXT_PUBLIC_` prefix; restart dev server | | `import` of server-only module on client | Server code imported in a Client Component | Move to Server Component or API route | | Type-only runtime import | `import { X }` used where `import type { X }` is needed | Switch to `import type` | | `remotePatterns` error for external images | Domain not whitelisted in `next.config.js` | Add entry under `images.remotePatterns` | | `Cannot find module` after adding MCP server | Package not installed globally | Use `npx -y package@latest` in server config | --- #### Knowledge Check — Module 11 Before moving on, verify you can: - Explain the MCP server/client model and why a standard protocol matters - Add a new MCP server to `.mcp.json` and confirm it is active - Launch Chrome with remote debugging and connect Chrome DevTools MCP - Give your AI assistant a debug prompt and interpret the output - Run the four-step BMAD repair loop on a real issue - Pass all pre-ship checklist gates before committing a fix If any of these feel unclear, re-read the relevant lesson above before proceeding. #### Module 11 Success Validation

Knowledge Check: MCP Ecosystem and Browser Debugging

**Quick verification commands (run in your terminal):** ```bash echo "=== Module 11 MCP Ecosystem Verification ===" echo "Checking for .mcp.json configuration..." ls -la .mcp.json 2>/dev/null \ && echo "✅ .mcp.json found" \ || echo "❌ .mcp.json not found — create it at project root" echo "Checking Chrome remote debugging availability..." curl -s http://127.0.0.1:9222/json/version 2>/dev/null | head -1 \ && echo "✅ Chrome DevTools MCP port is open" \ || echo "⚠️ Chrome not running with remote debugging (launch it to use MCP)" echo "Checking BMAD output directory..." ls -la _bmad-output/ 2>/dev/null \ && echo "✅ _bmad-output/ directory exists" \ || echo "ℹ️ _bmad-output/ not yet created (created when you document your first fix)" echo "Checking build integrity..." npm run typecheck 2>&1 | tail -3 ``` **Expected output:** ``` === Module 11 MCP Ecosystem Verification === Checking for .mcp.json configuration... ✅ .mcp.json found Checking Chrome remote debugging availability... ✅ Chrome DevTools MCP port is open Checking BMAD output directory... ✅ _bmad-output/ directory exists Checking build integrity... [TypeScript output showing no errors] ``` **Success indicators:** - `.mcp.json` is present and lists at least one server - Chrome is reachable on port 9222 (when debugging is needed) - TypeScript compiles without errors - You can list MCP tools from your AI assistant **If you see errors:** - Missing `.mcp.json`: create the file at project root with at least the `chrome-devtools` entry from Lesson 2 - Chrome not reachable: run `./.claude/scripts/chrome-devtools-with-cleanup.sh` or the manual launch command from Lesson 3 - TypeScript errors: run `npm run typecheck` and address each error before shipping

Module 11 Completion Checklist

**Skills verified:** - [ ] MCP protocol understood: server/client model, `.mcp.json` configuration - [ ] Chrome DevTools MCP configured and verified working - [ ] At least one MCP debug prompt successfully run against a local app - [ ] BMAD repair loop completed at least once end-to-end - [ ] Pre-ship checklist gates all passing before a commit **Ready for:** - [ ] Applying the MCP ecosystem to any future debugging session - [ ] Adding new MCP servers as your toolchain grows - [ ] Running the BMAD repair loop independently without prompting **Achievement Unlocked: MCP Ecosystem and Browser Debugging**

--- ## Module 12: From Idea to Monetized Product ### Lesson: Master BMAD Orchestrator (Single Prompt) What this prompt will do: - Interview you, build a BMAD plan, and guide all phases including monetization and launch - Run iterative build-run-verify loops with explicit files, commands, and checks - Optionally run audience research and pricing experiments as built-in sub-phases ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). You are the BMAD Orchestrator for my repository. Take my idea to a monetized, production-ready site here. Mode: - Full Journey (default): Interview → Plan → First Slice → Iterate → Monetize → Launch → Growth - Phase: audience-research | pricing-experiment | implement-slice | launch Protocol: - Ask one section at a time; summarize and confirm before continuing. - Produce artifacts in _bmad-output/ and .artifacts/ and steps with exact paths and npm commands. - Respect guardrails: local changes only; no remote pushes; ask before installs. - If using Claude Code, invoke BMAD agents via skills: /bmad-master, /bmad-analyst, /bmad-architect, etc. Context: - Stack: Next.js + TypeScript; Playwright; GitHub Actions; _bmad-output/ templates - Repo: current workspace; follow existing conventions and scripts - BMAD v6: agents in _bmad/core/agents/, config in _bmad/core/config.yaml Interview (ask now, one by one): 1) Idea in 2-3 sentences 2) Target audience and core problem 3) Success criteria (measurable) 4) Constraints (time/budget/data) 5) Monetization preference (Stripe checkout, subscription, gated content, email→sales) 6) Compliance (privacy/ToS placeholders OK?) 7) Today's goal / deadline Plan (output and save _bmad-output/bmad-plan.md): - BRIEF: problem, audience, value prop, success metrics - MILESTONES: 2-4 phases with outcomes and risks - ACTIONS: concrete steps with file paths and npm scripts - DELIVERABLES: URLs, screenshots (.artifacts/), passing tests - MONETIZATION PLAN: offer, price, checkout/gating path First Slice (propose and ask me to confirm): - Minimal files and diffs; demo route (e.g., /demos/) - Playwright smoke; commands to run; verification checklist Iterate (repeat until ready): - Provide exact steps; request results/screenshots; update _bmad-output/bmad-plan.md - Troubleshoot branches when needed; propose next slice Monetize & Launch: - If I confirm, scaffold minimal checkout or gating; add tests and docs - Prepare PR body, release notes, rollout checklist; final health/test verification Growth Loop (post-launch): - Propose 3 quick experiments (content, conversion, performance) with success metrics Start now: Ask the first interview question. ``` 💡 **What is a BMAD Orchestrator?** The BMAD Orchestrator is a single comprehensive prompt that guides an AI assistant through the entire product development lifecycle — from interviewing you about your idea to launching a monetized product. It coordinates all BMAD agent roles (analyst, architect, developer, etc.) in one conversation. 💡 **What is a "Slice"?** A slice is the smallest possible piece of working functionality. Instead of building everything at once, you build one thin vertical slice (e.g., a single page with one feature), verify it works, then add the next slice. This reduces risk and keeps progress visible. **Multi-Agent Pattern**: If you completed Module 10, you can use the multi-agent pattern here. Launch the BMAD Orchestrator in the main session while running parallel agents for implementation, testing, and documentation. See Module 10 for details on worktrees and background agents. #### Lesson (Optional): Audience Research & Positioning Deep Dive What this prompt will do: - Interview for audience segments, pains, and alternatives - Produce positioning, value props, and a messaging brief - Suggest validation experiments and integrate outcomes into the BMAD plan ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). You are the Audience Research Strategist for my repository. Interview me and produce: 1) Segments & jobs-to-be-done (top 2-3) 2) Pains & alternatives (table) 3) Positioning and 3 value propositions 4) Messaging brief (headline, subhead, CTA) 5) Validation experiments (3 quick tests with success criteria) Save to _bmad-output/audience-brief.md and update _bmad-output/bmad-plan.md → BRIEF and MILESTONES. Then propose one experiment I can run today with exact steps and verification. ``` #### Lesson (Optional): Pricing Experiment Runner What this prompt will do: - Select a simple pricing hypothesis and experiment design - Propose minimal implementation (Stripe or gated content) with tests - Define success metrics, log collection, and next steps ```text Paste into your AI coding assistant (Claude Code, Cursor, or similar). You are the Pricing Experiment Runner for my repository. Interview me briefly on offer and constraints, then output: - Pricing hypothesis and target metric (e.g., CTR, checkout start) - Minimal implementation steps with file paths and flags/env - Playwright smoke for the happy path and how to run + cleanup - Measurement plan (logs or counters) and a decision rule Save to _bmad-output/pricing-experiment.md and add steps to _bmad-output/bmad-plan.md. Wait for my confirmation before generating file changes. ``` #### Knowledge Check - Module 12 Before completing this course, verify you can: ✓ Use BMAD Orchestrator to transform ideas into scoped, actionable development plans ✓ Execute iterative build-run-verify loops with explicit files, commands, and testing ✓ Conduct audience research and positioning to validate product-market fit ✓ Implement pricing experiments and monetization strategies for production-ready applications ✓ Leverage multi-agent workflows (Module 10) to accelerate the build-test-document cycle If you cannot complete all checkpoints, review the relevant lessons in this module. #### ✅ Module 12 Success Validation **🎯 Complete these verification steps to confirm mastery:**

📋 Knowledge Check: From Idea to Monetized Product

**Quick Test Commands (Run in Terminal):** **Note:** These are terminal commands - run them directly in your shell, not in an AI agent. ```bash # Verify BMAD Orchestrator and product development setup echo "=== Module 12 Product Development Verification ===" echo "Checking BMAD v6 setup..." ls -la _bmad/core/ 2>/dev/null && echo "✅ BMAD v6 core available" || echo "❌ BMAD not found" echo "Checking BMAD skills..." ls .claude/skills/ 2>/dev/null | grep bmad && echo "✅ BMAD skills installed" || echo "❌ BMAD skills not found" echo "Verifying build-run-verify capabilities..." npm run build 2>/dev/null && echo "✅ Build successful" || echo "❌ Build failed" echo "Checking artifact output directory..." ls -la _bmad-output/ 2>/dev/null && echo "✅ Output directory exists" || echo "Create with: mkdir -p _bmad-output" ``` **✅ Expected Output:** ``` === Module 12 Product Development Verification === Checking BMAD v6 setup... ✅ BMAD v6 core available Checking BMAD skills... ✅ BMAD skills installed Verifying build-run-verify capabilities... ✅ Build successful Checking artifact output directory... ✅ Output directory exists ``` **🎉 Success Indicators:** - ✅ BMAD v6 Orchestrator is operational with skills-based invocation - ✅ Build-run-verify loops execute successfully - ✅ Product development methodology is understood - ✅ Monetization strategies are implementable **⚠️ If you see errors:** - Review the BMAD v6 installation in Module 3 - Check skills are installed: `ls .claude/skills/bmad-*` - Reference the iterative development workflow

🎯 Module 12 Completion Checklist

**Congratulations! You've mastered Module 12!** **Skills Verified:** - ✅ BMAD Orchestrator with v6 skills-based invocation - ✅ Iterative build-run-verify loop execution - ✅ Product-market fit validation and monetization **Achievement Unlocked: Product Development Master** 🏅

--- # 🎓 Course Completion: AI Platform Expert Achievement #### 🏆 Congratulations! You've Achieved Mastery! You have completed the same workflow used to build vybecoding.ai and achieved **AI Platform Expert** status. **🎯 Skills Mastered:** - ✅ Context-first AI development workflow mastery - ✅ The AI development spectrum from vibe coding to SDD - ✅ BMAD METHOD v6 with skills-based agent invocation - ✅ Next.js application architecture and deployment - ✅ Comprehensive testing with Playwright and MCP integration - ✅ Professional CI/CD pipeline implementation - ✅ AI-specific security awareness and mitigations - ✅ Agent teams, hooks, and automation patterns - ✅ MCP ecosystem for browser debugging and beyond - ✅ Advanced debugging and troubleshooting - ✅ Production-ready monetization workflows **📊 Your Achievement Metrics:** - ⏱️ **Learning Time**: 8-12 hours invested - 🎯 **Completion Rate**: 100% (All 12 modules mastered) - 🏅 **Skill Level**: Expert (Advanced proficiency achieved) - 🚀 **Project Readiness**: Production deployment capable **🌟 What You Can Build Now:** - Modern web applications with context-first AI assistance - Scalable platforms with TypeScript and Next.js - Comprehensive test suites with automated E2E coverage - Professional deployment pipelines with monitoring - Multi-agent workflows with hooks and automation - Monetized products using the BMAD methodology **🎊 Share Your Success:** "🎉 Just completed the AI-Generated Platform Guide! I'm now an AI Platform Expert capable of building modern web applications with context-first AI development. #AIExpert #NextJS #TypeScript #BMAD #ContextEngineering" **🚀 Next Steps:** - Apply these skills to your own projects - Join the vybecoding.ai community - Mentor other developers in AI-powered development - Explore advanced AI development techniques - Contribute back: share your CLAUDE.md patterns, custom skills, and hooks