But you’re still the one holding it all together.
“Read the specs first.”
“Update status when we’re done.”
“Check the pipeline.”
“Commit the changes.”

Every time you add something new to the system (a new file, a new convention, a new check), that’s one more thing to remember to tell the LLM at the beginning of a session.1

The files hold the knowledge. But they don’t carry the session forward on their own.

That’s what skills are for.

Shortcuts

One thing that made a real difference early on, before models that code, was codifying instructions I found myself repeating. goodalexander called these “prompt macros.”2

One of the first ones I used: OPTIMIZE.

The problem it solves: you braindump a flurry of thoughts into a chat, knowing well the model would give you a much better response if your request were cleaner, more structured. But you don’t want to rewrite it. So instead, you prepend your prompt with “OPTIMIZE,” and the model restructures your prompt into something precise, then answers that.

But how does it know what OPTIMIZE means? You define it.

Here’s the definition, abridged from the one I actually use:

OPTIMIZE: Analyze the prompt that follows for ambiguities and missing context. Rewrite it as a detailed, actionable specification: add defaults, specify output format, include operational requirements. Then execute the refined version.

You save this somewhere the model can access it. Claude has personal preferences and project instructions; ChatGPT has custom instructions. Or just tell it in a chat: “remember this definition for OPTIMIZE.” Most LLMs now have memory that persists across conversations, even if it’s not always the most reliable.

If you have never tried a version of this, throw something messy at a chatbot and type OPTIMIZE before it.

Or try VARIANTS, to get structurally distinct alternatives instead of slight variations. And PUSHBACK, to force the model to disagree with you (an anti-sycophancy protocol). Ask your favourite model to help you define these macros, and to commit them to memory. Then use them.

I built a much larger set over time.3 And once you get the idea, you may have Claude itself suggest and create macros for how you work.

From macros to skills

Anthropic’s Thariq Shihipar put it neatly: “Using Skills well is a skill issue.” His concern is the craft of it — how to write ones that actually work.4

But the craft isn’t the bottleneck. There’s myriad freely available skills you can adopt and add to your system wholesale. The real skill issue is recognizing the repeated moves in your own workflow that deserve codification.

I find it useful to think of skills as shortcuts that Claude Code (or Codex) knows to read.

Claude Code has a dedicated place for them: a .claude/skills/ directory. Each skill is a markdown file. Not a plugin. Not a script. Just structured instructions in plain language that Claude follows when you type a slash command — /log, /end, /brainstorm.

.claude/
    skills/
        brainstorm/
            SKILL.md
        start/
            SKILL.md
        end/
            SKILL.md

The idea is the same as macros. PUSHBACK the macro became /pushback the skill. VARIANTS became /variants.

The instructions look similar. The reach is different. A skill can read your project files, check past decisions, produce structured output, update your specs. A macro can’t do any of that — it only shapes how the model responds within a single conversation.

If you wrote a macro, you can write a skill. Same thinking, different reach.

The first routine worth encoding

The first thing I wanted off my plate was session continuity.

That only works if someone reliably reads the right files at the start and updates them at the end. /start and /end turn that from a repeated instruction into a routine.

/start reads your spec files, detects what you’re here to do from your opening message, and surfaces relevant context.

/end updates status.md and pipeline.md so the next session doesn’t begin cold.

Now you know what’s inside: a markdown file in .claude/skills/ that Claude reads when you type the name. The routine you used to perform manually, encoded once, done.

That alone is useful. But /start and /end are automation — they handle what you’d do anyway, just reliably.

Some skills change the work itself.

Before the first line of code

Two Files described how I begin projects by asking Claude to grill me on what I intend to build, saving the results of that discussion as design.md.

Over time this grew into a structured interview template.5 Here’s what it looks like:

1. The Idea — What are you building? What triggered this? Walk me through using it step by step.

2. Context Check — Does this overlap with something you already have? Who uses it? Where does it fit?

3. Scope Boundaries — What’s the minimum version that’s useful? What are you explicitly not building? /pushback on “it should also...”

4. Technical Constraints — What does it integrate with? Any hard limitations?

