AI-Assisted Coding Tutorial Workshop

Clone this repository from https://github.com/getexcited/WorkshopAiAssistedCodingWindsurf

Workshop Overview

Objective: Enable developers to immediately start using Windsurf.ai effectively for AI-assisted development through hands-on practice and proven patterns.

Format: Live coding, follow-along exercises, and mini-challenges

---

Agenda & Curriculum

Module 1: Foundation & Setup (15 minutes)

1.1 Quick Wins Demo (5 min)

• Live Demo: Build a complete browser game in 2 minutes
• Show the power of AI code generation
• Demonstrate the difference between traditional coding and AI-assisted flow

1.2 Essential Setup (10 min)

Hands-on Exercise #1: Configure Your Workspace

Tasks:
1. Create .windsurf/ directory
2. Set up rules.md with 3 essential rules
3. Configure one workspace memory
4. Test with first AI interaction

Key Concepts:

• The Context Trinity: planning.md, tasks.md, rules.md
• Global vs Workspace rules
• Why context engineering > prompt engineering

---

Module 2: The Core Workflow (25 minutes)

2.1 The Windsurf Development Cycle (10 min)

Interactive Demo: Feature Implementation Flow

1. Context establishment with @ references
2. The "Read-Analyze-Implement" pattern
3. Smart context windowing

Hands-on Exercise #2: Your First Feature

Challenge: Create a User Authentication Module
1. Write planning.md section (2 min)
2. Create implementation prompt with context
3. Review and iterate with AI
4. Add error handling

2.2 Conversation Management (7 min)

• The 5-10 prompt rule
• When to start fresh vs continue
• Using pins effectively (max 3-5 files)

2.3 Cascade Mastery (8 min)

Live Coding: Multi-file refactoring

• @ symbol navigation
• Preview for live testing
• Chat vs Edit vs Write modes

Mini-Challenge: Debug and fix a provided bug using proper context referencing

---

Module 3: Context Engineering Patterns (20 minutes)

3.1 Building Your Context System (10 min)

Hands-on Exercise #3: Create Your Context Framework

Template Provided:
├── .windsurf/
│   ├── planning.md    (fill in architecture section)
│   ├── tasks.md       (create 5 granular tasks)
│   └── rules.md       (add project-specific rules)

Key Patterns:

• Hierarchical context loading
• Cross-reference pattern for consistency
• Task breakdown strategies

3.2 Advanced Prompting Techniques (10 min)

Interactive Examples:

Pattern 1: "Read @auth/*, then implement similar for @products/*"
Pattern 2: "Analyze error [paste], fix with our error handling pattern"
Pattern 3: "Following our conventions in rules.md, refactor @legacy/*"

Pair Exercise: Partner up and practice prompt crafting

• One person writes context files
• Other person crafts prompts
• Switch roles

3.3 Bridging Theory and Practice (5 min)

Mini-Exercise: Prepare for Real-World Application

1. Review your context framework from Exercise #3
2. Choose one of the upcoming coding challenges (debugging, refactoring, or feature development)
3. Adapt your context framework to address the specific challenge
4. Create a first prompt that references your context files and the code files

Key Insight: Context engineering is most powerful when tailored to specific coding tasks

---

Module 4: Practical Workflows with Real Code (30 minutes)

4.1 Applying Context Engineering to Real Code (25 min)

Choose Your Adventure (participants apply context engineering to one of these challenges):

Option A: Feature Development Challenge

Scenario: Implement an e-commerce API feature
Materials: @ExerciseRepo/exercise-3-feature-dev/
Process:
1. Create a .windsurf/ directory with planning.md for the e-commerce API
2. Break down implementation into tasks.md
3. Define coding standards in rules.md
4. Use your context system to implement the feature with AI assistance

Option B: Refactoring Legacy Code Challenge

Scenario: Modernize callback-based code to async/await
Materials: @ExerciseRepo/exercise-2-refactoring/
Process:
1. Create a refactoring plan in planning.md
2. Define refactoring patterns in rules.md
3. Break down the refactoring into incremental tasks in tasks.md
4. Use your context system to guide the AI in refactoring

Option C: Debugging Challenge

Scenario: Fix bugs in an Express API
Materials: @ExerciseRepo/exercise-1-debugging/
Process:
1. Document the debugging approach in planning.md
2. Create a systematic bug-fixing checklist in tasks.md
3. Define code quality standards in rules.md
4. Use your context system to help AI identify and fix bugs

4.2 Code Review & Best Practices (5 min)

• Live review of participant solutions
• Common pitfalls and how to avoid them
• The "trust but verify" principle

---

Module 5: Optimization & Next Steps (10 minutes)

