---
name: diretiva-preferencias-tecnicas
type: feedback
title: "Technical Preferences — Directives"
description: "Mandatory technical preferences. uv as package manager, PEP 723 for scripts, artifacts in outputs, available hardware."
tags: [uv, pep723, python, artifacts, hardware, gitflow]
timestamp: 2026-07-07
---

# Technical Preferences — Directives

Mandatory rules for all code, scripts, and artifacts produced.

## Package Manager: uv (ALWAYS)

- **NEVER** use `pip` directly
- **NEVER** use `python` or `python3` directly
- **ALWAYS** use `uv` as intermediary
- Run scripts: `uv run script.py`
- Install packages: `uv pip install` (or better, use pyproject.toml)
- Virtual envs: `uv venv` if needed

## Dependencies: pyproject.toml (NEVER requirements.txt)

- Every Python project uses `pyproject.toml`
- **NEVER** `requirements.txt`
- `uv` manages lockfiles automatically

## Self-Contained Scripts: PEP 723

When the situation demands something self-contained (no setup, no project, zero deps):

```python
# /// script
# dependencies = [
#     "numpy>=2.0",
# ]
# ///

"""
Script description.
Usage: uv run script.py [args]
"""

import sys
# ... code ...

if __name__ == "__main__":
    main()
```

- Inline metadata in the file header
- `uv resolve` automatically resolves dependencies
- `uv run script.py` runs without setup
- Zero external dependencies = empty array `[]`
- Reference example: `wikifita/scripts/wikifita_audit.py`

## Artifacts: Location

- **NEVER** create artifacts in the project folder unless the user explicitly requests it
- Use the session outputs directory as default
- If the user asks to save in a specific location, respect that
- Present artifacts via `present_files` after creation

## Available Hardware

| Device | Specs | Primary Usage |
|---|---|---|
| MacBook Pro M3 Pro | 24GB Unified VRAM, macOS | Development, MLX/Metal, local models |
| PC Windows (chicotv) | Ryzen 5 4500, RTX 2060 6GB, 16GB RAM | Frida tools, Android RE, quantized local models |
| PS3 Evilnat | Cell BE | Bare-metal inference (experimental) |

## macOS Environment

- Homebrew available
- `uv` installed via Homebrew or standalone
- Native Git
- Docker Desktop available

## Git: Mandatory Rules

- **Mandatory commits** after each significant change
- **NEVER** use `git commit --no-verify` (skips validation hooks)
- Semantic messages: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
- OKF frontmatter validated automatically by pre-commit hook
- Audit runs automatically via post-commit hook

## Golden Rule

If you are writing `pip install`, `python script.py`, or `requirements.txt` — **stop**. Use `uv`.