docs: trim and realign CLAUDE.md and .cursor/rules/#473
Merged
Conversation
Make .cursor/rules/*.mdc the single source of truth (canonical) and
reduce CLAUDE.md to a thin index that points at them. Removes content
that was either duplicated, stale, factually wrong about the codebase,
generic theory, or personal preference that does not belong in a
shared open-source repo.
Cursor rules
- Delete 06-performance-optimization.mdc (entirely generic React/Python
perf advice, plus aspirational tools like TanStack Query that are not
used).
- 01: drop the Personal Style block (15 bullets of personal preferences;
belongs in user-level config, not the repo).
- 02: drop the 8-phase Data Product Lifecycle, Roles & Responsibilities,
and Contract Maintenance Principles sections (already in
docs/user-journeys/). Add Datasets (DEPRECATED), Assets & Ontology,
and Tagging System mentions to Core Features.
- 03, 04, 07, 08: rewrite/trim. Fix every stale "api/..." path to the
actual "src/backend/src/..." layout. Fix "api/app.yaml" to
"src/app.yaml".
- 04: replace the exhaustive directory tree with a compact one matching
reality; drop the config-file enumeration.
- 05: drop unenforced/wrong claims:
* "Use mapped types instead of enums" (FeatureAccessLevel and many
other enums exist).
* "wrapping fetch or axios" (no axios anywhere).
* "Prefer interfaces over types" (codebase uses both).
* Vacuous bullets ("Consider server-side patterns if applicable",
"Use Suspense for lazy loading components if needed").
Keep the security-relevant rules with teeth (no str(e) in
HTTPException, %-style logging, no template literals in console
with user data, Ajv allErrors warning).
- 07: drop obvious filler ("Follow RESTful API design", "Use SQLAlchemy
for ORM", "Optimize Web Vitals", "Ensure CORS is configured").
- 08: fix app.yaml path; add Playwright MCP tool block; drop "implement
unit tests using pytest/Jest" as obvious.
CLAUDE.md
- Collapse from ~315 lines to ~26: a thin index of the cursor rules
with markdown links, plus a small Claude-specific section and the
operational must-knows that bite (no server restart, log paths,
ports, hatch, yarn).
.claude/agents/ and .claude/commands/
- Delete all six files. They were stock Anthropic templates not
specific to this project (and partly factually wrong, e.g.,
create-pr.md referenced Biome which the project does not use).
All four agents duplicate built-in subagent types Cursor and
Claude Code already provide. The 26 KB test-engineer.md was a
fabricated JS test framework with no project relevance.
Repo URL
- Fix to https://github.com/databrickslabs/ontos (was previously
inconsistent: rule 01 said larsgeorge/ontos-app, CLAUDE.md said
larsgeorge/ontos; neither matches the actual remote).
Result
- .cursor/rules/ drops from ~900 lines to ~500 (matrix file 10
unchanged).
- CLAUDE.md drops from 315 lines to ~26.
- Zero duplicated content between CLAUDE.md and Cursor rules.
- Every path in the rules now resolves to a real file.
larsgeorge-db
force-pushed
the
docs-trim-cursor-claude-rules
branch
from
9889647 to
13c9c73
Compare
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
1 participant
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
Make
.cursor/rules/*.mdcthe single source of truth and reduceCLAUDE.mdto a thin index. Removes content that was duplicated, stale, factually wrong about the codebase, generic theory, or personal preference that doesn't belong in a shared open-source repo..cursor/rules/shrinks from ~900 lines to ~500 (matrix file 10 unchanged); deletes06-performance-optimization.mdcoutright.CLAUDE.mdshrinks from 315 lines to ~26 (now a markdown-linked index of the cursor rules + small Claude-specific section + the operational must-knows that bite)..claude/agents/and.claude/commands/deleted (six stock Anthropic template files, none project-specific; the 26 KBtest-engineer.mdwas fabricated JS framework with no project relevance;create-pr.mdreferenced Biome which the project doesn't use).api/...paths corrected tosrc/backend/src/...(the actual layout).api/app.yamlcorrected tosrc/app.yaml.https://github.com/databrickslabs/ontos(rule 01 hadlarsgeorge/ontos-app, CLAUDE.md hadlarsgeorge/ontos; neither matched the real remote).FeatureAccessLeveland ~20 other enums exist).02-project-overview.mdc; Playwright MCP tool block in08-testing-and-deployment.mdc.Result: zero duplicated content between
CLAUDE.mdand Cursor rules; every path resolves to a real file.Test plan
src/backend/src/routes/data_product_routes.py) and confirm05-code-style-and-structure.mdccontent is in scope per itsglobs.src/frontend/src/views/data-products.tsx) and confirm same.rg \"api/(routes|controller|common|utils|repositories|db_models|models|app\\.(py|yaml))\" .cursor/ CLAUDE.mdreturns zero hits..cursorrulesno longer references06-performance-optimization.mdc.CLAUDE.mdmarkdown links and confirm they all resolve to existing files.