Stop Letting LLMs Rot Your Codebase: solatis/claude-config Exposed

Your AI pair programmer is silently destroying your codebase.

Every sprint, every shipped feature, every "production-ready" commit—it's all compounding into a nightmare you won't see coming until your next migration, your next onboarding, your next 3 AM outage. The LLM doesn't know what it doesn't know. Worse? Neither do you. Not until it's far too late.

Here's the gut punch: LLM-assisted code rots faster than hand-written code. The velocity feels incredible. The technical debt accumulates invisibly. And when an engineer says "add retry logic," another engineer infers exponential backoff, jitter, idempotency. An LLM? It infers nothing you don't explicitly state. It cannot read the room. It has no institutional memory. It will cheerfully implement the wrong thing with perfect confidence and call it "production-ready."

I spent months watching this pattern destroy projects. Then I found something that actually fights back.

Enter solatis/claude-config—a disciplined, opinionated workflow that forces planning before execution, keeps context surgically focused, and catches mistakes before they compound into disasters. This isn't another AI wrapper. This is an engineering solution to an engineering problem.

Ready to stop the rot? Let's dissect what makes this workflow brutally effective.

What is solatis/claude-config?

solatis/claude-config is a meticulously crafted configuration and skill system for Claude Code—Anthropic's agentic coding tool. Created by a backend engineer who ships non-trivial applications entirely through LLM assistance, this repository distills months of iteration into battle-tested workflows, reusable skills, and ruthless context hygiene practices.

The creator's thesis is radical in its simplicity: LLMs are tools, not collaborators. Treat them otherwise, and you invite catastrophe. The repository encodes this philosophy into concrete, file-based workflows that transform Claude Code from an eager-but-ignorant assistant into a disciplined engineering team with built-in quality gates.

Why is this trending now? The AI coding honeymoon is ending. Early adopters who shipped fast with Cursor, Copilot, and Claude Code are hitting the wall—codebases that "work" but nobody understands, duplicate utilities scattered everywhere, documentation that exists but helps no one. The industry is desperate for structured approaches that preserve velocity without sacrificing maintainability. solatis/claude-config answers that demand with a system proven across backend systems, data pipelines, and streaming applications in C++, Python, and Go.

This isn't theoretical. The creator maintains this workflow through real shipping pressure, iterating based on what breaks and what saves projects from failure.

Key Features That Force Discipline

The solatis/claude-config workflow is built on four uncompromising principles, each with concrete technical implementations:

Context Hygiene: Surgical Precision Over Spray-and-Pray

The creator demolishes the "bigger context window" myth. Giving an LLM more text is like giving a human a larger stack of papers—attention drifts to the beginning and end, details in the middle vanish. The solution? Just-in-time context through a two-file pattern:

• CLAUDE.md — Auto-loaded tabular indexes with short descriptions and triggers. ~200 tokens maximum. Tells the LLM which files matter for which tasks.
• README.md — Invisible knowledge only: architecture decisions, invariants not apparent from code. ~500 tokens. Read only when CLAUDE.md triggers indicate relevance.

Token budgets are enforced, not suggested: 100 tokens for function docs, 150 for module docs. Exceed them, and you're documenting what code already shows. Function docs include "use when..." triggers so the LLM knows precisely when to reach for them.

Planning Before Execution: Surface Ambiguities When They're Cheap

LLMs make first-shot mistakes. Always. The workflow separates planning from execution, forcing ambiguities to surface before you've built the wrong thing. Plans capture why decisions were made, what alternatives were rejected, what risks were accepted. Plans are written to files—when you clear context and start fresh, the reasoning survives.

Review Cycles: Continuous Verification, Not Waterfall Hope

Execution splits into milestones—smaller, independently validatable units. Quality gates run at every stage: technical writer for clarity, quality reviewer for completeness. The loop runs until both pass. Plans pass review before execution. Each milestone passes review before the next starts.

Cost-Effective Delegation: Right Model, Right Task

The orchestrator delegates intelligently: Haiku for straightforward tasks, Sonnet for moderate complexity. Prompts inject just-in-time, giving smaller models precisely the guidance they need. Escalation to expensive models happens only for genuine ambiguity—not routine work burned through premium tokens.

Use Cases Where This Workflow Dominates

1. Migrating Legacy Systems with Hidden Dependencies

That C# Windows Service with print-based logging? The one with File.AppendAllText to a single file, no rotation, synchronous I/O blocking threads, and Console.WriteLine calls that vanish in service mode? The workflow's codebase-analysis skill found 31 call sites and leakage patterns a human would miss in manual review. Problem analysis evaluated NLog, Serilog, log4net against real constraints. The planner surfaced ambiguities—replace call sites or just implementation? rotation defaults?—before a single line of migration code shipped.

2. Building Backend Systems That Survive Team Turnover

The CLAUDE.md/README.md hierarchy encodes institutional knowledge persistently. When context clears, architectural reasoning survives in files, not in LLM state that evaporates. New team members inherit discoverable, LLM-navigable documentation with "use when..." triggers that guide intelligent code exploration.

3. Preventing the Fifteen-Utility-Functions Disaster

