dexrobot_isaac: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build Commands

• Install: pip install -e .
• Run simple test: python examples/dexhand_test.py
• Run with options: python examples/dexhand_test.py env.episodeLength=200 debug=true steps=500
• Test different control modes: python examples/dexhand_test.py env.controlMode=position_delta env.policyControlsFingers=true env.policyControlsHandBase=false
• Test headless with fewer envs: python examples/dexhand_test.py headless=true env.numEnvs=16 steps=100

Development Philosophy

Fail Fast - No Defensive Programming

This is research code where exposing bugs immediately is critical. NEVER hide errors with fallbacks.

❌ FORBIDDEN:

if x is None: x = default_value  # NO!
try: ... except: use_fallback   # NO!
value = x if x else fallback     # NO!
if hasattr(obj, 'attr'): ...     # NO! Let AttributeError expose bugs

✅ REQUIRED:

if x is None:
    raise RuntimeError("x is None - this indicates initialization bug")
# Let code crash immediately to expose problems at their source

Think Like a Scientist

Write elegant mathematical code, not defensive business logic.

Defensive Programming Clarification:

• ✅ DO check for external failures (hardware, file I/O, network)
• ❌ DON'T check if your own dependencies are None
• ❌ DON'T add fallbacks for your own logic errors
• If a dependency is required at init, it should NEVER be None later

❌ WRONG - Business programmer mindset:

if self.policy_controls_hand_base:
    if self.actions.shape[1] > 0:
        base_actions = self.actions[:, :self.NUM_BASE_DOFS]
        # ... 20 more lines of branching

✅ CORRECT - Scientific computing mindset:

# Use masks and vectorization
scaled_actions[:, self.active_target_mask] = self._scale_actions_to_limits(actions)

Key Principles:

1. Masking > Branching: Boolean masks replace conditional logic
2. Precompute Everything: Runtime should be pure math
3. Vectorize Operations: Think in tensors, not loops
4. Function Pointers: Assign functions during init, not runtime branching