Tuesday, June 23, 2026

Cómo se hizo «Menos software, más impacto»

El libro lleva un par de semanas a la venta y hay una pregunta que me repiten: ¿cuánto se tarda en escribir algo así?

La respuesta honesta es que no lo sé. Y no lo sé porque el libro no empezó siendo un libro. Empezó como una serie de posts, sin ningún plan de acabar en Amazon.

Como esta semana toca contar el proceso, me he puesto a reconstruir las fechas con el historial de git, los nombres de los ficheros de las entrevistas y los registros de los trámites. Esto es el making of, sin maquillaje.

No nació como libro, nació como serie

En abril de 2024 publiqué el primer post: "Introducción al Lean Software Development". No iba a ninguna parte concreta. Escribía sobre lo que había ido aprendiendo en equipos reales, un tema por entrega.

Salieron unos dieciséis posts en unos dieciséis meses. Con su parón y todo: después de "Empoderar al equipo" me quedé sin gasolina y la serie estuvo parada buena parte del invierno de 2024. La retomé en primavera de 2025 con el bloque de calidad (cinco posts casi seguidos) y la cerré en agosto de 2025 con "Lean, XP y mentalidad de producto".

Al principio no pensaba en ningún libro, solo en el siguiente post. Pero hacia la mitad de la serie la idea empezó a rondarme: con todo este contenido, quizá había un libro ahí. La aparqué casi enseguida. Me parecía algo lejano y con demasiado trabajo detrás, una más de las muchas ideas que siempre tengo dando vueltas en la cabeza. Aun así, según avanzaba y veía cuánto material se iba acumulando, la idea se hacía más fuerte. Lo que la frenaba era siempre lo mismo: el trabajo que parecía implicar.

El empujón que me lo hizo creer

Tenía el material, y cada vez tenía más claro que ahí había un libro. Lo que seguía frenándome era imaginar el trabajo por delante. Lo que no esperaba es que el desbloqueo llegara de una conversación que no iba de eso.

No nos conocíamos mucho: había hablado con Juan Macías unas pocas veces (algo por mensajes y un par de videollamadas), por temas que nada tenían que ver con escribir un libro. Juan está innovando de forma bastante radical en el uso de la IA para el desarrollo de producto, y además se había escrito un libro con ayuda de la IA, The Broken Telephone, lleno de ideas que me parecieron muy buenas. Tuvimos varias conversaciones sobre ellas.

Como efecto colateral de esas charlas, le pregunté por el propio proceso de crear el libro. Su forma de plantearlo, muy apoyada en la IA y en automatizar casi todo, me hizo verlo de otra manera: el muro de trabajo que me frenaba, de repente, parecía mucho más bajo. Y Juan fue tan generoso como para pasarme el repositorio base que había usado: los scripts, la estructura, todo el harness. Ese fue mi punto de partida. Me dio una base técnica sobre la que construir, sí, pero sobre todo me dio algo más difícil de conseguir: creerme que hacer el libro en un tiempo razonable era posible.

Sin esa conversación, el libro probablemente seguiría siendo una idea más en mi lista.

De posts a libro: poco más de cuatro meses

El 30 de enero de 2026, sobre esa base, hice el primer commit del repositorio. Ese día empezó "el libro" de verdad.

Aquí viene una de las cosas que más me sorprendió: en un par de días ya tenía la estructura entera, los catorce capítulos iniciales convertidos de posts a esqueleto de libro. Tener la serie escrita lo cambia todo. No partía de una página en blanco, partía de material que ya había pasado por el filtro de publicarlo y recibir respuestas.

Cuatro meses de ensamblaje, commit a commit.
No recoge los 16 meses de escritura de posts.

Lo escribí en un repositorio de git, como si fuera código, y me apoyé en la IA para aumentar mi capacidad: automatizar lo repetitivo, ordenar el material, forzar la crítica sobre mis propios textos. Las ideas, la experiencia y la voz son mías; la IA me ayudó a llegar más lejos y más rápido.

Y, como en casi todo lo que hago, el proceso entero fue un experimento: con sus hipótesis, sus validaciones e invalidaciones, y mucha iteración. Probaba una manera de trabajar, miraba si funcionaba y ajustaba. Buena parte de lo que acabó funcionando no estaba en el plan inicial.

Del primer commit a tener el libro a la venta pasaron poco más de cuatro meses.

El giro: no quería otro manual

A las pocas semanas tuve que parar y decidir qué clase de libro quería que fuera.

Podía salir un manual de Lean correcto. Otro más. Y, sinceramente, ni me apetecía escribirlo ni creo que hiciera mucha falta. Así que cambié el rumbo: si iba a hacerlo, tenía que ser un libro con una tesis propia, aunque incomodara un poco.

La tesis es esta: el mayor problema de los equipos no es que escriban código malo, es que escriben código de más. Todo el software que existe cuesta, lo uses o no, igual que el cuerpo gasta energía solo por estar vivo. Si no gestionas ese coste, crece hasta ahogar la capacidad del equipo. Lo llamo el coste basal del software, y atraviesa el libro de principio a fin.

A partir de ahí dejó de ser "un libro sobre Lean" y pasó a ser un libro sobre algo más incómodo: por qué muchas veces lo más valioso que puedes hacer es construir menos.

Las conversaciones: porque uno solo no lo ve todo

Una tesis como esa no se sostiene solo con mi cabeza. Y hay una parte del proceso que no se ve en los posts: las conversaciones. Diecisiete entrevistas, repartidas en dos oleadas, con gente con la que he trabajado a lo largo de los años.

¿Por qué entrevistar si el libro recoge mi experiencia? Porque por mucho que reflexiones, tú solo no sacas puntos de vista distintos sobre un mismo tema. Te quedas encerrado en tu propia perspectiva. Necesitaba a personas que habían vivido lo mismo desde su sitio y lo contaban con sus palabras, a veces para confirmar lo que yo pensaba y a veces para discutírmelo. Quería que el libro tuviera más miradas que la mía.

La primera oleada arrancó en junio de 2025, cuando todavía publicaba la serie y el repositorio del libro ni existía. La segunda llegó a principios de 2026, ya con el libro en marcha. Muchas de esas voces acabaron dentro del libro. Se estaba cocinando mucho antes de que yo me diera cuenta de que estaba escribiendo un libro.

La parte que nadie cuenta: los papeles

Escribir es la parte bonita. Luego está la otra.

Cuando tuve el contenido cerrado y las imágenes más o menos resueltas, me di cuenta de la cantidad de decisiones que me quedaban por delante y de lo poco preparado que estaba para tomarlas: formato, modelos de distribución, tipos de papel, precios, registro de Propiedad Intelectual, ISBN, márgenes, tipografías, contraste de las imágenes. Todo eso había que decidirlo, y yo no había hecho nada parecido en mi vida.

La portada completa(contra, lomo y cubierta) sobre la plantilla.

Ahí tuve mucha suerte. Pude contar con dos personas que ya habían pasado por esto. Gerard Chiva, que tiene varios libros publicados en Amazon y un nivel de experiencia y de herramientas que es casi el de una editorial propia. Y Carlos Iglesias (de Runroom), autor de Impact-Driven Growth, que acababa de publicar el suyo y lo tenía todo reciente.

Que se prestaran a sentarse conmigo en una videollamada lo cambió todo. En lugar de ir decidiendo a ciegas, pude contrastar cada duda con alguien que ya había pasado por lo mismo antes que yo. Buena parte de los aciertos del libro, los que tienen que ver con cómo está hecho y no con lo que cuenta, salieron de esas dos conversaciones. Sin ellas habría llegado a algo bastante más torpe.

Una prueba del interior, con las marcas de corte.


A la venta

El 6 de junio de 2026 el libro estuvo disponible en Amazon, Kindle y tapa blanda a la vez. Lo anuncié ese día y al siguiente salió en redes.

