Files, repos, and databases are the surface. The real work is designing behavior, state, rules, and boundaries.
A personal field guide I wrote to make myself a much better engineer. It is grounded partly in Parnas’s information hiding paper and Ousterhout’s software design philosophy, partly in my own synthesised mental model, and partly in the projects I am actually building.
When I look at software, I usually see files. That view is not wrong, but it is shallow.
When I open a project, the first things I see are repos, files, folders, databases, APIs, and configs. That is software as a filing cabinet. It is a real view, but it is the surface.
At the surface, software looks like file management. At the deeper level, software is behavior, state, rules, interfaces, and abstractions. The files are where it is written down. The behavior is what actually exists.
This essay is about training myself to see the second layer first.
One sentence: coding is designing and controlling behavior.
A useful definition I keep returning to:
Eight layers, from raw bytes up to product behavior. A way to know which floor I am actually working on.
Naming each artefact precisely so I stop treating them as interchangeable.
The shift from junior to senior engineering is the shift from “where do I put this file?” to “who is allowed to know this?”
A junior question: where should this file live? A senior question: who is allowed to know this thing?
The senior question is the one Parnas pushed in 1972. His paper on decomposing systems into modules argued that modularity is not just splitting a system into pieces. The effectiveness depends on the criteria used to divide the system. His central conclusion is sharp: it is usually wrong to begin decomposition from a flowchart of the program. Instead, begin with difficult design decisions or decisions likely to change, and design each module to hide one such decision from the rest of the system.[1]
That is information hiding. Modules should hide design decisions and expose as little as necessary through their interfaces. The rest of the system gets a small, stable contract; the messy decision lives in one place and can change without breaking everyone.
// scoring.ts
openai.chat.completions.create({ model: 'gpt-4o', ... })
// email.ts
openai.chat.completions.create({ model: 'gpt-4o-mini', ... })
// outreach.ts, summary.ts, evidence.ts, ...
// each importing the SDK directly
LLMClient hides model choice, prompt format, retries, fallback, and logging. Everyone else asks for a completion and stops caring how it is produced.// llmClient.ts -- the wall
export const llm = {
complete(prompt: Prompt): Promise<Completion> { ... }
}
// scoring.ts, email.ts, outreach.ts, ...
const result = await llm.complete(prompt)
// scoring.ts
if (apolloLead.organization?.estimated_num_employees > 50) ...
// email.ts
const company = apolloLead.organization?.name ?? '???'
ApolloAdapter converts the raw response into a NormalizedLead. The rest of the app only knows the normalised shape.// apolloAdapter.ts
export function fromApollo(raw): NormalizedLead { ... }
// scoring.ts
if (lead.employees > 50) ...
// email.ts
const company = lead.company.name
Ousterhout’s test: how much functionality does this module give me, behind how small an interface?
Ousterhout’s clearest idea is the deep module. A good module provides a lot of functionality through a small, simple interface. A shallow module gives little benefit but still adds cognitive cost: another name to learn, another file to open, another concept to keep in your head.[2]
He also pushes a wider definition of “interface.” The interface is not just method signatures. It is everything the caller has to understand to use the module correctly — side effects, dependencies, ordering assumptions, behavior under failure. If the docstring needs four paragraphs to be safe, the interface is not really small.[2]
function getCompanyName(company) {
return company.name
}
CompanyResolver.resolve(rawLead)
// - dedupes against existing companies
// - matches by domain + name fuzzy
// - enriches from secondary source on miss
// - returns a NormalizedCompany with confidence
Two different questions an engineer can ask. The second one compounds.
Ousterhout draws a sharp line between two mindsets. Tactical programming optimises for making the current thing work. Strategic programming invests in design so that future development stays easier. Tactical is fine in short bursts. The trap is doing it forever — every shortcut becomes the next person’s constraint.[2]
The honest version of strategic programming is not perfectionism. It is: every time I touch a file, I leave its structure slightly better than I found it.
A reading order that finds the architecture instead of getting lost in folders.
The folder structure is the map you get for free. The real architecture is the dependency and knowledge structure — which modules know what, and which decisions ripple when something changes. Question ten is the X-ray for that.
A reusable design note I fill in before opening an editor.
messageGenerator.generate(lead, campaign)The exercise is to name, for each product, the design decisions that should live behind one wall.
Specific code patterns that warn me I am leaking knowledge, not designing it.
processData, handleThing, manager, utils.The short version I want to carry around in my head.
What I built on, where I synthesised, and what I did not claim.
This essay is a synthesis of my own learning, grounded partly in Parnas’s information hiding paper and Ousterhout’s software design philosophy. The eight-layer model in Section 03 is my own framing, not a structure proposed by either author. Where I draw a specific claim from a source, the inline reference points to it.
Books, papers, and field maps on AI, software systems, intelligence, startups, and trust.
Open Reading Room