AI lets you ship faster than ever. That’s great. But six months later, you’re staring at your own codebase wondering who wrote this. Why is this service doing that? Why did you pick this library over the obvious one? What were you thinking?

The problem usually isn’t the code. It’s that AI accelerates the building without capturing the thinking. You evaluate options, make tradeoffs, reject approaches, and move on. The decision happens in a chat window and then it’s gone. What’s left is code without context, and that debt (a form of cognitive debt) compounds quietly until it becomes a real problem.

Though it might help, the best fix isn’t to slow down. It’s to build a few lightweight documentation habits that will hold up in an AI-assisted workflow.

The new documentation problem

Traditional documentation advice assumes you understand everything you’re writing. You wrote the code, you know why it works the way it does, you just need to write it down. AI-assisted development changes that assumption in a couple of ways.

First, you move faster. When you’re evaluating three AI-generated implementations in ten minutes instead of writing one over an hour, there’s almost no natural pause where documentation feels like the obvious next step. The decision-making is compressed, and so is the documentation.

Second, git history gets less useful. It still tells you what changed, but it doesn’t tell you that you picked this background job library because the other one had a deployment constraint you needed to avoid. It doesn’t tell you which of four Stripe webhook implementations the AI suggested, or why you picked that one. It doesn’t tell you that you almost went a completely different direction.

The gap is context. And that’s exactly what these habits are designed to capture.

Document decisions, not implementations

The highest-leverage documentation habit is writing down why, not what. Code already shows what. What it can’t show is the thinking that produced it.

Keep a docs/decisions.md file. No formal template required. No ADR ceremony. Just a running list of decisions, what options you considered, what you ruled out and why, and what you landed on. A few sentences per decision is enough.

Some examples of the kind of thing worth capturing:

• Why you chose Sidekiq over Solid Queue (maybe it was a deployment constraint, maybe it was familiarity, maybe you tried Solid Queue and hit a weird edge case)
• Which Stripe webhook implementation you kept after the AI suggested three different approaches
• Why the data model is shaped the way it is instead of the more obvious structure you considered first

This is especially useful in AI-assisted work because the evaluation often happens fast. You look at a few options, pick one, and move on. Without a quick note somewhere, that reasoning is gone the moment you close the chat.

The daily scratchpad

A scratchpad is not a journal. It’s not a changelog. It’s a place to think out loud while you’re working.

Drop a file at tmp/scratch.md (some people call it journal.md or dev-journal.md) and use it to capture rationale in the moment. What did you try? What didn’t work? How did you arrive at this solution? What were you unsure about?

It doesn’t need to be clean. It doesn’t need to be organized. It just needs to exist.

Git history will tell future you that something changed on a Tuesday in March. The scratchpad will tell future you that you were choosing between two approaches, that one of them had a subtle concurrency problem you figured out mid-afternoon, and that the solution you landed on was a compromise you felt okay about. That’s the stuff that can really help when you return to a project three months later and can’t quite remember what you were even trying to do.

Let AI explain what it built

Sometimes you ship code you don’t fully understand yet. That’s not a great position to be in, but it’s a real one, especially when you’re learning a new language or framework alongside building something.

When that happens, ask the AI to explain what it just built.

Recently I was building a new SaaS product in Elixir while still actively learning the language. The initial architecture involved OTP supervision trees, GenServers, and some patterns that weren’t immediately obvious (to me). Rather than hoping the understanding would come later, asking the AI to write an explainer.md for the architecture made the whole thing legible. Later, an explainer.html with diagrams and a walkthrough made it even better.

You can do the same thing with an existing codebase you’re jumping into for the first time. Drop the relevant files into context and ask for an explainer. It’s faster than reverse-engineering the code yourself, and it gives you something you can update and refer back to as your understanding deepens.

My explainers live in docs/explainers/. They’re not precious documents. They can be rough, they can be wrong in places, and they should be updated as you learn more. But having them at all is the difference between a codebase that feels like yours and one that always feels a little foreign.

Keep your README human

AI tooling has introduced a temptation to stuff READMEs with prompts, agent instructions, and notes about which parts were AI-generated. Resist it.

The README is for humans. What is this project? How do I get it running? Where is the rest of the documentation? How do I contribute?

AI-specific context belongs elsewhere. Agent instructions and project rules for your AI assistant go in AGENTS.md (if you use Claude, a CLAUDE.md symlink pointing to it is handy). Plans and specs go in docs/plans/ and docs/specs/. Decisions go in docs/decisions.md. Explainers go in docs/explainers/.

The README is the front door. Keep it welcoming and keep it human.

Own the code, all of it

You don’t need to mark which lines an AI wrote.

I know that might feel counterintuitive. There’s a reasonable instinct to be transparent about your process. But there’s a difference between transparency and hedging. Marking code as AI-generated is a subtle way of distancing yourself from it, as if to say: if this breaks, that’s not entirely on me. But that’s not how accountability works.

You are responsible for every line of code you ship, regardless of how it was produced. If you don’t understand the code, you shouldn’t ship it. If you’re not sure you understand it, that’s what explainers are for.

