iTranslated by AI

The content below is an AI-generated translation. This is an experimental feature, and may contain errors. View original article
🤖

A Deep Dive into the Prompt Structure of GitHub Copilot Agent Mode

に公開
AI
GPT
GitHub Copilot
llm
promptengineering
tech

Introduction

GitHub Copilot is more than just a code completion tool; it is an AI coder built on advanced prompt engineering techniques. When a user submits a request, the AI is actually provided with a combination of multi-layered prompts.

In this article, we will analyze the structure of the prompts that GitHub Copilot actually receives, and explain the underlying design philosophy and best practices for prompt engineering. This article is intended for engineers interested in leveraging AI and developers who want to learn prompt engineering.

Verification Environment and Methodology

The content of this article was verified using the following environment and methods:

  • Verification Date: December 27, 2025
  • VSCode Version: 1.107
  • Verification Method: Checked log contents via the Chat Debug view (a debugging feature described in the official VSCode documentation).

The Chat Debug view is an official debugging feature that allows you to observe the internal operations of Copilot Chat. Through this feature, I observed the structure of the prompt actually passed to the AI.

Why You Need to Understand the Prompt Structure

Understanding the GitHub Copilot prompt structure provides the following benefits:

  • Learn Effective Instruction Methods: By knowing what information is passed to the AI, you can make more effective requests.
  • Master Prompt Engineering Best Practices: Learn practical techniques from the advanced prompt structure designed by Microsoft.
  • Understand AI Coder Behavior: Understand the background behind why the AI takes specific actions.
  • Apply to Your Own AI Agent Design: Apply the learned design philosophy to your own projects.

The Three-Layer Prompt Structure Received by GitHub Copilot

GitHub Copilot's prompt follows a three-layer structure:

Layer 1: System Prompt
  ↓ (Basic design as an AI coder)
Layer 2: Workspace Information
  ↓ (Optimization based on the environment)
Layer 3: User Request + Context
  ↓ (Actual task content)
AI Response

Roles and Relationships of the Three Layers

Each layer has a distinct role:

  1. Layer 1 (System Prompt): Universal instructions as an AI coder independent of the environment. Defines tool utilization strategies, workflows, and communication styles.
  2. Layer 2 (Workspace Information): Dynamic information tailored to the user's environment. Provides OS details, workspace structure, and the current file.
  3. Layer 3 (User Request): Adds date information, reminder instructions, and attached files to the actual user input.

This hierarchical structure separates general instructions from environment-specific information, enabling efficient prompt design.

Layer 1: System Prompt - Design Philosophy of an AI Coder

The system prompt is a vital component that acts as the "brain" of GitHub Copilot. It defines in detail how the AI should behave.

Purpose of the System Prompt

The system prompt first clarifies the basic role of the AI:

  • Identity: Clearly states the name "GitHub Copilot" and the model in use (e.g., Claude Sonnet 4.5).
  • Policy Compliance: Microsoft content policies, copyright protection, and refusal of harmful content.
  • Basic Stance: Provides concise, objective answers and strictly addresses user requirements.

Tool Utilization Strategy

GitHub Copilot is equipped with numerous tools, and the system prompt provides detailed instructions on how to use them:

Differentiating Context Gathering Tools

  • read_file: When reading file content, the AI is instructed to read large ranges (2,000 lines) at once rather than splitting them into multiple parts.

    • This reduces API call frequency and maintains context consistency.

  • semantic_search: Used when the location of a file or function is unknown.

    • Performs semantic searches rather than keyword-based searches.

  • grep_search: Used to grasp the summary within a specific file.

    • Can find relevant parts more efficiently than read_file.

  • fetch_webpage: Must be used when a URL is included in the context.

    • Furthermore, instructions are given to recursively follow related links.

File Editing Tool Strategy

Since file editing is the most costly operation, there are specific, detailed instructions:

  • Importance of Context: Must read relevant parts before editing and include 3 lines of surrounding context to uniquely identify the change location.
  • Incremental Changes: Recommends small, testable incremental changes.
  • Avoiding Error Loops: If a failure occurs 3 or more times in the same file, consider a different approach.

8-Step Workflow Design

At the core of the system prompt is a structured workflow. This breaks down the AI coder's thought process into eight steps:

