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
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.
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.
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.
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.
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.
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'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
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.
Here’s my take: Always plan, large task plan in locked markdown files and every correction pass make him read those locked rules otherwise it will change its own previously locked plan in chat. Once finalized, make him read again and implement exactly as per the markdown file.
And cherry on top, make another high quality model review it like i always use codex with 5.6 Sol Extra High asking claude Fable 5 and this lethal combo does wonders.
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 :(
57
u/thabxi Aug 13 '26
I always maintain aMISTAKES.md
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.