ace
AGENTS.md261 starsChanged 49 days agoApache-2.0View on GitHub
This file is the single source of agent guidance for the ai2cm/ace repository. This is a Python machine learning project for atmospheric modeling (ACE - AI2 Climate Emulator). When running tests in a conda environment, use python -m pytest (not pytest) to ensure the correct interpreter is used. Pre-commit hooks run ruff, ruff-format, and mypy. Use pre-commit instead of ruff or ruff-format directly. Tests marked @pytest.mark.parallel must be run via torchrun. Environment variables FME_DISTRIBUTED_BACKEND (torch|model|none), FME_DISTRIBUTED_H, and FME_DISTRIBUTED_W control the…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- pre-reviewSkill
- write-pr-proseSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
25 rules. About 0 are common, 15 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Run all tests: make test
- Very specific: line 20
Run fast tests only: make test_fast
- Very specific: line 21
Run very fast tests: make test_very_fast
- Very specific: line 22
Run tests with coverage: make test_cov
- Very specific: line 23
Create development environment: make create_environment
- Very specific: line 25
Run pre-commit hooks: pre-commit run --all-files
- Very specific: line 27
When running tests in a conda environment, use python -m pytest (not pytest) to ensure the correct interpreter is used.
- Very specific: line 29
Use pre-commit instead of ruff or ruff-format directly.
- Distinctive: line 53
When committing changes, do not include Co-Authored-By: Claude in the commit message.
- Very specific: line 55
When committing to a branch that has an open PR, check whether the PR description needs to be updated to reflect the changes.
- Distinctive: line 56
When amending a PR description, make sure it still reflects the change _from the PR's base branch_ (main, unless the PR is stacked on …
- Very specific: line 60
When making PRs, use the template that exists in the repo under .github/pull_request_template.md, if one exists.
- Distinctive: line 69
Before starting, plan out how the changes will be made in one or more atomic commits.
- Distinctive: line 91
Create helpers for repeated test setup (threshold: 3+ instances).
- Distinctive: line 92
Prefer explicit helpers over pytest fixtures.
- Distinctive: line 93
When fixing a bug, add a failing test first.
- Distinctive: line 94
Prefer tests that cover user-story-level behavior over tests that lock down subjective API details.
- Distinctive: line 105
Use this same workflow for both initial review and re-review.
- Distinctive: line 120
If user provides a starting SHA, review changes from that point.
- Distinctive: line 121
If not, ask for starting SHA or default to changes since last review comment timestamp.
- Distinctive: line 126
Use these severity buckets:
- Distinctive: line 133
Treat clear author rationale as addressed when appropriate.
- Distinctive: line 137
Write concise markdown with:
- Distinctive: line 155
Prefer delta-focused summaries for re-reviews.
- Distinctive: line 156
If the PR was heavily refactored, recommend a fresh full review.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
This file is the single source of agent guidance for the ai2cm/ace repository.
Repository Context
This is a Python machine learning project for atmospheric modeling (ACE - AI2 Climate Emulator).
Key Conventions
- Code is in the
fme/directory (ace, core, coupled, diffusion, downscaling modules) - Tests follow pytest conventions
- Configuration uses YAML files in
configs/ - The project uses PyTorch for ML components
- The default conda environment for the repo is named
fme
Common Commands
- Run all tests:
make test - Run fast tests only:
make test_fast - Run very fast tests:
make test_very_fast - Run tests with coverage:
make test_cov - Create development environment:
make create_environment - Build Docker image:
make build_docker_image - Run pre-commit hooks:
pre-commit run --all-files
When running tests in a conda environment, use python -m pytest (not pytest) to ensure the correct interpreter is used.
Pre-commit hooks run ruff, ruff-format, and mypy.
Use pre-commit instead of ruff or ruff-format directly.
Parallel / Spatial Parallel Testing
Tests marked @pytest.mark.parallel must be run via torchrun. Environment
variables FME_DISTRIBUTED_BACKEND (torch|model|none),
FME_DISTRIBUTED_H, and FME_DISTRIBUTED_W control the backend.
Set FME_FORCE_CPU=1 for CPU. Quick smoke test:
FME_FORCE_CPU=1 FME_DISTRIBUTED_BACKEND=model FME_DISTRIBUTED_H=2 FME_DISTRIBUTED_W=1 \
torchrun --nproc-per-node 2 -m pytest -m parallel .Full matrix (8 configs, ~3-4 min): make cpu_test_all_parallel
Narrow to specific tests: make cpu_test_all_parallel TEST_PATH=fme/core/distributed/parallel_tests/test_step.py
Regression tests using .pt baselines must generate the baseline with a
single-rank python -m pytest run, then verify under spatial parallel via
torchrun. Generating baselines under the same backend you test against does
not validate cross-backend correctness.
Code Guidelines for Agents
Committing
When committing changes, do not include Co-Authored-By: Claude in the commit message. This is because Claude bears no accountability or responsibility for the changes, the user is the sole author accountable.
When committing to a branch that has an open PR, check whether the PR description needs to be updated to reflect the changes; update it via the write-pr-prose skill (see "PR description template").
When amending a PR description, make sure it still reflects the change from the PR's base branch (main, unless the PR is stacked on another branch), not the change from a previous, ephemeral state of the PR.
PR description template
When making PRs, use the template that exists in the repo under .github/pull_request_template.md, if one exists.
The PR description becomes the squash-and-merge commit message, so keep it self-contained and describe the final state of the change from main. PR-process information belongs in PR comments, not the description.
In Claude Code sessions, write or amend PR titles and descriptions only via the write-pr-prose skill (.claude/skills/write-pr-prose/), never inline: its frontmatter pins PR-prose authoring to the required model.
Commit/PR process
Changes that will go to main should be made in branches so that PRs can be made for review. Before starting, plan out how the changes will be made in one or more atomic commits. Commits should leave the codebase in a consistent state, and should not add unused features that can't be reviewed in isolation. They should also include tests for any new functionality, and should not break existing tests.
For branch naming conventions, see the "Internal Development" section of CONTRIBUTING.md.
Naming
- Config classes loaded from user-specified yaml: append
Configto the built type (TrainStepperConfig). - Private functions get a
_prefix.
Code style
- isinstance checks and type: ignore statements are a sign that types should be refactored, when adding them you must justify the decision.
Config design
- Validate in
__post_init__, not at runtime. - Trained checkpoint loading backwards compatibility for inference is critical, but can be broken for training; use deprecation warnings for config removal. Ask user if unsure.
Testing
- Create helpers for repeated test setup (threshold: 3+ instances).
- Prefer explicit helpers over pytest fixtures; use fixtures only when sharing scope across tests is valuable.
- When fixing a bug, add a failing test first.
- Prefer tests that cover user-story-level behavior over tests that lock down subjective API details.
- Helper function
validate_tensor_dictis available for regression testing against a saved reference
Code organization
- Consolidate duplicated code to shared locations (e.g.
fme/core/). fme/coreis not allowed to import fromfme.aceor other submodules.fme/aceis allowed to import fromfme.core, but not from other submodules.
Pull Request Review Assistant
Use this same workflow for both initial review and re-review.
1) Gather context with GitHub MCP
pull_request_read:getfor metadata/stateget_difffor full diff (or current context)get_review_commentsfor review threadsget_commentsfor general PR discussion
list_commitsandget_commitwhen commit-by-commit analysis is needed
2) Scope the review
- Initial review: review the full PR diff and all current discussion.
- Re-review (delta review):
- If user provides a starting SHA, review changes from that point.
- If not, ask for starting SHA or default to changes since last review comment timestamp.
- Focus on what changed, whether prior comments were addressed, and whether new issues were introduced.
3) Evaluate findings
Use these severity buckets:
- Critical Issues (Must Fix): security vulnerabilities, logic bugs, breaking changes
- Suggestions (Should Consider): performance, error handling, clarity/design improvements
- Minor/Nitpicks (Optional): style, naming, docs polish
For re-reviews, classify prior comments as Addressed, Partially Addressed, Unaddressed, or Dismissed. Treat clear author rationale as addressed when appropriate.
4) Output format
Write concise markdown with:
- PR Summary: title/number, author, target branch, goal
- Changes Overview: files changed + high-level summary
- Code Review Findings: grouped by severity with file/line references
- Discussion Status: key unresolved comment threads
- Testing Assessment: gaps and edge cases
- Recommendation: Ready to merge / Needs minor changes / Needs revision
For re-reviews, include:
- Commits reviewed (
<start_sha>...<head_sha>) - Status of previously raised comments
- Outstanding items before merge
5) Practical guidance
- Be specific, constructive, and explicit about blocking vs non-blocking items.
- Prefer delta-focused summaries for re-reviews.
- If the PR was heavily refactored, recommend a fresh full review.
- For large PRs, batch API calls to avoid rate limits.
- Remember that GitHub MCP access is read-only.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