Antes de publicar me había puesto unos números como objetivo, casi para tener una vara de medir honesta: 200 copias en los primeros seis meses, 300 en el primer año y que al menos el 60% fueran en papel y no en digital. Los escribí sin saber muy bien si eran ambiciosos o ingenuos.

A 22 de junio, dieciséis días después del lanzamiento, van 234 copias. El objetivo de seis meses se cumplió en las dos primeras semanas y ya estamos cerca del de doce. No me lo esperaba, y menos tan rápido. Que casi todo se vendiera en España lo daba por descontado; lo que sí me sorprendió fue el papel: el objetivo de mezcla se ha superado de largo, más del 80% de las copias son físicas.

Unidades por formato a 22 de junio: 185 en papel, 49 en digital.


Una segunda versión, esta misma semana

Y como el proceso no termina el día del lanzamiento: esta semana acabo de subir una nueva versión en papel.

Son cambios menores, todos para que se lea mejor: un margen interior algo más amplio (que el texto no se meta en el lomo), mejora de contraste en unas pocas imágenes y algún retoque suelto de maquetación. El contenido no cambia. Si ya tienes el libro, no te pierdes nada.

Me gusta que se pueda hacer esto. Detectas un detalle, lo corriges y lo subes. Muy en la línea de lo que defiende el propio libro: pasos pequeños, mejorar sobre lo que ya funciona.

Lo que me llevo

Si tuviera que quedarme con una idea del proceso es esta: un libro así no se escribe de una sentada, se cultiva. Dieciséis meses de escribir en abierto, diecisiete conversaciones, más de 180 correcciones llegadas de los revisores y cuatro meses de ensamblaje, con un puñado de personas echando una mano. Visto con perspectiva, el libro fue la consecuencia, no el objetivo.


Nota: durante todo esto fui dejando un rastro bastante completo de cómo lo hice: el flujo de trabajo, las herramientas, las plantillas de exportación, los scripts. Si veis interés, me planteo publicar un pequeño kit de autoedición (o, para quien le tire lo técnico, el tooling concreto que usé para escribir, maquetar y exportar el libro). Si os sería útil, decídmelo en comentarios o contactadme y lo preparo.

Sunday, June 14, 2026

Ya está publicado «Menos software, más impacto»

Después de meses de trabajo, ya está aquí mi primer libro: «Menos software, más impacto».


Va sobre desarrollo de software Lean. Sobre algo que llevo años viendo y que sigue costándonos asumir: muchas veces construir menos, quitar lo que sobra y mirar el impacto de verdad nos lleva más lejos que seguir añadiendo funcionalidad. He volcado ahí buena parte de lo que he aprendido en más de 25 años, con ejemplos de equipos y empresas reales por los que he pasado.

Y estos días están empezando a llegar las primeras copias físicas a sus lectores. Para alguien que se dedica a fabricar algo tan intangible como el software, verlo en papel hace una ilusión rara y bonita.

Lo tienes en tapa blanda y en Kindle (también en Kindle Unlimited): comprar en Amazon.

Monté además una web con los recursos por capítulo, gratis y abiertos, te leas el libro o no: recursos del libro.

Si lo lees y te aporta algo, una reseña honesta en Amazon ayuda muchísimo estas primeras semanas. Y si tienes cualquier comentario, me encantará leerlo.

Sunday, June 07, 2026

Keynote: Nuestra profesión no volverá a ser la misma. Y es una gran noticia. Commit Conf 26

El pasado viernes 5 de junio tuve el honor de abrir la Commit Conf 2026 en Madrid con la keynote inaugural. Arrancar a las nueve de la mañana, con la sala todavía desperezándose, impone. Y emociona todavía más. Commit es una de las conferencias técnicas más grandes de España, con un montón de comunidades detrás y más de mil personas pasando por allí, así que que me invitaran a abrirla fue un regalo.

