One File First
Gets the thing running in a single file before anyone decides where its pieces should live.
When to reach for it
Starting a new feature or prototype, when the agent's instinct is to create a folder of six files and an index before a single line has run.
What changes
- The first diff is one file plus zero new directories, with a stated command or URL for actually seeing it run.
- Types, constants, sample data, helpers, and styles stay inline until the behavior is agreed, so early changes touch one place.
- Splitting happens against a written trigger — a second caller, a size limit, a real runtime boundary — rather than on instinct.
- Future seams are marked as comments in the single file, so the eventual split is a move rather than a redesign.
Pairs with
- Keep the Diff SmallBounds a change to what you can actually read before approving it.
- Borrow the ShapeStarts new code from the closest existing file in your repo instead of from a blank page.
- Copy the NeighboursMakes new code look like the code already around it, instead of like whatever the agent prefers.
One File First
Structure decided before behavior is structure decided blind. Get it running in one file, then split on evidence.
1. Pick the file and the way to see it
Name the single file this will live in, and name how it gets run — a command, a route, a URL. If there is no way to look at it, that is the first thing to fix, not the code.
2. Put everything in that file
Types, constants, helper functions, sample data, styles, and the component or handler itself. All of it, in one file, in the order it reads best. Duplication inside this file is fine — it is one screen of scrolling, and it is going to change.
3. Fake the boring parts
Hardcode what is not the point yet: a fixed array instead of a fetch, a stubbed user instead of auth, a setTimeout instead of a job queue. Mark each stub with a comment naming what replaces it.
4. Run it and look at it
This is the gate, not a formality. Execute it, open it, click it. No structural work happens until something has actually run and been seen. Report what was observed.
5. Mark the seams, do not cut them
Where a boundary will eventually go, leave a comment saying so — "this block becomes the server query", "this section is the reusable list". Marking is free; cutting early is a guess.
6. Split only on evidence
Split when one of these is true, and say which one:
- A second caller genuinely exists — not is anticipated
- The file has passed the point where it can be read in one pass
- A real runtime boundary appears — server and client, worker and main thread, build-time and run-time
- Two people need to edit different parts at once
Rules
- No new directories, no barrel files, no index re-exports in this phase.
- No abstraction with one caller. A function extracted for tidiness with a single call site is a rename with extra steps.
- Do not wire real infrastructure — migrations, queues, third-party accounts — before the behavior has been agreed.
- Do not skip step 4. A file that has never executed is not a prototype, it is a proposal.
- Do not carry the stubs into the split silently. When the file is divided, list every stub still present.