The Foundation — Your Filesystem and Markdown
How I'm partner with Claude Code for more than coding
I remember the start of every school year as a kid. That hopeful feeling that this would be the year I’d actually use a planner. Write stuff down on paper — not on my hands or arms. Keep my backpack from becoming a fire hazard of crumpled papers. Every year, those hopes were dashed approximately 3.2 days after the first bell. Yes, I was blessed with ADHD so organization has always been a unique experience.
The challenge has always been finding an organizational system and ways to work that fits who I am — versus trying to fit myself to the system.
I’ve tried every productivity tool. Notion for years — always ended up back at Google Calendar with tasks spread across many days and too many browser tabs. Todoist. Roam. Obsidian with seventeen plugins. They all eventually fail. Not because they’re bad tools, but because they want me to think like them.
Most of my ideas don’t happen at a desk. They happen on the move — walking the dog, on a run, in the car. The “ah-ha” moments. The “oh-shit, I need to do X” realizations. Any system that assumes I’m seated at a computer when insight strikes is already dead.
Over the past year, taking inspiration from Daniel Miessler’s work on Fabric and my good friend Pedram Amini, I’ve been taking control. Building the organization system to fit me — not trying to fit myself to an organization system.
This is the first in a multi-part series sharing the commands, skills, MCP servers, Obsidian plugins, and general ways I’m leveraging Claude Code, markdown, and MCP to get work done. It’s not intended to be prescriptive. Some of what I’m doing might seem weird — cool, keep it to yourself. I hope by sharing, others can take inspiration like I did and find their own path with these tools.
I don’t believe AI gets rid of people. I think it helps highly creative people optimize in ways that weren’t ever able to before.
The Setup
Here’s what I’m running. This isn’t “you need all of this” — it’s context for what follows.
Claude Max — Anthropic’s subscription tier.
MCP Servers (tiered by how often I use them):
Every project
Firecrawl, Perplexity — Research, web scraping, search
Varies by project
Chrome DevTools — Visual validation, layout detection, browser automation
Google Calendar, Google Docs, Google Slides — Built for my own purposes, stayed tune for these :)
PostHog, Sentry, LangFuse — When debugging or analyzing issues, I built my own Sentry and Langfuse MCP servers.
Plugins (Claude Code)
superpowers — Workflow orchestration — skills, commands, process enforcement
episodic-memory — Conversation history across sessions — Claude remembers what we discussed last week
The MCP servers extend what Claude can do. The plugins change how it works. More on both in later posts.
Your File System is the API
My directory structure is the API contract with Claude Code. The directory structure isn’t just organization — it’s the interface through which Claude discovers what you know.
When you open Claude Code in a directory with a CLAUDE.md file, it reads that file automatically. Every conversation starts with context. No copy-pasting. No “let me share my project structure.” The model already knows where things are — because you structured it to.
Claude navigates via file operations — Read, Glob, Grep. Your directory structure determines what it finds and how fast.
Structure creates semantic meaning — context/ means evergreen facts. projects/ means active work. journal/1-1s/ means people over time. Claude learns this mapping from CLAUDE.md, then uses your structure to find things.
Paths are the interface — When CLAUDE.md says “Company strategy → context/<company>/strategy/”, that’s an API endpoint. Claude calls it by reading that path.
No database, no abstraction layer — Just folders. Claude’s “knowledge” of your world is literally your file tree. Change the structure, change what Claude can discover.
This isn’t about building the perfect knowledge management system. It’s about building one where the AI navigates like you do.
tl;dr: Make your file system the API contract with Claude Code. Structure it for the model to think like you.
The Implementation: Directory Structure
Here’s what I landed on after several iterations. Early versions had too many folders. I kept confusing “context” (evergreen facts) with “projects” (active work). My 1-1 notes were organized by date, which meant I could never find what someone said three months ago.
The current structure:
pai/
├── context/ # Source of truth — evergreen facts
│ └── <company>/
│ ├── strategy/ # Company direction, positioning
│ ├── product/
│ │ └── features/<topic>/ # Feature specs, decisions
│ ├── team/<person>/ # Team profiles, roles
│ └── terms.md # Glossary
│
├── learning/ # External wisdom — what I've learned
│ ├── domains/ # By subject area
│ │ ├── ai/ # AI/ML concepts, tools, patterns
│ │ ├── leadership/ # Management, org design
│ │ └── product/ # Product strategy, discovery
│ └── thinkers/ # Mental models from people
│
├── projects/<name>/ # Active bounded work
│ ├── sources/ # External inputs (not written by me)
│ ├── drafts/ # Work in progress
│ └── artifacts/ # Finished deliverables
│
├── journal/ # Time-based content
│ ├── 1-1s/<person>/ # Meeting notes by person
│ ├── weekly/ # Weekly digests
│ └── daily/ # Daily notes (optional)
│
├── inbox/ # Raw capture — GITIGNORED
│ ├── transcripts/ # Meeting transcripts
│ └── podcasts/ # YouTube/podcast transcripts
│
├── capture/ # Quick capture (sorted later)
│
└── tmp/ # Scratch work — GITIGNOREDThe why matters more than the what:
context/ — Evergreen facts separated from time-based content. When Claude needs to know about my company’s strategy, it looks here — not buried in meeting notes.
inbox/ — Raw automation output stays out of git. Meeting transcripts are noisy. They feed into other documents but don’t need to be versioned.
projects/ — Flow pattern: sources → drafts → artifacts. I always know where a piece of content is in its lifecycle.
journal/1-1s/ — Notes by person, not by date. When I need context on a direct report, I read their file — not hunt through a calendar.
learning/thinkers/ — External wisdom lives in personas, not scattered notes. When I want a famous CEO or thinker’s perspective on an idea, I have a file for that.
Your structure will look different. Maybe you don’t do 1-1s. Maybe you need a clients/ folder. The principle is the same: make it navigable for the model.
The Tooling: Obsidian + Git
One detail that makes this work: I edit everything in Obsidian, and the whole directory syncs to a private GitHub repo.
Obsidian gives me the speed of a native app with wiki-style linking between files. But I treat it as just a markdown editor — thats it, its not a second brain, not a plugin playground. The value is in the files, not the app.
Git gives me version history without thinking about it. When Claude makes changes to my files (yes, I let it edit my notes), I can see exactly what changed and roll back if needed.
No database. No proprietary sync. Just markdown files in folders, versioned like code.
CLAUDE.md: The Guide
Here’s the piece that ties it together: `CLAUDE.md` sits at the root of the directory. When Claude Code opens a project, it reads that file automatically.
Early versions of mine were too long. I tried to document everything — every folder, every convention, every preference. But Claude reads this file at the start of *every* conversation. Bloat costs tokens and dilutes focus.
Now I keep it tight:
# CLAUDE.md
## What This Is
Peter's personal knowledge base for thinking, writing, and strategy work.
## Directory Structure
[The tree from above — abbreviated]
## Key Reference Paths
- **Company strategy** → `context/<company>/strategy/`
- **Team profiles** → `context/<company>/team/<person>/`
- **Active projects** → `projects/<name>/`
- **My writing voice** → `.claude/skills/writing-voice.md`
## Interaction Principles
- Lead with the point — summarize first, then expand
- Challenge my thinking — agreement without scrutiny isn't helpful
- Be direct about uncertainty — ask targeted questionsThree things I keep pushing toward — though my actual CLAUDE.md is messier than this ideal:
1. Paths over descriptions. Don’t explain what’s in a folder — tell Claude where to look. It can read the files itself.
2. Principles over rules. “Challenge my thinking” shapes behavior better than “always provide three counterarguments.”
3. Keep it focused. If something doesn’t need to be in every conversation, it doesn’t belong here. Put it in a more specific file that Claude can find when relevant.
Shareable Artifacts
If you want to try this, here’s a starting point.
Directory scaffold script:
#!/bin/bash
# scaffold.sh — creates the base structure
mkdir -p context/{company}/strategy
mkdir -p context/{company}/product/features
mkdir -p context/{company}/team
mkdir -p learning/domains
mkdir -p learning/thinkers
mkdir -p projects
mkdir -p journal/{1-1s,weekly,daily}
mkdir -p inbox/{transcripts,podcasts}
mkdir -p capture
mkdir -p tmp
touch CLAUDE.md
echo "# CLAUDE.md" > CLAUDE.md
echo "" >> CLAUDE.md
echo "## What This Is" >> CLAUDE.md
echo "[Describe your repo's purpose]" >> CLAUDE.mdWhat to gitignore:
inbox/
tmp/What’s Next
That’s the foundation. Your file system is the API. Structure it for the model, not just for yourself.
This setup doesn’t do much on its own — it’s infrastructure. The value comes from what you build on top of it: syncing with the tools your team actually uses, automating capture from meetings and podcasts, building skills that know how to navigate your files.
Next in the series: making this sync with Google Docs, Notion, and the other tools that aren’t going away just because you’ve seen the markdown light.