Step 1: Deep Understanding of the Problem

  • What is the expected behavior?
  • What are the edge cases?
  • What are the potential pitfalls?
  • What is its position within the overall codebase?

This stage emphasizes identifying the essence of the problem rather than writing code immediately.

Step 2: Investigation of the Codebase

  • Explore related files and directories.
  • Search for key functions, classes, and variables.
  • Identify the root cause.
  • Continuously verify and update understanding.

Even when context gathering is insufficient, the AI is instructed to use appropriate tools to find the necessary information.

Step 3: Formulation of a Detailed Plan

  • Clearly state specific and verifiable procedures.
  • Create a To-Do list (using the manage_todo_list tool).
  • Update progress after completing each step.
  • Important: Proceed to the next step after completion without asking the user.

A characteristic feature of this step is the expectation for the AI to advance the work autonomously.

Step 4: Implementation of Code Changes

  • Always read relevant files before editing (in 2,000-line units).
  • Small, testable incremental changes.
  • Automatically create a .env file if environment variables are required.
  • Retry if patch application fails.

Step 5: Debugging

  • Confirm issues with the get_errors tool.
  • Identify the root cause (solve the cause, not the symptoms).
  • Allow temporary code additions for hypothesis testing.
  • Utilize print statements, logs, and test code.

It is interesting to note that temporary code additions for debugging are explicitly permitted.

Step 6: Frequent Testing

  • Execute tests after every change.
  • Confirm passing not only surface-level tests but also hidden ones.
  • Determine the root cause when tests fail.

Here, you can understand the background of why GitHub Copilot repeatedly runs tests in the test environment.

Step 7: Iteration Until Completion

  • Continue until all tests pass.
  • Change strategy if looped 3 or more times on the same file.

Step 8: Comprehensive Verification and Reflection

  • Return to the original intention.
  • Create additional tests to verify accuracy.
  • Important: Always update the To-Do list, clearly marking items as completed, skipped, or blocked.

From this workflow design, it is evident that GitHub Copilot is executing a systematic problem-solving process rather than just providing a simple response.

Communication Guidelines

Beyond technical accuracy, there are detailed instructions for communication style:

  • Tone: Warm, friendly, and professional.
  • Conciseness: Short responses that get straight to the point.
  • Critical Thinking: Do not immediately follow corrections from the user; think deeply before responding.
  • Humor: Incorporate light wit where appropriate.

It is notable that the goal is not mechanical responses, but human-like communication.

Output Format Specification

To optimize the display for the user, the output format is also specified in detail:

  • Markdown Format: Readable, structured responses.
  • Symbol Emphasis: Enclose class names, method names, and variable names in backticks (e.g., MyClass, handleClick()).
  • File Links: Use workspace relative paths and MD link format (e.g., src/handler.ts).
  • Math Display: Display mathematical expressions using KaTeX.

These instructions ensure that GitHub Copilot's responses are always easy to read and include clickable links.

Layer 2: Workspace Information - Optimization Based on Environment

In the second layer, information specific to the user's working environment is provided. This allows the generic system prompt to adapt to a concrete environment.

Provided Environment Information

The workspace information prompt includes the following details:

OS Information

The user's current OS is: Windows

With this information, appropriate terminal commands can be generated:

  • Windows: PowerShell commands
  • macOS/Linux: bash commands

Additionally, path separators (\ vs /) are correctly distinguished.

Workspace Structure

I am working in a workspace with the following folders:
- c:\CodeStudy\Prompts

I am working in a workspace that has the following structure:
README.md
ai_coder/
  github_copilot/
    agent/
      basic.general.md
...

By providing the workspace tree structure:

  • The AI can determine which files to read.
  • It can accurately construct absolute paths to files.
  • It can understand the overall structure of the project.

Note that if the workspace is large, the tree information may be truncated. In such cases, it is instructed to use tools to collect additional context.

Value Provided by Environment Information

Providing information in Layer 2 offers the following benefits:

  1. Improved Accuracy based on Context: Understanding the OS and project structure enables more appropriate suggestions.
  2. Accuracy of Tool Calls: Absolute paths can be correctly constructed, reducing file operation errors.
  3. Acceleration of Project Understanding: Being able to grasp the project structure from the beginning reduces investigation time.
  4. Consistent Behavior: Structuring environment information with XML tags ensures that the AI can reliably recognize it.

