I fell into an embarrassing pattern with Claude Code. I'd run a command, Claude would do something slightly off, I'd correct it, Claude would fix it, and we'd move on. Then, less than an hour later, I'd run the same command and get the exact same correction, the same fix, and the same version of me sighing quietly at my desk.

It took longer than I'd like to admit before the obvious question hit me: why am I doing this more than once?

What Claude Code Custom Commands Actually Are

If you haven't used custom slash commands in Claude Code yet, here's the quick version. You create a markdown file inside a .claude/commands/ directory at the root of your project, and that file becomes a /command you can invoke from inside Claude Code.

Create .claude/commands/draft-blog-post.md, and you get /draft-blog-post. The file contents are the instructions Claude follows when you run it. No plugins, no special syntax, no config files. Just markdown.

The commands can reference project files, accept arguments, and handle multi-step workflows. They're reusable prompts with context baked in, scoped to your project so they don't bleed into everything else you do with Claude.

The Problem: Claude Starts Fresh Every Time

When you run a custom command, Claude has no memory of the last time you ran it. It doesn't know that you already told it to skip the generic questions. It doesn't know the style you like, that a certain pattern drives you up the wall, or that "we always use PHP here" is a thing you've said four times now.

So you correct it again. It's not Claude's fault. It genuinely doesn't know. But it's still your time getting spent on work you've already done.

The Fix: A LESSONS LEARNED Section That Writes Itself

Here's the pattern I stumbled onto. At the bottom of your command file, add a LESSONS LEARNED section. Then add an instruction telling Claude to update that section after each run with anything new it picked up from your corrections or feedback.

A stripped-down version looks like this:

# Draft Requirements Document

Ask the user about their project goals, constraints, and timeline.
Generate a structured requirements document based on their answers.

After the run is complete, update this file by appending any new lesson
learned to the LESSONS LEARNED section below.

## LESSONS LEARNED
- Skip the "what programming language?" question -- this project is always PHP

Claude finishes the task, you give it corrections or confirm what worked, and before closing out, it appends to that section. Next time you run the command, those lessons are already in context before Claude does anything.

The command teaches itself from your actual usage.

A Concrete Example

Say you have a command for drafting a requirements document. First run, Claude asks a bunch of generic questions: project name, language, framework, timeline, and stakeholders. Half of them don't apply to your situation.

You correct it: "We always use PHP and Laravel and ask about the deployment environment first because that changes everything downstream."

Claude takes note and appends to the file:

## LESSONS LEARNED
- This project always uses PHP and Laravel -- skip language/framework questions
- Ask about deployment environment first, before anything else
- Stakeholder questions are not relevant for this team's workflow

Next run, Claude reads those lessons upfront. It skips the irrelevant questions and leads with deployment. You didn't have to say a word.

Keep running it, keep giving feedback, and the lessons accumulate. The command gets more precise with each use. Less noise, more signal.

Why the File Being a Text File Matters

The reason this works is almost embarrassingly simple: the command file is just a text file. Claude can read it, and (with your permission) Claude can write to it. So the command can update its own instructions based on what you tell it.

Your corrections don't vanish when the session ends. They live in the file, in version control, visible to anyone on your team who uses the same command. A teammate can add a lesson directly to the file, and the command gets smarter for everyone.

This is actually how the /draft-blog-post command on this project works. The LESSONS LEARNED section has picked up rules like "NEVER use em dashes" and "file path should match the publish date year" over multiple runs. Each one exists because I had to correct something once and decided I wasn't correcting it again (ask me how I know about the file path one).

The Feedback Loop

The full cycle is:

1. Run the command. Claude does the task with all existing lessons in context.
2. Review the output. Notice what was off and what landed well.
3. Give corrections or confirm what to keep. Claude knows what to carry forward.
4. Claude updates the file. New lessons get appended to the section.
5. Repeat. Each run starts a little sharper than the one before.

The command becomes a living record of your preferences, your team's conventions, and the quirks of your workflow. Not documentation nobody reads. Active context that shapes every future run.

How to Get Started

If you already use Claude Code, you can try this right now:

1. Open an existing command file in .claude/commands/ (or create one for something you do repeatedly).
2. Add a LESSONS LEARNED section at the bottom, even if it starts empty.
3. Add an instruction near the top telling Claude to update that section after each run based on your feedback.
4. Run the command and pay attention to what you have to correct.
5. Let Claude update the file with what it learned.

After three or four runs, you'll feel the difference. The repetitive corrections drop off. The command starts behaving like it actually understands your workflow, because at that point, it genuinely does.

That beats explaining the same thing for the fourth time, every time.