Add .claude/rules/ and refresh CLAUDE.md#745
Merged
Merged
Conversation
Introduce `docs/invariants.md`, a shortlist of design decisions that should survive future refactors — layering boundaries, the claims model, upstream API compatibility, sync atomicity, and related constraints. Each entry names the decision, the rationale, what must hold, and what breaks if it is undone. The intent is to give reviewers (human and agentic) a single place to cite when a change conflicts with a load-bearing choice that is otherwise only implicit in the code. Refresh `CLAUDE.md` to match the current codebase and reference the new doc. The previous version pointed to paths under `cmd/thv-registry-api/` that no longer exist (the real packages are under `internal/`) and described a `Provider` / `RegistryDataProvider` abstraction that was never part of this repository. Replace the layer description with an accurate directory tree, rewrite the "Key Patterns" and "Common Tasks" sections against the actual architecture (builder + functional options, `SourceConfig.GetType`, `RecordFilter` chains, audit wrapping, source type registration steps), and update the dependency list to reflect what is in `go.mod` today. Add a prominent pointer to `docs/invariants.md` at the top of the file and note that the `code-reviewer` subagent should cross-check against it.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #745 +/- ##
==========================================
- Coverage 60.64% 60.40% -0.24%
==========================================
Files 108 108
Lines 10482 13041 +2559
==========================================
+ Hits 6357 7878 +1521
- Misses 3572 4610 +1038
Partials 553 553 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Following review feedback, convert `docs/invariants.md` into scoped rule files under `.claude/rules/` so Claude Code loads each rule only when working on files in its declared path glob, matching the convention already used in `stacklok/toolhive` (`.claude/rules/vmcp-anti-patterns.md` and siblings). This keeps `CLAUDE.md` tight, avoids always-loaded context bloat, and lets rules be maintained alongside the code they govern. The content is the same set of constraints previously captured in `docs/invariants.md`, split by theme: `layering.md` (layer direction, two HTTP servers, builder/factory pattern), `data-model.md` (claims on names, source-type inference, managed-source uniqueness, flat claim values, CONFIG/API exclusivity, app-level filtering), `auth.md` (authn/authz separation, IdP-sourced roles, uniform claim matching, default-deny, subset validation, HTTPS for OIDC), `api.md` (upstream spec compliance, single publish endpoint, personalized responses, audit wrapping, entry-level dedup), `sync.md` (serializable txn, non-synced types, K8s per-CRD claims), and `secrets.md` (file-based secrets, symlink resolution, mutually-exclusive auth modes). Each file uses a `paths:` frontmatter glob and the gateway's **Detect** / **Instead** idiom where it fits. Update `CLAUDE.md` to point to the rules directory instead of the removed `docs/invariants.md` and refresh inline `§`-references in the "Common Tasks" recipes to name the specific rule file.
rdimitrov
changed the title
CLAUDE.md.claude/rules/ and refresh CLAUDE.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.claude/rules/— six scoped rule files (layering.md,data-model.md,auth.md,api.md,sync.md,secrets.md) capturing the design decisions that shaped this codebase and should not be broken without explicit discussion. Each file uses apaths:frontmatter glob so Claude Code loads the rule only when working on files in its scope. Matches the convention already used instacklok/toolhive(.claude/rules/vmcp-anti-patterns.mdand siblings). Credit to Alejandro for the suggestion.CLAUDE.md— the previous version referenced paths undercmd/thv-registry-api/that no longer exist (real packages live underinternal/) and described aProvider/RegistryDataProviderabstraction that is not in the codebase. This update replaces the stale architecture section with an accurate directory tree, rewrites the "Key Patterns" and "Common Tasks" sections against the real code (builder + functional options,SourceConfig.GetType,RecordFilterchains, audit wrapping, source type registration steps), fixes the dependency list to matchgo.mod, and points at.claude/rules/for the per-area design rules.No code changes; docs and rules only.
Rule file scopes
layering.mdinternal/**,cmd/**data-model.mdinternal/config/**,internal/service/**,internal/sources/**,database/**auth.mdinternal/auth/**,internal/authz/**, claims filterapi.mdinternal/api/**sync.mdinternal/sync/**,internal/sources/**,internal/kubernetes/**secrets.mdinternal/auth/**,internal/config/**,internal/db/**Test plan
paths:globs on each rule match the code that should trigger themCLAUDE.mddirectory tree matches reality (especially theinternal/layout)