Add AI-assistance policy, agent instructions, and code style docs#1699
Open
adcroft wants to merge 3 commits intomom-ocean:mainfrom
Open
Add AI-assistance policy, agent instructions, and code style docs#1699adcroft wants to merge 3 commits intomom-ocean:mainfrom
adcroft wants to merge 3 commits intomom-ocean:mainfrom
Conversation
3ae08ef to
14e7545
Compare
- 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
Very minor but this was a typo I think? [This address](https://github.com/NOAA-GFDL/MOM6-examples/blob/dev/master/ocean_only/global_ALE/z/available_diags.000000) gives me a 404 error [whereas this](https://github.com/NOAA-GFDL/MOM6-examples/blob/dev/gfdl/ocean_only/global_ALE/z/available_diags.000000) does not. Found this because I was writing some training notes: https://decoding-access-om3.readthedocs.io/decoding_mom6/#specifying-model-outputs-via-diag_table-or-make_diag_table
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.
14e7545 to
791736b
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
Also updates existing documentation:
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: