agentleFS
ai2cmai2cm/ace/AGENTS.md

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.

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
  1. Very specific:

    Run all tests: make test

    line 19
  2. Very specific:

    Run fast tests only: make test_fast

    line 20
  3. Very specific:

    Run very fast tests: make test_very_fast

    line 21
  4. Very specific:

    Run tests with coverage: make test_cov

    line 22
  5. Very specific:

    Create development environment: make create_environment

    line 23
  6. Very specific:

    Run pre-commit hooks: pre-commit run --all-files

    line 25
  7. Very specific:

    When running tests in a conda environment, use python -m pytest (not pytest) to ensure the correct interpreter is used.

    line 27
  8. Very specific:

    Use pre-commit instead of ruff or ruff-format directly.

    line 29
  9. Distinctive:

    When committing changes, do not include Co-Authored-By: Claude in the commit message.

    line 53
  10. Very specific:

    When committing to a branch that has an open PR, check whether the PR description needs to be updated to reflect the changes.

    line 55
  11. Distinctive:

    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 …

    line 56
  12. Very specific:

    When making PRs, use the template that exists in the repo under .github/pull_request_template.md, if one exists.

    line 60
  13. Distinctive:

    Before starting, plan out how the changes will be made in one or more atomic commits.

    line 69
  14. Distinctive:

    Create helpers for repeated test setup (threshold: 3+ instances).

    line 91
  15. Distinctive:

    Prefer explicit helpers over pytest fixtures.

    line 92
  16. Distinctive:

    When fixing a bug, add a failing test first.

    line 93
  17. Distinctive:

    Prefer tests that cover user-story-level behavior over tests that lock down subjective API details.

    line 94
  18. Distinctive:

    Use this same workflow for both initial review and re-review.

    line 105
  19. Distinctive:

    If user provides a starting SHA, review changes from that point.

    line 120
  20. Distinctive:

    If not, ask for starting SHA or default to changes since last review comment timestamp.

    line 121
  21. Distinctive:

    Use these severity buckets:

    line 126
  22. Distinctive:

    Treat clear author rationale as addressed when appropriate.

    line 133
  23. Distinctive:

    Write concise markdown with:

    line 137
  24. Distinctive:

    Prefer delta-focused summaries for re-reviews.

    line 155
  25. Distinctive:

    If the PR was heavily refactored, recommend a fresh full review.

    line 156

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 Config to 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_dict is available for regression testing against a saved reference

Code organization

  • Consolidate duplicated code to shared locations (e.g. fme/core/).
  • fme/core is not allowed to import from fme.ace or other submodules.
  • fme/ace is allowed to import from fme.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:
    • get for metadata/state
    • get_diff for full diff (or current context)
    • get_review_comments for review threads
    • get_comments for general PR discussion
  • list_commits and get_commit when 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:

  1. PR Summary: title/number, author, target branch, goal
  2. Changes Overview: files changed + high-level summary
  3. Code Review Findings: grouped by severity with file/line references
  4. Discussion Status: key unresolved comment threads
  5. Testing Assessment: gaps and edge cases
  6. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.