| name | common-development |
| description | Common rules for code development that apply across all project types (libraries, CLI tools, services, etc.). Covers requirements clarity, bug-fix workflow, logging, coding style, testing discipline, version management, and commit conventions. |
| metadata | {"author":"vsirotin","version":"1.3"} |
Common Development Rules
These rules apply to all code development activities in this project, regardless of whether the target is a library, CLI tool, or service.
Rules
1. Requirements must be clear and feasible
Functional and technical requirements must be provided in an understandable and feasible form before implementation begins. If requirements are ambiguous, ask the user for clarification.
2. Bug-fix workflow (TDD)
When fixing a bug, always follow this order:
- Write a unit test that fails because of the bug.
- Run the test to confirm it fails.
- Fix the code.
- Run the test to confirm it passes.
- Report the result.
3. Logging by default
All functions must include logging. If the specification does not describe logging, use best practices for the language (e.g. a @logged decorator for entry/exit, structured log fields for errors).
4. Consistent coding style
Use best practices of the programming language, but maintain a common, consistent style across the entire project. Do not mix conventions within one codebase.
5. Document environment dependencies
If a function uses data from environment variables or files, this must be mentioned in the function's documentation.
6. Unit test coverage expectations
If technically possible, unit tests should contain test cases for:
- All code paths — every branch in the tested function (decisions made with
if, switch, match, etc.).
- Timeout worst cases — worst-case timeout scenarios for language constructs like
await on internal calls.
- Broken or unavailable connections — worst cases for unavailable or broken external connections. If mocking is not easy, consider proposing a manual test (e.g. the user manually breaks the internet connection and runs a test script). Propose this when the programming language, frameworks, and tools support it.
- Missing or invalid environment variables — worst cases for unavailable or wrongly-valued environment variables used internally.
7. Test function naming convention
Use the following naming pattern for test functions:
test_<subject_under_test>_<aspect>
<subject_under_test> — what is being tested (for unit tests of a single function, use the function name).<aspect> — short abbreviation for the tested aspect (up to 10 characters), e.g. timeout, no_conn, bad_env.
8. Group unit tests into sub-directories
When a project has many unit tests (more than 5), try to group them into sub-directories by topic or module.
9. All unit tests must pass
After completing development, all unit tests in the project must be processed with success.
10. Clean up temporary test artifacts
After running tests, delete any temporary directories or files created during the test run (e.g. output or download directories produced in dist/ by integration tests). Leave the project tree in the same state it was before the tests ran.
11. Stop on unsolvable problems
If you see suddenly that you cannot solve some problem, stop the development and ask me.
12. Stop on long bug-fix loops
If you try to fix the same bug too long (more than 20 iterations), stop the development and ask me.
13. Test dependent projects
When a library changes, also run the tests of projects that depend on it. Discover dependents by scanning pyproject.toml files in the workspace for the library name in their dependencies list.
14. Post-task checklist
After completing a task that makes essential changes, apply the post-task skill (version bump, release notes, commit text proposal).
