One of the hidden costs of working with claude code across multiple sessions is context rebuild time. Every new conversation starts fresh. You might know where the project stands… Claude doesn’t . Getting back up to speed means re-explaining what you’re building, what decisions you’ve made, what’s done, and what’s next. On a complex project, this can feel like a real tax, and there’s a decent chance you’ll get lost in the weeds as well. I certainly have!
The standard developer response to this problem is CLAUDE.md. It’s a good idea, and worth understanding well. Anthropic’s guidance emphasizes putting the things Claude can’t easily infer from reading code into that file: build and test commands, key directories, environment setup, and — critically — failure modes or gotchas. The goal is to make Claude immediately productive in a new session without any orientation. The principle is density over verbosity: every line in that file is consuming context window, so make it earn its place.
I use CLAUDE.md, but I’ve found it solves for code level memory, not project-level memory. The why. The goals. The history of decisions. What’s been completed and what’s still open. The moment three weeks ago when you decided to change the approach. As far as I can tell, CLAUDE.md captures how the codebase works; it doesn’t capture why you’re building it or where you’re headed.
The /pm skill
My solution is a custom Claude Code skill I call /pm. When invoked, it either scopes a new project from scratch or picks up an existing one. Every project gets a folder in ~/topaz/projects/<project-name>/ — my Obsidian vault — with three files.
overview.md is the project brief: what it is, why it matters, what success looks like, and (for software projects) the stack, repo, and deploy target. tasks.md is a markdown checklist with priority tags, blockers, and completion dates. log.md is append-only — a timestamped record of every meaningful session, decision, and change.
When I start a session on a project, I ask Claude to read the project docs. In thirty seconds it knows where we stand: what’s done, what’s next, what’s blocked. No preamble, no recap. The overview tells it what we’re trying to accomplish. The tasks tell it the specific next moves. The log gives it the decision history. Together they work like a brief for a new contractor — except the contractor can read it in an instant.
What surprised me about this setup is how useful the scoping process itself is, independent of Claude. The questions /pm asks when initializing a project — what is this, why does it matter, what does success look like — are worth answering even when working alone. Writing them down creates clarity. And the task list isn’t just a to-do list for the AI; it’s how I keep track of what’s actually left across a dozen parallel concerns.
The personal site as a working example
I’ve been rebuilding davidtingle.com from scratch over the last week (my previous provider is shutting down). Over that time I’ve had probably a dozen Claude Code sessions touching different parts of the project: scaffolding Astro, building the writing feed, designing the lists page, a poker training tool I built to deploy on the site, and now the hosting setup. Each session has been different in scope.
Without project docs, each one would have started cold. With them, every session picks up where the last left off. The current tasks.md for the personal site shows hosting and DNS as the top two open items — both high priority — followed by tag filters on the /misc page, a micro.blog integration decision, and a few lower-priority design details. That’s the full picture, available instantly.
Here’s what those files actually look like mid-project:
log.md
## 2026-03-01 (session 2) - Split /misc into two equal columns: posts (writing) | projects - Added projects content collection sourcing ~/topaz/projects/*/overview.md - Widened body max-width: 900px → 1100px ## 2026-02-28 (session 3) - Replaced /stuff with /misc - Built Astro content collection from ~/topaz/writing/ at build time - Individual post pages at /misc/[slug] ## 2026-02-26 - Scaffolded Astro at ~/projects/davidtingle.com - Built homepage, photos, stuff pages - micro.blog JSON feed fetched at build time ## 2026-02-25 - Project created - Archived asocialfolder.com (56 files, 38MB) - Initial task list seeded
tasks.md
## Active - [x] Archive asocialfolder.com - [x] Decide on stack (Astro) - [x] Build the site - [ ] Set up hosting #high - [ ] Point DNS to host #high - [ ] Migrate /misc data #medium - [ ] micro.blog integration #low - [ ] Tag filters on pages #medium - [ ] Collapsed lists #medium - [ ] Printer's ornaments #low ## Blocked
The personal site also has a CLAUDE.md in the repo. It covers the Astro project structure, content directories, the dev and build commands, and a gotcha about the micro.blog JSON feed needing a CORS proxy locally. That’s where code-level context lives. The project docs in Obsidian are where project-level context lives. They serve different purposes and don’t overlap.
Closing the loop with /log
The system only works if the docs stay current. A project log that’s two sessions out of date is worse than no log — it creates false confidence.
The /log skill handles this. At the end of a session, /log appends a summary to log.md, marks completed tasks in tasks.md, updates the project status in overview.md, commits the code changes with a drafted message, and offers to push. The whole wrap-up takes a few minutes. The payoff is that the next session starts clean.
This has turned out to be one of the more valuable habits the workflow enforces — not because the logging itself is hard, but because it’s easy to skip. Having a skill that does it for you means it actually happens.
What the comparison reveals
Putting CLAUDE.md best practices alongside the /pm approach makes the distinction pretty clean:
CLAUDE.md is optimized for what — what commands to run, what files matter, what patterns to follow, what gotchas to avoid. It’s context that’s relatively stable across sessions and tied to the codebase itself.
The project docs are optimized for why and where — why you’re building this, where you’re headed, which tasks are open, what decisions have been made. It’s context that evolves over time and sits outside any individual codebase.
Both are answering the same underlying question — how do I give Claude the context it needs to be useful right now? — but they’re answering it at different levels. A developer working only with CLAUDE.md has code memory but not project memory. The skills-based system I’ve built tries to provide both.
The sessions where I’ve gotten the most done with Claude are invariably the ones where I started with clean, current context. The ones that have gone sideways have usually been improvised from a cold start.
Ben Guo made the observation that “plans are the new code.” I think that’s right, and the workflow I’ve built is essentially an expression of that idea. Good documentation — clear goals, a running task list, a decision log — is what makes a non-engineer meaningfully productive with AI tools. Not prompt engineering. Not the right model. The quality of the inputs.
Context is the bottleneck. Solve for that first.