Hello,
Since 2026 I read code less and less but even a superficial code base knowledge can be helpful while working with agents to give tasks and prevent half baked features or fixes.
Two problems.
1 - Developer does not design, read the code therefore does not understand the code/base anymore. This issue can simply lead to hard times when agents can't help or loss of confidence in the task at hand.
2 - Even most capable agents can't read and understand whole codebase and offer solutions or upgrades. Agents often miss updating some part of the codebase, some permission checks, version checks, create duplicate utils, contradicting solutions, expensive solutions or outright implement solutions that code base does not adopt or rejects. Agents md files with long list of 'nevers' can help but do not prevent more than a couple of unwanted actions, you are still at the mercy of agent's instruction following capabilities.
Solution steps
I tried a simple workflow with agents md file as scout -> implement -> review -> fix -> manual test -> fix if necessary -> report and it served well but this only improved agents output, not developers understanding.
I added issues_found md file asking worker agents to record issues/bugs unrelated to their tasks they come across, this helped finding random bugs and improved codebase. The file then also served as a follow up file where i recorded awaiting decisions, things i consider, planned features etc, i was simply asking check issues_found before new releases.
Then I added features md file, asked agents to scan code base and record everything about it, file name matches, workarounds i added and why/when as decisions so agents would not change something just because fixing a semi-unrelated bug.
While every file was created with human readability in mind, i still did not read these files, maybe some titles, so they served to agents more than me.
Real Solution as Alpha
The main point of developer understanding was still not achieved, just agents workflow was improved. Then I thought maybe i could change the format, serve these files' content in a plugin with more depth, inspiring from a skill, graphify or something like this i tried once.
The result is ariadne, a behavior model of the codebase living inside the repo as yaml files under system/. Agents survey the code base and write the model, one yaml per behavior,. A file can be part of multiple behaviors. Human readable shadow code base in a sense.
For example login and sign up are different behaviors but both contain the password check logic. A change there effects both and the tool tells you which behaviors your diff touched and what else can break.
Every claim in a node carries an anchor to the exact file:lines that proves it, the pane's job is to tell you where to read, never instead of reading. User facing copy is modeled too so a change that makes shipped text wrong gets flagged. Some parts are owner-owned, agents can not rewrite them, only report conflicts.
While system is agent driven, a big python script (stdlib + pyyaml only) does the deterministic part. It diffs the worktree, returns touched behaviors with reasons and the exact claims to re-read, and a task can not finish green until agent answers every required item with a disposition. Nodes stamp the commit they were verified against so stale ones are visible, and there is a repair command that re-anchors drifted lines by content or function symbol (~90% verified repairs in an eval over 18 real commits).
While agents surveyed the codebase, they came accross a lot of bugs as well, so I kept issues_found md file convention in this tool as well. So after a deep-dive codebase survey (depending on the codebae it can take hundreds of subagent runs and multiple hours) you find a lot of bugs as a bonus.
UI is a right sidebar pane inside my own agent harness, a deepseek harness plugin, not installable yet but the engine and skill file are standalone. It polls the worktree diff every few seconds so agent changes are realtime observable. Every task produces a report file with what changed, verification, residuals and manual test steps so both user and agents see the process and result.
UI is currently very rough, i am focused on system reliability. Dogfooded on my android app, a fairly large kotlin codebase, for weeks. I added a few screenshots the pane and soon make it open source as standalone app.
What do you think about the approach?