English · Español

Entorno de desarrollo — IDE, plugins, CLI, personalización de Claude Code¶

Resumen. El entorno de desarrollo no es opcional: CLAUDE.md y .claude/ hacen que cada sesión de Claude Code conozca las reglas del proyecto; el IDE (VS Code o Cursor en Fedora) corre los mismos linters que pre-commit y CI. Si los tres no coinciden, los errores se filtran.

§0 El principio¶

El IDE, los hooks de commit y CI deben correr las mismas reglas. Si tu IDE acepta un fragmento que pre-commit rechaza, pierdes tiempo. Si pre-commit acepta un fragmento que CI rechaza, pierdes más tiempo. Tres capas, un set de reglas.

§1 OS, shell, Python¶

OS: Fedora 43 (Linux 6.19). Cada receta de este currículo corre en Linux. Cualquier cosa específica de Windows en referencias enlazadas — tradúcela antes de usarla.
Shell: fish (default de Borja). Las recetas del Justfile son POSIX-compatibles (se corren vía sh); solo el shell interactivo es fish.
Python: 3.11.x, fijado por .python-version (leído por uv).

Instala Python y librerías de desarrollo:

sudo dnf install -y python3.11 python3.11-devel python3.11-pip \
                    git just fish \
                    gcc-c++ make cmake \
                    graphviz graphviz-devel \
                    libffi-devel openssl-devel

Instala uv (el gestor de paquetes):

curl -LsSf https://astral.sh/uv/install.sh | sh

Verifica:

uv --version    # esperado: uv 0.4.x
python --version
just --version

§2 IDE — VS Code (tooling Python open source de Microsoft) o Cursor¶

Cualquiera vale. Comparten el mismo modelo de extensiones. Elige uno y mantente con él para el proyecto; cambiar a mitad de fase cuesta tiempo.

§2.1 Extensiones requeridas¶

Extensión	Por qué
Python (Microsoft)	Language server, debugger
Pylance	Completado consciente de tipos + diagnostics inline de mypy
Ruff (Astral)	Lint + format inline; usa la config de `pyproject.toml` (sin drift respecto a pre-commit)
Mypy Type Checker (Microsoft)	Diagnostics inline de `mypy --strict`; misma config que pre-commit
Even Better TOML	Validación de `pyproject.toml`
YAML (Red Hat)	`.pre-commit-config.yaml`, config de CI
GitLens	Saca el historial de git inline — no trivial para trazar decisiones del currículo
GitHub Actions (GitHub)	Edición de workflows de CI
Markdown All in One	Los archivos de teoría son markdown-heavy
Mermaid Preview	Diagramas en `docs/phase-NN-*/diagrams/`
Jupyter (Microsoft)	Edición de notebooks — pero commitea solo outputs eliminados

Nota: "Microsoft" aquí se refiere al publisher de la extensión de VS Code (open source, MIT). El OS es Fedora.

§2.2 Workspace settings¶

En .vscode/settings.json (por usuario, no commiteado; el dir está en .gitignore):

{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.terminal.activateEnvironment": true,
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"],
  "ruff.organizeImports": true,
  "ruff.lint.run": "onType",
  "mypy-type-checker.args": ["--config-file=pyproject.toml"],
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": { "source.fixAll": "explicit" }
  },
  "files.exclude": {
    "**/__pycache__": true,
    "**/.pytest_cache": true,
    "**/.mypy_cache": true,
    "**/.ruff_cache": true
  }
}

.vscode/ está gitignored a nivel de repo — tus settings de editor siguen siendo tuyos, y no acabamos discutiéndolos.

§2.3 Particularidades de Cursor¶

Cursor es un fork de VS Code — extensiones y settings se transfieren. Las features de IA de Cursor son adicionales y complementarias a Claude Code, no un reemplazo: - IA inline de Cursor: tab-completion rápido, "explica esta función", ediciones pequeñas. - Claude Code: razonamiento a nivel de proyecto, ediciones multi-archivo, slash commands, subagentes, hooks, gobernado por CLAUDE.md.

Si ambos corren en paralelo, gobierna el uso inline de Cursor con un archivo .cursorrules que espeje CLAUDE.md §0 — si no, Cursor escribirá felizmente la expansión de scope de gramática verbal que Claude Code rechaza.

§3 Tooling de CLI¶

