Skip to content

workshop-guide.md

Latest commit

 

History

History
473 lines (348 loc) · 19.7 KB

workshop-guide.md

File metadata and controls

473 lines (348 loc) · 19.7 KB

🎯 GitHub Copilot: Use Case-Driven Workshop

Format: Onsite, instructor-led, scenario-based learning
Environment: Local VS Code or GitHub Codespaces
Audience: Developers looking to solve real-world problems with GitHub Copilot
Duration: 3.5–4 hours
Core Goal: Learn Copilot capabilities through practical, relatable use cases

🧭 Why This Workshop Is Different

Instead of learning features in isolation, you'll tackle real development scenarios that mirror your daily work. Each use case demonstrates multiple Copilot capabilities working together to solve actual problems.

🎯 What You'll Accomplish

By the end of this workshop, you'll have hands-on experience with:

  1. Feature Development - Build complete features from design to deployment
  2. Code Quality & Testing - Improve test coverage and code maintainability
  3. Security - Identify and fix vulnerabilities automatically
  4. Team Collaboration - Use custom agents and shared contexts

🗺️ Workshop Structure

Use Case Real-World Scenario Time Copilot Features
Setup Environment preparation 10 min Prerequisites
UC1 "Build a shopping cart feature" 30 min Planning Mode, Agent Mode, Vision
UC2 "Improve our test coverage" 20 min Prompt Files, Self-Healing
UC3 "Enforce team standards" 30 min Custom Instructions, Handoffs
UC4 "Understand & refactor old code" 20 min Ask Mode, Inline Chat, Agent Refactoring
Wrap Reflection & next steps 10 min -

🚀 Setup (15 min)

Prerequisites

  • GitHub account with Copilot enabled
  • Option A: Local machine with Node.js 18+, Git, VS Code Insiders (for Planning Mode)
  • Option B: GitHub Codespace (recommended for consistency)

Quick Start

  1. Fork or clone the demo repository

    git clone <repo-url> demo_copilot_agent
cd demo_copilot_agent
make install

  2. Verify the build

    make build

  3. Start the development environment

    make dev

Use Case 1: "I'm asked to add a new feature"

Scenario: Your PM says: "We need a shopping cart. Users should be able to add products, see a count in the nav bar, and view their cart on a dedicated page."

Your Challenge: Build this feature end-to-end, matching a provided design.

Step 1: Understand Requirements with Planning Mode

A new Planning mode was shipped to VS Code Insiders. This helps build a plan and clarify requirements. This will come to Stable in November 2025. Ideally use VS Code Insiders for this use case, but we also have included instructions for a custom agent for Stable users.

  1. Open Copilot Chat, switch to Plan mode
    • If you don't have Planning mode (because you are on Stable or an old insiders version), create a custom agent with these instructions:
      1. Go to the awesome-copilot repo and copy the Plan chat mode.
      2. Save this file as .github/chatmodes/plan.chatmode.md
      3. Go to Copilot Chat, click the mode selector, and you should now have the custom Plan mode available.
      4. Note this experience won't have the full Planning mode capabilities, but it will allow you to create a plan based on the design image.
  2. Drag docs/design/cart.png into chat (feel free to open it to review first)
  3. Set your model to 'Gemini 2.5 Pro'
  4. Prompt: 
    I need to implement a shopping cart feature in this application matching this image including routing, navbar badge with item count, state management, and add/remove interactions.
  5. Copilot will ask clarifying questions like:
    • Should the cart persist across sessions?
    • What data should be stored?
    • Any constraints on UI/UX?
  6. Answer the questions or say "Use standard e-commerce patterns"
  7. Review the generated plan - iterate if needed

Step 2: Implement with Agent Mode

  1. Switch to Agent mode, select Claude Sonnet 4.5 model
  2. Prompt: 
    Implement the plan you just produced.
  3. Agent will:
    • Create Cart component and page
    • Add routing
    • Implement state management (Context/Provider)
    • Add NavBar badge
    • Wire up add/remove functionality

You can follow along as files are created/modified and also in the task list. If it doesn't run the application to verify it, you should ask the agent to 'start the application and verify the cart works as expected'.

