Skip to content

Commit 03ac975

Browse files
committed
ai(rules[claude]) Consolidate cursor rules to CLAUDE.md for claude code
1 parent bddb4f7 commit 03ac975

File tree

1 file changed

+133
-13
lines changed

1 file changed

+133
-13
lines changed

CLAUDE.md

Lines changed: 133 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ uv run pytest tests/test_cli.py::test_sync
3131
uv run ptw .
3232
# or
3333
make start
34+
35+
# Run tests with coverage
36+
uv run py.test --cov -v
3437
```
3538

3639
#### Code Quality
@@ -41,8 +44,8 @@ uv run ruff format .
4144
# or
4245
make ruff_format
4346

44-
# Run ruff linting
45-
uv run ruff check .
47+
# Run ruff linting with auto-fixes
48+
uv run ruff check . --fix --show-fixes
4649
# or
4750
make ruff
4851

@@ -66,6 +69,16 @@ make build_docs
6669
make start_docs
6770
```
6871

72+
## Development Process
73+
74+
Follow this workflow for code changes:
75+
76+
1. **Format First**: `uv run ruff format .`
77+
2. **Run Tests**: `uv run py.test`
78+
3. **Run Linting**: `uv run ruff check . --fix --show-fixes`
79+
4. **Check Types**: `uv run mypy`
80+
5. **Verify Tests Again**: `uv run py.test`
81+
6982
## Code Architecture
7083

7184
### Core Components
@@ -98,21 +111,128 @@ Example format:
98111
awesome: "git+git://git.naquadah.org/awesome.git"
99112
```
100113
114+
## Coding Standards
115+
116+
### Imports
117+
118+
- Use namespace imports: `import enum` instead of `from enum import Enum`
119+
- For typing, use `import typing as t` and access via namespace: `t.NamedTuple`, etc.
120+
- Use `from __future__ import annotations` at the top of all Python files
121+
122+
### Docstrings
123+
124+
Follow NumPy docstring style for all functions and methods:
125+
126+
```python
127+
"""Short description of the function or class.
128+
129+
Detailed description using reStructuredText format.
130+
131+
Parameters
132+
----------
133+
param1 : type
134+
Description of param1
135+
param2 : type
136+
Description of param2
137+
138+
Returns
139+
-------
140+
type
141+
Description of return value
142+
"""
143+
```
144+
101145
### Testing
102146

103-
Tests use pytest and are organized by component functionality:
104-
- `tests/test_cli.py`: Tests for CLI functionality
105-
- `tests/test_config.py`: Tests for configuration parsing
106-
- `tests/test_sync.py`: Tests for repository synchronization
147+
#### Using libvcs Fixtures
148+
149+
When writing tests, leverage libvcs's pytest plugin fixtures:
150+
151+
- `create_git_remote_repo`, `create_svn_remote_repo`, `create_hg_remote_repo`: Factory fixtures
152+
- `git_repo`, `svn_repo`, `hg_repo`: Pre-made repository instances
153+
- `set_home`, `gitconfig`, `hgconfig`, `git_commit_envvars`: Environment fixtures
154+
155+
Example:
156+
```python
157+
def test_vcspull_sync(git_repo):
158+
# git_repo is already a GitSync instance with a clean repository
159+
# Use it directly in your tests
160+
```
161+
162+
#### Test Structure
163+
164+
Use `typing.NamedTuple` for parameterized tests:
165+
166+
```python
167+
class SyncFixture(t.NamedTuple):
168+
test_id: str # For test naming
169+
sync_args: list[str]
170+
expected_exit_code: int
171+
expected_in_out: ExpectedOutput = None
172+
173+
@pytest.mark.parametrize(
174+
list(SyncFixture._fields),
175+
SYNC_REPO_FIXTURES,
176+
ids=[test.test_id for test in SYNC_REPO_FIXTURES],
177+
)
178+
def test_sync(
179+
# Parameters and fixtures...
180+
):
181+
# Test implementation
182+
```
183+
184+
#### Mocking Strategy
185+
186+
- Use `monkeypatch` for environment, globals, attributes
187+
- Use `mocker` (from pytest-mock) for application code
188+
- Document every mock with comments explaining WHAT is being mocked and WHY
107189

108-
## Best Practices
190+
#### Configuration File Testing
191+
192+
- Use project helper functions like `vcspull.tests.helpers.write_config` or `save_config_yaml`
193+
- Avoid direct `yaml.dump` or `file.write_text` for config creation
194+
195+
### Git Commit Standards
196+
197+
Format commit messages as:
198+
```
199+
Component/File(commit-type[Subcomponent/method]): Concise description
109200
110-
1. **Types**: The codebase uses strict typing with mypy. All new code should include proper type annotations.
201+
why: Explanation of necessity or impact.
202+
what:
203+
- Specific technical changes made
204+
- Focused on a single topic
205+
206+
refs: #issue-number, breaking changes, or relevant links
207+
```
208+
209+
Common commit types:
210+
- **feat**: New features or enhancements
211+
- **fix**: Bug fixes
212+
- **refactor**: Code restructuring without functional change
213+
- **docs**: Documentation updates
214+
- **chore**: Maintenance (dependencies, tooling, config)
215+
- **test**: Test-related updates
216+
- **style**: Code style and formatting
217+
218+
Example:
219+
```
220+
cli/add(feat[add_repo]): Add support for custom remote URLs
221+
222+
why: Enable users to specify alternative remote URLs for repositories
223+
what:
224+
- Add remote_url parameter to add_repo function
225+
- Update CLI argument parser to accept --remote-url option
226+
- Add tests for the new functionality
227+
228+
refs: #123
229+
```
111230

112-
2. **Docstrings**: The project follows NumPy docstring style for all functions and methods.
231+
## Debugging Tips
113232

114-
3. **Error Handling**: Exceptions are defined in `exc.py`. Use appropriate exception types.
233+
When stuck in debugging loops:
115234

116-
4. **Testing Approach**:
117-
- Tests use fixtures extensively (see `conftest.py` and `tests/fixtures/`)
118-
- CLI tests use parameter fixtures with clear IDs for readability
235+
1. **Pause and acknowledge the loop**
236+
2. **Minimize to MVP**: Remove all debugging cruft and experimental code
237+
3. **Document the issue** comprehensively for a fresh approach
238+
4. Format for portability (using quadruple backticks)

0 commit comments

Comments
 (0)