diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..146effe
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,200 @@
+# Claude Development Guidelines
+
+This document establishes development patterns and workflows for maintaining clean, trackable progress on the PokeGoalsHelper2 project.
+
+## Git Workflow
+
+### Branch Naming Convention
+Use descriptive branch names following this pattern:
+- `feature/description-of-feature`
+- `bugfix/description-of-bug`
+- `refactor/description-of-refactor`
+- `docs/description-of-documentation`
+
+Examples:
+- `feature/floating-orb-ui`
+- `bugfix/image-buffer-leak`
+- `refactor/mvc-architecture`
+
+### Commit Guidelines
+
+#### Commit Early and Often
+- Commit after each logical change or completion of a small task
+- Don't wait to complete entire features before committing
+- Use the TodoWrite tool to track progress and commit when todos are completed
+
+#### Commit Message Format
+```
+<type>: <brief description>
+
+<optional detailed description>
+
+Related todos: #<todo-id>, #<todo-id>
+```
+
+Types:
+- `feat`: New feature
+- `fix`: Bug fix  
+- `refactor`: Code refactoring
+- `docs`: Documentation
+- `test`: Testing
+- `style`: Code formatting/style
+
+Examples:
+```
+feat: add floating orb UI with expandable menu
+
+Implemented CalcIV-style floating orb that expands to show
+detection and filter options. Replaces old button grid layout.
+
+Related todos: #22
+```
+
+```
+fix: resolve ImageReader buffer leak causing logcat spam
+
+- Increased buffer count from 2 to 3
+- Added proper image cleanup in triggerManualDetection()
+- Ensures images are closed after processing
+
+Related todos: #buffer-fix
+```
+
+### Branch Management
+
+1. **Create branch for each task/feature**
+   ```bash
+   git checkout -b feature/<description>
+   ```
+
+2. **Commit frequently during development**
+   ```bash
+   git add .
+   git commit -m "feat: implement basic orb button structure"
+   ```
+
+3. **Push branch and create PR when complete**
+   ```bash
+   git push origin feature/<description>
+   ```
+
+4. **Merge to main and delete feature branch**
+   ```bash
+   git checkout main
+   git merge feature/<description>
+   git branch -d feature/<description>
+   ```
+
+## Architecture Guidelines
+
+### Separation of Concerns
+
+#### UI Layer (Views)
+- Handle only UI interactions and display
+- No business logic or direct data manipulation
+- Communicate via events/callbacks
+
+#### Business Logic Layer (Controllers/Services)  
+- Handle core application logic
+- Process data and make decisions
+- Independent of UI implementation
+
+#### Data Layer (Models)
+- Manage data structures and persistence
+- Handle API calls and data transformations
+- Pure data operations
+
+### Event-Driven Communication
+
+Use callbacks and event buses to decouple UI from business logic:
+
+```kotlin
+// UI publishes events
+interface DetectionUIEvents {
+    fun onDetectionRequested()
+    fun onClassFilterChanged(className: String?)
+    fun onDebugModeToggled()
+}
+
+// Business logic handles events
+class DetectionController : DetectionUIEvents {
+    override fun onDetectionRequested() {
+        // Handle detection logic
+        // Notify UI via callbacks
+    }
+}
+```
+
+### File Organization
+
+```
+app/src/main/java/com/quillstudios/pokegoalshelper/
+├── ui/
+│   ├── FloatingOrbUI.kt           # UI components
+│   ├── DetectionOverlay.kt        # Visual overlays
+│   └── interfaces/
+│       └── DetectionUIEvents.kt   # UI event interfaces
+├── controllers/
+│   ├── DetectionController.kt     # Business logic
+│   └── ScreenCaptureController.kt # Screen capture logic  
+├── models/
+│   ├── Detection.kt               # Data models
+│   ├── PokemonInfo.kt            # Domain models
+│   └── DetectionSettings.kt       # Configuration
+└── services/
+    ├── YOLOOnnxDetector.kt       # YOLO inference
+    └── ScreenCaptureService.kt    # Android service
+```
+
+## Development Best Practices
+
+### Testing Approach
+- Test business logic separately from UI
+- Mock UI interactions for controller tests
+- Use dependency injection for testability
+
+### Code Quality
+- Single responsibility principle
+- Minimize coupling between layers
+- Use interfaces for dependency injection
+- Keep functions small and focused
+
+### Documentation
+- Update this file when patterns change
+- Document complex business logic
+- Use clear variable and function names
+- Add TODO comments for future improvements
+
+## Current Architecture Status
+
+### Phase 1: Current State (Coupled)
+- UI and business logic mixed in ScreenCaptureService
+- Direct calls between UI and YOLO detector
+- Monolithic service class
+
+### Phase 2: Target State (Decoupled)
+- Separate UI components with event interfaces
+- Controller layer handling business logic
+- Clean dependency injection
+- Testable, maintainable architecture
+
+## Commit Reminders
+
+Before each commit, ensure:
+- [ ] Code follows separation of concerns
+- [ ] No business logic in UI classes
+- [ ] Interfaces used for layer communication
+- [ ] Todo list updated with progress
+- [ ] Commit message follows format guidelines
+- [ ] Branch name is descriptive
+
+## Claude Instructions
+
+When working on this project:
+1. Always create a new branch for each task
+2. Commit frequently with descriptive messages
+3. Use TodoWrite tool to track progress
+4. Follow MVC/event-driven patterns
+5. Separate UI logic from business logic
+6. Test changes incrementally
+7. Update documentation when architecture changes
\ No newline at end of file