saorsa-core: Instructions file for Claude Code

CLAUDE.md

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

🤖 MANDATORY SUBAGENT USAGE

ALWAYS USE SUBAGENTS. THIS IS NOT OPTIONAL.

Subagents (via the Task tool) MUST be used whenever possible. They provide:

• Fresh context - Each subagent starts clean, preventing context pollution
• Parallel execution - Multiple agents can work simultaneously
• Specialization - Purpose-built agents for specific tasks
• Unbounded execution - No context limits when chaining agents

When to Spawn Subagents

Task Type	Action
Code exploration/search	Spawn Explore agent
Code review	Spawn review agents in parallel
Bug fixes	Spawn code-fixer agent
Test execution	Spawn test-runner agent
Build validation	Spawn build-validator agent
Security scanning	Spawn security-scanner agent
Documentation audit	Spawn documentation-auditor agent
Multi-step tasks	Spawn dev-agent or general-purpose agent
Complex research	Spawn Explore or general-purpose agent

Subagent Rules

1. PREFER subagents over doing work directly - Even for "simple" tasks
2. PARALLELIZE when possible - Spawn multiple agents in a single message
3. Use background agents for long-running tasks (run_in_background: true)
4. Chain agents for complex workflows - Output of one feeds the next
5. Never accumulate context - Delegate to fresh agents instead

IF YOU CAN USE A SUBAGENT, YOU MUST USE A SUBAGENT.

Build and Development Commands

Core Commands

# Build
cargo build                         # Debug build
cargo build --release               # Release build
cargo build --all-features          # Build with all features

# Tests - MUST ALL PASS before committing
cargo test                          # Run all tests
cargo test --lib                    # Unit tests only
cargo test --test '<test_name>'     # Specific integration test
cargo test test_function_name       # Run specific test by name
cargo test -- --nocapture           # Show println! output
RUST_LOG=debug cargo test           # With debug logging

# Code Quality - MUST PASS before committing
cargo fmt                           # Format code
cargo clippy -- -D warnings -D clippy::unwrap_used -D clippy::expect_used  # Strict linting
cargo audit                         # Security vulnerability check

# Benchmarks
cargo bench                         # Run all benchmarks
cargo bench --bench dht_benchmark  # Run specific benchmark

# Documentation
cargo doc --open                    # Build and open documentation

# Local CI Pipeline (safe, read-only checks)
./scripts/local_ci.sh               # Run full CI pipeline locally
./scripts/check_no_panic_unwrap.sh  # Check for forbidden patterns