docs: add CLAUDE.md for Claude Code guidance

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: shanghaikid

CLAUDE.md

@@ -0,0 +1,104 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Node.js SDK for [Milvus](https://milvus.io/) vector database, published as `@zilliz/milvus2-sdk-node`. Requires Node.js v18+.
+
+## Commands
+
+```bash
+# Install dependencies
+yarn install
+
+# Build (cleans dist/, compiles TS, generates sdk.json)
+yarn build
+
+# Run all tests (requires running Milvus instance)
+yarn test
+
+# Run a single test file (NODE_ENV=dev is required)
+NODE_ENV=dev npx jest test/grpc/SomeTest.spec.ts
+
+# Test coverage
+yarn coverage
+
+# Format code
+npx prettier --write <file-or-directory>
+
+# Regenerate proto JSON (after proto/ submodule update)
+yarn proto:json
+
+# Initialize proto submodule
+git submodule update --init --recursive
+```
+
+## Architecture
+
+Source code lives in `milvus/` (not `src/`). Build output goes to `dist/`.
+
+### Two Transport Layers
+
+1. **gRPC** (`MilvusClient`) — primary transport with connection pooling, automatic retries, and interceptors
+2. **HTTP** (`HttpClient`) — REST alternative for environments where gRPC isn't available
+
+### Class Inheritance Chain (gRPC)
+
+```
+BaseClient (proto loading, TLS, auth)
+  → User (user/role management)
+    → Database (database operations)
+      → Collection (collection CRUD)
+        → Data (insert/upsert/delete/query/search)
+          → Partition (partition management)
+            → MilvusIndex (index operations)
+              → Resource (resource queries)
+                → GRPCClient (channel pool, service init)
+                  → MilvusClient (high-level API)
+```
+
+Each class in `milvus/grpc/` adds one domain of Milvus operations. `MilvusClient` in `milvus/MilvusClient.ts` is the public entry point that extends `GRPCClient` with simplified high-level methods (aligned with the Python SDK).
+
+### Directory Layout
+
+- `milvus/grpc/` — gRPC client classes (one per domain: Collection, Data, User, etc.)
+- `milvus/http/` — HTTP client implementation
+- `milvus/types/` — TypeScript type definitions for requests/responses
+- `milvus/const/` — Constants, defaults, error codes
+- `milvus/utils/` — Utilities (schema building, data formatting, gRPC helpers, validation)
+- `milvus/proto-json/` — Generated proto definitions (from `yarn proto:json`)
+- `proto/` — Git submodule with upstream Milvus `.proto` files
+- `test/grpc/`, `test/http/`, `test/utils/` — Tests organized by transport/domain
+- `test/tools/` — Test helpers (collection param generators, data generators)
+
+### Key Patterns
+
+**Adding a new gRPC API method:**
+1. If proto has been updated: sync submodule (`git submodule update --init --recursive`) then regenerate JSON (`yarn proto:json`)
+2. Define request/response types in `milvus/types/`
+3. Implement method in the appropriate `milvus/grpc/` class
+4. Wrap gRPC calls with `promisify(this.grpcClient.methodName.bind(this.grpcClient), metadata, timeout)`
+5. Check results against `ErrorCode.SUCCESS`
+6. Add tests in `test/grpc/`
+7. Add JSDoc for public methods (include `@param` and `@returns`)
+
+**Error handling:**
+```typescript
+if (res.error_code !== ErrorCode.SUCCESS) {
+  throw new Error(res.reason);
+}
+```
+
+**gRPC interceptors** (in `milvus/utils/Grpc.ts`): meta (auth/db_name), retry (exponential backoff), trace (OpenTelemetry), request metadata (timing).
+
+**Connection pooling:** Uses `generic-pool` with configurable min/max (defaults: 5/10).
+
+## Code Style
+
+- TypeScript strict mode, target ES2015, CommonJS modules
+- Prettier: 2 spaces, single quotes, semicolons, ES5 trailing commas, avoid arrow parens
+- Classes: PascalCase; methods/variables: camelCase; constants: UPPER_CASE
+- Test files: `*.spec.ts`
+- Tests use `describe`/`it` blocks with `beforeAll`/`afterAll` for setup/cleanup
+- Tests are integration tests that connect to a real Milvus instance