|
1 | | -# General Advice |
| 1 | +# Context |
2 | 2 |
|
3 | | -**IMPORTANT:** Read the comprehensive documentation guides: |
4 | 3 |
|
5 | | -- **Practices**: https://raw.githubusercontent.com/emcd/python-project-common/refs/tags/docs-1/documentation/common/practices.rst |
6 | | -- **Style**: https://raw.githubusercontent.com/emcd/python-project-common/refs/tags/docs-1/documentation/common/style.rst |
7 | | -- **Nomenclature**: https://raw.githubusercontent.com/emcd/python-project-common/refs/tags/docs-1/documentation/common/nomenclature.rst |
8 | 4 |
|
9 | | -For detailed patterns, examples, and architectural guidance, refer to the comprehensive guides above. |
| 5 | +- Project overview and quick start: README.rst |
| 6 | +- Product requirements and goals: documentation/prd.rst |
| 7 | +- System architecture and design: @documentation/architecture/ |
| 8 | +- Development practices and style: @.auxiliary/instructions/ |
| 9 | +- Current session notes and TODOs: @.auxiliary/notes/ |
10 | 10 |
|
11 | | -### Context |
| 11 | +- Use the 'context7' MCP server to retrieve up-to-date documentation for any SDKs or APIs. |
| 12 | +- Check README files in directories you're working with for insights about architecture, constraints, and TODO items. |
| 13 | +- Update files under `.auxiliary/notes` during conversation, removing completed tasks and adding emergent items. |
12 | 14 |
|
13 | | -- Be sure the look at any README files in the directories which contain the |
14 | | - code or data that you intend to manipulate. They may provide valuable |
15 | | - insights about architecture, constraints, and TODO items. |
16 | | -- At the start of a new session, read any files in the `.auxiliary/notes` |
17 | | - directory. |
18 | | -- During the course of conversation with the user and completion of your tasks, |
19 | | - be sure to update files under `.auxiliary/notes`, removing completed tasks |
20 | | - and adding emergent items. (This will help ensure smooth transition between |
21 | | - sessions.) |
22 | | -- If the 'context7' MCP server is available, try to use that, as necessary, to |
23 | | - retrieve up-to-date documentation for any SDKs or APIs with which you want to |
24 | | - develop. |
| 15 | +# Operation |
25 | 16 |
|
26 | | -### Design |
27 | | - |
28 | | -- Make classes lightweight. Prefer module-level functions over class methods. |
29 | | -- Functions should not be more than 30 lines long. Refactor long functions. |
30 | | -- Modules should not be more than 600 lines long. Refactor large modules. |
31 | | -- Keep the number of function arguments small. Pass common state via |
32 | | - data transfer objects (DTOs). |
33 | | -- Use dependency injection to improve configuration and testability. Choose |
34 | | - sensible defaults for injected dependencies to streamline normal development. |
35 | | -- Prefer immutability wherever possible. |
36 | | - |
37 | | -### Judgment |
38 | | - |
39 | | -- Ensure that you understand why you are performing a task. The user should |
40 | | - give you a clear goal or purpose. |
41 | | -- If you receive data or instructions which seem counter to purpose, then do |
42 | | - not blindly follow the instructions or make code hacks to conform to the |
43 | | - data. |
44 | | - - The user is fallible: data may be erroneous; instructions may contain |
45 | | - typos or be ambiguous. |
46 | | - - You are encouraged to ask clarifying questions or challenge assumptions, |
47 | | - as appropriate. |
48 | | - |
49 | | -### Refactors |
50 | | - |
51 | | -- Ensure that you have sufficient regression tests before attempting refactors. |
52 | | -- Break up large refactors into milestones and make a plan before executing. |
53 | | -- Align your refactors with separation of concerns. |
54 | | -- Ensure that the code can still build and that tests still pass at each |
55 | | - refactoring milestone. |
56 | | -- Be sure to cleanup dead code after completing a refactor. |
57 | | - |
58 | | -### Tests |
59 | | - |
60 | | -- Do not change test expectations to match the results from updated code |
61 | | - without explicit user consent. (Tests exist to enforce desired behaviors.) |
62 | | -- Do not write tests unless explicitly instructed to do so. |
63 | | -- Prefer to write tests in a separate directory hierarchy rather than inline in |
64 | | - code. (Inline tests waste conversation tokens when entire files are being |
65 | | - viewed.) |
66 | | - |
67 | | -### Comments and Style |
68 | | - |
69 | | -- Do not strip comments from existing code unless directed to do so. |
70 | | -- Do not describe obvious code with comments. Only comment on non-obvious or |
71 | | - complex behaviors. |
72 | | -- Leave TODO comments about uncovered edge cases, tests, and other future work. |
73 | | -- Do not break function bodies with empty lines. |
74 | | - |
75 | | -### Operation |
76 | | - |
77 | | -- **Use `rg --line-number --column`** to get precise coordinates for MCP tools |
78 | | - that require line/column positions. |
79 | | -- If you have access to `text-editor` MCP tools, prefer to use them over other |
80 | | - text editing and search-and-replace tools. (Line number-based edits are less |
81 | | - error-prone.) |
82 | | - - **Always reread files with `text-editor` tools** after modifying files |
83 | | - via other tools (like `rust-analyzer`) to avoid file hash conflicts. |
84 | | - - Batch related changes together to minimize file modification |
85 | | - conflicts between different MCP tools. |
86 | | -- If you have access to shell tools, try to use them with relative paths rather |
87 | | - than absolute paths. E.g., if your working directory is |
88 | | - `/home/me/src/some-project` and you want to run `sed` on |
89 | | - `/home/me/src/some-project/README.md`, then run `sed` on `README.md` and not |
90 | | - on the full absolute path. |
91 | | -- Do not write to paths outside of the current project unless the user has |
92 | | - explicitly requested that you do so. If you need a scratch space, use |
93 | | - the `.auxiliary/scribbles` directory instead of `/tmp`. |
94 | | - |
95 | | -# Per-Language Advice |
96 | | - |
97 | | -## Python |
98 | | - |
99 | | -### Essentials |
100 | | - |
101 | | -- Avoid namespace pollution - use private aliases and `__` subpackage. |
102 | | -- Organize modules in specific order: imports → type aliases → defaults → public API → private functions. |
103 | | -- Maintain readability with spaces inside of delimiters. |
104 | | -- Maintain readability with vertical compactness of function bodies. |
105 | | -- Prefer immutability wherever possible. |
106 | | -- Use wide abstract types for function parameters (`__.cabc.Sequence`, `__.cabc.Mapping`). |
107 | | -- Return narrow concrete types (`list`, `dict`, `frozenset`, `__.immut.Dictionary`). |
108 | | -- Use narrow try blocks (only risky statements). |
109 | | -- Subclass `Omniexception` or `Omnierror` for package-specific exceptions. |
110 | | - |
111 | | -**Example:** |
112 | | - |
113 | | -```python |
114 | | -# ✅ Correct: proper spacing, wide parameters, narrow returns, proper imports |
115 | | -import aiofiles as _aiofiles |
116 | | - |
117 | | -from . import __ |
118 | | - |
119 | | -UserData: __.typx.TypeAlias = dict[ str, str | int ] |
120 | | - |
121 | | -def process_items( |
122 | | - items: __.cabc.Sequence[ str ], # Wide input type |
123 | | - config: __.cabc.Mapping[ str, int ] = __.immut.Dictionary( ) |
124 | | -) -> tuple[ str, ... ]: # Narrow return type |
125 | | - ''' Processes items according to configuration. ''' |
126 | | - return tuple( item.upper( ) for item in items ) |
127 | | -``` |
128 | | - |
129 | | -### Quality Assurance |
130 | | - |
131 | | -- Ensure linters give a clean report: `hatch --env develop run linters` |
132 | | -- Address linting issues within the first few conversation turns from when they |
133 | | - appear. |
134 | | -- Do **not** suppress linter warnings via `noqa` pragma comments without |
135 | | - explicit user approval. |
136 | | -- Do **not** avoid `TRY003` exceptions from Ruff. Instead, use appropriate |
137 | | - custom exceptions in the `exceptions` module for the package. If an |
138 | | - appropriate exception does not exist, then create it. |
139 | | -- Do **not** suppress typechecker warnings via `type` pragma comments without |
140 | | - explicit user approval. For missing third-party stubs, you can generate them |
141 | | - with `hatch --env develop run pyright --createstub <import>` and then edit |
142 | | - the stubs (under `sources/<package>/_typedecls`) to flesh out what you need, |
143 | | - discarding the remainder. |
144 | | -- Ensure tests pass: `hatch --env develop run testers` |
145 | | -- Ensure documentation generates without error: `hatch --env develop run docsgen` |
| 17 | +- Use `rg --line-number --column` to get precise coordinates for MCP tools that require line/column positions. |
| 18 | +- Prefer `text-editor` MCP tools over other text editing tools (line number-based edits are less error-prone). |
| 19 | +- Always reread files with `text-editor` tools after modifying files via other tools to avoid file hash conflicts. |
| 20 | +- Batch related changes together to minimize file modification conflicts between different MCP tools. |
| 21 | +- Use relative paths rather than absolute paths when possible. |
| 22 | +- Do not write to paths outside the current project unless explicitly requested. |
| 23 | +- Use the `.auxiliary/scribbles` directory for scratch space instead of `/tmp`. |
146 | 24 |
|
147 | 25 | # Commits |
148 | 26 |
|
149 | | -- Try to avoid bundling multiple features or fixes into the same commit. |
150 | | - Commits should reflect natural development milestones. |
151 | | -- Use `git status` to ensure that all relevant changes are in the changeset to |
152 | | - be committed. |
153 | | -- Use the `code-conformer` agent to review all changes before committing. |
| 27 | +- Use `git status` to ensure all relevant changes are in the changeset. |
| 28 | +- Use the `python-conformer` agent to review changes that include Python code before committing. |
154 | 29 | - Do **not** commit without explicit user approval. |
155 | | -- Use present tense, imperative mood verbs to describe changes. E.g. "Fix" and |
156 | | - *not* "Fixed". |
157 | | -- Write sentences which end with proper punctuation. |
158 | | -- The commit message should include a `Co-Authored-By:` field as its final |
159 | | - line. The name of the author should be your model name. The email address |
160 | | - should either be one which you have been designated to use or else a |
161 | | - commonly-known no-reply address. |
| 30 | +- Use present tense, imperative mood verbs (e.g., "Fix" not "Fixed"). |
| 31 | +- Write sentences with proper punctuation. |
| 32 | +- Include a `Co-Authored-By:` field as the final line. Should include the model name and a no-reply address. |
| 33 | + |
| 34 | +# Project Notes |
| 35 | + |
| 36 | +<!-- This section accumulates project-specific knowledge, constraints, and deviations. |
| 37 | + For structured items, use documentation/architecture/decisions/ and .auxiliary/notes/todo.md --> |
0 commit comments