Fueron solo 15 minutos. Condensar en un cuarto de hora una keynote de 45 que, para mí, ha sido la charla más importante que he dado (la di en la Software Crafters Barcelona 2025) tenía su miga: elegir tres o cuatro ideas que sostuvieran solas y soltar todo lo demás. Lo confieso: dar una charla corta cuesta bastante más que dar una larga.

El vídeo

Ya está disponible la grabación de la keynote. Puedes verla aquí mismo o directamente en YouTube:

La grabación es cortesía de Sirviendo Código (LinkedIn). ¡Mil gracias por capturar y compartir la charla!

Las slides

Aquí tienes la presentación. Si prefieres verla directamente, este es el enlace a las slides.

¿De qué va la charla?

La idea de fondo es fácil de decir y bastante más difícil de tragar:

El software nunca fue un fin, siempre fue un medio. La IA nos obliga, y nos da la oportunidad, de reinventar cómo lo creamos. La clave está en el desapego radical: soltar el código como identidad, las herramientas y los métodos rígidos, y quedarte apegado solo a lo que de verdad importa, que es resolver problemas y generar impacto.

A partir de ahí, la charla se apoya en cuatro ideas.

La primera: esto es una revolución, no una moda. No estamos ante otro blockchain, sino ante algo del calibre de la máquina de vapor, un cambio que va a reescribir nuestra profesión. Y si se va a reinventar sí o sí, la pregunta incómoda es: ¿quién quieres que lo haga? ¿McKinsey y las consultoras que miden productividad en líneas de código, o quienes llevamos años entendiendo de verdad la naturaleza del software? Lo veo como una responsabilidad, no como una amenaza.

La segunda es la frase que me gustaría que te llevaras a casa: la IA no acelera, multiplica. En el desierto, ese sitio sin tiempo, sin prácticas, lleno de silos y ansiedad, la IA multiplica el desastre. Más mierda, más rápido. En el bosque, donde hay excelencia técnica y testing y código que se entiende, multiplica el valor y abre un círculo virtuoso. Por primera vez hay un incentivo económico claro para hacer bien las cosas que la comunidad lleva una década predicando. Y eso me parece una noticia enorme.

La tercera tiene que ver con el desapego. Si el software es el medio y no el fin, la misión nunca fue codificar; era resolver problemas y cambiar lo que la gente hace. Toca vaciar la taza y desaprender, asumir que no eres tu código por muy bonito que te haya quedado, y aceptar que la habilidad que de verdad va a importar ya no es teclear, sino gestionar la complejidad. Construir va a salir casi gratis. Controlar lo construido será el verdadero reto.

Y la cuarta: la comunidad es quien mejor situada está para liderar todo esto. Porque la IA premia justo lo que Crafters, XP y Lean venimos defendiendo. Lo que toca ahora es experimentar en espacios seguros, codificar nuestro conocimiento en agentes y perderle el miedo a explorar sin certezas. Al fin y al cabo, la IA que ves hoy es la peor que verás en tu vida.

No quise venderlo como un cuento de hadas, así que dejé encima de la mesa una preocupación que me ronda: la escalera de aprendizaje de quien entra ahora en la profesión. Surfear la ola no es ignorar la corriente. Pero el fondo es esperanzador de verdad: no se trata de evitar la tormenta, sino de disfrutar surfeándola. Y prefiero hacerlo en comunidad.

Una versión concentrada de una charla más larga

Esta keynote es la destilación de "Desapego radical en la era de la IA: reinventar cómo hacemos software", la charla de 45 minutos que di en la Software Crafters Barcelona 2025. En 15 minutos se queda mucho en el tintero (Alan Kay y Xerox PARC, los cuellos de botella que se desplazan hacia producto, la escala de pereza del desarrollador, los agentes de comunidad...), así que si te quedas con ganas de más, ahí tienes la versión completa, con vídeo y todo, en este post.

Gracias

Gracias a la organización de Commit Conf por la invitación y por confiarme la apertura, y a todas las comunidades que hacen posible un evento así. Y gracias a quienes estuvisteis ahí a las nueve de la mañana: abrir con vosotros fue un lujo.

