Skip to main content

Team rules

Auto-generated. Do not edit by hand. Run pnpm capabilities or commit a rule change — scripts/build-capability-index.mjs regenerates this from .claude/rules/team/.

Team rules are conventions the whole team follows. A rule starts as a personal insight, is proposed via /share-rule (propose-team-rule), and once accepted applies in every session through @-imports in CLAUDE.md. Click a rule for its full text — the why, how to apply, and examples.

Accepted — in effect​

  • agent-drivable-cli — Every interactive CLI command must also have a non-interactive, machine-readable path (flags + --json) so an AI agent can drive it and read the result — not only a human at a TTY. (proposed by relbns, from sandbox)
  • artifact-language-english — User conversation may be Hebrew or English — match the user's language in chat. All written artifacts (docs, memory, GitHub, code comments, commit messages, Slack, ClickUp through tools) must be English only. (proposed by relbns, from bewith-docs)
  • confirm-before-acting — In any non-yolo flow, state a self-derived choice + rationale and wait for explicit approval before acting on it. (proposed by relbns, from bewith-docs)
  • explain-then-propose-fix — When the developer asks you to explain a problem, explain it then proactively propose a fix; on approval, present an implementation plan and get explicit approval before writing any code. (proposed by relbns, from bewith-docs)
  • inline-comments-critical-only — Keep inline code comments only when critical — non-obvious WHY, complex logic, or an approach that was already tried and failed. Move design rationale and history to the PR description or commit message body. (proposed by relbns, from leaders-app)
  • never-merge-without-approval — Claude must never merge a PR or branch silently. At the very least the developer must be AWARE of every merge Claude runs — surface which PR into which branch and get their go-ahead. A general "proceed"/"continue"/"ship it" about a task is not awareness of a specific merge. (proposed by relbns, from leaders-app)
  • never-offer-admin-merge — Claude must never proactively offer gh pr merge --admin (the branch-protection override). Report a blocked merge and leave the PR to a human; run --admin only if a developer explicitly instructs it. (proposed by relbns, from bewith-docs)
  • prefer-dedicated-tools-over-bash — Prefer dedicated tools over raw Bash — Read/Grep/Glob to read files, the sandbox infra-MCP query+write tools for DB/cache work — instead of cat/grep/find or raw mysql/psql/mongo/mongosh/redis-cli. (proposed by relbns, from bewith-docs)
  • session-completion-signal — When a session's planned work is done, tell the developer automatically (so they can close without losing context); proactively suggest a session handoff when context is long/stale or the next task is separable, and offer to draft a handoff prompt. (proposed by relbns, from bewith-docs)

Proposed — under discussion​

  • cache-key-by-viewer-permissions — A shared response cache on a permission-dependent endpoint must be keyed per viewer, or it serves one caller's data to another. (proposed by relbns, from backend-services)
  • concise-human-read-text — AI-authored text a human reads (PR bodies, commit bodies, ClickUp/Slack comments, review notes, reports) must be concise and lead with the point. (proposed by relbns, from backend-services)
  • dont-mute-deprecation-warnings — A deprecation warning that says a behaviour "will be ignored in a future version" is a scheduled failure — fix the cause, never silence the warning. (proposed by relbns, from backend-services)
  • dry-run-exercises-real-path — A dry-run must exercise or validate the same write / external-call path it claims to check, or explicitly log what it skips. (proposed by relbns, from migrations-tool)
  • force-run-cannot-recreate-deleted-events — Deleting an imported event only closes it, and the importer skips closed resources before it checks forceUpdate, so Force Run can never recreate a deleted event (proposed by relbns, from backend-services)
  • integration-spec-ids-are-staging — Integration spec JSONs carry staging org/community/leader IDs; prod wiring must use the prod IDs, never the spec's. (proposed by relbns, from backend-services)
  • jmespath-mapping-guards — A JMESPath cond && null || X guard never fires; put the nullable branch last, wrap when mixing pipes, and validate every mapping expression against the values live in prod. (proposed by relbns, from backend-services)
  • no-json-stringify-deep-equality — Never compare objects with JSON.stringify - its array second argument is a recursive property allowlist, not a key sort, so nested fields silently drop out of the comparison. (proposed by relbns, from migrations-tool)
  • no-network-in-shell-profile — Never make network calls at shell-profile top level — Claude Code initializes a shell from the profile on every Bash tool call, so the cost is paid hundreds of times a day and is invisible in the transcript. (proposed by relbns, from backend-services)
  • reusable-workflow-dynamic-matrix — Never drive a reusable-workflow (uses:) call from a matrix computed at runtime — it startup_fails the whole workflow; dispatch the target workflow instead. (proposed by relbns, from leaders-app)
  • shared-hooks-are-opt-in — A hook shipped in the shared plugin defaults to off — it may offer itself, but it may not switch itself on for the whole team. (proposed by relbns, from bewith-docs)
  • ssr-language-must-come-from-the-request — A server-rendered page must resolve the user's language from the request, and the default language and default direction must be configured together — otherwise the server and the client render different directions and React discards the entire server tree. (proposed by relbns, from organization-dashboard)
  • stacked-pr-review-skipped — A PR whose base is a feature branch is never reviewed by CodeRabbit — it reports "Review skipped" while its check still shows a green pass. Merge the bottom PR and retarget to master before treating a stacked PR as reviewed. (proposed by relbns, from leaders-app)
  • test-at-the-layer-where-logic-runs — Data-layer logic — a MongoDB aggregation or query, a write / update / bulkWrite, a TypeORM repository or raw SQL query on Aurora-MySQL, a DB transaction — must be covered by an integration test against the real engine. A DB-mocking unit test proves only the wiring, and on a write path it cannot tell you the engine would reject the call at all. (proposed by relbns, from backend-services)
  • time-dependent-test-fixtures — A test fixture timestamp that the code under test compares against the current time must be relative to now or paired with a pinned clock, never a hardcoded absolute instant. (proposed by relbns, from backend-services)
  • typed-plugin-callbacks-device-verified — Type every callback parameter a plugin hands you, and exercise plugin and camera callback paths on a physical device before merge. (proposed by relbns, from leaders-app)
  • unblocking-automode-classifier — When auto mode's classifier blocks a command, the fix is a scoped prose entry in autoMode.allow — not another permissions.allow rule, which a compound command will not match anyway. (proposed by relbns, from leaders-app)
  • verify-client-rendered-output — A green build does not verify output that is produced in the browser — load the page and assert the thing rendered (proposed by relbns, from bewith-docs)
  • verify-environment-before-defect — Prove the local dependency tree matches the branch before calling a missing symbol or type error a defect — worktrees share the main checkout's node_modules, which drifts silently. (proposed by relbns, from backend-services)