DeveloperGuides

Shared engineering standards, architectural patterns, and development guidelines for human and AI developers across the CliMA ecosystem.

License

Usage

DeveloperGuides is included as a Git subtree in CliMA repositories at the standardized path docs/dev-guides/. To add the subtree to a new consumer repo:

git subtree add --prefix docs/dev-guides \
    https://github.com/CliMA/DeveloperGuides.git main --squash

Note

DeveloperGuides ships its own AGENTS.md, LICENSE, and README.md at the repo root. These will conflict with the consumer repo's own root files during git subtree add. Resolve by keeping the consumer repo's versions:

git checkout --ours AGENTS.md LICENSE README.md
git add AGENTS.md LICENSE README.md
git rebase --continue   # or: GIT_EDITOR=true git rebase --continue

The consuming repo keeps its own AGENTS.md at the root, which references:

1. docs/dev-guides/AGENTS.md — the shared guide index
2. A repo-specific guide (e.g., docs/clima_atmos_specific.md)

See templates/ for ready-to-copy starter files: an AGENTS.md skeleton, a repo-specific guide skeleton, and a GitHub Actions workflow (update_dev_guides.yml.template) that automates the monthly subtree sync.

Updating

Consumer repos track main. To pull the latest guides manually:

git subtree pull --prefix docs/dev-guides \
    https://github.com/CliMA/DeveloperGuides.git main --squash \
    -m "chore: sync dev guides from central repo"

Note

git subtree pull exits with an error when there are no new commits upstream (i.e. nothing to merge). In an automated workflow, append || true so the step does not fail on months with no DeveloperGuides changes:

git subtree pull --prefix docs/dev-guides \
    https://github.com/CliMA/DeveloperGuides.git main --squash \
    -m "chore: sync dev guides from central repo" || true

Most consumer repos automate this with a scheduled GitHub Action (.github/workflows/update_dev_guides.yml) that runs the subtree pull monthly and opens a PR when there are changes. See templates/ for a ready-to-copy workflow file.

Contributing back

Edits to shared guidelines belong here, not in the vendored copy inside a consumer repo. Open PRs against CliMA/DeveloperGuides; once merged, the next subtree pull propagates them to every consumer.

🏗️ Architecture

• Repo Structure — how to navigate any CliMA Julia package.
• Ecosystem Conventions — module aliases, state layout (Y/Yₜ/p), ᶜ/ᶠ notation, CI, reproducibility, diagnostics.
• Architectural Boundaries — layered architecture and boundary rules.
• Software Design Patterns — numbered SDPs: branchless logic, functors, parameter extraction, etc.
• Cross-Repo Contracts — call-site conventions for ecosystem packages.
• Dependency Management — runtime vs dev deps, compat bounds.

⚡ Performance

• GPU Performance — GPU kernel rules, broadcast patterns, allocation avoidance.
• Type Stability — Float32 compatibility, inference checks, struct field rules.
• Numerical Robustness — denominator regularization, clamping, NaN/Inf avoidance.
• AD Compatibility — AD-safe patterns for ForwardDiff and Enzyme.
• Allocation Debugging — locating heap allocations with Profile.Allocs, JET, flame graphs.

🔧 Code Quality

• Code Style — formatting, variable locality, Git workflow, feature removal, naming conventions.
• Documentation Policy — docstrings, repository-level docs, minimally viable documentation.
• Changelogs and Versioning — NEWS.md format, SemVer rules, and the release/tagging flow.
• Variable List — standardized CliMA variable naming conventions.

🧪 Infrastructure

• Testing and Validation — type-stability checks, Aqua.jl, allocation regression, AD tests.
• ClimaComms — device-agnostic and MPI-distributed code patterns.

🤝 Workflow

• Onboarding — install Julia, clone a CliMA repo, set up Revise/Infiltrator/JuliaFormatter, first PR loop.
• Agent Autonomy — actions that require explicit user approval.
• Debugging — interactive recipes for numerical instabilities, dispatch surprises, and Field plotting.
• PR Review — review instructions and checklist.
• CI Triage — checklist for "passes locally, fails on CI" failure modes.

Directory Structure

├── AGENTS.md                  # Master index for AI agents
├── architecture/              # System design, layering, contracts
├── performance/               # GPU, type stability, numerics, AD
├── code-quality/              # Style, docstrings, changelogs
├── infrastructure/            # Testing, device abstraction
├── workflow/                  # Agent autonomy, PR review
└── templates/                 # Starter files for consumer repos

Integration with the CliMA Ecosystem

DeveloperGuides is the central source of truth for engineering standards across CliMA, including:

• ClimaAtmos
• ClimaCore
• ClimaLand
• ClimaOcean
• ClimaCoupler
• Thermodynamics
• CloudMicrophysics
• SurfaceFluxes
• ClimaTimeSteppers

Contributing

• Each guide has a Self-correction section: if you discover a guide is stale or missing a pattern, update it directly.
• New guides should be placed in the appropriate category directory and added to AGENTS.md.
• Cross-references between guides should use relative paths (e.g., ../performance/gpu_performance.md).

Getting Help

For questions or suggestions, open an issue on GitHub.