Step 3: Test & Iterate

  1. Run the application: 
    npm run dev
  2. Test in browser - Click on 'Ports' tab to open port 5137:
    • Go to the 'Products' page or click 'Explore Products'
    • Increment a quantity of a product and add to cart
    • Verify badge updates (shows a count next to the cart icon)
    • Click the cart icon to view cart page
  3. If issues arise, have Copilot help troubleshoot. Example prompt: 
    The badge doesn't update when I add items. Fix this.
  4. When you are all done, click 'Keep' to save the changes.

What You Learned

✅ Planning Mode or Custom Plan Mode - Clarify ambiguous requirements
✅ Vision - Copilot understands UI designs
✅ Agent Mode - Multi-file implementation with iteration
✅ Self-correction - Agent can fix its own mistakes

Time Investment: 30 minutes
Value: A complete feature that would normally take 2-3 hours

Use Case 2: "We need better test coverage"

Scenario: Your tech lead says: "Our API test coverage is at 45%. We need to get it above 80% before the release."

Your Challenge: Systematically improve test coverage across all API routes.

Step 1: Use a Reusable Prompt File

Manually prompting for test coverage improvements can work. However, it also means that the process may be inconsistent from developers and you never learn from mistakes. Instead, (have Copilot) create a documented prompt file checked into your repository. Utilize this and enhance it over time based on responses where Copilot struggled. Here we have provided a starting point (well, Copilot has)!

  1. If you haven't already, click the + button in the Copilot Chat panel to clear your history. This is a best practice when switching between use cases or activities to avoid sending unrelated context.
  2. Review .github/prompts/demo-unit-test-coverage.prompt.md
  3. Notice it defines:
    • Objective and routes to focus on
    • Testing patterns to follow (examples)
    • Success Criteria
    • Links to relevant documentation
  4. Notice the prompt does not say the percentage desired is greater than 80%. If that was important it could be added here.

Step 2: Execute the Prompt

  1. Switch to Agent mode, select the Claude Sonnet 4 or Claude Sonnet 4.5 models
  2. Run the prompt:
    • Option A: Click the play button when the prompt file is open
    • Option B: Type /demo-unit-test-coverage in chat. The prompt name automatically becomes a slash command.

Step 3: Agent Self-Heals Failures

Agent will:

  • Analyze current coverage
  • Generate new test cases for product and supplier routes
  • Run tests automatically
  • Fix any failures
  • Re-run until tests pass

Important: Press q when coverage report shows to let agent continue. Otherwise it will wait indefinitely.

Step 4: Verify Results Yourself

npm run test:coverage --workspace=api

Review the coverage report - it should be significantly improved.

What You Learned

✅ Prompt Files - Reusable, documented workflows ✅ Iteration - Agent iterates to fix failing tests automatically
✅ CodeQL Integration - Agent runs security scans after changes

Time Investment: 20 minutes
Value: Comprehensive test suite that would take days to write manually

Use Case 3: "We have standards and Copilot needs to understand and follow them"

Scenario: You use an internal observability framework (TAO). New developers keep forgetting to add proper logging/metrics. Beyond that, they continue to miss compliance requirements which delay releases.

Your Challenge: Encode team standards so Copilot enforces them automatically.

One of the most powerful features of Copilot is Custom Instructions. These allow you to define rules that Copilot applies automatically based on file path, type, or other criteria. This allows you to tune Copilot to your specific needs. As an example, it's one thing to be an expert in Java. Another to be an expert in your team's Java standards. Custom instructions bridge that gap.

Step 1: Review Current Standards

  1. Open .github/copilot-instructions.md
  2. See existing standards for the project. Note you can reference other files, links, etc.
    • Formatting is just markdown. Be concise as this takes up context space.
    • You can reference other files or links for more detail.
    • For your projects, the more documentation you have in repo the better, as Copilot can reference it directly.

Important: Don't have a copilot-instructions.md file yet? Click the gear icon at the top of the Copilot Chat panel, then "Generate Chat Instructions" to generate a starter file from your workspace. Alternatively, check out awesome-copilot instructions for inspiration.

