About 6 months ago, I started figuring out a workflow that’s probably similar to what a lot of you are doing but I thought I’d share it. I think it’s been the foundation that’s helped me survive a lot of model inconsistencies and regressions (Opus 5 looking at you) and generally helped me make a better product with smarter agents. So buckle your seatbelts, boys and girls, as I dive into how I’ve figured out the best workflow for my projects. The Worklog - letters to the future At the end of every work session, I run the command /worklog . This is a reverse-chronological session log called worklog.md which lives in the project root. Its explicit purpose is knowledge transfer to future agents, not proof-of-work. The git history already proves work happened, this is more about the WHY. It’s capped to 2-3 sentences max, and the agent can expand to 5 sentences only for a really big gotcha or non-obvious root cause. The command has a ruthless quality gate that cuts sentences which report test results, narrate process (“investigated”, “confirmed”), enumerate files/counts, or could be replaced by simply reading the diff. Cut the fluff, get to the good stuff. Interesting tip for those seeking agent brevity: Agents would write the world’s longest run-on sentences, turning a 2-3 sentence summary into a whole paragraph. On a whim, I added into the prompt, " If every word you want to write cost $0.25, would you spend it on this sentence? " That ONE LINE made all the difference. It’s incredible how much more concise the agents got. At the end of the worklog session, the agent is required to re-read the KnownPitfalls.md doc and identify a Pitfall Relevance: by which it has to pick one of four verdicts: None Existing - Section N, already covered Existing - Section N: gap: X New Pattern candidate - X This one line is the key feedback mechanism for Step 3. The agent is explicitly blocked from writing to KnownPitfalls (more on that later), but since this agent knows the exact context of its work session history, it’s best equipped to make a recommendation on the pitfall relevance in a way that simply summarizing the work is not. Therefore the pitfall relevance recommendation is the biggest indicator based on the session history as to whether we’ve covered this before, or we’ve covered it but there’s a gap, or this is a whole brand new issue we’re dealing with. Known Pitfalls - learn from the past or repeat it KnownPitfalls.md lives in my /docs/technical folder and it’s the superpower for my agents. It’s the permanent anti-pattern doc documenting all the traps we keep walking into, and how to avoid them. The header of this doc is a “If you’re working on X, read section(s) N” routing table so that no agent has to read the whole doc, though I try to keep it pretty tightly scoped so agents can ingest the whole thing without too much token bloat. Each section of KnownPitfalls is self-contained: the rule, the wrong pattern, the correct pattern, and occurrence count (how often the worklog has addressed this) in the header. Sections are never renumbered so that old worklog entries that reference that number won’t break and destroy that memory. This is crucial for the auditor (next step), so new entries are always appended in the right category. The Key Benefit of the Pitfalls Doc: Both Claude.md and write hooks require the agent to first read KnownPitfalls before making any non-trivial changes to the codebase, and path-scoped rules + hooks auto load the relevant pitfall entries when certain files get touched. This one thing has saved me countless times . I’ll often see it in the agent’s workflow, where it’ll go something like “…but according to Section N of KnownPitfalls that would cause X issue, so I’ll make sure to Y…” Opus 5 specifically says this ALL THE TIME. Audit Worklog - where the magic happens Originally, when I first started shaping this system, the /worklog command had agents write directly to KnownPitfalls.md. The big problem is that every single agent thinks its work session is worthy of including as a pitfall. Before I knew it, the worklog was chock-full of 8-sentence paragraphs on CSS indenting and camelCase vs snake_case trip ups. This made me realize that I can’t trust the agent’s judgement as to whether or not what it was working on was a true pitfall or not. Enter the /auditworklog command. I run this distillation agent every 2-3 weeks or at a major version release. The auditor will read the last checkpoint marker in the Worklog, usually a ======Audit Checkpoint [Timestamp]======= line so it knows where we last left off, then it reads every Worklog session from that point onwards. The worklog auditor aggregates all Pitfall relevance: lines, clusters them by theme, and looks for patterns hitting 3+ sessions (including sessions from before the checkpoint to make sure we catch all pattern candidates), then reads the worklog entries to understand what the pattern + the fix was. It will triage the worklog by examining the actual codebase to understand what the correct pattern actually was and note it. The quality bar for inclusion must be a specific repeatable trap (“overflow: hidden on a grid collapse wrapper permanently breaks position: sticky”), not general advice (“be careful with CSS”), and must be project-specific. General React/TS knowledge is already in the model’s training, so it’s noise we avoid. Then, the Mandatory approval gate : it presents strong candidates / minor refinements / skipped-with-reasons , then stops. Nothing gets written to KnownPitfalls without a human yes. I’ll check over this and approve or block specific recommendations (though usually the auditor is spot-on for candidate approval). Then it will write new sections, refine existing sections with additional information, and then add a new Audit Checkpoint [Timestamp] divider line into the worklog. By making Auditor be the sole line of reason when it comes to the pitfall doc, it dramatically cuts down on noise or the “you totally gotta trust me bro, this is ABSOLUTELY a pitfall candidate, I have to write it down now or we’ll lose everything!” urgency that every agent has about its own work. The Auditor helps create a tightly scoped, context-aware, poignant memory system that all agents have to abide by when they write code. Using KnownPitfalls - an extra audit step Back in the workspace, after agents are done working, I have a pretty robust /verify command that deserves its own separate post. But one of the sub-agents that this command spawns is a KnownPitfallsAuditor. This subagent’s sole job is to read the entire KnownPitfalls doc, scan the code that was just implemented, and raise hell if the code breaks any of the pitfall guidelines. This is the classic “belt and suspenders” workflow where agents have to read KnownPitfalls before they write code, but then also during the audit process, they have to read it again and prove that no pitfall patterns were broken. This is separate from /worklog
- it’s purely in the audit process. If the agent raised hell about a pitfall and the main implementer fixes it, it becomes a part of the /worklog command’s memory to help future agents avoid the gap. Why not just use agent memory? Or Claude.md? Memory is iffy, honestly. And why would I want to bloat Claude.md with backend pitfalls that a frontend agent will never need? The key part about my workflow is that it is curated, precise, and triggers on all codebase changes . Agent’s don’t have to remember to use it, they’re required to. You also get the added benefit of the Worklog capturing all your sessions which future agents can scroll through to find “oh that’s when we implemented that piece.” Which in turn helps track down when bugs or issues might have first appeared. I, as the human, get to decide to run /worklog , meaning that if I determine whatever was implemented was trivial, or I’m having a read-only conversation, I’m not forced to run it. And I can run it multiple times per session if we’re doing a lot of separate work. This way I determine whether the worklog warrants a run , not an agent (going back to the problem of “every agent thinks its work is crucially important.” Can you give us some examples? Sure! Here’s a verbatim entry from the worklog for a major app-breaking issue I ran into: Worklog: 2026-05-06 07:28 (Regex Lookbehind issue) Fix: Replace regex lookbehind in InlineMarkdown italic pattern (Safari < 16.4 white-screen) Root cause for the macOS Monterey 12.5 white-screen report identified via the new boot diagnostics. The regex literal /(?<![\w])*([^\n]+)*(?!*)/ in src/components/settings/InlineMarkdown.tsx uses a negative lookbehind, which Safari/WKWebView only added support for in Safari 16.4 (macOS Ventura 13.3). On earlier WebKit (Monterey 12.5 / Safari 15.6), the parser throws “Invalid regular expression: invalid group specifier name” at module-parse time, which kills the entire JS bundle. Replaced with the same (|[*\w]) leading-capture-group pattern that src/lib/regexUtils.ts already documents and uses for the same compatibility reason. Build function updated to emit the captured boundary char as plain text alongside the <em>. Pitfall relevance: New pattern candidate — Safari 15.x WKWebView does not support regex lookbehind. The existing regexUtils.ts helper documents this for chapter-scanner code, but other regex literals across the codebase don’t reuse it. Worth a one-time grep (?<[=!] audit and a KnownPitfalls entry to make the constraint discoverable for future regex authors. Known Pitfalls Entry (after audit):
- Cross-Platform / WebKit / Tauri WebView (10+ occurrences) Affected: Any regex in TypeScript files, TipTap editor access patterns, drag-and-drop, clipboard, platform-specific APIs. The bug (regex): JavaScript regex lookbehind assertions ((?<=…) and (?<!..)) crash Safari/WebKit before version 16.4 (macOS < 13.3, e.g. Monterey 12.x). This is a parse-time SyntaxError, not a runtime error — the regex literal kills its containing module at parse, which kills the entire bundle for users on older macOS. No error boundary catches it. No frontend log fires. Symptom: white screen on launch, backend logs end at “App setup completed” with zero [FRONTEND] lines after. WebKit’s exact error string in DevTools is SyntaxError: Invalid regular expression: invalid group specifier name. The bug (TipTap): TipTap v3’s editor.view is a Proxy that throws when the EditorView isn’t mounted. Accessing it outside the editor lifecycle crashes the app on macOS. Real incidents: v1.2.0 white-screen (May 2026): a single regex /(?<![\w])*([^\n]+)*(?!*)/ in src/components/settings/InlineMarkdown.tsx — pulled into the entry chunk via AboutManager → ChangelogViewer → InlineMarkdown — broke launch for every user on macOS Monterey 12.x. Caught only by adding boot-time logging in index.html after the fact (the existing console.log patcher in main.tsx never ran because the bundle never executed). Fixed in commit 1b5c3aa. Rules: Never use regex lookbehinds. Use consuming group alternatives. The same workaround is already documented and used in src/lib/regexUtils.ts — reuse wordBoundaryRegex if it fits, or copy the pattern: Audit before commit: grep -rn ‘(?<[=!]’ src/ should return zero hits. CI doesn’t catch this; it builds successfully and tests pass on the dev machine (which runs newer WebKit). The bug only manifests on older macOS. Guard all editor.view access with try/catch or check editor.isDestroyed first. Test on macOS if touching regex patterns, editor extensions, or platform APIs. This is just one example of many where all the time+tokens spent solving an issue got put into the Worklog, raised as a pitfall candidate, and loaded into KnownPitfalls in a way that has prevented app-breaking bugs from ever going back into the codebase. TL;DR Three files, three commands, one loop: /worklog → after a session, the agent writes 2-3 sentences to WORKLOG.md on why something was hard, not what it did. Then it tags the entry with one line: Pitfall relevance: None / Existing / Existing-with-gap / New candidate . It cannot write to the pitfalls doc itself. KnownPitfalls.md → the permanent anti-pattern doc. Numbered sections, never renumbered, with a “if you’re working on X, read section N” routing table at the top. Hooks and CLAUDE.md force agents to read the relevant sections before they write code. /auditworklog → every few weeks, one dedicated auditor reads all the tags since the last checkpoint, clusters them, and proposes new sections. I approve or reject. Nothing lands without a human yes. Is it perfect? No. But it makes even Opus 5 stick to the past’s learned lessons and help it push into the future where new agents can learn from the mistakes and avoid them. Thanks for reading! Hope this helps! submitted by /u/callmejace
Originally posted by u/callmejace on r/ClaudeCode