English · Español

Dev environment — IDE, plugins, CLI, Claude Code customization¶

🇪🇸 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 The principle¶

The IDE, the commit hooks, and CI must run the same rules. If your IDE accepts a snippet that pre-commit rejects, you waste time. If pre-commit accepts a snippet that CI rejects, you waste more time. Three layers, one rule set.

§1 OS, shell, Python¶

OS: Fedora 43 (Linux 6.19). Every recipe in this curriculum runs on Linux. Anything Windows-specific in linked references — translate before using.
Shell: fish (Borja's default). Justfile recipes are POSIX-compatible (run via sh); only the interactive shell is fish.
Python: 3.11.x, pinned by .python-version (read by uv).

Install Python and dev libs:

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

Install uv (the package manager):

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

Verify:

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

§2 IDE — VS Code (Microsoft's open-source Python tooling) or Cursor¶

Either works. They share the same extension model. Pick one and stick with it for the project; switching mid-phase costs time.

§2.1 Required extensions¶

Extension	Why
Python (Microsoft)	Language server, debugger
Pylance	Type-aware completion + reveals mypy diagnostics inline
Ruff (Astral)	Inline lint + format; uses `pyproject.toml` config (no drift from pre-commit)
Mypy Type Checker (Microsoft)	Inline `mypy --strict` diagnostics; same config as pre-commit
Even Better TOML	`pyproject.toml` validation
YAML (Red Hat)	`.pre-commit-config.yaml`, CI config
GitLens	Surface git history inline — non-trivial for tracing curriculum decisions
GitHub Actions (GitHub)	CI workflow editing
Markdown All in One	Theory files are markdown-heavy
Mermaid Preview	Diagrams in `docs/phase-NN-*/diagrams/`
Jupyter (Microsoft)	Notebook editing — but commit only stripped outputs

Note: "Microsoft" here refers to the publisher of the VS Code extension (open source, MIT). The OS is Fedora.

§2.2 Workspace settings¶

In .vscode/settings.json (per-user, not committed; the dir is in .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/ is gitignored at repo level — your editor settings stay yours, and we don't end up bikeshedding them.

§2.3 Cursor specifics¶

Cursor is a fork of VS Code — extensions and settings transfer. Cursor's AI features are additional and complementary to Claude Code, not a replacement: - Cursor's inline AI: fast tab-completion, "explain this function", small edits. - Claude Code: project-wide reasoning, multi-file edits, slash commands, subagents, hooks, governed by CLAUDE.md.

If both run side by side, govern Cursor's inline use with a .cursorrules file mirroring CLAUDE.md §0 — otherwise Cursor will happily write the verb-grammar-scope expansion that Claude Code refuses.

§3 CLI tooling¶

Tool	Use
`just`	The task runner — `just setup`, `just lint`, `just test`, etc.
`uv`	The package manager — `uv sync`, `uv run <cmd>`, `uv add`, `uv lock`.
`gh`	GitHub CLI — PRs, CI runs, issues. Pre-configured (per `~/.gitconfig`).
`pre-commit`	Wired by `just setup`.
`mkdocs`	Browse the curriculum as a site (`just docs-serve`).
`nvtop` / `intel_gpu_top`	GPU/iGPU live monitoring (Phase 4+ when we start producing artifacts).
`tokei`	Line counts; useful for reporting in `PHASE_NN_REPORT.md`.
`jq`	JSON inspection of manifests.
`httpie` (optional)	API testing once we're in Phase 31+ (MCP).

§4 Claude Code customization¶

Three files define Claude Code's behavior in this repo:

§4.1 `CLAUDE.md`¶

Auto-loaded on every session. Encodes the hard rules: verb-grammar scope (per LYNX_CORTEX_ADDENDUM.md §A13), Borja writes the code, per-phase ritual, build-before-abstract, reproducibility-mandatory, bilingual policy, spec-immutability. The contract.

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

§4.2 `.claude/settings.json`¶

Three top-level concerns:

Permissions allowlist (allow) — bash commands Claude can run without prompting (just *, uv *, pytest *, git status, etc.). Read-only and safe commands.
Permissions ask — commands that prompt (git commit *, git push *, gh repo create *, rm *, mv *). Anything mutating remote state, anything destructive.
Hooks — Stop hook reminds Claude to append to today's journal at session end.

A .claude/local.settings.json (gitignored) can override per-machine.

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

Six project-specific slash commands:

Command	Purpose
`/phase-start NN`	Open a phase: re-read spec, write `PHASE_NN_PLAN.md`, stop for approval
`/phase-checkpoint`	Mid-phase health check — no fixes, status only
`/phase-report`	Close a phase: verify DoD, take measurements, write `PHASE_NN_REPORT.md`
`/derive <topic>`	Long-form derivation into `docs/phase-NN-*/theory/`
`/break <concept>`	Introduce an instructive single bug for debugging practice
`/quiz NN`	Socratic quiz; graded; blocks `/phase-report` if score < 70%

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

Four specialized subagents:

Agent	Role
`math-reviewer`	Reviews derivations for correctness, conventions, missing steps
`numerical-stability-checker`	Reviews training code for NaN sources, non-determinism, missing seed plumbing
`phase-gatekeeper`	Enforces DoD honestly at phase close — adversarial
`journal-summarizer`	Distills journal entries into the reflection section

Invoked via the Agent tool in a session, or directly by /phase-report.

§5 Browsing the curriculum — `mkdocs`¶

mkdocs.yml configures a static site built from docs/. Theme: material. Plugins: search, mermaid, code highlighting.

just docs-serve     # http://127.0.0.1:8000, hot-reload
just docs           # build static site to site/

Reading the curriculum as a site (left-nav, search, syntax highlighting) is sometimes more comfortable than reading raw markdown. Optional but recommended.

§6 Exercises (solutions in `solutions/`)¶

(None for this chapter — the lab files cover the practical setup.)

§7 Pitfalls¶

Letting the IDE auto-format on save without ruff format config alignment: produces churn-only commits where lines get reflowed differently from CI.
Pinning mypy in the IDE to a different version than pyproject.toml: errors appear/disappear depending on which mypy ran.
Skipping pre-commit install: hooks defined but never run. just setup runs pre-commit install to prevent this.
Editing .claude/settings.json to mass-allow Bash(*) so prompts stop interrupting. Bad. The prompts are the seatbelt.

§8 Read next¶

→ ../lab/00-env-checklist.md — verify the environment as described above is actually present.