Step 2: Add Custom Instructions

Add this section to copilot-instructions.md:

## REST API Guidelines

For all REST API endpoints:

* Use descriptive naming following RESTful conventions
* Add Swagger/OpenAPI documentation
* Implement TAO observability (logging, metrics, tracing)
  - Assume TAO package is already installed
  - Follow patterns in existing routes

TAO is a fictitious observability framework for this workshop. You can read about it in docs/tao.md. It is used to show that you can encode your own internal standards that Copilot can reference.

Step 3: Test the Instructions

  1. Clear chat history, switch to Agent mode. Choose any model (Claude Sonnet 4.5 recommended)

  2. Prompt:

    Add observability to the Supplier route using our internal standards

  3. Notice Copilot:

    • Adds TAO logging
    • Includes metrics
    • Adds tracing
    • Doesn't try to install TAO (respects your instruction)

  4. Click 'Undo' to revert all changes. We don't want to keep these changes as TAO is fictitious and it will break our app!

Step 4: Create a Handoff

Sometimes you need to pass context to a teammate, a new chat session, or an agent. Custom prompts can help with this. Lets create a plan and then use a handoff to generate a summary document.

  1. Clear chat, switch to Plan mode. Again, consider switching to Gemini 2.5 Pro for planning use cases.

  2. Prompt:

    Create a plan for a user profile page with edit capability and picture upload

  3. Run the handoff command:

    /handoff

  4. Review generated handoff.md - contains:

    • Requirements summary
    • Implementation plan
    • Key decisions/assumptions
    • Next steps

The steps are just defined in .github/prompts/handoff.prompt.md. You can of course customize this. For example, you might want it to automatically create a file in your workspace or create a GitHub issue. You could always ask a follow up question to do that too.

Step 5: Add external documentation as context with Copilot Spaces

Copilot instructions is great for driving behavior in your current repo/workspace. But what about shared context across multiple repos? For example, your team may have a shared design system, style guide, or architecture principles. You can use Copilot Spaces to provide this shared context.

Here we will use GitHub's remote Model Context Protocol (MCP) server to retrieve documentation from a shared Copilot Space and use that to check compliance.

  1. Start the GitHub Remote Copilot Space

    • Open the Command Palette (Cmd/Ctrl + Shift + P)
      • Alternatively you can navigate to .vscode/mcp.json and click the start button next to the github-remote server definition.
    • Select "MCP: List Servers"
    • Select the github-remote server
    • Click "Start Server"
    • This will say "The MCP Server Definition 'github-remote' wants to authenticate to GitHub." Click "Allow" to continue
    • You will be redirected to an OAUTH flow. Click 'Continue' on the account you are using.
    • If the organization for your repo requires SSO, you may need to authenticate that as well. If not you can just click 'Continue' again.

  2. Check out the feature-add-tos-download branch. git checkout feature-add-tos-download (you may need to git stash first)

  3. Clear your chat history in Copilot Chat and switch to Agent mode, using the Claude Sonnet 4.5 model.

  4. Click on the 'Tools' icon next to the model selector. You should see github-remote checked at the bottom. You can uncheck things like Azure MCP Server, Bicep, and playwright if they are selected. Click OK to save.

  5. Enter the following prompt:

    Get the contents of the Copilot Space `OD OctoCAT Supply Compliance Docs`. Once you have those, please analyze my current changes in the PR: Did we include all the necessary languages for the Terms of Service download?

  6. Additional prompts at your disposal:

    Check if we have all the necessary legal disclaimers included in our Privacy Policy update.
    We need to implement a Cookie Banner. Implement it according to the compliance requirements we have in our Copilot Space `OD OctoCAT Supply Compliance Docs`.

Spaces provided additional compliance context for Copilot to reference when analyzing your code changes. However, you could also access them directly as a chat bot at https://github.com/copilot/spaces if you just want to ask questions about the content.

What You Learned

✅ Custom Instructions - Team standards encoded once, applied everywhere
✅ Path-Specific Instructions - Different rules for different file types
✅ Handoff Files - Transfer context between sessions or developers ✅ Copilot Spaces - Providing curated, shared context for use with GitHub Copilot

Time Investment: 30 minutes
Value: Consistent code quality, faster onboarding, less review friction

Use Case 4: "I inherited legacy code I don't understand"

Scenario: You've been assigned to maintain a 3-year-old module. The original developer left. The code works but is poorly documented and uses unfamiliar patterns.

Your Challenge: Understand the code, document it, and refactor safely without breaking functionality.

Step 1: Understand with Ask Mode

  1. Open a complex file (e.g., api/src/repositories/suppliersRepo.ts)
  2. Select a confusing function
  3. Use Inline Chat (Cmd/Ctrl + I): 
    Explain what this function does, including edge cases and error handling
  4. Close the inline chat
  5. Move to the chat window, clear your history, and provide broader context in Ask Mode: 
    @workspace Explain the repository pattern used in this codebase. 
How does it handle database connections and error mapping?

Step 2: Add Documentation

  1. Switch to Agent mode
  2. Prompt: 
    Add comprehensive JSDoc comments to all functions in suppliersRepo.ts.
Include parameter descriptions, return types, and example usage.
  3. Agent will add structured documentation. Review changes and keep one by one in the editor or keep all at once in the chat window.

Step 3: Refactor with Test Guardrails

  1. First, ensure tests exist: 
    Review suppliersRepo.test.ts. Are there any missing test cases for edge conditions?
  2. If coverage gaps exist: 
    Add tests for error scenarios: database connection failures, 
invalid IDs, constraint violations.
  3. Now safely refactor: 
    Refactor suppliersRepo.ts for better readability:
- Extract complex conditionals into named functions
- Reduce nested callbacks
- Add type safety where any types are used

Run tests after each change to ensure no breaking changes.

Step 4: Generate Architecture Documentation

  1. Prompt: 
    Create a Mermaid diagram showing the data flow from 
API route → repository → database for the suppliers module.
Save it in docs/architecture-suppliers.md
  2. Open and review the file that was created
  3. Note you can render the markdown and diagram by right-clicking the filename in the top tab and selecting "Open Preview"

Step 5: Document Database Schema

  1. Prompt: 
    Analyze the SQL migrations in api/sql/migrations/ and create 
an ERD (Entity Relationship Diagram) in Mermaid format.
Include all tables, relationships, and cardinality.

Save to docs/database-schema.md

Step 6: Create Developer Onboarding Guide

  1. Prompt: 
    Create docs/ONBOARDING.md with:
- Prerequisites and setup
- Architecture overview
- How to run tests
- How to add a new API endpoint (step-by-step)
- Common troubleshooting issues
- Link to all other documentation

Copilot is great at reviewing code and generating documentation.

What You Learned

✅ Ask Mode - Understand complex code without reading line-by-line
✅ Inline Chat - Quick explanations without leaving your file
✅ Agent Refactoring - Safe improvements with test guardrails
✅ Documentation Generation - Diagrams and docs from code

Time Investment: 20 minutes
Value: Hours of code reading condensed, safer refactoring, permanent documentation

🔄 Wrap Up

Reflection Questions

  1. Which use case felt most valuable to your daily work?
  2. Where could you apply these techniques tomorrow?
  3. What team processes could benefit from custom agents or instructions?

Key Takeaways

Use Case Key Lesson
Feature Development Planning Mode + Agent Mode = fast, high-quality features
Test Coverage Prompt files create reusable, documented workflows
Team Standards Custom instructions enforce consistency automatically
Legacy Code Ask Mode + Agent refactoring makes unknowns manageable

Next Steps

  1. This Week:

    • Add custom instructions for your team's standards
      • Use the 'Generate Chat Instructions' feature at the top of Copilot Chat to get started or consult examples in the awesome-copilot repo
    • Create one reusable prompt file for a common task

  2. This Month:

    • Configure custom agents for specialized domains
    • Enable Code Quality and work through findings

  3. This Quarter:

    • Establish team patterns for agent usage
    • Build a library of prompt files
    • Measure productivity impact
    • Try Spec-Driven Development for a new feature

📚 Resources

You're now equipped to solve real problems with AI. Go build something amazing! 🚀