Add comprehensive copilot-instructions.md for agent onboarding#2048
Add comprehensive copilot-instructions.md for agent onboarding#2048GernotMaier merged 10 commits intomainfrom
Conversation
…cumentation Co-authored-by: GernotMaier <14001688+GernotMaier@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR significantly expands the .github/copilot-instructions.md file from 20 lines to 323 lines, providing comprehensive guidance for AI coding agents working on the simtools project. The document serves as an onboarding resource covering project context, development workflows, coding conventions, testing requirements, and role-specific guidelines for different types of agents (Astrophysics Expert, Developer, Documentation Manager).
Changes:
- Expanded copilot instructions from 20 lines to 323 lines with detailed project context, setup instructions, testing guidelines, coding conventions, and troubleshooting advice
- Added changelog entry for the maintenance update
- Includes project structure overview, dependency information, CI/CD context, and agent-specific role definitions
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
.github/copilot-instructions.md |
Comprehensive expansion of agent instructions covering project overview, setup, testing (mandatory unit tests, fixtures), code standards (pre-commit hooks, linting), coding conventions, development workflow, troubleshooting, documentation, dependencies, and role-specific guidelines for different agent types |
docs/changes/2048.maintenance.md |
Changelog fragment documenting the improvement to copilot instructions |
Critical Issues Found:
- Line 147: Incorrectly states "Do not use type hints on function signatures" when the codebase extensively uses type hints throughout (e.g.,
mirror_number: int,camera_config_file: str | Path,-> dict,-> float) - Line 152: The example function demonstrates type hints, directly contradicting line 147's instruction
- Line 147: Minor formatting issue with double space before "type hints"
- Line 149: Minor grammatical error - "Private function can have" should be "Private functions can have"
The type hints contradiction is a critical issue that could mislead future AI agents to avoid using type hints, which are a well-established convention in this codebase. This needs to be corrected before merging.
.github/copilot-instructions.md
Outdated
| - Use semantic versions without "v" prefix ("1.0.0", not "v1.0.0") | ||
| - Do not use **type hints** on function signatures | ||
|
|
||
| **Docstrings (MANDATORY):** NumPy style with Parameters, Returns, Raises, Examples sections. 70%+ coverage required for all public functions/methods. Private function can have single-line docstring if self-explanatory. |
There was a problem hiding this comment.
Grammatical error: "Private function can have" should be "Private functions can have" (plural).
| **Docstrings (MANDATORY):** NumPy style with Parameters, Returns, Raises, Examples sections. 70%+ coverage required for all public functions/methods. Private function can have single-line docstring if self-explanatory. | |
| **Docstrings (MANDATORY):** NumPy style with Parameters, Returns, Raises, Examples sections. 70%+ coverage required for all public functions/methods. Private functions can have single-line docstrings if self-explanatory. |
.github/copilot-instructions.md
Outdated
| - Use **astropy.units** for physical quantities | ||
| - Validate names with `simtools.utils.names` functions | ||
| - Use semantic versions without "v" prefix ("1.0.0", not "v1.0.0") | ||
| - Do not use **type hints** on function signatures |
There was a problem hiding this comment.
The instruction "Do not use type hints on function signatures" is incorrect. The codebase extensively uses type hints throughout, including in core modules like src/simtools/model/telescope_model.py and src/simtools/model/camera.py. For example, functions use parameter annotations like mirror_number: int, camera_config_file: str | Path, and return type annotations like -> dict, -> float. This instruction should be removed or corrected to reflect the actual codebase convention of using type hints.
| - Do not use **type hints** on function signatures | |
| - Use **type hints** on function signatures, consistent with the existing codebase |
.github/copilot-instructions.md
Outdated
| **Docstrings (MANDATORY):** NumPy style with Parameters, Returns, Raises, Examples sections. 70%+ coverage required for all public functions/methods. Private function can have single-line docstring if self-explanatory. | ||
|
|
||
| ```python | ||
| def example_function(parameter: str, optional_param: int | None = None) -> dict: |
There was a problem hiding this comment.
The example function shows type hints in the signature (parameter: str, optional_param: int | None = None) -> dict), which directly contradicts the instruction on line 147 that states "Do not use type hints on function signatures". Since the codebase does use type hints (as seen in telescope_model.py and camera.py), this example is correct and line 147 should be removed or corrected.
|
Expanded
.github/copilot-instructions.mdfrom 20 lines to 616 lines of actionable guidance for coding agents. This one-time onboarding investment improves agent efficiency and code quality across the repository.Content Added
Project Context
Development Workflow
pip install -e '.[dev,tests]'+pre-commit installtmp_test_directorynottmp_path)Conventions
Site-Class-Typepattern (e.g.,North-LST-1,South-MST-FlashCam-D)simtools.utils.names.validate_array_element_name()Infrastructure
ghcr.io/gammasim/simtools-dev:latestincludes CORSIKA + sim_telarrayQuick Reference & Debugging
Impact
Provides complete context for agents unfamiliar with:
Code review comment about HTTP URL in line 569: matches project's README.md, likely GitLab Pages without HTTPS configured.
Warning
Firewall rules blocked me from connecting to one or more addresses (expand for details)
I tried to connect to the following addresses, but was blocked by firewall rules:
cta-computing.gitlab-pages.cta-observatory.org/usr/bin/curl curl -I -s --max-time 5 REDACTED(dns block)If you need me to access, download, or install something from one of these locations, you can either:
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.