intertwingly

Part 3 of 3: Part 1: TurboCable | Part 2: Shared-Nothing Architecture

Reading Reddit and other places, I see lots of people have had problems with Claude, mostly rate limiting and hallucinations. This most definitely has NOT been my experience. I'm on the Claude Max 5x plan, I've used it hard for several months with no issues, particularly since Sonnet 4.5 was released. Many have identified strategies making use of various tools and agents. Other than creating a CLAUDE.md file and starting to experiment with skills, I have done none of this.

What I bring to the equation is domain area expertise and discipline. What Claude brings is a broader area of expertise and raw speed, both in analyzing and coding. As I mentioned, others employ various tools to make Claude take a more disciplined approach, Sequential Thinking seems highly recommended, but as I said, I have not had any need or experience with any of this.

The components of discipline are simple: plan, document, and test.

The result: I can produce code of higher quality and faster with Claude than I could build by myself. This approach enabled building TurboCable and the Showcase architecture—both documented in companion posts that serve as real-world examples of this methodology in action.

Plan

A small, well scoped request completely satisfies the requirements for a plan. Since all my code is under version control, I can just let Claude rip on such requests, and if I like the results I commit them, otherwise I discard them.

For larger or less well scoped items, I describe what I want done and ask Claude to build a plan. I then review the plan and request revisions. Once I am happy with the plan, I ask that it be committed. As an example, showcase/plans contain the plans I am considering for my Showcase application.

For even larger tasks, I build one to throw away, also known as prototyping. A prototype can generally be built in one session. Once complete, I can build a larger and more complete version over a series of sessions. Claude seems particularly adept at adding features to a larger implementation given a working proof of concept to evaluate. In rare cases, this process (build a prototype => build a larger implementation) may need to be repeated to build ever larger systems.

Document

An example from my CLAUDE.md for Showcase:

Heats are numbered - to determine who is on the floor for a given heat number, find all Heat records with that number, follow the entry relationship to extract lead and follow. Heats with number >= 1 are scheduled heats. Scratched heats (withdrawn/canceled) have number < 0 and are excluded from scheduling and scrutineering but can be restored or permanently deleted

This is a concise description of the data model that is not readily apparent from the schema alone. Before I added then, when I would mention "heat 1", Claude would assume heat with an id of 1, not a number of 1.

This is complemented by larger descriptions at different levels of abstraction: ARCHITECTURE.md covers implementation details, while blog posts document specific components like TurboCable and system-level design philosophy like Shared-Nothing Multi-Tenancy. The mere act of writing such information down has proven to be a great way to organize my thoughts.

Plans themselves are documents too, the key difference between the various types of documentation generally relates to time aspects: items committed within the repository itself tend to be results and are meant to be kept current, blog posts tend to capture my thinking and underlying rationale at a given point in time.

Building a growing base of documentation is an example of a better end result with Claude than I would have done on my own. The only discipline it takes is to assess every input I provide Claude as to whether it is likely a one time thing or is something I would likely need to repeat in the future.

Test

I am a big believer in the theory of Test Driven Development, but have rarely been disciplined enough to practice it myself.

More than that, Claude's raw speed has given me a completely new perspective on the value of tests. Previously I viewed tests as a necessary chore to prevent regressions. Increasingly I am now seeing tests both as a form of documentation and a way of ensuring that every change in behavior is intentional. What I mean by that is that breaking tests is now expected and routine and presents me with a choice to accept the new behavior (and therefore update the tests) or not (and therefore update the code).

Additionally, tests provide feedback to me as to whether I need to carefully review a change. If I request a change, and the files I expected to be updated are updated, the overall number of lines are about what I expected, and the tests all pass, a cursory examination suffices. I spend more time when one or more of these conditions are not met.

Results

The end result is that I can produce code of a higher quality and quicker with Claude than I could build by myself. In one case, I actually implemented a new feature during a dinner break at a dance competition event and shared it with the person running the event before the event completed. I later refined the implementation at home.

I can only assume that bringing this discipline to my usage is a large part of the reason I don't hit rate limits. Either that or avoiding the use of tools.

Meta: These Posts as Examples

These three posts (TurboCable - Real-Time Rails Without External Dependencies, Shared-Nothing Multi-Tenancy with SQLite, TurboCable, and Navigator, and this one) are themselves examples of the documentation discipline described above:

TurboCable documents a specific implementation—what it does, how it works, when to use it. This is analogous to inline documentation and READMEs: focused, practical, reference material.

Shared-Nothing Multi-Tenancy provides the larger architectural context—why these choices were made, how the pieces fit together, what constraints drive the design. This parallels ARCHITECTURE.md files that explain system-level thinking.

This post describes the process and methodology—how I work with Claude, what disciplines lead to better results, the meta-patterns that make all the other documentation effective.

Each post serves a different purpose, but together they create a cohesive narrative. The technical posts document what was built, while this post documents how and why to build documentation itself. This layered approach—implementation details, architectural rationale, and process methodology—is exactly what makes working with Claude effective. You provide context at multiple levels, and Claude can navigate between them as needed.

Writing this trilogy with Claude's help demonstrates the very discipline it describes: clear planning (the scope of each post), thorough documentation (three complementary perspectives), and iterative refinement (building each post to reference and reinforce the others).