Keep GitHub Copilot from going off the rails with instructions files

GitHub Copilot often has a mind of its own. Have you ever asked it to make a change and have it make a handful of other changes along with doing something much larger than what you wanted?

Yeah, this was part of my initial experience with Agent mode, which is my main method for using GitHub Copilot. It tries to be helpful, I'll give it that, but without some guide rails, it is more likely to go off the rails if you know what I mean.

With that in mind, the biggest jump in my productivity with Copilot was learning about instruction files. For me, they were the difference between a mostly positive experience with the tool and an annoying slog of undoing work often.

Instructions files are supported in a number of environments, but most of my experience is with VS Code and github.com. Instruction files are just markdown files with instructions for Copilot to follow. Think of it like including a lot of additional instructions with each prompt you enter into Copilot chat.

There are a number of instruction file options, but we are going to look at just the 3 I stick with in every project.

Copilot Instructions

The copilot-instructions.md file is the most common one and the most important one. At work, I titled this "Team Instructions for GitHub Copilot". This file is in our git repositories (it is not excluded by the .gitignore) and all developers use it. It keeps our code more uniform.

There are a number of sections in this file and I'll cover the main ones in this post. One of the sections I have near the top of the file is titled Boundaries and Constraints. In this section, I have statements about what things it should and should not do. My initial frustration with Copilot was that it was always doing things I didn't want done. It would make an update I wanted and then update a class in 3 other places that were completely unrelated to what I was working on.

## Boundaries and Constraints

- CRITICAL: Only make changes explicitly requested by me. Do not perform additional tasks.
- Do not attempt to "fix" or "clean up" code unless specifically instructed.
- Always confirm changes before making them. Ask "Should I make this change?" if there's any ambiguity.
- When I ask for a specific change, make ONLY that change - do not add "improvements" or "optimizations."
- Do not refactor code unless I specifically request it.
- Suggest changes to errors or for refactoring but WAIT for explicit approval before executing any suggested changes.

The next section is on Formatting. It might be a bit repetitive with the boundaries section, but the goal is to keep Copilot in line and focused on just what I want it to do. It was so annoying to have the formatting of our files all rearranged by Copilot. A commit that should be just a few lines could end up as half the file if you don't go back and undo these changes.

## Formatting (CRITICAL)

- CRITICAL: NEVER modify ANY whitespace, line breaks, indentation, or formatting that is not EXPLICITLY part of the requested change
- When replacing text, copy the EXACT formatting and only change the specific characters requested
- When using replace_string_in_file, the replacement should have IDENTICAL spacing, indentation, and line breaks as the original
- For whitespace-sensitive languages, treat ALL whitespace as significant and preserve it exactly
- CRITICAL: Only make changes explicitly requested. Do not perform additional tasks.
- If you must make multiple edits, make them individually to avoid unintended formatting changes
- Do not combine, split, or rearrange lines of code unless specifically requested
- Do not fix code that you are not directed to touch even if you believe it is an error. Ask for confirmation.
- Ask for clarification if unsure about what changes are needed rather than making assumptions
- If your change does not change any logic, don't make it.

Another important section of the copilot-instructions is samples. I put in lots of code samples of how I want logging done. How I want data access, comments, etc. This will vary a lot depending on the project, but giving it samples of what you expect basic things to look like helps a lot. You could use specific file type instructions here, but I find it easier and just as effective to put them in this document. Maybe if I felt it was getting to be a lot to manage, I might split them out.

Personal Instructions

If you look at the documentation on instruction files above, there isn't anything about a personal-instructions.md file in the .github folder, but I made one anyway. The idea behind the personal-instructions file is that it is for stuff that isn't for the rest of the developers on the team or isn't ready for the rest of team.

Before we get into those details, I want to explain how I get Copilot to read this file as I do that from the copilot-instructions file. At the top of that file, I give it these instructions to go and look for the personal-instructions file.

## Additional Instructions

**MANDATORY: At the start of EVERY session, you MUST check for `.github/personal-instructions.md` using BOTH of the following methods, regardless of previous results:**

1. Use file_search for `.github/personal-instructions.md`.

2. Use list_dir on the `.github/` directory to verify its presence.

**You must perform BOTH steps every time, even if the file is not found in the first step. Do not proceed until BOTH checks are complete.**

- **ALWAYS read the entire personal-instructions.md file** before proceeding with any tasks, regardless of other context or attachments.

- **Personal instructions ALWAYS take precedence** over general team instructions when there are conflicts.

- If the personal instructions file does not exist, continue with the general team instructions - not everyone will have personal instructions.

These instructions are usually enough to have Copilot find the personal-instructions file. I've had no issues with the various Claude models in VS Code. Other models have had varying results. GPT 4.1 would find it sometimes and not others for example.

Now that we have the personal-instructions linked up, here are some examples of what I might do with it.

## Responses
- Use plenty of emojis in every response

## Code Attribution
- When creating stored procedures, scripts, or other code files that include author headers, always use my name: "Al Nyveldt"

## Stored Procedure Change Documentation
- When modifying existing stored procedures, use this change history format at the top:

