Graham Knapp

What's in my Copilot instructions file, and why?

written by Graham Knapp on 2025-09-22

Following my article on adopting LLMs in a startup, I was asked about the GitHub Copilot instructions file I maintain for one of our core projects. I’d like to explain what’s in that file, why it’s structured the way it is, and how it differs from standard Python/Django agents guideline templates.

My team uses GitHub Copilot in 3 main ways in VSCode and JetBrains PyCharm:

1. Autocomplete on steroids - the classic in-IDE use case.
2. Copilot Chat / Edit - in-IDE discussions or targeted edits on specific files or sections
3. Agentic coding - in a dedicated environment on GitHub or in the IDE

This file is used in Copilot Chat/Edit and in agentic coding sessions — not for raw autocomplete.

What’s in the file

My copilot instructions markdown file is a project overview — a map of the terrain rather than a rulebook. It gives LLMs, but also developers, the essential context to work productively without overloading the context window. It covers:

• Framework and language information: stating clearly that the backend is Django/DRF with PostgreSQL and the frontend is React/Next.js with Tailwind. This prevents confusion when switching between backend and frontend files.
• Key objects and relationships: a description of the main models, their attributes, and how they connect. I don’t list every sub-object, but I do capture the backbone entities that show up across multiple features.
• App namespaces and state containers: the boundaries that structure the system and guide where new functionality belongs.
• Helper functions: brief descriptions of the translation function for localization, the error-handling wrapper, and the logging service, since these are invoked often and underpin consistent behavior.
• Frontend system: design framework, routing, state management libraries, and the main customer/staff pages, each with file paths for the top-level component. LLMs are good at following these links when needed.
• Testing commands: a short note on how to run unit and end-to-end tests. (I’ve found Copilot can sometimes guess these correctly, but not reliably.)

How I got here

The file is mostly my own work, built up over the course of 2025 in about a dozen revisions. I’ve discussed the contents with my team — our full-stack engineer helped refine frontend conventions and our QA/dev-ex specialist contributed to the testing sections. But as the main AI enthusiast and early adopter, I’ve done most of the drafting and revisions myself.

Why I wrote it this way

1. Painfully gained experience - Many of the details here are the result of multiple frustrating coding sessions seeing Copilot (or Claude or Junie or ...) making the same mistakes or giving me results which are OK in isolation but don't follow my project's conventions.
2. Save time when working with LLMs – I can start a session without re-explaining the project’s structure, and the model can follow references to objects, state containers, or pages directly.
3. Support ongoing development – when I’m focused on a feature, I add detail to the objects or modules in play, so that both I and any agent I’m using can work with the right context in hand.

It’s not an exhaustive manual. Instead, it’s a lightweight and evolving scaffold: the things my team and I need most often, written once and reused many times.

How It differs from standard agent templates

Standard agent templates for Python / Django projects usually focus on:

• Coding best practices (PEP 8, ORM usage, query optimization).
• Framework conventions (signals, __str__ methods, template inheritance, URL naming).
• Security and testing standards (CSRF protection, migrations, unit test coverage).

My file is different because it’s:

• Contextual, not prescriptive – it documents what already exists in the project rather than telling you how to code.
• Project-specific – it sets out actual objects, modules, and frontend structure rather than abstract patterns.
• Optimized for agent use – it’s structured so that an LLM can follow references and drill into the right files with minimal prompting.

In short: templates are rulebooks, my file is a map. That said, looking now at the recommendations from GitHub (published in July 2025) I do seem to have reached similar conclusions on what to include and what to omit.

What’s Next ?

Right now, my Copilot instructions file, Claude instructions file, and JetBrains Junie instructions file are all identical. I don’t yet have agent-specific guidance. I look forward to JetBrains adopting the AGENTS.md convention so I can unify around a single source of truth and only add agent-specific sections where needed.

I also want to work on, and then document, some project-specific tools such as an access to feature PRD documents in Notion and a GitHub Workspaces definition file so my Copilot agents can run unit tests and end to end tests in their own environment.

ai django python typescript