# DocumentDb Project Rules

## Performance Constraints

### Tool Usage
- **NEVER** use the `&` operator to combine commands in PowerShell (not supported). Use `;` or separate `run_command` calls instead.

### Development
- **ALWAYS** involve the user for refactoring tasks on sample and test files to focus on the core logic
- Ask the user for build or test to get stack trace

### Zero-Reflection Policy
- **NEVER** use reflection in hot paths or runtime code
- Source generators are preferred for code generation
- All type information must be resolved at compile-time

### Zero-Allocation Goals
- Minimize heap allocations in critical paths
- Use `Span<T>`, `ReadOnlySpan<T>`, and `Memory<T>` for buffer operations
- Leverage stack allocation where appropriate (`stackalloc`)
- Reuse buffers through `ArrayPool<T>` or custom pooling
- Avoid LINQ in hot paths (use manual loops instead)
- Prefer value types over reference types when possible
- Use `ref struct` for temporary data structures

### High-Performance Requirements
- Memory-mapped files for efficient I/O
- Lock-free or minimal locking strategies
- Batch operations where possible
- Optimize for CPU cache locality
- Profile and benchmark all critical paths

## Code Quality

### Design Principles
- Prefer composition over inheritance
- Use interfaces for abstraction
- Keep public API surface minimal and intentional
- Use `readonly struct` for immutable value types

### Testing
- All public APIs must have unit tests
- Performance-critical code must have benchmarks
- Verify zero-allocation with BenchmarkDotNet memory diagnostics