From bbbfd1e7da36a9ce5c393e0390cdbd3eb9082f89 Mon Sep 17 00:00:00 2001
From: Zijie Tian <zijietian@mail.xmu.edu.cn>
Date: Thu, 8 Jan 2026 04:51:55 +0800
Subject: [PATCH] [docs] Simplify multi-instance development with direct
 PYTHONPATH

Replace pip install -e . --prefix=./.local approach with simpler PYTHONPATH method:
- No pip install required
- Code changes take effect immediately
- Each worktree is completely isolated

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/rules/commands.md | 14 ++++--------
 .claude/rules/testing.md  | 22 +++++++-----------
 CLAUDE.md                 | 48 ++++++++++++++-------------------------
 3 files changed, 30 insertions(+), 54 deletions(-)

diff --git a/.claude/rules/commands.md b/.claude/rules/commands.md
index 026ec79..64c861c 100644
--- a/.claude/rules/commands.md
+++ b/.claude/rules/commands.md
@@ -1,20 +1,16 @@
 # Commands
 
-## Installation
+## Running (with PYTHONPATH)
 
-```bash
-pip install -e .
-```
-
-## Running
+For multi-instance development, use PYTHONPATH instead of pip install:
 
 ```bash
 # Run example
-python example.py
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python example.py
 
 # Run benchmarks
-python bench.py                    # Standard benchmark
-python bench_offload.py            # CPU offload benchmark
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python bench.py
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python bench_offload.py
 ```
 
 ## Config Defaults
diff --git a/.claude/rules/testing.md b/.claude/rules/testing.md
index aa32abc..5f10f1a 100644
--- a/.claude/rules/testing.md
+++ b/.claude/rules/testing.md
@@ -66,33 +66,27 @@ print("test_xxx: PASSED")
 
 ## Running Tests
 
+Use PYTHONPATH for multi-instance isolation (no pip install needed):
+
 ```bash
 # Run a specific test
-python tests/test_offload_engine.py
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python tests/test_offload_engine.py
 
 # Run with specific GPU
-CUDA_VISIBLE_DEVICES=0 python tests/test_ring_buffer.py
+CUDA_VISIBLE_DEVICES=0 PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python tests/test_ring_buffer.py
 ```
 
 ## Benchmarks
 
 ```bash
-# Standard GPU benchmark
-python bench.py
-
-# CPU offload benchmark
-python bench_offload.py
-
-# vLLM comparison benchmark
-python bench_vllm.py
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python bench.py
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python bench_offload.py
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python bench_vllm.py
 ```
 
 ## Quick Verification
 
 ```bash
 # Import test
-python -c "from nanovllm import LLM"
-
-# Run offload benchmark (tests CPU-primary ring buffer mode)
-python bench_offload.py
+PYTHONPATH=/path/to/nano-vllm:$PYTHONPATH python -c "from nanovllm import LLM"
 ```
diff --git a/CLAUDE.md b/CLAUDE.md
index b56447d..a2d5ea8 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -44,45 +44,31 @@ python bench_offload.py
 - Running examples (`python example.py`)
 - Any script that imports torch/cuda
 
-## Local Package Installation for Multi-Instance
+## Multi-Instance Development with PYTHONPATH
 
-**CRITICAL**: After ANY code modification in the `nanovllm/` directory, you MUST reinstall the package before running tests or benchmarks:
+**IMPORTANT**: When running multiple Claude instances on different worktrees, do NOT use `pip install -e .` globally as it will affect other instances.
+
+**Use PYTHONPATH directly** - no pip install needed:
 
 ```bash
-pip install -e . --prefix=./.local --no-deps
+# Set PYTHONPATH to point to the project root directory
+PYTHONPATH=/path/to/your/worktree:$PYTHONPATH python <script.py>
+
+# Example: running tests
+PYTHONPATH=/home/zijie/Code/nano-vllm:$PYTHONPATH python tests/test_needle.py
 ```
 
-Then run with PYTHONPATH:
+**Benefits**:
+- No `pip install` required
+- Code changes take effect immediately (no reinstall needed)
+- Each worktree is completely isolated
+
+**For shell session** (optional):
 ```bash
-PYTHONPATH=./.local/lib/python3.10/site-packages:$PYTHONPATH python <script.py>
+export PYTHONPATH=/path/to/your/worktree:$PYTHONPATH
+python tests/test_needle.py  # PYTHONPATH already set
 ```
 
-**IMPORTANT**: When running multiple Claude instances on different worktrees, do NOT use `pip install -e .` globally as it will affect other instances. Instead, use local installation:
-
-1. **Install to worktree-local directory**:
-   ```bash
-   pip install -e . --prefix=./.local --no-deps
-   ```
-
-2. **Set PYTHONPATH before running any Python command**:
-   ```bash
-   export PYTHONPATH=./.local/lib/python3.10/site-packages:$PYTHONPATH
-   ```
-
-3. **Combined example**:
-   ```bash
-   # One-liner for running tests with local package
-   PYTHONPATH=./.local/lib/python3.10/site-packages:$PYTHONPATH python tests/test_needle.py
-   ```
-
-**Note**: The Python version in the path (python3.10) should match your environment.
-
-**CRITICAL**: After making code changes to `nanovllm/` source files, you MUST reinstall the package for changes to take effect:
-```bash
-pip install -e . --prefix=./.local --no-deps
-```
-Without reinstallation, Python will use the old cached version and your changes will NOT be reflected!
-
 ## Sparse Attention
 
 For sparse attention related content (block sparse attention, MInference, FlexPrefill, XAttention, AvgPool, etc.), refer to [`docs/sparse_attention_guide.md`](docs/sparse_attention_guide.md).