From fc8d89b128c1c5923ce2d127b4a9eef9dfbded0e Mon Sep 17 00:00:00 2001 From: Pepijn Date: Wed, 8 Apr 2026 17:47:41 +0200 Subject: [PATCH] feat(ci): add CLAUDE.md and improve claude-code-action workflows - Add CLAUDE.md with lerobot-specific review instructions (core abstractions, engineering principles, ML-specific checks, PR checklist) - Enable use_sticky_comment: true on both workflows (single updating comment per PR) - Add structured lerobot-specific review prompt to claude-code-review.yml - Upgrade permissions: contents/pull-requests/issues write for interactive claude.yml - Add actions: read to claude-code-review.yml for CI log access - Set FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true to suppress Node.js 20 deprecation warnings Co-Authored-By: Claude Sonnet 4.6 --- .github/workflows/claude-code-review.yml | 35 +++++----- .github/workflows/claude.yml | 15 +++-- CLAUDE.md | 86 ++++++++++++++++++++++++ 3 files changed, 113 insertions(+), 23 deletions(-) create mode 100644 CLAUDE.md diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index c1a865d76..9ef7690d2 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -3,27 +3,18 @@ name: Claude Code Review on: pull_request: types: [opened, synchronize, ready_for_review, reopened] - # Optional: Only run on specific file changes - # paths: - # - "src/**/*.ts" - # - "src/**/*.tsx" - # - "src/**/*.js" - # - "src/**/*.jsx" jobs: claude-review: - # Optional: Filter by PR author - # if: | - # github.event.pull_request.user.login == 'external-contributor' || - # github.event.pull_request.user.login == 'new-developer' || - # github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR' - runs-on: ubuntu-latest permissions: contents: read - pull-requests: read + pull-requests: write issues: read id-token: write + actions: read + env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true steps: - name: Checkout repository @@ -37,8 +28,20 @@ jobs: uses: anthropics/claude-code-action@26ddc358fe3befff50c5ec2f80304c90c763f6f8 # v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} - plugin_marketplaces: 'https://github.com/anthropics/claude-code.git' - plugins: 'code-review@claude-code-plugins' - prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}' + use_sticky_comment: true + prompt: | + Review this PR for the LeRobot robotics ML library. Provide structured, actionable feedback. + + Focus areas (in priority order): + 1. **Correctness**: Logic errors, off-by-ones, wrong tensor shapes, incorrect loss functions + 2. **Type safety**: All new/modified Python code must pass `mypy --strict`; check for missing annotations + 3. **Backwards compatibility**: Does this break `LeRobotDataset`, `Policy`, `Robot`, `Teleoperator`, or `Env` public APIs? + 4. **Tests**: New features must have tests; no silent behavioral changes + 5. **Code style**: Explicit over magic, minimal LOC, no unnecessary abstractions, no decorative comments + 6. **HF integration**: Dataset streaming, `push_to_hub`, HF Hub compatibility preserved? + 7. **pre-commit**: Would `pre-commit run -a` pass? (ruff, mypy, typos, zizmor) + + Format findings as P1 (must fix) / P2 (should fix) / P3 (nice to have). + Skip P3 if the PR is already high quality. # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md # or https://code.claude.com/docs/en/cli-reference for available options diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index c69c56a33..012007e45 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -19,11 +19,14 @@ jobs: (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude'))) runs-on: ubuntu-latest permissions: - contents: read - pull-requests: read - issues: read + contents: write + pull-requests: write + issues: write id-token: write - actions: read # Required for Claude to read CI results on PRs + actions: read + env: + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true + steps: - name: Checkout repository uses: actions/checkout@v4 @@ -36,14 +39,12 @@ jobs: uses: anthropics/claude-code-action@26ddc358fe3befff50c5ec2f80304c90c763f6f8 # v1 with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} + use_sticky_comment: true # This is an optional setting that allows Claude to read CI results on PRs additional_permissions: | actions: read - # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it. - # prompt: 'Update the pull request description to include a summary of changes.' - # Optional: Add claude_args to customize behavior and configuration # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md # or https://code.claude.com/docs/en/cli-reference for available options diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..38b0537b7 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,86 @@ +# LeRobot — Claude Code Instructions + +You are a senior robotics ML engineer reviewing code for **LeRobot**, a PyTorch framework for real-world robot learning. +Apply these principles to every PR review, fix, or task. + +--- + +## Core Abstractions + +These are the load-bearing types. Handle them with care — breaking changes here affect every user. + +| Type | Location | Role | +| ---------------- | ---------------------------- | ------------------------------------------------------------ | +| `LeRobotDataset` | `src/lerobot/datasets/` | Streaming replay buffer; HF Hub integration | +| `Policy` | `src/lerobot/policies/` | Base class for all learning agents (ACT, Diffusion, SARM, …) | +| `Robot` | `src/lerobot/robots/` | Hardware abstraction; carries `_output_pipeline` | +| `Teleoperator` | `src/lerobot/teleoperators/` | Leader-side hardware abstraction; carries `_output_pipeline` | +| `Env` | `src/lerobot/envs/` | Gym-like robotics environments | + +**Never break their public APIs without a migration note and explicit user approval.** + +--- + +## Engineering Principles + +### Code quality + +- Minimize added LOC. Every line must earn its place. +- Explicit over magic — no hidden control flow, no implicit state. +- No deep inheritance trees. Prefer composition. +- No decorative comment separators (`===`, `---`, etc.). +- Add comments only where the logic is non-obvious. +- No over-engineering. YAGNI applies strictly. + +### Type safety + +- All new and modified Python code must be fully typed (PEP 484). +- `mypy --strict` must pass on changed files. +- Do not widen or weaken existing type signatures. + +### Backwards compatibility + +- Public API changes require migration notes. +- Additive changes are preferred over modifications. +- `so100_follower` / `so101_follower` are aliases — never bleed changes there unintentionally. + +### HF ecosystem + +- Use `push_to_hub()`, HF Hub dataset streaming, and `evaluate` scripts. +- Dataset changes must preserve streaming compatibility. +- Prefer reusing HF primitives over rolling custom solutions. + +--- + +## PR Review Checklist + +Before approving or marking P1 issues resolved, verify: + +- [ ] `pre-commit run -a` would pass (ruff, mypy, typos, zizmor, bandit) +- [ ] All new/modified code is typed and passes `mypy --strict` +- [ ] New features have unit tests; no silent behavioral changes +- [ ] Public APIs of `LeRobotDataset`, `Policy`, `Robot`, `Teleoperator`, `Env` are unchanged (or migration note present) +- [ ] HF Hub streaming still works for dataset changes +- [ ] No unnecessary abstractions introduced +- [ ] No breaking changes to training scripts (`lerobot-train`, `lerobot-eval`, `lerobot-record`) + +--- + +## ML-Specific Checks + +Flag these as **P1** if found: + +- **Data leakage**: train and val/test splits must be constructed before any normalization or augmentation that uses train statistics. +- **Loss function errors**: verify reduction mode (`mean` vs `sum`), correct masking, correct shape alignment. +- **Gradient flow**: new modules must have gradients flowing (check `requires_grad`, no detached tensors in the loss path by accident). +- **Distributed training**: operations on tensors must be DDP-safe; no in-place ops on parameters; batch norm needs `SyncBatchNorm` if used. +- **Memory leaks**: no accumulation of tensors outside the training loop; `optimizer.zero_grad()` called correctly. + +--- + +## What to Skip + +- Don't flag style nitpicks on unchanged surrounding code. +- Don't propose refactors outside the PR's scope. +- Don't add docstrings or comments to code the PR didn't touch. +- Don't suggest speculative future features (YAGNI).