Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Add an `AGENTS.md` with shared rules for AI coding tools

Open
  • Is something wrong?
#976 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
Half a day
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
github, markdown
Domain
documentation

Research direction

Start by reading the draft in #950 and the two reference AGENTS.md files from pandas and scikit-learn. The target is a root AGENTS.md; reuse the linked docs under docs/developer_guide/ rather than duplicating them, and reconcile any existing .github/copilot-instructions.md. Done means the file exists, several developers have reviewed it, and the checklist in the issue is satisfied.

Written by the indexing model from the issue text.

Description

infrastructure

Add an AGENTS.md with shared rules for AI coding tools

@genevievestarke already has a draft up in #950 for review!

Developers who use AI tools each configure them differently, so generated code varies in style and quality. Common complaints from the workshop:

  • Code that does not follow H2I or OpenMDAO best practices
  • Excess code, such as too many try/except blocks, overly long names, and roundabout logic
  • Unrequested changes to unrelated files and large changes made without human collaboration or review
  • Agents lacking an overall view of H2I, so they duplicate existing utilities or break conventions

Proposed solution

Add a root-level AGENTS.md developed collaboratively by H2I developers so everyone's concerns are included.
Use the pandas and scikit-learn files as references:

Suggested contents:

  1. Expectations for humans using agents
    • Humans write issues, PR bodies, and review comments
    • Disclose AI usage in the PR (see the PR template issue)
  2. Scope limits for agents
    • Agents run pre-commit and the docs build where appropriate during dev
    • Make the smallest change that solves the request; no unrelated file edits
    • Do not add speculative abstractions (goldplating), broad try/except, or extra comments
    • Stop and ask before large or cross-cutting changes
  3. H2I conventions
    • Link to docs/developer_guide/coding_guidelines.md, class_structure.md, testing.md, and adding_a_new_technology.md
    • Model registration, config class naming, control signal naming, and units in OpenMDAO variables
    • OpenMDAO pitfalls agents commonly get wrong (collect these from the team)
  4. Sensitive framework areas that need extra care and human collaboration (see the area-guardrails issue)
  5. Facts and numbers: agents can never invent values; cite a primary source.
  6. Security: no secrets, no sensitive data, no unreviewed network access or new dependencies.

How to know when we're done

  • AGENTS.md exists at the repo root and is reviewed by several developers (including non-AI users)
  • Any individual dev's existing AGENTS.md file or .github/copilot-instructions.md is reconciled with it (single source of truth, or one points to the other)
  • The file is kept short and links to docs instead of duplicating them
Dominant language
Python
Stars
30
Forks
44
Avg merge
3d 12h
Merged PRs (30d)
28

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from NatLabRockies/H2Integrate

All issues in NatLabRockies/H2Integrate

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.