You are vibecoding. You are moving fast. You ask Claude for a feature, it adds it. You keep iterating and your app keeps working, so you keep going.
A few hours later you have a single file that contains everything:
- UI
- state
- data fetching
- business logic
- formatting helpers
- edge-case fixes
- debug code you meant to remove
This is common in prototyping. It is also where handoff pain begins.
Engineering teams optimize for code that stays workable over months and years. They need code that is easy to scan, easy to test, and safe to modify. A massive file makes all of those harder.
This post has three parts:
- The engineering principles that keep projects easy to collaborate on
- How to create a reusable
principles-and-layout.mdprimer for Claude sessions - How to turn that primer into a Claude slash command so you can apply it instantly at the start of a session
Why AI Sessions Create Mega-Files
AI is excellent at local edits. Adding a new feature often feels easiest inside the file you already have open.
That pattern repeats:
- add feature
- add one more feature
- patch an edge case
- add another hook
- add a helper function near the code that uses it
The file grows because the workflow is optimized for speed in the moment.
Teams navigate code by predictable places:
- UI lives in clear folders
- data access lives in clear folders
- shared utilities are centralized
- domain rules are isolated
A mega-file removes that map.
Part 1: Engineering Principles That Keep Handoffs Smooth
These principles reduce friction during reviews, debugging, onboarding, and refactoring.
1) Build Wide
As the app grows, add modules and folders instead of expanding one file.
Benefits:
- easier navigation
- fewer merge conflicts
- cleaner ownership boundaries
- smaller review surfaces
Quick smell test: If you cannot describe a file in one sentence, it is doing too much.
2) Separate Concerns
Common buckets that work well:
- UI components: rendering and layout
- hooks: wiring, state, orchestration
- services: API calls and persistence
- domain logic: rules and transformations
- utils: shared helpers
Once you have these buckets, code becomes easier to reason about.
3) Prefer Pure Functions for Domain Logic
A pure function is simple to test and reuse. It takes inputs and returns an output. It does not mutate global state or trigger side effects.
If most business rules are pure functions, refactors become far safer.
4) Use Predictable Naming
Naming is navigation. Teams search code constantly.
Conventions that stay readable:
- components:
UserCard.tsx,PricingTable.tsx - hooks:
useUsers.ts,useBilling.ts - services:
users.service.ts,billing.service.ts - types:
users.types.ts - utils:
formatCurrency.ts,parseDate.ts
Predictable names speed up onboarding and reviews.
5) Keep Modules Focused
A common prototype pattern is one component slowly becoming a whole application.
When modules stay focused:
- changes stay local
- bugs are easier to isolate
- tests are easier to write
- reviews are faster
Aim for smaller units that compose well.
6) Make State Intentional
Mega-files tend to grow accidental state:
- duplicated state
- derived values stored as state
- state updated from many places
Guidelines that help:
- keep state close to where it is used
- derive computed values instead of storing them
- name state by intent (
selectedUserId,isCheckoutOpen) - centralize cross-cutting concerns (auth, feature flags) in a clear place
7) Create Clear Boundaries Around Data Access
Fetching should live behind a small set of functions. That makes your UI simpler and your code easier to test.
A practical split:
- services perform API calls and persistence
- hooks orchestrate calls and expose data to UI
- UI renders based on hook outputs
8) Treat Errors and Loading as First-Class
A team-friendly app handles reality:
- loading states are consistent
- errors surface predictably
- retries and timeouts exist where needed
When this is standardized, the app feels coherent.
9) Write Code That Can Be Tested
You do not need a huge test suite to benefit from testability. You need structure that makes testing possible.
Pure functions plus separation of concerns tends to get you there.
10) Document Intent
Fast code still needs intent:
- assumptions
- constraints
- tradeoffs
- known limitations
Short notes in the right places prevent future confusion.
Part 2: The Claude Primer That Prevents Mega-Files
The goal is simple. You want a default that keeps your project organized while you build quickly.
Create a markdown file that you can paste at the start of a Claude session:
- principles
- folder layout
- naming rules
- feature workflow
- anti-patterns to avoid
This changes how new code gets added.
How to Create principles-and-layout.md
Step 1: Write Your Non-Negotiables
Keep it short. Make it strict.
Examples:
- Build wide: create new modules and folders as features grow
- Separate UI, hooks, services, and domain logic
- Prefer pure functions for business rules
- Keep route files thin
- Use consistent naming conventions
- Handle loading and error states consistently
Step 2: Define a Folder Structure You Will Follow
For a Next.js-style project, this stays practical:
/appfor routes and pages/componentsfor shared UI components/features/<feature-name>components/hooks/services/types/utils/
/libfor shared infrastructure (API client, config)/styles/tests(optional early, useful to reserve)
Step 3: Lock in Naming Conventions
Examples:
- Components: PascalCase (
UserCard.tsx) - Hooks:
useX(useUsers.ts) - Services:
x.service.ts(users.service.ts) - Types:
x.types.ts - Utils: clear verbs and nouns (
formatCurrency.ts)
Step 4: Define the Feature Workflow
Rules that work well:
- UI goes in feature components
- data access goes in feature services
- orchestration goes in feature hooks
- business rules go in feature utils as pure functions
- pages compose modules and stay small
- split files that grow beyond 250 lines
Step 5: List Anti-Patterns Explicitly
Examples:
- no large blocks of logic inside page components
- no mixing rendering, fetching, and business rules in one component
- no duplicated helpers across files
- no vague names like
thing,handler,data2 - no commented-out abandoned implementations in production files
Part 3: Turn Your Primer Into a Claude Slash Command
If you use Claude regularly, the fastest workflow is a slash command that inserts your primer automatically.
The idea is simple:
- store your primer text in one place
- trigger it with a short command at the start of a session
- keep your sessions consistent without copy-pasting a long block every time
Step 1: Save the primer text
Keep the contents in a single markdown file in your repo:
principles-and-layout.md
If you update your structure later, update this file once.
Step 2: Create a slash command in Claude
Create a custom slash command that expands into your primer.
Example command name:
/teamready
Command content:
- paste the full contents of
principles-and-layout.md
Step 3: Use it at the start of every session
Your first message becomes:
/teamready- then your folder tree
- then your feature request
Example:
/teamready Current folder tree: app/ components/ features/ lib/ Feature request: Add a billing settings page with a plan selector and Stripe checkout. Keep route files thin and place logic in features/billing.
This sets the rules early and prevents the session from drifting into mega-file edits.
Step 4: Add a second command for new features
Optional, but useful.
Create another slash command for feature scaffolding, for example:
/newfeature
Its content can be a short checklist that Claude follows:
- create
/features/<name>/with components/hooks/services/types/utils - add an index file if you use barrel exports
- add placeholder tests if you want
Then your workflow becomes:
/teamready/newfeature billing- request feature details
This keeps structure consistent even when you move fast.
Copy-Paste Starter: principles-and-layout.md
# Project Principles and Layout (Claude Primer) ## Goal Build quickly with AI while keeping the project easy to read, change, and hand off to engineers. ## Non-Negotiable Principles 1. Build wide. Add small modules instead of growing mega-files. 2. Separate concerns: - UI components render - hooks orchestrate state and calls - services handle data access - domain logic is pure functions 3. Keep route/page files thin. 4. Use predictable naming and folder placement. 5. Handle loading and errors consistently. ## Folder Layout - /app - route/page files (thin composition only) - /components - shared UI components - /features/<feature-name>/ - components/ - hooks/ - services/ - types/ - utils/ - /lib - shared infrastructure (api client, config, constants) - /styles - /tests (optional early, reserve space) ## Naming Conventions - Components: PascalCase (UserCard.tsx) - Hooks: useX (useUsers.ts) - Services: x.service.ts (users.service.ts) - Types: x.types.ts - Utils: clear verbs and nouns (formatCurrency.ts, parseDate.ts) ## Feature Workflow When implementing a new feature: 1. Place it in /features/<name>/ (create the folder if needed). 2. UI goes in /features/<name>/components. 3. Data access goes in /features/<name>/services. 4. Orchestration goes in /features/<name>/hooks. 5. Business rules and transformations go in /features/<name>/utils as pure functions. 6. Keep route/page files as thin composition. 7. Split any file that exceeds 250 lines. ## Anti-Patterns - No large logic blocks inside route/page files. - No mixing rendering, fetching, and business rules in one component. - No duplicated helpers across files. Extract to utils. - No vague names like thing, data2, doStuff. - No commented-out abandoned code in production files. ## Output Expectations - Prefer multiple small files over one large file. - Keep modules focused and imports clean. - Add short comments explaining intent when needed.
Final Thought
Speed gets you a working prototype. Structure keeps it shippable.
If you want to collaborate with engineers, give them a codebase they can navigate quickly and change safely.
That is vibecoding with structure.