Without review cycles, the same utility function gets reimplemented fifteen times across a codebase. The quality reviewer catches this. The technical writer ensures documentation stays consistent. The refactor skill explores naming, extraction, types, errors, modules, architecture in parallel—validating findings against evidence, outputting prioritized recommendations without generating code blindly.

4. Strategic Architecture Decisions Under Uncertainty

When multiple valid approaches exist and gut feel isn't enough—PDF conversion strategies, S3 artifact versioning schemes, CI/CD patterns—the deepthink skill launches parallel sub-agents with distinct analytical perspectives, synthesizes through agreement patterns, and self-verifies. Quick mode for direct reasoning, full mode for complex trade-offs, auto-detected based on complexity.

Step-by-Step Installation & Setup Guide

Getting started with solatis/claude-config takes minutes, but the discipline it instills pays dividends for months.

Clone the Repository

Choose your scope—per-project or global:

# Per-project installation
git clone https://github.com/solatis/claude-config .claude

# Fresh global setup
git clone https://github.com/solatis/claude-config ~/.claude

# Existing ~/.claude directory (merge without losing your history)
cd ~/.claude
git remote add workflow https://github.com/solatis/claude-config
git fetch workflow
git merge workflow/main --allow-unrelated-histories

The per-project .claude directory keeps configurations scoped and version-controlled with your repository. Global installation applies across all Claude Code sessions.

Initialize the Two-File Pattern

In every directory where LLM context matters, create:

# CLAUDE.md (place in project root, src/, src/services/, etc.)
| File | Trigger | Description |
|------|---------|-------------|
| README.md | Architecture decisions needed | System invariants, design rationale |
| src/services/README.md | Modifying service layer | Service boundaries, data flow |

Keep it under 200 tokens. This loads automatically—make every token earn its place.

# README.md (detailed knowledge, loaded only on trigger)
## Service Layer Architecture

**Invariant**: All external calls go through the resilience decorator.
**Decision**: Circuit breaker over bulkhead for resource constraints (rejected: bulkhead complexity not justified at current scale).

Target 500 tokens. If a developer could learn it by reading source, it doesn't belong here.

Configure Your First Skill

Skills live in the skills/ directory. Start with the planner—it's the workflow's backbone:

# Verify skills are recognized
ls skills/planner/
# Expected: README.md, system prompts, sub-agent definitions

Establish Token Budget Discipline

Create enforcement habits:

Exceeding these limits signals you're documenting what code already shows—refactor instead.

REAL Code Examples from the Repository

These examples demonstrate the workflow in practice, extracted directly from the repository's documentation.

Example 1: The Core Workflow Command Sequence

The fundamental pattern—explore, plan, execute—is invoked through explicit skill commands:

# Step 1: Explore with codebase analysis
Use your codebase analysis skill to briefly explore this C# project,
with a focus on all the places where debug logs are currently emitted.

# Step 2: Analyze the problem space
Then use your problem analysis skill to think through an appropriate
logging framework:
 * must work with .NET Framework 4.8.1
 * must support log rotation out of the box
 * we run multiple processes on the same machine, so it needs structured
   multi-process support

Why this matters: Notice the explicit constraint enumeration. The LLM receives no ambiguity about "appropriate"—every requirement is testable. The codebase analysis skill returns structured findings (31 call sites, Console.WriteLine leakage) that ground subsequent decisions in evidence, not assumption.

After analysis completes, the workflow progresses through planning:

# Step 3: Generate reviewed plan
Use your planner skill to write an implementation plan to: plan-logging.md

The planner runs review cycles automatically—technical writer for clarity, quality reviewer for completeness—surfacing ambiguities like "replace all call sites or just implementation?" before expensive execution begins.

Example 2: DeepThink Skill Invocation

The most frequently used skill handles analytical questions without predetermined answer structures:

# Default invocation—mode auto-detected
Use your deepthink skill to think through [question]

# Explicit quick mode for straightforward analysis
Use your deepthink skill (quick) to [question]

# Explicit full mode for complex, multi-faceted problems
Use your deepthink skill (full) to [question]

The technical mechanism: Full mode launches parallel sub-agents with different analytical perspectives, then synthesizes through agreement patterns. Both modes self-verify. The creator uses this for meta-cognitive debugging ("why does the LLM keep misunderstanding this task?"), strategy evaluation, best practices research, and architecture decisions.

Example 3: Refactor Skill for Technical Debt Detection

When LLM-generated code accumulates debt the LLM itself cannot see:

# General refactoring analysis
Use your refactor skill on src/services/

# Targeted refactoring with explicit goal
Use your refactor skill on src/ -- focus on refactoring the rendering engine so that it can be reused in multiple components.

Critical distinction: This skill does not generate code. It explores naming, extraction, types, errors, modules, architecture, abstraction in parallel—validates findings against evidence—and outputs prioritized recommendations. The human (or planner-directed developer agent) decides what to implement. This prevents the blind-leading-blind cycle where LLMs generate debt and LLMs "fix" it worse.

Example 4: Plan Execution with Context Clearing

The pivotal moment where discipline separates this workflow from cowboy coding:

