Tutorial: Advanced Copilot Chat techniques

Learning objectives

By the end of this tutorial, you will:

• Master model selection strategies for different task types
• Understand when and how to use Agent Mode effectively
• Leverage workspace context and codebase search
• Structure complex prompts for optimal results
• Handle multi-step workflows autonomously
• Debug and troubleshoot Copilot operations

Prerequisites

• VS Code with GitHub Copilot configured (see Setup Tutorial)
• Multi-root workspace with multiple repositories
• Familiarity with basic Copilot Chat usage
• Understanding of Git and GitHub workflows

Part 1: Strategic model selection

Understanding model capabilities

GitHub Copilot Chat surfaces several frontier model families. Specific versions and context windows rotate as GitHub adds and retires models — treat the model picker in the Chat panel as the source of truth, not this tutorial.

The four families that matter for day-to-day infrastructure work:

OpenAI GPT (current generation)

Strengths:

• Fast response time
• Good for single-file completions and quick edits
• Strong on rapid iteration

Limitations:

• Smaller context window (typically ~128k–200k tokens)
• Less effective for sweeping multi-file operations

Best for:

• Single-file edits and quick fixes
• Inline completions
• Simple Q&A

Example prompts:

Fix the syntax error in this function

Add type hints to this Python function

Explain what this code block does

Claude Sonnet (current)

Strengths:

• Strong analytical and code-review capabilities
• Solid multi-file reasoning
• Large context window (~200k tokens, up to 1M in gated preview tiers)

Limitations:

• Slower than the smallest GPT models for trivial edits

Best for:

• Multi-file refactoring
• Code review and analysis
• Documentation generation
• Moderate-complexity changes

Example prompts:

Refactor this module to use dependency injection

Review this code for security vulnerabilities

Generate comprehensive documentation for this API

Claude Opus / Sonnet (large-context tier)

Strengths:

• Largest context window available in Copilot
• Best fit for whole-codebase reasoning
• Strong autonomous operation in Agent Mode

Limitations:

• Slower response time
• Higher token consumption
• May be overkill for simple tasks

Best for:

• Multi-repository operations
• Large-scale refactoring
• Architectural changes
• Cross-cutting analysis across many files

Example prompts:

Update all Terraform workspace configurations across 8 repositories
with the new naming standard

Analyze all API endpoints in this workspace and generate a comprehensive
security audit report

OpenAI reasoning models (o-series)

Strengths:

• Reasoning-tuned, good for logic and algorithmic problems
• Strong on planning and stepwise problem-solving

Limitations:

• Not optimized for raw code generation
• Smaller usable context than Claude large-context tier

Best for:

• Algorithm design
• System architecture planning
• Logic-heavy tasks

Model selection decision tree

graph TD
    A[Task Type] --> B{Scope}
    B -->|Single File| C{Complexity}
    B -->|Multi-File| D{Repository Count}
    B -->|Analysis| E{Depth Required}

    C -->|Simple| F[OpenAI GPT current]
    C -->|Complex| G[Claude Sonnet current]

    D -->|1 Repo| G
    D -->|Multiple Repos| H[Claude Opus/Sonnet large-context]

    E -->|Surface Level| G
    E -->|Deep Analysis| H
    E -->|Reasoning Focus| I[OpenAI o-series]

Part 2: Mastering Agent Mode

When to enable Agent Mode

Agent Mode allows Copilot to execute autonomously without constant user approval.

Enable Agent Mode when:

• ✅ Executing systematic bulk changes
• ✅ Multi-repository operations
• ✅ Creating comprehensive documentation
• ✅ Complex refactoring workflows
• ✅ You trust Copilot to make decisions

Disable Agent Mode when:

• ❌ Making critical production changes
• ❌ You want step-by-step control
• ❌ Testing new approaches
• ❌ Uncertain about desired outcome

Agent Mode workflow patterns

Pattern 1: Discovery → Plan → Execute

Let Copilot discover, plan, then execute:

1. Find all repositories with Terraform workspace configurations
2. Create a detailed execution plan showing what will change
3. After I approve, execute the changes across all repositories

Benefits:

• Review plan before execution
• Validate approach
• Catch issues early

Pattern 2: Phased execution

Break complex operations into phases:

Phase 1: Discover all target files and create GitHub tracking issue
Phase 2: Update repository configurations
Phase 3: Create PRs with standardized format

Benefits:

• Natural checkpoints
• Easier troubleshooting
• Progress visibility

Pattern 3: Conditional logic

Embed business rules in requests:

Update all workspace names, but:
- Skip if already has correct prefix
- Add detailed notes for workspaces with >30 configs
- Create separate PR for repos with existing open PRs

Benefits:

• Handles edge cases
• Reduces manual cleanup
• More intelligent automation

Monitoring Agent Mode execution

Watch for these indicators of progress:

Tool usage (illustrative — actual names depend on the Copilot build):

Using tool: semantic_search
Using tool: read_file
Using tool: replace_string_in_file
Using tool: run_in_terminal
Using tool: gh (GitHub CLI)