Herramienta	Uso
`just`	El task runner — `just setup`, `just lint`, `just test`, etc.
`uv`	El gestor de paquetes — `uv sync`, `uv run <cmd>`, `uv add`, `uv lock`.
`gh`	GitHub CLI — PRs, ejecuciones de CI, issues. Preconfigurado (según `~/.gitconfig`).
`pre-commit`	Conectado por `just setup`.
`mkdocs`	Navega el currículo como sitio (`just docs-serve`).
`nvtop` / `intel_gpu_top`	Monitoreo en vivo de GPU/iGPU (Fase 4+ cuando empecemos a producir artefactos).
`tokei`	Conteo de líneas; útil para informes en `PHASE_NN_REPORT.md`.
`jq`	Inspección de JSON en manifiestos.
`httpie` (opcional)	Tests de API una vez en Fase 31+ (MCP).

§4 Personalización de Claude Code¶

Tres archivos definen el comportamiento de Claude Code en este repo:

§4.1 `CLAUDE.md`¶

Cargado automáticamente en cada sesión. Codifica las reglas duras: scope de gramática verbal (según LYNX_CORTEX_ADDENDUM.md §A13), Borja escribe el código, ritual por fase, construir-antes-de-abstraer, reproducibilidad obligatoria, política bilingüe, inmutabilidad del spec. El contrato.

CLAUDE.md se carga automáticamente al iniciar Claude Code en este repo. Codifica las reglas duras del proyecto.

§4.2 `.claude/settings.json`¶

Tres preocupaciones de nivel superior:

Allowlist de permisos (allow) — comandos bash que Claude puede correr sin pedir permiso (just *, uv *, pytest *, git status, etc.). Comandos de solo lectura y seguros.
Pedir permisos — comandos que piden confirmación (git commit *, git push *, gh repo create *, rm *, mv *). Cualquier cosa que mute estado remoto, cualquier cosa destructiva.
Hooks — el hook Stop recuerda a Claude que añada al diario de hoy al final de la sesión.

Un .claude/local.settings.json (gitignored) puede sobreescribir por máquina.

§4.3 `.claude/commands/*.md`¶

Seis slash commands específicos del proyecto:

Comando	Propósito
`/phase-start NN`	Abrir una fase: releer spec, escribir `PHASE_NN_PLAN.md`, parar para aprobación
`/phase-checkpoint`	Chequeo de salud a mitad de fase — sin arreglos, solo estado
`/phase-report`	Cerrar una fase: verificar DoD, tomar medidas, escribir `PHASE_NN_REPORT.md`
`/derive <topic>`	Derivación larga en `docs/phase-NN-*/theory/`
`/break <concept>`	Introducir un único bug instructivo para práctica de debugging
`/quiz NN`	Quiz socrático; calificado; bloquea `/phase-report` si la nota < 70%

§4.4 `.claude/agents/*.md`¶

Cuatro subagentes especializados:

Agente	Rol
`math-reviewer`	Revisa derivaciones por corrección, convenciones, pasos faltantes
`numerical-stability-checker`	Revisa código de entrenamiento por fuentes de NaN, no-determinismo, plumbing de seed faltante
`phase-gatekeeper`	Hace cumplir el DoD honestamente al cierre de fase — adversarial
`journal-summarizer`	Destila entradas de diario en la sección de reflexión

Se invocan vía la tool Agent en una sesión, o directamente por /phase-report.

§5 Navegar el currículo — `mkdocs`¶

mkdocs.yml configura un sitio estático construido desde docs/. Tema: material. Plugins: search, mermaid, resaltado de código.

just docs-serve     # http://127.0.0.1:8000, hot-reload
just docs           # construye sitio estático en site/

Leer el currículo como sitio (nav izquierda, búsqueda, syntax highlighting) a veces es más cómodo que leer markdown crudo. Opcional pero recomendado.

§6 Ejercicios (soluciones en `solutions/`)¶

(Ninguno para este capítulo — los archivos de lab cubren el setup práctico.)

§7 Escollos¶

Dejar al IDE auto-formatear al guardar sin alinear con la config de ruff format: produce commits de solo-churn donde las líneas se re-fluyen distinto que CI.
Fijar mypy en el IDE a una versión distinta a pyproject.toml: los errores aparecen/desaparecen según qué mypy corrió.
Saltarse pre-commit install: hooks definidos pero nunca corren. just setup corre pre-commit install para prevenirlo.
Editar .claude/settings.json para mass-permitir Bash(*) y que los prompts dejen de interrumpir. Mal. Los prompts son el cinturón de seguridad.

§8 Siguiente lectura¶

→ ../lab/00-env-checklist.md — verifica que el entorno descrito arriba está realmente presente.