The Architecture of Beginnings: Writing a README Before Writing Code

Introduction

In the sprawling, multi-month arc of the opencode session documented across segments 60–65, there is a message that, on its surface, appears almost trivial. At index 11853, the assistant writes:

[assistant] [write] /home/theuser/glm-kimi-sm120-rtx6000bw/kdtree-engine/README.md Wrote file successfully.

That is the entirety of the message. A single tool call result, two lines of output. No reasoning block, no elaborate explanation, no visible decision-making. Yet this message sits at a critical inflection point in the session: the moment when the assistant pivots from planning to implementation, from abstract architecture to concrete artifact. Understanding why this particular message matters requires reconstructing the full context of the decision it represents.

The Context: A Pivot to Native Implementation

The user's instruction in [msg 11846] was unambiguous: "Go with all phases, work non-interactively; Work in a new repo. Save plans in the repo in plans/ for later reference, then start implementation work." This directive came after an extended period of deploying, benchmarking, and diagnosing the DDTree speculative decoding system within SGLang. The assistant had spent chunks 0 and 1 of segment 65 building a native C/C++/CUDA DDTree inference engine from scratch, diagnosing throughput regressions, and extending service context length. Now the user wanted all of this work consolidated into a proper repository with plans, documentation, and systematic implementation.

The assistant's response to this instruction was methodical. First, it verified the local CUDA compilation toolchain ([msg 11847]), confirming that nvcc could compile sm_120 kernels on the local RTX 5070 Ti. Then it created the repository directory structure ([msg 11851]), establishing the skeleton: plans/, src/kernels/, src/engine/, src/common/, tests/, python/, scripts/, docs/, and third_party/. Then it wrote the detailed implementation plan into plans/0001-ccuda-ddtree-engine-plan.md ([msg 11852]). Only after these preparatory steps did it write the README.

Why Write a README Before Code?

The decision to write the README at this specific moment — after the plan but before any implementation files — reveals a particular philosophy about software project structure. The README serves as the project's front door, the document that orients anyone (including the assistant itself in future sessions) to the repository's purpose, structure, and conventions. By writing it before any .cu or .h files, the assistant is establishing the conceptual framework that will govern all subsequent implementation.

This ordering is not accidental. In the assistant's reasoning visible in [msg 11852], it states: "Now I'm moving on to save the plan, write documentation, and set up the build infrastructure to get everything ready for deployment." The sequence is deliberate: plan first (what we're building), then README (how the project is organized), then .gitignore (what to exclude), then build system, then implementation. Each step creates the conditions for the next.

The README likely contains:

• The project's name and purpose ("kdtree-engine" — a native C/C++/CUDA DDTree inference engine)
• The target model (Kimi K2.6 with MLA+MoE architecture)
• Build instructions and dependencies (CMake, CUDA 13, sm_120)
• The directory structure and what each directory contains
• The phases of implementation and what each delivers
• How to run tests and benchmarks

Assumptions Embedded in This Message

The act of writing a README makes several implicit assumptions. First, it assumes that the project will have longevity — that someone (the user, the assistant in future sessions, or other developers) will need to understand the repository's structure without having followed the conversation that created it. This is a bet on the project's value beyond the immediate session.

Second, it assumes that documentation should precede implementation rather than follow it. This is a specific development methodology choice: establish the contract and conventions first, then fill in the implementation. It prioritizes clarity and reproducibility over speed of execution.

Third, it assumes that the repository structure created in [msg 11851] is correct and stable. The directories src/kernels/, src/engine/, src/common/, tests/, python/, scripts/, docs/, and third_party/ represent a specific architectural vision — separating kernels from engine logic from common utilities, keeping Python tooling separate from C++ code, and reserving space for third-party dependencies. Writing the README before any code commits to this structure as the project's organizing principle.

Input Knowledge Required

To understand this message fully, one needs to know:

• The DDTree (Draft-Driven Tree) speculative decoding algorithm and why it requires custom CUDA kernels
• The Kimi K2.6 model architecture (MLA + MoE) and its inference characteristics
• The SGLang inference framework and its existing DDTree implementation
• The CUDA compilation environment (sm_120 targets Blackwell architecture GPUs like the RTX PRO 6000)
• The repository conventions established in the plan document
• The user's instruction to work non-interactively and save plans for reference Without this context, the message reads as a mundane file write. With it, it becomes a deliberate architectural decision.

Output Knowledge Created

The README creates a permanent record of the project's purpose and organization. It transforms the repository from a collection of directories into a documented project with a clear identity. For the assistant, it serves as a self-orienting document — in future sessions, reading the README will allow the assistant to quickly reconstruct the project's conventions without re-reading the entire conversation history. For the user, it provides a single entry point to understand what the repository contains and how to use it.

The Thinking Process

The assistant's reasoning in the messages surrounding this one reveals a careful, methodical approach. In [msg 11847], it considers scope: "I need to be realistic about scope—I can establish the foundation, build system, and test infrastructure, then implement the first self-contained kernel." In [msg 11850], it weighs dependency decisions: "Going with CPU torch via uv is the cleanest path forward... But even simpler: I'll write a pure-numpy reference generator." In [msg 11855], it designs the kernel architecture: "For the kernel design, I'm planning to have one thread per request manage the best-first heap expansion sequentially."

The README write sits at the boundary between these planning deliberations and the implementation that follows. It is the last planning artifact before the first implementation artifact. The assistant is, in effect, taking a breath — codifying the project's identity before diving into the CUDA kernels that will occupy the next dozen messages.

Conclusion

The message at index 11853 is a document of transition. It marks the moment when the kdtree-engine project shifted from being a plan in the assistant's reasoning to being a documented repository with a README, a .gitignore, and soon, CUDA kernels. The brevity of the message — a tool call result, nothing more — belies its significance. In the architecture of a software project, the README is the first thing anyone sees. Writing it before the code is a statement of intent: this project is meant to be understood, maintained, and built upon.