Vision-Agents: Instructions file for Claude Code

CLAUDE.md

Project overview

Python monorepo managed with uv workspaces. The core framework lives in agents-core/ and plugins live in plugins/ (37+ packages). Python >= 3.10, 3.12 recommended.

Commands

All commands use uv. Never use python -m. If you run into dependency issues, stop and ask.

# Full check (ruff + mypy + unit tests)
uv run --no-sync dev.py check

# Unit tests only (--no-sync avoids uv panic in sandboxed environments)
uv run --no-sync pytest -m "not integration"

# Integration tests (needs .env secrets)
uv run --no-sync pytest -m "integration"

# Lint & format
uv run --no-sync ruff check .
uv run --no-sync ruff format .

# Type check
uv run --no-sync mypy

Testing

• Framework: pytest. Never mock.
• @pytest.mark.asyncio is not needed (asyncio_mode = auto).
• Integration tests use @pytest.mark.integration.
• NEVER adjust sys.path.
• Keep unit-tests for the class under the same test class. Do not spread them around different test classes. For example, tests for Agent must be inside TestAgent, etc.
• ALWAYS test behavior, not calling a path.
• Use pytest.fixture for test setup, not helper methods
• NEVER observe method calls in tests; assert on outputs and state.

Python rules

• Never use from __future__ import annotations.
• Prefer specific exceptions if they are known. If the exception type is not clear, it is ok to use except Exception as e.
• Avoid getattr, hasattr, delattr, setattr; prefer normal attribute access.
• Docstrings: Google style, keep them short.
• Do not use section comments like # -- some section --
• Prefer logger.exception() when logging an error with a traceback instead of logger.error("Error: {exc}")
• Do not use local imports, import at the top of the module
• Avoid # type: ignore comments.
• Avoid using Any type.
• When adding code to an existing file, follow the patterns already established in that file (e.g. error handling style, import guards, naming).

Code style