The Documentation-Driven Developer: Why Updating Port Numbers Means Updating the README

A Single Message in a Complex Distributed Systems Build

In the midst of building a horizontally scalable S3 architecture with a three-layer hierarchy of stateless proxies, Kuri storage nodes, and a shared YugabyteDB database, one message stands out for what it reveals about the assistant's development philosophy. The message is deceptively simple:

Message 391 (assistant): `` ## Agent Reasoning Now I should also update the README.md to reflect the new port numbers. [read] /home/theuser/gw/test-cluster/README.md <file> 00001| # Test Cluster Setup (Scalable S3 Architecture) 00002| 00003| This directory contains configuration to run a test cluster with the **scalable S3 architecture**: 00004| - **S3 Frontend Proxy** (stateless) - Routes S3 requests to storage nodes 00005| - **2 Kuri Storage Nodes** (kuri-1, kuri-2) - Independent storage backends 00006| - **1 YugabyteDB** - Shared database for coordination and object placement tracking 00007| 00008| ## Architecture 00009| 00010| ` 00011| ... ``

At first glance, this appears to be a trivial action: the assistant reads a README file to prepare for updating port numbers. But in the context of the broader coding session — a sprawling, multi-hour effort to build, debug, and deploy a distributed storage cluster — this message captures a critical moment of discipline. It is the moment when the assistant, having already made two configuration changes, catches itself and realizes that documentation must follow code.

The Context: A Cascade of Port Changes

To understand why this message was written, we must trace the chain of events that led to it. The session had been building toward a working test cluster for the Filecoin Gateway's horizontally scalable S3 architecture. The architecture, as specified in the roadmap, required three layers: stateless S3 frontend proxies (port 8078), independent Kuri storage nodes, and a shared YugabyteDB database. The assistant had already corrected a fundamental architectural flaw — it had initially been running Kuri nodes as direct S3 endpoints, violating the requirement for separate stateless proxy nodes — and had restructured the entire Docker Compose configuration.

In message 386, the user issued a simple but consequential request: "Test ports - for kuri instead 8443/.. use 7001/7002." This was not a cosmetic change. The Kuri nodes expose LocalWeb endpoints for CAR file access and internal debugging. The original ports 8443 and 8444 had been chosen arbitrarily during earlier development. The user wanted them changed to 7001 and 7002, likely for consistency with other services or to avoid port conflicts in their environment.

The assistant responded methodically. In message 388, it updated docker-compose.yml, changing the port mappings for kuri-1 and kuri-2 from 8443 and 8444 to 7001 and 7002 respectively. In messages 389 and 390, it updated gen-config.sh, the shell script that generates per-node configuration files, to emit the new port numbers in the Kuri configuration. These were the essential changes — the ones that would actually affect how the cluster ran.

But then came message 391. The assistant paused and thought: "Now I should also update the README.md to reflect the new port numbers." It then read the file to see what needed changing.

Why This Matters: The Discipline of Documentation

This message is remarkable precisely because it was not required. The README is documentation, not code. The cluster would work perfectly well with the old port numbers in the README — Docker Compose and the configuration scripts would use the correct ports regardless of what the documentation said. The user had asked for port changes, and those changes had been made in the operational files.

Yet the assistant chose to update the documentation anyway. This reveals a deeply held assumption: that documentation is not a separate artifact but an integral part of the codebase, with the same claim to correctness as the code itself. The assistant's reasoning — "Now I should also update the README.md" — treats the README as a deliverable that must be kept in sync with the implementation.

This assumption is not universal. Many developers treat documentation as a best-effort artifact, updated when time permits or when someone files a bug. The assistant's approach is more rigorous: documentation is part of the "truth" of the system, and any change to the system's behavior should be reflected in its documentation. This is the hallmark of what might be called "documentation-driven development" — not documentation before code, but documentation as code, subject to the same standards of accuracy and maintenance.

The Thinking Process Visible in the Message

The message contains only one line of reasoning before the file read: "Now I should also update the README.md to reflect the new port numbers." This single sentence is rich with implied thought.