5. Success Criteria — How will you know it’s done enough to use?

6. Synthesis — Reflect back, surface tensions, propose boundaries, draft the spec files.

You can use this today. Paste it into any LLM and run the interview yourself. You’ll get a better design.md than if you’d just said “help me plan my project.”

I folded this template into a skill called /brainstorm.6 Now I type one word and Claude runs the full interview — checks my existing projects for overlaps, grills me on scope, pushes back when I’m cramming two features into one, and produces a design.md at the end.

Same template. One word.

And it works for more than kickoffs. Mid-project, when I’m thinking about a new feature, /brainstorm runs the same interview adapted to what already exists. It reads the codebase, assesses impact, tells me if the feature is more invasive than I think.

The wider pattern

/brainstorm is one skill that shapes the work. There are others.

/architect turns a brief into a design document with architecture decisions and tradeoffs.
/review audits code for quality and security before I ship.
/variants generates structurally distinct alternatives when I’m stuck between approaches.
/pushback forces Claude to find flaws in a plan before I commit to it.

The one I find myself reaching for most lately is /study — a structured way to absorb what everyone else is building and fold the patterns into my own system. That one deserves its own post.

Encode the move once. Stop restating it every session.

design.md — what you’re building.
status.md — where you are right now.

You tell Claude to read them at the start of each session. It picks up where you left off. It works.

Until it doesn’t.

A couple of days into building fin, status.md had become a dumping ground. Feature ideas. Bugs I’d noticed. Half-formed thoughts about how subscriptions should work. Things I was dreaming up mixed in with things that actually existed.

Status was supposed to be what is. Now half of it was “what is” and half “what if.” And the more threads I opened in a single session, the messier Claude’s responses got. Not necessarily wrong. Just less focused. Less useful.

Here’s what I noticed: better organize what the model reads, and what it does becomes markedly more predictable. This idea is called separation of concerns.

Each file should answer exactly one question.

When a file starts answering two questions, split it.

pipeline.md — “What’s next?”

The first concern worth separating: your developmental queue.

Feature ideas. Deferred work. Bugs you noticed but don’t want to fix right now. Things that aren’t the current state of the project — they’re the future state. They don’t belong in status.

pipeline.md separates what’s next from what exists.

specs/
    design.md      ← what are we building?
    status.md      ← where are we right now?
    pipeline.md    ← what’s next?

It doesn’t need to be fancy. A list works:

• “Dashboard chart overhaul — start with multi-select.”

• “Subscription alerts — not enough pain yet, revisit later.”

Tell Claude to read it alongside your other spec files at the the start of a session, and to “add this to the pipeline” or “queue this up” mid-session. It knows your priorities without your explaining them. It’ll slot it in and prioritize the list for you.1

Status then goes back to doing one thing: the current state — what exists right now and what happened in your most recent sessions.

decisions.md — “Why this and not that?”

Some decisions are obvious from the code. You used Flask, not FastAPI. Anyone can see that.

But some decisions are invisible. The reasoning lived in a conversation, and when that conversation is gone, so is the reasoning.

I wanted my subscriptions in fin — Netflix, Spotify, ChatGPT — linked to actual bank transactions. Not static rows. Live data: when did I last pay, how much.

Claude and I worked through several matching approaches. We picked one. It worked.

A few days later, new session. Claude suggests a completely different approach — one we’d already considered and rejected.

decisions.md is where that reasoning lives. A running log of choices that were contentious or consequential — the ones where you weighed alternatives and chose for reasons that aren’t obvious from the code.

Not every choice. Just the ones where forgetting would cause confusion. The test: would Claude relitigate this if it didn’t know?

Over time, decisions.md becomes a developmental journal. You can trace the evolution of your project through the choices you made and why.

Status tracks session-by-session progress. Decisions tracks how the shape emerged. Design still holds the original vision — and the gap between design and reality is also telling.

If you’re building with someone else, decisions is even more valuable; a new collaborator can read the rationale without asking you to re-explain every choice.2

The format is simple — you can use mine or ask Claude to suggest a structure that works for you:

