Skip to content

Add AI-assistance policy, agent instructions, and code style docs#1699

Open
adcroft wants to merge 3 commits intomom-ocean:mainfrom
NOAA-GFDL:agents-and-policy
Open

Add AI-assistance policy, agent instructions, and code style docs#1699
adcroft wants to merge 3 commits intomom-ocean:mainfrom
NOAA-GFDL:agents-and-policy

Conversation

@adcroft
Copy link
Copy Markdown
Collaborator

@adcroft adcroft commented Apr 19, 2026

Add three new documentation files and supporting pointer files to guide both human contributors and AI coding assistants:

  • docs/Consortium-policy-on-AI.md : Project policy on AI-assisted contributions, authored by Hallberg and Ward. Establishes that a human contributor is accountable for all submitted code, requires disclosure of AI assistance in PRs, and catalogs specific risks (physical correctness, comprehension debt, vacuous tests, code churn, unsafe code). Permits AI for development assistance, debugging, documentation, CI triage, and PR review; prohibits autonomous contribution without human oversight.

  • docs/AGENTS.md : Technical instructions for AI coding assistants covering the parameter system (get_param, _BUG flags, ANSWER_DATE), diagnostics (registration, posting, masking conventions), the test suite (.testing/ with tc0–tc4, test categories, verification via bitwise-identical checksums), git workflow (fork-based branching, commit message conventions with */+ prefixes, PR description style), physics domain knowledge, common development tasks (new parameterizations, diagnostics, runtime parameters, bug fixes), architecture constraints (infra/framework layering), and defensive programming practices.

  • docs/Code-style.md : Fortran code style guide migrated from the wiki and extended with sections on module structure, naming conventions, memory macros (SZI_, SZIB_, etc.), the dimensional unit annotation system ([rescaled ~> MKS]), and Doxygen documentation requirements. The line-length guideline is set to 120 characters to match what trailer.py and the GitHub Action enforce.

Pointer files so AI tools auto-discover the conventions:

  • CLAUDE.md (Claude Code) — uses @docs/AGENTS.md directive
  • AGENTS.md (OpenAI Codex / OpenCode) — links to docs/AGENTS.md
  • .github/copilot-instructions.md (GitHub Copilot) — links to docs/AGENTS.md

Also updates existing documentation:

  • README.md: expanded project description, added resource links (developer wiki, forum, CVMix, TEOS-10, GOTM)
  • docs/code_organization.rst: updated directory tree to reflect current layout (added FMS2, nuopc_cap, timing_tests, unit_tests; removed mct_cap; added driver descriptions)
  • docs/about.rst: fixed typos
  • docs/front_page.md: updated link to Code-style.md
  • docs/README.md: pointed Doxygen style references to docs/Code-style.md instead of the retired wiki pages
  • docs/Doxygen_* were modified to include new markdown files

And, for full disclosure, copilot/Claude Opus 4.6 was used to reconcile the redundant or conflicting information between our first draft of the docs (on google drive) and files in the repository.

PR quirks:

@adcroft adcroft force-pushed the agents-and-policy branch 2 times, most recently from 3ae08ef to 14e7545 Compare April 19, 2026 17:10
glwagner and others added 3 commits April 20, 2026 10:08
- Add CLAUDE.md
- Update language description to Fortran (2023-compliant)
- Update build systems: drop CMake, add mkmf, remove GNU Make
- Add netCDF, HDF5, and MPI to dependencies list
- Update compilers: any standards-compliant, PGI to NVIDIA
- Apply suggestion from @glwagner
- Update testing description: emphasize .testing/, drop GitLab
- Main branch is main, don't single out dev/gfdl
- Note rare exceptions to no-global-data rule
- Pointers require intent, note some code is out of date
- Soften _init/_end and Local variables to conventions
- File naming: one module per file, name must match
- Add face/edge-point memory macros (SZIB_, SZJB_, SZKB_)
- Add no-double-divisions rule to arithmetic section
- Replace dev/gfdl with main in branch strategy section
- Tighten commit message format: 50-char subject, 72-col body
- Remove GFDL GitLab CI reference from CI section
- Remove line counts from source directory structure
- Remove (simplest; testing) from solo_driver desc
- Generalize infra/ description to framework interface
- Clarify !### meaning: known bugs deferred for cleanup
- Fix short-circuit advice: Fortran doesn't guarantee it
- Add no-touch signal for !### marked code
- Rename CLAUDE.md to AGENTS.md
Add three new documentation files and supporting pointer files to
guide both human contributors and AI coding assistants:

- docs/Consortium-policy-on-AI.md : Project policy on AI-assisted
contributions, authored by Hallberg and Ward. Establishes that a human
contributor is accountable for all submitted code, requires disclosure
of AI assistance in PRs, and catalogs specific risks (physical
correctness, comprehension debt, vacuous tests, code churn, unsafe
code). Permits AI for development assistance, debugging, documentation,
CI triage, and PR review; prohibits autonomous contribution without
human oversight.

- docs/AGENTS.md : Technical instructions for AI coding assistants
covering the parameter system (get_param, _BUG flags, ANSWER_DATE),
diagnostics (registration, posting, masking conventions), the test
suite (.testing/ with tc0–tc4, test categories, verification via
bitwise-identical checksums), git workflow (fork-based branching, commit
message conventions with */+ prefixes, PR description style), physics
domain knowledge, common development tasks (new parameterizations,
diagnostics, runtime parameters, bug fixes), architecture constraints
(infra/framework layering), and defensive programming practices.

- docs/Code-style.md : Fortran code style guide migrated from the wiki
and extended with sections on module structure, naming conventions,
memory macros (SZI_, SZIB_, etc.), the dimensional unit annotation
system ([rescaled ~> MKS]), and Doxygen documentation requirements.
The line-length guideline is set to 120 characters to match what
trailer.py and the GitHub Action enforce. Code-style.md is excluded
from doxygen INPUT because its example code blocks contain \namespace
and #include which doxygen parses as commands even inside fenced code
blocks, producing spurious warnings that fail CI.

Pointer files so AI tools auto-discover the conventions:
- CLAUDE.md (Claude Code) — uses @docs/AGENTS.md directive
- AGENTS.md (OpenAI Codex / OpenCode) — links to docs/AGENTS.md
- .github/copilot-instructions.md (GitHub Copilot) — links to
  docs/AGENTS.md

Also updates existing documentation:
- README.md: expanded project description, added resource links
  (developer wiki, forum, CVMix, TEOS-10, GOTM)
- docs/code_organization.rst: updated directory tree to reflect current
  layout (added FMS2, nuopc_cap, timing_tests, unit_tests; removed
  mct_cap; added driver descriptions)
- docs/about.rst: fixed typos
- docs/front_page.md: link to Code-style.md now points to GitHub
  (mom-ocean/MOM6) since the file is no longer in the doxygen output
- docs/README.md: pointed Doxygen style references to docs/Code-style.md
  instead of the retired wiki pages
- docs/Doxyfile_*: added Consortium-policy-on-AI.md to doxygen INPUT

And, for full disclosure, copilot/Claude Opus 4.6 was used to reconcile
the redundant or conflicting information between our first draft of the
docs (on google drive) and files in the repository.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants