Resonant Coding: Practical Guide

Everything above sounds good in theory, but theory has that annoying particularity of dissolving when it touches reality. So here’s how this materializes in day-to-day work, with the caveat that any system that claims to be definitive is doomed to fail, and this one is no exception1.

This document is an expansion of the three-step method—research, planning, implementation—described in Resonant Coding, with the additional structures we discovered we needed as we applied it to real projects.

Folder Structure

The first decision was structural: if context is a bucket that gets dirty, then you need separate buckets for each type of water. In practice this translates to folders with specific functions2:

  • research/ for research documents, named with dates to track the evolution of understanding
  • plans/ for implementation plans, also dated, also versioned
  • specs/ for formal specifications in Gherkin format3, which function as living documentation and executable tests at the same time
  • handoffs/ for handoff documents between sessions, because the model doesn’t remember anything and someone has to remember for it

Procedure

The second decision was procedural: before writing code, write a plan. Always. Without exception. The plan divides work into phases that can be completed in a reasonable amount of time, with explicit success criteria—automated when possible, manual when there’s no other option. Each phase is a clean bucket: the model receives only the plan for that phase and relevant information, nothing more. For tasks with architectural risk, we sometimes use tracer bullets4.

Memory

The third decision was about memory. Models don’t remember, but files do. At the end of each work session—or when you need to pass context to another person, or another model, or your future self—a handoff document is generated that captures the current state: what was done, what was learned, what’s pending, what files are relevant. It’s externalized prosthetic memory, and it works better than it has any right to5.

Design Decisions

For design decisions that aren’t obvious—when there are multiple possible paths and choosing one means discarding others—we maintain a debates/ folder where the options considered are documented, the pros and cons of each, and the reason why what was chosen was chosen. This seems like bureaucracy until, six months later, someone asks “why did you do it this way?” and the answer is written instead of lost in the head of someone who no longer works here6.

Typical Flow

The typical flow ends up being something like this:

  1. A requirement arrives. Before touching code, a research document is created. The model reads the existing code, documentation, whatever exists, and generates a summary of the current state. That summary goes through the Rule of 5 until it’s reliable.

  2. With the research document as input—and only that document, in a new conversation, with a clean bucket—a plan is generated. The plan divides work into phases, each phase has success criteria, each task is small enough to fit in a single bucket. The plan also goes through the Rule of 5.

  3. Implementation happens phase by phase, each in its own conversation, each validated before moving to the next. If something doesn’t work, the plan is adjusted, not improvised.

  4. At the end of the session, the handoff is generated. Whoever picks up the work next—whether human or model—has all the context they need.

There’s a constant temptation to skip steps, to go straight to code because “this is simple” or “I already know how to do it.” Sometimes it works. More often than I’d like to admit, it doesn’t, and the time you saved skipping steps you lose multiplied fixing what went wrong. The method is slower at the beginning and faster at the end. The question is whether you have the patience to reach the end7.

Notes