[CLAUDE.md] add code conventions from PR #3429 review

Patterns: enums in enums.py, constants in constants.py, typed error hierarchies,
TypedDicts for structured dicts, filelock for cross-platform locking, tentacle
import priority (tentacles-first), log level guidelines, shared filter helpers.

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

Author: Herklos

CLAUDE.md

@@ -36,6 +36,49 @@ Use when: running tests, debugging test failures, or verifying changes after cod
 
 Trigger: `@agent-test-runner` · Definition: `.claude/agents/test-runner.md`
 
+## Code Conventions
+
+### Enums
+Place enums in `<package_root>/enums.py` (e.g. `octobot/enums.py`, `packages/node/octobot_node/enums.py`). Never define enums inline in module files.
+
+### Constants
+Place module-wide constants in `<package_root>/constants.py`. Private module constants (used only within one file) may stay in that file, prefixed with `_`.
+
+### Typed errors
+Define a typed error hierarchy rather than raising bare `ValueError`/`KeyError`. Pattern:
+```python
+# errors.py (sibling to the feature module)
+class FeatureError(Exception): pass
+class SpecificError(FeatureError, ValueError): pass  # multi-base preserves except ValueError compat
+```
+Re-export from the package `__init__.py`. Use typed catches in API routes — never inspect `str(err).lower()`.
+
+### TypedDicts for structured dicts
+When a dict has a fixed schema (e.g. wallet info returned to callers), define a `typing.TypedDict`. Place it in the module that owns the data, before the class that produces it.
+
+### File locking
+Use the `filelock` library (cross-platform, POSIX + Windows) instead of `fcntl`/`msvcrt` branching.
+
+### Import priority in tentacle files
+Prefer the installed `tentacles.Services.Interfaces.*` path first; fall back to bare direct imports (build-time fallback). Pattern:
+```python
+try:
+    from tentacles.Services.Interfaces.node_api_interface.api.deps import X
+except ImportError:
+    from api.deps import X  # type: ignore[no-redef]
+```
+All files within a tentacle package should use the same priority order.
+
+### Log levels
+- `debug`: verbose diagnostics, expected no-ops.
+- `info`: normal operational events (startup, shutdown, config loaded).
+- `warning`: unexpected but recoverable (auto-unlock skipped, optional feature unavailable).
+- `error`: configuration/state errors that affect functionality (wallet missing, key wrong).
+- `exception`: unexpected exceptions — always re-raise after logging unless the function is a top-level "best-effort" path that must not crash the caller.
+
+### Shared filter helpers
+Filtering logic used in multiple places belongs in a shared utility module (e.g. `workflows_util.py`), not duplicated inline. Name with a verb: `filter_by_wallet`, not `_filter`.
+
 ## Documentation
 
 Documentation lives in `docs/content/` and is built with Docusaurus 3. Package docs go under `docs/content/developers/packages/<pkg-name>/`.