Si la charla te ha resonado, o si discrepas en algo, me encantará seguir la conversación: ¡escríbeme! Y si te llevas una sola cosa, que sea la pregunta con la que cierro siempre: ¿qué vas a experimentar mañana?

Nos vemos en la próxima.

Sunday, May 10, 2026

El libro está cerca: web de recursos y un Substack dedicado

Después de bastante tiempo trabajando en él, mi libro Menos software, más impacto está cerca de estar terminado. La edición en español está prevista para junio de 2026, y poco después saldrá la edición en inglés.

Mientras tanto, he preparado dos cosas:

Una web con recursos del libro, organizados por capítulos: menos-software.eferro.net. La iré ampliando a medida que el libro avance, con referencias, charlas, artículos y otros materiales que complementan cada capítulo.

Un Substack específico para el libro: menossoftware.substack.com. Lo he creado aparte a propósito, separado de eferro's Substack. La cadencia será muy baja por diseño: solo escribiré allí cuando haya algo concreto sobre el libro (publicación en Amazon, edición en inglés, extractos, errata, segunda edición). Si quieres enterarte cuando salga sin recibir nada más, suscribirte allí es la mejor opción.

Aquí en el blog y en eferro's Substack seguiré escribiendo sobre Lean, XP, construcción de equipos y cómo entregamos mejor software.

Gracias por acompañarme en este camino.

Artículo relacionado: El libro que llevo 25 años intentando escribir — la historia detrás del libro.

Enlaces:

Sunday, May 03, 2026

Good talks/podcasts (May I)

These are the best podcasts/talks I've seen/listened to recently: Reminder: All of these talks are interesting, even just listening to them.

You can explore all my recommended talks and podcasts on the interactive picks site, where you can filter by topic, speaker, and rating: Related:

Sunday, April 26, 2026

How I use Claude Code to maintain an Obsidian vault

Seven mental models had been sitting in my inbox for weeks. Rough captures I'd jotted down while reading and watching things online: a stub here, a link there, a sentence I wanted to come back to. I asked the agent to flesh them out into proper notes. It dropped each one in the right folder, got the tags right, updated the central index, and committed the batch with a sensible message. No broken links. All in one session, and I didn't touch a single file.

That sentence is easy to write and easy to misread. It sounds like magic, or like marketing copy, or like the kind of thing people say about AI before you try it yourself and it puts notes in the wrong folder and breaks half the links in your vault. So let me explain what actually made it work, because it wasn't the model. It was the scaffolding.

A previous post described the general system: markdown files on Dropbox, versioned with Git, an AI agent that operates on the vault. This one is about a narrower question the first post barely touched. How do you give an agent durable, specific knowledge of a vault it didn't create, so that it stays consistent across sessions, not just within one?

Rules as the agent's memory

Claude Code reads a set of rule files at the start of every session. They live in .claude/rules/ and load automatically. This is the part most write-ups about "AI plus Obsidian" skip. The rules are not a prompt I rewrite each time, and they're not a long system prompt I crafted once and forgot about. They are operational memory: stuff that persists between sessions and grows the more I use the agent.

The main file, obsidian.md, runs to a few hundred lines. It describes the PARA structure and where each type of content belongs, how wiki-links work, the format conventions for literature notes, evergreen notes, Maps of Content (MOCs), mental models. It also tells the agent which Python script to run in which situation and how to interpret the output. A second file, vault-management.md, is more operational: when to use find_broken_links.py versus fix_broken_links.py, what to do with a fuzzy match at 73% versus 91% confidence. A third, master-viu-presentaciones.md, covers the conventions for the master's program materials I teach.

None of these files is static. After every session where I learn something, I update the relevant one. Sometimes it's a convention I'd been applying inconsistently. Sometimes it's a pattern that worked better than what I had documented. Sometimes it's just a rule I'd been meaning to write down for weeks. The next session starts with that lesson already loaded, and the agent doesn't need to rediscover it.

