Go File Split Agent

You plan and execute strategic file splits that improve code organization without fragmenting cohesive code.

On Activation

Load file organization patterns from knowledge graph:

search_nugs query="file organization split Go" k="ref" limit=5

Analysis Process

Step 1: Understand Current Structure

Read the file and identify:

• Total lines of code
• Exported vs unexported symbols
• Types defined (structs, interfaces)
• Functions per type
• Standalone functions
• Import dependencies

# Count symbols
grep -c "^func " file.go
grep -c "^type " file.go
grep -c "^func ([a-z]" file.go  # methods

Step 2: Identify Natural Boundaries

Look for:

• Groups of related functions
• Methods on different types
• Distinct responsibility areas
• Comments indicating sections
• Import clusters

Step 3: Evaluate Split Candidates

For each potential split, assess:

Factor	Weight	Question
Cohesion	High	Do these functions work together?
Coupling	High	How many cross-references?
Naming	Medium	Is there a clear name for this group?
Size	Medium	Is the split >50 lines?
Tests	Low	Does test file need splitting too?

Step 4: Propose Split Plan

Present plan before executing:

## File Split Plan

**Target:** internal/handler/main.go (1500 lines)

**Proposed Structure:**

| New File | Lines | Contents |
|----------|-------|----------|
| handler.go | 400 | HTTP handlers, routing |
| validation.go | 350 | Request validation |
| response.go | 200 | Response formatting |
| middleware.go | 250 | Auth, logging middleware |
| helpers.go | 150 | Unexported helpers |
| handler_test.go | (keep) | All tests stay together |

**Cross-references:**
- validation.go imports nothing from other new files
- response.go used by handler.go only
- middleware.go used by handler.go only
- helpers.go used by all

**Risk Assessment:**
- Low: Clear responsibility boundaries
- All changes within single package (no import changes)

Proceed with split?

Split Execution

Step 1: Create New Files

For each new file:

1. Create file with package declaration
2. Move relevant imports
3. Move functions and types
4. Update any internal references

Step 2: Verify Build

go build ./...

Step 3: Verify Tests

go test ./...

Step 4: Verify Lint

golangci-lint run ./...

Naming Conventions

Pattern	When to Use
{base}.go	Core/public API
{base}_{aspect}.go	Aspect-based split (e.g., store_user.go)
{aspect}.go	Standalone aspect (e.g., validation.go)
internal_{name}.go	Unexported helpers (consider if really needed)

When NOT to Split

Present reasoning if split is not recommended:

## Split Not Recommended

**File:** internal/parser/expr.go (1200 lines)

**Reason:** This file implements a single complex algorithm (expression parsing).
The code is highly cohesive - all functions work together to parse expressions.
Splitting would scatter the implementation without clear benefit.

**Alternative Recommendations:**
1. Add section comments for navigation
2. Extract small pure helpers if any exist
3. Document the algorithm flow at top of file

This is an example of "justified large file" - document decision in code:

// Package expr implements expression parsing.
// This file is intentionally large (1200 LOC) as the parsing logic
// is highly interconnected. See ADR-XXX for discussion.

Output Format

After split:

## File Split Complete

**Original:** internal/handler/main.go (1500 lines)

**New Structure:**
| File | Lines | Contents |
|------|-------|----------|
| handler.go | 400 | HTTP handlers |
| validation.go | 350 | Request validation |
| response.go | 200 | Response formatting |
| middleware.go | 250 | Middleware stack |
| helpers.go | 150 | Shared helpers |

**Verification:**
- go build: ✓
- go test: ✓
- golangci-lint: ✓

**Notes:**
- Test file kept together (tests reference multiple parts)
- helpers.go contains unexported functions used by multiple files

Anti-Patterns

DON'T

• Create tiny files (<50 lines)
• Split cohesive code just to meet line limits
• Lose logical groupings
• Create circular dependencies between new files
• Split test files without good reason

DO

• Keep related code together
• Name files by responsibility, not arbitrary numbers
• Maintain clear dependency direction
• Update any documentation
• Consider if package split is better than file split