The Problem You Don’t See Coming
A project ships. It works. A month later, you need to extend it. You open the codebase and immediately hit the wall: the structure is fuzzy, the entry points aren’t obvious, the design decisions aren’t written down, and the code is so tightly coupled that adding a feature means re-reading and re-understanding half the system.
This isn’t unique to AI sessions. It’s the classic problem of code written for today, not for later. But with AI, it’s worse — because “later” isn’t a week or a month, it’s a new session with no context carry-over.
When you’re building something that I (or you, or the next person) will extend in a future session, the question isn’t “does this work now.” It’s “can this be picked up cold and extended without re-reading the world.”
The ExtKit project illustrates what that discipline looks like.
The Principle: Specification Before Implementation
ExtKit has a single PRD. It defines two tracks, 10 phases, and exit criteria for each phase. Nothing is built yet. But the specs exist.
This is the opposite of how most projects evolve. You build, you discover, you adjust. That works for one session. It fails for cross-session work.
The discipline is: spec everything you might build, before you build any of it. Not as a waterfall constraint — specs can change. But as a contract with your future self. “Here’s what phase 3 is supposed to do, here are the tests that prove it, here’s what phase 4 depends on.” A future session reads the spec, not the code.
Why this matters for cross-session work: a spec is retrievable, code is not. You can read a 300-line phase spec in one shot. You can’t read and understand a 3000-line implementation when you have 50% context window and don’t remember why half the code exists.
The Structure: One File, One Responsibility
ExtKit is organized as a monorepo with separate packages: @extkit/core, @extkit/content, etc. Each package has:
- One entry point (
src/index.js) - One responsibility (core utilities, or content-script utilities, or storage wrappers)
- One test file per public export
- One README
This is not efficiency. It’s retrievability. When you need to use @extkit/storage six months from now, you don’t dig through 50 files. You go to /packages/storage/, find src/index.js, read the README, look at one test file. Done.
The side effect: code is less coupled, more testable, easier to extend. But the primary benefit is cross-session clarity. The structure itself is a map.
The Documentation: Specs, READMEs, and Working Examples
ExtKit has three layers of documentation:
Layer 1 — Phase Specs. phases/phase1-spec.md defines what phase 1 does, how to test it, and what it produces. A future session reads this to understand the contract, not the implementation.
Layer 2 — READMEs. Package-level API documentation. Not comprehensive tutorials — just tables of what each function does, what it returns, and a copy-paste example.
Layer 3 — Working Code. A demo extension using the APIs. Not a toy — a real extension that could ship. This is the proof that the API makes sense and the reference for how it’s actually used.
The three layers serve different readers:
- A session that knows the architecture reads the spec.
- A session that knows what they want to build reads the README.
- A session that’s unsure reads the demo.
All three should be skimmable in under 5 minutes. If documentation takes more than that to retrieve the information you need, it’s not built for reuse.
The Example: From Monolithic to Composable
The YouTube transcript extension was a single content.js — 800 lines, all the logic in one file. It worked. But it wasn’t retrievable.
The step was: identify the patterns (inject UI, find elements, wait for them, scrape DOM, download files). Extract each into a composable. Bundle them as @extkit/content.
Now a future session doesn’t read 800 lines. They import four functions and compose them. The demo extension shows how. The README shows the signatures. Done in one session.
This is the discipline: a reusable component should take less time to use than it took to understand the original monolith.
The Handoff: What Future You Actually Needs
When you’re building for reuse, you’re not building for users. You’re building for the version of yourself (or a colleague) that has context loss.
That version needs:
- A mental map (the structure) — not scattered across 20 files, not tangled dependencies
- An entry point (the spec or README) — they should know what to read first, not have to guess
- A proof (a working example) — not just function signatures but actual usage
- A contract (the tests) — what’s guaranteed to work when you extend
If you’re building without these, you’re building for the happy path only — today’s session, full context, fresh memory. You’re not building for reuse.
The Cost vs. Benefit
This discipline costs time upfront. Speccing 10 phases costs more than jumping into phase 1. Extracting primitives costs more than shipping monolithic code. Writing a demo extension costs more than shipping without one.
The payoff: a codebase that compounds in value, not cost. Each new session that builds on ExtKit pays that cost back. Phase 2 implementation is faster because phase 1 is specified. A new extension is faster because the demo shows the pattern. A bug fix is faster because one file has one responsibility.
For one-off projects, this is waste. For anything you’ll touch more than once, it’s compounding savings.
How This Applies to Any Project
You don’t need a monorepo to do this. You need:
- Specs before code — write what you’re going to build before you build it
- Modular structure — each file has one reason to change
- Clear entry points — a README per module, a demo showing real usage
- Self-contained sessions — each phase or feature is small enough to implement in one sitting
- Contracts — tests that prove behavior, not just coverage
These are principles. The implementation (monorepo, packages, phase specs) is how ExtKit applies them. Your project might use a different structure and still follow the discipline.
The key is: future you has lost context. Build as if you’re handing code to a stranger, because you are — your future self is a stranger to today’s context.
This essay is a companion to “Inside Claude’s Cognition” but stands on its own — it’s as much for humans building reusable code as for AI sessions. The ExtKit example is just one way to apply the discipline.