Phase transitions:

Discovery phase: Found 8 repositories with 230+ workspaces
Planning phase: Creating tracking issue and labels
Execution phase: Updating repository 1 of 8
PR creation phase: Creating standardized pull requests

Completion signals:

Completed: 8/8 repositories updated
Created: 8 PRs, 1 issue, 15 labels
Metrics: 167 workspaces updated, 0 errors

Part 3: Leveraging workspace context

Using @workspace effectively

The @workspace tag tells Copilot to reference the entire workspace context.

Basic usage:

@workspace show me all files containing "terraform.tfvars"

Advanced usage:

@workspace analyze all Ansible roles and create a dependency graph
showing which roles depend on which other roles

Filtering results:

@workspace find all Python scripts in repositories starting with
"ohemr-ansible" that import the "requests" library

Using #codebase for targeted search

The #codebase tag performs semantic search across all repositories.

Difference from @workspace:

• @workspace: General context, file-based operations
• #codebase: Semantic search, finds concepts not just strings

Usage patterns:

#codebase find all authentication implementations

#codebase show me error handling patterns used in API code

#codebase locate all database connection configurations

Combining context sources

Use multiple context sources for comprehensive analysis:

@workspace #codebase find all files that handle user authentication
and show me the security patterns used across different repositories

Part 4: Advanced prompt engineering

Structuring complex prompts

Template for multi-phase operations:

[Context Setting]
We have a multi-root workspace with 8 OHEMR infrastructure repositories.

[Primary Objective]
Update all Terraform Enterprise workspace names with organizational prefix.

[Specific Requirements]
1. Find all files named terraform.tfvars in tfe-workspace/ directories
2. Add prefix "aide-0085665-" to workspace names
3. Skip workspaces that already have the prefix
4. Create feature branches following naming convention: feat/add-aide-prefix

[Tracking & Documentation]
- Create GitHub issue in ohemr-issue-tracker
- Create comprehensive labels for tracking
- Link all repos as trackable tasks

[Deliverables]
- Updated configurations in all repositories
- PRs with standardized format
- Tracking infrastructure established
- Summary report with metrics

Using conditional logic

Embed business rules directly in prompts:

IF repository has >30 workspaces:
  Add detailed summary to PR description
  Include metrics table

IF workspace name already has prefix:
  Skip modification
  Add to skip report

IF repository has open PRs:
  Add note to tracking issue
  Use different branch name

Requesting specific outputs

Specify exactly what you want Copilot to produce:

Provide results as:
1. Markdown summary table
2. JSON file with all changes
3. Shell script to validate changes
4. List of PR URLs

Include metrics:
- Total files modified
- Workspaces updated
- Repositories affected
- Time elapsed

Part 5: Handling complex workflows

Multi-step operations

Break complex tasks into discrete steps:

Step 1: Discovery
- Search all ohemr-* repositories
- Identify terraform.tfvars files
- Count workspace configurations

Step 2: Validation
- Check for existing prefixes
- Identify edge cases
- Estimate impact

Step 3: Preparation
- Create feature branches
- Set up tracking infrastructure
- Establish labels

Step 4: Execution
- Update configurations
- Commit with conventional format
- Push branches

Step 5: PR Creation
- Generate standardized descriptions
- Link tracking issue
- Request reviews

Error handling

Request explicit error handling:

For each repository:
1. Attempt update
2. If git errors occur, stash changes and retry
3. If file not found, skip and note in report
4. If syntax errors, validate and fix
5. Continue to next repository regardless of errors

Provide error summary at end.

Rollback strategies

Include rollback procedures in complex operations:

Before making changes:
1. Record current state of each repository
2. Document branch names
3. List commits made

If asked to rollback:
1. Delete feature branches (local and remote)
2. Reset to recorded state
3. Provide confirmation of rollback

Part 6: Debugging and troubleshooting

Understanding tool execution

Copilot exposes a set of internal tools to the model. Tool names and the exact set available drift over time as VS Code Copilot evolves. The names below are illustrative, not contractual — check the chat output for the actual tool calls in your session.

File operations (illustrative):

• read_file: Read file contents
• replace_string_in_file: Edit a file
• multi_replace_string_in_file: Batch edits
• create_file: Create a new file

Git/terminal operations (illustrative):

• run_in_terminal: Run shell commands
• get_changed_files: Review the set of changed files

GitHub operations (via gh CLI):

• gh issue create: Create an issue
• gh pr create: Create a pull request
• gh label create: Manage labels

Common issues and solutions

Issue: Copilot stops mid-execution

Symptoms:

• Progress halts during multi-repo operation
• No response for extended period
• "Thinking..." indicator stuck

Solutions:

[In chat]
What's the current status? Which repository are you working on?

[If truly stuck]
Stop and resume from the last completed repository.
Show me what was completed and what remains.

Issue: Incorrect file modifications

Symptoms:

• Wrong files modified
• Incorrect string replacements
• Syntax errors introduced

Solutions:

