I had five files in my Claude Project. Strategy docs, published articles, reference material. Claude read them every conversation. Felt organized. Felt smart.
Then I deleted all of them.
Not because they were bad. Because Claude Projects has a gap that will drive you nuts the second you notice it: Claude can read your project files, but it can't update them. Read-only. Every single one. Desktop app, mobile app, web — doesn't matter. Same limitation everywhere.
So if you have anything that evolves — a content strategy, a spec, a reference that changes over time — you're stuck in this loop: download the file, manually delete the old version from the project, re-upload the new one. Every. Single. Time. It's brutal. On mobile it's genuinely painful.
I spent a month testing workarounds. Tried three different approaches. One of them not only fixed the problem — it turned into a better architecture than editable project files would've been anyway.
The Obvious Thing Didn't Work
My first instinct was to just move everything to Notion and delete the project files entirely. Makes sense, right? Claude has Notion access via MCP. It can read pages, edit pages, create new database entries. Problem solved.
Except — not really.
Without project files, Claude starts every conversation blind. It doesn't know what pages exist in Notion, doesn't know the database IDs, doesn't know the structure. You'd have to re-explain your whole setup every single time. "Go to my Content Hub, the database ID is cx532... look for the article called..."
That's not a workflow. That's a chore.
Some people suggested using a GitHub repo with Claude Code instead. And sure, that works great — if what you're managing is code. But these aren't code files. They're content strategies, brand guides, idea banks, reference docs with images, project trackers. A repo treats all of that like source code — raw text in a file tree. No formatting, no inline images, no tables you can actually look at without squinting.
Notion gives you an app. You open it on your phone, your laptop, wherever — and your docs look like docs. Tables look like tables. Images are right there. You're not opening a terminal or learning git commands to check your content calendar. Not everything belongs in a developer tool, and the people who need to touch these docs — PMs, designers, content leads — shouldn't need to learn version control to update a brand guide.
Watch: Why Notion beats GitHub repos for non-code projects →
The Thing That Actually Works: One File That Knows Where Everything Lives
Here's what I landed on — and it's almost embarrassingly simple.
One markdown file. Lives in your Claude Project. Maybe 40 lines long. I called mine CONTENT_HUB.md.
It doesn't contain your actual content. It's a map. Think of it like a table of contents for a book you keep in a different building. The overview file tells Claude: here's where the Notion hub lives. Here's the database ID. Here's what properties exist. Here's what's been published. Here are the rules and guidelines for this project.
That's it.
Claude reads this file automatically every conversation — because it's a project file. Instantly knows the lay of the land. When it needs the actual content of an article or a doc, it fetches from Notion. One tool call. Takes a few seconds.
And here's the key — Claude can write back. Edit a draft? Update a status? Add a new entry to the database? It just does it. In Notion. Where the content actually lives.
The project file stays lightweight and stable. The Notion database stays current and editable. They work together.
If you're an engineer who uses Claude Code, you already know this pattern — it's exactly what a CLAUDE.md file does for a codebase. A small file that tells Claude "here's how this project works, here's where things live." Same architecture, just for non-code work. And unlike CLAUDE.md, this setup lets Claude write back to the system it's pointing at.
Why This Is Better Than You'd Think
The obvious win is editability. But there are a few things I didn't expect.
Your context window stops suffocating. When I had five project files loaded — three full articles, a strategy doc, a standalone post — that's a lot of tokens consumed before Claude even reads my first message. The overview file is maybe 50 lines. Everything else gets fetched on demand. My context window went from stuffed to breathing room.
It scales without bloating. Say you've got a dozen docs in your project — specs, briefs, meeting notes, whatever. You don't need their full text loaded every conversation. But you do need to know they exist, what they're called, and where they live — in case you want to reference or update them. The overview file handles that. When you add new docs, the overview grows by a couple lines. The old approach? More and more project files until the context window is packed with content you haven't touched in months.
Version history comes free. Notion tracks every edit. If Claude writes something wrong — edits an article intro badly, overwrites a section — you roll it back. Project files don't have that.
It works from your phone. I dictate all my prompts on Claude Desktop via SuperWhisper. The Notion setup works identically on mobile — Claude reads the overview file, fetches from Notion, writes back. No re-uploading files from your phone's file picker. That workflow was genuinely painful before.
Watch: The full setup walkthrough →
How to Set This Up Yourself
Takes about 10 minutes.
Start a conversation in your Claude project and tell Claude to create a Notion hub page. Give it a name, tell it what database properties you need — type, status, tags, dates, whatever makes sense for your project. Have Claude migrate your existing project file content into Notion pages.
Then — the important part — have Claude generate an overview file. One markdown file. It should contain the Notion page URLs, the database ID so Claude can create new entries, a summary of what each page is, and any rules or guidelines for the project.
Download that overview file. Add it to your Claude project. Delete all the other project files. They live in Notion now.
That's it. Every conversation going forward, Claude reads the overview, knows where everything lives, fetches what it needs, writes directly to Notion.
I made two starter templates you can customize in less than a minute — grab them here
The Bigger Picture
This isn't really about Notion. Or project files. Or even Claude.
It's about a pattern that keeps showing up everywhere I look: the best AI workflows aren't the ones where you give the AI all the information upfront. They're the ones where you give it a map — and let it go find what it needs.
One lightweight file that says "here's what exists and where to find it." That's the whole move.
And honestly? If Anthropic eventually lets Claude edit project files directly, this setup still wins. Because the separation — stable map in the project, living docs in Notion — is just a better architecture for anything that changes over time. You want your persistent context to be small and stable. You want your working documents to be wherever gives you the most flexibility.
The map doesn't need to change every time the territory does.
I'm a software engineer at The New York Times (previously Amazon), currently using Claude Code extensively in production. I write about what actually works, not what theoretically should.