Skip to content

Commit 466138d

Browse files
tonytony
committedMar 8, 2025·
cursor,windsurf(rules[dev-loop]) Sync with latest python loop
1 parent 38293da commit 466138d

File tree

5 files changed

+517
-0
lines changed

5 files changed

+517
-0
lines changed
 

‎.cursor/rules/avoid-debug-loops.mdc

+57
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
description: When stuck in debugging loops, break the cycle by minimizing to an MVP, removing debugging cruft, and documenting the issue completely for a fresh approach
3+
globs: *.py
4+
alwaysApply: true
5+
---
6+
# Avoid Debug Loops
7+
8+
When debugging becomes circular and unproductive, follow these steps:
9+
10+
## Detection
11+
- You have made multiple unsuccessful attempts to fix the same issue
12+
- You are adding increasingly complex code to address errors
13+
- Each fix creates new errors in a cascading pattern
14+
- You are uncertain about the root cause after 2-3 iterations
15+
16+
## Action Plan
17+
18+
1. **Pause and acknowledge the loop**
19+
- Explicitly state that you are in a potential debug loop
20+
- Review what approaches have been tried and failed
21+
22+
2. **Minimize to MVP**
23+
- Remove all debugging cruft and experimental code
24+
- Revert to the simplest version that demonstrates the issue
25+
- Focus on isolating the core problem without added complexity
26+
27+
3. **Comprehensive Documentation**
28+
- Provide a clear summary of the issue
29+
- Include minimal but complete code examples that reproduce the problem
30+
- Document exact error messages and unexpected behaviors
31+
- Explain your current understanding of potential causes
32+
33+
4. **Format for Portability**
34+
- Present the problem in quadruple backticks for easy copying:
35+
36+
````
37+
# Problem Summary
38+
[Concise explanation of the issue]
39+
40+
## Minimal Reproduction Code
41+
```python
42+
# Minimal code example that reproduces the issue
43+
```
44+
45+
## Error/Unexpected Output
46+
```
47+
[Exact error messages or unexpected output]
48+
```
49+
50+
## Failed Approaches
51+
[Brief summary of approaches already tried]
52+
53+
## Suspected Cause
54+
[Your current hypothesis about what might be causing the issue]
55+
````
56+
57+
This format enables the user to easily copy the entire problem statement into a fresh conversation for a clean-slate approach.

‎.cursor/rules/dev-loop.mdc

+187
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
description: QA every edit
3+
globs: *.py
4+
alwaysApply: true
5+
---
6+
7+
# Development Process
8+
9+
## Project Stack
10+
11+
The project uses the following tools and technologies:
12+
13+
- **uv** - Python package management and virtual environments
14+
- **ruff** - Fast Python linter and formatter
15+
- **py.test** - Testing framework
16+
- **pytest-watcher** - Continuous test runner
17+
- **mypy** - Static type checking
18+
- **doctest** - Testing code examples in documentation
19+
20+
## 1. Start with Formatting
21+
22+
Format your code first:
23+
24+
```
25+
uv run ruff format .
26+
```
27+
28+
## 2. Run Tests
29+
30+
Verify that your changes pass the tests:
31+
32+
```
33+
uv run py.test
34+
```
35+
36+
For continuous testing during development, use pytest-watcher:
37+
38+
```
39+
# Watch all tests
40+
uv run ptw .
41+
42+
# Watch and run tests immediately, including doctests
43+
uv run ptw . --now --doctest-modules
44+
45+
# Watch specific files or directories
46+
uv run ptw . --now --doctest-modules src/libtmux/_internal/
47+
```
48+
49+
## 3. Commit Initial Changes
50+
51+
Make an atomic commit for your changes using conventional commits.
52+
Use `@git-commits.mdc` for assistance with commit message standards.
53+
54+
## 4. Run Linting and Type Checking
55+
56+
Check and fix linting issues:
57+
58+
```
59+
uv run ruff check . --fix --show-fixes
60+
```
61+
62+
Check typings:
63+
64+
```
65+
uv run mypy
66+
```
67+
68+
## 5. Verify Tests Again
69+
70+
Ensure tests still pass after linting and type fixes:
71+
72+
```
73+
uv run py.test
74+
```
75+
76+
## 6. Final Commit
77+
78+
Make a final commit with any linting/typing fixes.
79+
Use `@git-commits.mdc` for assistance with commit message standards.
80+
81+
## Development Loop Guidelines
82+
83+
If there are any failures at any step due to your edits, fix them before proceeding to the next step.
84+
85+
## Python Code Standards
86+
87+
### Docstring Guidelines
88+
89+
For `src/**/*.py` files, follow these docstring guidelines:
90+
91+
1. **Use reStructuredText format** for all docstrings.
92+
```python
93+
"""Short description of the function or class.
94+
95+
Detailed description using reStructuredText format.
96+
97+
Parameters
98+
----------
99+
param1 : type
100+
Description of param1
101+
param2 : type
102+
Description of param2
103+
104+
Returns
105+
-------
106+
type
107+
Description of return value
108+
"""
109+
```
110+
111+
2. **Keep the main description on the first line** after the opening `"""`.
112+
113+
3. **Use NumPy docstyle** for parameter and return value documentation.
114+
115+
### Doctest Guidelines
116+
117+
For doctests in `src/**/*.py` files:
118+
119+
1. **Use narrative descriptions** for test sections rather than inline comments:
120+
```python
121+
"""Example function.
122+
123+
Examples
124+
--------
125+
Create an instance:
126+
127+
>>> obj = ExampleClass()
128+
129+
Verify a property:
130+
131+
>>> obj.property
132+
'expected value'
133+
"""
134+
```
135+
136+
2. **Move complex examples** to dedicated test files at `tests/examples/<path_to_module>/test_<example>.py` if they require elaborate setup or multiple steps.
137+
138+
3. **Utilize pytest fixtures** via `doctest_namespace` for more complex test scenarios:
139+
```python
140+
"""Example with fixture.
141+
142+
Examples
143+
--------
144+
>>> # doctest_namespace contains all pytest fixtures from conftest.py
145+
>>> example_fixture = getfixture('example_fixture')
146+
>>> example_fixture.method()
147+
'expected result'
148+
"""
149+
```
150+
151+
4. **Keep doctests simple and focused** on demonstrating usage rather than comprehensive testing.
152+
153+
5. **Add blank lines between test sections** for improved readability.
154+
155+
6. **Test your doctests continuously** using pytest-watcher during development:
156+
```
157+
# Watch specific modules for doctest changes
158+
uv run ptw . --now --doctest-modules src/path/to/module.py
159+
```
160+
161+
### Pytest Testing Guidelines
162+
163+
1. **Use existing fixtures over mocks**:
164+
- Use fixtures from conftest.py instead of `monkeypatch` and `MagicMock` when available
165+
- For instance, if using libtmux, use provided fixtures: `server`, `session`, `window`, and `pane`
166+
- Document in test docstrings why standard fixtures weren't used for exceptional cases
167+
168+
2. **Preferred pytest patterns**:
169+
- Use `tmp_path` (pathlib.Path) fixture over Python's `tempfile`
170+
- Use `monkeypatch` fixture over `unittest.mock`
171+
172+
### Import Guidelines
173+
174+
1. **Prefer namespace imports**:
175+
- Import modules and access attributes through the namespace instead of importing specific symbols
176+
- Example: Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
177+
- This applies to standard library modules like `pathlib`, `os`, and similar cases
178+
179+
2. **Standard aliases**:
180+
- For `typing` module, use `import typing as t`
181+
- Access typing elements via the namespace: `t.NamedTuple`, `t.TypedDict`, etc.
182+
- Note primitive types like unions can be done via `|` pipes and primitive types like list and dict can be done via `list` and `dict` directly.
183+
184+
3. **Benefits of namespace imports**:
185+
- Improves code readability by making the source of symbols clear
186+
- Reduces potential naming conflicts
187+
- Makes import statements more maintainable

‎.cursor/rules/git-commits.mdc

