# 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
```
<type>: <short summary>

<optional detailed description>
```

**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 <module_name>`

### 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.

