Hey, what's up? It's Takuya here.
This week, I restructured my app's monorepo so that my coding agents copy good patterns instead of bad ones. Along the way, about 55 bugs turned up and got fixed, and all of them were written by me, by hand.
In this article, I'd like to share what inspired me, what I changed, and what I learned about working with agents.
TL;DR #
- My agents kept taking the nearest fix, and writing more rules for them didn't help.
- The codebase is the agent's memory: agents copy whatever pattern is already there.
- Directory structure is context, so I grouped the code by feature and made lint enforce the boundaries.
- I had been blindly following existing patterns too, just like agents do.
- Strict lint rules stop bad patterns before I review them.
- Writing tests before the lint fixes found about 55 bugs, all written by me, by hand.
- Building high trust with agents is the new engineering work.
The monorepo keeps every app on the latest modules #
In the last article, I moved 39 repositories into a monorepo to boost my agentic coding. It has been working pretty well so far.
I usually focus on one app at a time, like the desktop app or the mobile app. So when I switched to another app, I always found a lot of stale module versions that I had to upgrade. That was annoying. Now, when I update a module, my agent updates the other apps in the same change. The monorepo works as a restriction that forces every app to stay up to date, which is great.
It also aligned my toolchain with the common tools, like Oxlint instead of ESLint and Vitest instead of Jest. With everything in one place, I found more outdated setups and strange mismatches between the packages.
My agents kept taking the nearest fix, and more rules didn't help #
Still, reviewing the code that AI generated was taking a lot of my time. My agents kept making the same missteps. They inserted comments justifying their changes, which were boring and useless. They often patched the wrong files just to reach the goal. In other words, they went with local minimum solutions instead of thinking broadly over the whole project structure.
I tried writing more rules for my agents, but it didn't solve these issues. I didn't know what else to do.
The codebase is the agent's memory #
Then, this week, I watched a talk by Lauren Tan (poteto): All Code is Slop Except Mine. What a spicy title. It was so insightful, and it gave me so many ideas to improve my repository. She said she shipped 3,000 pull requests to production in a month. I don't know if I can reach that level, but I was sure her ideas would help with my problems.
Her key point is that your codebase is one of the largest inputs for agents, so it works as their memory. If the codebase has a bad pattern, the next agent will replicate it, because it looks like the established pattern. Code arrives so fast now that it grows like something organic, and she calls this "organic architecture". I totally agree with her.
So, whenever you correct your agent, she suggests making it a deterministic check, like a lint rule, instead of adding another line to your rules or your AGENTS.md.
By the way, last week, I got Claude Ultra free for six months from Anthropic's Claude for Open Source program, thanks to my OSS activity. It let me fully use Fable instead of Opus without worrying about the token allowance. It was the perfect timing to try her principles.
Directory structure is context, so I grouped the code by feature #
First, I restructured the directories, because directory structure is a form of context. I myself read a directory name as the scope or the role of the code in it, so I have no doubt that AI agents read it that way, too. Her principle is to group code by features and layers. Categories like "utils" or "modules" are bad groupings.
I fixed two things. First, who may import what:
The main process and the renderer can no longer import each other, and lint reports it if they do. Every IPC channel is now typed against a shared contract, and only the main process writes the config file.
Second, the layout of the desktop app. Before, the code was grouped by kind:
apps/desktop/src
โโโ browser/
โ โโโ actions/
โ โโโ reducers/
โ โโโ components/ 330 files, flat
โ โ โโโ activity-dot-chart.tsx
โ โ โโโ activity-streaks.tsx
โ โ โโโ ai-provider-settings-segment.tsx
โ โ โโโ app-container.tsx
โ โ โโโ ...
โ โโโ utils/ 54 files of mixed scope
โ โโโ editor/
โ โโโ telescope/
โ โโโ ... commands registered in 48 files
โโโ main/
โ โโโ account.ts
โ โโโ data-store.ts
โ โโโ session.ts
โ โโโ utils/ 29 files
โ โโโ ...
โโโ shared/
After, it's grouped by feature:
apps/desktop/src
โโโ renderer/
โ โโโ features/
โ โ โโโ ai/
โ โ โโโ auth/
โ โ โโโ editor/
โ โ โโโ note-list/
โ โ โโโ telescope/
โ โ โ โโโ index.ts the only entry point
โ โ โ โโโ components/
โ โ โ โโโ actions.ts
โ โ โ โโโ reducer.ts
โ โ โ โโโ command-handlers.ts
โ โ โโโ ... 15 features
โ โโโ components/ UI shared by features
โ โโโ commands/ every command is registered here
โ โโโ utils/ 5 domain-free helpers
โโโ main/
โ โโโ ai/
โ โโโ auth/
โ โโโ database/
โ โโโ export/
โ โโโ ipc/
โ โโโ windows/
โ โโโ ...
โโโ shared/
โโโ ipc/ one typed contract per channel
Each feature folder holds its components, hooks, actions, reducer, command handlers and tests, and the rest of the app imports it only through its index.ts. I did the same on the mobile app and the web editor, so the three apps share one shape.
While restructuring, I found many illegal imports that crossed the boundaries. This was a bad pattern I had made, and now it's fixed. The structure is also easier for me to understand. Agents write massive amounts of code rapidly, and it's hard to keep track of it. Now, I can quickly find where to look when I review. My apps have a lot of IPC, between the main process and the renderer, and between the host app and the web view, which is complicated. With the feature folders, I no longer have to look here and there and miss the point.
I was blindly following the existing patterns, just like agents do #
While working on it, I realized that I had been working just like my agents. I don't know if that's a good thing or a bad thing.
When I started Inkdrop, I forked the Atom editor, so I already had a bunch of code and files. It was the first time I built an Electron app, and I didn't know the patterns. So I blindly followed Atom's directory structure and coding patterns, assuming they were the best practices. That worked pretty well, and I replicated so many patterns from it.
But as the app grew, those patterns no longer fit its architecture and feature set. One directory ended up with hundreds of flat files, many of them with the -utils suffix. That hid the scope and the role of the code, for me and for agents too.
I did with Atom's code exactly what my agents do with mine: I followed whatever pattern was already there, without asking whether it still fit. Now I understand why agents work this way, because I did the same. And it was time to update my own principles for designing a codebase. I'm glad I learned that from this work.
Strict lint rules stop bad patterns before I review them #
Strict lint rules are one of the crucial guardrails for agents, because they prohibit bad patterns deterministically.
I personally trust the taste of Christoph Nakazawa, the creator of Jest, Yarn and Metro, who has been producing great output and contributing to projects at VoidZero. He recently published a new version of his oxlint config, @nkzw/oxlint-config. It's aimed at anti-slop: its rules are strict, so agents can't make silly mistakes, and it also cares about performance.
Adopting it required a lot of changes, and I haven't finished yet. It reported 11,589 findings in 2,422 files at the start:
But it already paid off a lot. rules-of-hooks alone found 18 real bugs, like hooks called after an early return or inside a loop. These rules forced me and my agents to revisit the current design and flow.
Writing tests for the lint fixes found the most bugs #
Refactoring business logic with agents to satisfy new lint rules made me worried about regressions, since I can't fully trust them yet.
I hadn't been writing unit tests except for the critical parts, like the data store and authentication, simply because it was economically impossible for a solo developer like me. But now, agents write code instead of me at a drastically fast speed. It's almost like managing a team at a company, back in the before-AI era. This scale can't be managed without thorough unit tests for every module, including the UI components.
For example, react-hooks/exhaustive-deps requires every dependency of a useEffect to be listed. Adding one changes when the effect runs, so before each fix, my agents wrote component tests against the old code. None of these projects had component tests before:
| Project | Component tests added |
|---|---|
| uikit | 385 |
| mobile web editor | 625 |
| desktop | 764 |
| mobile | 852 |
Writing those tests found far more bugs than the rule itself. About 55 are fixed so far, each with a test that failed first. For example, the editor's search bar subscribed on every effect run and never unsubscribed, so a single "find next" jumped over several matches. These bugs were all written by me, by hand.
I expect this work to find more bugs before it's finished: 13 bugs on mobile are already pinned by tests and waiting for fixes. It feels good.
Mass changes with agents came with their own traps #
Not everything went smoothly, though.
- The automatic fixers are not always safe.
catch-error-namerenamed{ cause }to{ error },prefer-node-protocolwould have broken thecryptoalias in React Native, andno-varrewrotedeclare varin a.d.tsfile. - Mass moves conflict with open branches. Merging
maininto the lint branch after the directory moves gave me 145 conflicts. - Require cycles on mobile. Exporting a feature's Redux state from its
index.tsmade the Redux roots load the components, which import the roots back: ten new cycles at launch. I fixed it with a second public file per feature,state.ts. - Verification lags behind the code. I haven't made a packaged desktop build since the move yet, CI hasn't run the moved tests, and Windows, Linux and the account flows are still unchecked.
Building high trust with agents is the new engineering work #
poteto said in another talk: "It's not really a secret. It's a lot of hard work." That held for me. The new structure and boundaries made my codebase something I'm happy for an agent to copy, and the stricter lint rules turned out to be a bug finder, because they forced tests into code that never had any.
I learned that I should doubt my codebase and my lint rules before adding another rule for my agents. As a next step, I'm eager to add more runtime verification.
I think the engineering task for us humans has changed: from improving code by hand to building high trust with agents through tools and design. If your agents keep making the same mistakes, I hope this helps you look at your codebase first.
That's it! Thanks for reading.