Imported from zaffnet/qareen (
AGENTS.md). Install upstream withnpx skills add zaffnet/qareen. Copyright stays with the author.
Setup
Run uv sync --all-extras to install dependencies.
Dependency Management
pyproject.tomlis the source of truth. Edit it directly, then runuv sync. Never useuv pip installorpip install.
Running Python
After activating the virtual environment (source .venv/bin/activate), use python or python3 to execute scripts. Project scripts use python3 for explicit version specification.
Rules
All rules are present inside @.cursor/rules/ and are meant to be read before you start a task. You should abide by the rules at all times.
Architecture Patterns
Pydantic-first: use Pydantic models for all data structures, configs, schemas. Use ABC pattern for extensible components (see qareen/dataset/base.py, qareen/indexing/base.py). Follow module structure: dataset/, indexing/, config/. Implement vector store backends against the interfaces defined in qareen/indexing.
Code Style
- Type hints required on all functions and methods you modify or add.
- Docstrings required on all classes and public methods.
- Line length: 100 characters.
- Must pass ruff and mypy.
- Commits: Conventional Commits format.
- Comments: Write comments ONLY when absolutely necessary. Your code should be self-documenting. Never comment "WHAT" code does. Only comment "WHY" and that only when diverging from convention or when rationale might be unclear. Avoid verbose comments.
Communication & Code: Minimalism Required
Rules:
- Code First — Minimal Explanations - No preambles, explanations, or narration
- Edit, don't create - Always prefer editing existing files over creating new ones
- One task = one change - Don't add features that weren't requested
- No obvious comments - Code should be self-documenting
- No helper files - No utils.py, helpers.py, or "temporary" scripts unless explicitly asked
Anti-patterns:
- ❌ Creating new files when editing would work
- ❌ Adding logging/error handling that wasn't requested
- ❌ Creating unrelated documentation files proactively (documentation within PR scope or requested maintenance is allowed; e.g., updating setup instructions for new dependencies or adding brief README notes for a shipped feature is allowed; creating detailed API reference or full CONTRIBUTING.md proactively is not)
- ❌ Writing test helpers or fixtures that weren't needed
- ❌ Refactoring code that works and wasn't mentioned
- ❌ Adding type hints to files you didn't touch
- ❌ "Improving" variable names in passing
Speaking rules:
- Errors: state problem + fix concisely; include enough context to reproduce (logs, steps, inputs) when relevant
- Clarifications: ask question directly; brief context or examples are permitted to aid understanding
- Completion: "✅ [what was done]" with 1–3 sentences; optional note about caveats or next steps for handoff
⚠️ CRITICAL: Pre-commit Checks - REQUIRED BEFORE COMPLETION
Before declaring work complete, you MUST:
- Run:
uv run pre-commit run --all-files - If ANY hooks fail: fix issues and re-run step 1
- Repeat until ALL hooks show "Passed"
- Explicitly state: "✅ Ran
uv run pre-commit run --all-files- ALL HOOKS PASSED"
Note: Never assume checks pass. Always run and confirm. CI/CD will reject PRs if this fails.
Troubleshooting non-code hook failures: If hooks fail due to environment/tooling (not code issues), check:
- pre-commit version:
pre-commit --version - Python/node versions match requirements
- Virtual environment is active:
which pythonshould show.venv/bin/python - PATH includes required tools
- Run
uv sync --all-extrasto ensure all dependencies installed For detailed setup help, see CONTRIBUTING.md or project setup docs.