5.1 Performance & Cost Optimization (5 min)

Quick Tips:

• Model selection strategy (Gemini for planning, Claude for implementation)
• Token management with .gitignore
• Context window optimization
• The 500-line rule

5.2 Advanced Techniques Preview (3 min)

• Multi-agent orchestration teaser
• MCP server integration
• Automation possibilities

5.3 Your 30-Day Roadmap (2 min)

Week 1: Master basic workflows
Week 2: Build your context system
Week 3: Experiment with advanced patterns
Week 4: Develop custom workflows

---

🎯 One More Thing: Centralized Agents Directory Pattern

The Challenge (2 minutes)

As teams adopt multiple AI tools (Cursor, Windsurf, Claude Code, Devon, etc.), they face:

• Duplicated rules across tool-specific files (cursor.rules, claude.md, .windsurf/rules.md)
• Inconsistent behavior between tools
• Maintenance nightmare when updating rules

The Solution: /agents Directory Pattern (3 minutes)

Live Demo: Create a centralized knowledge base for ALL AI tools

project-root/
├── agents/                    # Central source of truth
│   ├── rules/
│   │   ├── typescript.md     # TypeScript guidelines
│   │   ├── frontend.md       # Frontend patterns
│   │   ├── testing.md        # Testing standards
│   │   └── api.md           # API conventions
│   ├── migrations/           # Tech debt tasks
│   └── README.md            # How to use this directory
├── .cursorrules             # Points to → agents/rules/
├── .windsurf/rules.md       # Points to → agents/rules/
└── claude.md                # Points to → agents/rules/

Implementation Example (5 minutes)

.cursorrules:

# Cursor Rules
For TypeScript guidelines, see: @agents/rules/typescript.md
For Frontend patterns, see: @agents/rules/frontend.md
For Testing standards, see: @agents/rules/testing.md

.windsurf/rules.md:

# Windsurf Rules
Reference the centralized rules in @agents/ directory:
- TypeScript: @agents/rules/typescript.md
- Frontend: @agents/rules/frontend.md
- Testing: @agents/rules/testing.md

Key Benefits

• Single source of truth for all AI tools
• Consistent behavior across different IDEs
• Easier maintenance - update once, applies everywhere
• Human-readable documentation that also serves AI
• Tool-agnostic - works with any AI coding assistant

Quick Exercise

"Create an /agents directory in your project and move one rule from cursor.rules into it. Update cursor.rules to reference the centralized file."

Pro tip: "What's good for humans is good for LLMs" - your centralized docs help both!

---

Workshop Materials

Pre-Workshop Checklist

• Windsurf installed and licensed
• Sample project repository cloned
• Basic familiarity with VS Code

Provided Resources

1. Starter Templates Pack

   • planning.md template (for context engineering exercises)
   • tasks.md template (for breaking down implementation steps)
   • rules.md examples for different project types (for defining coding standards)
   • debug.md troubleshooting template (for systematic debugging)

2. Exercise Repository

   • exercise-1-debugging: Express API with bugs (for Module 4, Option C)
   • exercise-2-refactoring: Legacy callback code (for Module 4, Option B)
   • exercise-3-feature-dev: E-commerce API skeleton (for Module 4, Option A)
   • These code examples are used to apply context engineering techniques learned in Modules 1-3

3. Cheat Sheet (single page)

   • Essential shortcuts
   • Top 10 prompt patterns
   • Context reference syntax
   • Troubleshooting quick fixes

Key Takeaways Card

🎯 Remember These 5 Rules:
1. Context is King - Invest in planning.md
2. Small Chunks - Never exceed 500 lines
3. Fresh Conversations - Reset every 5-10 prompts
4. Test Everything - AI-generated code needs verification
5. Document Decisions - Future you will thank you

---

Instructor Notes

Time Management

• Use timer for each section
• Have pre-recorded backup demos
• Keep Q&A to breaks between modules

Engagement Tactics

• Live polls: "Who's tried AI coding before?"
• Mini competitions: "Fastest to implement feature X"
• Peer reviews during exercises

Integration Notes

• Modules 1-3 build context engineering skills
• Module 3.3 bridges to practical application
• Module 4 applies those skills to real code examples
• Emphasize how context files should guide AI when working with the code examples
• Show examples of referencing both context files and code files in prompts

Common Issues & Solutions

• Slow Windsurf: Check .gitignore, reduce pinned files
• Poor AI responses: Review context quality
• Confusion about modes: Quick visual guide ready

Success Metrics

Participants should leave being able to:

1. Set up a Windsurf project with proper context
2. Execute the basic development cycle
3. Debug issues using AI effectively
4. Apply at least 3 prompt patterns
5. Know where to learn more