Entorno de desarrollo

Todo lo de aquí está medido, con fecha. Si algo contradice tu expectativa, gana la medición; y si sospechas que ha caducado, vuelve a medirlo antes de fiarte.

Última verificación: 2026-08-21.

1 · Los comandos no se ejecutan tal como los escribes

El hook PreToolUse/Bash sustituye el ejecutable en posición de comando:

rg --version                 ->  grep (GNU grep) 3.12          (se ejecutó grep)
python3 -m pytest --version  ->  No module named rtk           (se ejecutó python3 -m rtk)
echo pytest                  ->  pytest                        (los argumentos NO se tocan)

Tres vías lo evitan, las tres verificadas:

Consecuencia dura: ningún oráculo se invoca por nombre suelto. Ver knowledge/MISTAKES.md · M-001.

2 · Python

Nunca pip install --break-system-packages ni pip3 install global. Receta:

~/.venvs/tools/bin/<tool> --version 2>/dev/null || (
  ~/.venvs/tools/bin/pip install <pkg> -q &&
  ln -sf ~/.venvs/tools/bin/<tool> ~/.local/bin/<tool>
)

Para un venv de proyecto: uv venv .venv --seed. Sin --seed no siembra pip, y después no se puede gestionar con nada que no sea uv.

3 · Node

node y npm vía nvm (node --version, npm --version). pnpm NO está en $PATH: existe solo como shim de corepack (~/.nvm/versions/node/<versión>/bin/pnpm). El directorio ~/.local/share/pnpm/bin está en $PATH pero vacío. Invócalo por ruta o vía corepack.

4 · Sistemas de ficheros

El cuello no es el ancho de banda: es la latencia por syscall de metadatos, y la caché apenas ayuda (una segunda pasada no mejora). Patrones patológicos: du, stat en bucle y recolección de pytest con imports pesados.

Los proyectos del usuario viven en /mnt/c/Users/…/Downloads/. Un venv en ext4 apuntando a código en /mnt/c es la combinación buena, y ya existe: ~/.venvs/riego.

5 · Los guards bloquean por literal, no por acción

Sentinel y los guards de kit/claude/hooks/ inspeccionan la cadena del comando. Escribir el nombre de un fichero de credenciales dispara [CRITICAL] sensitive path pattern aunque sea para excluirlo; rm -rf sobre un temporal propio también se bloquea.

Ante un bloqueo: reformula. Ampliar la allowlist convierte un sensor en decoración, y solo se hace con justificación escrita en knowledge/DECISIONS/.

Coste medido de la cadena completa de 7 hooks: 160 ms por comando Bash, idéntico en ext4 y en /mnt/c (los guards no ejecutan git status). El más lento es block-dangerous-commands.sh con 58 ms.

6 · Proxy Headroom — retirado (2026-10)

Medido: 0,2-0,6 % de ahorro real con latencia añadida; se retiró del kit con --with-headroom y sus tests (kit/docs/archive/03-headroom.md). No lo repongas ni uses headroom wrap: escribe ANTHROPIC_BASE_URL en el settings.local.json de cada proyecto. Si queda esa variable en algún sitio, quítala; kit/doctor.sh falla si enruta a un endpoint muerto o está en más de un fichero.

7 · Herramientas presentes y ausentes

Hay: gh 2.46.0 · gitleaks 8.30.1 · jq 1.8.1 · shellcheck 0.11.0 · rg 15.1.0 · git 2.53.0 · zip/unzip · uv · pre-commit.

No hay: bats, ruff, black, docker. → Los tests de este repo son bash puro, no introduzcas un framework nuevo.

sha256sum es uutils coreutils 0.8.0, no GNU. En macOS no existe: usa shasum -a 256. Todo script que valide checksums debe resolver ambos.