Add repository-level custom AI instruction files (Copilot, Agents, Claude)

[Copilot]

Description

Adds three AI instruction files to standardize AI-assisted development across tools. AGENTS.md is the single canonical source of truth; tool-specific files are thin adapters that defer to AGENTS.md and contain only tool-specific workflow behavior.

All files are policy-focused and reference authoritative source files (pyproject.toml, .pre-commit-config.yaml) instead of embedding volatile information such as version numbers, dependency constraints, or tool configuration values. This ensures the files remain correct when versions, dependencies, or configurations change.

• AGENTS.md (root, 114 lines) — Comprehensive, tool-agnostic canonical reference: coding standards (Ruff, MyPy, NumPy docstrings), architecture (xarray accessors, CF conventions), testing (pytest, xarray.testing assertions), dependency policy, build commands, workflow rules. References pyproject.toml and .pre-commit-config.yaml for all configuration details.
• .github/copilot-instructions.md (19 lines, ~17% of AGENTS.md) — Thin adapter. Points to AGENTS.md as canonical. Contains only Copilot-specific behavioral constraints: grounding in repo context, no hallucination of files/modules, preferring established patterns.
• .claude/CLAUDE.md (26 lines, ~23% of AGENTS.md) — Thin adapter. Points to AGENTS.md as canonical. Contains only Claude-specific behavioral constraints plus a build command quick-reference.

No architectural, testing, dependency, or coding standard content is duplicated across tool-specific files — all such rules live exclusively in AGENTS.md.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My changes generate no new warnings
• Any dependent changes have been merged and published in downstream modules

If applicable:

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass with my changes (locally and CI/CD build)
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• I have noted that this is a breaking change for a major release (fix or feature that would cause existing functionality to not work as expected)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Doc]: Add repository-Level custom AI instruction files (Copilot, Agents, Claude)</issue_title>
<issue_description>## Summary

Introduce repository-level custom AI instruction files to standardize AI-assisted development across tools. These files define shared coding guidelines, architectural constraints, and project conventions so that AI agents generate consistent, context-aware responses without requiring repeated prompt context.

Reference:
https://code.visualstudio.com/docs/copilot/customization/custom-instructions

Objective

Ensure consistent AI behavior across:

• GitHub Copilot (VS Code Chat)
• Multi-agent workflows
• Claude-based tools

These instruction files should reflect:

• Coding standards
• Architectural patterns
• Testing conventions
• Dependency rules
• Project-specific constraints

Requirements

• .github/copilot-instructions.md

  • Automatically applies to all Copilot Chat requests within the workspace
  • Stored in the repository under .github/
  • Defines project-wide AI behavior for GitHub Copilot

• AGENTS.md

  • Supports multi-agent workflows
  • Applies to all chat requests in the workspace or scoped subfolders
  • Stored at the repository root
  • Documents agent responsibilities, constraints, and coordination rules

• .claude/CLAUDE.md

  • Enables compatibility with Claude Code and Claude-based tools
  • Stored in the .claude/ directory
  • Mirrors or adapts relevant guidance for Claude-specific usage

Acceptance Criteria

• All three instruction files exist in the correct locations.
• Instructions are aligned across tools where appropriate.
• AI-generated code reflects documented standards without repeated prompting.
• Documentation explains the purpose and scope of each file.

Design Clarification

• AGENTS.md is the canonical, tool-agnostic source of AI development rules.
• Tool-specific files (.github/copilot-instructions.md, .claude/CLAUDE.md) should contain concise, enforceable extracts aligned with AGENTS.md.
• Tool-specific files may reference AGENTS.md, but must not rely solely on cross-references.
• Avoid unnecessary duplication while ensuring each tool file remains independently effective.

Notes

Keep instructions concise, enforceable, and tool-agnostic where possible. Avoid duplication unless required for tool compatibility.
</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Doc]: Add repository-Level custom AI instruction files (Copilot, Agents, Claude) #834

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (8238fab) to head (da3669f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #835   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           18        18           
  Lines         1989      1989           
=========================================
  Hits          1989      1989           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[tomvothecoder]

@copilot Refactor the repository-level AI instruction system to eliminate unnecessary duplication across tool-specific files.

Objective

• AGENTS.md must remain the single canonical source of truth.
• .github/copilot-instructions.md and .claude/CLAUDE.md must become thin adapters.
• Remove duplicated architectural, testing, and dependency rules from tool-specific files.
• Tool-specific files must contain only workflow-specific guidance required by that tool.

---

Required Changes

1. AGENTS.md (Canonical)

• Ensure it fully defines:

  • Architecture constraints
  • Coding standards
  • Logging rules
  • Testing philosophy
  • Concurrency model constraints
  • Dependency policy (policy-level only)

• Remove any wording that is tool-specific (Copilot or Claude).

• Keep it tool-agnostic and authoritative.

---

2. .github/copilot-instructions.md (Adapter Only)

Reduce this file to:

• A short statement that AGENTS.md is canonical.

• Copilot-specific behavior constraints only, such as:

  • Apply AGENTS.md automatically to all workspace chat responses.
  • Prefer repository context over speculative patterns.
  • Avoid generating code that violates canonical rules.
  • Avoid hallucinating files, modules, or configuration not present in the repo.

• No architectural restatement.

• No testing philosophy restatement.

• No dependency policy duplication.

• No configuration values.

• No numeric or version-specific content.

This file should be minimal and enforce Copilot workflow behavior only.

---

3. .claude/CLAUDE.md (Adapter Only)

Reduce this file to:

• A statement that AGENTS.md is canonical.
• Claude-specific workflow guidance only.
• Any Claude Code–specific behavioral constraints required for proper operation.
• No duplicated architectural or policy sections.

---

Anti-Duplication Rule

Tool-specific files must not restate:

• Architecture rules
• Coding standards
• Testing philosophy
• Dependency policies
• Structural constraints

They may reference AGENTS.md but must remain independently actionable.

---

Acceptance Criteria

• AGENTS.md contains all authoritative rules.
• Copilot and Claude files are concise adapters (< ~25–40% of AGENTS.md length).
• No repeated architectural or dependency sections.
• No volatile configuration values.
• Tool adapters remain valid if dependencies or CI change.

---

Refactor the files accordingly and provide a summary of removed duplication and final file responsibilities.

[Copilot]

@copilot Refactor the repository-level AI instruction system to eliminate unnecessary duplication across tool-specific files.

Objective

...

Refactored in da3669f. Summary of changes:

Removed from both adapter files:

• Project description section
• Coding Rules (Ruff, MyPy, docstrings, imports, license)
• Architecture (xarray accessors, cf_xarray, module responsibility, public API)
• Testing (pytest, xarray.testing assertions, fixtures)
• Dependency policy
• Workflow rules

copilot-instructions.md (19 lines, 17% of AGENTS.md):

• Canonical Reference section pointing to AGENTS.md
• Copilot-specific behavioral constraints only (grounding in repo context, no hallucination, prefer established patterns)

CLAUDE.md (26 lines, 23% of AGENTS.md):

• Canonical Reference section pointing to AGENTS.md
• Claude-specific behavioral constraints (read AGENTS.md per session, ground in repo)
• Build command quick-reference retained (useful for Claude Code workflow)

AGENTS.md — unchanged, remains the comprehensive tool-agnostic canonical source (114 lines).