rez-next: Instructions file for Claude Code

CLAUDE.md - Anthropic Claude Guidance for rez-next

Important: This file references AGENTS.md for core project information. Read that file first.

For Anthropic Claude Agents

When working with the rez-next project, follow this guidance:

1. Start Here

Read AGENTS.md to understand:

• Project structure and architecture
• Available Python modules and their Rez equivalents
• Development workflow (build, test, lint)
• Common tasks and how to approach them

2. Key Principles

• Progressive disclosure: AGENTS.md → llms.txt (concise) → llms-full.txt (full API) → docs/ (human guides)
• Check coverage: Not all Rez APIs are implemented; verify before suggesting code
• Use vx: Tool management via vx (see vx.toml)
• Run CI early: vx just ci before submitting changes

3. Python Code Patterns

# ✅ Correct: Use rez_next as drop-in
import rez_next as rez
from rez_next.packages_ import get_latest_package

# ❌ Avoid: Direct rez imports (won't work with rez-next)
import rez

4. Rust Code Patterns

// ✅ Correct: Use the crate structure
use rez_next_version::Version;
use rez_next_package::Package;

// ❌ Avoid: Direct std types when crate types exist

5. Documentation Updates

When updating documentation:

1. Update AGENTS.md (project map) if structure changes
2. Update llms.txt (AI-friendly concise index) if submodule list changes
3. Update llms-full.txt (complete API reference) for new APIs
4. Update docs/*.md (human guides) for workflow changes
5. Update README.md / README_zh.md for user-facing changes

6. Commit Messages

Follow Conventional Commits:

feat: add new solver heuristic
fix(solver): handle cyclic dependencies
docs: update AGENTS.md with new module
chore: upgrade dependencies

7. Testing Strategy

# Always run tests before submitting
vx just test

# Run specific tests
cargo test --package rez-next-solver

# Run Python tests
maturin develop --release && pytest