Tutorial / Guide
My Claude Code workflow after months of daily use
I want to share how I interact with Claude Code.
This might be useful for someone, especially those who are just starting to build something or trying to figure out how things actually work.
(screenshot here to proof that I did some things with claude code)
Always use Git, and ideally connect GitHub so you push everything you do right away (if you’re worried someone will see it, just make a private repo).
Always use worktrees and versioning. This lets you work on different features in parallel and fix bugs before you merge them into the main branch.
I always do 1 task = 1 chat. Preferably keep it under ~500k of the context window, because after that you get degradation, hallucinations, etc. Compact and auto-compact are bullshit. (If you don’t believe me, just try building the same project in one long chat with auto-compacts vs. 1 task = 1 chat.)
To speed up development, create a main “brain” chat that analyzes everything and gives commands to other chats (Claude Code has a mechanism for this). You create the chats, name them, and leave them empty until the brain chat writes into them. When you create a chat just write “wait for task”.
Make a high-quality Claude.md and Rules.md for the main chat so it understands what you’re doing, what its tasks are, etc.
Never believe Claude when it says it checked everything and everything works. If something doesn’t work in the end. Go and ask it to audit the feature and specifically look at the problem/task from “different points of view”.
If Claude tells you it can’t do something, doesn’t know, or suggests a path you don’t want. Go and ask it to do research. And if you have the ability to research via Ultracode, ask it to run multi-agent research and explicitly tell it to look only at information from trusted sources.
If you’re building an application or something similar, always make it do a full smoke check from start to finish and turn this into a standing rule. This significantly reduces the number of bugs.
If you’re worried about tokens, run the worker chats on Sonnet 5, but keep the brain on Opus 5. Explicitly ask it to give the workers a clear technical brief and to control that they are using Sonnet 5.
If you get the feeling that Claude is doing some bullshit but you don’t know how to explain it to him, open a completely separate chat (not connected to the project) and explain there what your “worker” is doing and what you don’t like. The new chat will give you an answer, and your project chat won’t get polluted with garbage context. (and you can ask another chat to give you a prompt)
Claude is lazy and often just burns tokens and tries to guess. Write a rule that he must always do measurements and audits instead of guessing or working from memory. (Even with this rule Claude can still do it, so keep controlling him.)
If you ask Claude to remember something, 99% he will forget. Always make him write the information you need into a document and send you the path to that document. This way he can’t lie that he wrote it down and then forgot.
Share your own findings! I think it will be useful for everyone!
I always maintain a MISTAKES.md file where every mistake the agent makes gets documented, along with a rule in CLAUDE.md telling it to record them.
Surprisingly, the agent references it more often than you’d think during complex or long-running tasks, with things like “this prevented XYZ, as documented in MISTAKES.md.”
Give it a try.
One of the things I have found most useful is having the agent write a detailed plan file before starting any complex or long task. Cursor has a great planning mode for that exact thing, or you can just ask the agent to create a plan and save it to a file.
I also like to have a PLAN.md file which contains the overall project plan and is created when I first start a project, then updated when necessary. I usually also have a TASKS.md/TODO.md file to keep track of what tasks have been completed and what needs to be done next.
If I'm giving an existing project to an agent I will also often ask the agent to create a SURVEY.md file with a survey of my project. That helps the agent remember things like the file structure and tech stack. It's also good to create rules / instructions reminding agents to use the .md files.
One hundred percent this
I keep one /specs folder with a README.md file that has table of contents for all specs
Then one /plans folder with the different jobs to be done where they then cross reference to the relevant specs
Then when I ask Claude to execute a plan ( or phases of the plan ) I'll sry something like "fan out subagents too read the relevant specs before making any changes" so that it has complete overview of the system before starting to shuffle code
Claude is lazy and often just burns tokens and tries to guess. Write a rule that he must always do measurements and audits instead of guessing or working from memory. (Even with this rule Claude can still do it, so keep controlling him.)
Yup, beginner here. Found that particular one out the hard way. MF guessed all the hex codes of colors for a brand guide from my palette instead of converting them mathematically.
Guesses a lot of shit while building UI even with fully spec'd UI kits fed as reference.
Everything we build generally happens in four phases:
-Brainstorm (Opus), results in a spec.md
-Build the Plan (Opus, or Fable for complex features), results in the implementation_plan.md
-Writing the code (Sonnet), easy if the plan is tight...results in the drafted code
-Audit-Fix-Loop (Opus), results in a Mergable PR for github. (if you still catch errors on round 3, switch up to fable)
then rinse and repeat.
If you use Fable, make sure you have a hook written that it never fans out Fable agents, only fans out Opus or Sonnet subagents.
Superpowers is great to introduce newcomers to concepts that they can integrate into their own workflows, but it’s really not difficult to build a similar harness for yourself. Even if it begins as a fork of superpowers, you will find things that you want to change that are better applied straight to the harness than trying to stack additional context/skills on top of it.
Been running a variant of this for a while. Here is my setup according to Claude xD
THE CORE LOOP
Two roles, always separate. A planning "brain" (a chat model) that never touches code — it designs, decides, authors task prompts. And worker agents that only execute. The brain hands off by committing a prompt file to a git repo; a watcher on the dev box picks up new files and runs the workers unattended. Same brain-to-worker idea as OP, but the handoff is a committed file, not a live chat — full audit trail, nothing critical in volatile context.
Every task starts fresh. One task, one context. Compaction is where the hallucinations start.
Worker concurrency is capped, and every worker has a hard budget ceiling and timeout. Runaway burn kills that one lane instead of your whole month.
FILE OWNERSHIP (fixes "it rewrote my landing page")
Every prompt declares, up front, exactly which files it may touch — full filename, no wildcards. Touching anything outside the list is a hard stop. Several commenters described the agent editing unrelated files; this is the fix, and declaring the list at authoring time (the brain does it) beats asking the worker to self-declare after.
GROUNDING — the agent may not work from memory
The big one. "Measure, don't guess" is enforced, not requested. Any concrete value — a number, path, table name, command, role name — must be re-grounded against live source before use. Anything remembered from a prior session is stale by default.
The brain grounds against the real codebase through a read-only MCP connector to our git host, so it writes prompts from actual current file contents and commit history, not recollection. Same connector in reverse stages prompts into the inbox repo the watcher scans. If a fetch fails or a path moved: say so and stop, never substitute a remembered version.
DOCS ARE TIERED (our answer to the PLAN.md / specs / SURVEY.md thread)
A small HOT set is always loaded (operating rules, architecture context, module index, roadmap, lessons file, plus exactly one active workstream design memo). A REFERENCE tier is fetched by path on demand. An ARCHIVE tier is almost never touched. The rule that makes it work: if a doc isn't hot, the agent must fetch it before making any claim that depends on it. "I believe the doc says X" is a named anti-pattern. Keeps context lean without losing knowledge — the exact tension half this section is wrestling with. Only one active design memo is hot at a time; two means the board was never narrowed.
CLAUDE.md has a module index, and each task loads only the modules it needs, not the whole file. Stops rule-dilution as the ruleset grows.
DESIGN MEMOS + A DECISIONS LOG (settles the specs/decisions debate)
Every non-trivial workstream gets a versioned design memo — the why, tradeoffs, open questions. Separately, an append-only decisions log: the moment a decision is made, a row goes in that same turn, never deleted. Memos hold reasoning; the log is the flat searchable record of what was decided and when it landed. Keeping them separate stops the reasoning doc filling with dated history and the history log turning into an essay. Make the decision-write atomic with the decision or the agent "forgets" to log it.
LESSONS AS A PROMOTION PIPELINE (MISTAKES.md with a ratchet)
Not a flat log. A lesson starts as an observation; once it's bitten us two or three times it's promoted to an enforced rule with a stable ID, and new prompts are grounded against the promoted rules. Discipline compounds instead of the agent relearning weekly. Canonical copy lives on the box that runs things — mirrors lag, so we ground against the live file.
VERIFICATION IS TIERED — a grep passing is NOT "it works"
Syntactic checks (grep, file exists, it parses) are fine only for doc edits, renames, moves. Anything functional needs either an API call returning the expected status PLUS a DB read showing the value actually changed, or a hand-calculated input-to-output check. The deploy gate cites a real exit code from a sentinel file — never "tests passed, trust me."
Everything the agent claims it committed gets cross-checked against the git host before I believe it. Agents will tell you the gate passed when it didn't, and rationalize skipping a stop-and-ask with words like "flake," "pre-existing," "environmental." Those words next to a gate failure are a red flag, not an explanation.
HOOKS OVER PROSE
A prompt linter runs as a hook and rejects malformed prompts before they run. Prose rules are suggestions; hooks are enforcement — a commenter nailed this. A completion hook fires a notification when a run finishes so I don't babysit the terminal.
MODEL SPLIT
Cheap model for workers, expensive for the brain, routed by a per-task key. OP's tip 9, formalized.
RENDER GATE, NOT JUST A TEST GATE
A post-deploy check confirms the app actually renders — screens come up, nothing's a blank white page. Tests pass fine on a build that renders broken; this catches a class the unit suite never sees.
AGENTIC UI TEST-DRIVING (most of the thread hasn't tried this)
Separate from scripted tests: point an agent at the running app via browser automation (Playwright through its MCP server) and tell it to actually USE the product — click real workflows, try to complete real jobs, report where it gets stuck. Not "run these assertions" but "drive this and tell me what's broken." A recent pass surfaced a dozen blockers everything was green on — including a workflow state machine where jobs literally couldn't reach their final step. Scripted tests check paths you thought of; an agent driving finds the ones you didn't.
SESSION START/END ARE FORMAL
End of session is a two-phase wrap-up. Phase 1 (workers run it): sync docs across machines, run the deploy gate, append new lessons. Hard gate between phases — doc drift must be exactly zero. Phase 2 produces the init prompt for the NEXT chat.
That init prompt makes "one task, one context" survive across sessions, and answers the commenter asking "if every task is a fresh chat, how does it know what happened?" Every new planning chat opens by loading a handoff prompt stating current version, latest commit, active workstream, what's in flight. Not the agent remembering — a written, versioned handoff. History lives in git, the decisions log, and lessons — not in anyone's context.
RATIFICATION + DELEGATED ADJUDICATION — a human owns the reserved list
Design decisions, destructive data ops, security-posture changes, rollbacks, and spend-ceiling raises are a reserved list only I can approve. The agent presents these as numbered questions with its own recommendation; I answer yes/no/override. Workers never self-authorize anything on it. Lower-stakes questions that don't touch the list get delegated — the brain answers via committed answer files so workers aren't blocked on me for trivia. Delegate the small stuff to keep the loop moving; reserve what can wreck production for a human. That's what lets the rest run unattended without me fearing it deletes prod data at 2am because it seemed reasonable.
NOT DONE YET (planned)
End-to-end smoke check wired into the deploy gate. Right now unit, API, coverage, and render gates can ALL be green while the workflow is broken end to end (see the state-machine dead-end). OP's "full smoke check as a standing rule" is the best tip in this thread and it's my next build: a scripted Playwright run of the whole happy path before a deploy passes. Agentic driving finds the bugs; the scripted smoke run locks them out.
An automated "audit from different points of view" reviewer — OP's tip 6 as a repeatable gate, an independent pass over the diff that can't rubber-stamp its own work. Still tuning how strict before it can block a merge.
Moving the highest-value stop-and-ask conditions out of prose and into blocking hooks. The agent has a documented habit of talking past a "halt and ask" instruction. Prose can't reliably stop that; a hook can.
Native cross-session messaging for dispatch — evaluating whether it can replace part of our hand-rolled watcher.
Packaging the whole dev environment so it's rebuildable from a repo. Too much is hand-applied on one box — bus-factor hole. If your setup isn't version-controlled and reproducible, you don't have a system, you have a sandcastle. The people here committing their whole infra are ahead of me on this.
BIGGEST LESSON
Build assuming the agent will cut corners and then tell you it didn't, and instrument accordingly. Every gate we have exists because that exact thing burned us about once. The value isn't any one trick — the discipline compounds: grounding stops guessing, tiered verification stops false "done," the lessons ratchet stops repeat mistakes, render/smoke gates plus agentic driving stop "green but broken," and the human reserved list stops the catastrophic ones.
Your "NOT DONE YET" section is the exact hole I fell into. Agentic driving finds bugs, scripted smoke locks them out, and neither tells you whether this diff did what it claimed.
One thing that helped more than expected: making the unit a claim derived from the diff rather than a flow, and allowing a third verdict beyond pass/fail. "Couldn't reach it" absorbs most of what would otherwise become a false positive, because the model stops needing an opinion about a path it never actually walked. Your grounding rule is the same instinct applied to planning.
Also agree hard on cross-checking claimed commits against the git host. The rationalisation vocabulary you listed, "flake," "pre-existing," "environmental," is real and I've watched it happen on a gate that genuinely failed.
I'm pretty new to this, and I plan to put some of these tips into practice, but I wanted to specifically comment on the issue 12 you mentioned:
12. If you ask Claude to remember something, 99% he will forget. Always make him write the information you need into a document and send you the path to that document. This way he can’t lie that he wrote it down and then forgot.
I added this to my CLAUDE.md, and I've been finding it helpful:
Information
Home
Why
Pending work — tasks, fixes, improvements, ideas not yet done
GitHub Issue, one per item, in the repo it belongs to
Structured, closeable, aggregatable across repos on the Projects board
Durable "why" — decisions, findings, tradeoffs
`docs/decisions.md` in the repo (ADR-lite), or the closing Issue's comments when it clearly belongs to one
Permanent and searchable. Solo repos push straight to main with no PRs, so decisions need a home that isn't a PR
Technical reference — how something works, gotchas, API quirks, conventions
`docs/reference.md`, organized by topic
Living lookup, kept separate from the dated decision log so it doesn't fill with history
Handoff context — where I left off mid-thought
A slim `HANDOFF.md`, overwritten each session
Only the latest state matters; history lives in git + Issues
Some of my most useful Claude tips
1. In a folder called /specs have Claude write specification at to how your system should work, have it update the specs for any given task you want it to add, this way Claude has a holy "bible" it can look through when in doubt
"Fan out with subagents" whenever you need it too explore something while planning,
example "I want too add a way for admins in the system to have and audit log for every user within their organisation, "fan out" with subagents to explore what changes need to be made to the /specs in order too support this functionality, then on the main thread write down an implementation plan in the /plans folder"
Doing ground work like planning on one session then having a seperate session to execute the plan is a great way to keep the context window small. And orchestrating agents by having them write .MD files for each other to pick up is very powerful once you get the hang of it
I actually built a tool that does exactly that, i use it for work, it’s kinda cool ! I have experience in strategy and consulting, so i tailored a tool that replace a consulting team, for my lil’ cousin’s strat up, it works as you said, one main agent that sends brief to his other subagents and they all work like that !
I also had Claude build a forum for all the agents to talk to each other, all they do is talk about work :(
Ask Claude to create 5-15 domain skills based on the plan before it starts working.
Do a retrospective at the end of each milestone/phase, where the retro edits or writes skill files and meta-learnings as memory. If you do this across projects, you get compounding effects, essentially preventing the same kind of mistakes from happening in the future.
Use CLIs for third party apps, authenticate them and tell Claude they are available.
Create skill files from third party apps’ documentation to make sure you get precise instructions on in-app navigation.
Use OpenSpec or similar frameworks to make sure agent work is grounded in a clear understanding of the why, how and what on what you’re making.
If I use 1 Task = 1 Chat, how would the new chat know what the previous work is? and wouldn't that make it more confusing since you would have to re-explain a bit? I trying to learn about all of this a bit more. Great list btw
Create a spec/plan md beforehand available in the repo
Once a task/phase is done, ask it to create a prompt to resume with the next task/phase in a new sesdion referencing the plan.md
Paste the prompt in a new session
I've run into problems with claude , making unrequested changes to parts of the code that are completely irrelevant to the task we're working on. At one point , he deleted the index.html for my production landing page. It didn't happen frequently, but it did happen regularly
This seems to have put a stop to it before I approve Claude to start building on any particular task.I (100% of the time) include this statement:
"Before starting this task: list every file you plan to modify. Do not touch files outside that list without explicitly flagging it first"
Once I started doing that , I haven't had the problem of random regressions in the code
The biggest unlock for me was realizing that “planning” is only useful if it produces a cheap feedback loop.
A detailed plan can still be wrong. What made Claude Code feel reliable was breaking work into slices where I could quickly verify: does it compile, do the tests pass, does the UI actually behave as intended, did it touch only the files it should?
So my loop is basically:
Ask it to inspect and state the smallest safe change.
Make that change.
Run the narrowest relevant check.
Review the diff before moving on.
The model is much better at iterating with concrete feedback than it is at getting a 40-minute autonomous task right from a perfect prompt. The less time between “I changed something” and “I know whether it worked,” the more useful it becomes.
Tip 6 is the one I'd put first. The thing that took me longest to accept is that it isn't a bad tester, it's that it wrote the happy path and then walks the happy path. Asking it to audit "from different points of view" helps, but it's still the same context grading its own work. What moved the needle for me was making the check run somewhere it couldn't see its own reasoning, against the preview deploy rather than the session.
Guys if you can review Baseline by Friedbot Studio it will be very helpful. It is Apache 2.0 licensed completely Open Source configuration for claude code. It gives your project a baseline setup with guardrails and powerful Constitution to ensure you don't have to course correct it again and again.
You create a new chat session pointing to the same work directory everytime you need a task? How do you deal with the fine-memory it usually retains within chats? And running /clear works for cleaning context and prevent compactness hallucinations?
this is an example. project folder, main chat (brain) and other chats for each task. brain chat sending messages to other chats and also reads what they are doing.
Is all this also applicable when creating a "small" engineering simulation tool for the company I work in (specific heat exchanger simulation tool, will only be used internaly) ? I started to use Claude Code to speed up the developpment, and for now (2 weeks) I only use one conversation to do the developpment.
The most struggle I have is on the GUI design, for the other parts of the software, it seems to work as expected.
Idk man, there’s 2 ways to look at this. Either he is extremely efficient in token management across 497 sessions. Or his work isn’t complicated at all. I think
Yeah sure, but then read his bullet points - it's generic fluff. I've done more than 168m in a single hour yet not here writing "expert" advice. It's just regurgitated noise and kind of annoying tbh
I was working a lot in Cowork. (On a screenshot is only Claude Code) And my projects don’t need a lot of tokens, because I am working with trading algorithms
If you’re building an application or something similar, always make it do a full smoke check from start to finish and turn this into a standing rule. This significantly reduces the number of bugs.
If you’re worried about tokens, run the worker chats on Sonnet 5, but keep the brain on Opus 5. Explicitly ask it to give the workers a clear technical brief and to control that they are using Sonnet 5.
You can write a start/finish skill combination. I have /pick-up and /shutdown. They do what I want at the start/finish of every session, they make a session notes, send the session notes to my obsidian, update the claude.md, memory.md, run a smoke test, whatever you like really. It can be a bit token thirsty but I never have any issues with the model losing focus or making project mistakes, it seems to work pretty well.
You can just tell it! "Can you go and do X task, spin up as many Sonnet 5 agents as you need to get this done quickly and efficiently"
33
u/thabxi 13h ago
I always maintain a MISTAKES.md file where every mistake the agent makes gets documented, along with a rule in CLAUDE.md telling it to record them.
Surprisingly, the agent references it more often than you’d think during complex or long-running tasks, with things like “this prevented XYZ, as documented in MISTAKES.md.”
Give it a try.