🌐 Connect with Sahin
**Transform your AI assistant from a helpful tool into a disciplined, systematic, and highly efficient development partner**
[Quick Start](#-quick-start) • [Core Philosophy](#-core-philosophy) • [Visual Workflow](#-visual-workflow-architecture) • [Rule System](#-rule-system) • [Testing](#-testing-strategy) • [Best Practices](#-best-practices)
📖 Table of Contents
- Introduction
- Quick Start
- Core Philosophy
- Visual Workflow Architecture
- System Components
- Rule System
- Workflow Methodology
- Testing Strategy
- Development Standards
- Best Practices
- 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
Clone the Repository
git clone https://github.com/yourusername/sahin-ai-rules.git
cd sahin-ai-rules
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
Configure Your AI Assistant
- Place
CLAUDE.mdin your project root - Ensure
.cursor/rules/directory is properly structured - AI assistants will automatically read and follow the rules
- Place
🧠 Core Philosophy
The Three Pillars
1. Plan Before Action
USER REQUEST → ANALYSIS → PLAN → APPROVAL → EXECUTION
2. High ROI Development
ROI = (User Impact × Usage Frequency) / Lines of Code
3. User-First Testing
USER STORY → E2E TEST → IMPLEMENTATION → VERIFICATION
🏗️ 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] │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
📋 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 │
└─────────────────┘
📝 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 │
└─────────────────────┘
🔄 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 │
└─────────────────┘
🎯 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 │
└─────────────────────┴─────────────────────┘
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 │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘
🎭 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 │
└─────────────┘
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 │
└─────────────────┘
📊 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 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
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
🔄 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 │
└─────────────────────────────┘
🎯 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 │
└─────────────────────────────────────────────────────────────────┘
🏗️ 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]
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
3. Todo Management System
Task Queue Structure:
├── Pending [□□□□□] (waiting)
├── Active [▶□□□□] (in progress)
├── Complete [✓✓✓□□] (done)
└── Failed [✗] (retry needed)
📚 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│
└──────────────┘
🔄 Workflow Methodology
Complete Todo-Driven Flow
REQUEST → ANALYZE → PLAN → APPROVE → TODO → EXECUTE → TEST → CHANGELOG
↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
[User] [Rules] [Tasks] [User] [File] [Code] [E2E] [History]
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...]
🧪 Testing Strategy
Testing Pyramid Implementation
/\
/E2E\ ← 70% effort (User flows)
/------\
/ API \ ← 20% effort (Integration)
/----------\
/ Unit \ ← 10% effort (Functions)
/--------------\
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
💎 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)
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 }
});
};
🏆 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";
}
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)
📊 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% │
└────────────────────────────────────┘
🚨 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
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
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