AI Coding Guideline - Templates

.cursorrules.md

Cursor Rules - Anti-Overengineering Guidelines

Note: After reading, remove CAREER IMPACT REMINDER as your AI won't need it :). Also, rename this file to cursorrules. I adeed .md extension so github renders it better as makrdown

🎯 MINIMAL CODE CHANGES PRINCIPLE

• ALWAYS start with the simplest possible solution
• NEVER create new files unless absolutely necessary
• PREFER editing existing files over creating new ones
• Question if you're solving the right problem before implementing

📋 REQUIRED PROCESS BEFORE IMPLEMENTATION

1. Problem Analysis: Clearly identify the root cause
2. Solution Brainstorm: List 3+ possible solutions, from simplest to complex
3. Impact Assessment: How many files/lines of code will change?
4. Justification: Why is this the minimal viable solution?
5. Implementation: Only proceed after steps 1-4

⚠️ RED FLAGS - STOP AND RECONSIDER

• Creating more than 2 new files for a single issue
• Adding more than 50 lines of code for a simple fix
• Creating "alternative" or "offline" versions of existing functionality
• Building infrastructure when a configuration change would work
• Adding abstraction layers when direct solutions exist

🚫 ANTI-PATTERNS TO AVOID

• Over-engineering: Don't build for hypothetical future requirements
• Premature optimization: Solve the actual problem, not imaginary ones
• Feature creep: Stick to the original request scope
• Copy-paste architecture: Don't duplicate existing patterns unnecessarily
• "Future-proofing": Build for today's needs, not tomorrow's maybes

✅ PREFERRED PATTERNS

• Single-purpose changes: One problem, one minimal solution
• Configuration over code: Use env vars, flags, or settings when possible
• Existing tool leverage: Use built-in features before building custom ones
• Progressive enhancement: Start minimal, add complexity only when needed
• Explicit trade-offs: Document why complexity was necessary

🔍 VALIDATION QUESTIONS

Before implementing any solution, ask:

1. "Is there a way to solve this without writing new code?"
2. "Can I solve this by changing configuration instead?"
3. "Am I solving the stated problem or a problem I imagined?"
4. "Will this solution create more problems than it solves?"
5. "Can a user accomplish the same goal with existing features?"

🎱 DECISION FRAMEWORK

• Simple fix (1-5 lines): Implement immediately
• Medium change (6-25 lines): Quick analysis, then implement
• Large change (26-100 lines): Detailed planning required
• Major change (100+ lines): Must justify why simpler solutions won't work

💡 EXAMPLE SCENARIOS

❌ Overengineered Solutions

• Issue: "Can't connect offline" → Building offline infrastructure
• Issue: "Need logging" → Creating logging framework
• Issue: "Error messages unclear" → Building error handling system

✅ Minimal Solutions

• Issue: "Can't connect offline" → Cache the missing resources
• Issue: "Need logging" → Add console.log or use existing logger
• Issue: "Error messages unclear" → Update existing error strings

🚀 SUCCESS METRICS

• Lines of code: Minimize additions, maximize problem resolution
• File count: Prefer 0 new files when possible
• Complexity: Can a junior developer understand it in 5 minutes?
• Maintenance: Will this require ongoing updates or just work?
• Business value: Does this solve a real user problem?

💰 COST AWARENESS

Every line of code has hidden costs:

• Development time: Writing, testing, documenting
• Maintenance burden: Updates, bug fixes, refactoring
• Cognitive load: Understanding, explaining to teammates
• Technical debt: Future constraints and complexity

🎯 CAREER IMPACT REMINDER

Overengineering can cost you:

• Interview failures: Complex solutions to simple problems
• Team friction: Difficult-to-maintain code
• Missed deadlines: Over-scoped implementations
• Reputation damage: Known as someone who overcomplplicates

Remember: The best engineers are paid to choose NOT to build things.

🏆 THE GOLDEN RULE

The best code is often no code at all.

When in doubt, choose the solution that requires the least amount of new code while solving the actual problem effectively.

