New here? Get the free field guide →

← Blog

The One-Folder-One-Topic Rule, and Why It Matters More Than It Sounds

SpecDevShip · · 2 min readworkflowgetting-started
Contents

It's the least glamorous rule in SpecDevShip and one of the highest-leverage ones: every spec folder holds exactly one piece of work. Never place new, unrelated work into an existing folder. No shared catch-all folders. No numbered siblings for a different fix that happens to be similar in kind.

Why this needs to be a rule at all

Left to its own devices, an AI agent will happily reuse a folder that's "close enough" — especially late in a session, when creating a new, well-named folder feels like more ceremony than the change deserves. That instinct is exactly backwards. The five extra seconds it takes to name a new folder properly is the entire mechanism that keeps your spec history navigable a year from now.

What a good name looks like

Name folders after the actual thing being built or fixed — csv-export, dark-mode-toggle, login-redirect-bug — never a generic category like misc-fixes or ui-updates. If a good name doesn't come to mind immediately, a slightly awkward but specific name still beats a generic bucket name you'll be tempted to reuse and number later. login-redirect-bug-2 is a symptom that the first folder should never have been a bucket in the first place.

The exceptions, and why they're narrow

There are exactly two legitimate exceptions. First: a product's founding folder also holds its product.md — the one deliberate case where a folder carries both its own spec work and durable product context every later spec links back to. Second: genuinely continuing the same piece of work — revising something whose spec already exists, whether still draft or already implemented — isn't new work; it reopens the existing folder rather than creating a new one. Everything else gets its own folder, full stop.

What this buys you later

Six months in, a repo that followed this rule has a ./spec/ directory that reads like a table of contents for the product's actual history — one folder per decision, findable by name, each one scoped to something a person can actually hold in their head. A repo that didn't follow it has a junk drawer. The difference isn't visible on day one. It's extremely visible on day one hundred.

Get the free field guide. A short, practical eBook walking through the whole workflow — the tier decision framework, the investigate-before-you-fix discipline, and how the approval gates hold up day to day.

Grab your copy →