Published on 2026-03-11
]]>Published on 2026-03-11
Tags: commentary, llm, ocaml, software-eng
Drop a coding agent into any existing codebase that uses libraries and tools that are too private or too new to feature in the training data and my experience is that it works just fine—the agent will consult enough of the existing examples to understand patterns, then iterate and test its own output to fill in the gaps.
This is my experience as well. Two years ago (gpt-4o, sonnet-3.5), there was a noticeable difference in the "smoothness" of the OCaml code generated by agents, when compared to generated Python code. The Python code was simpler, more clever, more easily involved various libraries, while the OCaml code had complicated compound expressions, unfortunate nesting (all helper functions defined inside the current function via let-binding instead of deduplicating into the file or across files), and sometimes simply failed to be written in complex situations involving Functors or circular module definitions or using popular libraries (without handing the agent interface files).
]]>Published on 2026-03-01
]]>Published on 2026-03-01
Tags: article, llm, ocaml, python, software-eng, software-eng-auto
On today's episode: a lot of code. The previous work prepared the project codebase to guide agents in generating good quality code, which is what we did.
After the Kb_service module was broken apart, the coding agent easily generated full verticals for update, resolve, and archive commands. The process I'm following:
docs/product-requirements.md.prompts/activities/implementation-plan.md for building the functionality.prompts/activities/code-review.md), and apply changes for all issues.Related commit: 0eb5584 — feat: add update, resolve, and archive commands
Published on 2026-02-26
]]>Published on 2026-02-26
Tags: article, llm, ocaml, software-eng, software-eng-auto
Today's log consists mostly of code generation. We've laid enough foundation that new functionality is easily produced.
The functionality for bs list is well defined after the work for the previous dev log. I think the experiment of directing the agents from the requirements document rather than my own intuition of what to tackle was successful, though perhaps only at the scale of a project like Knowledge Bases. The coding agent was able to select a reasonable chunk of functionality to peel off and turn into an implementation plan, with a different agent generating the implementation.
Published on 2026-02-24
]]>Published on 2026-02-24
Tags: article, llm, ocaml, software-eng, software-eng-auto
Today's changes follow on from the previous post's "next steps": nesting and ideation.
I worked with the agent to find code with deep nesting, decide how to flatten it, and generalize the approach into suggestions for a nesting principle. We then applied that principle across the codebase, and I think we were successful as the diff in the refactor commit is noticeably flatter.
]]>4. Nesting Depth
Keep expressions nested at most two or three levels deep. Deeply nested code is hard to follow because the reader must hold every enclosing context in their head at once. When nesting grows, treat it as a signal that the code should be restructured.
Approaches for reducing nesting:
- Use monadic result operators (
let*,let+). ...- Extract resource-management wrappers. ...
- Consolidate error mapping into named functions. ...
- Factor repeated control-flow shapes into helpers. ...
Published on 2026-02-20
]]>Published on 2026-02-20
Tags: article, code-review, llm, ocaml, software-eng, software-eng-auto
Today's changes build on the previous commit's unpacking of Todo, making a repository for Todos, and hooking it up to the command line to provide bs add todo ....
The implementation plan forgot to add a task for integration tests, which resulted in a bin principle saying changes to bin, where we're only keeping command-line parsing and top-level orchestration, should always be accompanied by an integration test. I also had the agent put together an architecture document guiding the structure of integration tests and their purpose.
In the hopes of keeping file sizes down, I added a line length principle to bin and lib. I'm not sure about these principles, because I think this can be automated as a lint. I will keep these in mind and improve the linting situation when I get another structural/syntactic principle that can be automated.
Published on 2026-02-19
]]>Published on 2026-02-19
Tags: article, code-review, llm, ocaml, software-eng, software-eng-auto
Today's change to Knowledge Bases is addressing my unhappiness at the beginning of the month: "Data modeling". I've returned to the work of unpacking Note into Todo, to make it easier to control the TypeID prefix, and prepare for making a Todo repository.
A handy thing about coding agents: they can make such a wide-ranging change with minimal effort (see the number of changed files in the commit). Additionally, the coding principles guidance doc paid for itself — agent code review noted the duplicated validation logic for title and content now in both Note and Todo and recommended deduplication. I redirected it to encapsulate the validation into new types, a favorite software engineering technique of mine (see "Aside: Correct Construction"), as well as adjusted the guidance.
Published on 2026-02-18
]]>Published on 2026-02-18
Tags: article, git, llm, ocaml, software-eng, software-eng-auto
I've decided to use this project as a testbed for automatic development, to explore the kinds of techniques described in recent results [1] [2], and to speed up development. I'll be making the vast majority of changes to the codebase via coding agents, exploring what controls are needed to stay hands-off yet maintain code quality.
I've played around with longer AGENTS.md and not seen much value. Agents would ignore pieces, and after a while it felt like simply a waste of context space. I'm keeping AGENTS.md short this time around, "linking" to where more information can be retrieved, with the hope that brevity keeps the content important.
Published on 2026-02-03
]]>Published on 2026-02-03
Tags: article, database, git, ocaml, software-eng
Today's update is brought to you by my lack of motivation 😆. I decided to work on building out a storage layer for Knowledge Bases objects, and then got burned by lack of interest.
Restating our storage requirements: we need notes, todos, etc to be persisted to disk in a way where git's diff will capably show edits, additions, and deletions, and which allows for easily querying these objects by identifier or by their relation to each other (we want to support parent-child, related-to, etc). To meet those requirements I intend to persist data in two ways. First, in an appropriately-sorted JSON or YAML file, to solve for the git-diff requirement. Second, in a SQLite database to make it easy to add/edit/delete/query. The program will mirror the SQLite database onto the JSON file unless it's determined to be out of date (i.e. when the git branch is changed), in which case we'll rebuild the database from the JSON file. For now I'm starting with the SQLite db, as that can be useful for purely local todo storage, and we'll bolt-on the ability to synchronize them over git later.
]]>Published on 2026-01-01
]]>Published on 2026-01-01
Tags: article, git, meta, ocaml, static-site
For 2024's New Year's resolution I decided I'd finally build and publish a personal website. That I'd write up my thoughts on the articles I was reading and post them instead of dumping them on friends 😆. In review, I'm happy to say I succeeded.
I wrote and published 164 blog posts over the past year, not counting this post. September was my most prolific month. I initialized the OCaml project that became the static site generator in late January, writing a test post at the beginning of February to work out frontmatter parsing, markdown generation, and my custom templating language. The first "real" post came at the end of June, a few days after I bought the domain name.
]]>Published on 2025-12-02
]]>Published on 2025-12-02
Tags: changelog, ocaml, static-site
I've created individual image pages. Now all images will link to their own image page, which makes it easier to see the alt text and variant images. For example, this page for the picture of my dog on Rialto Beach.
Implementing this was pretty straightforward. My static site generator makes a distinction between "normal" pages, ones where the Page structure is constructible solely from the contents of a file (HTML or Markdown body with all the necessary metadata in a YAML frontmatter), and "synthetic" pages, where the Page structure is constructed in OCaml code inside the generator. These image pages are synthetic: the generator constructs one for each image original used on the site, generated alongside other synthetic pages like the tag pages or blog post archive pages.
Published on 2025-11-30
]]>Published on 2025-11-30
Tags: article, git, ocaml, software-eng
TypeID is a micro-standard combining a number of well-thought-out decisions.
TypeIDs are a modern, type-safe extension of UUIDv7. Inspired by a similar use of prefixes in Stripe's APIs.
TypeIDs are canonically encoded as lowercase strings consisting of three parts:
- A type prefix (at most 63 characters in all lowercase snake_case ASCII
[a-z_]).- An underscore '_' separator
- A 128-bit UUIDv7 encoded as a 26-character string using a modified base32 encoding.
user_2x4y6z8a0b1c2d3e4f5g6h7j8k
└──┘ └────────────────────────┘
type uuid suffix (base32)
Most identifiers, barring a specialized context, should include a "type" for the identifier. Interconnected computer systems are always passing around identifiers — for someone holding an identifier in their database it is really valuable to know who that identifier belongs to as well as what the identifier is for. For example in a financial institution handling investments, md_quote_2x4y6z8a0b1c2d3e4f5g6h7j8k can tell the receiver that they're holding a reference to a stock price quote, owned by the market data (md) system. Identifier types give engineers metadata, which can be especially useful when there's a bug in the system — no need to stress whether the integer identifier you're currently holding came from the user table or news table.
Published on 2025-11-01
]]>Published on 2025-11-01
Tags: article, ocaml
Short update today — the definitions of note and todo types and their basic operations.
My intention is to represent arbitrary content as a note, and represent things to be done with todo. Notes are just an identifier, a title, and some content, while Todos also have a status and eventually relationships. I've left relationships between notes and todos for later. I'm not sure if I want them represented separately or as part of the structures.
(** Note type and operations.
A note bundles an [Identifier.t] with a title and content.
*)
(** Abstract type of notes. *)
type t
(** [pp fmt t] prints the note [t] using the formatter [fmt]. *)
val pp : Format.formatter -> t -> unit
(** [show t] returns the same string that {!pp} would print. *)
val show : t -> string
(** [make identifier title content] constructs a note after validating inputs.
- [title] must be non-empty and at most 100 characters.
- [content] must be non-empty and at most 10000 characters.
@raise Invalid_argument if validation fails. *)
val make : Identifier.t -> string -> string -> t
(** [id t] returns the note identifier. *)
val id : t -> Identifier.t
(** [title t] returns the title of the note. *)
val title : t -> string
(** [content t] returns the content of the note. *)
val content : t -> string
Published on 2025-10-25
]]>Published on 2025-10-25
Tags: article, llm, ocaml
My inclination, after getting the hello world project set up in place, is to start defining the major data representations of the domain we're working in. Since I'm documenting the process, and I want to discuss decisions, I'm going to start out pretty slowly — today's update is basically just a type for representing identifiers for "notes" (whatever it is we decide to call the basic content building block).
The plan here is to expose an opaque type t for our identifier values (Identifier.t), and be explicit and deliberate about what data is exposed to the rest of the program. I liked how Beads stuck with an identifier format that's human readable, and likely prevalent in LLM training data, so we'll use the same format for our identifier: [a-z]{1,5}-[0-9]+ (e.g. kbase-12345). Decomposing that identifier gets us a namespace and raw_id.
Published on 2025-10-22
]]>Published on 2025-10-22
Tags: article, git, llm, ocaml
A couple days ago, Steve Yegge wrote about a coding agent tool he's been developing called Beads.
Beads is a lightweight memory system for coding agents, using a graph-based issue tracker. Four kinds of dependencies work to chain your issues together like beads, making them easy for agents to follow for long distances, and reliably perform complex task streams in the right order.
I haven't had an opportunity to see if it works well or not, but the feature set seems straightforward to implement and I've been looking for a project to work on which will involve OCaml and publishing to opam. I'll be documenting the development process here 😁.
]]>Published on 2025-09-06
]]>Published on 2025-09-06
Tags: article, ocaml, security, software-eng
When using OpenSSH, you may see ASCII art from time to time, like:
+--[ED25519 256]--+
| |
| . |
| o |
| o o o . |
| .B S oo |
| =+^ =... |
| oo#o@.o. |
| E+.&.=o |
| ooo.X=. |
+----[SHA256]-----+
This is output[1] of the randomart SSH Key visualization algorithm, intended to leverage the user's visual pattern matching to quickly recognize (or not) a remote host key. It's known as the Drunken Bishop's algorithm, contributed to the OpenSSH codebase by Alexander von Gernler in 2008.
]]>Alexander von Gernler on 2008-06-11:
Introduc[ing] SSH Fingerprint ASCII Visualization, a technique inspired by the graphical hash visualization schemes known as "random art", and by Dan Kaminsky's musings on the subject during a BlackOp talk at the 23C3 in Berlin.
Scientific publication (original paper): "Hash Visualization: a New Technique to improve Real-World Security", Perrig A. and Song D., 1999, International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)
Published on 2025-08-18
]]>Published on 2025-08-18
Tags: commentary, llm, ocaml, plt, protocol, software-eng
A general challenge with MCP today is that the more tools you have, the more you’re contributing to context rot. You’re also limited to rather low amounts of input. On the other hand, if you have an MCP that exposes a programming language, it also indirectly exposes a lot of functionality that it knows from its training.
I've been thinking about how one could design a programming language, knowing that a language model would be used in the crafting of programs in said programming language. Models have trouble generating nested "language", e.g. outputting code inside of JSON (and failing to make the code syntactically correct), or as Armin documents their poor ability at using MCP (data and semantics embedded in JSON).
]]>Published on 2025-08-10
]]>Published on 2025-08-10
Tags: article, java, javascript, ocaml, static-site
I like the idea of having search for my blog, to help readers find anything related to a specific topic, or something they'd read in the past. How do I make something as dynamic as search, but statically generated?