How to Reduce Claude Code Hallucinations: PRD, Task Manager, Sessions
Prefer to watch? Watch on YouTube · Subscribe for new builds · Read the transcript
In this video I walk through the workflow that helped me with errors and hallucinations in Claude Code: a product requirement doc, the /init command, a task manager markdown file, and start and end session commands. I recorded this in August 2025, two days after I moved my project from Bolt into Claude Code. It's for beginners who keep fixing one thing and then watching something else break. Tools change fast, so check the current Claude Code docs before you copy any of this exactly.
What I cover in this video
- 0:00 Why I ran into errors and hallucinations right after moving from Bolt to Claude Code
- 0:45 How working on every task in the same window filled up the context window
- 1:30 Running
/initso Claude Code creates the CLAUDE.md file - 3:51 The product requirement doc and why it goes into the project first
- 5:22 Asking Claude to create a task manager markdown file
- 6:08 The start session and end session commands
- 6:53 My terminal layout with one terminal per subagent
- 9:12 Ending a session, closing out the context window, and starting fresh
Why Claude Code kept breaking my project
When I first moved the project over, I opened one chat in Claude Code and knocked out task after task in it. I never cleared the context window. We would fix one thing and another thing broke. Then we fixed that, and the text didn't load. Then the login didn't work.
It took me a while to see that I was the one causing it. I hadn't set Claude up properly for the project, and I was stuffing too many tasks into the same chat. If Claude is hallucinating or throwing errors for you, you are probably doing the same thing I was: filling up the context window.
The fix came from a call in a group I'm in, where someone laid out how to run tasks efficiently in Claude Code and hand them to specific subagents. This is what works for me and how I look at my project. It may not fit everyone.
The setup: PRD, /init, then a task manager file
The order matters here, so I'll go through it step by step.
- Put your product requirement doc in the project first. The PRD is the blueprint of the build. I wrote mine with Claude and pasted everything in: the vision, timelines, and revenue goals. My project is easyflip.ai. You snap a photo, GPT vision generates the listing, and you can upload it to marketplaces like eBay, Poshmark, Mercari, and Facebook Marketplace. The PRD also says we start with a web app and build the mobile features after. Without this file, Claude has no idea what tasks to build.
- Run the init command inside your project folder. This has Claude Code create a markdown file called CLAUDE.md. That file gives Claude guidance for working in the repository. Mine covers the commands, the stack, the AI integration, Supabase, the back end, and the front end.
/init - Ask Claude to build the task manager. Once the PRD and CLAUDE.md are in place, I just ask for it:
Create me a task manager MD file so we could track tasks and progress.
The task manager tracks the tasks that come out of the PRD and what has been finished.
The task manager is what lets me pick up where I left off the day before. Before I had it, if I closed a chat or my computer crashed, Claude forgot what we had done. That happened to me and it was very frustrating.
Start session, end session, and one terminal per subagent
Along with the task manager, Claude creates two slash commands for me: one to start a session and one to end a session.
- Start session reads the task manager file and gets Claude caught up on what we accomplished on previous days and where we left off.
- End session writes what we completed into the task manager file so it's there the next day.
After I end a session, I close out the chat and the context window and start fresh before the next task.
I also split my work across terminals. The top terminal is for broad, general questions. The three terminals below it are each named after one of my subagents, which Claude Code built based on what it saw in my files:
- A business subagent
- An infrastructure subagent, for back end work like Supabase or authentication
- An AI accuracy analysis subagent, for improving the GPT vision and Google vision results when listings are generated
In each terminal I run the start session command and then tell Claude which subagent I want. I talk to it by voice with Wispr Flow. In the video I say:
I want to use the business sub agent to help optimize my business better and also give me a brief overview of what we've accomplished today.
This keeps each task on its own track. I do a task, see it through to completion, end the session, and the progress is saved. I'm also more efficient with tokens this way. After a full day of working like this, we were the furthest we had ever been on the project, because we corrected a lot of errors along the way.
Key takeaways
- If Claude Code is hallucinating or breaking things, you are probably filling up the context window by doing too many tasks in the same chat.
- Set things up in this order: PRD in the project, then
/initto create CLAUDE.md, then ask Claude for a task manager markdown file. - Use a start session command to catch Claude up from the task manager and an end session command to save what you finished.
- After each completed task, close out the context window and start fresh.
- If you are just starting with Claude Code, spend a day or two or three on the workflow before you plug in your project and start building.
FAQ
Why does Claude Code hallucinate or break things that were working?
In my case I was filling up the context window by doing task after task in the same chat without clearing it. Fixing one thing kept breaking another until I split the work into separate sessions.
What is a task manager file in Claude Code?
It's a markdown file I asked Claude to create that tracks the tasks from my product requirement doc and the progress on them. It lets me pick up where I left off the next day, even if I close the chat or my computer crashes.
What order should I set up the PRD, CLAUDE.md, and task manager?
Put the PRD in your project first, then run /init so Claude Code generates CLAUDE.md, then ask Claude to build the task manager file. Claude can't know what tasks to create without the PRD and CLAUDE.md in place.
What do the start session and end session commands do?
Start session reads the task manager file and catches Claude up on what was accomplished before. End session writes what you completed into the task manager so it's saved for the next day.
Transcript
Read the full transcript
0:00Just two days ago, we moved our project from bolt new into cloud code and we started having fun and maybe we got ahead of ourselves because we quickly ran into errors and hallucinations within cloud code and I was figuring out why is this happening and little did I know I didn't set up claude properly to be able to handle the project we were currently working on. And in this video, we're going to be going over some helpful tips that helped me just in the last 48 hours to help bring more clarity to my project. And I know it can for you as well. So, it doesn't mean that this is going to work for everyone. It just works for me and my kind of point of view when I'm looking at my project and kind of how I can optimize and become more efficient and when we end up building this project. So, that's what
0:45we're going to be working through today. So cloud code of course is a huge powerful tool if used correctly. And the thing that I was dealing with the most was filling up the context window so much working on each task within the same window and coming come to find out we would fix one thing and then the other thing broke and then we'd fix that thing that broke and then the text didn't load and then the login didn't work. It was just because I was just creating havoc by myself, not knowing what I was doing and just really becoming frustrated. So now we're going to go through this workflow that can help you become more organized when building things with Claude Code. And I think this is going to be helpful for you. Maybe you already know it, but
1:30we're going to just walk you step by step through this process. So once you get your Cloud Code project transferred in or downloaded from your GitHub and you start working on it, you're going to want to hit slashinit once you're in your folder. And then you're going to have cloud code create an MD file, a markdown file. And that file is going to be kind of the command and the basis on which it operates in these files and in these folders and kind of how to build out the project. So we did that and of course it was amazing. So we had cloud code build out some sub aents and you know according to what it saw in the files and all that was great but it didn't really click until we figured out what we were doing wrong and basically we were just opening up a chat within
2:17cloud code and just knocking out task after task. We weren't clearing the context window and we really started breaking things. It just became so frustrating. So I I just tried to figure there has to be a better way and I'm in the startup empire group um and we just had a great call that a guy had come on and just really laid it out the blueprint on how tasks can be efficiently done within cloud code and by how you can delegate these tasks to specific sub aents within your project. So we're going to walk you through this simple setup. It's going to take you like two seconds to set it up. So the first thing you're going to do is going to run that init command, you're going to create those um cloud.md files which
3:04I have already here um in my codebase. So if you go to the cloud.md file um this file provides guidance to cloud code when working with the cloud code in this repository. So it just gives it all the commands the stack API data AI integration superbase all the back end all the front end API keys and so forth. So um once you get the claude markdown file going, I then asked Claude to build a task manager markdown file and in this task manager markdown file if I can find it. Here we go. It tracks all the tasks from my product my project requirement document that I did um with Claude and
3:51it develops tasks. So, I should probably back up a little bit and go into that product requirement document which is right here. So, done with Claude. And this product requirement doc really is the blueprint of your build, right? So, it won't know what task to build unless you have this file. You need to have this put into your directory so it can have something like it's like the vision of your business. So the product requirement doc was put in after the the claude MD uh file was generated and um actually before that. So before the cloud MD file was created, the product uh requirement doc was put in. Then you
4:37generate the cloud MD file and then after that you can then build tasks because they won't know what tasks you're going to do if you don't have these to put in place. So once we got this done, I just had Claude write up um kind of the vision for our whole product. you know how we wanted to start on a web app first and then develop the mobile features what it exactly does why it's relevant why it saves time we are building out a project called easyflip.ai AI where it allows people to snap a photo using GPT vision. It generates the listing and you can upload it to market places like eBay, Poshmark and Merkari, Facebook Marketplace. So that in a nutshell is what our project is. So now we have like the context for
5:22um Claude to be able to know what to do. Um so yeah, you can see my prd is right here. Everything just copy pasted timelines, revenue goals, everything. And then it was able to really um come up with a task manager. So, and it's really simple, y'all. You're just going to ask Claude to do this for you. Once you get the PRD doc into your um codebase, once you get Claude MD um the markdown file all written out for your project, then you can just ask Claude, "Create me a task manager MD file so we could track tasks and progress." Because if you don't do this, it's going to be really hard for you to kind of leave off where you left off the day before or maybe your computer crashed and you lost
6:08the context that you were, you know, initiating changes and and it forgets, you know, that happened to me the other day. So, by having a task manager is huge. And this is how we do it. So, you're going to have two commands that it's going to create for you. It's going to be the slashstart session command and slashend session command. So, whenever you're working with like an sub agent, um I'll just show you an example here. This is kind of what I've been how I've had the layout. It's been really helpful. So, the top terminal I just have for like broad questions. Um and then the three bottom terminals I just named them um our sub aents name. So, we have a business um sub aent, we have an infrastructure sub aent, and then we
6:53have an AI accuracy analysis agent. um for the GPT vision and Google vision uh to help make that better. So um this is really allows me to break down the tasks that we're working on on an individual level and not get so jumbled with completing tasks and then starting a new task in the same window and then just basically we're the ones making the AI hallucinate and cause all these errors. And maybe you've been in that position before. This is probably going to help you out big time. So you can see just the top here is just kind of like for general questions. Um and then here we can go to um claude and just say okay so we will go to start start session and we want to use start session command it to
7:40kind of initiate um the workflow right it's going to read the task manager um file and get caught up to date as to like what we accomplished in previous days. So, start session and then I'm just going to use Whisper Flow to communicate. I want to use the business sub agent to help optimize my business better and also give me a brief overview of what we've accomplished today. Okay. So, once that gets done, um, we're going to be kind of getting caught up to date and it's going to look at the task. It's going to look at where we left off, what we got accomplished, and so forth. Same thing with the infrastructure agent. I can also do the same command start session and start maybe working on the backend stuff like fixing some something
8:26with superbase or authentication and then the AI accuracy sub agent as well. We could use that to work on something completely different like the AI analysis when it comes to generating the listings. So that's in a brief overview how you're going to set it up. You're going to get your PRD set up. You're gonna have slashinit command to start generating the claude md file. And then once you have that set, you can just ask claude to build a task manager file for you. So it can know kind of time frames what you're doing and you can save the progress as you're making progress through your project. So, it's really cool because I'm able to not only like be more efficient with the tokens that we have. Um, but I'm able to kind of
9:12like do a task, see it through completion, and then end session and have all of what we completed put into the task manager MD file for the next day. So, I just had a hard time once we completed something, um, you know, if I closed out or lost the the conversation, it wouldn't remember what we did and that was very frustrating for me. So, if you are like me and you're having a hard time, you know, dealing with Claude and maybe it's hallucinating or errors, you're probably just filling up the context window and you're probably doing too many tasks within the same chat. Another one after you end the session too, you're going to want to do a command um where you could just close out the chat, close out the context window and then start fresh. So that's
9:58what I have been doing all day today and we are furthest we've ever been in this project. The furthest we've ever been in the last 24 hours because we corrected a lot of errors. We started using Cloud efficiently. And I would just say for you if you're just starting using Cloud Code, spend a day or two or three developing the workflow within Cloud Code before you just start plugging in your project and working crazy. Maybe it works for you. I don't know. But for me, this is what worked and this is what I'm seeing that how the kind of workflow is going to be. So, comment down below. What are you doing to kind of solve this problem? Have you had Claude uh hallucinate in your project? I know I was kind of getting tired of it, especially coming over from Bolt where we already were dealing with a lot of hallucinations. So doing this kind of
10:44workflow, the PRD with the Claude MD, having Claude build the task manager and then starting session, ending session, and clearing and closing out the context window after we complete tasks is an amazing workflow that I can actually understand. Like I said, 17 days ago, I wasn't even doing anything like this. But 16 days in, we have a vision. We can see the horizon, and we can actually see this product launching here in the next 30 to 45 days. So, if you like seeing startups come to life, we're posting every single day. Make sure you guys follow and subscribe, and we'll see you in the next one.
Ready to start building with AI?
Join the Shipping Skool community free. Paid members get live bootcamp calls every week and weekly-updated courses.
Join Shipping SkoolKeep reading
CLAUDE.md Explained: How to Set Up Claude Code for Your Project
Before you build anything in Claude Code, create a CLAUDE.md file in your project root. It should cover your tech stack, file structure, conventions, and business logic. Have Claude read it at the start of each chat, add to it whenever Claude guesses wrong, and use it alongside your agents markdown file and your PRD.
Claude Code /btw Command: Ask Side Questions Without Context Rot
Claude Code has a /btw command that lets you ask a side question and get a full answer without it piling into your main build thread. I use it to keep my coding sessions focused and to avoid context rot in the 200,000 token window.
How to Start a SaaS With AI: Idea Browser, PRD, and Claude Code
Validate an idea first (I use Idea Browser), turn it into a PRD with Claude, then build in Claude Code on top of Ross Mike's Next.js starter kit. Hook it up to GitHub, a database like Neon or Supabase, Vercel for hosting, and Better Auth for login.