The middle ground is being transparent about your development process at a high level. It’s no secret that most developers use AI assistance now, and saying so in your docs or your README is great. That’s transparency. What’s different is using it as a hedge. The tool you used to write the code doesn’t change your responsibility for the result.

The loop

Good documentation helps you understand your codebase. Understanding your codebase means you can give the AI better context when you’re building something new. Better context (human and AI) produces code that really fits the existing architecture. Code that fits is easier to explain and document. Round and round.

None of these habits are heavy. A few sentences in decisions.md. A rough note in scratch.md. An explainer file when you’re in unfamiliar territory. A README that stays focused on humans.

The payoff is that six months from now, when you come back to this project, it feels like yours. You remember what you were thinking. You know why things are the way they are. And you can keep building without spending the first week just figuring out what past-you was up to.

Bonus: automate it with a post-merge hook

All of these habits share a common enemy: you have to remember to do them. Remembering is fine when you’re focused, but documentation is usually the thing that slips when you’re rushing to ship.

Here’s a way to take the remembering out of it. A git post-merge hook fires automatically after every merge. You can use it to shell out to Claude Code in non-interactive mode and ask it to review and update your docs in light of what just changed.

The hook grabs the merge diff, hands it to Claude along with a focused prompt, and lets Claude update README.md, docs/decisions.md, any relevant explainers, and product docs. Changes are left unstaged so you can review them before committing. Nothing gets force-pushed. Nothing gets auto-committed. You stay in control.

Here’s the script:

#!/usr/bin/env bash
#
# .git/hooks/post-merge
#
# After merging to main, asks Claude Code to review and update documentation.
# Changes are left unstaged for your review.
#
# Setup:
#   cp post-merge .git/hooks/post-merge
#   chmod +x .git/hooks/post-merge
#
# Requires Claude Code CLI to be installed and authenticated.

set -euo pipefail

# Only run on main branch
CURRENT_BRANCH=$(git symbolic-ref --short HEAD)
if [ "$CURRENT_BRANCH" != "main" ]; then
  exit 0
fi

echo "📝 Checking documentation after merge to main..."

# Capture what changed in the merge so Claude has context
DIFF=$(git diff ORIG_HEAD..HEAD --stat)

# Build the prompt
PROMPT="A feature branch was just merged to main. Here is a summary of what changed:

$DIFF

Please review the following documentation and update anything that is out of date
or missing given the changes above:

- README.md
- docs/decisions.md (add an entry if a significant architectural decision was made)
- Any relevant files in docs/explainers/
- Any relevant product documentation in docs/

Do not modify AGENTS.md or any files in docs/plans/ or docs/specs/.

After making changes, print a brief summary of what you updated and why.
If nothing needed updating, say so."

# Run Claude Code in non-interactive mode with read/write permissions only
claude -p "$PROMPT" \
  --allowedTools "Read" "Write" "Glob" "Grep" \
  --max-turns 10

# Show which files were changed (if any)
DOC_CHANGES=$(git diff --name-only -- README.md 'docs/**' 2>/dev/null || true)

if [ -n "$DOC_CHANGES" ]; then
  echo ""
  echo "✅ Documentation updated. Review changes before committing:"
  echo "$DOC_CHANGES" | sed 's/^/   /'
  echo ""
  echo "   Run 'git diff' to review, then 'git add' and 'git commit' when ready."
else
  echo "✅ No documentation changes were necessary."
fi

Download here: post-merge

To install it, copy the script to .git/hooks/post-merge and make it executable with chmod +x .git/hooks/post-merge. Since .git/ isn’t tracked by git, you might want to keep the canonical copy in a hooks/ directory in your repo and add a setup step to your README.

A few things worth noting about the script:

The --allowedTools flag scopes Claude to read and write only. It can’t run arbitrary bash commands, can’t touch your git history, and can’t do anything outside the files you’ve pointed it at. Keeping the tool surface small is good hygiene for any automated Claude Code invocation.

The --max-turns 10 flag is a circuit breaker. It caps how many agentic turns Claude can take so a single post-merge hook can’t spin forever if something unexpected happens.

The prompt explicitly excludes AGENTS.md, docs/plans/, and docs/specs/. You don’t want a merge hook rewriting your agent instructions or your design plans. Keep the scope tight.

The --max-turns flag is a circuit breaker, but may need to be tuned based on how much the amount of work that needs to be done. If the circuit breaker is hit, the hook will exit with an error and leave the finished changes unstaged for manual review.

This is a starting point, not a finished product. Your project’s doc structure will differ, and you’ll want to tune the prompt to match. But the pattern holds: capture the diff, give Claude focused scope, leave changes unstaged, and let the human decide what to commit.

A few days ago I built a tool called JoyConf: a real-time audience feedback system that lets speakers see emoji reactions floating up in the corner of their presentation while they’re talking. It was a fun, simple idea and I was pretty excited about it.

I built it in Elixir and Phoenix LiveView, which was a deliberate choice. I mostly write Ruby these days, but this project felt like a good excuse to dig into Elixir and LiveView. Learn something new, build something useful. Two birds, one stone.

