Skip to content

CLAUDE.md

Latest commit

 

History

History
134 lines (96 loc) · 5.42 KB

CLAUDE.md

File metadata and controls

134 lines (96 loc) · 5.42 KB
AGENT SAFEGUARDS (non-negotiable)

Operating principles

  1. Prefer clear code over comments.

    • Use comments only for: non-obvious reasoning, security invariants, protocol quirks, or “why” that code cannot express.
    • Prefer descriptive names, small functions, and explicit types over commentary.

  2. Solve root cause, not band-aids.

    • Do not add retries/timeouts/logging to hide failures unless the root cause is addressed or explicitly impossible to fix.
    • If a workaround is necessary, document the root cause and the exact reason it can’t be fixed now.

  3. Use idioms of the language and ecosystem.

    • Follow standard style guides, conventions, directory layout, and tooling.
    • Avoid clever patterns that fight the ecosystem. Prefer boring, maintainable solutions.

Quality gates 4) Tests must run after each modification.

  • After any functional change, run the relevant test suite locally (or in CI steps) and ensure it passes.
  • If tests cannot run (missing dependency, environment), add or update a runnable test harness or clearly state what is required.
  • Never leave the repo in a state where tests are known failing.

  1. Documentation for all features.

    • Every new feature must have usage docs + one runnable example.
    • Docs must include intent, flags/config, and failure modes.
    • Prefer docs that answer user questions (“How do I…”) and include copy/paste snippets.

  2. Update CHANGELOG with all changes.

    • Every user-visible change must be added to CHANGELOG.md under “Unreleased”.
    • Use categories: Added / Changed / Fixed / Security / Deprecated / Removed / Chores.
    • Mention migration steps if behavior changes.

Robustness & correctness 7) Include error handling everywhere it matters.

  • Never ignore errors; propagate with context.
  • Wrap/annotate errors so the caller has actionable info.
  • Ensure exit codes/return values are correct and consistent.
  1. Test edge cases and invariants.
    • Add tests for: empty inputs, invalid inputs, boundary values, timeouts, large payloads (reasonable), and concurrency/ordering if relevant.
    • Include at least one test for each bug fixed to prevent regressions.

Security & safety (important for agentic tooling) 9) No harmful actions by default.

  • Do not delete data, rotate secrets, publish releases, or mutate external systems unless explicitly requested.
  • Treat external calls (network, cloud APIs) as “dangerous”: require explicit opt-in via config/flags.
  1. Least privilege and safe defaults.
  • Minimize permissions, capabilities, scopes, and access tokens.
  • For Kubernetes artifacts: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation=false, drop ALL capabilities unless justified.
  1. No secret leakage.
  • Never print tokens, passwords, or full credential material to logs.
  • Redact known secret patterns; avoid echoing env vars that might contain secrets.
  1. Deterministic builds and reproducibility.
  • Prefer pinned versions, lockfiles, and deterministic packaging.
  • Avoid “download latest at build time” unless necessary.

Change management rules 13) Small, reviewable diffs.

  • Prefer incremental changes with clear commit boundaries.
  • If a refactor is needed, do it in a separate commit/PR before feature changes.
  1. Respect existing standards and tooling.
  • Use the repo's existing lint/format/test tools (Makefile/package scripts/cargo test/etc.).
  • If tooling is missing, add it in a minimal conventional way.
  1. Provide a “How to verify” section in PR descriptions/output.
  • Include exact commands: build, lint, unit tests, integration tests (if any).

Agent execution constraints (for local runners / GH actions) 16) Only modify files that are in-scope for the task.

  • Do not reformat unrelated files.
  • Do not introduce new dependencies unless justified.
  1. When uncertain, choose the safer option and make it explicit.
  • Prefer failing fast with actionable errors over silent fallback.
  • If ambiguity remains, implement a guardrail and document the decision.
  1. When really uncertain, ask for help.
  • Avoid making assumptions without asking for confirmation.
  1. When running locally, prefer the mcp edit tool to direct file edits.
  • If issues arise where files seem unedited, alert the user before continuing.
  1. Prefer bash commands/scripts to python3 when investigating.

Definition of implement issue

  • Find the issue in github issues.
  • If not found, inform the user.
  • If found:
    • Fetch from origin
    • Create a branch with the issue number in the name from origin/main.
    • Implement the issue.
    • Run all e2e tests.
    • If during implementation, obvious errors were found in the originating issue, also add a comment to the issue about the fix.
    • If running from Claude Code or Claude Desktop:
      • Do NOT create a PR automatically.
      • Instead, present a summary of changes and let the user decide when to create the PR.
    • Otherwise (e.g. GitHub Copilot, Junie, or other automated agents):
      • Create a PR with the issue number in the title.
      • Make sure the PR passes CI.

Definition of done

  • Code compiles without warnings.
  • Code is linted.
  • Code is formatted.
  • dprint check passes with no issues (Markdown, JSON, TOML, YAML, Dockerfile).
  • Tests pass.
  • Docs updated.
  • CHANGELOG updated.
  • Edge cases tested.
  • Security posture maintained.
  • Output includes a concise summary of changes + how to verify.
  • For rust code:
    • All unsafe code is annotated.
    • Use explicit lifetimes where necessary.
    • Use clippy lints.