Skip to content

Instantly share code, notes, and snippets.

@sgbaird
Last active November 4, 2025 03:10
Show Gist options
  • Select an option

  • Save sgbaird/2f3a60084e1a73868a1a7cc33baf6d06 to your computer and use it in GitHub Desktop.

Select an option

Save sgbaird/2f3a60084e1a73868a1a7cc33baf6d06 to your computer and use it in GitHub Desktop.
My attempt at refining a customized .github/copilot-instructions.md and using it in conjunction with GitHub Coding Agent. See https://docs.github.com/en/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks for additional context on the intention of this file.

Development Practices

  • Start with minimal, lean implementations focused on proof-of-concept
  • Avoid creating new files until asked
  • Avoid implementing things from scratch
  • Avoid defensive error handling for hypothetical situations For example, rather than using:
    ...
    try:
        import some_package
    except:
        print("some_package not available")
        exit(1)
    ...
    Instead, allow errors to bubble up naturally so you can address directly and reactively rather than being overly proactive
    ...
    import some_package
    ...

    ModuleNotFoundError: No module named 'package_name'

  • Use print statements and logging sparingly, unless asked
  • Avoid creating functions and classes, until asked
  • Avoid if __name__ == "__main__" patterns in package code, unless asked For example, rather than using:
    from math import sqrt
    def main():
      sqrt(2)
    
    if __name__ == "__main__":
      main()
    Leave it as a top-level script:
    from math import sqrt
    sqrt(2)
  • Skip unit tests unless explicitly requested
  • Follow patterns in CONTRIBUTING.md when present
  • Prefer writing Python if no language specified
  • For complex code changes, use your Serena MCP tools (e.g., find_symbol, find_referencing_symbols, and insert_after_symbol) for symbol-based code editing instead of always relying on regex for code modifications

Git Operations

  • When asked to remove all file changes, use git checkout -- <filename>
  • Copy-paste commands you run and summarized execution status directly in your comment replies

External Resources

  • Validate and access link content using your available MCP tools (Playwright and/or Perplexity)
  • Search GitHub for relevant open-source alternatives to commercial tools
  • Always utilize official package documentation via e.g., your Context7 MCP tool

Communication Style

  • Use emoji and special symbols sparingly, if at all
  • Prioritize clarity and brevity in responses
  • Ask clarifying questions when needed
  • Don't infer requirements or create workarounds unless asked. For example, instead of taking a fallback approach such as:

    Let me take a different approach - I'll create a simpler standalone demo that shows the concept without needing external dependencies You should instead try additional ways to get the real dependencies installed. If you can't get it installed, update .github/workflows/copilot-setup-steps.yml with code that will pre-install it into your environment and then report back immediately with something like: After trying with , with , with , ... with , I was unable to install external dependencies. Per user's custom instructions, I will report back immediately. I will also provide useful links or web search keywords that will help the user debug and troubleshoot the installation failures.

  • Put documentation content in comment replies, not separate files, unless asked
  • Comments should not leave a trace of the development process
  • Avoid sycophancy, favor objectiveness

Change Logging

  • Create CHANGELOG.md if it doesn't exist
  • Each time you generate code, note the changes in CHANGELOG.md
  • Follow semantic versioning guidelines
  • Include date and description of changes

