Custom Claude Code Commands That Simplified My Coding Sessions

Late last year I wrote two articles about working with AI assistants across sessions. Both worked really well. Copy-paste the handover prompt. Update the docs at the end of the session. Archive completed items before the file gets unwieldy. Simple. Turns out though, it could be even simpler.

About a month ago I started using Claude Code and discovered commands. Hang on, they're just prompts stored in files. New hammer looking for nails: you know the drill.

I tried simplifying the continuation prompt. It became /next.

I finished a bunch of tasks, which inevitably led to the next command: /archive.

My TODO list was empty. I needed /todo to create new ones.

TODO contained a growing list of noisy deferred ideas. This led to /idea.

A handful of slash commands was far easier to remember. I've structured this article so you can point an AI at it to set up the files for you. What could be easier?

The System at a Glance

Four files in your project root:

File	Purpose
CLAUDE.md	Agent instructions. Loaded automatically every session.
TODO.md	Current work. Step-by-step tasks with checkboxes.
HISTORY.md	Completed work. Archived from TODO when done.
IDEAS.md	Future work. Low-priority, separated from active focus.

Four commands in .claude/commands/:

Command	What it does
/next	Reads TODO.md, finds the first unchecked task, and continues working.
/archive	Moves completed tasks from TODO.md to HISTORY.md.
/idea	Captures a new idea in IDEAS.md without interrupting flow.
/todo	Plans the next step and writes it into TODO.md (after your approval).

That's the whole system. Let's have a look at each piece.

CLAUDE.md: Agent Instructions

CLAUDE.md is the file Claude Code reads automatically at the start of every session. It replaces the "Quick Context" section from my earlier TODO.md pattern and the manual "Read these docs first" prompt.

This file isn't documentation for humans. It's configuration for the AI. Write it as instructions, not prose.

Here's a distilled template you can adapt to any project:

# [Project Name] — Agent Instructions

## Read first

1. [KEY_DOC].md — [what it covers]
2. [SOURCE_DIR]/ — [what to look at]

## Dev environment

- [How to run the project]
- [Key URLs, ports, services]

## Architecture rules (never violate these)

- [Rule 1: e.g. "No direct database access from UI components"]
- [Rule 2: e.g. "All state changes go through the store"]
- [Rule 3: e.g. "No React — vanilla JS only"]

## Key commands

[command]  # [lint?]
[command]  # [build?]
[command]  # [run?]

## Working style

- One step at a time — implement, then stop for review
- If anything is ambiguous or has meaningful trade-offs, ask first

## Verify steps

TODO items marked "Verify:" require manual testing in a running
browser/server. Never tick these off — leave them unchecked and
list them for the user to confirm.

## Commits

Never commit unless the user explicitly asks.

What to put in here and what to leave out

Put in: Anything the AI needs to know every session. Architecture constraints. How to run the project. Non-obvious conventions. Working style preferences (do you want it to ask before editing, or just go?).

Leave out: Things derivable from code (file structure, function signatures). Things that change often (current task, recent history). Anything longer than a page. If a section is growing, extract it into its own file and add a "Read first" pointer.

The "Architecture rules" section does the most work. My experience is that without explicit constraints, the AI will suggest whatever framework or pattern it's been trained on most heavily. If you're using Custom Elements, it will suggest React. If you're using Fastify, it will suggest Express. Name your constraints. The AI respects what it can read.

The "Verify steps" and "Commits" sections solve a specific problem: AI agents that tick off manual testing checkboxes without testing, or commit code without being asked. Both have bitten me. State the rules once in CLAUDE.md and they apply to every session.

TODO.md: Current Work

TODO.md is where active work lives. Nothing else. No backlog, no ideas, no completion history. Just the current and upcoming tasks with enough detail for the AI to pick up where you left off.

# [Project Name]: TODO

## Goal

