With Claude as my assistant, it’s very easy for me to not think. I never have to think about code. I don’t ever look at APIs. And there’s no chance I’m reviewing each of the thousands of lines of code that Fable emits each day. Being a dedicated code reviewer is just so… boring.

I’ve turned into the PM who constantly asks for one-off fixes but barely understands the system. And I don’t like this!

I’m experimenting with two fixes for this.

1. A living requirements doc.

This is an excerpt of my CLAUDE.md

`REQUIREMENTS.md` (repo root) is the authoritative record of project
guidelines, design intent, and requirements and should never be
written to by Claude.

This solves two issues. First, it makes me think about design. Because I don’t let Claude edit this file, I have to proactively think. This requires a deeper level of thinking versus choosing from Claude’s multiple choice lists in plan mode. I feel like I’m actually guiding the product.

Occasionally I’ll give Claude a prompt like this:

Check the codebase to see if it adheres to REQUIREMENTS.md. Also tell
me if REQUIREMENTS.md is under-specified in any area.

Claude will happily do this. It’s also crucial that I tell Claude not to suggest updates to REQUIREMENTS.md; otherwise I’d find myself blindly copy/pasting.

2. A good way to view the resulting architecture.

Understanding what Claude has actually built is the second big knowledge gap I’ve come across.

My first attempt was to have Claude write ARCHITECTURE.md files in each directory. Here’s my initial instruction in CLAUDE.md:

Key architecture decisions should be BRIEFLY documented in an
`ARCHITECTURE.md` file in the relevant directory. Generally, these
decisions should be limited to a single paragraph each.  When a change
makes or changes an important design decision, update it. Outdated
entries should be updated or deleted.

Fable obliges, but I end up with hundreds of lines of markdown across many files, a lot of which are arcane implementation details, trade-offs, and the like. And TBH I don’t like markdown for exploring system designs.

Instead, I’m now having fable generate documentation sites. Here’s my prompt:

I want some way to see the high level architecture of this
system. Particularly i'm concerned with APIs and invariants and
stuff. It should be done at multiple levels too - i want the overall
architecture, but then I can also look specifically at the gateway
architecture and APIS, or look at the raspberry pi or macos client
architecture too. Markdown readmes aren't really sufficient. I would
prefer something like a browser I can click through. Can you give me
ideas

And the generated site — it’s really good! It has navigation, clickable links, proper diagrams instead of ASCII art, and more flexibility with layout. As a result I actually like reading it.

While these workflows certainly slow me down, I think it’s the right price to pay going forward. Ultimately I’m still the one responsible for the code so I need to understand what exactly is happening. Not necessarily in line-by-line detail, but at a high level.