This is what separates "I told the agent the rules" from "the rules live in the repo and improve with use." Most setups stop at the first. Getting an agent to write a note is trivial. Getting it to write a note that's consistent with 774 other notes it didn't write, and to keep it consistent over months, is what needs this kind of explicit, maintained context.

The zero broken links rule

The single most important rule in the vault is this one: if you're not certain a note exists, don't create the wiki-link. Use plain text instead.

A broken link in Obsidian isn't a 404. It's a ghost. The link renders, it shows up in the graph view, it looks like a connection. But click it and you're in an empty note. Broken links are promises the vault never kept. They make the graph misleading. They accumulate silently, each one suggesting knowledge that isn't there.

The rule is enforced two ways. In the agent's behavior: before writing [[SomeConcept]], Claude Code runs a Glob search to confirm the file exists. If it doesn't, it uses plain text. No exceptions. And in a Python script:

make find-broken-links

This runs after any session that involved creating or editing notes. It parses every .md file in the vault, extracts every [[wiki-link]], and checks that a file with that name exists. The output is a table. The acceptable result is zero.

There's a principle I keep coming back to here: you can't trust an agent's self-reporting on something like link integrity. The agent thinks it checked. The script actually checked. Both have to be in the loop.

The mechanical layer

Behind the agent there are 15 Python scripts wired together through a Makefile. They are the part of the system that doesn't improvise.

find_broken_links.py I've already described. Its companion, fix_broken_links.py, handles the cases where a broken link is a typo or a slightly different name of an existing note. It uses difflib for fuzzy matching, configurable threshold, interactive confirmation by default. --auto-apply --threshold 0.90 handles the obvious cases without asking; --dry-run shows what would change without touching anything. validate_frontmatter.py scans every note and checks that the YAML is valid, that title is present, and that tags is a list rather than a bare string. These drift surprisingly fast during fast note creation, and catching them at the script level keeps them from accumulating into a future cleanup job.

The principle behind the whole layer is the one above: the agent decides, the scripts verify and execute the repeatable mechanics. The agent says "I created seven notes." The script confirms whether the wiki-links between them resolve. Two different jobs, run by two different actors, with no overlap of trust.

The middle layer

Between rules (context for the agent) and scripts (mechanical operations), there is a third layer: skills. These are workflow protocols that combine agent judgment with script execution.

The vault has six. create-note creates a note with the right frontmatter, in the right PARA location, with the right tags. If something's missing it asks before guessing. fix-broken-links runs the detection script, applies the obvious fixes automatically, and surfaces the edge cases for me to decide. vault-health-check runs the full check-health suite and tells me what to fix and in what order.

The distinction I care about is this: a skill is not a prompt. A prompt runs once and the agent improvises the rest. A skill is a protocol. It's explicit about which tools to use, in which order, what to verify, and when to ask the human. The same skill runs the same way every time. That's what you want for maintenance work. Boring, repeatable reliability. Not novelty.



The pattern: friction → script → skill → rule

None of this was designed upfront. It evolved from use, and the evolution is visible in the commit history.

Each piece started as a friction. I'd notice I was making the same judgment call session after session, or hitting the same dull task by hand, or repeating a correction I'd already made. The first response was a script for the mechanical part. Then, when the script was being called the same way each time, a skill that wrapped the orchestration. Then, when the lesson was something the agent should always know, a line in the rules so the next session would start with it loaded.

The presentation materials for the master's program followed exactly this arc. After the third session I noticed I'd made the same mistakes twice: too many bullets per slide, explanatory content in visible slides instead of speaker notes, material that didn't fit the session dumped at the end of the main presentation. I spent an hour updating the rule file with what I'd learned. From session four onward, Claude Code applied those lessons automatically. I didn't have to remember them. The rules remembered them for me.

Every problem I solve ends up encoded in a rule, a script, or a skill. The next time the same problem turns up, the agent already knows the answer. The documentation I write once keeps working session after session, which is why this thing keeps getting more useful without me planning for it.

