mirror of
https://github.com/MLSysBook/TinyTorch.git
synced 2025-12-05 19:17:52 -06:00
0d6807cefb
- Removed 30 debugging and development artifact files - Kept core system, documentation, and demo files - tests/milestones: 9 clean files (system + docs) - milestones/05_2017_transformer: 5 clean files (demos) - Clear, focused directory structure - Ready for students and developers
160 lines
4.3 KiB
Markdown
160 lines
4.3 KiB
Markdown
# 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/`)
|
|
|
|
## Command Output Preferences
|
|
|
|
**NEVER use pipe commands (|) to filter terminal output**
|
|
- User wants to see FULL, RAW output from all commands
|
|
- Do NOT use: `| tail`, `| grep`, `| head`, or similar filters
|
|
- Show complete output so user can see everything
|
|
- Examples of what NOT to do:
|
|
- ❌ `command 2>&1 | tail -50`
|
|
- ❌ `command | grep "pattern"`
|
|
- ❌ `command | head -10`
|
|
- Instead, just run: `command` or `command 2>&1`
|
|
|
|
## 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/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.
|
|
|