codebase-classification

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)