More tools, same scaffolding

The tools I lean on most share a shape: text in, text out, callable from a make target. That's what lets them attach to the loop without friction. The agent operates them like it edits a note. Each one adds a capability without changing how the system works.

  • Mermaid: diagrams written as .mmd files. The agent generates them, renders to PNG via mmdc, embeds the result in the note, and commits, all from a single make target. I use it for architecture sketches, process flows, the kind of thing I used to draw on a whiteboard and lose.

  • Marp: slide decks written in markdown with annotations, compiled to PDF and PowerPoint. I ask the agent to change a slide, it edits the .md, regenerates the PDF, and commits. The thing I value most is mundane: I can git diff between session 3 and session 7 of the same master's class.

  • Excalidraw: Obsidian stores its sketches as JSON inside regular .md files, so the agent edits them like any other text. Whiteboard-style diagrams that live next to the note that needs them, refined by prompt instead of by hand.

  • notebooklm-py: a client for the NotebookLM API. The agent passes a URL, a transcript, or a PDF and gets back topics, key points, and a structured summary. That's how external material lands in the vault with a consistent shape, without me writing every summary by hand.

  • yt-dlp: YouTube extraction. The vault uses it for talk-note metadata (title, channel, duration, captions), and also for downloading the video or the audio when I want a local copy of something I might lose access to.

  • markitdown: PDF and Word to markdown. It's how a paper or a slide deck someone shares ends up inside the vault as text the agent can read, summarise, and link to whatever else is already there.

The pattern repeats every time. If a tool speaks text and a Makefile target can wrap it, the agent inherits the capability. Adding a new one is a few lines of glue, not a rewrite.

What the agent doesn't do

The agent doesn't decide what's worth capturing. That judgment is still entirely mine. It doesn't surface connections I haven't thought of, at least not reliably enough to trust. It doesn't write the parts of notes that actually matter: the "applications in software" section of a mental model note, the personal reflection on why a talk changed how I think about something, the synthesis between two ideas I read six months apart.

What it does is remove the friction between having an idea and that idea being properly integrated into the vault. Before: I'd capture something in the inbox, know vaguely where it should go, not quite have the energy to do all the steps correctly, leave it in limbo. Now: the skill handles the scaffolding, I make the judgment calls, the note ends up in the right place with the right tags and no broken links.

The honest version is that the system requires active maintenance. If I'm lazy about updating the rules after learning something new, the next session starts with slightly worse context. The skills are only as good as the last time I refined them. The scripts catch what they're designed to catch. They are not magic.

But the direction is right. Each round makes the agent a bit more useful in this specific vault, and each round is cheap: a few lines of rules, a Makefile target, a refined skill. Unlike a one-off prompt, none of it evaporates when the session ends.

Where this leaves me

774 notes, 15 scripts, 33 Makefile targets, 6 skills, 3 rule files. Around 100 commits in the last two months, most of them from sessions where I was building something else and the vault maintenance happened as a side effect.

The test I use: after a week off, how long does it take me to pick up where I left off? With the previous system (no scripts, no rules, ad-hoc organization), reorienting took twenty or thirty minutes of reading through recent notes to figure out what was where. Now it's opening the vault, running make check-health, skimming recent commits. Five minutes.

Back to the question this post opened with: what makes Claude Code reliable in this specific vault? The short answer is that reliability doesn't come from the model. It comes from making conventions explicit. Rules the agent reads at the start of every session. Scripts that verify what the agent thinks it did. Skills that turn a vague instruction into a written protocol. The model fills in the parts that weren't worth automating. Everything else is documented, checked, and reused.

I've built this kind of thing in software teams: explicit conventions, automated checks, tools that hold on to what the team has figured out so new members don't start from zero. The dynamics are the same here. The agent is the new team member who read the onboarding docs, runs the checks before committing, and asks when something isn't covered. The documentation just happens to live in .claude/rules/.

Related reading