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.

copilot-instructions.md

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 <command A> with <error message A>, <command B> with <error message B>, <command C> with <error message C>, ... <command Z> with <error message Z>, 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

• In your comment replies, avoid using # style info, such as "#1", unless you're specifically referring to an issue or pull request, since this auto-formats as an issue or PR link. Instead, state "No. 1" or "number 1" etc.
• 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

Edison Scientific

If using Edison Scientific, you may need to wait up until 10 minutes to get the response. If you're an agent, sleep for 10 minutes (to avoid consuming requests unecessarily), and then every 5 minutes after that. Start with a 15 minute wait if using high effort literature query type. If you need to upload files, use analysis query type. See the docs: https://edisonscientific.gitbook.io/edison-cookbook/edison-client. Here is the endpoint you should use: https://api.platform.edisonscientific.com. The API key is EDISON_PLATFORM_API_KEY. Don't expose this secret, e.g., by echoing or grepping it. Pass the API key in explicitly:

from edison_client import EdisonClient, JobNames
client = EdisonClient(api_key=EDISON_PLATFORM_API_KEY)

Whenever you retrieve results (either during the current agent session or during the next session), make sure to fetch and commit all artifacts associated with a trajectory.

If using Edison Analysis, refer to https://docs.edisonscientific.com/edison-client/file-management#upload for instructions on how to upload files. If able to use Context7, to better inform use of EdisonClient, see https://context7.com/future-house/edison-client-docs/llms.txt?tokens=10000

LaTeX

Install MiKTeX instead of TeXLive to reduce download size and time. In the first installation of MiKTeX, download known required packages based on the LaTeX file itself, and install anything else ad-hoc as needed.

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

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.

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?

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)

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

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:

• AccelerationConsortium/ac-dev-lab#339
• AccelerationConsortium/ac-dev-lab#297
• AccelerationConsortium/ac-dev-lab#289

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":

• AccelerationConsortium/ac-dev-lab#297 (comment)

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.

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

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.

Came across https://docs.github.com/en/copilot/tutorials/copilot-chat-cookbook

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.

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

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

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)".

Some other things I've been doing recently:

• giving it an Edison Scientific API key and using that as an "adversary" (mock reviews)
• using Copilot's built in "Code Review" occasionally to catch errors (often catches things that the agent session didn't)
• almost always using the latest Claude reasoning model (higher multiplier/"cost", Claude Opus 4.7 is 15x multiplier compared with Sonnet 4.6 at 1x multiplier)
• I've gotten better at structuring and organizing GitHub issues and pull requests, and then I often give it
• I switch back-and-forth between local and cloud as needed. Local when I know I need to be more hands-on and I have more time. Cloud Agent when I have shorter bits of free time and am OK with waiting
• I've started using GitHub Copilot CLI, where I find toggling between their "plan", regular, and "autopilot" modes a lot more natural