1. Request validation before committing:

   Before committing, show me a diff of all changes made

2. Use more specific context:

   In the file terraform.tfvars located in the tfe-workspace/ directory,
   update only the workspace name fields that start with "tfews-"

3. Request verification:

   After each file modification, verify syntax is valid

Issue: Git conflicts

Symptoms:

• Unable to push changes
• Merge conflicts reported
• Branch creation fails

Solutions:

For each repository with conflicts:
1. Stash local changes
2. Pull latest from main
3. Create new feature branch
4. Apply stashed changes
5. Resolve any conflicts using theirs strategy
6. Commit and push

Validating results

Always verify Copilot's work:

Validation prompts:

Before creating PRs, provide:
1. Summary table of all changes
2. List of files modified per repository
3. Sample of changes from each repo
4. Count of workspaces updated vs skipped

Then wait for my approval.

Post-execution validation:

Generate validation script that:
1. Checks all branches were created
2. Verifies workspace names have prefix
3. Confirms PR URLs are accessible
4. Validates conventional commit format

Part 7: Real-world examples

Example 1: Multi-repo configuration update

Objective: Update Terraform workspace names across 8 repositories

Prompt:

Model: Claude Sonnet (large-context tier) | Agent Mode: ON

Find every Terraform Enterprise workspace configuration throughout all
ohemr-* repositories in this workspace. For each repository:

1. Pull latest from main
2. Create feature branch: feat/add-aide-prefix-to-workspace-names
3. Update terraform.tfvars in tfe-workspace/ directory
4. Add prefix "aide-0085665-" to all workspace names
5. Skip workspaces that already have this prefix
6. Commit with conventional commit format
7. Push branch
8. Create PR with standardized format

Also:
- Create tracking issue in ohemr-issue-tracker
- Create comprehensive labels (epic, infrastructure, terraform, etc.)
- Link all repositories as tasks in the issue

Provide metrics: repositories updated, workspaces modified, PRs created

Indicative outcome from a real run on this stack:

• Repositories processed: 8
• Workspaces updated: ~170
• End-to-end execution: ~15 minutes
• Human interaction: ~2 minutes of approvals

These numbers are an illustrative data point from an internal run, not a performance guarantee — your mileage will vary with model, network, and repo size.

Example 2: Documentation generation

Objective: Generate comprehensive API documentation across services

Prompt:

Model: Claude Sonnet (current) | Agent Mode: OFF

@workspace analyze all API endpoint definitions in repositories containing
"api" in their name. For each API:

1. Extract endpoint paths and methods
2. Identify authentication requirements
3. Document request/response schemas
4. Note any security considerations
5. Find example usage in code

Generate comprehensive API documentation following our documentation
standards with proper front-matter. Create separate files for each API
in docs/guides/api/ directory.

Show me the structure and one example before generating all files.

Example 3: Security audit

Objective: Identify security issues across infrastructure code

Prompt:

Model: Claude Sonnet (large-context tier) | Agent Mode: ON

#codebase conduct security audit of all Terraform and Ansible code:

Security checks:
- Hardcoded credentials or secrets
- Unencrypted sensitive data
- Overly permissive IAM policies
- Missing HIPAA compliance controls
- Insecure network configurations
- Deprecated or vulnerable dependencies

For each finding:
- Severity: Critical, High, Medium, Low
- Location: file path and line number
- Description: what's wrong
- Recommendation: how to fix
- Related compliance: HIPAA, SOX, etc.

Generate:
1. Executive summary with counts by severity
2. Detailed findings by repository
3. Remediation playbook with prioritization
4. Tracking issue with tasks for each critical/high finding

Next steps

Now that you've mastered advanced Copilot techniques:

1. Apply to real work: Try multi-repo operations on your projects
2. Learn prompt patterns: Study prompt engineering guide
3. Master context: Deep dive into workspace context usage
4. Share knowledge: Teach your team these techniques

Best practices summary

Model selection:

• Simple tasks → OpenAI GPT (current generation)
• Multi-file work → Claude Sonnet (current)
• Multi-repo operations → Claude Opus / Sonnet (large-context tier)
• Complex reasoning → OpenAI o-series

Agent Mode:

• Enable for systematic bulk operations
• Disable for critical changes requiring approval
• Monitor progress through tool usage
• Include validation checkpoints

Prompt engineering:

• Structure complex prompts clearly
• Include conditional logic for edge cases
• Specify exact outputs needed
• Request validation before execution

Workspace context:

• Use @workspace for file-based operations
• Use #codebase for semantic search
• Combine context sources for comprehensive results
• Filter results with specific criteria

Error handling:

• Include rollback strategies
• Request error summaries
• Validate results before committing
• Test in non-production first

Additional resources

• VS Code Copilot Documentation
• GitHub Copilot Best Practices
• Prompt Engineering Guide
• Claude Model Documentation

Related resources

• AI Development hub — Central hub for all AI development tools
• AI-DLC methodology — Structured AI development lifecycle
• AI-DLC workflow patterns — Advanced workflow patterns