spectral: Instructions file for Claude Code

Spectral — Project Specification

Style preferences

• No code samples in documentation. Documentation files should describe concepts in prose and tables, not paste code. The code lives in the code.
• Import convention. All imports go at the top of the file (standard Python style). Internal CLI code (cli/…) is always imported at the top level — no lazy imports. Heavy external dependencies (e.g., mitmproxy, yaml, pydantic_ai) may be lazy-imported inside helper functions to keep spectral --help fast. Optional dependencies may use a lazy try/except with a user-friendly error. For mutable module-level state (e.g., _model in llm/_client.py), import the module at the top and access the attribute at call time to avoid stale references.
• Private function convention. Every module should clearly separate its public API from internal helpers. Prefix internal functions with _ (e.g. _build_timeline_text, _resolve_url). The public API of a module is the set of unprefixed functions and classes — only those should be imported by other packages. Tests may import private functions for unit testing, but production code in other packages should only depend on the public API.

Development environment

• Package manager is uv. Use uv run to execute commands (no need to activate the venv):
  • uv run pytest tests/ — run tests
  • uv run spectral mcp analyze ... — run the CLI
  • uv add <package> — add a dependency (updates pyproject.toml + uv.lock)
  • uv add --dev <package> — add a dev dependency
• The LLM provider and API key are resolved from stored config at ~/.local/share/spectral/config.json or created interactively on first use via spectral config. Supports Anthropic, OpenRouter, OpenAI, and Ollama. No .env file needed.
• Before finishing any code change, run the full verification suite and fix any new errors:
  • uv run pytest tests/ -x -q — all tests must pass
  • uv run ruff check — zero lint errors (use --fix for auto-fixable import sorting)
  • uv run pyright — zero new type errors (pre-existing errors in proxy.py, test_proxy.py are known)
• Shell completion scripts (cli/completions/spectral.bash and spectral.zsh) are static — they must be updated manually whenever a CLI command, subcommand, or option is added, removed, or renamed.
• Conventional Commits are mandatory. Every commit message must follow the format type(scope): description (e.g. fix:, feat:, chore:, docs:, refactor:, test:, ci:). This drives python-semantic-release: fix: bumps patch, feat: bumps minor, BREAKING CHANGE: bumps major. Use chore:/docs:/refactor:/test:/ci: for changes that should not trigger a release.