The project, SP/M, is a hardware bring-up OS for ESP32 microcontrollers. It provides an interactive shell for GPIO/I2C/SPI/ADC experimentation, a script interpreter for automated diagnostics and prototyping, and a built-in ed editor. The goal is fast iteration during hardware development. Allowing developers to test their board, and their software without compile/flash cycles.
The reports were generated using my own micro-IDE which is specifically designed to support the lode coding method and other conversational AI assisted development.
In Report A the model had exposure to the entire project, including its lode.
In Report B the lode was removed, leaving only the code. I also had to remove the .git folder as on first run the model decided to extract the lode files from git history… surprisingly.
Each report was generated from a fresh empty session.
This comparison reveals something important about knowledge representation for code understanding, and Lode Coding in particular.
The lode-enabled model had structured knowledge built as a byproduct of lode coding the SP/M system. This knowledge shaped how the model understood the system and responded to the question “explain the OS aspects of this implementation”.
The lode provided additional project history and context that source code alone cannot. Specifically:
Conceptual framing: The CP/M heritage and design philosophy came through clearly in Report A. Source code shows how things work, but the lode captures why they were designed that way.
Architecture-first thinking: Report A’s clean layering diagram and “what’s NOT there” section shows how the lode captured high-level design decisions. Reading code bottom-up makes it harder to extract these architectural choices.
Domain context: Terms like “TPA”, “jump table”, “Harvard architecture implications” were used with more precision in Report A with the lode providing the conceptual vocabulary that made these explanations clearer.
Pedagogical structure: Report A’s flow (architecture → process → memory → filesystem → loading) shows the lode captured a narrative and mental model, not just facts.
Report B is mostly correct and demonstrates the model successfully reverse-engineered the OS from source. Although it does infer some behaviours from the technology used, and hallucinates the meaning of the name SP/M.
Report A reads like it was written by someone who designed the system, while Report B reads like it was written by someone who studied it. The lode captures design intent and conceptual models that are not visible from the code alone.
This is a compelling argument for structured knowledge representation and Lode Coding by providing the conceptual scaffolding necessary for sustained development and quality model interaction.
I have provided both reports below in case you’re interested.
Model: Kimi-K2.6 (Ollama Cloud, 256K context)
| Report | Time | Turns | Tool Calls |
|---|---|---|---|
| A | 46s | 8 | 19 |
| B | 1m 27s | 9 | 24 |
Prompt: explain the OS aspects of this implementation
[intermediate turns redacted for brevity]
The user wants me to explain the OS aspects of this implementation. I now have a comprehensive understanding from the lode files and source code. Let me synthesize this into a clear, structured explanation covering the key OS aspects:
Let me provide a comprehensive but concise explanation.
SP/M is a minimal operating system for ESP32 microcontrollers, built on top of FreeRTOS/ESP-IDF but presenting its own distinct OS personality. Here are the key OS aspects:
SP/M follows a layered design with clear separation between kernel services and user code:
┌────────────────────────────────────────────┐
│ User Space: Scripts (.sps) │
│ Transient Programs (.spm) │
├────────────────────────────────────────────┤
│ Kernel: CCP │ VFS │ Loader │ Script │
│ Shell │ │ │ Interpreter│
├────────────────────────────────────────────┤
│ HAL (GPIO, UART, I2C, SPI, ADC) │
├────────────────────────────────────────────┤
│ ESP-IDF (FreeRTOS, drivers) │
└────────────────────────────────────────────┘
The kernel is monolithic — all services (shell, filesystem, loader, interpreter) compile into a single binary (~440KB).
SP/M has no processes in the traditional sense. Instead, it has three execution contexts:
| Context | Type | Lifetime | Core |
|---|---|---|---|
| CCP Shell | Infinite loop | Forever | Core 0 |
| Transient Programs | Loaded binary | Until exit | Core 1 (dual-core) |
| Scripts | Interpreted text | Until completion | Core 0 |
There is no preemptive multitasking. Only one transient program or script runs at a time. The shell blocks during script execution and remains responsive during transient program execution (because programs run on Core 1).
SP/M runs on ESP32’s Harvard architecture, which has separate executable (IRAM) and data (DRAM) memory regions. The OS handles this explicitly:
.text (code), allocated with MALLOC_CAP_EXEC.rodata, .data, .bss, allocated with MALLOC_CAP_8BITThe loader performs IRAM-safe memory operations because IRAM requires 32-bit aligned access — byte-level memcpy/memset will crash. The loader uses word-aligned copies.
There is no virtual memory, no memory protection, and no address space isolation. Everything shares the same physical address space.
SP/M implements a Virtual File System layer on top of ESP-IDF’s VFS:
| Mount Point | Backend | Purpose |
|---|---|---|
/void/ |
Virtual | Always exists, always empty (graceful degradation) |
/nv0/ |
Internal flash (LittleFS) | Persistent config/scratch |
/sd0/ |
SD card (FAT32) | Removable storage |
Path aliases provide named shortcuts:
sys: → /sd0/system/ → /nv0/system/ → /void/ (cascading fallback)null: → /void/The VFS root / is a virtual namespace — it lists mount points but cannot be opened with opendir().
SP/M’s most distinctive OS feature is its transient program system — a deliberate homage to CP/M’s COM files:
A custom binary format (28-byte header + sections + relocation table):
[header: magic, version, entry, sizes]
[.text section]
[.rodata section]
[.data section]
[relocation table]
SPM\x01) and versionTransient programs cannot call ESP-IDF directly. Instead, the kernel passes a function pointer table (spm_table_t) at program entry:
typedef struct spm_table {
// Console I/O
int (*putchar_fn)(int c);
int (*getchar_fn)(void);
// File I/O (POSIX-like)
int (*open_fn)(const char *path, int flags);
int (*read_fn)(int fd, void *buf, size_t n);
// ...
// Hardware
int (*gpio_set_level)(int pin, int level);
int (*i2c_write)(uint8_t addr, const uint8_t *data, size_t len);
// ...
} spm_table_t;
This is SP/M’s system call interface. The SDK header (sdk/spm.h) shadows ESP-IDF function names with macros that transparently call through the jump table, enabling dual-target compilation — the same source compiles as either a transient program or native ESP-IDF firmware.
On dual-core ESP32 (ESP32, ESP32-S3):
This means you can run a program and still interact with the shell — a deliberate design choice for hardware debugging.
On single-core variants (ESP32-C3, ESP32-C6):
The CCP (Console Command Processor) is the OS shell:
if/else chain to built-in commands.spm file)This is not a modular command system — built-ins are compiled into the kernel, not loadable modules.
These absences are as important as its features:
SP/M is a single-user, single-tasking, embedded OS with a deliberately retro design philosophy. It provides just enough OS services to support interactive hardware debugging: a shell, filesystem, program loader with relocations, and a hardware abstraction layer. The jump table mechanism gives it a clean binary interface for user programs without the overhead of a full syscall trap mechanism. It trades completeness for simplicity and fast iteration during hardware bring-up.
Prompt: explain the OS aspects of this implementation
[intermediate turns redacted for brevity]
The user asked me to explain the OS aspects of this implementation. I have gathered enough information to provide a comprehensive answer. Let me summarize the OS-like aspects of this SP/M (Script Processing Module) system:
.spm files (transient programs) via a loader with a jump table (system call interface). This is similar to CP/M or early DOS TPA (Transient Program Area) model.spm_table_t provides a structured system call interface for transient programs, shadowing ESP-IDF/FreeRTOS APIs.This is essentially a miniature operating system for ESP32, modeled after classic CP/M concepts but with modern embedded features. Let me provide a clear, structured explanation.
This project is a miniature single-user, single-tasking OS for ESP32 called SP/M. It is explicitly modeled after classic CP/M concepts (the name, “Transient Program Area,” .spm binaries, and the jump-table syscall interface), but built on top of FreeRTOS and ESP-IDF. Here are its OS aspects:
The system follows a monolithic kernel design with a clear separation between the resident kernel and transient user programs:
main.c, ccp/, exec/, vfs/, hal/): Always in memory. Handles hardware, filesystems, shell, and program loading..spm files): Loaded into the TPA, executed, and then discarded.The boot sequence in app_main() is typical of a small OS:
ccp_run())SP/M implements a CP/M-style Transient Program Area (TPA) with explicit memory segmentation:
| Region | Size | Purpose | Allocation |
|---|---|---|---|
| IRAM (code) | 32 KB | .text section |
MALLOC_CAP_EXEC \| MALLOC_CAP_32BIT |
| DRAM (data) | 16 KB | .rodata, .data, .bss |
MALLOC_CAP_8BIT |
| Stack | 8 KB | Program stack | Part of FreeRTOS task |
The loader (exec/loader.c) is the core of the process model:
.spm binary (header + sections + relocation table)program_task) to run the programwhile (!s_exec_ctx.done)) until the program exits, then frees TPA memoryThis is effectively cooperative multitasking from the shell’s perspective: only one user program runs at a time, and the kernel waits for it to finish.
SP/M provides a structured syscall interface via the spm_table_t jump table (sdk/spm.h, exec/spm_table.c). This is the only way transient programs interact with the kernel:
putchar_fn, getchar_fnopen_fn, read_fn, write_fn, close_fn (pass-through to POSIX/VFS)exit_fn, delay_ms_fnThe SDK header (spm.h) shadows ESP-IDF and FreeRTOS APIs as macros that dereference the jump table. This means the same source code can compile as either:
This is analogous to how DOS .COM files used INT 21h or how modern OSes use libc as a syscall wrapper.
The VFS layer (vfs/) provides a Unix-like namespace on top of ESP-IDF’s VFS:
/void/ (virtual empty), /sd0/, /sd1/ (SD cards), /nv0/ (internal LittleFS flash)sys:), absolute paths, and relative paths with CWDccp_get_cwd())This abstracts the underlying storage (SD via FAT, internal flash via LittleFS) behind a unified path interface.
The HAL (hal/hal.h) isolates the kernel from ESP32-specific peripherals, providing a consistent API for:
This is the standard OS HAL pattern: the kernel and transient programs talk to the HAL, and the HAL talks to ESP-IDF drivers.
The Console Command Processor (ccp/ccp.c) is the user-facing OS shell:
line_edit.c)argc/argvhelp, ls, cd, cat, gpio, i2c, etc.).spm files) if no built-in matcheslast_error) like $? in Unix shellsBeyond binary transient programs, the OS includes a full interpreted language runtime (script/):
.spm binariesSP/M is a real operating system in miniature. It has:
Its architecture is closest to CP/M (transient programs, TPA, jump table) or early MS-DOS, but running on a dual-core ESP32 with FreeRTOS as its microkernel foundation.
]]>When you use AI coding assistants, you’ve probably noticed something frustrating: the AI doesn’t truly know your project. It can see your code, but it doesn’t understand your architecture, your naming conventions, or why you made certain decisions. The deeper context, the stuff that lives in your head and your team’s conversations, isn’t accessible to it.
Lode Coding solves this by giving you a flexible approach to capture and share that deeper project knowledge with your AI coding assistant.
Imagine having a body of knowledge about your project. One that is effortlessly created and maintained, that explains how things work, why they’re built that way, and what patterns to follow. Now imagine referencing this body of knowledge whenever you work with your AI coding assistant.
While you can recall why you made a decision in the past your AI coding assistant cannot. The lode bridges this gap by capturing knowledge from previous sessions, giving the AI access to context it would otherwise never have.
That’s Lode Coding.
The word “lode” comes from mining. A lode is a rich vein of valuable ore. Your project’s lode is a rich vein of valuable knowledge, accrued over time as you solve problems and deliver features.
The coding assistant will decide what goes into the lode and you can prompt it for further refinement. A lode is a collection of markdown files (.md) organized in a folder. These files describe:
You don’t write these files manually. They emerge as a byproduct of your design, planning, and implementation conversations with the AI. You’re not setting out to write documentation. You’re solving problems, and the lode captures what you learn along the way.
The coding agent will create this if it does not exist. It will also populate and maintain the lode content. You do not have to do anything other than ensure that you enrich your agent via one of the following methods:
A typical baseline structure that the agent will create looks like this:
project/
└── lode/
├── summary.md # What is this project?
├── terminology.md # What is this project?
├── practices.md # Patterns and practices relevant to this project
├── lode-map.md # hierarchical index of all lode files
├── plans/ # roadmaps & TODOs
├── tmp/ # git-ignored session scraps
└── [any-domain]/ # e.g. parser/, auth/, ui/, billing/
└── summary.md + *.md # one focused topic per file (kebab-case)
The structure and content will grow as you orchestrate development.
Conversational orchestration is key to the success of this method. You converse with the agent as if you were pairing or mentoring a junior or mid-level colleague. A unique colleague at that, one who types extremely fast, has considerable knowledge of languages, protocols, and other theory, but lacks any experience in building quality sustainable software and is prone to making foolish mistakes.
Converse with the agent in this manner and you will naturally provide the level of detail required to enrich the session, resulting in more productive output and high quality information placed in the lode.
Instead of writing markdown files up front, behave like you would if you were coding organically. Ensure you have a good understanding of the requirements, a reasonable idea about the overarching design, and a mental list of steps you plan to implement, as well as the checkpoints you’ll use to verify results.
Conduct a two-way conversation with the agent as if it were a colleague. Explain the problem, your vision, plan, and other pertinent details. The two-way conversation is important because you receive feedback from the agent about its understanding and the opportunity to correct it. This is considerably more effective than up-front detailed hand-written markdown.
If your agent has a planning mode you should use it for this step as it will result in a comprehensive plan you can review before starting.
When the agent presents you with a plan you should review it and provide feedback, ask clarifying questions, and if necessary continue the conversation to raise the quality of the plan. No different to mentoring a colleague.
Once you’re happy. It’s time to implement.
This phase has become a lot simpler since Q4 2025 when agents and models seemed to take a dramatic step forward in ability. In the following I will present the more controlling approach but you should find that you can relax a little more and leverage the benefits of these new agent and model capabilities.
By now you should have been presented with a plan. One that maps well to the vision and instruction you provided during planning. *This is not the time to go grab a cup of tea*. This is the time to work.
Our primary goal is to ensure we have quality, maintainable, and acceptable code by the end of the session. No long rework, no manual refactors or clean up.
Keep your agent’s permissions as tight as possible. How tight is going to depend on the complexity of the work at hand, your comfort with the lode coding method, and your level of trust with the model and agent.
Intervention is important. If you see the agent start to do something that is unacceptable, hit the ESC key and have a pep talk with it. This might involve asking it what it’s doing, or it might just be a straightforward correction.
Correcting via conversation is important in lode coding. The agent will automatically update the lode on completing work. So it’s important that any clarifications or direction changes are provided to the agent if you want those retained for future sessions.
Planning and implementation aren’t phases you complete once. They form a tight cycle: plain, decide, review, implement + intervene, repeat. The agent will automatically update the lode as it goes.
Work with small incremental changes. Avoid trying to one-shot anything, especially entire features. Work to your own pace. Don’t let the marketing hype push you into trying to 100x your work. Speed is an inherent properly of coding agents, but your primary goal here is to retain full understanding of the code and to enforce a level of quality that encourages sustainability and changeability.
Sometimes its helpful to move an implementation to a fresh session. To do this simply ask the agent to create a handover lode. It will then create a lode in lode/plan/ and leave handover instructions for the next session. You can resume a handover by simply mentioning the handover file in your first prompt:
resume from lode/plans/name-of-handover.md
It’s useful to not include an @ prefix when doing this.
From time to time you will want to conduct a lode audit. You can do this by simply asking the agent:
audit the lode and ensure it correctly describes the system as implemented
The agent will conduct an interactive review with you and update the lode.
As far as merging goes, the agent is quite capable of looking at the two branches and reconciling the lode after you have conducted the merge. If you have any lode merge conflicts, just accept the incoming changes and then explain to the agent that it should resolve any inconsistencies in the lode. Provide helpful information relating to relevant branches or commits. The agent will do most of the work for you and verify the lode is correct.
Lode Coding works with existing projects. When you start a lode coding session the agent will attempt to read the lode. If the lode does not exist, it will ask you if it can create one. Accept this request. The agent will examine the project and create the baseline lode structure.
If your project is relatively small the agent might then add additional lode files to give itself full coverage but in most cases it will suggest updating the lode as it goes.
If you want a full lode created you can simply ask the agent for one. Large lode creation is better done in phases so be sure to enter planning mode and have the agent work in tranches. Create a fresh session for each tranch. Also, watch your token usage. :)
AI coding assistants are tools, not authors. When code goes into your project, it becomes your responsibility. Bugs, security issues, maintenance: all yours.
Lode Coding forces you to stay engaged. You’re not copying and pasting blindly. You’re not feeding in a markdown requirements document and hoping for the best. You’re undertaking context management, then you’re reviewing, understanding, and accepting only what you’d be comfortable defending.
Every session adds to your lode. Over time, your AI coding assistant becomes remarkably effective because it has access to rich, accurate context about your project. The assistant will also proactively refresh knowledge when it becomes stale due to change, and add missing information as gaps are discovered.
Every new session, the AI will already know your conventions, your architecture, and your preferences.
Today you might use Claude Code. Tomorrow it might be something else. Your lode is markdown files. They work with any AI tool that can read text. You can even use multiple tools simultaneously: developing on your desktop with one assistant while submitting issues for automatic completion by another. Both have access to the same rich information, and you can reference lode files in your issue text as well.
You’re not locked in. Your knowledge investment stays with you regardless of what tooling you use.
Visit the Lode Coding Repo and either clone it and run the lode script to start, or use the custom agent in Anthropic’s Claude Code or Github’s Copilot, or grab the System Prompt, and save it in your AGENTS.md.
That’s it. You’re ready to Lode Coding.
Once you’re comfortable with the basics, explore these resources for deeper insight.
Lode Coding is simple, repeatable, low friction, and effective.
Back in April I wrote a short piece on Lode Coding, a disciplined approach to AI-assisted coding. If you’re not familiar with Lode Coding then please read the original Lode Coding article first.
Today I am revising this topic to share a few refinements to the approach. If you want to know about my background then there’s plenty of info in my bio.
Lode Coding’s primary goal is to enhance my own disciplined approach to software development through the use of llms. It’s not a one-shot-wowfest, but an incremental adoption of modern tooling to improve existing, well established, practices.
I’ve found this approach to be extremely effective. It lacks the ego-lifting-circle-jerk-feelgood-factor that seems to attract attention. But I hope some find it as useful as I have.
Lode Coding is simple, repeatable, low friction, and effective. Try it, take what works, leave the rest, or ignore it. I am sharing it for those who will find it useful. It works for me but ymmv.
One thing I should have made quite explicit in my original article is that Lode Coding is a switch, not a dial. I don’t mix Lode Coding with traditional coding. I have two distinct forms of development practice:
Traditional coding is where I code manually and deliberately. When I’m coding like this there is no copy/paste. No prompting for implementation. Just good old fashioned discipline, knowledge, and reference material. I don’t use AI auto-complete nor AI-suggestions. I do what I’ve always done. And there are plenty of scenarios where this remains the best approach.
Lode Coding is all about 100% prompting. No code editing. My editor becomes my window into the model’s output. I’m not coding, I’m orchestrating, anchoring, reviewing, and iteratively refining. I’m sharing my experience with the model and building up an effective context window that enables good coding outcomes. And, when I’m done, I’m getting the model to sow that knowledge back into the lode. This differs considerably from Vibe Coding: my focus is on knowledge capture, lode enrichment, ownable outcomes, and quality results.
I’ll talk more about how I segue from one to the other in the next section.
I can’t emphasise this enough. I never write a single lode myself. The model creates and maintains all of them. It’s surprising sometimes how insightful these lodes become. Leaving the llm to write the lodes encourages me to share the knowledge, perspectives, and design objectives required to meet the goal.
This has proven invaluable. I switch between Github Copilot, Claude Code, and Jetbrains Junie with zero friction. Very helpful considering how the pricing landscape is changing on what seems like a weekly basis. I can seed a session for any assistant and get at minimum the same baseline outcomes. I’ve never used the memory features in any of the tools, they aren’t worth the lock-in.
Currently I pay US$10/m for Github Copilot, US$20/m or US$100/m for Claude Code (depending on how busy I am), and I have access to Jetbrains Junie through my All Products pack. Being able to move between vendor offerings with zero friction is extremely useful, especially considering that Github Copilot has a number of “unlimited” models.
I have found myself being less concerned about chat vs agent mode. Most models will respond to questions without running ahead. But sometimes I find it useful to be explicit that this is a chat or planning session.
Once the lodes are enriched enough early anchoring becomes relatively simple. Introducing the lode overview at the start of a session is usually enough. I’ve also found that the model will create a system overview lode without being asked, so I’ll usually source this early too.
In the next section I’ll expand on how I’ve adapted early anchoring.
This one is absolutely key. Taking ownership of the outcomes, being prepared to call the work my own, being able to maintain it when there’s no agent available. Ultimately the code the model produces reflects my own goals. I am always pushing the development forward with my prompting, not being pulled forward by the model’s decisions.
Nothing gets pushed unless it’s 100% understood, 100% ownable, and at an acceptable level of quality. I can switch to traditional coding practices with all of the Lode Coding outcomes. Just as if it had been written by me or another team member.
So what enhancements have I made since the last article? Well there are a few that are worth reporting on now. Some I will hold off on until I’ve tried them a bit longer. But let’s delve (!!) into the former.
In the original article I mentioned the ~/lode/tmp folder as being a special location for temporal information that I don’t want in the repo. This includes planning lodes. I’ll kick off a planning session, seed it with relevant lodes, have a conversation with the model, ask for it to propose a plan, iterate a refinement of that plan, get the model to document the plan to a tmp lode - including relevant information from other lodes. Then I’ll start a new session, source that one tmp lode, and prompt: make it so.
Planning sessions are 100% discussion based. Lode maintenance is zero effort due to sourcing the lode-overview and relevant lodes as part of that discussion.
I find this less useful now due to the planning lodes. It’s far more effective to start a session, source relevant lodes, discuss the session outcomes, create a planning lode, clear the session and then run the next session from that planning lode. Sometimes I can’t just make it so and will have a conversation that produces iterative outcomes.
I find that the models, especially Claude Sonnet, are better at UI design/implementation than I am. So I will often work traditionally on back end features and then segue into a Lode Coding session to create/iterate the UI.
After a traditional session I’ve found it useful to update the lodes. This’ll usually involve telling the model I’ve made some changes, and then watching it read the code and the lode and then update the lode automatically.
I’ve also found it useful to gather information via grok. Usually relating to more technical aspects of a problem. I’ll have a code-agnostic conversation with grok and then copy the conversation as markdown and drop it into ~/lode/tmp as a resource for a Lode Coding session. I have on occassion also brought Grok into an active session to help seed some expertise with minimal effort on my part.
These two commands in my Claude Code global config illustrate how easy it is to kick off and finish a session with a lode update.
~/.claude/commands/lode.md
# Seed lode method
Our knowledge management approach is defined in lode/lode-overview.md
~/.claude/commands/lupdate.md
# Request lode update
remove code comments that provide historical commentary.
update lodes with concise information,
do not leave historical commentary,
the lode is a snapshot for AI agents.
lode-overview.md provides an example lode overview used for initial project seeding. This gives the model enough information about the approach to enable it to maintain lodes. Bear in mind that the model will update this lode just like any other lode. I place the file in ~/lode/lode-overview.md (github gist)
I have recently open-sourced a handful of projects which have included some Lode Coding efforts. These are:
fjleb128 is an early project which I wrote by hand. I added the lodes later in the project to help me go from “good enough for me” to “good enough to open source”. One area of the library that was Lode Coded was the span support and associated tests. These lodes are a little more verbose than more current ones but give a decent impression of what the model will produce as an outcome of a session. (repo)
arcc is a tool that was produced entirely via Lode Coding. I think I might have put in about 30 mins of traditional coding practice into it. Leveraging my long-established Win32 SDK experience, I prompted my way through this one just to get the tool good-enough. If I wanted to extend this tool I’d probably put in more time cleaning up the code and improving separation of concerns. This one is included because it’s as close to Vibe Coding as Lode Coding gets. (repo)
Software development is an ecosystem comprising those who build and those who consume. What happens when the builders start to disappear?
In the days before open source software, the software development scene was quite straightforward. Companies had two main options for sourcing the underlying tooling to deliver a solution: they could either buy a commercial library licence or hire experienced developers to create custom tooling. This was a time of high demand for skilled developers, with a significant barrier to entry, and work that was both mentally challenging and financially rewarding.
The emergence of open source software changed this landscape dramatically. Developers no longer needed to maintain a vast toolkit of computer science knowledge. Instead, they could leverage open source libraries to handle the heavy lifting, allowing them to focus almost exclusively on solving business problems. Many of those open source solutions were effectively free of charge. This shift democratised software development, but it also created a new ecosystem that would become crucial to the industry’s future.
The open source community thrives on motivated developers who contribute for various reasons. For many, it’s a career accelerator - a way to demonstrate abilities, develop skills, and drive interview conversations. It’s also a powerful platform for showcasing collaboration skills and organisational compliance. Most importantly, it’s all out in the open, visible for anyone to see and evaluate.
This visibility has led to an explosion of open source projects. Almost every library started with a simple problem and solution, evolving into a reusable library as interested parties got involved. The community’s strength lies in this organic growth - developers solving real problems and sharing their solutions with others.
This ecosystem is responsible for almost everything. From the niche office automation tooling created by a disparate community of developers who want to solve one specific problem, right up to the creators of languages, compilers, editors, and core infrastructure.
The open source ecosystem traditionally balances two primary stakeholders: the contributors and the consumers. While we’ve explored the motivations of contributors, the consumers - particularly for-profit corporations - play an equally crucial role. These companies rely heavily on open source software to make their systems development financially viable. Without open source, many companies would struggle to fund the internal skills they’d need to get things done. And in turn, by being potential employers, they contribute to the motivation for developers to get involved. We all depend on the open source communities, even those of us who primarily produce closed source proprietary solutions.
But there are new players in this ecosystem: the AI coding agent vendor and their “vibe coding” users. These new stakeholders bring a concerning mentality to software development. They view software development as something that can be automated and commoditised, claiming that AI agents will soon replace developers entirely. Their focus is purely on profit, with little regard for the software development ecosystem that makes the vendors tools viable, and the “vibe coders” dreams feasible.
It’s one thing to expect an AI agent to glue together a few libraries that represent thousands of hours of work comprising the opinions and experience of an army of smart minds. It’s an entirely different proposition to expect an AI agent to reproduce that work at an acceptable level of proven quality.
So what happens if the AI agent vendors and users get their “developer-less vibe coding” utopia? The consequences could be severe. The demand for software developers would begin to disappear, taking with it the motivation that drives the open source community. Many open source projects would die from neglect, and we would face a generational1 loss of skill that might never recover.
Consider these critical questions: How useful would an AI agent be if it couldn’t pull in human-created open source libraries to do the real work? How many people drawn to the “vibe coding” or “prompt-driven development” cycle would be motivated to take over open source software maintenance?
Remember, these are people who were drawn to AI agents because of the simplicity and speed, not because of the underlying technical outcomes. I foresee a desert of creativity, where the motivated minds who once contributed to open source software seek their satisfaction - and income - in other industries. A sad but inevitable outcome of the destruction of the software development discipline.
Assuming that AI agents are going to remain, there are two possible outcomes as I see it: a failure cascade and a total takeover.
The failure cascade is simple: with fewer developers, open source will cease to be a viable source of tooling. The loss of human-created tooling will lead to a failure of AI agents. The industry will have to reboot, having lost a generation of developers.
The total takeover is more concerning. In this scenario, the AI agent vendors progressively fill the gap created by the collapse of open source software. They produce the libraries themselves, employing humans to produce them, and then charge licence fees for their use via their own products. Don’t fool yourself into thinking that the AI agent vendors would open source their work. Why would anybody open source a toolset if the only other consumers are their competitors?
The software ecosystem has always relied on a delicate balance between those who build and those who consume. As AI agents edge closer to the centre of development, we risk losing not just the builders, but the motivation and community that have driven open source forward. If we allow the skills and spirit of real developers to fade, we may find ourselves in a world where innovation stalls and the tools we depend on are no longer freely shared, but locked away behind paywalls. The future of software depends on the choices we make now. Do we nurture the ecosystem, or watch it unravel?
Generational Loss
As I see it, a developer generation is created over a 5 year period, very often as young people gain unfettered access to computing. A generational loss would take 5-10 years at most. ↩
A lode is a rich or abundant source of valuable resources.
AI coding assistants are powerful tools, but their effectiveness depends heavily on context. Without proper guidance, they can generate inconsistent or misaligned solutions. Over the past year, I’ve evolved a systematic approach that solves this problem by maintaining a rich knowledge repository - a lode - that captures the essence of a project.
This approach – dubbed Lode Coding – is a simple, tool-agnostic method that helps me get the most out of AI coding assistants. By building and maintaining a structured collection of project knowledge, I can quickly seed AI sessions with relevant context, leading to more consistent and higher quality outcomes. The approach requires no special configuration and works with any AI coding assistant that supports chat mode, agent mode, and file references.
This article presents a practical guide to Lode Coding. I’ll explore how I create and maintain a knowledge repository, how I use it effectively in coding sessions, and some practical tips that help me maintain control while getting the most out of AI assistance.
I use a few specific terms throughout this article to describe different aspects of Lode Coding:
Chat Mode - the coding assistant mode where the assistant will not modify your code
Agent Mode - the coding assistant mode where the assistant will offer file changes
Seeding - prompting in chat mode to enrich session context
Orchestrating - prompting in agent mode to achieve a specific outcome from a well-seeded session
Lode - a structured repository of relevant system knowledge
Anchoring - direct intervention to rein in an over-enthusiastic coding assistant
Here are the key advantages I’ve found with Lode Coding:
Zero configuration: It’s a philosophy and process, not a technology. I don’t need any special tools or setups.
Tool agnostic: I can use this with any coding assistant that supports chat mode and file operations. No vendor lock-in.
Simple approach: I just maintain markdown files in a structured way. No complex systems or special features needed.
Zero Lead Time - lodes are created iteratively as a by-product of the development process.
Fast context seeding: I can quickly provide high-quality context to get my coding sessions on the right track from the first prompt.
Easy context switching: When I need to fork context or switch tasks, I can do it with minimal overhead by referencing different lode files.
Consistent results: By providing focused context, I get more reliable and aligned output from the coding assistant.
Knowledge retention: I capture and retain systems knowledge that I can use to seed prompts, discuss the system, orchestrate code generation, and write documentation.
Team friendly: Since the lode lives in the repo, a team can work from, share, and enrich the same knowledge base.
A lode is a rich or abundant source of valuable resources.
Knowledge capture and storage is a fundamental software development skill1. As a professional developer, I spend much of my time discovering and capturing knowledge - in code, tests, documentation, and through discussions with my peers. When working with coding assistants, I’ve found this knowledge to be just as crucial - I need to provide relevant context to get meaningful results.
This realization led me the evolution of Lode Coding. Instead of repeatedly providing context to a coding assistant manually, I maintain a structured repository of knowledge - the lode - that covers all relevant areas of my system. This includes both implemented features and planned developments, alongside higher-level design decisions and patterns.
By maintaining the lode in the same repository as my code, I can easily access, enrich, and reference it during coding sessions. When I start a new task, I simply tag the relevant lode files to seed my session with the right context. As I progress through my goals, I also maintain and update the lode, ensuring it grows alongside my project.
The lode becomes particularly valuable when I’m working on complex features or returning to a project after some time away. Instead of having to rebuild context from scratch, I can quickly provide the coding assistant with the specific knowledge it needs to help me effectively.
I usually have a lode directory structure at the root of my repo. The minimum lode looks something like this:
~/lode/
overview.md
I also keep a tmp directory for short-term knowledge. When I’m forking a session, I’ll dump relevant parts into a file in ~/lode/tmp/ so I can use it – and other lode files – to seed a new session while retaining important context.
~/lode/tmp/
refactor.md
I always add ~/lode/tmp to .gitignore.
I don’t write lode files by hand. Instead, I have the coding assistant create them. I converse with it to build up a session specifically focused on an area and then ask it to create the file. This makes creating and updating lode files low effort. I’ve found that if I tell the assistant it’s writing the file for itself, it creates a more effective lode file anyway.
Creating the lode from an existing project
When I have an existing code base, I start a new session in chat mode and ask the agent to examine the codebase and provide a summary. I review this summary, prompt to clarify any inaccuracies, misunderstandings, or missing context. Then I have the agent re-present the summary and iterate until I’m happy with the outcome. At this point I switch to agent mode and request the summary be saved as a markdown file. I usually place this file in ~/lode/overview.md.
Starting from Scratch
When I’m starting from scratch, I make the effort to begin my project with deliberation. I set up the scaffold to my liking and name things well enough to convey intent. Then I go through the same steps outlined above to create my ~/lode/overview.md. I also enrich this overview in chat mode to provide more context.
Dealing with Complex Projects
For complex projects, especially those with multiple behavioural boundaries – both internal and external – I create a subdirectory for each system behaviour and prompt for a new overview.md to introduce it. When I need more detail, I create other .md files in the same folder to keep the knowledge in small reusable units.
Here’s an example lode from one of my current projects - a programming language that compiles to WASM. The language’s syntax is heavily influenced by the Web Assembly Component Model and WASM Interface Type language. While the project is in its early stages, the lode has already proven invaluable. I’ve had many sessions where I’ve achieved a goal in just two shots, producing code that meets my standards and that I’m confident owning.
~/lode/
milestones.md
overview.md
unit-testing.md
language/
overview.md
reference-manual.md
wit-support.md
lexer/
overview.md
parser/
overview.md
read-lex.md
parse-syntax-tutorial.md
generator/
overview.md
binary-section-tutorial.md
patterns.md
examples/
currying_demo.lang
data_processor.lang
graphics_engine.lang
string_processor.lang
Each file in this lode contains markdown documents generated by my coding assistant, either from orchestration sessions or focused conversations. These files provide concise descriptions of specific areas of the system, which I use to seed new sessions with relevant context. The tutorial files are particularly valuable - they teach the assistant my preferred patterns and approaches for complex operations like parsing syntax or generating WASM binaries using parts of the system that I wrote by hand.
As the system grows and my design evolves, I make sure to keep the lode up-to-date. I maintain information about system behaviours, milestones, roadmap, standards, patterns used in my code, and the endpoints and interfaces of behavioural boundaries.
Sometimes my coding assistant gets lost or misaligns with my intentions. I’ve found I can fix this by starting a mentoring session. I begin by seeding the session with existing lode files and reference source files, then I provide guidance to help the assistant understand how to code the way I want. Once done, I have it create a new lode file to capture this knowledge.
For example, in my compiler project, parse-syntax-tutorial.md came from one of these tuition sessions. This file gives the assistant everything it needs to know about querying the lexeme queue, working with token patterns, using existing tokens, and creating new ones. Similarly, binary-section-tutorial.md provides guidance on generating WASM binaries according to my patterns and preferences.
I also experiment with including mermaid diagrams in the lode documents. I’ll ask the coding assistant to create these diagrams, review them, and add them to the lode. While I’m not yet certain how much the assistant benefits from these diagrams, I include them to explore their potential value.
When I finish implementing a goal, I follow a simple process to update the lode:
This systematic approach helps ensure the lode remains a reliable source of context for future sessions.
I work with two levels of granularity: objectives and goals. An objective is a high-level outcome, something akin to a story or complete feature. A goal is one step in delivering that objective - essentially a task. I keep my goals small and very focused on specific outcomes.
After breaking an objective down into goals – my normal approach when coding – I iterate through a number of goal sessions to deliver the feature.
Here’s how I structure each goal session:
When updating the lode, I switch to chat mode and ask my assistant to summarize what we’ve achieved. I review the response and provide any needed corrections. Then I ask which md files in the lode folders are affected by these changes and iterate through the assistant’s response before requesting updates to the lode files.
Before ending the session, I ask the assistant to summarize any information not captured in the existing lode files. After refining this summary, I have the assistant save it in a new lode file. Sometimes the assistant suggests where to put the file, but I can always specify a different location if I prefer.
Once I’m satisfied with both the code and lode updates, I accept all changes, commit them, and close the session.
Orchestrate the conversation. Coerce the coding assistant to do your bidding.
When I orchestrate, I almost exclusively code by talking to my coding assistant. I don’t edit source files directly - instead, I direct the assistant through conversation.
With my session already seeded with relevant lode files and the goal communicated, I stay in chat mode to discuss what needs to be done. I approach this with the same mental picture I’d have if I were coding by hand. The difference is that I’m going to helicopter over the topic and guide the assistant in writing all the code. I switch between chat and agent modes when I need to direct/clarify and create code respectively.
Here’s what my orchestration process looks like. While I use Cursor in this example, this works with any coding assistant:
Setup
Iteration
This orchestration approach means I’m fully engaged with every change being made. I’m not passively accepting suggestions - I’m actively directing the implementation, reviewing each piece of code, and understanding every decision. Because I’m thinking through the solution just as I would if coding by hand – with the mechanical work delegated to the assistant – I maintain complete ownership of the architecture and design. When the goal is complete, I’m confident in the code because I’ve shaped it, reviewed it, tested it, and understood it at every step. The resulting implementation is as much mine as if I’d typed every character myself - the assistant is simply helping me work more efficiently.
Lode Coding is a disciplined approach to working with AI coding assistants that centres around maintaining a knowledge repository (the “lode”). The method involves storing project knowledge in markdown files within a structured directory (~/lode/), which is used to seed AI coding sessions with relevant context.
Key aspects include:
The approach emphasizes taking ownership of AI-generated code, maintaining control of the development process, and creating a reusable knowledge base that grows with the project. It’s tool-agnostic and requires no special configuration, making it easy to adopt with any AI coding assistant that supports chat and file operations.
The method has proven particularly effective for complex projects, reducing mental load while maintaining code quality and consistency with my standards and design intentions.
Know your mode, stay in control, own the outcomes, build something you can own.
Here are a few fundamentals that help me get the most out of Lode Coding.
Know when you’re conversing and when you’re orchestrating. Choose the right mode.
I’ve learned to be deliberate about switching between chat and agent modes. When I just want to discuss or explore ideas, I stay in chat mode - this prevents the assistant from making unwanted changes just because I asked a question. When I’m ready for code changes, I switch to agent mode. Being explicit about these mode switches gives me better control over the session.
Make sure the coding assistant knows you are in control.
While runaway prompts often indicate that my context seeding needs work, sometimes I need to directly tell the assistant to slow down and focus. Anchoring can be as simple as saying “slow down, I’m in charge here,” or I might summarize the session so far and use that summary to seed a fresh session. I’ve found that recognizing when the assistant has gone adrift and correcting early saves me significant time. The lodes make this switch trivial.
Only accept what you are prepared to own. Prompt diligently and iteratively for it.
The coding assistant won’t face the consequences of bad code - I will. That’s why I apply my professional judgment to every outcome before accepting it. I ask myself:
Only when I can answer “yes, I’m happy to call this my own” do I accept and move forward.
You will iterate often, sometimes that’s best done in a new session.
When I need to iterate on a response, I decide whether to continue in the current session or start fresh. It comes down to how the session context is guiding the assistant. If there’s too much history, the assistant might not be as focused on the remaining problem as I am. Sometimes it’s more effective to accept an almost-good outcome, start a new session, seed it properly, and then fix the remaining issue. This is another form of anchoring that can save time, especially with a rich lode.
I hope you’ve found this guide useful. While every developer’s approach to AI assistance will be different, I’ve shared what works for me in the hope that you’ll find some ideas to help make your own coding sessions more productive and enjoyable. Thank you for reading, and happy coding and please reach out to me on X or drop me a follow.
You might also be interesting in September’s update: Lode Coding Revisited
]]>