template-project/CONVENTIONS.md

CONVENTIONS

Rules ai tools must follow

General

• Write code you understand yourself. If you cannot explain a line it doesn't belong here
• 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"

Git

• One logical change per commit
• Commit message in active voice: "add feature x" NOT "added feature X"

What NOT to do

• 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