|
| 1 | +# Contributing Claude Context to This Repo |
| 2 | + |
| 3 | +Every time you catch Claude making the same mistake twice, explain the same convention in chat, or hand a teammate a mental map they didn't have — that's knowledge worth encoding. This guide covers what belongs in this repo's `.claude/`, where to put it, and how to land it alongside the code it describes. |
| 4 | + |
| 5 | +## When to contribute here vs. elsewhere |
| 6 | + |
| 7 | +Ask: **is this knowledge specific to this codebase, or generic enough to work across repos?** |
| 8 | + |
| 9 | +- **Specific to this codebase** → contribute here, in `.claude/`. |
| 10 | + Example: "how we add a new cipher type," "how our feature-flag system works." |
| 11 | +- **Generic, reusable across repos** → [`bitwarden/ai-plugins`](https://github.com/bitwarden/ai-plugins) — persona plugins (e.g., a code-review agent), tool integrations, or shared utilities. |
| 12 | + |
| 13 | +When unsure, keep it here. Promoting up to `ai-plugins` later is easier than pulling it back — see its [CONTRIBUTING.md](https://github.com/bitwarden/ai-plugins/blob/main/CONTRIBUTING.md) when you're ready. |
| 14 | + |
| 15 | +## Choose scope, then shape |
| 16 | + |
| 17 | +### 1. Scope — where does it apply? |
| 18 | + |
| 19 | +This is a monorepo. Claude loads every `CLAUDE.md` and `CLAUDE.local.md` by [walking up from the working directory](https://code.claude.com/docs/en/memory#how-claude-md-files-load) — looking in each ancestor directly, not in a nested `.claude/` subdirectory. Files below the working directory (including nested `.claude/skills/`) are loaded lazily when Claude reads into that subtree. Use that hierarchy: |
| 20 | + |
| 21 | +- **Applies everywhere in this repo** → root `CLAUDE.md` or `.claude/skills/` |
| 22 | +- **Applies only within one app, library, utility, or subtree** → nested `CLAUDE.md` or `.claude/skills/` in that directory |
| 23 | + |
| 24 | +Push rules as deep as they'll go — keeping app-specific rules local saves context for everyone else's sessions, not just yours. |
| 25 | + |
| 26 | +For rules that should apply only to certain file types (e.g., all `*Controller.cs` files), use [`.claude/rules/<name>.md` with a `paths:` frontmatter glob](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/) instead of a nested `CLAUDE.md`. |
| 27 | + |
| 28 | +### 2. Shape — how should Claude use it? |
| 29 | + |
| 30 | +| You want to… | Use | |
| 31 | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | |
| 32 | +| State a rule Claude must always follow in its scope | `CLAUDE.md` | |
| 33 | +| State a rule that applies only to certain file globs | `.claude/rules/<name>.md` with `paths:` frontmatter | |
| 34 | +| Teach a procedure Claude invokes on demand | `.claude/skills/<name>/SKILL.md` | |
| 35 | +| Give Claude a specialized subagent with its own context | `.claude/agents/<name>.md` (YAML frontmatter; `name` + `description` required) | |
| 36 | +| Add a user-invocable slash command | `.claude/commands/<name>.md` | |
| 37 | +| Trigger a shell script on a Claude Code event | _We have them, but no strict project enforcement yet — register yours in `settings.local.json`._ | |
| 38 | + |
| 39 | +Rule of thumb: **if Claude only needs it sometimes, it's a skill.** Once a `CLAUDE.md` loads, it stays in context for the rest of the session — keep each one lean, especially the root. |
| 40 | + |
| 41 | +## Security conventions |
| 42 | + |
| 43 | +Skills and agents that touch vault data, authentication, or cryptography must use Bitwarden's [Core Vocabulary](https://contributing.bitwarden.com/architecture/security/definitions) (Vault Data, Protected Data, Secure Channel, etc.) and re-state the zero-knowledge invariant inline. **Subagents run in a fresh context** and do not inherit this repo's `CLAUDE.md` — include the relevant definitions directly in the agent's system prompt. |
| 44 | + |
| 45 | +## What good contributions look like |
| 46 | + |
| 47 | +- **Grounded in the code.** Real files, real patterns, real commands. |
| 48 | + If it could apply to any repo, it belongs in `ai-plugins`. |
| 49 | +- **Describes the "what" and "why," not the "who."** |
| 50 | + Avoid team-persona framing. Describe the domain and its constraints; the team is an implementation detail. |
| 51 | +- **Short and specific.** |
| 52 | + 2,000 words of general advice isn't a skill. |
| 53 | +- **Active voice, direct language.** |
| 54 | + "Invoke this skill when..." — not "This skill may be invoked when..." |
| 55 | +- **Reviewed like code.** |
| 56 | + Teams of domain experts own `.claude/` in their areas — they're the ones shaping how Claude behaves for everyone who works there, so treat changes with the same seriousness as source. |
| 57 | + |
| 58 | +## Anti-patterns |
| 59 | + |
| 60 | +- **Team-persona agents** ("Team ABC engineer"). |
| 61 | + If a team's process is unique enough to warrant a persona, that's an SDLC signal to address, not a persona to encode. |
| 62 | +- **Root-level rules that only matter in one subtree.** |
| 63 | + If it applies to `util/Seeder` only, put it in `util/Seeder/CLAUDE.md`. |
| 64 | +- **Duplicating `ai-plugins` content.** |
| 65 | + Check existing plugin skills before writing a new one. |
| 66 | +- **Generic advice disguised as repo-local knowledge.** |
| 67 | + "Write good tests" isn't repo-specific. |
| 68 | + "Our integration tests must hit a real database because…" is. |
| 69 | + |
| 70 | +## Building a contribution |
| 71 | + |
| 72 | +The Claude Code ecosystem moves fast — last session's habits may already be out of date. Here's the workflow we follow. |
| 73 | + |
| 74 | +### 1. Start with the canonical docs |
| 75 | + |
| 76 | +A quick refresh before you begin goes a long way — the rules shift more often than you'd think: |
| 77 | + |
| 78 | +- [How Claude Code Works](https://code.claude.com/docs/en/how-claude-code-works) — the mental model. |
| 79 | +- [Best Practices for Claude Code](https://code.claude.com/docs/en/best-practices) — what Anthropic recommends. |
| 80 | +- [Extend Claude Code](https://code.claude.com/docs/en/features-overview) — what you can build (skills, agents, commands, hooks). |
| 81 | +- [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) - a must read for skill building |
| 82 | + |
| 83 | +### 2. Survey the landscape |
| 84 | + |
| 85 | +A quick skim of both goes a long way: |
| 86 | + |
| 87 | +- This repo's [`.claude/`](.) tree. |
| 88 | +- [`bitwarden/ai-plugins`](https://github.com/bitwarden/ai-plugins). |
| 89 | + |
| 90 | +Try to match the voice you see. "Invoke when the user asks to X" — not "This skill may be invoked when X." Direct, active, specific. Your contribution should read like the neighbors. |
| 91 | + |
| 92 | +### 3. Build iteratively |
| 93 | + |
| 94 | +When you're authoring a skill, start with `/skill-creator:skill-creator`. It runs an iterative loop — draft → test against evals → review outputs → refine — with benchmark stats and a side-by-side reviewer. You end up with a skill that's been exercised against concrete inputs before you open the PR. |
| 95 | + |
| 96 | +For agents, commands, hooks, and `CLAUDE.md` entries, start from an existing one in the repo and adapt it. No need to invent a new structure when a neighbor already solves the shape problem. |
| 97 | + |
| 98 | +### 4. Validate before you push |
| 99 | + |
| 100 | +- Run a local Bitwarden Claude Code review with `/bitwarden-code-review:code-review-local` — it writes findings to files so you can fix them before pushing, without posting anything to GitHub. |
| 101 | +- When you raise the PR, apply the `ai-review` label. Our reusable GitHub workflow watches for it and runs a Claude Code review automatically; without the label, the review doesn't fire. |
0 commit comments