Tip: Methodology for working with large codebases (15K+ lines) without 503 crashes

[leeluling]

The Problem

Working with large files (15K+ lines) in Claude Code causes context overflow → 503 → permanent session death. I lost 20+ sessions trying to migrate a 15K-line Python app from SimpleGUI to WebView.

The Solution

A 6-principle methodology that finally made it work:

1. Protect the Main Agent — delegate all heavy reading/writing to subagents (Agent tool). If a subagent 503s, your session survives.
2. Save Early, Save Often — commit after every unit of work. Assume the session can die anytime.
3. Minimize Context Consumption — only read what you need, use line ranges, keep output concise.
4. Break Big Tasks into Small Pieces — decompose until each piece fits in one subagent call.
5. Reserve Context Buffer — don't push to the limit.
6. Design for Session Continuity — progress files + descriptive commits so new sessions resume seamlessly.

Core idea

Treat the main agent as a project manager, not a developer. It never reads the big file directly. It delegates focused tasks to disposable subagent workers.

Full guide + templates

I published a complete guide with a copy-paste CLAUDE.md snippet and progress tracker template:

GitHub: https://github.com/leeluling/large-codebase-survival

Hope this helps others dealing with the same pain!