Skip to content

CLAUDE.md

Latest commit

 

History

History
62 lines (52 loc) · 2.4 KB

CLAUDE.md

File metadata and controls

62 lines (52 loc) · 2.4 KB
Raw

node_reqwest

Project

Rust-based Node.js native addon using neon bindings for HTTP client functionality (wrapping reqwest). Three packages (core, meta, node), each combining a Rust crate with TypeScript glue. Supply-chain verification on install uses the external node-addon-slsa dependency.

Commands

  • mise run check — full pre-commit: lint, format, build checks
  • mise run fix — auto-fix lint and format issues
  • mise run test — run all tests
  • mise run build — build all packages

Guiding Principles

  1. Tooling over documentation — if a rule can be enforced by a tool (clippy, oxlint, ruff), configure the tool. Don't document what tooling already enforces.
  2. Lean instructions — CLAUDE.md captures conventions that require judgment; mechanical checks belong in config files.
  3. Config consistency — CLAUDE.md and agent prompts (.claude/agents/) must stay in sync.
  4. Hooks for guardrails — the Stop hook in .claude/settings.json runs mise run fix after every coding task, which both auto-formats and runs the same linters as mise run check.

Dependency Management

  • Prefer updating over overriding — when a transitive dependency has a vulnerability, update the parent dependency first. Only add overrides as a last resort.
  • Respect cooldown periods — Python uses exclude-newer = "1 day" (pyproject.toml) and pnpm uses minimumReleaseAge: 1440 minutes (pnpm-workspace.yaml). Never pin to a version published less than 1 day ago.
  • Exact pins in pnpm catalog — all entries in pnpm-workspace.yaml's catalog: section use exact versions (no ^). This prevents version drift from semver ranges.
  • Verify CLI compatibility after upgrades — tool upgrades can change CLI flags (e.g. pyrefly dropped --all). After bumping a tool version, verify that all mise tasks using it still work.

Code Conventions

  • License header on all source files: // SPDX-License-Identifier: Apache-2.0 OR MIT
  • Use node: prefix for Node.js built-in imports: import process from "node:process".
  • Scripts in scripts/ must use the helper patterns from scripts/helpers/ (runCommand, runScript).
  • Follow existing script patterns (see setup-postinstall.ts as reference).
  • Markdown lines must not exceed 100 characters (enforced by markdownlint MD013).