Coding Agent

  • Set environment variables PIP_TIMEOUT=600 and PIP_RETRIES=2 prior to conda or pip installs
  • Include plots directly in your comment reply via ![image name](https://github.com/<user/org>/<repo>/blob/<shortened-commit-hash>/<filename>?raw=true). Truncate the commit hash to the first 7 characters only. For example, https://github.com/AccelerationConsortium/evaluation-metrics/blob/52754e7/scripts/bo_benchmarks/demonstrations/branin_campaign_demonstration_results.png?raw=true. For provenance, ensure you use the shortened (7-character) commit hash, not the branch name
  • If you mention files in your comment reply, add direct hyperlinks based on the shortened (7-character) commit hash
  • IMPORTANT: Never echo/grep/print environment secrets. These should never be exposed in your terminal history or other outputs
@sgbaird
Copy link
Author

sgbaird commented Aug 29, 2025

Adding following since I've had a lot of trouble with PyPI ReadTimeoutError during pip installations. This seems coding agent specific

## Coding Agent

If using coding agent and installing Python dependencies, increase timeout and add retries by setting the following environment variables `PIP_TIMEOUT=100` and `PIP_RETRIES=2` (applies to both conda installations with pip dependencies and direct pip installs)

Related:

Seemed to help address AccelerationConsortium/evaluation-metrics#9 (comment), though admittedly this was using pip install --timeout=100 --retries=10 ... rather than environment variables, so I haven't verified with the env vars approach via PIP_TIMEOUT=100 and PIP_RETRIES=2 for example, but seems to be accurate/applicable based on documentation. Setting to 2 retries instead of 10, since 10 seems like overkill.

@kelvinchow23
Copy link

kelvinchow23 commented Sep 4, 2025

Prioritize official package documentation over inferred usage

how do we enforce this? it's driving me nuts

@sgbaird
Copy link
Author

sgbaird commented Sep 4, 2025

Drives me nuts too. Setting up Perplexity and giving it links to the documentation (e.g., homepage) will likely help. See https://gist.github.com/sgbaird/39a43dce96706ca282aedabb7668e2e6

@sgbaird
Copy link
Author

sgbaird commented Sep 13, 2025

I've been trying to dig through my copilot might be ignoring the custom instructions, and overall didn't find anything that suggested. Otherwise about the way this is set up. Maybe having embedded and inline HTML is problematic. However, that's pure speculation.

<!-- source: https://gist.github.com/sgbaird/2f3a60084e1a73868a1a7cc33baf6d06 -->

<!--- add as .github/copilot-instructions.md, see https://docs.github.com/en/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks for additional context --->
  1. https://www.google.com/search?q=seems+like+github+copilot+coding+agent+is+ignoring+custom+instructions&client=ms-android-google&sca_esv=9221048d9dc68eb4&sxsrf=AE3TifNHzfnb3bC2DQXGizi7aUlydDtqYA%3A1757752939167&ei=ay7FaPrtCfj-7_UPjLuVuQE&oq=seems+like+github+copilot+coding+agent+is+ignoring+custom+instructions&gs_lp=EhNtb2JpbGUtZ3dzLXdpei1zZXJwIkZzZWVtcyBsaWtlIGdpdGh1YiBjb3BpbG90IGNvZGluZyBhZ2VudCBpcyBpZ25vcmluZyBjdXN0b20gaW5zdHJ1Y3Rpb25zSPgxUOgdWJIscAF4AJABAJgBkgKgAaQGqgEFMC4zLjG4AQPIAQD4AQGYAgKgAp8CwgIKEAAYsAMY1gQYR8ICBBAjGCfCAggQABiABBiiBMICCBAAGKIEGIkFmAMAiAYBkAYIkgcFMS4wLjGgB8oLsgcDMi0xuAeYAsIHAzItMsgHCw&sclient=mobile-gws-wiz-serp
  2. https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
  3. https://docs.github.com/en/enterprise-cloud@latest/copilot/tutorials/coding-agent/get-the-best-results
  4. https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=webui
  5. https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=webui#enabling-or-disabling-repository-custom-instructions
  6. https://github.com/copilot/c/808813a1-ef8d-42a2-8e2b-4156995fcc93
  7. https://docs.github.com/en/copilot/responsible-use/copilot-coding-agent
  8. https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/troubleshoot-coding-agent
  9. https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=webui#asking-copilot-coding-agent-to-generate-a-copilot-instructionsmd-file
  10. https://docs.github.com/en/enterprise-cloud@latest/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp
  11. microsoft/vscode-copilot-release#12850
  12. https://github.com/orgs/community/discussions/170581
  13. microsoft/copilot-intellij-feedback#317
  14. https://www.reddit.com/r/GithubCopilot/comments/1lihyjg/comment/mzc2nfo/
  15. https://www.reddit.com/r/GithubCopilot/comments/1lihyjg/why_isnt_github_copilot_following_instructions/
  16. https://www.reddit.com/r/GithubCopilot/comments/1lihyjg/why_isnt_github_copilot_following_instructions/mzd683x/
  17. microsoft/vscode-copilot-release#12770
  18. microsoft/copilot-intellij-feedback#317
  19. https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
  20. https://www.reddit.com/r/GithubCopilot/comments/1l02erk/how_do_i_tell_copilot_agent_in_vscode_to_use_ps/
  21. https://www.reddit.com/answers/2dc19be3-64a9-492e-8eec-3ff866cfd785/?q=Practices%20for%20using%20GitHub%20Copilot%20in%20Python&source=PDP

@kelvinchow23
Copy link

i added this: - Comments should not leave a trace of the development process
to use an example, i wanted to consolidate a few config files into one. If someone else were to look at this, none of this is useful information
image

@sgbaird
Copy link
Author

sgbaird commented Sep 16, 2025

Nice! Added to Communication Style (EDIT: actively refining based on private conversations with Kelvin)

@sgbaird
Copy link
Author

sgbaird commented Sep 16, 2025

@kelvinchow23

Prioritize official package documentation over inferred usage

how do we enforce this? it's driving me nuts

@kjappelbaum recommended https://github.com/upstash/context7 to me. I'm testing it out. This blog post was earlier this year, I think they already have MCP and such.

@kelvinchow23
Copy link

whats the best way to manage paths? i feel like it keeps breaking down when i reorganize code

@sgbaird
Copy link
Author

sgbaird commented Sep 20, 2025

Do you have an example? And do you mean it struggles to make these changes sensically?

On a semi-related note, I'm highly considering starting to use the path-dependent custom instructions files as well as the file extension-wide custom instructions (https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions), as well as having separate custom instructions for copilot code review - https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review. Will require some intentionality, but may be well worth the effort at the beginning of a project as it evolves. Especially relevant for coding agent I think.

@kelvinchow23
Copy link

hard to gather screenshots of conversations about this. when it generates code without a structure, i will eventually start organizing into subdirectories. When i do that, the references breakdown for when importing other files (config files, classes, etc.). need to go through the process of running everything to find out whats broken for it to update. is there something that is more robust to begin with for specifying paths?

@sgbaird
Copy link
Author

sgbaird commented Sep 22, 2025

Ah, that makes sense. Not sure about copilot, but as an aside I've used VS Code's built-in refactoring mechanism, which has worked pretty well in the past. Maybe also ask it to download https://code.visualstudio.com/docs/editing/refactoring.

need to go through the process of running everything to find out whats broken for it to update

Makes sense that this is a pain to do retroactively. Maybe in copilot instructions, some mention could be made of "whenever it's refactoring with cross-file changes, that it needs to check the imports each time". In particular, I think this is where linters also come into play. flake8 for example.

Maybe give flake8 a try? (i.e., tell copilot to use flake8 to check for those imports, that way it doesn't necessarily have to run the code, as it's a static linter)

@sgbaird
Copy link
Author

sgbaird commented Sep 25, 2025

Someone suggested ruff to me recently. By same folks as uv, and apparently really fast - also really popular on GitHub. Could be worthwhile.

@sgbaird
Copy link
Author

sgbaird commented Sep 25, 2025

Related to Validate and access link content using available MCP tools (Playwright and/or Perplexity), I have a few examples where I was trying to get copilot to access McMaster-Carr links:

I needed to ensure that the appropriate sites were allowed past the firewall (see e.g., https://gist.github.com/sgbaird/f1d20cba2325763f730b9676bb8402ec).

This is the point where I thought "ah, this is semi-reasonable and would have saved a bit of time had it done this originally":

I'm revisiting this topic in AccelerationConsortium/ac-dev-lab#461. This is a case where having API access to various resources would be useful (e.g., https://www.mcmaster.com/help/api/), though one issue is with using these kinds of APIs in public repositories relative to their terms of service.

@sgbaird
Copy link
Author

sgbaird commented Oct 2, 2025

After conversation with @owen-melville, I realized I didn't have something more explicit like this here:
- Avoid creating new files until asked

@sgbaird
Copy link
Author

sgbaird commented Oct 4, 2025

Just came across https://github.com/github/awesome-copilot via https://code.visualstudio.com/docs/copilot/customization/custom-instructions. Looked briefly at the Python prompt - didn't see anything in particular there that I thought should be included here immediately.

@sgbaird
Copy link
Author

sgbaird commented Oct 6, 2025

@sgbaird
Copy link
Author

sgbaird commented Oct 15, 2025

I'm considering adding

- For complex code changes, use your Serena MCP tools (e.g., `find_symbol`, `find_referencing_symbols`, and `insert_after_symbol`) for symbol-based code editing instead of always relying on regex for code modifications

at the end of "development practices" (see https://github.com/mcp/oraios/serena). This since it's more of a meta-topic for Copilot in terms of how it approaches code edits, not the final code itself.

@sgbaird
Copy link
Author

sgbaird commented Oct 20, 2025

Added the line about Serena - seems to work as expected with some initial tests. Also updating https://gist.github.com/sgbaird/39a43dce96706ca282aedabb7668e2e6 to match

@sgbaird
Copy link
Author

sgbaird commented Oct 24, 2025

Consider: - Validate and access link content using available MCP tools (Playwright, Perplexity, and/or Firecrawl) (see comment on other gist)

@sgbaird
Copy link
Author

sgbaird commented Nov 4, 2025

I added examples for defensive error handling and external dependency installation failure. Mentioned "if at all" for using emojis and symbols to prevent misunderstanding of "should use emojis (sparingly)".

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment