π Sahin AI Rules - The Ultimate AI Assistant Development Framework
π Connect with Sahin
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
- 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.md
in 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
- π Full Documentation
- π Report Issues
- π€ Contribute
- π¬ Discussions
- π§ Contact
π 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
Top comments (0)