• Context — why this decision came up

• Options — what you considered

• Decision — what you chose

• Why it matters — what a future session needs to know

specs/
    design.md      ← what are we building?
    status.md      ← where are we right now?
    pipeline.md    ← what’s next?
    decisions.md   ← why this and not that?

Four files. Each answering one question.

CLAUDE.md — “How does this all work?”

You now have four spec files. But Claude doesn’t automatically know they exist. Every session, you’d need to say: “Read the specs folder. There’s a pipeline file now. And a decisions file.”

CLAUDE.md is a markdown file at your project root that Claude Code reads automatically at the start of every session.3 You don’t ask. It just does. Anthropic calls it a project constitution — a persistent set of instructions the model loads before you say a word.4

It’s where you describe your project’s layout: what lives where. The spec files you just created? CLAUDE.md is how Claude knows they exist.

It tells Claude:

• What this project is (one line)

• Where to find context (your specs folder)

• How to run the project (commands it can’t guess)

• What to avoid (constraints that would waste time)

Tell Claude to write it once. You revise it when the project’s structure changes.5

my-project/
    CLAUDE.md          ← how does this all work?
    specs/
        design.md      ← what are we building?
        status.md      ← where are we right now?
        pipeline.md    ← what’s next?
        decisions.md   ← why this and not that?

Five files. Five questions. One system.

Encoding the ritual(s)

If you’re using these files, pretty soon you’ll find yourself tired of telling Claude to read design, status, pipeline, decisions before every session, and to update them at the end. This is where skills come in.

Claude Code lets you create reusable procedures you trigger with a slash command.6 I start every session by typing /sessionstart. I end with /sessionend. That’s it — my shorthand for Claude to read the specs, surface what’s relevant, and update everything when we’re done.

CLAUDE.md gives Claude the map. Skills give Claude the routine. I’ll go over skills in much more detail in subsequent posts.

A caveat

Naval Ravikant recently said something worth sitting with:7

“The only reason to use these workflows and tool sets, which are very ephemeral, and their longevity is measured in weeks, perhaps months at best, not in years, is if you’re at the bleeding edge and absolutely need every advantage.”

His strongest version: AI will adapt to you faster than you can adapt to it. The tools will absorb the best practices. Why build infrastructure that’ll be outmoded?

He’s not wrong about the tools. Claude Code will evolve. Skills might work differently next quarter, or next week. Some of this may become built-in.

But the act of structuring your process teaches you things about your own work that no tool can hand you. What belongs in status vs. pipeline? Which decisions are worth recording? Where does complexity actually live in your project? These aren’t questions a tool answers for you. They’re questions you answer by building the system — and the answers make you better at the work itself.

The files aren’t just for Claude. They’re for you.

What are we building?
Where are we right now?
What’s next?
Why this and not that?
How does this all work?

Five questions. Five files. Markdown. They’ll likely outlast whatever tool you’re using today.

Give it structure. The rest will follow.

Naval has a habit of naming what everyone’s already feeling. If you’re curious about building with AI — or you’ve already started and every session feels like starting from scratch — here’s how I’d do it if I were starting all over again.

Start with a real problem. Not a tutorial. Not a to-do app from a YouTube video. Something you actually need — a tracker, a dashboard, a tool for your business. The motivation matters. It’s what keeps you going when the AI gives you garbage on the third try. I built fin because I had zero handle on where my money was going each month. I built Scholia because I didn’t want to pay Remnote for AI credits when I could pay the frontier labs directly, ha!

Getting set up

You need two things: Claude Code and a terminal.

I know. The terminal. A Command Line Interface (CLI). That black window with text that looks like it’s from 1993. But here’s the thing — once you go terminal, you don’t go back. It’s where the real power is, and it’s how I build everything you’ll see on this Substack.

If a terminal truly isn’t for you, use Claude Desktop (Cowork) instead — same AI, visual interface, works fine. I hear Codex isn't terrible either.

But try the terminal first. On Windows, it’s called PowerShell. On Mac, it’s Terminal. If you’ve never installed a CLI tool before, ask any LLM you already use to walk you through it.1

