Bo Boghosian

How I think and understand code in spite of Claude

Wed, 02 Sep 2026 04:00:00 GMT

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.

Mac Mini acquired

Wed, 29 Apr 2026 04:00:00 GMT

I found one. I’ve been refreshing the Apple Store website in vain to find a Mac Mini. Best Buy was totally sold out too. I finally tracked one down at MicroCenter this morning. I got the M4 Pro with 24GB memory.

It should be good enough to manage the house but I’m not expecting it to write code for me.

I also picked up a Raspberry Pi to use as a remote voice control for my claw. I have a very practical first project in mind.

So here begins my claw life. Wish me luck.

Code readability - is it useful?

Mon, 13 Mar 2023 04:00:00 GMT

For a time at Google, I was a “readability reviewer” for Java code. - that is, one of a group of java experts that had a high standard for code quality. This group had the ability to bestow “readability” powers upon other developers.

Readability (i’ll use capital-R) was important because all code that was to be submitted needed to be approved by somebody with Readability for that given language. If you had Readability approval yourself. Otherwise you’d need to find someone who had Readability to approve your code. This was in addition to the traditional Owners approval.

Although two approvals were required, it didn’t turn out to be much of a burden - typically you’d get readability within a few months of joining (or maybe a year for new-grads), and it was more than likely that most people in the Owners file had readability for the language.

I mention Readability just to show how much importance Google placed on readability. On the other end of the code quality spectrum there are people who put minimal effort into documentation, saying that “code is self-documenting” and the docs will get stale anyway and then be a drag. When you do code reviews for this group, it can take a while to figure out what’s going on, and often there’s more feedback than there would be on code from a Readability devotee.

What is readable code, anyway?

At Google and Niantic I was firmly in the pro-readability camp, although I never cared for the extra bureaucracy of an official Readability program. The Readability program, while well intentioned, was a bureaucratic obstacle with a spotty track record. One person told me that since so much bad code was in the Google codebase, there was an “existence proof” that the Readability program did not work. What was important was a team culture of readability coming from the leaders of the team.

Before I get too far, let me define readability. In my opinion, the readability of code is ultimately how long it takes for somebody to understand how the codebase works and to be confident making changes.

Note that I didn’t mention documentation. While documentation is important, I don’t believe that more is always better. It’s a means to an end rather than the end itself.

My definition of readability is intentionally practical. When you start on a new project, your first task is going to be learning the codebase and fixing a bug. How long does that take? A week? A month? Or maybe you never entirely understand it, you just make a change in the right area and see if it did what you expected.

The missing metrics of readability

When measured this way, readability (lowercase-r) has a huge effect on a team’s productivity. But how do you know how readable your code is? What metrics are there?

The disappointing answer is, there are almost no metrics measuring readability. It’s an art more than a science. You have to put yourself into the mind of a new engineer and try to imagine where they’d get tripped up and what would help. If the leader of another team had ever challenged me to prove that our codebase was more readable than theirs, there’s no way I would have been able to!

It’s not hard to imagine then why readability could be cast aside in a highly data-driven tech world. One could try and create proxy metrics like “lines of documentation” or “interface to class ratio” but those will then become the goal, and the team will optimize for those rather than readability itself.

How to get readable code then?

It’s important that the engineering manager instills a culture of code quality and readability. Given that there will be varying opinions on your team about how much code quality matters, it’s important that the manager communicates and enforce standards. If the manager neglects this job and it’s left to the team to decide, this will create enmity as the individual contributors (ICs) duke it out amongst themselves about how important is code quality is, what is the purpose of documentation, etc etc. These arguments have a tendency to reach “holy war” status quickly. Things are much easier on the ICs when the manager sets the guidelines for code quality. The ICs may grumble about the manager between themselves, but that’s better than the alternative.

Code quality at a two-person company

The irony of everything I’ve written so far is that in my current role as as co-founder of Bodeville, I’m writing the least readable code of my career. I always complain to my partner than I’m having to refactor the code because it’s a mess and it won’t support the next thing I want to do.

Still, I believe I’m writing at the correct quality for the situation. Why?

First, I’m the only person who is likely to ever read this code. Compare that with Google, where you might have 10, 50, or even hundreds of people read your code. The cost of low quality code increases with the number of people reading it. It takes more time to write quality code; if more people are reading it, the higher cost of writing high quality code can be worth it.

Second, the game we are making is a ship-and-release product, not a service. That means the lifespan of the codebase will be considerably shorter than say, Pokémon GO, where the code I wrote as early as 2014 is still being seen every day by developers.

In the game we’re developing, Chief Emoji Officer, I’ve had to do a more than a few refactors, code-cleanups, because of the low quality code. I’d be totally embarrassed if the code leaked out. The Google Readability team would think they’d made a huge mistake in letting me join the team. But the cost-benefit of a one-person engineering team actually skews towards less readable code because it lets you develop faster. As the number of people working with your code increases, so does the importance of readability.

Your code could be new again!

A few times in my career, I’ve had to work with code I wrote years before. It had been long enough where I’d completely forgotten the codebase and it was like learning it new. When I wrote the code I never imagined it’d be my future self getting up to speed. But when I found myself in that situation, and came across beautifully readable code, it was the ultimate validation of the investment I had made.

But ultimately, your code standards should depend on the product. For a longer lasting product with a large team, the code should be highly readable, well tested, and well documented. On a project with just one developer, you may be wasting time making your code perfectly readable.

Announcing Bodeville!

Tue, 01 Nov 2022 04:00:00 GMT

I’m happy to announce that Alexia Mandeville and I have formed a new game company named Bodeville!

Bodeville is the realization of our dream of making games with complete creative freedom. I firmly believe that the only way to get this freedom is by not taking anyone else’s money. Too many times in the game industry, people have been promised creative control only to have it taken away when the executives or investors decide otherwise. By self-funding, we are beholden to nobody but ourselves (for better or worse!)

Without a big pile of cash, we are starting small. The two of us will try to make an entire game and manage the business at the same time. We’ll cut as many corners as we can without sacrificing the vision and the experience. The games will be smaller in scope than those from a 10 or 100 person studio, but we hope the story and soul will still shine through.

We will post development updates on Bodeville’s website and twitter page. My personal takes on games and business will be here. I look forward to sharing the experience with you!

On quitting

Tue, 18 Oct 2022 04:00:00 GMT

I hear a lot of conversation about quitting these days. “Quiet quitting” is all the rage. A former poker player has written a new book on quitting. And it’s something that’s been on my mind since I quit my job nearly six months ago.

I’ll focus on why I quit rather than cover the multitude of reasons that others quit. And the reason is quite simple - because I wasn’t happy!

On the surface it seems like an idealistic, irrational decision - quitting because of one’s feelings. The money was good, and in theory working in game development was fun. Our depression-era ancestors surely would disapprove of leaving a good-paying job.

But how do you measure mental exhaustion, burnout? And how to value the ability to be present and energized for my family and friends after the day is done?

This is where I think the line between rational and irrational behavior in our society is misplaced. It seems that anything subjective or immeasurable is by definition irrational. It reminds me of economic theory, in which we are taught all about “rational consumers” who are always perfectly maximizing their utility. These models can’t possibly place a value on the range of human emotions.

So yeah, I quit because I was unhappy. It’s kind of like relationships! Of course, you want to try your best to make it work out, and give it a fair shot. But once you realize that things won’t turn around, it may be time to go.