codebase-assessment
Use when starting open-ended tasks in unfamiliar codebases, before following existing patterns
When & Why to Use This Skill
The Codebase Assessment skill is a specialized diagnostic tool designed to evaluate the maturity, architectural patterns, and technical health of unfamiliar repositories. By systematically analyzing configuration files, dependency signals, and coding consistency, it enables developers and AI agents to align their implementation strategy with the project's actual state—preventing technical debt and ensuring adherence to established standards.
Use Cases
- Initial Project Onboarding: Quickly grasp the coding standards and 'state of health' of a new repository before contributing code.
- Legacy System Analysis: Identify outdated patterns and inconsistent structures in older projects to propose informed refactoring or modernization strategies.
- AI-Driven Development Guardrails: Provide AI agents with a structured context of the codebase (Disciplined vs. Chaotic) to ensure generated code follows local conventions.
- Pre-Implementation Audit: Verify the presence of essential developer tools like linters, type-checkers, and test frameworks to maintain project integrity.
- Consistency Checks: Sample existing files to determine if a project is in a transitional state, helping decide which architectural patterns to follow.
| name | codebase-assessment |
|---|---|
| description | Use when starting open-ended tasks in unfamiliar codebases, before following existing patterns |
Codebase Assessment
Assess codebase maturity before implementing. Don't blindly follow patterns that may be outdated or inconsistent.
Quick Assessment Checklist
- Check config files: linter, formatter, type config present?
- Sample 2-3 similar files: Are patterns consistent?
- Note project age signals: Dependencies current? Patterns modern?
State Classification
| State | Signals | Your Behavior |
|---|---|---|
| Disciplined | Consistent patterns, configs present, tests exist | Follow existing style strictly |
| Transitional | Mixed patterns, some structure | Ask: "I see X and Y patterns. Which to follow?" |
| Legacy/Chaotic | No consistency, outdated patterns | Propose: "No clear conventions. I suggest [X]. OK?" |
| Greenfield | New/empty project | Apply modern best practices |
Verification Before Assuming
If codebase appears undisciplined, verify before assuming:
- Different patterns may serve different purposes (intentional)
- Migration might be in progress
- You might be looking at the wrong reference files
What To Check
| Area | Check For |
|---|---|
| Style | ESLint/Prettier/Biome config, consistent formatting |
| Types | tsconfig.json strictness, type coverage |
| Testing | Test framework, coverage expectations, test file patterns |
| Structure | Folder conventions, naming patterns, module boundaries |
| Dependencies | Package age, maintenance status, duplicate functionality |
Output Format
After assessment, state:
Codebase state: [Disciplined/Transitional/Legacy/Greenfield]
Key patterns to follow: [list 2-3]
Concerns noted: [any issues observed]
Proceeding with: [your approach]