DEV Community

Sahin Boydas
Sahin Boydas

Posted on

Sahin AI Rules - The Ultimate AI Assistant Development Framework

πŸš€ Sahin AI Rules - The Ultimate AI Assistant Development Framework

🌐 Connect with Sahin

LinkedIn
Twitter


Version
Status
Compliance
Framework

Transform your AI assistant from a helpful tool into a disciplined, systematic, and highly efficient development partner

Quick Start β€’ Core Philosophy β€’ Visual Workflow β€’ Rule System β€’ Testing β€’ Best Practices


πŸ“– Table of Contents

  1. Introduction
  2. Quick Start
  3. Core Philosophy
  4. Visual Workflow Architecture
  5. System Components
  6. Rule System
  7. Workflow Methodology
  8. Testing Strategy
  9. Development Standards
  10. Best Practices
  11. Implementation Guide

🎯 Introduction

Sahin AI Rules is a comprehensive framework that transforms AI assistants from reactive helpers into proactive, disciplined development partners. This system enforces strict workflow compliance, systematic planning, and measurable outcomes through a battle-tested rule architecture.

Why This Framework Exists

Traditional AI assistants suffer from:

  • ❌ Immediate Action Syndrome: Jumping to code without planning
  • ❌ Context Overload: Poor memory and context management
  • ❌ Inconsistent Quality: Varying approaches to similar problems
  • ❌ Over-Engineering: Building complex solutions for simple problems
  • ❌ Testing Negligence: Skipping or minimal testing coverage

This framework solves these problems through:

  • βœ… Mandatory Planning: Every action requires approved plans
  • βœ… Smart Context Management: Dynamic rule loading based on task
  • βœ… High-ROI Development: Maximize impact, minimize code
  • βœ… Testing-First Approach: User flows drive development
  • βœ… Systematic Workflow: Todo-driven development with tracking

πŸš€ Quick Start

Installation

  1. Clone the Repository
git clone https://github.com/yourusername/sahin-ai-rules.git
cd sahin-ai-rules
Enter fullscreen mode Exit fullscreen mode
  1. Set Up Your Project
# Copy the rules directory to your project
cp -r rules /your/project/.cursor/rules/

# Create the main configuration file
cp CLAUDE.md /your/project/CLAUDE.md
Enter fullscreen mode Exit fullscreen mode
  1. Configure Your AI Assistant
    • Place CLAUDE.md in your project root
    • Ensure .cursor/rules/ directory is properly structured
    • AI assistants will automatically read and follow the rules

🧠 Core Philosophy

The Three Pillars

1. Plan Before Action

USER REQUEST β†’ ANALYSIS β†’ PLAN β†’ APPROVAL β†’ EXECUTION
Enter fullscreen mode Exit fullscreen mode

2. High ROI Development

ROI = (User Impact Γ— Usage Frequency) / Lines of Code
Enter fullscreen mode Exit fullscreen mode

3. User-First Testing

USER STORY β†’ E2E TEST β†’ IMPLEMENTATION β†’ VERIFICATION
Enter fullscreen mode Exit fullscreen mode

πŸ—οΈ Visual Workflow Architecture

Complete System Overview

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                          CLAUDE WORKFLOW SYSTEM                                β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                                                                                 β”‚
β”‚  User Request β†’ Analysis β†’ Plan β†’ Approval β†’ Todo β†’ Execute β†’ Changelog      β”‚
β”‚       ↓           ↓        ↓        ↓        ↓       ↓         ↓              β”‚
β”‚   [Natural    [Context] [Task    [User    [Auto   [Work    [History]          β”‚
β”‚    Language]   Rules]   List]    OK/NO]    File]   Loop]    Track]            β”‚
β”‚                                                                                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

πŸ“‹ Phase 1: Request Analysis & Planning

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                              PHASE 1: ANALYSIS                                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                      β”‚
                                      β–Ό
                            β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                            β”‚  User Request   β”‚
                            β”‚                 β”‚
                            β”‚ "Build login    β”‚
                            β”‚  with tests"    β”‚
                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                      β”‚
                                      β–Ό
                            β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                            β”‚ Load Rules      β”‚
                            β”‚                 β”‚
                            β”‚ β€’ Workflow      β”‚
                            β”‚ β€’ Testing       β”‚
                            β”‚ β€’ High-ROI      β”‚
                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                      β”‚
                                      β–Ό
                            β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                            β”‚ Analyze         β”‚
                            β”‚ Requirements    β”‚
                            β”‚                 β”‚
                            β”‚ β€’ Features      β”‚
                            β”‚ β€’ User Flows    β”‚
                            β”‚ β€’ Dependencies  β”‚
                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                      β”‚
                                      β–Ό
                            β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                            β”‚ Create Plan     β”‚
                            β”‚                 β”‚
                            β”‚ β€’ Task List     β”‚
                            β”‚ β€’ Priorities    β”‚
                            β”‚ β€’ Estimates     β”‚
                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                      β”‚
                                      β–Ό
                            β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                            β”‚ Show to User    β”‚ ←── "Would you like me to proceed?"
                            β”‚                 β”‚
                            β”‚ Plan Format     β”‚
                            β”‚ with Tasks      β”‚
                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

πŸ“ Phase 2: Todo Creation & Task Management

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                            PHASE 2: TODO CREATION                              β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

User Approves Plan
        β”‚
        β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Generate Todo   β”‚
β”‚ File            β”‚
β”‚                 β”‚
β”‚ tasks-YYYY.md   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
        β”‚
        β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Task 1          β”‚    β”‚ Task 2          β”‚    β”‚ Task 3          β”‚
β”‚ [ ] Login UI    β”‚    β”‚ [ ] Auth Logic  β”‚    β”‚ [ ] Tests       β”‚
β”‚                 β”‚    β”‚                 β”‚    β”‚                 β”‚
β”‚ Files: 3        β”‚    β”‚ Files: 2        β”‚    β”‚ Files: 5        β”‚
β”‚ LOC: ~50        β”‚    β”‚ LOC: ~30        β”‚    β”‚ LOC: ~100       β”‚
β”‚ Priority: High  β”‚    β”‚ Priority: High  β”‚    β”‚ Priority: Med   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
        β”‚                       β”‚                       β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                β”‚
                                β–Ό
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚ Context Window      β”‚
                    β”‚ Size Check          β”‚
                    β”‚                     β”‚
                    β”‚ Split if > 80%      β”‚
                    β”‚ of context limit    β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

πŸ”„ Phase 3: Execution Loop

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                           PHASE 3: EXECUTION LOOP                              β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                        β”‚ Get Next Task   β”‚ ←─────────────────┐
                        β”‚ from Todo       β”‚                  β”‚
                        β”‚                 β”‚                  β”‚
                        β”‚ [ ] β†’ [πŸ”„]      β”‚                  β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β”‚
                                β”‚                            β”‚
                                β–Ό                            β”‚
                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                  β”‚
                        β”‚ Execute Task    β”‚                  β”‚
                        β”‚                 β”‚                  β”‚
                        β”‚ High-ROI Rules: β”‚                  β”‚
                        β”‚ β€’ Min LoC       β”‚                  β”‚
                        β”‚ β€’ Max Impact    β”‚                  β”‚
                        β”‚ β€’ User-First    β”‚                  β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β”‚
                                β”‚                            β”‚
                                β–Ό                            β”‚
                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                  β”‚
                        β”‚ Create Files    β”‚                  β”‚
                        β”‚                 β”‚                  β”‚
                        β”‚ Playwright      β”‚                  β”‚
                        β”‚ Tests First     β”‚                  β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β”‚
                                β”‚                            β”‚
                                β–Ό                            β”‚
                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                  β”‚
                        β”‚ Test & Verify   β”‚                  β”‚
                        β”‚                 β”‚                  β”‚
                        β”‚ User Flows      β”‚                  β”‚
                        β”‚ Work?           β”‚                  β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β”‚
                                β”‚                            β”‚
                                β–Ό                            β”‚
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                     β”‚
                     β”‚ Mark Complete   β”‚                     β”‚
                     β”‚                 β”‚                     β”‚
                     β”‚ [πŸ”„] β†’ [βœ…]     β”‚                     β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                     β”‚
                                β”‚                            β”‚
                                β–Ό                            β”‚
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                     β”‚
                     β”‚ Move to         β”‚                     β”‚
                     β”‚ Changelog       β”‚                     β”‚
                     β”‚                 β”‚                     β”‚
                     β”‚ + Timestamp     β”‚                     β”‚
                     β”‚ + Files Changed β”‚                     β”‚
                     β”‚ + Test Results  β”‚                     β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                     β”‚
                                β”‚                            β”‚
                                β–Ό                            β”‚
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                     β”‚
                     β”‚ More Tasks?     β”‚ ──Yesβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                     β”‚                 β”‚
                     β”‚ Check Todo      β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                β”‚
                               No
                                β–Ό
                     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                     β”‚ Session         β”‚
                     β”‚ Complete        β”‚
                     β”‚                 β”‚
                     β”‚ Show Summary    β”‚
                     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

🎯 High-ROI Development Strategy

Decision Matrix Visualization

                    High Impact              Low Impact
                β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
    Low LoC     β”‚     πŸš€ DO FIRST     β”‚    βœ… DO NEXT      β”‚
                β”‚                     β”‚                     β”‚
                β”‚ β€’ User login        β”‚ β€’ UI polish        β”‚
                β”‚ β€’ Critical bugs     β”‚ β€’ Nice-to-haves    β”‚
                β”‚ β€’ Core features     β”‚ β€’ Minor features   β”‚
                └─────────────────────┼──────────────────────
    High LoC    β”‚    ⚠️ MINIMIZE      β”‚    ❌ AVOID        β”‚
                β”‚                     β”‚                     β”‚
                β”‚ β€’ Complex features  β”‚ β€’ Over-engineering β”‚
                β”‚ β€’ Must-have only    β”‚ β€’ Premature optim  β”‚
                β”‚ β€’ Break into steps  β”‚ β€’ Scope creep      β”‚
                β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

Code Change Strategy Flow

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                            MINIMIZE LOC CHANGES                                 β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚                                                                                 β”‚
β”‚  1. Reuse Existing β†’ 2. Extend Current β†’ 3. Create New (only if needed)       β”‚
β”‚                                                                                 β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”     β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                     β”‚
β”‚  β”‚ Check:      β”‚     β”‚ Modify:     β”‚     β”‚ Build:      β”‚                     β”‚
β”‚  β”‚             β”‚     β”‚             β”‚     β”‚             β”‚                     β”‚
β”‚  β”‚ β€’ Components│────▢│ β€’ Add props │────▢│ β€’ New files β”‚                     β”‚
β”‚  β”‚ β€’ Hooks     β”‚     β”‚ β€’ Extend fn β”‚     β”‚ β€’ Only when β”‚                     β”‚
β”‚  β”‚ β€’ Utils     β”‚     β”‚ β€’ Add types β”‚     β”‚   necessary β”‚                     β”‚
β”‚  β”‚ β€’ Types     β”‚     β”‚ β€’ Small add β”‚     β”‚ β€’ Minimal   β”‚                     β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜     β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                     β”‚
β”‚                                                                                 β”‚
β”‚  Target: 80% reuse, 15% extend, 5% new                                        β”‚
β”‚                                                                                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

🎭 Playwright-First Testing Flow

User Experience Driven Development

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                         PLAYWRIGHT-FIRST APPROACH                              β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Start with User Story
        β”‚
        β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ "As a user,     β”‚
β”‚  I want to      β”‚
β”‚  login so I     β”‚
β”‚  can access     β”‚
β”‚  my account"    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
        β”‚
        β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Write E2E Test  β”‚    β”‚ Create UI       β”‚    β”‚ Add Logic       β”‚
β”‚                 β”‚    β”‚                 β”‚    β”‚                 β”‚
β”‚ test('login')   β”‚ ──▢│ LoginForm.tsx   β”‚ ──▢│ useAuth.ts      β”‚
β”‚ .fill(email)    β”‚    β”‚ Input fields    β”‚    β”‚ API calls       β”‚
β”‚ .fill(password) β”‚    β”‚ Submit button   β”‚    β”‚ State mgmt      β”‚
β”‚ .click(login)   β”‚    β”‚ Error handling  β”‚    β”‚ Validation      β”‚
β”‚ .expect(url)    β”‚    β”‚                 β”‚    β”‚                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
        β”‚                       β”‚                       β”‚
        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                β”‚
                                β–Ό
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚ Test Passes?        β”‚
                    β”‚                     β”‚
                    β”‚ User can actually   β”‚
                    β”‚ login successfully  β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                β”‚
                           Yes  β”‚  No
                                β–Ό
                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                        β”‚ Task        β”‚
                        β”‚ Complete    β”‚ ←─── Fix & Retry
                        β”‚             β”‚
                        β”‚ βœ… Working  β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

Test-First Development Cycle

User Flow β†’ E2E Test β†’ Implementation β†’ Verification
    ↑                                        β”‚
    └────────────── Feedback Loop β†β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β”‚ Each Feature:   β”‚
                    β”‚                 β”‚
                    β”‚ 1. User story   β”‚
                    β”‚ 2. E2E test     β”‚
                    β”‚ 3. Minimal code β”‚
                    β”‚ 4. Test passes  β”‚
                    β”‚ 5. Refactor     β”‚
                    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

πŸ“Š Context Window Management

Task Splitting Strategy

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                          CONTEXT WINDOW OPTIMIZATION                           β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                        β”‚ Large Feature   β”‚
                        β”‚ Request         β”‚
                        β”‚                 β”‚
                        β”‚ "Build complete β”‚
                        β”‚  auth system"   β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                β”‚
                                β–Ό
                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                        β”‚ Analyze Size    β”‚
                        β”‚                 β”‚
                        β”‚ Estimate:       β”‚
                        β”‚ β€’ Files: 15     β”‚
                        β”‚ β€’ LoC: 800      β”‚
                        β”‚ β€’ Context: 90%  β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                β”‚
                                β–Ό
                        β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                        β”‚ Split Strategy  β”‚
                        β”‚                 β”‚
                        β”‚ Rule: Each task β”‚
                        β”‚ ≀ 70% context   β”‚
                        β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                β”‚
                                β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Task 1          β”‚    β”‚ Task 2          β”‚    β”‚ Task 3          β”‚
β”‚ Basic Login UI  β”‚    β”‚ Auth Logic      β”‚    β”‚ Advanced Auth   β”‚
β”‚                 β”‚    β”‚                 β”‚    β”‚                 β”‚
β”‚ Files: 3        β”‚    β”‚ Files: 4        β”‚    β”‚ Files: 8        β”‚
β”‚ Context: 45%    β”‚    β”‚ Context: 60%    β”‚    β”‚ Context: 70%    β”‚
β”‚ Dependencies: - β”‚    β”‚ Depends: Task1  β”‚    β”‚ Depends: Task2  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

Context Usage Monitor

Context Window Status:
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Used: 45% [β–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘β–‘] β”‚
β”‚                                                             β”‚
β”‚ Files Loaded: 8                                            β”‚
β”‚ Rules Loaded: 3                                            β”‚
β”‚ Todo Context: 15%                                          β”‚
β”‚ Code Context: 30%                                          β”‚
β”‚ Available: 55%                                             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Status: 🟒 Safe to continue
Action: βœ… Execute current task
Enter fullscreen mode Exit fullscreen mode

πŸ”„ Integration Flow

How Everything Connects

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                            INTEGRATION FLOW                                    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Workflow Router ←→ Rules System ←→ Todo Manager ←→ Task Execution
       β”‚              β”‚              β”‚              β”‚
       β”‚              β”‚              β”‚              β”‚
    Keywords       Load Rules     Create/Read    Execute with
    Detect         Based on       Todo Files     Context Limits
       β”‚           Keywords          β”‚              β”‚
       β”‚              β”‚              β”‚              β”‚
       β–Ό              β–Ό              β–Ό              β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Dynamic     β”‚ β”‚ Context     β”‚ β”‚ Progress    β”‚ β”‚ High-ROI    β”‚
β”‚ Loading     β”‚ β”‚ Aware       β”‚ β”‚ Tracking    β”‚ β”‚ Strategy    β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       β”‚              β”‚              β”‚              β”‚
       β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                      β”‚              β”‚
                      β–Ό              β–Ό
              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
              β”‚     Changelog System        β”‚
              β”‚                             β”‚
              β”‚ β€’ Track completed work      β”‚
              β”‚ β€’ Audit trail              β”‚
              β”‚ β€’ Progress history         β”‚
              β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

🎯 Success Metrics

Workflow Efficiency Targets

Target KPIs:
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ β€’ Context Usage: < 70% average                                 β”‚
β”‚ β€’ Task Completion: > 95%                                       β”‚
β”‚ β€’ Code Reuse: > 80%                                           β”‚
β”‚ β€’ New LoC: < 20% of total changes                             β”‚
β”‚ β€’ E2E Test Coverage: 100% of user flows                       β”‚
β”‚ β€’ User Story β†’ Working Feature: < 2 iterations                β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

πŸ—οΈ System Components

Component Architecture

1. Circuit Breaker System

Prevents immediate action through mandatory checkpoints:

00-circuit-breaker.md β†’ 01-plan-template.md β†’ 02-approval-gate.md β†’ 03-plan-content.md
        ↓                      ↓                     ↓                      ↓
   [Stop Help]           [Format Plan]         [Get Approval]        [Show Content]
Enter fullscreen mode Exit fullscreen mode

2. Dynamic Rule Router

Intelligent rule loading based on keywords:

// Smart Loading System
Keywords Detected β†’ Rules Loaded β†’ Context Optimized
    "API"      β†’    api-design.md     β†’    40% context
    "test"     β†’    smart-testing.md  β†’    30% context
    "React"    β†’    react-patterns.md β†’    35% context
Enter fullscreen mode Exit fullscreen mode

3. Todo Management System

Task Queue Structure:
β”œβ”€β”€ Pending   [β–‘β–‘β–‘β–‘β–‘] (waiting)
β”œβ”€β”€ Active    [β–Άβ–‘β–‘β–‘β–‘] (in progress)
β”œβ”€β”€ Complete  [βœ“βœ“βœ“β–‘β–‘] (done)
└── Failed    [βœ—] (retry needed)
Enter fullscreen mode Exit fullscreen mode

πŸ“š Rule System

Rule Categories & Loading

Foundation Rules (Always Loaded)

Rule Purpose Context Cost
Core Workflow Execution process 5%
Coding Standards Code quality 3%
Documentation Doc requirements 2%
Project Overview Context/setup 4%

Conditional Rules (Smart Loading)

Keywords Rules Loaded Context Cost
API, endpoint, REST api-design, fastapi, security +8%
React, component, UI react-patterns, typescript +7%
test, testing, TDD core-standards, smart-testing +6%
database, SQL, query database-schema, migrations +5%
deploy, CI/CD, production deployment, git-workflow +6%

Rule Enforcement Flow

Request Received
       ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Load CLAUDE.mdβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Check Router β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Load Rules   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Create Plan  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
       ↓
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Wait Approvalβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

πŸ”„ Workflow Methodology

Complete Todo-Driven Flow

REQUEST β†’ ANALYZE β†’ PLAN β†’ APPROVE β†’ TODO β†’ EXECUTE β†’ TEST β†’ CHANGELOG
   ↓         ↓        ↓       ↓        ↓       ↓        ↓        ↓
[User]   [Rules]   [Tasks] [User]   [File]  [Code]  [E2E]   [History]
Enter fullscreen mode Exit fullscreen mode

Todo File Structure

# Tasks: Authentication System
Created: 2024-01-15
Priority: High
Context Budget: 70% per task

## Task Queue

### Task 1: Login UI
- [ ] Status: Pending
- **Files**: LoginForm.tsx, login.css
- **LoC**: ~50
- **Context**: ~30%
- **ROI**: High (10Γ—10/50 = 2.0)
- **Acceptance**:
  - [ ] Form renders
  - [ ] Validation works
  - [ ] E2E test passes

### Task 2: Auth Service
- [ ] Status: Pending
- **Dependencies**: Task 1
[continues...]
Enter fullscreen mode Exit fullscreen mode

πŸ§ͺ Testing Strategy

Testing Pyramid Implementation

         /\
        /E2E\      ← 70% effort (User flows)
       /------\
      /  API   \   ← 20% effort (Integration)
     /----------\
    /   Unit     \ ← 10% effort (Functions)
   /--------------\
Enter fullscreen mode Exit fullscreen mode

Smart Testing System

# Smart Test Detection Flow
Code Changed β†’ Analyze Impact β†’ Run Affected Tests Only
     ↓              ↓                    ↓
auth.service.ts β†’ Dependencies β†’ auth.test.ts + login.e2e.ts
                                  (5 seconds vs 3 minutes)

# Commands
npm run test:smart         # Run affected tests
npm run test:smart:dry     # Preview what will run
npm run test:smart:verbose # See why tests selected
Enter fullscreen mode Exit fullscreen mode

πŸ’Ž Development Standards

Code Quality Hierarchy

Level 1: Type Safety (TypeScript)
    ↓
Level 2: Code Standards (ESLint/Prettier)
    ↓
Level 3: Testing Coverage (80%+)
    ↓
Level 4: Documentation (Complete)
    ↓
Level 5: Performance (Optimized)
Enter fullscreen mode Exit fullscreen mode

High-ROI Code Examples

// ❌ LOW ROI - Custom everything (500 LoC)
class CustomAuthSystem {
  // Complex custom implementation
}

