One file does too much
A single file accumulates unrelated responsibilities and becomes a local gravity well.
- Where you see this
controllersservice classesjob handlerslegacy integration points
- Not necessarily a problem when
- the file is large because of data tables or declarative mappings that remain easy to reason about
- Often mistaken for
- big file equals bad design in all cases
- Time horizon
- near-term
- Best placed to act
module ownertech lead
The signal
What you would actually notice
Local convenience becomes systemic fragility. The file becomes hard to understand, review, and safely change.
Field observation
Large files mixing business logic, validation, orchestration, transformations, and edge-case handling.
Also observed
- This file is where the real behavior lives.
- Do not split it yet or we will lose the flow.
- Every incident fix touches this file.
Primary reading
What it usually indicates
Most likely underlying patterns when this signal shows up. Not a diagnosis, a starting hypothesis.
Usually indicates
Most likely underlying patterns when this signal shows up.
- weak decomposition discipline
- urgent patches landing in the easiest visible place
- missing domain boundaries
Stakes
Why it matters
Local convenience becomes systemic fragility. The file becomes hard to understand, review, and safely change.
Inspection
What to check next
Deliberate steps to confirm or disconfirm the primary reading above. Not a checklist. An order of inspection.
- change history
- review frequency
- ownership patterns
Diagnostic questions
Questions to ask the team, or yourself, before concluding anything.
- How many distinct reasons does this file change?
- Could this file be explained as one coherent concept?
- What responsibilities are accidentally coupled here?
Progression
Under the signal
Where this pattern tends to come from, what's holding it up, and where it goes if nothing changes.
Leading indicators
What tends to show up first.
- reviewers skip full-file review
- small changes trigger fear
- merge conflicts cluster in one place
Common root causes
What is usually sitting under the signal.
- shortcut culture
- missing decomposition standards
- unclear ownership
Likely consequences
What happens if nothing changes.
- review fatigue
- merge conflict hotspots
- harder testing
- fear-based maintenance
Look-alikes
Not what it looks like
Patterns that can be mistaken for this signal, and 'fix' attempts that make it worse.
- big file equals bad design in all cases
- small files automatically mean good design
Anti-patterns when responding
Responses that feel sensible and usually make the underlying pattern worse.
- solving file growth by adding regions or comments instead of splitting responsibilities
- treating line count as the only signal
Context
Context and ownership
Where this signal surfaces, who sees it first, who can actually act, and how much runway there usually is before escalation.
Where it shows up
- controllers
- service classes
- job handlers
- legacy integration points
Who sees it first
Before it escalates.
- reviewers
- new joiners
- maintainers
Who can move on it
Not always the same as who notices it.
- module owner
- tech lead
near-term
How much runway there usually is before the signal hardens into the underlying pattern.
AI impact
AI effects on this signal
How AI-assisted and AI-driven workflows tend to amplify or hide this signal.
AI amplifies
Ways AI tooling tends to make this signal louder or more common.
- AI makes it easy to append more logic into the already-central file because it predicts the local pattern well.
AI masks
Ways AI tooling tends to hide this signal, so it keeps growing under the surface.
- Uniform generated style can make a bloated file look orderly.
Relationships
Connected signals
Related failure modes, decisions behind the signal, response playbooks, and neighboring red flags.