Skip to content

Add section on folder organization as system map #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
benvinegar wants to merge 3 commits into
base: main
Choose a base branch
from
+15 −3
Open

Add section on folder organization as system map #1

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
0741ad2
write-discoverable-code: stop flattening repos — folders organize, na…
claude Aug 19, 2026
e0940ca
Generalize the folder guidance to a single principle
claude Aug 19, 2026
6b3c398
Reframe folder guidance as positive rules, not a correction
claude Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 15 additions & 3 deletions write-discoverable-code/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ rules make code resolvable in one search instead of five.
disambiguates `users/diff.ts` from `orders/diff.ts` sits at the top of the file; the
search hit is at line 300. Put the context in the symbol (`formatDurationMs`), not the
folder. Exception: rigid, absolute conventions where the path carries the meaning
(e.g. every contract file exporting `Input`/`Output`).
(e.g. every contract file exporting `Input`/`Output`). Folders still group related
files (section 2); they just don't carry the name's context.
- **One concept, one spelling.** Pick `organizationId` or `orgId` and use it everywhere;
every synonym splits every future search in half. Reuse existing vocabulary in the
codebase you are editing rather than introducing near-synonyms.
Expand All @@ -47,7 +48,16 @@ rules make code resolvable in one search instead of five.
`billing-plan-config.ts`, not `config.ts`. (`index.ts` is acceptable only as a
thin re-export entry point.)

## 2. Types are the documentation agents can't skip
## 2. Folders are the map

A directory listing is the first search in an unfamiliar codebase, and it should read
as a map of the system. Group related files into folders — by feature, domain, or
layer, whichever organizing principle the codebase already follows — so each listing
shows a handful of named areas rather than every file at once. Folders carry the
grouping; context still lives in the symbol (section 1), so a name should make sense
even when quoted without its path.

## 3. Types are the documentation agents can't skip

- **Brand your primitive IDs.** `z.string().brand<'UserId'>()` (TS) or newtypes (Rust).
A `transferOwnership(userId: string, orgId: string)` signature makes argument
Expand All @@ -61,7 +71,7 @@ rules make code resolvable in one search instead of five.
uses to self-correct. `OrgScopedDb` explains itself; `Ctx2` does not. Avoid `any`: every
`any` is a spot where the compiler goes silent and the agent is back to guessing.

## 3. Say it where the search lands
## 4. Say it where the search lands

- **One-line doc comment on every export**, stating the sharpest constraint the code
itself can't show (units, timezone, "source time, not insert time", ownership).
Expand Down Expand Up @@ -105,3 +115,5 @@ rules make code resolvable in one search instead of five.
4. Do all log/error strings exist verbatim in the source?
5. Did anything change behavior without changing its name?
6. When code moved, is it gone from where it came from?
7. Does each new file sit in a folder alongside related code, and does the listing
still read as a map of the system?