refactor(rules): reorganise Claude/Cursor rules structure #53
Conversation
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
… rules Migrate project rules from .cursor/rules/ to .claude/rules/ to establish a single source of truth for both Claude Code and Cursor IDE. New rules structure: - development-workflow.md: Code style and project conventions - git-workflow.md: Commit conventions, branch strategy, PR guidelines - examples-standards.md: Example requirements and organisation - no-relative-imports.md: Enforce absolute imports in Python files - package-installation.md: UV package management standards - release-please-standards.md: Release versioning with release-please - uv-scripts.md: Utility script standards with UV All rules now use simplified YAML frontmatter format compatible with both Claude Code (via description/alwaysApply) and Cursor (via globs).
…e/rules/ Convert .cursor/rules/*.mdc files to symlinks pointing to their corresponding .claude/rules/*.md sources. This ensures consistency between Claude Code and Cursor IDE rule definitions. Changes: - Remove cursor-rules-location.mdc (obsolete with new structure) - Add symlinks for development-workflow and git-workflow (new rules) - Convert existing rules to symlinks (examples-standards, no-relative-imports, package-installation, release-please-standards, uv-scripts) Symlink format: .cursor/rules/foo.mdc -> ../../.claude/rules/foo.md
Update CLAUDE.md to document the new rules and skills structure, matching the Node SDK's format. Changes: - Add rules/skills structure explanation section - Add table of available rules with their glob patterns - Update references to use rule names instead of file paths - Use UK English spelling (behaviour, organisation)
Replace all make commands with just commands in rules and CLAUDE.md to reflect the migration from Makefile to justfile.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
3 issues found across 21 files
Prompt for AI agents (all 3 issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name=".claude/rules/uv-scripts.md">
<violation number="1" location=".claude/rules/uv-scripts.md:20">
P2: Python version in UV script header (`>=3.8`) is inconsistent with project's minimum Python version (`>=3.9`). Update to match project requirements to avoid confusion.</violation>
<violation number="2" location=".claude/rules/uv-scripts.md:61">
P2: Example script doesn't follow the error handling guidelines specified earlier in this same document. Consider wrapping the HTTP call in try/except to demonstrate the recommended pattern.</violation>
</file>
<file name=".claude/rules/development-workflow.md">
<violation number="1" location=".claude/rules/development-workflow.md:20">
P2: Documentation states 'Use Python 3.11+ typing features' but the project requires Python >=3.9. This is misleading since Python 3.11+ syntax won't work on older versions. Consider updating to clarify that developers should use `typing_extensions` for features not available in Python 3.9+, or specify which syntax features are safe to use.</violation>
</file>
Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR
|
|
||
| async def fetch_data() -> Dict: | ||
| async with httpx.AsyncClient() as client: | ||
| response = await client.get("https://api.example.com") |
There was a problem hiding this comment.
P2: Example script doesn't follow the error handling guidelines specified earlier in this same document. Consider wrapping the HTTP call in try/except to demonstrate the recommended pattern.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .claude/rules/uv-scripts.md, line 61:
<comment>Example script doesn't follow the error handling guidelines specified earlier in this same document. Consider wrapping the HTTP call in try/except to demonstrate the recommended pattern.</comment>
<file context>
@@ -0,0 +1,66 @@
+
+async def fetch_data() -> Dict:
+ async with httpx.AsyncClient() as client:
+ response = await client.get("https://api.example.com")
+ return response.json()
+
</file context>
|
|
||
| ```python | ||
| # /// script | ||
| # requires-python = ">=3.8" |
There was a problem hiding this comment.
P2: Python version in UV script header (>=3.8) is inconsistent with project's minimum Python version (>=3.9). Update to match project requirements to avoid confusion.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .claude/rules/uv-scripts.md, line 20:
<comment>Python version in UV script header (`>=3.8`) is inconsistent with project's minimum Python version (`>=3.9`). Update to match project requirements to avoid confusion.</comment>
<file context>
@@ -0,0 +1,66 @@
+
+```python
+# /// script
+# requires-python = ">=3.8"
+# dependencies = [
+# "package1",
</file context>
| ## Type Annotations | ||
|
|
||
| - Full type annotations required for all public APIs | ||
| - Use Python 3.11+ typing features |
There was a problem hiding this comment.
P2: Documentation states 'Use Python 3.11+ typing features' but the project requires Python >=3.9. This is misleading since Python 3.11+ syntax won't work on older versions. Consider updating to clarify that developers should use typing_extensions for features not available in Python 3.9+, or specify which syntax features are safe to use.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At .claude/rules/development-workflow.md, line 20:
<comment>Documentation states 'Use Python 3.11+ typing features' but the project requires Python >=3.9. This is misleading since Python 3.11+ syntax won't work on older versions. Consider updating to clarify that developers should use `typing_extensions` for features not available in Python 3.9+, or specify which syntax features are safe to use.</comment>
<file context>
@@ -0,0 +1,63 @@
+## Type Annotations
+
+- Full type annotations required for all public APIs
+- Use Python 3.11+ typing features
+- Run `make mypy` to verify type correctness
+- Strict mypy configuration is enforced
</file context>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR refactors the rules structure to consolidate Claude Code and Cursor IDE rules into a single source of truth. Rules are migrated from .cursor/rules/*.mdc to .claude/rules/*.md with simplified Markdown format and YAML frontmatter, while .cursor/rules/ now contains symlinks for backward compatibility.
Key changes:
- Migrates all rules from
.cursor/rules/to.claude/rules/as the authoritative source - Converts
.cursor/rules/*.mdcfiles to symlinks pointing to.claude/rules/*.md - Adds two new rules:
development-workflow.mdandgit-workflow.mdfor comprehensive project guidance - Updates
CLAUDE.mddocumentation with a structured rules table and improved navigation
Reviewed changes
Copilot reviewed 16 out of 21 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| CLAUDE.md | Updated documentation structure with rules table, removed direct file references in favor of rule names, changed "Behavior" to "Behaviour" for British English consistency |
| .cursor/rules/*.mdc | Converted all rule files to symlinks pointing to corresponding .claude/rules/*.md files |
| .claude/rules/uv-scripts.md | New rule file with YAML frontmatter, both globs and paths fields, simplified Markdown structure |
| .claude/rules/release-please-standards.md | New rule file using alwaysApply: true for global application |
| .claude/rules/package-installation.md | New rule file with path-specific targeting for pyproject.toml files |
| .claude/rules/no-relative-imports.md | New rule file targeting Python files with import standards |
| .claude/rules/git-workflow.md | New comprehensive git workflow rule with commit conventions and PR guidelines |
| .claude/rules/examples-standards.md | New rule file for example code standards and structure |
| .claude/rules/development-workflow.md | New comprehensive development workflow rule covering code style and tooling |
| .cursor/rules/cursor-rules-location.mdc | Removed as obsolete with new symlink-based structure |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Snapshot testing for tool parsing (`tests/snapshots/`) | ||
| - Async tests use `pytest-asyncio` | ||
| - Example validation: See @./.cursor/rules/examples-standards | ||
| - See `examples-standards` rule for example validation |
There was a problem hiding this comment.
The reference format changed from using @./.cursor/rules/examples-standards to just examples-standards rule. However, this line should be updated to match the format used on line 102: "See examples-standards rule" instead of "See examples-standards rule for example validation". Consider making the phrasing consistent: either "See rule-name rule for..." on both lines, or use a different consistent format.
Suggested change
| - See `examples-standards` rule for example validation | |
| - See `examples-standards` rule |
- Update GitHub workflow files from .yml to .yaml extension - Enhance version update script to refresh uv.lock - Resolve symlink conflict in cursor rules
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
.cursor/rules/to.claude/rules/as the single source of truth.cursor/rules/*.mdcfiles with symlinks to.claude/rules/*.mdpathsfield for Claude Code andglobsfield for Cursor compatibilityWhat Changed
.claude/rules/with simplified YAML frontmatter.cursor/rules/contains symlinks for Cursor IDE compatibilitydevelopment-workflow.mdandgit-workflow.mdcursor-rules-location.mdc(obsolete with new structure)Why
Aligns Python SDK structure with Node SDK for consistency across projects. Having a single source of truth in
.claude/rules/makes maintenance easier and ensures both Claude Code and Cursor use the same rule definitions.Summary by cubic
Consolidates all project rules under .claude/rules as the single source of truth, with .cursor/rules replaced by symlinks for Cursor compatibility. Adds new workflow rules and updates CLAUDE.md to document the structure.
Refactors
Migration
Written for commit e703169. Summary will update automatically on new commits.