diff --git a/.shared-ai-rules.md b/.shared-ai-rules.md new file mode 100644 index 00000000..98954bd8 --- /dev/null +++ b/.shared-ai-rules.md @@ -0,0 +1,147 @@ +# Shared AI Assistant Rules + +**These rules apply to ALL AI assistants working on this project (Cursor, Claude, GitHub Copilot, etc.)** + +## Git Commit Guidelines + +### Commit Structure +- **Make small, focused commits** - one logical change per commit +- **Never lump multiple unrelated changes** into a single commit +- Each module fix should be its own commit +- Each feature should be its own commit +- Each bug fix should be its own commit + +### Commit Message Format +``` +: + + +``` + +**Types:** +- `fix`: Bug fixes +- `feat`: New features +- `refactor`: Code restructuring +- `docs`: Documentation changes +- `test`: Test additions or fixes +- `chore`: Maintenance tasks + +**Rules:** +- **Never use exclamation marks** in commit messages +- Keep first line under 72 characters +- Use imperative mood: "Fix bug" not "Fixed bug" +- Be specific and descriptive +- Reference issue numbers when applicable + +**Good Examples:** +``` +Fix Module 06 optimizers AdamW gradient handling +Add KV cache support for transformer inference +Refactor attention masking to use standard conventions +``` + +**Bad Examples:** +``` +Fix stuff! +Update files +Changes +WIP +``` + +### What NOT to Commit +- Generated files (`.ipynb` notebooks - they're auto-generated from `.py`) +- `__pycache__/` directories +- Build artifacts +- Temporary files +- IDE-specific configuration (`.vscode/`, `.idea/`) +- AI assistant folders (`.cursor/`, `.claude/`, `.ai/`) + +## Code Quality + +### Critical Rules +- **Test every change** before moving to the next task +- **Run inline tests** immediately after defining them +- **Never skip testing** - it catches issues early +- **Check imports** - ensure all dependencies are available + +### Development Workflow +1. Make a change +2. Test the change +3. Verify it works +4. Commit (small, focused commit) +5. Move to next change + +**Never:** +- Make multiple changes without testing +- Commit untested code +- Bundle unrelated changes together + +## TinyTorch-Specific Rules + +### Module Development +- All source code lives in `modules/source/XX_name/name_dev.py` +- `.ipynb` files are generated - don't edit them directly +- Use `tito export` to sync changes to the package +- Test with `tito test ` + +### Testing Philosophy +- **Inline tests** = component validation within modules +- **`tests/` directory** = integration tests across modules +- Every module must have passing inline tests +- Integration tests verify modules work together + +### Code Organization +- Avoid duplication - create shared utilities +- Follow existing module structure +- Maintain consistent formatting +- Use the project's established patterns + +## Communication + +### With the User +- Be direct and concise +- Don't ask for permission for standard operations +- Propose solutions, don't just describe problems +- Show progress with concrete results + +### In Code +- Write clear, educational comments +- Explain non-obvious decisions +- Document complex algorithms +- Use meaningful variable names + +## Efficiency + +### Tool Usage +- Use specialized tools over terminal commands when available +- Make parallel tool calls when operations are independent +- Read multiple files simultaneously when needed +- Batch related operations + +### Problem Solving +- **Be proactive** - fix issues when you find them +- **Think critically** - challenge assumptions +- **Consider edge cases** - don't just test happy paths +- **Learn from errors** - patterns repeat + +## Quality Standards + +### Before Committing +- [ ] All tests pass +- [ ] No linter errors +- [ ] Imports are correct +- [ ] Code follows project style +- [ ] Commit message is clear and specific +- [ ] Only changed files are included + +### Before Marking Complete +- [ ] Feature works as intended +- [ ] Edge cases are handled +- [ ] Documentation is updated +- [ ] Tests are passing +- [ ] No regressions introduced + +--- + +**Remember:** Quality over speed. Small, tested, well-documented commits are better than large, untested, rushed ones. +