+95
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
description: git-commits: Git commit message standards and AI assistance
3+
globs: git-commits: Git commit message standards and AI assistance | *.git/* .gitignore .github/* CHANGELOG.md CHANGES.md
4+
alwaysApply: true
5+
---
6+
# Optimized Git Commit Standards
7+
8+
## Commit Message Format
9+
```
10+
Component/File(commit-type[Subcomponent/method]): Concise description
11+
12+
why: Explanation of necessity or impact.
13+
what:
14+
- Specific technical changes made
15+
- Focused on a single topic
16+
17+
refs: #issue-number, breaking changes, or relevant links
18+
```
19+
20+
## Component Patterns
21+
### General Code Changes
22+
```
23+
Component/File(feat[method]): Add feature
24+
Component/File(fix[method]): Fix bug
25+
Component/File(refactor[method]): Code restructure
26+
```
27+
28+
### Packages and Dependencies
29+
| Language | Standard Packages | Dev Packages | Extras / Sub-packages |
30+
|------------|------------------------------------|-------------------------------|-----------------------------------------------|
31+
| General | `lang(deps):` | `lang(deps[dev]):` | |
32+
| Python | `py(deps):` | `py(deps[dev]):` | `py(deps[extra]):` |
33+
| JavaScript | `js(deps):` | `js(deps[dev]):` | `js(deps[subpackage]):`, `js(deps[dev{subpackage}]):` |
34+
35+
#### Examples
36+
- `py(deps[dev]): Update pytest to v8.1`
37+
- `js(deps[ui-components]): Upgrade Button component package`
38+
- `js(deps[dev{linting}]): Add ESLint plugin`
39+
40+
### Documentation Changes
41+
Prefix with `docs:`
42+
```
43+
docs(Component/File[Subcomponent/method]): Update API usage guide
44+
```
45+
46+
### Test Changes
47+
Prefix with `tests:`
48+
```
49+
tests(Component/File[Subcomponent/method]): Add edge case tests
50+
```
51+
52+
## Commit Types Summary
53+
- **feat**: New features or enhancements
54+
- **fix**: Bug fixes
55+
- **refactor**: Code restructuring without functional change
56+
- **docs**: Documentation updates
57+
- **chore**: Maintenance (dependencies, tooling, config)
58+
- **test**: Test-related updates
59+
- **style**: Code style and formatting
60+
61+
## General Guidelines
62+
- Subject line: Maximum 50 characters
63+
- Body lines: Maximum 72 characters
64+
- Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
65+
- Limit to one topic per commit
66+
- Separate subject from body with a blank line
67+
- Mark breaking changes clearly: `BREAKING:`
68+
- Use `See also:` to provide external references
69+
70+
## AI Assistance Workflow in Cursor
71+
- Stage changes with `git add`
72+
- Use `@commit` to generate initial commit message
73+
- Review and refine generated message
74+
- Ensure adherence to these standards
75+
76+
## Good Commit Example
77+
```
78+
Pane(feat[capture_pane]): Add screenshot capture support
79+
80+
why: Provide visual debugging capability
81+
what:
82+
- Implement capturePane method with image export
83+
- Integrate with existing Pane component logic
84+
- Document usage in Pane README
85+
86+
refs: #485
87+
See also: https://example.com/docs/pane-capture
88+
```
89+
90+
## Bad Commit Example
91+
```
92+
fixed stuff and improved some functions
93+
```
94+
95+
These guidelines ensure clear, consistent commit histories, facilitating easier code review and maintenance.

‎.cursor/rules/notes-llms-txt.mdc

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
description: LLM-friendly markdown format for notes directories
3+
globs: notes/**/*.md,**/notes/**/*.md
4+
alwaysApply: true
5+
---
6+
7+
# Instructions for Generating LLM-Optimized Markdown Content
8+
9+
When creating or editing markdown files within the specified directories, adhere to the following guidelines to ensure the content is optimized for LLM understanding and efficient token usage:
10+
11+
1. **Conciseness and Clarity**:
12+
- **Be Brief**: Present information succinctly, avoiding unnecessary elaboration.
13+
- **Use Clear Language**: Employ straightforward language to convey ideas effectively.
14+
15+
2. **Structured Formatting**:
16+
- **Headings**: Utilize markdown headings (`#`, `##`, `###`, etc.) to organize content hierarchically.
17+
- **Lists**: Use bullet points (`-`) or numbered lists (`1.`, `2.`, etc.) to enumerate items clearly.
18+
- **Code Blocks**: Enclose code snippets within triple backticks (```) to distinguish them from regular text.
19+
20+
3. **Semantic Elements**:
21+
- **Emphasis**: Use asterisks (`*`) or underscores (`_`) for italicizing text to denote emphasis.
22+
- **Strong Emphasis**: Use double asterisks (`**`) or double underscores (`__`) for bold text to highlight critical points.
23+
- **Inline Code**: Use single backticks (`) for inline code references.
24+
25+
4. **Linking and References**:
26+
- **Hyperlinks**: Format links using `[Link Text](mdc:URL)` to provide direct access to external resources.
27+
- **References**: When citing sources, use footnotes or inline citations to maintain readability.
28+
29+
5. **Avoid Redundancy**:
30+
- **Eliminate Repetition**: Ensure that information is not unnecessarily repeated within the document.
31+
- **Use Summaries**: Provide brief summaries where detailed explanations are not essential.
32+
33+
6. **Standard Compliance**:
34+
- **llms.txt Conformance**: Structure the document in alignment with the `llms.txt` standard, which includes:
35+
- An H1 heading with the project or site name.
36+
- A blockquote summarizing the project's purpose.
37+
- Additional markdown sections providing detailed information.
38+
- H2-delimited sections containing lists of URLs for further details.
39+
40+
By following these guidelines, the markdown files will be tailored for optimal LLM processing, ensuring that the content is both accessible and efficiently tokenized for AI applications.
41+
42+
For more information on the `llms.txt` standard, refer to the official documentation: https://llmstxt.org/

‎.windsurfrules