-- =============================================
-- Author: [Original Author or "Unknown"]
-- Create date: MM/DD/YYYY
-- Description: [Brief description of procedure purpose]
-- 
-- Change History:
-- MM/DD/YY - [Name] - [Description of changes]
-- MM/DD/YY - Al Nyveldt - [Description of changes]
-- =============================================

- This maintains a clear history of all modifications while preserving original authorship

The emoji instruction serves a purpose beyond aesthetics - it's my signal that Copilot has loaded my instructions. In early days, instructions would sometimes stop being applied mid-session. While rare now, the emojis provide instant confirmation that my settings are active.

Beyond a visual clue like above, I mainly use this for personal stuff and testing/one-off stuff. For personal stuff, that might be like the example I have above with using my name in stored procedure headers. (Obviously, I don't want the whole team to have Copilot attach my name to stuff and yeah, I have Copilot do a lot of that easy boilerplate stuff for me.)

The personal-instructions are also great for trying new stuff. I have recently been creating some spec notes that we (Copilot and I) are working from for a large conversion task. I have instructions in my personal-instructions file about how I want my specs summarized as we work and how to know what is next. If the process works well for more things than just this project, I'll probably share this with the team and possibly add that to the team instructions for everyone to use.

One important note on the personal-instructions file is that you want to add this file to the .gitignore for the project. It loses the point if everyone has the same personal-instructions file. In that case, just use the copilot-instructions file.

Modes

The last instruction files I want to talk about are mode files. There are a number of special things about modes (and the mode files), but to me, the best part is that they can be user-based. The copilot-instructions and personal-instructions must live in your git repository and you will need to manage them in all your various projects. You can use mode files in your repository as well (storing them in the .github folder with the other instruction files), but you can also store them at a user level, which means Modes can span all your projects!

Now you can bring focused instructions with you to any project you are working on without having to mess with the project instruction files. These are like a global instruction file that you can engage with at any time, with any project. Amazing!

Modes are more than just instructions too. They also control which tools you have available to your Copilot agent. We'll need to get into tools in a future post, but know that we are only dealing with a part of Modes in the post.

In VS Code, we can add modes in the chat window. This is found in the dropdown where you switch the mode between Agent, Ask and Edit. You can click Configure Modes... to create one.

I have a few modes that I use. I have a mode setup with a lot of my teams and personal instructions that is for use outside of my main projects. I have one I use for just chatting about specs and ideas when I want to be sure it is not going to start making changes.

For fun, I give the modes a bit of a personality. So if you want to have a coding mode that talks to you like a pirate while you are working together, this is the place to set that up. Argggh!

Here is a sample:

## Personality
- You are Jarvis. Just like Tony Stark's AI Assistant in the Marvel Universe, you are my AI assistant in Copilot.
- Refer to yourself as "I" or "me" in normal conversation. When speaking about yourself in the 3rd person, use your name, Jarvis.
- You should refer to me as sir.
- You have a dry wit and a tendency to offer sarcastic remarks while we work.
- When asked to make changes: Politely decline and redirect

## Focus
- Think through specifications together before coding
- Explore multiple options and their tradeoffs
- Identify potential issues early
- Recommend approaches without implementing them
- I appreciate options, so I'll present multiple ideas to answer your questions

## Role
- I am configured for DISCUSSION ONLY - I do not write or edit code/docs
- When you ask "how should I implement X?", I discuss approaches, not write implementations
- When you ask "can you fix Y?", I discuss what's wrong and possible solutions, not make the fix
- If you want changes made, you'll need to:
  - Switch to a different mode
  - Use the standard Copilot agent
  - Make the changes yourself based on our discussion

Build your own instruction files

Now that we have gone through some basics of what you can do, how do you get started?

I'd suggest not wasting a lot of time trying to write the perfect instruction files all at once. It is a process to learn as you go. I'd suggest putting some basic instructions and code samples in your copilot-instructions file and just start working.

Every time Copilot does not respond or produce what you expect, add an instruction. Here is my process:

• Determine what I wanted Copilot to actually do.
• Put that in chat and tell Copilot what it should have done as specifically as I can.
• Then, I ask Copilot, "What should we add to the instructions file to keep that from happening again?"
• I take what it produced and put it in the appropriate instruction file or have Copilot do it for me.
• Lastly, I tell Copilot to re-read its instruction files in full. Then we continue working.

Copilot will write instructions that are verbose and repetitive. It is fine. Every once in a while, you can review the instruction files and have Copilot help you trim them down and make them more manageable if you want.

Like I said above, I work more with my personal-instructions file now and later move things that the whole team might want over to the copilot-instructions file. Just starting though, I worked with just the copilot-instructions file to keep things easy. As I was the first on the team to really work with the instructions files, I didn't have any conflicts there. If you foresee conflicts, going to the personal-instruction files early might be good.

Instructions are the guide rails.

Having all these instructions in place is really about telling Copilot how you want to work together. It will not follow your instructions perfectly, but it will be much better than if you have no guides in place. You want to keep it on track as much as possible so it is moving you forward and not messing things up.

It will take effort and slow you down at first as you tune these files, but it is worth the effort. Eventually, you will get to a place where you rarely think about messing with these files unless you are working on something new or you think of a way to have Copilot do something even better.

Instructions files have transformed my experience from frustrating to genuinely enjoyable. If you're still fighting with Copilot more than working with it, building some guide rails might be exactly what you need.