# AI Agent Rules for Python Projects

**⚠️ READ AGENTS_RULES.md FOR COMPLETE DOCUMENTATION**

This is a quick reference. Full rules are in `AGENTS_RULES.md`.

## Quick Reference

### Workflow
1. **Plan** → Discuss with user
2. **Test** → Write failing tests first (TDD)
3. **Develop** → Implement with Python best practices
4. **Test** → `pytest --cov` (90% coverage minimum)
5. **Commit** → Get user approval first

### Python Best Practices
- **Type hints**: Always use type annotations
- **Dataclasses**: Use for data containers
- **Result pattern**: Return Result[T, Error] or use exceptions
- **f-strings**: Use for string formatting
- **List comprehensions**: Prefer over loops when readable
- **Context managers**: Use `with` for resources

### Code Quality
- ❌ No default values to hide errors
- ✅ Fail fast and explicit
- ✅ Type hints everywhere
- ✅ Docstrings for public APIs

### Testing
```bash
pytest tests/ -v --cov=src --cov-report=html
mypy src/
black src/ tests/
ruff check src/ tests/
```

### Git Rules
- ❌ NEVER `git stash`
- ❌ NEVER `git push` or `git push --force`
- ✅ ALWAYS ask user approval before commit

### Commit Format
```
<type>(agt): <description>

Types: feat, fix, refac, chore, doc, test
Example: feat(agt): add user authentication with JWT
```

### Tools
```bash
python -m pytest        # Test
black .                 # Format
mypy .                  # Type check
ruff check .            # Lint
pip install -e .        # Install dev
```

---

**📖 For complete rules, examples, and detailed guidelines:**
**Read `AGENTS_RULES.md` in this directory**
