Skip to content

Latest commit

 

History

History
63 lines (44 loc) · 4.64 KB

CLAUDE.md

File metadata and controls

63 lines (44 loc) · 4.64 KB

Claude Code Guidelines for vitaminc

Principles

Vitamin C is a suite of crates for cryptography and handling sensitive data. These goals (from README.md) guide every design and code change. They describe where the project is heading, not what every crate does today: make each change move toward them, and check the code for the current state. When two goals conflict, call out the trade-off rather than silently picking one.

  • Misuse resistant: make the secure path the easy path. Prefer types and APIs that make insecure code hard to write or fail to compile.
  • Verified: back changes with tests, and with formal methods where practical. Prefer dependencies that are themselves verified.
  • Vetted: prefer dependencies that security experts have reviewed. Write code so it is easy for an expert to review.
  • Minimal: include only what is necessary, in both code and dependencies. Put optional functionality behind features.
  • Consistent: keep interfaces consistent across crates, so everything feels like one library reachable from the vitaminc facade.
  • Compatible: work toward support for embedded (no_std) and WASM targets. Keep the WASM builds that CI checks today passing, and keep core crates and traits-only feature sets free of threads, timers and native-only dependencies. No crate is no_std yet, and vendor adapters (AWS, Azure, GCP, Vault) and aead-napi are native-only by design. Discuss before removing std support to reach no_std.
  • Fast: speed and security can be friends. Keep performance in mind without trading away security.

Commits

  • Use conventional commit messages: feat:, fix:, refactor:, chore:, docs:, test:, perf:, ci:
  • Write commit subjects that describe the why, not just the what
  • Scope commits to the affected crate when possible (e.g. feat(aead): add streaming encryption support)
  • These messages feed into automated changelog generation via git-cliff, so clarity matters

Documentation

Use the repository-local rust-documentation skill for Rust documentation work. Follow the documentation conventions for this repository's checks, README links, and separation of user-facing docs from contributor workflows. Repository requirements take precedence over the skill's general guidance.

Dependency updates

Every third-party crate version in Cargo.lock must pass three gates in CI: cargo deny (advisories, yanked versions, sources, licences, build scripts; deny.toml), cargo vet (a recorded audit or exemption for every version; supply-chain/), and the tests. The Node addon and Go guest test harnesses have their own lockfiles and their own supply-chain/ stores, checked the same way with --manifest-path. A dependabot PR that fails 🔏 cargo vet needs the delta read and recorded; supply-chain/README.md has the steps and the review checklist.

  • First run cargo vet without --locked on the PR branch. If it passes and only imports.lock changed, commit that to the PR: a trusted registry already audited the version. Only an unaudited version needs the delta read.
  • Review the published crate (cargo vet diff), not the git tag; they can differ.
  • Crates the primitives are built on (aws-lc-rs, aes-gcm, chacha20, digest, getrandom, hmac, rand, sha2, subtle, zeroize) need crypto-reviewed as well as safe-to-deploy, and get a full read on every bump.
  • Do NOT add an exemption or an ignore entry to make a PR pass. Record an audit, or leave the PR open.
  • Commit the audit onto the dependency PR itself, next to the lockfile change; no separate PR and no rebase. who is the person who approves that PR, and the notes say what was read and against which upstream changes.

Releases

Releases are automated with release-plz. See RELEASING.md for the full process.

  • Do NOT manually edit CHANGELOG.md files on feature branches — release-plz manages them
  • Do NOT manually bump versions in Cargo.toml — release-plz handles this
  • All 19 crates release together as a single version group

Changelogs on release PRs

When working on a release PR (created by release-plz), you may be asked to rewrite the auto-generated changelog entries. Follow these guidelines:

  • Write entries from the user's perspective, not the developer's
  • Focus on what changed and why it matters, not implementation details
  • Group related commits into a single entry where it makes sense
  • Call out breaking changes prominently with a Breaking: prefix
  • Keep entries concise — one line per change is ideal

Reviewing pull requests

Follow the review guidelines in AGENTS.md, including its list of known non-findings:

@AGENTS.md