This is Part 6 of the Claude Code Series, a complete guide to Claude Code from first principles to real-world use. Start from Part 1 if you are just joining, or pick up from Part 5 if you just finished configuration.
Five posts of groundwork. Understanding, installation, configuration. All of it necessary. None of it the actual thing.
This is the actual thing.
In this post I am going to walk through a complete Claude Code session from the first prompt to the finished result. A real task. Real back and forth. Including the moment where Claude Code went in the wrong direction and I had to pull it back.
The task is something anyone might actually need: taking a folder of loosely named, inconsistently formatted markdown files and cleaning them up. Rename them to a consistent format, fix the frontmatter so every file has the same fields, and generate a summary CSV listing every file and its key metadata.
Not hello world. Something worth doing.
Before the Session Starts
Two things happen before I type the first prompt.
I check my CLAUDE.md file. From Part 5, you know this is the file Claude Code reads at the start of every session to orient itself. My global CLAUDE.md has a few standing preferences. For this task, I also create a project-level CLAUDE.md in the folder I am about to work in.
It says:
# Project: markdown cleanup
This folder contains 23 markdown blog posts in various states of disarray.
Filenames are inconsistent. Frontmatter fields vary across files.
## Goal for this session
1. Rename all files to kebab-case with a date prefix: YYYY-MM-DD-title-slug.md
2. Ensure every file has these frontmatter fields: title, date, tags, status
3. Generate summary.csv listing filename, title, date, tags, status for every file
## Rules
- Do not delete any content inside the files
- Do not change any existing frontmatter values, only add missing fields
- If a date cannot be determined from the file, use "unknown" as the value
- Ask before doing anything that affects more than 5 files at once
That last rule is important. I added it because this is the first time I have run Claude Code on this folder and I want visibility before it touches too many files in one go.
Then I navigate to the folder in my terminal and run claude.
The Opening Prompt
I do not repeat everything in the CLAUDE.md file. Claude Code already read it. I just say what I want to do this session.
Me:
Let’s work through the markdown cleanup described in CLAUDE.md. Start by reading the folder and giving me an inventory of what you find. Do not change anything yet.
This is deliberate. I want Claude Code to show me what it sees before it does anything. This gives me a chance to catch any misunderstandings early, before they become 23 renamed files I have to undo.
Claude Code:
I’ll read the folder contents and give you an inventory.
[reads 23 files]
Here is what I found:
Files: 23 total Filenames: Mix of formats. Some have dates (2024-03-blog-title.md), some are just titles (my-post-about-writing.md), three have no discernible structure at all (draft1.md, final.md, FINAL-FINAL.md).
Frontmatter: 18 files have some frontmatter. 5 have none at all.
- All 18 have a title field
- 14 have a date field
- 9 have a tags field
- 7 have a status field
Three files (draft1.md, final.md, FINAL-FINAL.md) appear to be drafts or duplicates. Do you want me to include these in the cleanup or handle them separately?
That last question is exactly right. Claude Code noticed something ambiguous and stopped to ask instead of guessing. This is what good agentic behaviour looks like.
Handling the Ambiguity
Me:
Leave those three files completely untouched. Add a note in summary.csv marking them as “excluded”. Work on the other 20 only.
Claude Code:
Understood. I’ll work on the 20 files and mark the three excluded files in the CSV with status “excluded”. Ready to proceed with renaming when you are.
Short acknowledgment. No unnecessary recap. Claude Code is ready to act.
The First Action
Me:
Go ahead and rename the files. Start with the first 5 so I can check the format before you do the rest.
I am applying the CLAUDE.md rule manually here. Even though I wrote “ask before doing anything that affects more than 5 files,” I am making the ask explicit because I want to be extra careful on first run.
Claude Code:
I’ll rename the first 5 files to kebab-case with date prefix. Here is what I plan to rename them to before I do it:
- my-first-post.md → 2024-01-15-my-first-post.md (date from frontmatter)
- WritingEveryDay.md → 2024-02-03-writing-every-day.md (date from frontmatter)
- tools-i-use-2023.md → 2023-11-20-tools-i-use.md (date from frontmatter, removed year from title)
- the-one-about-focus.md → unknown-date-the-one-about-focus.md (no date found)
- Post About Reading.md → 2024-03-10-post-about-reading.md (date from frontmatter, spaces removed)
Shall I proceed with these?
Two things worth noticing. For file 3, Claude Code removed the year from the slug because the date prefix already carries that information. That is a reasonable call but it is also a judgment call. I want to check I agree before it applies that logic to 15 more files.
For file 4, Claude Code used “unknown-date” as the prefix because there was no date to find. That matches my CLAUDE.md instruction but I want to see how it looks in practice before committing.
Me:
One change. For files with no date, use “undated” as the prefix instead of “unknown-date”. It is shorter. Everything else looks good. Go ahead.
Claude Code:
Got it — “undated” prefix for files without a date. Renaming the first 5 now.
[renames 5 files]
Done. All 5 renamed successfully. Ready to continue with the remaining 15?
Where It Went Wrong
Me:
Yes, go ahead with the remaining 15.
Claude Code:
[renames 15 files]
Renaming complete. All 20 files now follow the format. Moving on to frontmatter.
I’ll add missing frontmatter fields to all 20 files now.
This is where I needed to stop it.
Claude Code jumped straight into the next task without checking in. My CLAUDE.md said to ask before affecting more than 5 files. Frontmatter changes across 20 files counts. I had gotten comfortable enough with the renaming that I let it run all 15 at once, and now it was treating that comfort as permission to continue at the same pace.
Me:
Stop. I want to check the frontmatter changes before you apply them broadly. Show me what you would do to the first 3 files and wait.
Claude Code:
Understood. Here is what I would add to the first 3 files:
2024-01-15-my-first-post.md — currently missing: tags, status. Would add: tags: [], status: draft
2024-02-03-writing-every-day.md — currently missing: status. Would add: status: draft
2023-11-20-tools-i-use.md — all four fields present. No changes needed.
For any file without a status field, I’ve defaulted to “draft” since I cannot determine the intended status. Should I use a different default?
Good. The pause was useful. I want “unpublished” not “draft” as the default, which I would not have caught if it had run all 20.
Me:
Use “unpublished” as the default status, not “draft”. Now apply to all 20 files.
Claude Code:
[updates frontmatter in 20 files]
Frontmatter complete. 13 files had missing fields added. 7 files were already complete. Moving to summary.csv.
The Finished Output
Claude Code generates the CSV, I review it, and one thing needs fixing: the tags column is showing raw arrays like ["writing", "tools"] instead of clean comma-separated values. One prompt fixes it.
Me:
The tags column in the CSV is showing array syntax. Change it to plain comma-separated values, no brackets or quotes.
Claude Code:
[updates summary.csv]
Done. Tags now display as: writing, tools
The whole session takes about 25 minutes. 20 files cleaned up, frontmatter standardised, a clean CSV ready to use.
What This Session Taught Me
A few things became clear by the end of it.
The opening inventory prompt is always worth it. Asking Claude Code to read and report before acting takes two minutes and catches ambiguities before they become problems. The three draft files would have been renamed and had frontmatter added without it.
CLAUDE.md rules do not enforce themselves. Claude Code read my rule about checking in before affecting more than 5 files. It still jumped ahead when I gave it an open-ended “go ahead.” The rules are guidance, not guardrails. You still have to apply judgment in the moment.
Stopping and redirecting is not a failure. When Claude Code moved too fast, I stopped it, asked to see the proposed changes first, and caught the “draft” versus “unpublished” issue. That is the loop working correctly. The agentic system runs, you observe, you adjust. You are part of the loop too.
Small corrections compound into a clean result. Every prompt was short. Most corrections were one sentence. The accumulated result of a dozen small clarifications was 20 well-formatted files and a usable CSV. That is what a good Claude Code session feels like.
What’s Next
Part 7 is about prompting. Specifically, how writing instructions for Claude Code is different from writing prompts for the chat interface, and the patterns that reliably produce good results versus the ones that reliably go wrong.
If this session felt a little rough in places, Part 7 is what smooths it out.
See you there.
Claude Code Series — Part 6 of 18. A complete guide to Claude Code from first principles to real-world use.
