One command. Evidence-backed findings. Smallest safe changes. Explicit restraint.
A refactor review can produce plausible-looking advice with no demonstrated need:
- ❌ Introduce an
IRepositoryabstraction - ❌ Split the payment service into smaller services
- ❌ Upgrade the framework
- ❌ Extract the duplicated retry loop
Better Codebase requires findings to look like this:
Finding: checkout retries can charge the same order twice
Evidence: evals/.../src/payment/retry.ts:42
Root cause: each retry creates a new idempotency key
Impact: HIGH · Confidence: HIGH
Smallest safe change: reuse one order-scoped idempotency key across retries
Verification: accept the first charge, time out, retry, and assert one charge
Rejected refactors:
- Repository interface — no demonstrated boundary
- Framework upgrade — no relevant defect or compatibility need
That example comes from the checked-in payment retry eval, not from an invented architecture preference.
npx skills add NicolasYusim/better-codebase --skill '*'
$better-codebase
That's it. The default run is a read-only, evidence-backed review.
Why it is different · Evals · Install · Use · How it works · Development
AI refactoring prompts can reward visible change: more layers, interfaces, abstractions, newer packages, and larger diffs. Better Codebase optimizes for a different outcome:
Find the root cause, prove the impact, make the smallest safe change, and show which tempting refactors should not be done.
Rules such as SOLID, DRY, KISS, YAGNI, and Clean Architecture can be useful, but they are not findings. Every recommendation must answer five questions:
| Question | Required answer |
|---|---|
| Evidence | Where is the exact implementation or observed behavior? |
| Mechanism | How does it produce the problem? |
| Impact | What becomes incorrect, risky, slow, or expensive to change? |
| Intervention | What is the smallest safe correction? |
| Verification | How will the correction be proven? |
An observation that cannot answer all five remains a question, measurement candidate, or rejected refactor—not a confirmed defect.
The repository includes four small execution cases aimed at the failure modes Better Codebase is designed to prevent:
| Case | Signal | Restraint |
|---|---|---|
| Payment retries | A retry can charge twice after an ambiguous timeout | Do not invent layers or upgrade the framework |
| Discount policies | Similar code represents independently owned rules | Do not force a shared abstraction |
| Tenant context | Global mutable context can cross tenant boundaries | Fix data flow without a container or event bus |
| Session expiry | A mock-only test misses a seconds/milliseconds defect | Add one behavioral assertion, not a new test stack |
Controlled comparisons. Each eval can run with and without Better Codebase under the same model, prompt, tools, permissions, and runtime settings. Raw responses and scoring are committed before comparative claims are published. See the evaluation protocol and result template.
flowchart LR
A["Run Better Codebase"] --> B["Map scope, stack, and baseline"]
B --> C["Apply seven internal reviewers"]
C --> D["Group symptoms by root cause"]
D --> E["Reject unsupported proposals"]
E --> F{"Requested action"}
F -->|Review| G["Rank evidence-backed findings"]
F -->|Plan| H["Order reversible steps"]
F -->|Implement| I["Change selected findings"]
I --> J["Re-run focused and baseline checks"]
Better Codebase is the product-facing orchestrator. It owns scope, evidence, prioritization, restraint, and verification. Seven internal reviewers supply domain-specific judgment without duplicating their rules in the orchestrator.
| Internal skill | Responsibility |
|---|---|
| better-architecture | Boundaries, dependency direction, coupling, cohesion, and safe structural change |
| better-simplicity | Unnecessary layers, speculative abstractions, KISS/YAGNI, and the final challenge of every proposal |
| better-duplication | Repeated business knowledge, drift, copy-paste, and the decision to extract or keep duplication |
| better-maintainability | Local clarity, control flow, naming, side effects, state, and safe changeability |
| better-dependencies | Package necessity, health, compatibility, advisories, lockfiles, and migration cost |
| better-testing | Critical behavior, trustworthy assertions, test layers, flakiness, and testability |
| better-performance | Measured bottlenecks, N+1 work, I/O, memory, bundle size, and established complexity problems |
The better-codebase orchestrator uses all seven. Install the complete collection for a holistic review. Specialists can still be invoked directly for a deliberately narrow task.
Better Codebase does not hide mutation behind a review command.
| Depth | Meaning |
|---|---|
quick |
Default. Inspect a requested scope or risk-weighted complete slice and report up to seven high- or medium-impact findings. |
full |
Inspect the entire credible scope across all reviewers and report up to twenty findings, including low-impact items when justified. |
| Action | Meaning |
|---|---|
review |
Default and read-only. Return evidence-backed findings. |
plan |
Read-only. Produce ordered, reversible migration steps. |
implement |
Modify only selected findings or an explicitly approved scope, then verify every step. |
A bare implement without a prior report, finding IDs, or clear change scope
stops after review and planning. The agent does not select an unbounded rewrite
on your behalf.
Install Better Codebase and its internal reviewers for Claude Code, Codex, and other Agent Skills clients:
npx skills add NicolasYusim/better-codebase --skill '*'The repository includes a Claude marketplace and plugin manifest:
/plugin marketplace add NicolasYusim/better-codebase
/plugin install better-codebase@better-codebase
Invoke the product, then optionally add depth or scope:
/better-codebase:better-codebase
/better-codebase:better-codebase full src/billing/
After updating the plugin, run /reload-plugins or start a new session.
Install from the repository marketplace:
codex plugin marketplace add https://github.com/NicolasYusim/better-codebase
codex plugin add better-codebase@better-codebaseOr use the Skills CLI installation above. Invoke the product by name:
$better-codebase
$better-codebase full src/billing/
The repository includes the Codex marketplace at
.agents/plugins/marketplace.json, plugin metadata at
.codex-plugin/plugin.json, and UI metadata in every agents/openai.yaml.
$better-codebase
Runs a quick, read-only review, checks the existing baseline, and returns one finding per root cause.
$better-codebase full src/billing/
Reviews the full billing scope without implying unrelated surfaces were inspected.
$better-codebase plan findings 1, 3, and 4
Produces independently reviewable steps, verification points, dependencies, and rollback boundaries without editing code.
$better-codebase implement findings 1 and 3
Protects current behavior, changes one bounded mechanism at a time, and re-runs the relevant checks after every material step.
Every consolidated finding records four independent ratings:
| Dimension | Values | Purpose |
|---|---|---|
| Impact | HIGH, MEDIUM, LOW |
Consequence for correctness, change cost, or operations |
| Reach | SYSTEMIC, MODULE, LOCAL |
Size of the affected surface |
| Confidence | HIGH, MEDIUM, LOW |
Strength of the demonstrated mechanism |
| Change risk | HIGH, MEDIUM, LOW |
Danger and reversibility of the correction |
No fake numeric score combines them. Evidence strength is explicit:
PROVEN— reproduced failure, test, trace, profile, benchmark, advisory, or demonstrated cycle;SUPPORTED— multiple locations, dependency path, drift, documented constraint, or coupled change evidence;INFERRED— credible but unconfirmed risk, reported only infullwith a verification step;PREFERENCE— aesthetic or ideological opinion, excluded from findings.
Every review records real improvements that were considered and rejected:
| Candidate | Rejected because |
|---|---|
| Introduce a repository interface | One persistence implementation exists and no volatile boundary, migration, or deterministic-effect seam justifies the indirection. |
| Extract two similar blocks | They encode different business concepts and have independent reasons to change. |
| Upgrade the newest framework major | No advisory or compatibility need justifies the breaking changes and migration cost. |
| Cache the result | No measured bottleneck exists, and invalidation would add a correctness risk. |
If no borderline candidate was actually inspected, the review says so instead of inventing rejected work as filler.
- Apply SOLID, DRY, Clean Architecture, patterns, or metrics dogmatically.
- Introduce an interface merely because only concrete classes feel impure.
- Remove every repeated block or create option-heavy shared utilities.
- Split coherent functions into navigation-heavy micro-functions.
- Change public APIs, schemas, wire formats, or intended behavior casually.
- Upgrade dependencies without release notes, compatibility, and migration evidence.
- Claim performance improvement without measurement or established complexity evidence.
- Hide pre-existing test failures or convert verification gaps into findings.
- Rewrite a repository when a local, reversible change is sufficient.
| Surface | Included support |
|---|---|
| Agent Skills clients | Standard skills/<name>/SKILL.md layout and progressive disclosure |
| Claude Code | .claude-plugin/plugin.json and .claude-plugin/marketplace.json |
| Codex | .codex-plugin/plugin.json and per-skill agents/openai.yaml |
| Local development | Zero-dependency validator, unit test, eval fixtures, and GitHub Actions workflow |
The skills require no MCP server, hook, runtime service, or third-party Python package. They use the tools already available to the host agent and target repository.
.claude-plugin/ Claude plugin and marketplace metadata
.codex-plugin/ Codex plugin manifest
.agents/plugins/ Codex marketplace metadata
.github/ CI and pull-request template
evals/ Controlled with-skill/without-skill cases
skills/better-codebase/ Product orchestrator and evidence protocols
skills/better-*/ Seven internal domain reviewers
scripts/check_repo.py Zero-dependency repository validator
tests/ Repository contract tests
Validate the complete repository:
python3 scripts/check_repo.py
python3 -m unittest discover -s tests -vBefore changing a skill, read CONTRIBUTING.md. Domain rules belong to one owner; the orchestrator contains only coordination, evidence, prioritization, implementation control, and the consolidated output.
Contributions are welcome when they improve decision quality without turning the collection into an encyclopedia of style opinions. Add evidence gates, failure modes, realistic eval cases, and forward tests before adding more rules.
See CONTRIBUTING.md and use the pull request template.
MIT — Copyright © 2026 Better Codebase contributors.