Not Documentation. Experience: Teaching a Coding Agent with Claude Code Hooks

One thing that annoys me most about agentic coding: even with auto mode on, writing E2E tests eventually reaches a point where I have to step in and direct the LLM.

In my case, it often decides a manual test can't be automated. It checked the API request, didn't find enough information there, and stopped.

So I tell it:

"Go check the UI and see if that gives you the information."

Once is fine. Several times a week, it gets annoying.

It's not one correction, it's dozens

Sure, you can write a skill for this one. But it's not the only one. There are dozens of small, codebase-specific lessons you end up teaching the agent over and over:

• where the information really lives (the UI, not the API response)
• which helper to use, and which one looks right but breaks
• which approach failed last time, and why

None of these belong in a design doc. They're experience, and right now the agent loses it at the end of every session.

How do you make a coding agent learn all of this without constantly telling it to "remember this"?

Claude Code hooks

The idea is simple:

1. The agent gets stuck.
2. I give it guidance.
3. The agent completes the task.
4. A hook captures the correction.
5. A small learning step extracts the reusable lesson.
6. The lesson gets stored.
7. Future tasks use it automatically.

The plan. The growth curve shows what I'm hoping for, not something I've measured yet.

There are two halves:

• Before a task: retrieve the lessons that match what the agent is about to do, and inject them into its context.
• After a task: look at what I had to correct, decide whether it's reusable, and if it is, save it. One-off fixes ("rename this variable") get ignored.

Where the hooks fit

Claude Code hooks are commands that run on events in a session, configured in .claude/settings.json. A few events line up with the loop:

• Inject lessons: SessionStart and UserPromptSubmit. Output from these hooks is added to the agent's context, so they can pass in the relevant lessons.
• Capture a correction: UserPromptSubmit. A correction is usually a prompt I type mid-task, so this is where it shows up.
• Extract the lesson: Stop. It runs when the agent finishes and gets the session transcript, so it can see what went wrong, what I said, and what worked after.

The wiring is small:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "python3 .claude/hooks/inject_lessons.py" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "python3 .claude/hooks/extract_lesson.py" }] }
    ]
  }
}

The interesting part is the learning step, not the wiring: telling a reusable lesson from a one-off, keeping lessons short and specific, and not injecting fifty of them into every task.

Documentation vs. experience

Documentation says: use helper X.

Experience says: I tried approach Y, hit error Z, and helper X worked instead. Use X to avoid Z.

The second one is what I keep repeating to the agent, and the second one is what makes it stop making the same mistake. Over time, the agent builds its own playbook for how your codebase actually works.

That's what I'm experimenting with next: using Claude Code hooks to turn the small corrections we give agents every day into knowledge that persists. I'll share what works, and what doesn't, once I have results.