[One or two sentences describing what you're building toward.]

## Milestones

[List of milestone numbers/names showing progression.]

## Next Steps

### N) Task Title

One-line description of the feature or change.

#### Sub-section name

- [ ] Implementation task
- [ ] Implementation task

#### Verify

- [ ] Verify: manual testing instruction
- [ ] Verify: manual testing instruction

---

### N+1) Next Task Title

...

Why this structure works

Each task is a numbered step with checkboxes. The AI reads the file, finds the first unchecked box, and knows exactly where to start.

The #### Verify sections are a forced hold. CLAUDE.md tells the AI to never tick these off, so it implements everything it can and then stops. You test in the browser, confirm it works, and your next prompt is usually "verified, mark as done, commit." This is the human-in-the-loop checkpoint. Ironically, it lends itself to yet another command (maybe /verified), which is how you know the pattern is working: it's easy to extend.

The --- between tasks acts as a clean boundary. When /archive removes a completed task, it removes everything from the ### heading to the next --- or ###.

HISTORY.md: Completed Work

HISTORY.md is a date-stamped log of completed tasks. It gives the AI temporal context without cluttering the active task list.

# [Project Name]: History

## 2026-03-21

- Step 37: Markdown syntax highlighting
- Step 36: Re-index and housekeeping improvements

## 2026-03-15

- Step 35: Soft delete and bin management
- Step 34: Ambient summaries

## 2026-03-10

- Step 33: Notebook drag and drop

The format is minimal. Date heading, bullet points with step number and title. That's enough for the AI to understand project maturity, recent momentum, and what's already been built.

You don't write this file. The /archive command does.

IDEAS.md: Future Work

IDEAS.md is where backlog items, feature ideas, and "maybe someday" thoughts go. It's deliberately separated from TODO.md to solve the original problem: AI assistants treating backlog items with equal weight to current work.

# [Project Name]: Ideas

These are not prioritised. They are captured here so they don't get
lost and don't pollute the active TODO.

### Idea Title

One or two paragraphs explaining the idea, its motivation, and how
it might connect to existing work.

### Another Idea

Description.

The AI doesn't read this file unless you ask it to. That's the point. When you're mid-session working on step 42 and a stray thought hits you, type /idea wiki-links with autocomplete and it gets captured without breaking your flow or contaminating the task list.

The Four Commands

Commands live in .claude/commands/ as markdown files.

/next

Read `TODO.md` and continue working on the current or next task.

## Steps

1. Read `TODO.md`.

2. Find the **current task** — the first task under "Next Steps"
   that has at least one unchecked (`[ ]`) non-Verify checkbox.

3. Summarise the task and which steps remain, then proceed with
   the next unchecked step.

This is the command that replaced the handover prompt. You open your laptop, start Claude Code, type /next, and the AI picks up where you left off. No copy-pasting. No remembering. No context.

I forget where I'm up to constantly. This command means I don't have to remember.

/archive

Archive completed tasks from TODO.md into HISTORY.md.

## Steps

1. Read `TODO.md` and `HISTORY.md`.

2. Identify **fully completed tasks** — a task is fully completed
   when:
   - Every non-Verify checkbox is checked (`[x]`)
   - Verify checkboxes are ignored (they are always unchecked
     by design)
   - If a task has no checkboxes at all, it is NOT considered
     complete

3. If no tasks are fully complete, report that and stop.

4. For each completed task, append to `HISTORY.md` grouped
   by date:
   - If a `## YYYY-MM-DD` heading for today already exists,
     add bullet points under it.
   - Otherwise, append a new date heading first.

5. Remove the completed task sections from `TODO.md`.

6. Show the user what was archived and what remains, then ask
   them to confirm before committing.

7. When confirmed, commit both files with message:
   `Archive completed tasks: <comma-separated task titles>`

When a task is done (all implementation checkboxes ticked, Verify items left unchecked by design), /archive moves it to HISTORY.md with today's date, cleans TODO.md, and commits.

/idea

Quickly capture an idea in IDEAS.md.

## Steps

1. Read `IDEAS.md` to understand the current structure and avoid
   duplicates.

2. Take the user's input and expand it into a well-formed idea
   entry:
   - `### Title` — short, descriptive name
   - One or two paragraphs explaining the idea, its motivation,
     and how it connects to the project
   - If the idea relates to existing ideas already in the file,
     note the connection

3. Append the new entry to the end of `IDEAS.md`.

4. Show the user what was added.

You type /idea streaming responses for the ask mode and it writes a properly formatted entry. The idea is captured. Your flow isn't broken. TODO.md stays clean.

/todo

Plan the next step for TODO.md without executing it.

## Steps

1. Read `TODO.md`, `DESIGN.md`, and `HISTORY.md`.

2. Read the current source code relevant to the feature being
   planned.

3. Break the feature into small, ordered implementation steps.
   Group related tasks under sub-sections.
   Include a Verify section with manual testing checks.

4. Present the proposed step to the user for review.
   Do NOT edit TODO.md yet.

5. Once approved, write the step into the "Next Steps" section
   of `TODO.md`.

This one is for planning. When you finish a phase and need to figure out what's next, /todo add entity-aware filtering reads the codebase, reads the history, and proposes a detailed step-by-step plan. You review it, adjust it, approve it. Then it writes it into TODO.md and you can /next to start executing.

How It Fits Together

A typical workflow looks like this:

1. Start of session: Type /next. The AI reads TODO.md, finds the current step, summarises where you are, and starts working.

2. During work: The AI implements each checkbox, stops for review, and moves to the next. If a stray idea comes up, type /idea [description] to capture it without losing focus.

3. Task complete: All implementation checkboxes are ticked. The AI lists the Verify items for you to test manually. You test, confirm, and ask for a commit.

4. Housekeeping: Type /archive to move completed tasks to HISTORY.md. Type /todo [next feature] to plan the next step.

5. Next session: Type /clear then /next. The AI picks up exactly where you left off.

The human's job is to review, test, and decide. The protocol's job is to remember.

Setting Up a New Project

Share this article with Claude Code and ask it to scaffold the files. Or copy the templates above:

1. Create CLAUDE.md in your project root with your architecture rules and dev environment.
2. Create TODO.md with a goal and your first task.
3. Create HISTORY.md with just a heading.
4. Create IDEAS.md with a heading and a note that items are not prioritised.
5. Create the four command files in .claude/commands/.

The commands are generic enough to work across projects without modification. CLAUDE.md is the only file that needs project-specific content.

Scope and Honesty

This is a personal workflow system. It's great for solo work. It could work in a team. It doesn't replace Jira.

It doesn't replace documentation. CLAUDE.md tells the AI how to work on your project. It doesn't explain your architecture to a new team member. If your project needs a DESIGN.md, have the AI write one and point to it from CLAUDE.md's "Read first" section. It's only a matter of time before you add /docs to tell the AI to summarise what 'we' just built and make sure the documentation is aligned with the current state of the code.

Enjoy!