sirian/template-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reiterate the conventions

Browse Source
This commit is contained in:
Elias Ahokas
2026-06-17 23:06:45 +03:00
parent ffff52d361
commit 37f595a377
1 changed files with 30 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

44
CONVENTIONS.md
View File

@@ -1,23 +1,39 @@
# CONVENTIONS
Rules ai tools must follow
Rules for AI coding assistants working in this project.
## General
- Write code you understand yourself. If you cannot explain a line it doesn't belong here
## Code style
- Follow the existing style in whatever file you're reading
- Run the project's linter after every change and fix all issues
- No "clever" one-liners if a longer form is clearer
- Function name says what it does, docstring why
- No comments that restate the code. Comments say "why" not "what"
- No comments that restate the code. Comments explain "why" not "what"
## Git
- One logical change per commit
- Commit message in active voice: "add feature x" NOT "added feature X"
## Naming
- Files and directories: snake_case
- Functions and variables: snake_case
- Classes: PascalCase
- Database tables: snake_case, plural
- No single-letter variable names. Except "i", "j", "k" in loop index
## Patterns
- Every API endpoint validates input before processing.
- Errors use the frameworks standard error mechanism. Dont invent your own.
## What NOT to do
- Do not add new dependencies without explicit instruction. If proposing a dependency describe it in plain text. Do not install it.
- Do not refactor adjacent code "while you're at it". Stay within the scope of the request.
- Do not assume environment variables exist. If a new environment variable is needed state it clearly and add it to '.env.example'
- Do not suppress type checker or linter errors without a comment explaining why.
- Do not commit code that fails lint, type check or tests.
- No new dependencies without discussion (propose to ARCH.md, don't add)
- Don't mess with code style. Follow what is already there
- Don't refactor adjacent code "while you're at it"
- No assumed environment variables without decumenting in ARCH.md
## Git
- One logical change per commit
- Commit messages are in imperative mood, lowercase and max 72 char title.
- Good: "add email validation to user signup"
- BAD: "added email validation to user signup"
- BAD: "fix stuff"
## Testing
- Test files mirror source structure: "src/users/service.py" -> "tests/users/test_service.py"
- Mock only external IO boundaries. Never mock our own modules, services or utilities.
- Every new endpoint needs at minimum one test for the success case and one test for a validation error case.