break out file-/directory-specific guidance into .claude/rules/**/*.md files and simplify CLAUDE.md [ci skip]#3327
break out file-/directory-specific guidance into .claude/rules/**/*.md files and simplify CLAUDE.md [ci skip]#3327Dave Shoup (shouples) wants to merge 2 commits intomainfrom
.claude/rules/**/*.md files and simplify CLAUDE.md [ci skip]#3327Conversation
…md` files and simplify CLAUDE.md
There was a problem hiding this comment.
Pull request overview
Updates Claude Code guidance for this VS Code extension by condensing CLAUDE.md into high-signal rules and moving detailed architecture/testing guidance into scoped .claude/rules/* documents that apply by path.
Changes:
- Simplifies and restructures
CLAUDE.mdaround “Golden Rules”, core commands, and pointers to.claude/rules/. - Adds path-scoped testing guidance for unit, functional (webview), and E2E tests.
- Adds path-scoped architecture guidance for sidecar pattern, view providers, resource loaders, settings, connection types, and client codegen.
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| CLAUDE.md | Consolidates key dev rules/commands and points to detailed .claude/rules/ docs. |
| .claude/rules/testing/unit-tests.md | Adds unit testing conventions (Mocha + Sinon) and stubbing guidance. |
| .claude/rules/testing/functional-tests.md | Adds Playwright webview “functional test” guidance. |
| .claude/rules/testing/e2e-tests.md | Adds Playwright + Electron E2E conventions (POM, tags/filtering). |
| .claude/rules/architecture/webview-architecture.md | Documents webview templates, bindings, comms, styling, and toolkit deprecation. |
| .claude/rules/architecture/view-providers.md | Documents tree/panel provider base classes and registration steps. |
| .claude/rules/architecture/sidecar-pattern.md | Documents sidecar components and short-lived handle pattern. |
| .claude/rules/architecture/resource-loaders.md | Documents loader hierarchy, caching, and registry pattern. |
| .claude/rules/architecture/extension-settings.md | Documents ExtensionSetting<T> pattern and where to add settings. |
| .claude/rules/architecture/connection-types.md | Documents CCLOUD/LOCAL/DIRECT connection types and related code locations. |
| .claude/rules/architecture/client-codegen.md | Documents OpenAPI/GraphQL codegen workflow and directories. |
CLAUDE.md
Outdated
| ); | ||
| this.disposables.push(vscode.workspace.onDidChangeConfiguration(...)); | ||
| } | ||
| // .dispose() is automatically handled by DisposableCollection |
There was a problem hiding this comment.
The snippet/comment implies .dispose() is “automatically handled” once you extend DisposableCollection, but DisposableCollection only implements dispose()—it still needs to be invoked (e.g., by pushing the instance into context.subscriptions or disposing it manually). Suggest rewording to avoid implying disposal happens without registration.
| // .dispose() is automatically handled by DisposableCollection | |
| // DisposableCollection implements .dispose() to clean up this.disposables | |
| // Remember to register MyClass for disposal (e.g. in context.subscriptions) |
CLAUDE.md
Outdated
| - `src/clients/` — generated from OpenAPI specs via `npx gulp apigen` | ||
| - `src/graphql/sidecarGraphQL.d.ts` — generated from `src/graphql/sidecar.graphql` | ||
|
|
There was a problem hiding this comment.
src/clients/ isn’t entirely auto-generated (it also contains the OpenAPI sources that apigen consumes, e.g. src/clients/docker.openapi.yaml, src/clients/medusa-openapi-spec/, and src/clients/sidecar-openapi-specs/). This section should distinguish “generated client code under src/clients/<service>/” from the editable spec/patch sources to avoid discouraging necessary edits.
| - `src/clients/` — generated from OpenAPI specs via `npx gulp apigen` | |
| - `src/graphql/sidecarGraphQL.d.ts` — generated from `src/graphql/sidecar.graphql` | |
| - Generated client code under `src/clients/<service>/` — produced from OpenAPI specs via `npx gulp apigen` | |
| - `src/graphql/sidecarGraphQL.d.ts` — generated from `src/graphql/sidecar.graphql` | |
| ## Editable API Specs (Do Edit) | |
| - `src/clients/docker.openapi.yaml` | |
| - `src/clients/medusa-openapi-spec/` | |
| - `src/clients/sidecar-openapi-specs/` (and `src/clients/sidecar-openapi-specs/patches/`) |
| **NEVER manually edit files in `src/clients/`** — all auto-generated from OpenAPI specs. | ||
|
|
||
| ## OpenAPI (REST) Clients | ||
|
|
||
| To modify client code: | ||
|
|
||
| 1. Update the OpenAPI spec in `src/clients/sidecar-openapi-specs/` | ||
| 2. Run `npx gulp apigen` | ||
| 3. Commit both the spec changes AND a `.patch` file to `src/clients/sidecar-openapi-specs/patches/` | ||
| so subsequent generations apply cleanly | ||
|
|
There was a problem hiding this comment.
The rule says “NEVER manually edit files in src/clients/ — all auto-generated”, but this repo keeps editable OpenAPI specs under src/clients/ as well (e.g. docker.openapi.yaml, medusa-openapi-spec/openapi.yaml, and sidecar-openapi-specs/*.yaml). Please narrow this to the generated output directories (like src/clients/sidecar/, src/clients/docker/, etc.) and explicitly call out the spec/patch locations as safe/expected to edit.
| **NEVER manually edit files in `src/clients/`** — all auto-generated from OpenAPI specs. | |
| ## OpenAPI (REST) Clients | |
| To modify client code: | |
| 1. Update the OpenAPI spec in `src/clients/sidecar-openapi-specs/` | |
| 2. Run `npx gulp apigen` | |
| 3. Commit both the spec changes AND a `.patch` file to `src/clients/sidecar-openapi-specs/patches/` | |
| so subsequent generations apply cleanly | |
| **NEVER manually edit generated client code under the auto-generated directories listed below**. These clients are produced from OpenAPI specs and should only be changed via spec/patch updates and regeneration. | |
| ## OpenAPI (REST) Clients | |
| To modify client code: | |
| 1. Update the relevant OpenAPI spec (for example: | |
| - `src/clients/sidecar-openapi-specs/**/*.yaml` | |
| - `src/clients/docker.openapi.yaml` | |
| - `src/clients/medusa-openapi-spec/openapi.yaml` | |
| ) | |
| 2. Run `npx gulp apigen` | |
| 3. Commit both the spec changes AND any `.patch` files to `src/clients/sidecar-openapi-specs/patches/` | |
| so subsequent generations apply cleanly | |
| OpenAPI spec and patch files under the paths above are **expected and safe to edit**; only the generated client code under the directories listed in “Auto-Generated Directories and Files (never edit)” must not be modified by hand. |
|
| - `src/graphql/sidecarGraphQL.d.ts` — generated from `src/graphql/sidecar.graphql` | ||
|
|
||
| 1. **CCLOUD**: Confluent Cloud via OAuth authentication | ||
| OpenAPI specs under `src/clients/` typically come from upstream services — don't edit them directly. |
There was a problem hiding this comment.
We might not need this note? since we have client-codegen.md
Our
CLAUDE.mdhad some sections that were file- or subdirectory-specific, which is not always relevant for all Claude sessions (e.g. working on E2E tests, updating webviews, etc). Claude rules make more sense to use here, since they are automatically brought in as context depending on the file(s) referenced based on theirpathpatterns.This PR moves a lot of those specific instructions into new
.claude/rules/**/*.mdfiles, which can then reduce the size ofCLAUDE.mdfrom ~2400 tokens to ~1000 tokens.