Codebase organizer

Codebase Organizer

Maintain optimal file sizes for AI-assisted development by splitting large files into focused modules.

Configuration

Variable	Default	Description
SOURCE_DIR	.	Root source directory to scan
FILE_EXT	*	File extension filter (e.g., *.go, *.ts, *.py)
MAX_LINES	800	Maximum lines before file must be split
TEST_CMD	make test	Command to run tests
LINT_CMD	make lint	Command to run linter

Quick Start

# Find large files in your project
find ${SOURCE_DIR:-.} -name "${FILE_EXT:-*}" -exec wc -l {} \; | awk '$1 > 500 {print}' | sort -rn

When to Use This Skill

Invoke when user says:

• "Check file sizes" / "report file sizes"
• "Split this file" / "refactor large file"
• "Organize the codebase"
• "Make files AI-friendly"

File Size Targets

Size	Status	Action
200-500 lines	Sweet spot	None needed
500-800 lines	Acceptable	Consider splitting
>800 lines	CRITICAL	Must split

Workflow

Step 1: Status Check

# Find all large files
find ${SOURCE_DIR:-.} -name "${FILE_EXT:-*}" -type f -exec wc -l {} \; | awk '$1 > 500 {print}' | sort -rn

Output format:

CRITICAL (>800 lines):
  src/parser/parser.ts: 2518 lines

WARNING (500-800 lines):
  src/eval/evaluator.py: 765 lines

Step 2: Plan the Split

Before ANY refactoring:

1. Run baseline tests: ${TEST_CMD}

2. Identify natural boundaries:

   • Different responsibilities or concerns
   • Public API vs internal helpers
   • Different data types or domains
   • Logical groupings of related functions

3. Plan file names (match to primary functions):

   • expressions.ts → expression handling
   • statements.ts → statement handling
   • helpers.ts → utility functions

4. Check for circular dependency risks

Step 3: Execute Split

# 1. Create new files with clear names
# 2. Move related functions together (maintain cohesion)
# 3. Update imports in all affected files
# 4. Keep main types/structs in the primary file

Keep together:

• Tightly coupled functions
• Helper functions used by one main function
• Functions that share complex state

Step 4: Validate

# MUST run after every split
${TEST_CMD}     # All tests must pass
${LINT_CMD}     # No linting errors

If tests fail:

1. DO NOT COMMIT
2. Analyze failure (missing import? broken reference?)
3. Fix issue
4. Re-run tests
5. Only commit when tests pass

Step 5: Document & Commit

Commit with descriptive message:

git add src/path/*.ext
git commit -m "Split path/file.ext into N files (AI-friendly)

- primary.ext: Main types (200 lines)
- expressions.ext: Expression handling (450 lines)
..."

Error Handling

Circular Dependency

If split creates circular dependency:

1. Identify cycle: File A imports B, File B imports A
2. Solutions:
   • Extract shared code to new file (e.g., types.ext)
   • Use interfaces to break dependency
   • Restructure to have one-way dependency
   • Merge files if truly inseparable (<800 lines combined)

Test Failures

Common issues after split:

• Missing import in new file
• Function moved but still referenced in old location
• Test file not updated to match new structure

Success Metrics

After refactoring:

• 0 files over 800 lines
• <5 files between 500-800 lines
• Average file size: 300-400 lines
• 100% test pass rate maintained

Important Reminders

• ALWAYS run tests before and after refactoring
• NEVER commit if tests fail
• One refactoring at a time (easier to debug)
• Show plan before executing (get user approval)
• Keep related functions together (maintain cohesion)