TinyTorch/.shared-ai-rules.md

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.