Codebase Readiness
Most teams struggling with AI agents have a codebase problem, not a model problem.
You’ve seen it: an agent rewrites a file, the tests pass, but the code doesn’t follow your conventions. Or worse, there are no tests to catch what it broke. Weak test coverage, unclear architecture, missing type safety, no feedback loops. These aren’t minor inconveniences. They’re the reason agents produce drift instead of value.
This free assessment scores your repo across the 8 dimensions that matter most for AI-assisted development and gives you a prioritized roadmap to close the gaps.
A codebase readiness assessment evaluates how well your repository supports AI-assisted development. It measures test coverage, architecture clarity, type safety, feedback loops, and five other dimensions that determine whether AI agents produce useful output or compound drift.
Run It in 60 Seconds
The assessment is an agent skill. Install it, run it, get your score.
Via npx:
Via Claude plugin marketplace:
The assessment runs locally against your repo. Nothing is sent externally.
Built by Damian Galarza — 15+ years building production software, former CTO (scaled 0→50+), currently shipping AI features daily as a Senior SWE.
What It Measures
Eight dimensions benchmarked against teams shipping 1,000+ AI-generated PRs per week. Each dimension gets a weighted score contributing to your overall rating (0-100).
Test Foundation
Coverage, speed, reliability. Agents need fast, trustworthy feedback to know if their changes work. Without it, they guess.
Architecture Clarity
Layering, dependency direction, separation of concerns. Agents replicate existing patterns. Without clear boundaries, agent output drifts across concerns and couples things that shouldn't be coupled.
Type Safety
Static analysis, type coverage, schema validation. Types constrain the solution space. Without them, agents make changes that compile but fail silently at runtime.
Feedback Loops
Linting, CI speed, error messages. Agents learn from error output. Without quality feedback, agents repeat the same mistakes and you spend human time catching what automation should catch.
Documentation as Code
CLAUDE.md quality, architecture docs, inline context. This is how agents understand intent. Without it, agents produce code that passes every check but misses the point.
Dependency Health
Outdated packages, security vulnerabilities, lockfile hygiene. Without healthy dependencies, agents inherit unpredictable behavior they can't reason about or debug.
Development Environment
Setup scripts, containerization, reproducibility. Without a consistent environment, agents produce changes that work locally and break everywhere else.
Code Consistency
Formatting, naming conventions, structural patterns. Without consistency, every agent change looks like it was written by a different developer.
Sample Assessment Output
Here's what a real assessment looks like. This Rails codebase scored 46/100 — strong code clarity, but documentation and feedback loop gaps that limit agent effectiveness.
| Dimension | Weight | Score |
|---|---|---|
| Test Foundation | 25% | 57/100 |
| Documentation & Context | 15% | 14/100 |
| Code Clarity | 15% | 82/100 |
| Architecture Clarity | 15% | 55/100 |
| Feedback Loops | 10% | 25/100 |
| Type Safety | 10% | 21/100 |
| Consistency & Conventions | 5% | 25/100 |
| Change Safety | 5% | 35/100 |
Critical Findings
- Feedback Loops (25/100): CI runs tests but lacks linting, security scanning, and pre-commit hooks. Agents get pass/fail feedback only.
- Documentation & Context (14/100): No CLAUDE.md, no ARCHITECTURE.md, no ADRs. Agents must reverse-engineer all conventions from code alone.
- Type Safety (21/100): Zero model validations. Dynamic method dispatch in data pipelines creates fragile interfaces where typos fail silently.
View Improvement Roadmap
- Create a CLAUDE.md with build/test/lint commands, environment variables, and domain model overview
- Add ActiveRecord validations to all domain models (currently zero)
- Add RuboCop to the CI pipeline for automated style feedback
- Increase test coverage from 43% to 60%+ (priority: controllers and data import pipeline)
- Add SimpleCov enforcement with a minimum threshold
- Add pre-commit hooks for immediate local feedback
What Every Assessment Includes
- A single score (0-100) that tells you exactly where you stand, with a band rating from Agent-Ready to Foundation
- Per-dimension breakdown showing exactly where you're strong and where the gaps are
- A prioritized improvement roadmap ordered by impact, not effort
- Specific, actionable recommendations tied to your actual codebase
Who This Is For
- Engineering leads evaluating whether their codebase is ready for AI-assisted development at scale
- Teams that tried Claude Code or Copilot and got inconsistent results they couldn’t explain
- Anyone about to invest in AI tooling who wants to know what to fix first
- Teams already using AI agents who want to improve output quality systematically
What Clients Say
"Working with Damian was one of the most productive technical sessions we've had. He quickly understood where we were with AI tooling and gave us immediately actionable advice, not generic frameworks. He identified gaps we hadn't considered, walked us through how he architects agent loops in production, and helped us think through our product-level agent strategy without over-engineering it. If you're a technical founder trying to move faster with AI, Damian is the person to talk to."
"I discovered Damian on YouTube. I found his videos especially clear-headed. I booked a couple of private sessions to discuss OpenClaw, and to my delight, he was equally clear-headed in person."
What to Do With Your Results
Work Through It Yourself
The roadmap tells you exactly what to fix and in what order. For documentation gaps, the companion agent-ready plugin scaffolds CLAUDE.md, ARCHITECTURE.md, and a docs/ structure automatically. If your team has the bandwidth, you can close most gaps on your own.
Get StartedAI Workflow Enablement
From $8k
A structured 3-8 week engagement where I work with your team to close the gaps the assessment surfaces. Custom CLAUDE.md systems, shared skills, workshops built on your actual codebase. You get a team that ships confidently with AI, not just a few power users.
Writing on AI-Assisted Development
Context on why codebase readiness matters and how it connects to production AI workflows.
How I Use Claude Code: My Complete Development Workflow
The full workflow after a year of daily use. How codebase structure directly impacts agent output quality.
Build Efficient MCP Servers: Three Design Principles
Token efficiency, clear boundaries, structured output. Design principles that apply to agent-ready codebases too.
MCPs vs Agent Skills
Understanding the architecture decisions that shape how agents interact with your codebase.
Frequently Asked Questions
What is a codebase readiness assessment?
A codebase readiness assessment evaluates how well your repository supports AI-assisted development. It scores your repo across 8 dimensions (test foundation, architecture clarity, type safety, feedback loops, documentation, dependency health, dev environment, and code consistency) and produces a prioritized improvement roadmap.
How do I know if my codebase is ready for AI agents?
Run the assessment. You'll get a score from 0-100 with a band rating: Agent-Ready (80+), Strong (60-79), Developing (40-59), or Foundation (below 40). The per-dimension breakdown shows exactly where your strengths and gaps are.
What does the assessment actually check?
Eight dimensions benchmarked against teams shipping 1,000+ AI-generated PRs per week: test coverage and speed, architecture layering, type safety, CI and linting feedback loops, CLAUDE.md and documentation quality, dependency health, development environment reproducibility, and code formatting consistency.
Does the assessment send my code anywhere?
No. The assessment runs entirely inside Claude Code on your local machine. Your code never leaves your environment.
What do I need to run it?
The assessment is an agent skill. You can install it via npx skills add (works with any tool that supports agent skills) or through the Claude Code plugin marketplace.
What if my score is low?
That's the point of running it. The assessment produces a prioritized improvement roadmap ordered by impact. Most teams can close the highest-impact gaps on their own. For teams that want hands-on help, the AI Workflow Enablement program works through these gaps on your actual codebase.
Not Sure Where to Start?
Run the assessment first. If the results raise questions or you want help prioritizing, book a free intro call. We'll look at your score together and figure out the right next step.
No pitch. No pressure. Just a conversation about what the numbers mean for your team.
Building with AI agents? Stay in the loop.
Practical insights on AI-assisted development, agent architecture, and making codebases work with AI tools.
Occasional emails. No fluff.