Why Claude Code is a Stalactite (And Why That Matters): Part 1 of The Claude Code Chronicles
ℹ️
Disclaimer: I am not affiliated with, employed by, or sponsored by Anthropic. I am a paying Claude Pro subscriber and receive no compensation or endorsement for mentioning Claude in this article. All opinions and experiences shared are my own.
You're working with Claude Code. It's brilliant—until you close the terminal. Then the context is gone. You start the next session explaining everything again. It's like water running off a surface: powerful in the moment, leaving nothing behind.
I discovered something different while optimizing my website's page speed. A simple workflow that turns Claude Code from flowing water into something permanent: a stalactite.
The Stalactite Principle
Think about how stalactites form. Each water drop deposits minerals. Nothing dramatic happens with a single drop. But thousands of drops over time? You get complex, permanent structures.
Without persistence, your Claude Code workflow looks like this:
- Water flows, does its work, disappears
- Each session starts fresh
- Context lives only in your head
- AI assistance is brilliant but ephemeral
With persistence, everything changes:
- Each drop deposits minerals (GitHub Issues)
- Structure builds incrementally
- Context accumulates over time
- Small repeated additions create complex formations
The key insight: GitHub Issues become the mineral deposit that persists between sessions.
How One Sentence Generated a Complete Spec
Here's what this looks like in practice. I gave Claude Code one sentence:
"PageSpeed Insights found some concerns about my page, create an issue for this please."
I gave it 10 seconds. What did Claude Code give me back?
Issue #96 with:
- 5 distinct problem areas (images, JavaScript, fonts, caching, CSS)
- Impact analysis for each problem
- Proposed technical solutions
- Acceptance criteria
- Complete technical context (stack, key files, constraints)
- Testing plan
- Priority assessment
It gave me a complete project specification.
But here's the real magic: I could review it before any code was written. Claude showed me its understanding of the problem. I could catch misalignments, clarify requirements, adjust the approach—all before a single line of code changed.
This isn't a party trick. This is the first mineral deposit of my stalactite. Every future session can reference this issue. The context doesn't disappear when I close the terminal.
Why This Changes Everything
1. Track What Actually Got Done
Issues don't just start as plans—they end as reality documentation. When I finished the optimizations:
- ✅ Logo converted to WebP: 73% size reduction
- ✅ JavaScript chunking improved
- ✅ Font preloading implemented
- ❌ VitePress internal CSS optimization: not feasible (documented why)
- ❌ Some caching strategies: blocked by VitePress architecture (explained in detail)
Clear distinction between "completed" and "not feasible." No guessing months later what actually happened.
2. Break Overwhelming Tasks Into Batches
Large tasks overwhelm Claude Code's context window. Issues let you organize work into logical chunks:
- Session 1: Images and fonts
- Session 2: JavaScript and caching
- Session 3: Testing and validation
Each section tackled separately. Commit after each batch, reference the issue. The stalactite grows layer by layer.
3. Fast Context Recovery
Come back days later. Tell Claude Code: "Continue work on Issue #96."
It reads the issue. Picks up exactly where it left off. Zero time spent re-explaining.
(There's more to this story—the issue is just the beginning. In the next post, I'll show you the complete workflow that makes this context recovery automatic.)
The Self-Documenting Loop
Here's what blew my mind. The complete workflow:
- I ask Claude Code to create an issue
- Claude Code works through it systematically
- Claude Code creates a PR
- I merge the PR
- I tell Claude Code: "The PR is merged, please update the issue"
- Claude Code updates the issue with ✅/❌ checkboxes, actual results, and lessons learned
Zero manual documentation. Claude Code manages the entire lifecycle. The stalactite builds itself.
Claude Code Audits Its Own Work
After implementing Issue #96, I noticed PageSpeed still showed problems. I told Claude Code:
"The PNG is still being used and X-Frame-Options isn't allowed in meta, create an issue to fix this."
Claude Code created Issue #100 that:
- Audited its own previous work
- Explained what was marked complete but didn't actually work
- Provided technical explanation (X-Frame-Options MUST be HTTP header, not meta tag)
- Listed specific files and line numbers to fix
- Offered multiple solution options with tradeoffs
- Linked back to parent Issue #96
Claude Code can correct itself through issues. It reviews its own work, identifies gaps, and creates follow-up tasks. The stalactite doesn't just grow—it self-corrects.
Your First Stalactite
Next time you work with Claude Code, try this:
"I have [problem/feature], please create an issue for this."Watch what it generates. Watch how it structures the problem. Watch how it documents as it works.
Each session deposits knowledge. The stalactite grows. The context persists.
Not using GitHub?
This works with any persistent system Claude can read:
- Local markdown files (
docs/tasks/feature-name.md) - Issue trackers (GitLab, Jira, Linear)
- Note-taking apps (Obsidian, Notion)
The key is persistence across sessions. GitHub Issues just happen to be perfectly designed for this workflow.
What's Next
This is just the beginning. In the next post, I'll show you the complete 6-step workflow I use—from problem to merged PR to updated documentation—with only minimal prompts from me.
And after that? I'll show you something that will completely change how you think about AI-assisted development.
(Hint: What if you could run multiple Claude Code instances in parallel, all sharing the same memory?)
Try It Today
- Start a Claude Code session
- Say: "Create an issue for [your task]"
- Let Claude Code structure it
- Watch your first stalactite deposit begin to form
Key takeaway: 10-second prompts → comprehensive persistent documentation that Claude Code manages itself.
This blog post was co-written with Claude (Chat for ideation and outline, Code for assembly and refinement). The experiences, insights, and creative direction are human; the execution and polish are collaborative.