I drove the overall design and implementation planning, did active code review, and contributed everywhere I could. But for the Elixir and LiveView specifics, I leaned heavily on Claude. The syntax, architecture decisions, and debugging were Claude’s domain, because I simply didn’t know enough yet to own them. The tool worked and it seemed to work well. But when I got to the end and looked at the codebase, I realized I didn’t really understand the parts Claude had built. I had reviewed the code as carefully as I could, but reviewing code in a language you don’t know, implementing an unfamiliar architecture, only gets you so far. The understanding of those pieces had mostly stayed with Claude.

That’s cognitive debt. And LLMs are very good at generating it.

What cognitive debt actually is

Cognitive debt accumulates when you defer the thinking that should happen now. It’s different from technical debt, which is about the code itself (shortcuts taken, tests skipped, abstractions that didn’t quite work out). Cognitive debt is about the reasoning that never happened. The mental model that never got built. The decision that got made without being understood.

Like financial debt, it doesn’t feel like much at first. You’re moving fast, things are working, you’re shipping. The bill comes later, when you need to debug something you can’t reason about, extend a system you don’t understand, or explain a decision you never actually made. And to be clear, cognitive debt has been around long before LLMs, LLMs just magnify the problem.

LLMs make this disturbingly easy

LLM-generated code is mostly right. That’s what makes it dangerous.

If the code were obviously wrong, you’d catch it. You’d dig in, figure out what went wrong, learn something in the process. But LLM output is usually plausible, often correct, and just coherent enough that it passes the vibe check. You run the tests. They pass. You move on. The mental model of how it works never gets built, because you never needed it… until you do.

There’s a specific failure mode worth naming here. Using an LLM to move faster on things you understand is leverage. Using it to skip understanding altogether is debt. Those feel identical in the short term. Both result in code getting written. One leaves you with understanding you can build on; the other leaves you with output you’re stuck with.

And it catches everyone. Junior developers accept LLM output because they don’t know enough to question it. Senior developers accept it because they had a hundred PRs today and the code looks fine, so they assume it is fine. Both skip the reasoning step. The result is a codebase full of decisions nobody on the team can actually defend.

Back to JoyConf

When I realized I’d built something I didn’t fully understand, I asked Claude to write me an explainer document. Not a summary, but an actual explanation of the architecture, the key concepts, why certain decisions were made, how the pieces fit together. Something I could read, learn from, and come back to later.

It wasn’t a magic pill. I was starting from near zero with Elixir and LiveView, so one document didn’t make me an expert. But it meaningfully closed the gap. I understood the code better than I did before. I had something to refer back to. And I started to feel like the codebase was actually mine.

That experience shaped how I think about using LLMs for coding. The tool works fine. How you engage with it makes all the difference.

Practical ways to keep the debt in check

Ask for explanations before you accept the code. Don’t just run it. Ask the LLM to walk you through what it did and why. This takes an extra minute and catches a surprising number of cases where the code is technically correct but built on assumptions you don’t share.

Ask for an explainer document for bigger decisions. Architecture choices, non-obvious patterns, anything you’re going to need to live with for a while: ask the LLM to write it up in plain language. Keep it in the repo. Future you will thank present you.

Use Simon Willison’s “showboat” approach to document what was built. The showboat tool “creates executable demo documents that show and prove an agent’s work.” (kind of like a Jupyter notebook, but just markdown). The LLM walks through its output with explanation and context. It’s a great way to produce living documentation that captures not just what the code does, but why it was written that way. It’s a great tool, but not suitable for every use case.

Read the LLM’s thinking, especially when debugging. Many LLMs can expose their reasoning process. When you’re stuck on a bug or trying to understand a decision, asking the LLM to think out loud before answering is one of the fastest ways to build genuine understanding rather than just getting an answer.

Write the tests yourself. Even if you let the LLM write the implementation, writing the tests forces you to reason about the behavior you actually want. It’s one of the best ways to make sure the mental model gets built. Of course, it takes more time and it’s not always possible, like with JoyConf where I didn’t know enough about the Elixir environment to write effective tests. But when you can, it’s a great way to stay in the driver’s seat.

Slow down at decision points. LLMs are fast. That’s the point. But speed can accelerate debt. When you hit a fork in the road (an architectural choice, a tradeoff, a “there are a few ways to do this” moment) pause and do the reasoning yourself, even if you use the LLM to help you think it through.

The goal isn’t to use LLMs less

LLMs are genuinely useful and I don’t plan to stop using them. The goal is to stay in the driver’s seat mentally, using them for leverage rather than as a substitute for thinking.

A healthy LLM workflow and a debt-generating one can look identical from the outside. The difference shows up later, when you need to understand, maintain, or extend what you built. If you finish each session understanding what you built and why, you’re using the tool well. If you don’t, you’re taking out a loan.

And like financial debt, cognitive debt is a lot easier to avoid than to pay off.

References

• MIT study on cognitive debt
• Simon Willison’s showboat tool
• JoyConf repo
• JoyConf story