Architectural Decision Records (ADRs) help human teams establish rules and carry context forward in software projects. They capture significant design choices, the context behind them, and the reasons they were made. Like many tools built for human software teams, ADRs work remarkably well for coding agents too.
\nAgents often arrive with little or no memory of yesterday and only a narrow view of a codebase. Even systems with persistent memory may preserve context without establishing whether it is accurate, current, or accepted by the human team. Decision records help them understand the intent behind the code rather than having to infer it. Keeping them in a project repository also spares agents from having to trawl through issues, search chats, and perform code archaeology. When intent is recorded explicitly, an agent is less likely to mistake an implementation detail for a foundational rule.
\nOnce a decision enters an agent’s context window, the agent may adhere to it even more rigidly than a human would. In my own work, I’ve seen agents fight tooth and nail to apply an accepted decision even when it is obsolete. In one case, an agent preserved an outdated storage abstraction across a new feature because an ADR still described it as mandatory. Instead of flagging the mismatch, it added another layer to keep the new requirement technically compatible with the old ruling.
\nThe first remedy is to give agents explicit permission to question decisions that no longer fit — and to watch for signs that they are overfitting. But that solves only half the problem. When you invite an agent to update a decision, a second tendency appears: preserving the deliberation. Every clarification becomes an amendment explaining its own existence at the expense of clarity. Small implementation details become rules, and cross-references acquire their own restatements and justifications. The result is overlitigated prose that is hard for humans to read.
\nADRs should absolutely be readable by humans, especially as we lean on agents to generate more and more code. To counter this, I’ve become explicit in my projects’ AGENTS.md files about how agents should apply and maintain ADRs. Here’s an excerpt from one:
\n\nArchitectural Decision Records (ADRs) are stored as Markdown files in the
\ndocs/decisionsdirectory. Treat accepted ADRs as binding. Proposed ADRs are non-binding context. Superseded ADRs are historical context and do not govern current work. If a given task conflicts with an accepted ADR, stop and discuss whether the task or ADR should change and propose the change that you think should be made. Propose new ADRs or updates to existing ones when a change introduces or revises a durable product or architectural decision.Keep ADRs succinct. Each ADR carries only its current text; Git history is its changelog, so do not add or maintain amendment logs in ADR headers. When substantively changing an accepted ADR, add or update a single
\nUpdated:date line afterDate:— its presence signals that history exists and Git has the details. A superseded ADR records aSuperseded-On:date instead ofUpdated:, matching theSupersedes:line on the ADR that replaced it. State each rule once in the ADR that owns it and cross-reference it from other ADRs instead of restating it.
These instructions are still evolving in my projects, and different projects will need different conventions. Some teams will prefer immutable ADRs that are superseded rather than revised; in my projects, I’m happy to have Git carry that history.
\nIf you do something similar, adapt the guidance to your own needs. The essential principle is that each governing ADR should describe the decision currently in force, with enough rationale to apply it. An agent doesn’t need the transcript of every argument. It needs the ruling that governs today and clear permission to stop when the ruling no longer fits.
\n", "date_published": "2026-09-01T00:00:00.000Z" }, { "id": "https://duncandavidson.com/a-home-for-personal-context", "url": "https://duncandavidson.com/a-home-for-personal-context", "title": "A home for personal context", "summary": "Every agent builds a model of you, and each vendor keeps that model inside its own walls. I’ve written an essay for O’Reilly Radar that argues for a user-controlled home for personal context, drawing five lessons from a year of working out of a Markdown vault.", "content_html": "Every agent I use is building a model of me. Claude has learned how I like my prose. ChatGPT remembers what I’m working on. I don’t mind this, but if I switch products, I have to start over. If I use three agents, each rebuilds from scratch what the others already know. Everything an agent learns lives with its vendor.
\nIt doesn’t need to be this way. What if every person had a canonical, user-controlled repository of context that any agent could request permission to use?
\nLast month I wrote about what a personal website becomes in the age of AI: canonical, public context for how the network understands you. This is the flip side of that thought. A website is where you teach the world who you are. But the richer context — your preferences, your projects, your history — is private, and right now it has no home of its own. It lives in fragments inside whichever agent you happen to have been using.
\nPlenty of people have started down this road by pointing agents at a pile of Markdown files; the best-known recent example is probably Karpathy’s LLM Wiki, elegant not just as a design but as a document. I’ve spent the past year working in a similar way, and it taught me five things a personal context system has to get right. It also led me to a bigger question: where should that context live? Not on which disk, but inside which trust boundary?
\nI’ve written about both in A Home for Personal Context, published on O’Reilly Radar. If we get the pattern right, changing agents won’t mean changing homes.
\n", "date_published": "2026-08-11T00:00:00.000Z" }, { "id": "https://duncandavidson.com/the-job-changed", "url": "https://duncandavidson.com/the-job-changed", "title": "The job changed", "summary": "The arrival of agentic engineering changed the shape of both Webflow and my role in it. After recognizing that my energy was being pulled elsewhere, I’ve decided to take a leap into the unknown: research, hacking on things, and possibly agitating for standards and protocols that help agents actually know the people they work for.", "content_html": "Last week was my last week at Webflow. This week, I’m heading off in a new direction.
\nI’d started at Webflow last December because it had amazing people working on a good product. My job was to establish a Platform Engineering group to get the company ready for the scale and scrutiny its next chapter looked like it would demand.
\nJust as I started, agentic engineering really arrived with a roar. I knew the moment was coming. The whole year had been building up to it, but something gelled in the industry at the end of the year, and by January the effect was unmistakable. Model release after model release, alongside constant updates to the agentic harness we’re all using now.
\nI can’t really point to a single day the job changed. Change came on an accelerating gradient. The arc of where Webflow was heading had shifted, and by April it was more than obvious to me. The restructuring announced in May made it public.
\nTo be clear, I like where Webflow is going. What Webflow had built was an incredibly valuable abstraction that tamed HTML, JavaScript, and CSS into a visual designer that was actually usable. Now, agentic engineering has reached the point where that abstraction is no longer necessary. Webflow is rearchitecting around the source code of a site itself. It’s heady, challenging, exciting stuff.
\nAs the spring turned towards summer, however, something else became clear. I went to Foo Camp in Berkeley, where I spent three days talking deeply with amazing friends, old and new, about AI and personal context, and how these tools can actually benefit the humans using them. And I got so much energy from it that I had to pay attention.
\nI’ve learned to trust myself when a problem pulls me in. Every time I’ve followed that pull, it has been exactly what I should be doing at that moment. And, to be honest, the smaller, leaner Webflow team doesn’t need three Vice Presidents of Engineering. Sometimes there are too many people in the room, and the right move is to be the one who leaves. Especially when something else is pulling.
\nSo, as compelling as the work at Webflow has been, I’ve decided to take a leap into the unknown to do some research, hack on some things, and possibly agitate for standards and protocols to help agents actually know the people they work for.
\nThis is a moment for builders. May we all find amazing things to build. 🚀
\n", "date_published": "2026-08-10T00:00:00.000Z" }, { "id": "https://duncandavidson.com/personal-websites-in-the-age-of-ai", "url": "https://duncandavidson.com/personal-websites-in-the-age-of-ai", "title": "What is a personal website in the age of AI?", "summary": "Personal websites have moved from homesteads, to publications, to social-profile pointers. AI changes the reader again: assistants need durable identity, provenance, citation, context, and clear surfaces they can understand without hallucinating a platform-shaped version of you.", "content_html": "In the very early web, readers wandered from link to link. A homepage was like a plot of land on the digital frontier. You represented who you were, and what you wanted to be, through links, pages, colors, guestbooks, blogrolls, photos, lists, and hand-rolled HTML. It was a place where you said, “Here’s who I am.”
\nWith the advent of weblogs and RSS, the personal website became a publication: something that could move outward without surrendering its source. Our sites became less like places to visit and more like streams of chronological content. Instead of asking people to remember to come back, you gave them a feed. The personal site became where you said, “Here’s what I publish.”
\nI’d argue that this was the golden age of the web, even if it was never the easiest place for non-technical people to participate.
\nThen the walled gardens of social networks emerged. Readers became followers inside someone else’s system. Platforms bundled identity, distribution, feedback, and audience into one place, while algorithmic feeds replaced other forms of discovery. It became easier to share online, and more people did so than ever before — including people who weren’t technical. As a result, many of us who had websites kept them, but they became pointers to where we lived on the social web. Maybe the most important use of a personal website became simply saying, “Here’s where else you can find me.”
\nFor many people, doing anything more started to feel less practical than nostalgic. They lacked the intense network effects that social networks provided and became lonely infrastructure in contrast.
\nI felt this myself. I blew up my own site and rebooted it repeatedly, each time trying to figure out what a personal website was supposed to mean now. Was it an archive? A portfolio? A pointer to social profiles? A place for half-finished thoughts? I never stopped believing in it, but for a long time I could not quite explain — even to myself — what it was for.
\nNothing on the web remains static for long, however. The wheel turns again, this time driven by AI. Agents are starting to change the role of discovery online. They do not just find pages. They summarize, compare, cite, recommend, and make connections between sites, concepts, and people.
\nA personal website in the age of AI is not only your digital homestead and a place to publish your work, but also a place to teach the network how it should think of you. We are back to the personal website as a place where you can say, “Here’s who I am, and here’s how you can understand me.”
\nThe virtues of the old web are now more important than ever. Everything that the social web encouraged us to walk away from — stable URLs, clearly written content, exposed feeds, and metadata — is suddenly more useful than it has been in a very long time. The people who kept publishing on their own domains, tending their archives, and making their work available in plain old HTML were not merely being nostalgic. They were preserving the parts of the web that still make the most sense when the reader is a machine as well as a person.
\nFor those of us who abandoned or otherwise lost touch with why we made personal websites, I believe that it is time to rebuild them with a clear eye on what is needed now. We should not just be recreating the aughts with better typography. We need to learn from what MCP Apps are making explicit for software meant to appear inside agent conversations and what ora is measuring for business sites: agents need surfaces they can find, understand, cite, act on, and hand back to a person without losing context.
\nFor a personal site, this means durable identity, citation, context, authorship, provenance, contact boundaries, and a place where assistants can recover what we actually said instead of hallucinating a LinkedIn-shaped version of it. It also means that we shouldn’t treat people, search, and agents as one reader. A human reader wants texture, taste, surprise, and trust. A search engine wants indexable relevance. An AI assistant wants retrievable chunks, provenance, and disambiguation. Those needs overlap, but they also conflict. And this will take time to figure out.
\nOf course, publishing canonical context does not mean the agents on the network will honor it. AI systems will still infer, compress, rank, and sometimes ignore what we say about ourselves. Nonetheless, a personal website is a durable source of truth that can provide signal in an otherwise noisy environment that increasingly manufactures summaries from fragments. Furthermore, personal sites matter even when they aren’t directly cited because they can influence the retrieval indexes, entity graphs, citations, and future corpora that AI systems draw from.
\n", "date_published": "2026-07-04T00:00:00.000Z" } ] }