| name | codebase-review-and-design-assessment |
| description | Review an unfamiliar codebase and produce a grounded design assessment with explicit judgment and pragmatic recommendations. |
| version | 1.0.1 |
| tags | ["code-review","architecture","assessment","design","maintainability"] |
| tool_agnostic | true |
| authors | ["Anders Hybertz"] |
| tested_on | [] |
Codebase review and design assessment
Use this skill when asked to read a project, review a codebase, assess the current design, evaluate architecture, or give a grounded opinion on maintainability and technical direction.
Core rule
Do not answer from stale conversational context or from a previous task summary. Start by re-grounding in the current repository and current request. A design review that is not tied to the actual codebase is worse than no review.
Outcome
Produce a review that:
- is grounded in the repository as it exists now
- distinguishes observations from inferences
- identifies strengths, weaknesses, risks, and next moves
- is pragmatic rather than theatrical
- speaks with senior software development and software architecture judgment
Required workflow
-
Re-anchor on scope.
- Restate the requested review target in one line.
- Treat requests like "have a read at this project" as a fresh task, even if previous turns discussed other work.
-
Read project instructions first.
- Check repository guidance files before forming opinions.
- Respect the repo's declared source of truth for coding and agent instructions.
-
Map the codebase before judging it.
- Identify the main entrypoints, core packages/modules, public API surface, tests, and configuration.
- Look for boundaries: domain logic, orchestration, IO/adapters, CLI, rendering, persistence, integrations.
-
Review implementation evidence.
- Read representative files, not just names.
- Inspect how data flows through the main path.
- Compare intended structure with actual coupling.
- Use tests to infer expected behavior and stability boundaries.
-
Assess the design on concrete axes.
- Module boundaries and cohesion
- Coupling and dependency direction
- Public API clarity
- Error-handling strategy
- Testability and test shape
- Extensibility and change cost
- Operational risk and failure modes
-
Deliver the review in a useful shape.
- Brief overall verdict
- What is working well
- What is structurally weak or fragile
- Most important risks
- Recommended next steps, prioritized
- Explicitly separate "do now" from "later if worth it"
Review intent variants
The framing of the review request changes what you prioritize:
"I haven't looked at this in a while, is it okay?"
Standard health check. Cover all axes. Flag anything that would cost time to fix later.
"We're about to do a big update — want to make sure the foundation is solid"
This is a pre-change stabilization review. Different priority order:
- Principle violations first — things that will compound across many files when the big update touches them (duplicated logic, type drift, undeclared contracts)
- Missing tests second — the big update needs a safety net; flag if there is none
- Structural seam problems third — boundaries that will make the update hard to execute cleanly
- Polish and local smells last — fine to note, but don't let them dominate a pre-change review
- End with an explicit "lock these in before you start" list of principles, not just a to-do list
For this intent, the output should give the user confidence about what is stable and a clear list of what to fix before branching.
"Review this PR / feature"
Standard diff-focused review. See code-reviewer-strict for this path.
Good review heuristics
- Prefer evidence over vibes. Name files/modules/functions when making claims.
- Call out duplication only when it affects change cost, correctness risk, or conceptual clarity.
- Distinguish a local code smell from a design problem.
- Recognize when the current design is good enough and should not be over-abstracted.
- Reward stable seams, focused modules, and strong tests.
- Critique with precision: what hurts, why it hurts, and what a smaller better shape looks like.
Support files
references/pre-change-stabilization-checklist.md — structured checklist for the "solid foundation before a big update" review intent.references/nextjs-logic-duplication-patterns.md — common duplication patterns in Next.js apps (server/client logic drift, type redeclaration) and how to fix them.
Pitfalls to avoid
- Responding with a summary of unrelated prior work
- Skipping the repository-reading step and jumping straight to recommendations
- Inventing architectural intent that is not visible in the code or docs
- Recommending a large redesign when a smaller boundary cleanup would solve the actual problem
- Giving only negatives; note what should be preserved
- Claiming a config file is absent without actually checking
