[Doc]: Add repository-level custom AI instruction files (Copilot, Agents, Claude)

[tomvothecoder]

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 repeated prompt context.

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

Establish a canonical-source and anti-drift policy to prevent instruction files from becoming stale as dependencies, CI, or configuration evolve.

---

Objective

Ensure consistent AI behavior across:

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

Instruction files must:

• Reflect project coding standards
• Capture architectural patterns and constraints
• Define testing philosophy and enforcement expectations
• Encode dependency policies at a policy level (not version level)
• Document project-specific constraints
• Avoid drift-prone configuration duplication

---

Canonical Source & Anti-Drift Policy

To minimize maintenance overhead:

1. AGENTS.md is the canonical, tool-agnostic source of AI development rules.
2. Tool-specific files are derived, concise artifacts.
3. Volatile configuration data must never be embedded directly.

Prohibited Hardcoding

The following must not be statically embedded in tool-specific files:

• Exact dependency versions
• Version ranges or pinned constraints
• Minor Python versions (unless policy-level)
• CI matrix versions
• Tool configuration values
• Counts of modules, drivers, or files
• Experimental feature states

When necessary, reference authoritative sources instead:

• pyproject.toml
• pre-commit-config.yaml
• GitHub Actions workflows
• Source code defaults

Structural Over Quantitative

Prefer:

• Architectural rules
• Design principles
• Capability-based descriptions
• Policy-level constraints

Avoid:

• Numeric counts
• Enumerations of dynamic structures
• Repetition of dependency specifications

Regeneration Requirement

Tool-specific files must remain valid if dependencies or CI configurations change.

They must be safely regenerable without manual synchronization edits.

---

Requirements

AGENTS.md (Canonical)

• Located at repository root

• Single source of truth

• Tool-agnostic

• Documents:

  • Architecture and design constraints
  • Coding standards
  • Logging practices
  • Testing philosophy
  • Concurrency and execution constraints
  • Dependency policy (policy-level only)

• Must not embed volatile configuration values

.github/copilot-instructions.md

• Located under .github/
• Applies automatically to Copilot Chat
• Concise and enforceable
• Derived from AGENTS.md
• Must not introduce configuration drift
• Must remain independently effective

.claude/CLAUDE.md

• Located under .claude/
• Compatible with Claude Code and related tools
• Concise and enforceable
• Derived from AGENTS.md
• Must remain independently effective (not solely cross-referential)

---

Acceptance Criteria

• AGENTS.md exists at repository root and is canonical.
• .github/copilot-instructions.md exists and aligns with canonical rules.
• .claude/CLAUDE.md exists and aligns with canonical rules.
• No tool-specific file embeds volatile configuration values.
• Tool-specific files remain valid if dependency versions or CI settings change.
• AI-generated code reflects project standards without repeated prompting.
• Documentation clearly distinguishes canonical vs derived responsibilities.

---

Design Clarification

• AGENTS.md is the single source of truth.
• Tool-specific files are concise extracts derived from it.
• Tool-specific files may reference AGENTS.md, but must contain sufficient guidance to function independently.
• Avoid unnecessary duplication.
• Avoid embedding values that can drift over time.

---

Notes

Instructions must be:

• Concise
• Enforceable
• Structural rather than configuration-specific
• Regenerable without ongoing manual maintenance

The goal is consistent AI-assisted development with minimal long-term operational overhead.

[tomvothecoder]

@rljacob @mahf708 @forsyth2 @chengzhuzhang This is the GitHub issue prompt I am using to assign to GitHub Copilot to create the AI instructions files. We should consider standardizing a GitHub issue template similar to this and sharing it with others on E3SM to get them started with fully setting up their repos for AI development.

I'm happy to add a Confluence page if there is a support.

Results:

• simboard: Add AGENTS.md as canonical AI instruction source; refactor Copilot and Claude files as thin adapters #116
• xcdat: Add repository-level custom AI instruction files (Copilot, Agents, Claude) xCDAT/xcdat#835
• e3sm_diags: Add repository-level custom AI instruction files (Copilot, Agents, Claude) e3sm_diags#1039

[mahf708]

I remember rob linking to the main file only, see: E3SM-Project/E3SM#8083

[rljacob]

Yes that's done to guarantee the various tools all have the same context. My understanding is these do require hand-maintenance and you don't want to have to edit N of them.

[tomvothecoder]

@mahf708 @rljacob I agree, AGENTS.md should be the canonical source of truth. The Copilot and Claude files produced from my prompt can be simplified, with shared policy and constraints moved into AGENTS.md to avoid duplication.

I see two routes here:

1. Keep it simple – Put all governance and constraints in AGENTS.md and have Copilot and Claude files reference it. This minimizes maintenance and avoids drift (like what is done here).
2. Simple and min configs – Route 1 + include minimal workflow-specific guardrails (e.g., PR/diff scope constraints for Copilot, multi-file edit and refactor limits for Claude).

In any case, AGENTS.md remains the single source of truth. The decision is whether we want additional workflow-level guardrails per tool. I think 1 should be standard and 2 up to the maintainers based on their repos.

[tomvothecoder]

Just updated the prompt and the PR with new markdowns to follow route 1 above. Much simpler now and the adapters are minimal, basically just telling the tools explicitly to reference AGENTS.md

Result on SimBoard:

• Agents
• Copilot
• Claude

[mahf708]

@tomvothecoder I agree

[rljacob]

You're right that its up the repo maintainers if they want to have extra text in other context files. As long as you have AGENTS.md, you're fine.