// βœ… HIGH ROI - Leverage existing (50 LoC)
const useAuth = () => {
  return useExistingAuthLibrary({
    provider: 'email',
    callbacks: { onSuccess, onError }
  });
};
Enter fullscreen mode Exit fullscreen mode

πŸ† Best Practices

The ROI Formula in Practice

// Calculate ROI for every feature
function calculateROI(feature) {
  const impact = getUserImpactScore();      // 1-10
  const frequency = getUsageFrequency();    // 1-10
  const linesOfCode = estimateLoC();        // number

  const roi = (impact * frequency) / linesOfCode;

  if (roi > 10) return "πŸš€ DO IMMEDIATELY";
  if (roi > 3)  return "βœ… SCHEDULE SOON";
  if (roi < 3)  return "⏳ DEFER OR REJECT";
}
Enter fullscreen mode Exit fullscreen mode

Code Reuse Decision Tree

Need Feature?
     β”‚
     β–Ό
Can Reuse Existing? ──Yes──→ Use It (0 LoC)
     β”‚No
     β–Ό
Can Extend Existing? ──Yes──→ Extend It (10 LoC)
     β”‚No
     β–Ό
Can Modify Slightly? ──Yes──→ Modify It (30 LoC)
     β”‚No
     β–Ό
Must Create New? ──Yes──→ Minimize It (50+ LoC)
Enter fullscreen mode Exit fullscreen mode

πŸ“Š Implementation Guide

Project Setup Checklist

  • [ ] Copy rules to .cursor/rules/
  • [ ] Place CLAUDE.md in project root
  • [ ] Configure smart testing
  • [ ] Set up todo templates
  • [ ] Create changelog structure
  • [ ] Configure CI/CD integration
  • [ ] Set up monitoring metrics

Measuring Success

Weekly Metrics Dashboard:
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ Features Completed:        8       β”‚
β”‚ Average LoC/Feature:      45       β”‚
β”‚ Code Reuse Rate:          82%      β”‚
β”‚ Test Coverage:            87%      β”‚
β”‚ E2E Tests Passing:        100%     β”‚
β”‚ Context Efficiency:       68%      β”‚
β”‚ Rule Compliance:          100%     β”‚
β”‚ User Satisfaction:        95%      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
Enter fullscreen mode Exit fullscreen mode

🚨 Common Issues & Solutions

Issue Solution
AI not following rules Ensure CLAUDE.md is in root with correct paths
Context overflow Use task splitting strategy (70% rule)
Slow tests Use npm run test:smart for affected tests only
Low ROI scores Focus on user impact and code reuse
Plan not created Check circuit breaker files are loaded

🎯 Key Success Mantras

πŸ›‘ "Stop and plan before you code"

Every line of code starts with a plan

πŸ§ͺ "Test what users do, not how code works"

E2E tests validate user success, not implementation

πŸ“Š "Maximum impact, minimum code"

ROI drives every decision

βœ… "Perfect is the enemy of good"

Ship working features, iterate later


πŸ“ˆ Results You Can Expect

Before vs After Implementation

Metric Before After Improvement
Planning Time 5% 15% More upfront thinking
Coding Time 70% 40% Less code needed
Testing Time 15% 30% Comprehensive coverage
Rework Rate 25% 5% 80% reduction
Code Reuse 20% 80% 4x improvement
Bug Rate High Low 90% reduction
Feature Delivery Slow Fast 2x faster

πŸ”— Additional Resources

Documentation Structure

docs/
β”œβ”€β”€ architecture/      # System design docs
β”œβ”€β”€ features/         # Feature specifications
β”œβ”€β”€ setup/           # Configuration guides
β”œβ”€β”€ testing/         # Test strategies
β”œβ”€β”€ workflows/       # Process documentation
└── best-practices/  # Guidelines and patterns
Enter fullscreen mode Exit fullscreen mode

Community & Support


🌟 Start Your Journey Today

Transform your AI assistant into a disciplined development partner

git clone https://github.com/yourusername/sahin-ai-rules.git
cd sahin-ai-rules
./install.sh
Enter fullscreen mode Exit fullscreen mode

Join hundreds of developers who have revolutionized their AI-assisted development

⭐ Star this repo β€’ πŸ”„ Fork it β€’ πŸ“’ Share it


Built with discipline, tested with rigor, delivered with confidence

Β© 2024 Sahin AI Rules Framework | MIT License

Making AI assistants work the way they should

Top comments (0)