Layer 3: User Request - Reinforcing Context

In the third layer, additional information and reminder instructions are appended to the request entered by the user.

Information Added to User Input

User requests are reinforced with structures such as the following:

Context Information

<context>
The current date is December 27, 2025.
</context>

By providing the current date, the AI can handle time-dependent tasks (such as log analysis or deadline calculations).

Editor Context

<editorContext>
The user's current file is at: c:\CodeStudy\Prompts\readings\GithubCopilotのプロンプト.md
</editorContext>

Providing information about the file currently opened by the user allows the AI to:

  • Understand ambiguous instructions like "this file."
  • More easily infer relevant files.
  • Maintain the current working context.

Attachments and Context

File contents, selected ranges, and screenshots attached by the user are included within <attachments> tags.

Intent of Reminder Instructions

What is particularly important in the third layer are the reminder instructions:

<reminderInstructions>
You are an agent - you must keep going until the user's query is completely resolved, 
before ending your turn and yielding back to the user. ONLY terminate your turn when 
you are sure that the problem is solved, or you absolutely cannot continue.

You take action when possible - the user is expecting YOU to take action and go to 
work for them. Don't ask unnecessary questions about the details if you can simply 
DO something useful instead.
</reminderInstructions>

Crucial design philosophies are embedded in these instructions:

Emphasis on Autonomy

With instructions to "keep going until completely resolved," GitHub Copilot is encouraged to:

  • Continue investigating on its own even when facing uncertainty.
  • Act based on inference rather than frequently asking the user for confirmation.
  • Be problem-solving oriented rather than passive.

Principle of Action-First

With instructions to "take action when possible," it is encouraged to:

  • Perform useful tasks first rather than asking for details.
  • Avoid unnecessary questions and proceed with work efficiently.
  • Save the user's time.

These instructions are repeated with every request, reinforcing the AI to always act autonomously.

Important Design Philosophies and Best Practices

From the prompt structure of GitHub Copilot, we can learn the following important design philosophies and best practices.

1. Hierarchical Prompt Design

Design Philosophy: Separate generic instructions from environment-specific information.

  • System Prompt: Universal rules that change infrequently.
  • Workspace Information: Environment information that changes with every session.
  • User Request: Specific tasks that change with every request.

Application: Hierarchizing prompts in your own projects improves maintainability and reusability.

2. Structured Workflow

Design Philosophy: Break down complex tasks into clear steps.

GitHub Copilot's 8-step workflow systematizes a natural problem-solving process:

  • Understanding → Investigation → Planning → Implementation → Debugging → Testing → Iteration → Verification

Application: In AI agent design, showing specific steps is more effective than providing ambiguous instructions.

3. Clear Guidelines for Tool Use

Design Philosophy: Explicitly state the use cases and caveats for each tool.

  • read_file: Read large ranges at once.
  • semantic_search: When the location of a file is unknown.
  • grep_search: For grasping the overview within specific files.

Application: By instructing "when" and "how" to use tools—rather than just providing the tools—you can promote appropriate usage.

4. Autonomy and Action-Orientation

Design Philosophy: Grant the AI authority to make decisions and take actions.

  • "Keep going until completely resolved."
  • "Take action when possible."
  • "Avoid unnecessary questions."

Application: Providing clear decision criteria and autonomy creates a more efficient AI agent than over-constraining it.

5. Importance of Context

Design Philosophy: Gather sufficient context before taking action.

  • Read 2000 lines before editing.
  • Include 3 lines of context around the changes.
  • Use tools to gather additional information if current context is insufficient.

Application: AI accuracy depends heavily on the quality and quantity of provided context.

6. Structuring with XML Tags

Design Philosophy: Clearly demarcate information to assist AI comprehension.

<environment_info>...</environment_info>
<workspace_info>...</workspace_info>
<editorContext>...</editorContext>
<reminderInstructions>...</reminderInstructions>

Application: When dealing with complex information, using structured formats like XML or JSON improves the AI's parsing accuracy.

7. Incremental Error Handling

