Here's what my spec reviews looked like six months ago:
"In section 3, the paragraph that starts with 'The user must be logged in', specify what happens if the session expires while the form is being filled in. And in the security section, the constraint on tokens should be phrased as a requirement. Watch out for the paragraph right after it too, it still uses the old wording…"
That's what you have to write when you want to give AI feedback on a document. Dozens of lines like this whose only job is to say where to look, to point at a context.
Today, the same remark takes me five words: "and if the session expires?", left directly on the sentence concerned.
That's what notabene does. The AI adapts, not the other way around.
We already know how to work together
When several people work on the same document, nobody waited for AI to figure out how. You highlight a passage, you leave a word in the margin, someone replies, you resolve the thread. These gestures are thirty years old, everyone knows them, and there has never been any need to explain them to anyone.
With LLMs, all of that disappeared. All that's left is a text box.
And since the tool can only do that, we're the ones who adapted. We describe locations with sentences, we copy passages to remove doubt, we pile ten requests into a single message hoping they arrive intact. We added complexity to make up for an interface.
Like a lot of tools and machines in their early days, it's backwards. An AI meant to make our lives simpler should adapt to the way we work, not force us to learn a new one - especially when there's no good reason for it.
In my case, it's the spec
When I build a feature, I no longer write the code, I write the detailed specification. In effect, I've just changed languages.
It has become the step that matters most. The agent codes from my instructions. If they're clear enough, the result just comes out right the first time. If they're vague, it fills the gap on its own.
And it fills it well. That's the trap. A vague spec doesn't produce a visible error, it produces a decision nobody made.
Let's go back to the example. I write "the user must be logged in to access this page", and I say nothing about the session expiring in the middle of a form. The agent doesn't ask me the question. It picks a behavior, implements it cleanly, and I discover its choice at review - or worse, while testing.
So I reread. Seriously, line by line. And what follows applies to any document written four-handed with an AI, whether it's a spec, a scoping note or a contract.
Where it breaks down
I spot a problem on page 2, another on page 5, a third in a diagram on page 8. And to save time, I want my agent to handle all of it.
I open the terminal, and I have to spell everything out.
I can't simply write "this paragraph is vague". It doesn't know which one. I have to locate it: the page, the section, the sentence starting with a given word. Most of the time I end up copying the passage, to be sure.
It's long, and it's fragile. The more remarks I pile up, the less readable the whole thing is. The agent handles some of them, forgets one, misreads another. Then I spend fifteen minutes checking what it understood.
The problem doesn't come from it. It comes from the fact that I lose all the information when I switch windows. When I was reading, I knew exactly which paragraph I was talking about. In the terminal, I have to rebuild it with words. The prompt is a good interface for asking. It's a mediocre one for pointing.
The idea
Go back to the gestures we already know. Comment directly on the text, like in Word or Google Docs.
I select the passage, I write three words, I carry on reading. Nothing to locate, nothing to copy. The comment is anchored to the exact spot.
At the end, a single sentence to the agent: "address the comments."
It picks up each remark with its position. What I gain isn't typing time. It's no longer having to rebuild what I already had in front of me. And I didn't have to learn anything for that.
How it works
The tool generates a documentation site from Markdown files. Your specs, your docs, everything that lives in markdown. Classic .md and .mdx coexist, you can mix the two depending on the page.
You open the site locally and you read. When something's off, you select the text and you comment. It also works on a whole page, an image, or a Mermaid diagram. Each comment opens a thread: you reply, you put it on hold, you collaborate, you resolve. A page recaps what's still open.
Then you hand over to the agent. It reads the comments, edits the source files, and marks the threads as resolved.
Some fixes are quicker to make yourself than to explain. A pencil in the margin then opens the relevant block directly in the page. You edit either visually, like in a word processor, or in raw markdown when you'd rather see the syntax. You save, and it closes the comments your change answers along the way.
Everything is stored as JSON in your repo, with the rest of the code. Your colleagues annotate the same page as you, and their remarks arrive through git.
The full loop fits in a thirty-second demo on the repo: a comment left, the agent applying it, the diff I approve.
Checking what the agent did
We've all changed the way we write code. Almost nobody has changed the way they review it. And that's where quality is decided now.
An agent handles thirty comments in three minutes. On a spec, that's potentially thirty design decisions nobody validated.
Hence two safeguards.
A journal. Every pass by the agent leaves an entry on a dedicated page: what changed, why, and in response to which comments. The why matters most in three weeks, when you wonder where that odd constraint came from.
An "approve" mode. The agent prepares its changes instead of applying them. You validate them one by one, with the real git diff in front of you. Not a summary of what it thinks it did: the diff.
What's not in it
No online service, no account, no database. Everything lives in the repository. The day you stop using notabene, you delete a folder.
No server or MCP in the loop with the agent either. It reads files and it writes them, that's all. I added skills so it knows straight away how to use the tool, and any agent capable of reading a file can then do the work.
The write server only runs locally. The editor also refuses to modify a file that git doesn't track, because an unversioned change can't be recovered.
Local first, then public
It is, by the way, a real doc generator. Spaces, a table of contents driven by the frontmatter, full-text search, multilingual with per-language comments, light and dark themes, zoomable Mermaid diagrams, PDF export with bookmarks. You can make it your own: home page, logo, navigation links, fonts, and a set of CSS variables to pick up your brand.
But everything above happens on your side. You run the site on your machine, you annotate, the agent works. Nobody sees anything until you push.
When the docs are ready, the same command produces a static site to publish. That build is read-only and contains no editor, no write server, no comments. Your working annotations stay on your side. You can also mark pages as private: they don't go into the public build, and the linter warns you if a published link points to one of them.
The published site includes an llms.txt and a Markdown version of each page, so agents read it properly.
Built with AI, and improved by itself
notabene was itself largely developed with AI. Without the intensive use of agents, I would never have run into the problem the tool solves.
There's a second loop, one I care about more. notabene's documentation is written, reviewed and published with notabene. I write a feature's spec, I reread it in the browser, I comment, the agent applies, I approve the diffs. We code afterwards.
It's my best test. Every friction I hit while annotating becomes an issue. The project's journal is the history of its own fixes.
Who is it for?
If your specs are in Confluence or Notion, it won't be any use to you. notabene only reads versioned Markdown files.
If they're already in the repo, next to the code, installing it takes two minutes. It's a project that aims to be simple to set up and simple to run - the point isn't to weigh down the project it works in.
The code: github.com/z29k/notabene
The docs: z29k.github.io/notabene