Once Claude Code is installed:

Make yourself a home base. Open File Explorer (Windows) or Finder (Mac), and create a folder where all your projects will live. I call mine dev. Everything I build goes here — one subfolder per project.

Inside dev, create a folder for your first project. Give it a name. I have one for each thing I build:

dev/
    fin/
    scholia/
    moom/

Each project gets its own folder. Don’t dump everything into one place. When you start something new, make a new folder.

Now open your terminal, navigate to your project folder, and start Claude.2

cd dev/fin
claude

That’s it. You’re in.

You’re now armed with the two things you need to vibe code: an idea and a coding agent.

Everything you build, every file you create, lives in the directory you just created.

The first thing to do

Before Claude writes a line of code for you, ask it to help you think through what you’re building.

Not vaguely. Have it grill you. What’s the problem? Who’s it for? What’s the scope? What are you not building? Let it push back. Let it ask the questions you haven’t thought of yet.3

Then ask it to save that conversation as design.md in a folder called specs/.

my-project/
    specs/
        design.md

You now have a design document. You didn’t write it. Claude did, from your answers.

Here’s what mine looks like for fin:

That’s the whole purpose, scope, and architecture — written by Claude after a 10-minute conversation where it asked me what I needed and I answered honestly.

The second file

After your first real working session — an hour, two hours, whenever you want to stop — ask Claude to write a status update. What happened. What’s working. What’s broken. What you should pick up next time.

Ask it to save it as status.md.

my-project/
    specs/
        design.md
        status.md

Here’s a real one from fin:

Next time you open Claude on this project, tell it to read specs/. It knows what you’re building. It knows where you left off. Zero re-explanation.

A third file?

I didn’t start with three files. I started with two.

pipeline.md — a backlog of what’s next — showed up later, when my projects got big enough that I couldn’t keep track of what to build next in my head.

If you’re building something small, two files is enough. The system grows with you.4 Don’t over-engineer it on day one.

Why markdown

Why not Notion? Why not a database? Why not some fancy tool?

Markdown because:

• The AI reads it natively. No parsing, no API, no export step. It’s just text.

• You can read it in any editor. VS Code, Obsidian, Notepad, your phone. No account required.

• It lives in your project directory. Right next to your code. Versioned with git if you’re using it.

• No dependencies. No accounts, no subscriptions, no setup. Create a file, start typing.

A note on context windows

The amount of information an LLM can hold in a single conversation

Context windows started at around 4,000 tokens (roughly 3,000 words). They’re now at 1 million tokens on the highest tiers. That’s an entire codebase (or the Lord of the Rings trilogy) in memory.

Bigger context windows are genuinely useful. They can hold more. But what to hold — that’s still on you. A million tokens of raw conversation is noise. The model can hold a ton of information, but it can’t tell what matters unless you’ve told it.

That’s what the spec files do. They’re not a workaround for small context windows. They’re the signal inside the noise. The problem was never memory capacity. It’s memory structure.

Closing thoughts

After a week of updating status.md, you have a development journal you didn’t intend to write.

After a month, you have a searchable history of every decision, every blocker, every pivot — across every project.

You didn’t plan this. It just happens when you give your process a place to accumulate.

You’ll also notice you’re repeating yourself: “Claude, read the specs” at the start, “Claude, update status” at the end. There’s a way to automate that. Next post.

This works with Claude Code, Cowork, Cursor, Codex — anywhere you can point an LLM at files in a folder. The tool doesn’t matter. The structure does.

Happy building!

Now I’m building. Full-stack tools, AI-assisted, shipped and used. A personal finance tracker. An ERP system for my wife’s health supplements company. A research knowledge platform. All built with AI coding agents, in a language I don’t formally “know.”

The building became its own research. How do you develop a mental model of an AI system’s capabilities? How do you systematize what you learn across projects? What compounds and what doesn’t?

This Substack is where I work through that — the tools, the process, the practice of getting better at building with AI. Not tips. Not tutorials. The actual trajectory, documented as it happens.

First series: how I went from re-explaining everything every session to a system that learns from my own work.