I no longer read AI-written code line by line

The experiences here are abstracted. I can’t go into the specific implementation, so this is only about approach and lessons.

After leaving Black Lake, I spent a few months doing iOS development at a startup. In those months AI wrote most of the code; I wrote very little myself. What changed most wasn’t that I learned Swift, but how I write code.

I used to open VS Code after every change the AI made and compare the git diff side by side, line by line. I wrote commit messages myself too. It could eat up half a day. Now I barely look.

The premise: give AI more trust

Staring at git diffs all the time really says: I don’t quite trust what AI writes.

Look at it another way. You’re a product lead or a manager handing tasks to your team. You don’t sit next to someone watching every line they type; you explain clearly what needs doing, and at the end you check the whole feature they built.

Now AI is that team member. Its ability rivals a top PhD student; it knows a great deal and is smarter than most people. That being so, you can trust its work and put yourself in the manager’s seat: check from the feature’s point of view, without spending so long reading code details.

The cost of not trusting it is real: you get exhausted, and you’re slow. What AI writes in a minute, you spend half an hour reading line by line, and the bottleneck becomes you.

Trust doesn’t mean not caring, nor does it mean not understanding anything yourself (more on that in point 9). A manager still has to explain the task clearly, look at the results, and take responsibility for what ships. The small methods below all start from this premise: how to hand off a task clearly, how to check it, and what you still have to oversee yourself.

1. Discuss the plan first, then let it write

Before any code, talk the plan through with the AI: what to change, how, and what the risks are. If the plan is right, the code probably won’t stray; if the plan is wrong, no amount of careful diff reading will save it.

My order now: say clearly what I want → have the AI explain how it plans to do it → I pick holes → it gets to work → I skim the implementation.

2. Check by feature, not by reading line by line

When the AI is done, I first check whether the feature works: click through it, run it, look at the result. I only skim the implementation for obviously wrong turns.

Ask the AI for results, not “it’s done”: tests it ran, build output, screenshots. The Claude Code team works this way too. In a piece on how they review code, they say that before opening a PR they have Claude run tests and builds, or compare screenshots against the design, and then have a fresh agent review the change.¹ Anthropic’s official best practices also list “give Claude a check it can run itself” as one of the most important things.²

But watch out: passing tests doesn’t mean correct. Someone had AI rewrite SQLite; it compiled and passed all the tests, but looking up 100 rows by primary key was over 20,000 times slower than the original.³ So when checking, try performance and edge cases too.

3. Let AI write the commits

Have the AI write commit messages: a one-line title, a few bullet points, and at the end which agent and which model wrote it.

It saves time, and AI writes more thoroughly than people do. Later, when you want to know why something was changed, the commit has the reason.

4. Put a guide for AI in the repo

Put an AGENTS.md in the project root. It’s a format many AI coding tools recognise.⁴ Claude Code reads CLAUDE.md; write one line in it, @AGENTS.md, and both share the same file.

Write these:

• how to run tests, build and check;
• places in the code that mislead, like “don’t copy this old pattern”;
• decisions the team has made that you can’t see from the code;
• things you’ve already corrected the AI on twice.

These four come from Anthropic’s official best practices.² Don’t write what can be read from the code, like directory structure or dependency lists. Keep it short; the official advice is under 200 lines, because if it’s too long the AI misses the one rule that matters.²

One more line well worth adding: “When the docs and the code disagree, follow the code, and tell me where they disagree.” A paper tested Claude Code and Codex on 40 projects. According to its abstract, when instructions were stale and conflicted with the code, the AI followed the stale instructions 90 percent of the time; with that one sentence added, 90 percent followed the code instead.⁵

An example (for reference only)

Here’s one I wrote following the points above; the project name and commands are made up. It isn’t the best way to write it, just a starting point. When you write yours, cut and adapt it to your project, or have AI read your codebase and draft one, then trim it together.

# AGENTS.md

A React + TypeScript front end for factory reports. Reply to me in English.

## Common commands
- Install dependencies: pnpm install
- Run locally: pnpm dev
- Run a single test: pnpm vitest run path/to/file.test.ts
- Type check: pnpm tsc --noEmit
- Must run before handing off: pnpm lint && pnpm test; it's only done when all pass

## Conventions
- All requests go through src/api/client.ts; don't use fetch directly
- New pages use the function-component style under src/pages/; src/legacy/ is still in use, but don't copy its style
- If you change a function's parameters or return value, search for every caller and update them together

## Pitfalls
- Column widths in print templates are in characters, not pixels
- The test environment needs API_BASE_URL set first; see .env.example

## When you hit a problem
- First check docs/pitfalls/ for a similar problem
- If a problem took a long time to solve, or you hit a pitfall not recorded before, create a new note
  in docs/pitfalls/ yourself, with four parts: problem, cause, fix, and the mistake to avoid next time. Don't wait for me to remind you
- If the same problem fails to be fixed twice in a row, stop and tell me what you tried, why it failed, and what you think now

## Commits
- Commit messages: a one-line title plus a few bullet points
- Last line: Author: <agent name> Model: <model name>

## When docs and code disagree
- Follow the code, and list in your reply where they disagree

Open-source repos to look at

Text alone is a bit abstract, so here are three open-source repos you can open directly, from shortest to longest. This is how they looked on 2026-11-01; they may change.

• temporalio/sdk-java⁶ (Java, AGENTS.md about 60 lines): the plainest approach, basically an onboarding guide: what each directory is for, how to format, how to run all tests and a single test, what to put in commits and PRs, which checks to pass before submitting. Good to copy the structure from the first time you write one.
• astral-sh/uv⁷ (Rust, AGENTS.md about 50 lines): the whole thing is a list of rules, each starting with ALWAYS, NEVER, PREFER or AVOID, like “never assume a clippy warning or test failure was already there” and “don’t put our conversation in code comments or PR descriptions”. Short, but every rule was written after hitting a pitfall.
• tldraw/tldraw⁸ (React + TypeScript, AGENTS.md about 230 lines): closest to a front-end team, with the most complete structure, worth a careful look:
  • CLAUDE.md is just one line, @AGENTS.md, as described above;
  • it opens with a few core rules, like “only use pnpm; yarn will fail, and a hook already blocks it”: rules that must be followed aren’t just written in the guide but enforced with tooling;
  • it says clearly what each package does and where to go for each kind of change;
  • repetitive work like writing tests, writing docs, committing and opening PRs is each written as a skill in a skills/ directory, then linked for different tools like Claude and Cursor to share, rather than copied.

Among open-source repos, I didn’t find an example that keeps a separate directory of “pitfall notes” for AI to write into itself; tldraw distilling practices into skills is the closest. For pitfall notes, you can add your own, like the “When you hit a problem” section in the example above.

A few more places to start:

• The agents.md website: the format, which sections are recommended, and examples from several open-source projects⁴
• Search GitHub for path:AGENTS.md to see how tens of thousands of projects write theirs⁹
• Anthropic’s official best practices include a very short CLAUDE.md example, and what to include and leave out²

5. Record the pitfalls, and let AI record them itself

Every problem that took a long time to solve deserves a short note with just four parts: the initial problem, the real cause, the final fix, and the mistake to avoid next time. Put them in a directory like docs/pitfalls/, and tell the AI in AGENTS.md to read it first when debugging.

The key is letting AI record them itself, without a person reminding it each time. Write the rule into AGENTS.md, as in the example above: “If you hit a pitfall not recorded before, create a new note yourself.” Then next time it meets a similar problem, it checks its own earlier notes first.

On projects I’ve worked on, we built up over a hundred notes in a few months. Some call this “compound engineering”: write down what each task teaches you, read it before the next task starts, and experience accumulates bit by bit.¹⁰

Note that what AI records itself can be wrong or go stale. Every so often, have the AI check it against the code and delete what’s out of date.

6. Let AI remember what each file is responsible for

When I worked on the WPS add-in, I knew which file to fix when a given template broke. It was a map in my head. Now that map has to be handed to AI: write a line or two at the top of each file on what it’s responsible for and what its pitfalls are, plus the entry points in AGENTS.md.

No need to write “who calls this file, and what it calls”. That’s already in the code and AI will search for it itself; writing it in comments means keeping it in sync with every change, and the moment you forget, it’s wrong.

When you want to understand part of the codebase, just have AI explain it to you; it always reads the latest code. The Claude Code team says nobody on their team holds the whole codebase in their head; when they want to understand a part, they have Claude generate an explanation on the spot.¹

7. People handle the big things, AI handles the details

Not reading every line doesn’t mean not caring about anything. These still need a person’s judgement:

• whether a feature should be built;
• database changes and architectural changes;
• code where mistakes are expensive, like billing and permissions;
• what finally ships is a person’s responsibility.

