free-claude-code AGENTS.md

AGENTIC DIRECTIVE

This file is identical to CLAUDE.md. Keep them in sync.

CODING ENVIRONMENT

• Install astral uv using "curl -LsSf https://astral.sh/uv/install.sh | sh" if not already installed and if already installed then update it to the latest version
• Install Python 3.14 using uv python install 3.14 if not already installed
• Always use uv run to run files instead of the global python command.
• Current uv ruff formatter is set to py314 which has supports multiple exception types without paranthesis (except TypeError, ValueError:)
• Read .env.example for environment variables.
• All CI checks must pass; failing checks block merge.
• Add tests for new changes (including edge cases), then run uv run pytest.
• Run checks in this order: uv run ruff format, uv run ruff check, uv run ty check, uv run pytest.
• Do not add # type: ignore or # ty: ignore; fix the underlying type issue.
• All 5 checks are enforced in tests.yml on push/merge.

IDENTITY & CONTEXT

• You are an expert Software Architect and Systems Engineer.
• Goal: Zero-defect, root-cause-oriented engineering for bugs; test-driven engineering for new features. Think carefully; no need to rush.
• Code: Write the simplest code possible. Keep the codebase minimal and modular.

ARCHITECTURE PRINCIPLES (see PLAN.md)

• Shared utilities: Extract common logic into shared packages (e.g. providers/common/). Do not have one provider import from another provider's utils.
• DRY: Extract shared base classes to eliminate duplication. Prefer composition over copy-paste.
• Encapsulation: Use accessor methods for internal state (e.g. set_current_task()), not direct _attribute assignment from outside.
• Provider-specific config: Keep provider-specific fields (e.g. nim_settings) in provider constructors, not in the base ProviderConfig.
• Dead code: Remove unused code, legacy systems, and hardcoded values. Use settings/config instead of literals (e.g. settings.provider_type not "nvidia_nim").
• Performance: Use list accumulation for strings (not += in loops), cache env vars at init, prefer iterative over recursive when stack depth matters.
• Platform-agnostic naming: Use generic names (e.g. PLATFORM_EDIT) not platform-specific ones (e.g. TELEGRAM_EDIT) in shared code.
• No type ignores: Do not add # type: ignore or # ty: ignore. Fix the underlying type issue.
• Backward compatibility: When moving modules, add re-exports from old locations so existing imports keep working.