# Improve Code Quality

> Vibe-coded prototype → production-ready code — a guided journey that orchestrates 9 AI agent skills, one decision at a time.

Published 2026-07-16 · Updated 2026-08-17 · Guided journey · Free and MIT-licensed
Canonical: https://skills.wondel.ai/skills/improve-code-quality/
Source: https://github.com/wondelai/skills/tree/main/improve-code-quality
Companion guide: https://skills.wondel.ai/guides/vibe-coded-prototype-to-production/

**Install:** `npx skills add wondelai/skills/improve-code-quality --global`

## What is the Improve Code Quality journey?

Prototypes that work are not products that survive. Nine phases take vibe-coded code to production: characterization tests first, then readability, structure, deep modules, a business-rules boundary, sustaining habits, production hardening, honest sizing and a durable data layer — with each decision recorded in docs/ so the work spans sessions.

## The 9 phases

1. **Legacy Code** _(gate)_ — Can I change this code without breaking it unknowingly? → `docs/TESTING.md + docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/working-with-legacy-code/)
2. **Clean Code** — Is this readable to the next person (and agent)? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/clean-code/)
3. **Refactoring** — Can I reshape structure without changing behavior? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/refactoring-patterns/)
4. **Software Design** — Is complexity hidden behind deep modules? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/software-design-philosophy/)
5. **Clean Architecture** — Do business rules depend on the framework, or vice versa? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/clean-architecture/)
6. **Pragmatic Programmer** — What habits keep it clean after we stop? → `docs/TECH-DEBT.md` (https://skills.wondel.ai/skills/pragmatic-programmer/)
7. **Release It!** — Will it survive a hostile production? → `docs/RELIABILITY.md` (https://skills.wondel.ai/skills/release-it/)
8. **System Design** — Is it sized for the load we actually have? → `docs/ARCHITECTURE.md + docs/RELIABILITY.md` (https://skills.wondel.ai/skills/system-design/)
9. **Data-Intensive Apps** — Is the data layer correct and durable under concurrency? → `docs/ARCHITECTURE.md` (https://skills.wondel.ai/skills/ddia-systems/)

## What it produces

- `docs/TESTING.md`
- `docs/TECH-DEBT.md`
- `docs/ARCHITECTURE.md`
- `docs/RELIABILITY.md`
- `docs/IMPROVE-CODE-QUALITY-PLAN.md`

## When to use Improve Code Quality — and when not to

Reach for it when:

- Take an AI-generated or hackathon prototype to production
- Put untested code under characterization tests before touching it
- Raise code quality without mixing refactors and behavior changes
- Add timeouts, circuit breakers, and health checks before launch
- Make honest scaling and data-layer decisions

Reach for something else when:

- The codebase is large, old and team-owned rather than a weekend build — Remove Technical Debt paces the work differently.
- Nothing is written yet and the question is structure — Design Code Architecture decides boundaries before any code exists.
- You just want naming and function length fixed in one module — Clean Code alone is the lighter tool.
- The complaint is about the product’s experience, not its internals — Improve an App is the journey for that.

## Example prompts

- I vibe-coded this app in a weekend — make it production-ready. using improve-code-quality skill _(Prototype hardening)_
- Run the code-quality journey on this repo, safety net first. using improve-code-quality skill _(Safety net first)_
- Resume hardening this codebase from the tracker. using improve-code-quality skill _(Resume journey)_

## Worked example — Take a Vibe-Coded Prototype to Production

The demo works. The code was written by vibes. Launch is in six weeks.

```
This repo is a working prototype built fast and untested. Run the improve-code-quality journey: safety net first, then readability, structure, production hardening, and honest scaling decisions. Structural and behavioral changes in separate commits.

Use improve-code-quality skill.
```

## Frequently asked questions

### How do I install the Improve Code Quality journey?

Run `npx skills add wondelai/skills/improve-code-quality --global`. It takes about 30 seconds and needs no account. The Improve Code Quality skill then works in Claude, Claude Code, Claude Cowork, Codex, Cursor, OpenClaw and Hermes Agent — anything that reads the open agentskills.io format — and your agent loads it on its own when a task calls for it. It is free and MIT-licensed, and the source is at https://github.com/wondelai/skills.

### Which skills does the Improve Code Quality journey run, and what does it produce?

It orchestrates 9 skills across 9 phases — Legacy Code, Clean Code, Refactoring, Software Design, Clean Architecture, Pragmatic Programmer, Release It!, System Design, Data-Intensive Apps — asking you one decision question per phase. Each answer is written to your project's docs/ folder (docs/TESTING.md, docs/TECH-DEBT.md, docs/ARCHITECTURE.md, docs/RELIABILITY.md, docs/IMPROVE-CODE-QUALITY-PLAN.md), so the journey survives across sessions and you keep the reasoning, not just the output.

### What does the safety-net gate mean in practice?

Phase one will not let the journey change the shape of anything until the code you intend to touch is pinned by characterization tests — tests that record what it does today, bugs included, rather than what it should do. The result goes to docs/TESTING.md, with the still-unpinned regions listed in docs/TECH-DEBT.md. Refactoring without that net is how a working prototype becomes a broken one.

### Nine phases is a lot. Where does most of the value land?

Usually in the first three and in Release It!. Legacy Code buys you the ability to change anything at all; Clean Code and Refactoring make the next month cheaper; Release It! is what stands between a demo and a hostile production — timeouts, circuit breakers, bulkheads, health checks. The Data-Intensive Apps phase matters most if you hold money, counters, or anything two users can write at once.

### Should structural and behavioural changes go in the same commit?

No, and the journey is strict about it. Every refactoring phase separates the two: one commit reshapes structure with the tests green and behaviour unchanged, a different commit changes what the code does. That discipline is what makes review possible and lets you revert a mistake without unpicking a week of work. The rule sits in docs/TECH-DEBT.md next to the debt ledger.

### My prototype is six months old and has real users. Is this still right?

Check the size first. This journey assumes a codebase small enough that nine phases can sweep most of it — a weekend build, a hackathon repo, an agent-generated MVP that found traction. If it has grown into something several people are afraid to touch, Remove Technical Debt is built for that: the same safety-net gate, but worked module by module while the team keeps shipping.