The Claude Code team’s list of “what people still do” is similar: decide whether to build it, review risky code, do architecture reviews, check the evidence, take responsibility for what ships.¹ Small changes, details and boilerplate go to AI.

8. Stop when it keeps failing

If AI fails to fix the same problem twice in a row, don’t let it keep trying. Have it write down what it tried, why it failed and what it thinks now, then a person decides on a different direction. You can write this straight into AGENTS.md.

9. But don’t understand nothing: a problem I haven’t solved

So far I’ve been saying trust AI. This point is the other side. It’s a pitfall I fell into myself, and I still haven’t fully worked it out.

At first I thought I didn’t need to learn. When I started on iOS, I had Claude rewrite a web project as a native iOS app. It wrote it fast and well, and I was amazed. I thought: maybe I don’t need to learn all of Swift; know the rough structure and leave the details to AI? But I felt uneasy too: AI wrote too fast for me to keep up, and if I didn’t understand what each component did, AI was in control and I had no say.

Later I found I had no sense of control. Two or three months in, I still didn’t really understand SwiftUI, because AI had written all the code and I’d never built a mental model of the framework. When AI writes React, I feel confident, because I wrote React myself for two years: I know when the overall structure is right, styles rarely go badly wrong, and I only need to watch the API logic. Swift was different. I couldn’t judge whether what AI wrote was right, so I just fiddled. Whenever a hard problem came up and AI kept changing things for ages, getting it more and more wrong, I couldn’t see where the problem was either. Talking to it again felt like guesswork; I didn’t know how to put things so it wouldn’t misunderstand, and it was easy to feel defeated.

I tried to catch up, but it was hard to settle down to it. I followed a tutorial one lesson a day, starting from variables, and kept it up for a few days. When I didn’t understand something at work, I had AI fill in the knowledge and took notes. Once, near the end of the day, I built a little demo project myself and finally understood what a few properties actually did. I was so happy in that moment: “finally not poking at a black box”. A colleague also told me: forget the schedule for now, take it slowly, figure things out; you don’t have to go through a whole tutorial from the start, just learn what the project uses.

I understood all that, but actually settling down to it was hard. Learning on work time, I always felt pressure, thinking the features were waiting, a bit guilty and anxious. After work, I wanted to keep some room for my own life and didn’t want to touch work. Both were uncomfortable. That’s not anyone else’s fault; it’s more that I haven’t found the balance yet. Back at Black Lake, my manager gave me that kind of room to work things out slowly, and looking back I’m very grateful. AI has made writing code faster, but how to make time for myself to learn, I’m still figuring out.

Later I saw it’s not just me:

• Anthropic ran an experiment with 52 engineers, mostly junior, learning a new Python library: half used AI, half wrote it themselves. The AI group averaged 50 on a comprehension quiz afterwards, the self-written group 67, and the AI group wasn’t much faster either.¹¹
• In the same experiment, the difference came mostly from how people used AI: those who had AI write the code and fix bugs directly scored under 40 percent; those who asked “why is it written this way” after AI wrote it, or only asked about concepts and fixed errors themselves, scored much higher.¹¹
• Addy Osmani wrote about his own experience: he had Claude build a feature, the tests passed, he skimmed it and accepted it, and “three days later, I couldn’t explain how it worked.” He calls this “comprehension debt”.¹²

What I think now (not doing it yet, just what I want to try):

• Having a mental model of a framework is how you know where to look when problems come up; otherwise you end up passive. So however fast things go, I want to keep time for learning the framework itself.
• After AI writes something, ask one more question: “why is it written this way?”, “what does this property do?” For unfamiliar things, build a little demo and try it.
• When AI keeps failing to get it right, remind it to look up best practices and official docs for the problem online before changing anything. My sense is GPT needs this reminder more and Claude is a bit smarter; that’s just my impression.

This doesn’t contradict “trust AI” above: a manager doesn’t need to read every line their team writes, but the manager does need to understand the trade.

These are just my own feelings; some people don’t seem to have this problem. It’s neither good nor bad. Try it yourself.

In the end, all these methods come down to one thing: going from someone who writes and reads code to someone who hands off tasks and checks the results. If you only want to try one thing, I suggest starting with point 3: next time you commit, let AI write the commit message. Then try point 1: discuss the plan with it before it writes anything.

AI wrote this post, and you can absolutely have AI read it. More importantly, I wanted to record some of my understanding and share it with everyone.