Skip to content

AGENTS.md

Latest commit

 

History

History
94 lines (68 loc) · 2.76 KB

AGENTS.md

File metadata and controls

94 lines (68 loc) · 2.76 KB

AGENTS.md - Genesis AI Agent Guide

Guide for AI coding assistants working with the Genesis physics simulation codebase.

Quick Start

# Setup
uv sync
uv pip install torch --index-url https://download.pytorch.org/whl/cu126  # or cpu/metal

# Run tests
uv run pytest tests/
uv run pytest tests/ -m required  # minimal set

# Run examples
uv run examples/tutorials/hello_genesis.py

How to Run Tests

uv run pytest tests/                      # All tests
uv run pytest tests/test_file.py          # Specific file
uv run pytest tests/ --backend=gpu        # GPU backend
uv run pytest tests/ -m required          # Required tests only
uv run pytest tests/ -m "not slow"        # Skip slow tests

See TESTING.md for details.

How to Contribute

PR Title Prefixes

  • [BUG FIX] - Non-breaking bug fixes
  • [FEATURE] - New functionality
  • [MISC] - Minor changes (docs, typos)
  • [CHANGING] - Behavior changes
  • [BREAKING] - Breaking API changes

Before Submitting

  1. Install pre-commit hooks: pre-commit install
  2. Run required tests: uv run pytest -m required tests/
  3. Link to related issue in PR description

See PULL_REQUESTS.md for details.

Formatting & Lint

Genesis uses ruff for linting and formatting (via pre-commit):

# Install hooks (auto-runs on commit)
pre-commit install

# Manual run
pre-commit run --all-files

Rules:

  • Line length: 120 characters
  • Format: ruff-format (black-compatible)
  • Lint: ruff-check

See CODING_CONVENTIONS.md for code style.

When to Ask a Human

Ask for clarification when:

  • Ambiguous requirements - Multiple valid interpretations exist
  • Breaking changes - Changes that affect public APIs or behavior
  • Architecture decisions - New solvers, major refactors, new entity types
  • Performance trade-offs - When optimization conflicts with readability
  • Test failures - Unclear why tests fail or how to fix them
  • Cross-solver coupling - Changes affecting multiple physics solvers

Do NOT ask when:

  • Standard bug fixes with clear reproduction steps
  • Documentation updates
  • Adding tests for existing functionality
  • Code style fixes flagged by linters

Reference Documentation

Document Description
ARCHITECTURE.md Project structure, solvers, entities
TESTING.md Testing guide and fixtures
CODING_CONVENTIONS.md Code style and patterns
EXAMPLES.md Examples reference
PULL_REQUESTS.md PR guidelines