Codebase Classification Skill

Analyze and classify codebases before making changes to ensure appropriate development approach.

Overview

Before modifying any codebase, classify it to determine whether to:

• •Follow existing patterns (Disciplined)
• •Gradually improve while following conventions (Transitional)
• •Propose improvements to legacy patterns (Legacy)
• •Establish best practices from scratch (Greenfield)

Classification Types

1. Disciplined Codebase

Signals:

• •Consistent code style (formatting, naming conventions)
• •Comprehensive test coverage (>70%)
• •Clear module boundaries and interfaces
• •Type hints/annotations throughout
• •Up-to-date dependencies
• •Active CI/CD pipeline
• •Good documentation (README, docstrings)

Approach: Follow existing patterns strictly. Don't introduce new conventions.

2. Transitional Codebase

Signals:

• •Mixed code quality (some areas good, others not)
• •Partial test coverage (30-70%)
• •Some type hints, inconsistent usage
• •Active development with modernization efforts
• •Dependencies somewhat current

Approach: Follow existing conventions in touched areas. Propose improvements for new code.

3. Legacy Codebase

Signals:

• •Inconsistent patterns across the codebase
• •Minimal or no tests (<30% coverage)
• •No type hints
• •Outdated dependencies
• •Complex, undocumented logic
• •Possibly unmaintained

Approach: Be careful with changes. Add tests before modifying. Propose gradual improvements.

4. Greenfield Codebase

Signals:

• •New project (<6 months old)
• •Few files (<20 source files)
• •No established patterns yet
• •Minimal or no tests (but not legacy)
• •Active initial development

Approach: Establish best practices from the start. Set up proper structure, testing, CI.

Quick Classification Checklist

Run this analysis before making significant changes:

1. Check test coverage: Is there a test/ or tests/ directory? How comprehensive?
2. Check type hints: Are functions annotated? Is there py.typed or mypy config?
3. Check CI/CD: Is there .github/workflows/, .gitlab-ci.yml, or similar?
4. Check code style: Is there .pre-commit-config.yaml, ruff.toml, or similar?
5. Check dependencies: When was requirements.txt/pyproject.toml last updated?
6. Check documentation: Is there a comprehensive README? API docs?

Decision Matrix

Behavior Guidelines

When Disciplined

• •Study existing patterns before writing new code
• •Match naming conventions exactly
• •Follow established module structure
• •Add tests matching existing test style
• •Don't propose architectural changes without strong justification

When Transitional

• •Follow patterns in the specific area you're modifying
• •Match quality of surrounding code or slightly better
• •Add tests for new functionality
• •Document rationale for any pattern deviations

When Legacy

• •Add tests BEFORE modifying code
• •Make minimal changes to achieve goal
• •Document assumptions and findings
• •Propose improvements as separate follow-up work
• •Be extra careful with untested code paths

When Greenfield

• •Establish best practices immediately
• •Set up proper project structure
• •Configure linting, formatting, type checking
• •Write tests for new functionality
• •Create comprehensive documentation

Examples

Identifying Disciplined Codebase

$ ls -la
pyproject.toml          # Modern packaging
.pre-commit-config.yaml # Style enforcement
mypy.ini                # Type checking
.github/workflows/      # CI/CD

$ wc -l tests/**/*.py
2500 total              # Substantial tests

→ Classification: DISCIPLINED
→ Approach: Follow existing patterns strictly

Identifying Legacy Codebase

$ ls -la
setup.py                # Old-style packaging
requirements.txt        # Pinned 3 years ago
# No tests directory
# No CI configuration

$ grep -r "def " src/ | head -5
def process_data(x):    # No type hints
def handle_input(data): # No docstrings

→ Classification: LEGACY
→ Approach: Careful changes, add tests first

Integration

This skill helps agents:

1. •Avoid imposing new patterns on well-structured codebases
2. •Avoid perpetuating bad patterns in legacy codebases
3. •Make appropriate improvement suggestions
4. •Set up proper structure for new projects

Related

• •Tool: shell (for running analysis commands)
• •Tool: read (for examining codebase structure)