Documentation next: Habits that survive AI-assisted development

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.