diff --git a/CLAUDE.md b/CLAUDE.md
index 7b79fa168..6886fc1ed 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -107,6 +107,9 @@ All data flows as **Frame** objects through a pipeline of **FrameProcessors**:
 - **Docstrings**: Google-style. Classes describe purpose; `__init__` has `Args:` section; dataclasses use `Parameters:` section.
 - **Linting**: Ruff (line length 100). Pre-commit hooks enforce formatting.
 - **Type hints**: Required for complex async code.
+- **Dataclass vs Pydantic**: Use `@dataclass` for frames and internal pipeline data (high-frequency, no validation needed). Use Pydantic `BaseModel` for configuration, parameters, metrics, and external API data (benefits from validation and serialization). Specifically:
+  - `@dataclass`: Frame types, context aggregator pairs, internal data containers
+  - `BaseModel`: Service `InputParams`, transport/VAD/turn params, metrics data, API request/response models, serializer params
 
 ### Docstring Example