claude.md

CLAUDE.md Template

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

🎯 MINIMAL CODE CHANGES PRINCIPLE

CRITICAL: Always start with the simplest possible solution. Overengineering has real business costs including lost job opportunities, maintenance burden, and team productivity.

Core Rules

• ALWAYS start with the simplest possible solution
• NEVER create new files unless absolutely necessary
• PREFER editing existing files over creating new ones
• Question if you're solving the right problem before implementing

Required Process Before Implementation

1. Problem Analysis: Clearly identify the root cause
2. Solution Brainstorm: List 3+ possible solutions, from simplest to complex
3. Impact Assessment: How many files/lines of code will change?
4. Justification: Why is this the minimal viable solution?
5. Implementation: Only proceed after steps 1-4

Red Flags - Stop and Reconsider

• Creating more than 2 new files for a single issue
• Adding more than 50 lines of code for a simple fix
• Creating "alternative" or "offline" versions of existing functionality
• Building infrastructure when a configuration change would work
• Adding abstraction layers when direct solutions exist
• Implementing patterns that will require documentation to understand

Anti-Patterns That Cost Careers

• Interview Killers: Overengineered solutions during technical interviews
• Team Friction: Code that's hard to understand or maintain
• Missed Deadlines: Over-scoped implementations
• Technical Debt: Future constraints from unnecessary complexity

Decision Framework

• Simple fix (1-5 lines): Implement immediately
• Medium change (6-25 lines): Quick analysis, then implement
• Large change (26-100 lines): Detailed planning required
• Major change (100+ lines): Must justify why simpler solutions won't work

Validation Questions

Before implementing any solution, ask:

1. "Is there a way to solve this without writing new code?"
2. "Can I solve this by changing configuration instead?"
3. "Am I solving the stated problem or a problem I imagined?"
4. "Will this solution create more problems than it solves?"
5. "Can a user accomplish the same goal with existing features?"
6. "Would this impress an interviewer or confuse them?"

Success Metrics

• Lines of code: Minimize additions, maximize problem resolution
• File count: Prefer 0 new files when possible
• Complexity: Can a junior developer understand it in 5 minutes?
• Maintenance: Will this require ongoing updates or just work?
• Business impact: Does this solve a real user problem efficiently?

Cost Awareness

Every line of code has hidden costs:

• Development time: Writing, testing, documenting
• Maintenance burden: Updates, bug fixes, refactoring
• Cognitive load: Understanding, explaining to teammates
• Technical debt: Future constraints and complexity
• Career impact: Reputation for over-complication

Preferred Solutions

1. Configuration changes over code changes
2. Using existing tools over building new ones
3. Simple functions over complex architectures
4. Direct solutions over abstracted frameworks
5. Single-purpose fixes over multi-feature implementations

Example Decision Process

Problem: "Docker build fails offline because it can't pull images"

❌ Overengineered Approach:

• Create offline Dockerfiles
• Build dual-mode infrastructure
• Add offline/online toggle systems
• Result: 200+ lines, 6+ files, ongoing maintenance

✅ Minimal Approach:

• Identify missing images: node:20-alpine, dockerfile:1
• Cache them: docker pull node:20-alpine && docker pull dockerfile:1
• Result: 2 commands, problem solved

Communication Guidelines

• Explain the trade-offs when choosing complexity over simplicity
• Justify new files - why can't this be added to existing files?
• Document maintenance costs for any new infrastructure
• Consider team onboarding - how long to explain this to new developers?

Project-Specific Context

• Technology stack preferences
• Existing patterns to follow
• Team coding standards
• Performance requirements
• Deployment constraints

🏆 THE GOLDEN RULE

The best code is often no code at all.

Remember: Senior engineers are paid to choose NOT to build things. The most valuable skill is knowing when NOT to write code.

---

This template is based on real experiences where overengineering cost job opportunities, team productivity, and project success. Simplicity is not just a technical choice—it's a career and business strategy.