# Step 4: Clear context—critical for preventing pollution
/clear

# Step 5: Execute from plan, not from memory
Use your planner skill to execute: @plan-logging.md

The /clear command is non-negotiable. Without it, the LLM carries exploration-phase assumptions, discarded alternatives, and partial understandings into execution. The @plan-logging.md syntax references the reviewed, approved plan file—ensuring execution follows intentional design, not whatever the LLM happens to remember.

During execution, the planner delegates to sub-agents (developer, debugger, technical writer, quality reviewer). Each milestone passes review before the next starts. Parallel execution where possible, but no milestone proceeds on a failed predecessor.

Example 5: Prompt Engineering Self-Optimization

The meta-skill that improves the workflow itself:

Use your prompt engineer skill to optimize the system prompt for agents/developer.md

Recursive improvement: This skill analyzes prompts, proposes changes with explicit pattern attribution ("this change applies few-shot reasoning because..."), and waits for human approval. The creator notes this skill was optimized using itself—a concrete example of the workflow's self-improving potential.

Advanced Usage & Best Practices

Bootstrapping Existing Codebases

The doc-sync skill audits and synchronizes documentation across repositories:

# Full repository audit
Use your doc-sync skill to synchronize documentation across this repository

# Targeted recovery after restructuring
Use your doc-sync skill to update documentation in src/validators/

Use this when adopting the workflow mid-project, after major refactors, or during periodic drift audits.

Escalation Patterns

The orchestrator's cost-effective delegation follows clear escalation rules:

The Decision-Critic Safety Net

For decisions with significant downstream consequences, add the decision-critic skill:

Use your decision-critic skill to stress-test: [decision description]

The creator skipped this for the NLog migration ("not a complicated decision"), but reaches for it when ambiguity has genuine cost.

Comparison with Alternatives

Why solatis/claude-config wins: It treats LLM-assisted coding as systems engineering, not tooling configuration. The context hygiene prevents the attention drift that destroys larger context windows. The mandatory planning surfaces ambiguities when they're cheap. The multi-agent review catches the bugs that ship to production. And the cost optimization means you're not burning Opus tokens on tasks Haiku handles brilliantly.

FAQ

Q: Does this workflow add overhead that slows me down?

A: For trivial changes—one-liners, obvious fixes—you may bypass the full workflow. But for anything touching architecture, dependencies, or multiple files, the planning phase prevents the "build wrong, rebuild, rebuild again" cycle that destroys velocity. The creator ships non-trivial applications entirely with Claude Code; the discipline enables speed, not prevents it.

Q: I'm new to software engineering. Will this help or overwhelm me?

A: The creator explicitly wants feedback from less experienced developers. The workflow encodes practices—review cycles, planning, documentation discipline—that accelerate learning. But it assumes you can evaluate whether a plan makes sense. Start with smaller features, build intuition, scale up.

Q: Can I use this with frontend projects?

A: The patterns should apply, but the creator is a backend engineer and hasn't tested frontend work. The principles—context hygiene, planning before execution, review cycles—are universal. The specific skills may need adaptation for component frameworks, build tools, and browser-specific concerns.

Q: How do I handle the CLAUDE.md/README.md maintenance burden?

A: The planner's technical writer agent handles documentation as part of execution. Use doc-sync for bootstrapping or recovery. If you bypass the planner, you maintain hierarchy yourself—that's the cost of flexibility.

Q: What if the planner's review cycles disagree with my judgment?

A: The workflow is opinionated, not authoritarian. You can override. But investigate first—review cycles caught a missing LogManager.Shutdown() and incorrect file paths in the creator's migration. These bugs ship to production when humans skip review.

Q: Is this better than writing code by hand?

A: The creator thinks so, but won't speak for everyone. The workflow shines where complexity exceeds working memory—multi-file changes, cross-system dependencies, architectural decisions with long-term consequences. For code you fully understand, hand-writing may be faster. The workflow prevents the disasters that happen when you think you understand.

Conclusion

LLM-assisted coding isn't going away. But the Wild West phase—ship fast, fix later, hope someone remembers why—is ending. The codebases built during that phase are rotting now. The engineers who treated LLMs as magic collaborators are paying the price.

solatis/claude-config offers a proven escape hatch: a disciplined, opinionated workflow that preserves velocity while enforcing the engineering practices that keep codebases alive. Context hygiene prevents attention drift. Mandatory planning surfaces ambiguities cheaply. Multi-agent review cycles catch production bugs before they ship. Cost-effective delegation keeps budgets sane.

The creator ships backend systems, data pipelines, streaming applications in C++, Python, and Go using this workflow. The problems that used to hit constantly—ambiguity resolution, code hygiene, LLM-navigable documentation—are gone.

This isn't for everyone. It's opinionated. It demands discipline. But if you're serious about LLM-assisted coding and want a structured approach that survives real engineering pressure, give it a shot.

Clone solatis/claude-config today. Iterate on what works. Report what doesn't. The workflow improves through real-world battle testing—and your next production incident might be the one it prevents.

Found this breakdown valuable? Star the repository, fork it for your own customizations, and join the growing community of engineers refusing to let LLMs rot their codebases.