I use Claude Code for most of my work. After months of iteration, I noticed a pattern: LLM-assisted code rots faster than hand-written code. Technical debt accumulates because the LLM does not know what it does not know, and neither do you until it is too late.
This repo is my solution: skills and workflows that force planning before execution, keep context focused, and catch mistakes before they compound.
LLM-assisted coding fails long-term. Technical debt accumulates because the LLM cannot see it, and you are moving too fast to notice. I treat this as an engineering problem, not a tooling problem.
LLMs are tools, not collaborators. When an engineer says "add retry logic", another engineer infers exponential backoff, jitter, and idempotency. An LLM infers nothing you do not 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".
Larger context windows do not help. Giving an LLM more text is like giving a human a larger stack of papers; attention drifts to the beginning and end, and details in the middle get missed. More context makes this worse. Give the LLM exactly what it needs for the task at hand -- nothing more.
This workflow is built on four principles.
Each task gets precisely the information it needs -- no more. Sub-agents start with a fresh context, so architectural knowledge must be encoded somewhere persistent.
I use a two-file pattern in every directory:
CLAUDE.md -- Claude loads these automatically when entering a directory.
Because they load whether needed or not, content must be minimal: a tabular
index with short descriptions and triggers for when to open each file. When
Claude opens app/web/controller.py, it retrieves just the indexes along that
path -- not prose it might never need.
README.md -- Invisible knowledge: architecture decisions, invariants not apparent from code. The test: if a developer could learn it by reading source files, it does not belong here. Claude reads these only when the CLAUDE.md trigger says to.
The principle is just-in-time context. Indexes load automatically but stay small. Detailed knowledge loads only when relevant.
The technical writer agent enforces token budgets: ~200 tokens for CLAUDE.md, ~500 for README.md, 100 for function docs, 150 for module docs. These limits force discipline -- if you are exceeding them, you are probably documenting what code already shows. Function docs include "use when..." triggers so the LLM knows when to reach for them.
The planner workflow maintains this hierarchy automatically. If you bypass the planner, you maintain it yourself.
LLMs make first-shot mistakes. Always. The workflow separates planning from execution, forcing ambiguities to surface when they are cheap to fix.
Plans capture why decisions were made, what alternatives were rejected, and what risks were accepted. Plans are written to files. When you clear context and start fresh, the reasoning survives.
Execution is split into milestones -- smaller units that are manageable and can be validated individually. This ensures continuous, verified progress. Without it, execution becomes a waterfall: one small oversight early on and agents compound each mistake until the result is unusable.
Quality gates run at every stage. A technical writer agent checks clarity; a quality reviewer checks completeness. The loop runs until both pass.
Plans pass review before execution begins. During execution, each milestone passes review before the next starts.
The orchestrator delegates to smaller agents -- Haiku for straightforward tasks, Sonnet for moderate complexity. Prompts are injected just-in-time, giving smaller models precisely the guidance they need at each step.
When quality review fails or problems recur, the orchestrator escalates to higher-quality models. Expensive models are reserved for genuine ambiguity, not routine work.
I have not run formal benchmarks. I can only tell you what I have observed using this workflow to build and maintain non-trivial applications entirely with Claude Code -- backend systems, data pipelines, streaming applications in C++, Python, and Go.
The problems I used to hit constantly are gone:
Ambiguity resolution. You ask an LLM "make me a sandwich" and it comes back with a grilled cheese. Technically correct. Not what you meant. The planning phase forces these misunderstandings to surface before you have built the wrong thing.
Code hygiene. 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.
LLM-navigable documentation. Function docs include "use when..." triggers. CLAUDE.md files tell the LLM which files matter for a given task. The LLM stops guessing which code is relevant.
Is it better than writing code by hand? I think so, but I cannot speak for everyone. This workflow is opinionated. I am a backend engineer -- the patterns should apply to frontend work, but I have not tested that. If you are less experienced with software engineering, I would like to know whether this helps or adds overhead.
If you are serious about LLM-assisted coding and want to try a structured approach, give it a shot. I would like to hear what works and what does not.
Clone into your Claude Code configuration directory:
# Per-project
git clone https://github.com/solatis/claude-config .claude
# Global (new setup)
git clone https://github.com/solatis/claude-config ~/.claude
# Global (existing ~/.claude)
cd ~/.claude
git remote add workflow https://github.com/solatis/claude-config
git fetch workflow
git merge workflow/main --allow-unrelated-historiesThe workflow for non-trivial changes: explore -> plan -> execute.
1. Explore the problem. Understand what you are dealing with. Figure out the solution.
This is relatively free-form. If the project and/or surface area is particularly
large, use the codebase-analysis skill to explore the project's code properly
before proposing a solution.
2. (Optional) Think through the problem. For complex decisions, the
problem-analysis skill forces structured analysis: decompose problems into
constraints and variables, generate distinct approaches, verify assumptions
against evidence. It produces a decision framework with explicit tradeoffs.
Use it when you need to gain a better understanding of the problem domain, potential solutions, their tradeoffs, and the cost of choosing wrong is high.
3. (Optional) Stress-test your approach. If you are uncertain, use the
decision-critic skill to find holes in your reasoning before you commit to a
direction.
4. Write a plan. "Use your planner skill to write a plan to plans/my-feature.md"
The planner runs your plan through review cycles -- technical writer for clarity, quality reviewer for completeness -- until it passes.
The planner captures all decisions, tradeoffs, and information not visible from the code so that this context does not get lost.
5. Clear context. /clear -- start fresh. You have written everything
needed into the plan.
6. Execute. "Use your planner skill to execute plans/my-feature.md"
The planner delegates to sub-agents. It never writes code directly. Each milestone goes through the developer, then the technical-writer and quality-reviewer. No milestone starts until the previous one passes review.
Where possible, it executes multiple tasks in parallel.
For detailed breakdowns of each skill, see their READMEs:
I needed to migrate a legacy C# Windows Service from print-based logging to something that actually rotates files.
The codebase had a homegrown Log() method writing to a single file with File.AppendAllText. No rotation, no log levels, synchronous I/O blocking the thread. Six Console.WriteLine calls scattered elsewhere went nowhere when running as a service.
I started with exploration and analysis in a single prompt:
Use your codebase analysis skill to briefly explore this C# project,
with a focus on all the places where debug logs are currently emitted.
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
The codebase analysis found 31 call sites and the Console.WriteLine leakage. The problem analysis evaluated NLog, Serilog, log4net, and Microsoft.Extensions.Logging against my constraints.
The recommendation was NLog. It handles rotation and async out of the box. Multi-process support comes from layout variables. Serilog would work but requires three packages for the same functionality.
I agreed with the recommendation. Not a complicated decision, so I skipped the
decision-critic and moved to planning:
Use your planner skill to write an implementation plan to: plan-logging.md
The planner surfaced two ambiguities:
- Replace all Log() call sites, or just the implementation? Obvious to a human, but worth clarifying upfront.
- Log rotation defaults. The planner assumed 1-day rotation, but I also need size-based rotation at 1GB.
The plan went through review. The technical writer flagged comments that explained what rather than why -- the NLog.config had comments like "configures file target" instead of explaining the rotation strategy. The quality reviewer caught two issues I would have missed: no explicit LogManager.Shutdown() in the service's OnStop() handler, and incorrect file paths missing the src/ prefix.
These are the bugs that ship to production when you skip review cycles. The shutdown issue would have caused log loss on service restart. The path issue would have failed silently.
After fixes, I cleared context and executed:
Use your planner skill to execute: @plan-logging.md
The developer, debugger, technical writer, and quality reviewer run the implementation. Each milestone passes review before the next starts. If the implementation deviated from the plan, I would know.
Not every task needs the full planning workflow. These skills handle specific concerns.
The CLAUDE.md/README.md hierarchy requires maintenance. The structure changes over time. Documentation drifts.
The doc-sync skill audits and synchronizes documentation across a repository.
Use it when:
- Bootstrapping the workflow on an existing repository
- After major refactors or directory restructuring
- Periodic audits to check for documentation drift
If you use the planning workflow consistently, the technical writer agent handles documentation as part of execution. Doc-sync is primarily for bootstrapping or recovery.
Use your doc-sync skill to synchronize documentation across this repository
For targeted updates:
Use your doc-sync skill to update documentation in src/validators/
This workflow consists entirely of prompts. Each can be optimized individually.
The skill analyzes prompts, proposes changes with explicit pattern attribution, and waits for your approval before applying anything.
Use it when:
- A sub-agent definition is not performing as expected
- Optimizing a skill's Python script prompts
- Reviewing a multi-prompt workflow for consistency
Use your prompt engineer skill to optimize the system prompt for agents/developer.md
The skill was optimized using itself.