+136
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# libtmux Python Project Rules
2+
3+
<project_stack>
4+
- uv - Python package management and virtual environments
5+
- ruff - Fast Python linter and formatter
6+
- py.test - Testing framework
7+
- pytest-watcher - Continuous test runner
8+
- mypy - Static type checking
9+
- doctest - Testing code examples in documentation
10+
</project_stack>
11+
12+
<coding_style>
13+
- Use a consistent coding style throughout the project
14+
- Format code with ruff before committing
15+
- Run linting and type checking before finalizing changes
16+
- Verify tests pass after each significant change
17+
</coding_style>
18+
19+
<python_docstrings>
20+
- Use reStructuredText format for all docstrings in src/**/*.py files
21+
- Keep the main description on the first line after the opening `"""`
22+
- Use NumPy docstyle for parameter and return value documentation
23+
- Format docstrings as follows:
24+
```python
25+
"""Short description of the function or class.
26+
27+
Detailed description using reStructuredText format.
28+
29+
Parameters
30+
----------
31+
param1 : type
32+
Description of param1
33+
param2 : type
34+
Description of param2
35+
36+
Returns
37+
-------
38+
type
39+
Description of return value
40+
"""
41+
```
42+
</python_docstrings>
43+
44+
<python_doctests>
45+
- Use narrative descriptions for test sections rather than inline comments
46+
- Format doctests as follows:
47+
```python
48+
"""
49+
Examples
50+
--------
51+
Create an instance:
52+
53+
>>> obj = ExampleClass()
54+
55+
Verify a property:
56+
57+
>>> obj.property
58+
'expected value'
59+
"""
60+
```
61+
- Add blank lines between test sections for improved readability
62+
- Keep doctests simple and focused on demonstrating usage
63+
- Move complex examples to dedicated test files at tests/examples/<path_to_module>/test_<example>.py
64+
- Utilize pytest fixtures via doctest_namespace for complex scenarios
65+
</python_doctests>
66+
67+
<testing_practices>
68+
- Run tests with `uv run py.test` before committing changes
69+
- Use pytest-watcher for continuous testing: `uv run ptw . --now --doctest-modules`
70+
- Fix any test failures before proceeding with additional changes
71+
</testing_practices>
72+
73+
<git_workflow>
74+
- Make atomic commits with conventional commit messages
75+
- Start with an initial commit of functional changes
76+
- Follow with separate commits for formatting, linting, and type checking fixes
77+
</git_workflow>
78+
79+
<git_commit_standards>
80+
- Use the following commit message format:
81+
```
82+
Component/File(commit-type[Subcomponent/method]): Concise description
83+
84+
why: Explanation of necessity or impact.
85+
what:
86+
- Specific technical changes made
87+
- Focused on a single topic
88+
89+
refs: #issue-number, breaking changes, or relevant links
90+
```
91+
92+
- Common commit types:
93+
- **feat**: New features or enhancements
94+
- **fix**: Bug fixes
95+
- **refactor**: Code restructuring without functional change
96+
- **docs**: Documentation updates
97+
- **chore**: Maintenance (dependencies, tooling, config)
98+
- **test**: Test-related updates
99+
- **style**: Code style and formatting
100+
101+
- Prefix Python package changes with:
102+
- `py(deps):` for standard packages
103+
- `py(deps[dev]):` for development packages
104+
- `py(deps[extra]):` for extras/sub-packages
105+
106+
- General guidelines:
107+
- Subject line: Maximum 50 characters
108+
- Body lines: Maximum 72 characters
109+
- Use imperative mood (e.g., "Add", "Fix", not "Added", "Fixed")
110+
- Limit to one topic per commit
111+
- Separate subject from body with a blank line
112+
- Mark breaking changes clearly: `BREAKING:`
113+
</git_commit_standards>
114+
115+
<pytest_testing_guidelines>
116+
- Use fixtures from conftest.py instead of monkeypatch and MagicMock when available
117+
- For instance, if using libtmux, use provided fixtures: server, session, window, and pane
118+
- Document in test docstrings why standard fixtures weren't used for exceptional cases
119+
- Use tmp_path (pathlib.Path) fixture over Python's tempfile
120+
- Use monkeypatch fixture over unittest.mock
121+
</pytest_testing_guidelines>
122+
123+
<import_guidelines>
124+
- Prefer namespace imports over importing specific symbols
125+
- Import modules and access attributes through the namespace:
126+
- Use `import enum` and access `enum.Enum` instead of `from enum import Enum`
127+
- This applies to standard library modules like pathlib, os, and similar cases
128+
- For typing, use `import typing as t` and access via the namespace:
129+
- Access typing elements as `t.NamedTuple`, `t.TypedDict`, etc.
130+
- Note primitive types like unions can be done via `|` pipes
131+
- Primitive types like list and dict can be done via `list` and `dict` directly
132+
- Benefits of namespace imports:
133+
- Improves code readability by making the source of symbols clear
134+
- Reduces potential naming conflicts
135+
- Makes import statements more maintainable
136+
</import_guidelines>

0 commit comments

Comments
 (0)
Please sign in to comment.