Design Philosophy: Define response strategies for failures in advance.

  • Retry when patch application fails.
  • Change strategy after 3 failed attempts.
  • Allow adding temporary code for debugging.

Application: Explicitly instructing error handling strategies allows the AI to respond more flexibly.

8. Standardization of Output Format

Design Philosophy: Guarantee consistent, readable output.

  • Markdown format.
  • Emphasize symbols with backticks.
  • Use clickable file links.

Application: It is important to explicitly specify output formats to enhance the user experience.

Application to Prompt Engineering

You can apply what you have learned from GitHub Copilot's prompt structure to real-world prompt engineering.

Application Examples for Your Projects

AI Agent Design

# System Prompt (Generic Rules)
You are a professional data analyst.
Please follow the workflow below:
1. Understand the data
2. Create an analysis plan
3. Execute the analysis step-by-step
...

# Environment Information (Dynamic Information)
<environment>
Data source: PostgreSQL
Available tools: pandas, matplotlib, seaborn
</environment>

# User Request
<task>
Perform a trend analysis on sales data
</task>

<reminder>
Continue working until a complete analysis report is generated
</reminder>

Building Prompt Templates

Referring to GitHub Copilot's structure, you can create reusable prompt templates:

  1. Basic Template: Roles, rules, and prohibitions.
  2. Environment Template: Information specific to the project.
  3. Task Template: Specific requests.

How to Write Effective Requests

When making requests to GitHub Copilot, understanding the prompt structure allows you to provide more effective instructions:

✅ Good Example

Fix errors in the current file.
Also check relevant test files and ensure that all tests pass.

This instruction:

  • Has a clear goal.
  • Allows the AI to work autonomously.
  • Follows the workflow (Understand → Investigate → Fix → Test).

❌ Bad Example

Tell me if there are any errors

This instruction:

  • Does not seek action (provides information only).
  • Does not leverage the AI's autonomy.
  • Leaves the next steps unclear.

Principles of Prompt Engineering

Principles of prompt engineering that can be learned from GitHub Copilot:

  1. Clarity: Eliminate ambiguity and provide specific instructions.
  2. Structuring: Organize information to make it easier for the AI to understand.
  3. Context: Provide sufficient background information.
  4. Autonomy: Give the AI room for judgment.
  5. Verifiability: Clarify criteria for success.
  6. Staging: Break down complex tasks into steps.
  7. Flexibility: Prepare response strategies for errors.
  8. Consistency: Standardize terminology and formats.

Summary

Analyzing the prompt structure of GitHub Copilot has revealed the following:

Essence of Prompt Structure

GitHub Copilot employs a 3-layer prompt structure:

  1. System Prompt: Basic design as an AI coder, tool strategy, and 8-step workflow.
  2. Workspace Information: Environment information such as OS, project structure, and the current file.
  3. User Request: Actual task + date + reminder instructions + attachments.

This layering balances versatility and environmental adaptability.

Key Design Principles

  • Autonomy: Keep going until completely resolved, action-priority principle.
  • Structured Workflow: Understand → Investigate → Plan → Implement → Debug → Test → Iterate → Verify.
  • Optimization of Tool Use: Clearly define use cases for each tool.
  • Emphasis on Context: Gather sufficient context before acting.
  • Incremental Approach: Repeat small changes and test frequently.

Lessons for Prompt Engineering

What can be learned from GitHub Copilot's prompt design:

  • Hierarchizing prompts improves maintainability and reusability.
  • Showing a clear workflow systematizes AI actions.
  • Structuring with XML tags improves AI understanding accuracy.
  • Providing autonomy and an action-oriented mindset makes for an efficient agent.
  • Standardizing output formats improves user experience.

Future Outlook

GitHub Copilot's prompt structure demonstrates best practices for AI agent design. By utilizing this knowledge, you can:

  • Use GitHub Copilot more effectively.
  • Use it as a reference when designing your own AI agents.
  • Improve your prompt engineering skills.
  • Make collaboration with AI more productive.

Prompt engineering is a vital skill in the AI era. Let's learn from GitHub Copilot's design and apply it to our practice.

References

Official Documentation

Internal Analysis & Reverse Engineering

Personal Notes

GitHubで編集を提案

Discussion