# Handling "Simplicity First" Conflicts with Existing Complex Architecture

> Resolve 'Simplicity First' conflicts with complex architecture. Evaluate abstractions, apply surgical changes, and verify impact through goal-driven execution for cleaner systems.

- Repository: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills)
- Tags: best-practices
- Published: 2026-04-19

---

**Resolve conflicts between "Simplicity First" and complex existing architectures by evaluating whether current abstractions provide essential value or historical baggage, then apply surgical changes that implement minimal code outside unnecessary layers while verifying impact through goal-driven execution.**

The `multica-ai/andrej-karpathy-skills` repository codifies the **"Simplicity First"** principle, demanding developers write the minimum code that solves the problem without speculative features or over-engineered solutions. When working within legacy systems featuring deep inheritance hierarchies or microservice meshes, teams often struggle to reconcile these minimalist guidelines with existing architectural complexity.

## Understanding the Simplicity First Principle

The principle originates from the repository's core skill definitions found in [`README.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/README.md) and [`skills/karpathy-guidelines/SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md). It mandates three non-negotiable tenets:

- **Minimum viable code** – Write only what solves the immediate problem
- **No speculative features** – Avoid building for hypothetical future requirements
- **Eliminate unnecessary abstractions** – Reject deep hierarchies and utility layers that don't reduce complexity

The `.cursor/rules/karpathy-guidelines.mdc` file enforces these rules within the Cursor IDE, ensuring developers encounter this guidance during code review.

## Evaluating Existing Architecture Against Simplicity First

When confronting a complex existing architecture,apply a **three-step evaluation framework** to determine whether to work within or around the existing structure:

1. **Identify the real requirement** – Define what the feature or bug-fix must accomplish in concrete terms
2. **Map the requirement onto existing layers** – Determine if the current architecture provides *essential* value (cross-cutting concerns, security, observability) or merely *historical baggage*
3. **Apply "Simplicity First" selectively** – If existing layers add no value for this specific change, implement the solution *outside* the complex hierarchy using a simpler facade

This workflow respects the **Surgical Changes** principle (touch only what you must) and the **Goal-Driven Execution** principle (define verifiable success criteria).

| Step | Goal-Driven Check |
|------|-------------------|
| **Assess necessity** | "Does this abstraction reduce duplicated logic elsewhere?" |
| **Prototype minimally** | Write a small, self-contained implementation that passes the test suite |
| **Validate impact** | Run existing integration tests; if they pass, the simplification is safe |
| **Iterate** | If new code reveals hidden dependencies, plan a targeted refactor rather than a wholesale rewrite |

## Practical Resolution Strategies

### Apply Surgical Changes

When the existing architecture represents *historical baggage* rather than essential infrastructure, implement new functionality as **standalone units** that bypass complex hierarchies. This approach treats the existing architecture as a hypothesis to be tested: *"This layer is required for X"*—validated through concrete, minimal code that keeps the codebase lean while honoring architectural decisions that truly add value.

### Validate with Goal-Driven Execution

Every simplification must satisfy a **verifiable success criterion**. Before removing an abstraction layer or bypassing a service hierarchy, establish measurable goals: integration tests must pass, performance benchmarks must hold, and security requirements must remain satisfied. This prevents "simplification" from becoming destructive refactoring.

## Code Example: Refactoring Complex Service Hierarchies

Consider a scenario where a deep inheritance hierarchy forces minimal utility functions to inherit complex concerns. The following examples demonstrate resolving this conflict.

### Before: Over-Engineered Approach

This implementation uses a generic `BaseService` hierarchy found in `existing architecture (complex)` patterns, requiring even simple utilities to inherit logging, metrics, and authentication concerns:

```python
class BaseService:
    def __init__(self, repo):
        self.repo = repo
    
    def execute(self, request):
        raise NotImplementedError

class UserService(BaseService):
    def execute(self, request):
        user = self.repo.get_user(request.id)
        # Cross-cutting concerns (logging, metrics, auth) handled in BaseService

        return user

```

**Problem:** Adding a tiny utility that formats a user's name forces creation of a new `BaseService` subclass, pulling in logging, metrics, and other concerns irrelevant for this one-off task.

### After: Simplicity First Implementation

This refactored solution implements the **"Simplicity First"** principle by creating a self-contained function that operates outside the complex hierarchy:

```python
def format_user_name(user):
    """Return a nicely formatted display name for a user."""
    return f"{user.first_name} {user.last_name}".strip()

```

**Why this resolves the conflict:**

- The function directly solves the requirement without adding to the class hierarchy
- Existing services remain untouched, satisfying **Surgical Changes**
- Tests verify behavior in isolation, meeting **Goal-Driven Execution** criteria
- If formatting later requires logging or caching, a thin wrapper can be added around `format_user_name` rather than expanding the entire inheritance tree

## Summary

- **Evaluate existing architecture** as a hypothesis to be tested—determine whether layers provide essential value or historical baggage before deciding to work within or around them
- **Apply "Simplicity First" selectively** by implementing new functionality outside complex hierarchies when existing abstractions add no value to the specific requirement
- **Respect Surgical Changes** by touching only what you must, keeping existing service hierarchies intact while bypassing them for new, minimal implementations
- **Validate through Goal-Driven Execution** by establishing verifiable success criteria—passing integration tests and maintaining performance benchmarks—before finalizing simplifications
- **Defer complexity** by starting with standalone functions rather than new class hierarchies, adding wrappers only when cross-cutting concerns prove genuinely necessary

## Frequently Asked Questions

### How do I convince my team to bypass existing architecture for a simple feature?

Frame the existing architecture as a **testable hypothesis** rather than immutable infrastructure. Demonstrate that the new functionality can meet **Goal-Driven Execution** criteria—passing all integration tests and security checks—without inheriting the full service hierarchy. Present the **Surgical Changes** approach as risk mitigation: by not modifying existing services, you eliminate regression risk while still delivering the feature.

### What if the simple implementation reveals hidden dependencies later?

This discovery actually validates the **"Simplicity First"** approach. When hidden dependencies emerge, you have concrete evidence that the abstraction layer *is* necessary for this specific functionality. Apply **iterative refactoring**: add a thin wrapper around your simple implementation to handle the cross-cutting concern, rather than rewriting the feature to fit the existing hierarchy. This keeps the codebase lean while accurately reflecting actual dependencies.

### Can this approach work in microservice architectures?

Yes, but the evaluation criteria shift from class hierarchies to **service boundaries**. Apply the three-step framework: identify the real requirement, map it against existing services to determine if they provide essential value (observability, circuit breakers, ACLs) or merely historical baggage, then implement **outside** the mesh if possible. Use **Goal-Driven Execution** to verify that bypassing the service layer doesn't violate SLOs or security policies.

### How do I document the decision to bypass complex layers?

Create a **decision record** referencing the specific files in `multica-ai/andrej-karpathy-skills` that guided your choice. Cite the **Simplicity First** principle from [`skills/karpathy-guidelines/SKILL.md`](https://github.com/multica-ai/andrej-karpathy-skills/blob/main/skills/karpathy-guidelines/SKILL.md) and the **Surgical Changes** rule. Document the **Goal-Driven Execution** criteria used for validation—specific test suites passed, performance benchmarks met—and the hypothesis tested regarding the necessity of the existing architecture. This creates an audit trail for future maintainers.