First, it acknowledges that the port change is a user-facing change. The README is the primary entry point for anyone setting up the test cluster. If a developer follows the README and encounters port 8443 in the documentation but the cluster is actually listening on 7001, they will experience confusion and friction. The assistant is thinking about the next developer — the human who will read this documentation without the context of the conversation.

Second, the sentence uses the word "also," which is telling. It means the assistant is tracking a mental checklist: "I've updated docker-compose.yml. I've updated gen-config.sh. Now I should also update the README." This reveals a systematic approach to change management. The assistant is not just making changes ad hoc; it is categorizing the affected files and ensuring complete coverage.

Third, the assistant reads the file before making changes. This is a deliberate choice. Rather than assuming what the README contains, the assistant fetches the current content to understand the exact text that needs updating. This avoids the common mistake of rewriting documentation based on memory or assumption, which can introduce new errors.

Assumptions Made by the Assistant

The assistant makes several assumptions in this message, most of them reasonable but worth examining:

  1. The README is the authoritative documentation. The assistant assumes that the README is the primary source of truth for users setting up the cluster, and that it should be kept accurate. This is a sound assumption for most projects, but it does imply that there are no other documentation files that also reference the old port numbers (e.g., a wiki, a man page, or inline comments in other scripts).
  2. Port numbers in documentation are a correctness issue. The assistant treats a documentation discrepancy as a bug to be fixed, not a minor inconvenience. This reflects a high standard of quality but also assumes that users rely on the README for precise operational details.
  3. The user wants documentation updated. The user's request was specifically about ports. The assistant infers that this implies updating all references to those ports, including in documentation. This is a reasonable inference but not explicitly stated.
  4. The README needs only port number updates. The assistant reads the file but does not yet know what other changes might be needed. It assumes that a simple find-and-replace of port numbers will suffice, without needing to restructure the documentation or update architecture diagrams.

Input Knowledge Required to Understand This Message

To fully grasp what is happening in message 391, a reader needs:

Output Knowledge Created by This Message

This message does not create output knowledge in the traditional sense — it does not modify any files or produce a new artifact. Instead, it creates process knowledge: the assistant has now identified the README as a file that needs modification and has read its contents to prepare for that modification. The actual output — the updated README — will come in subsequent messages.

However, the message does create knowledge about the assistant's methodology. By reading the README before making changes, the assistant demonstrates a careful, evidence-based approach. It also signals to anyone observing the session (including the user) that documentation is being treated seriously. This builds trust: the user can see that the assistant is not just making code changes but is also maintaining the supporting materials.

Mistakes and Potential Pitfalls

The assistant's approach in this message is sound, but it is worth considering what could go wrong.

One potential issue is that the README might contain port references in multiple formats — not just in a port table but also in example commands, architecture diagrams, or explanatory text. A simple find-and-replace might miss some references or, worse, accidentally change a port number that should remain unchanged (e.g., port 8078 for the S3 API). The assistant will need to be careful when making the actual edit.

Another consideration is that the README might have been updated by someone else between the last read and this read. The assistant reads the file fresh, which mitigates this risk, but there is always a possibility of concurrent modifications in a collaborative environment.

Finally, the assistant assumes that updating the README is the final step. In reality, there might be other files that reference the old ports — test scripts, example configurations, or inline comments in Go source files. The assistant's systematic approach suggests it will catch these in subsequent passes, but the message itself does not enumerate all affected files.

The Broader Significance

Message 391 is a small moment in a large coding session, but it encapsulates a philosophy of software development that is worth articulating. The assistant treats documentation as a first-class citizen of the codebase, subject to the same rigor as source code. This is not always the norm in software development, where documentation is often treated as a secondary concern, updated sporadically or not at all.

The message also reveals the assistant's working style: systematic, thorough, and self-aware. The "Now I should also..." phrasing suggests an internal checklist that the assistant is consciously tracking. This is a pattern that appears throughout the session — the assistant frequently pauses to consider what else needs updating, what edge cases might exist, and what the user might need next.

For the reader — whether a developer studying the assistant's methodology or a user relying on the resulting documentation — this message is a small but telling indicator of quality. It says: this assistant does not stop when the code works. It continues until the entire system, including its documentation, is coherent and correct.