Worldbuilding with Claude Code

Introduction

There’s ongoing debate about AI-generated creative content, for many good reasons. I don’t think that it’s practical to assume that AI will never be an adequate creative engine, but let’s assume that, for the moment, it is not. Having AI write your worldbuilding content, or your novel, or your TTRPG content, robs you of the experience of building it yourself, and sours most of your readers or players as well. That said, writing or creating directly with LLMs is outside the scope of this post.

This post is about the myriad other uses of AI (in this case, Claude Code in specific) that avoid that debate entirely. Claude isn’t generating fiction in any of the workflows below. It’s doing the unglamorous structural work around content you already wrote, or preparing you to do more of the writing. If you’re building a setting of any size you’ll eventually have hundreds of notes scattered across multiple sources. This creates a growing risk that you’ve contradicted yourself somewhere.

To help fight that risk, you’re using the tool to organize notes, extract valuable information from raw brain dumps or transcripts, find contradictions in your established lore, and all of the other little jobs that you do to keep a large corpus of knowledge from becoming too unwieldy to be reliable.

A few things up front:

1. Everything assumes plain markdown files (text with a little formatting) on disk. Claude Code reads, writes, and edits those directly.
2. None of this requires Obsidian, but the patterns you’ll be working through mesh well with it. If you use Obsidian, see Obsidian for Worldbuilders for the organizational foundation these workflows sit on top of. You can get Obsidian at https://obsidian.md
3. The setup matters more than the prompting. Get the next section right and most of the rest is Claude doing what you’d have done yourself if you’d had time.
4. You can get Claude Code at https://claude.com/claude-code. It has a sibling application, Cowork, which is the friendlier version. Cowork only works in the folder you open it in and runs in a bit of a sandbox that Claude Code doesn’t. Almost anywhere I say Claude Code, Cowork can be substituted.

The Setup

The setup dictates everything else that you do, so here are three tasks to get done before you start building with Claude’s assistance.

CLAUDE.md

The CLAUDE.md file is a Markdown file at the root of your project that Claude Code reads automatically every session. It’s where you tell Claude what your world is, how it’s organized, and what conventions it follows.

Treat it as an orientation for the LLM each session, not documentation. You’re writing for a smart collaborator but one who’s brand new to the project and needs to come up to speed quickly before you begin a working session. You can include things like:

• The world in a few paragraphs. Core premise, defining constraints, what makes it unique. Not exhaustive descriptions, just the main points and sweeping stuff. Your world is an ice planet, and there are furry giant creatures there, as well as a secret base for interstellar rebels, and someday, the evil empire will come for them. That kind of thing.
• Directory layout. What lives where: People/ for your characters, Places/ for locations, and so on.
• Metadata conventions. If you use Obsidian, document the Properties you’ll be using in your notes, and if not, any similar frontmatter or metadata, and possible values. For more on the subject, take a look at Metadata-First Worldbuilding in Obsidian.
• Naming conventions. Spelling of proper nouns, casing rules, what gets a wiki link and what doesn’t in your notes.
• What’s canon vs. draft. How can Claude tell whether a note is established lore or speculative scratch work and ideas that aren’t really “officially” part of your world yet? This can be part of the Properties set above (status: draft) or some other method, file naming, or a banner at the top, or in-text tags.

Keep this file short. Under 200 lines is a good ceiling. CLAUDE.md goes into every session’s context window, so a sprawling file costs you context budget for no particular benefit. And a bonus: You can just say all of this stuff in a Claude Code conversation in an empty directory (or one with your existing world files) and it’ll make the CLAUDE.md for you. In fact, if you already have world files, you can also have it read them and shape the CLAUDE.md with this information in mind, then just review it yourself.

Git for everything

If you are familiar with Git, put your worldbuilding notes in a git repository, even if you’re the only one touching them. Two reasons:

1. The obvious one: backup and reversibility. When a session goes sideways and rewrites things you didn’t want rewritten, git diff and git checkout get you back. Always commit before you start a substantial Claude task.
2. The less obvious one: Claude can read your history. When you ask about something that depends on past work — “what did we decide about the Storm Court last month?” — Claude can run git log, read commit messages, and inspect old diffs to reconstruct what happened. Your commits become a queryable record of how the world evolved. Write commit messages that would help future-you understand the decision, not just the file change.

You don’t need a remote. A local repository is enough. If you push to GitHub or a similar service, remember to make your repo private, or gitignore anything you don’t want to be public.

If you don’t know Git and don’t want to learn, that’s ok too. If you aren’t going to use Git, or you are but with no remote, consider paying for the Obsidian Sync service or setting your notes/vault up in a cloud provider, so that at least you have a synced copy of your world data somewhere that isn’t on your machine.

A WORKING file

For larger projects, keep a short WORKING.md at the project root. It’s not a planning document, exactly. It’s a one-page snapshot, again, for Claude, not for you, of:

• What you’re focused on right now (one or two lines)
• Recent decisions or changes (last five to ten bullets)
• Upcoming TODOs or roadmap items or whatever you call them
• Open questions you haven’t resolved yet

The CLAUDE.md file is about the world and the project writ large. The WORKING.md file is about what you’re working on now. When you start a new session, this file gives Claude immediate context about where you left off and where you’re going next that would otherwise live only in your head and have to be constantly repeated to new sessions. Update it as you go, and let Claude do so as well, but don’t let it get too long. It’s not meant to document your project, just provide a little status update for conversation starts.

Together, CLAUDE.md, git (if you use it), and WORKING.md give Claude three views of your project. First are the facts of the world, next the history of how it came to be this way, and lastly what’s happening right now. Most of the workflows below depend on these.

Extracting Structure from Raw Input

This is where most of the day-to-day leverage lives. You produce raw material in formats that aren’t immediately useful. Long-form brain dumps, voice notes or transcripts, half-organized session prep notes, jotted quick notes that you slowly lose the ability to understand even though you wrote them. The work of converting all of that into discrete, properly-structured, properly-tagged notes doesn’t happen because it’s boring. Here’s how Claude can help.

Brain dumps to discrete notes

You’ve sat down and written, say, two thousand words on a region of your world. Locations, the people in them, the factions that are constantly at each others’ throats or those that are friends. Individual heroes or villains, perhaps even a few bits of history. It’s a single file, hopefully stored with your other world stuff, but it’s not the most useful it could be in this form. When you go looking for “what did I write about that fishing village in that one region?” three months from now, you won’t find it unless you remember what you called it (to search for it) or where it lives.

An example prompt that works for this, referencing a file sitting in my inbox folder:

Read inbox/drowned-coast-dump.md. Identify the separate entities within it, such as locations, NPCs, factions, events, creatures. For each of those, propose a new note in the correct directory with proper Obsidian properties on each file, following the conventions in CLAUDE.md. Before you write anything, search the existing corpus of information for any of these entities. If I’ve already mentioned them, propose an update or merge rather than a new note. If you see potential matches, but aren’t sure, let me know. Don’t write anything yet. Just give me a report of what you found and what you’d suggest to do.

Two parts of that prompt that are particularly important. First, “search the existing corpus” is what prevents Claude from creating a duplicate Lord Vance.md file when you already have one. Second, “don’t write anything yet” gives you a review checkpoint before any files change. Sometimes Claude can be overeager and do things you didn’t want in an effort to please you, so it helps to be explicit when you want a stopping point. Once Claude returns the report, you can scan the proposals, accept the obvious ones, “push back” (as it would say) on the wrong ones (“merge that one with the existing note” or “skip that, it was a half-thought I changed my mind on”), and then say “go ahead with these changes.”

What you’ll get back is something like:

Found in the dump:

• 4 locations: Salt Hollow (new), Granite Pier (new), Westwatch (already exists at Places/Westwatch.md — proposing update with new details), the Drowned Light (already exists, no new content).
• 3 NPCs: Mara Greel (new), Tomas Vail (new), the Harbormaster (no name given — flagging for clarification).
• 1 faction: the Salt Brotherhood (new).
• 1 event: the Sundering of the Eastern Reach (already exists at Events/Sundering.md — proposing minor update with the casualty number you mentioned).

The Harbormaster flag is exactly the kind of judgment call you want to see. Claude is correct not to invent a name, and right to surface that you’ll need to either name them or leave the note generic with just the title. That’s the difference between extraction and generation.

Voice transcripts to structured notes

Same target, messier source. You went on a drive, opened a voice memo app, and talked through your world for thirty minutes. Or maybe Wispr Flow or a similar transcription tool or even just voice-to-text on your phone gave you a raw transcript of your words. It might be full of false starts, “wait, scrap that, let me try again,” tangents that go nowhere, and the same idea expressed three different ways before you settled on the one you liked.

The prompt is similar to the brain-dump version, with one important addition:

Read inbox/drive-transcript-2026-04-15.md. This is a raw voice transcript. I changed my mind out loud, went on tangents, and corrected myself. Identify the actual decisions and specific entities, ignoring retracted ideas. Same proposal-only output as before. Flag anything ambiguous so I can clarify before you write.

The “flag anything ambiguous” instruction is the same sort of barrier as before. Claude is genuinely good at saying “you said X early on, then later said Y, and I think Y is the version you settled on, can you confirm?” That clarification round is fast but without it, Claude may do what it thinks you want without asking.

What you should not really expect Claude to do well though, is people-stuff. Sometimes it’s ok at it, sometimes not really. It often fails to catch sarcasm, tone shifts, the deliberate “I’m going to leave this ambiguous” choices. If you said “I don’t know yet, let me think about this more,” Claude may extract a tentative answer rather than respecting the unfinished state. That’s why the review at the end matters.

Post-Session: Session Notes to Wiki Updates

A caveat before we get into it is that this section is TTRPG-flavored. The pattern of extracting canonical worldbuilding from a stream of new material applies equally to fiction writers working from chapter drafts or scene notes, but the mechanics are different and the examples below assume you’re running a tabletop game. Adapt for your own work accordingly.

After a session, your notes contain a mix of things, most times. You’ll have pre-planned content that played out, planned content that didn’t actually happen at the table, improvised content you generated at the table, player contributions you accepted as canon, quick sketches of ideas that almost happened but didn’t. Some of it should become new canonical entries for your worldbuilding. Some of it should update existing notes. Some of it shouldn’t enter canon at all (table improv that didn’t quite land, false leads the players chased, mistakes you’d like to retcon later).

The default is doing none of this. You finish a session, you mean to update the wiki, the week gets away from you, and the session notes become their own solo ship that drifts away from the official one. Six sessions later you’ve got contradictions you can’t untangle, or you just forget the cool stuff you hoped to build off of.

Another example prompt:

Read sessions/2026-09-15-session-32.md. Identify three things from my D&D session notes, which include prep as well as actual notes from the table:

1. New NPCs, locations, factions, or events that should become canonical world content.
2. Updates to existing wiki entries based on what was revealed or developed in play.
3. Contradictions with established lore, places where what happened in session conflicts with what’s written elsewhere in the corpus.

Don’t write anything. Produce a report.

The output is a structured proposal very similar to the text intake above, but shaped more like worldbuilding for a TTRPG. New canonical entries to create (each with a draft note), existing entries to update (each with the proposed change as a diff), and contradictions surfaced (each with both passages quoted side by side).

Then you can decide what’s actually canon. Not everything that happens at a table belongs in the wiki. Sometimes a player contributed a great detail and you want it; sometimes you improvised something on the fly that isn’t worth writing down. Sometimes a contradiction means the session version wins, because only you ever saw the existing written thing. These are creative decisions that you can make after seeing the report, and then have Claude make the updates.

The week-of-getting-away-from-you problem still happens, but now when you come back to the session two weeks later, the changes are already made, or perhaps the report is sitting there waiting and the work is fifteen minutes instead of two hours.

Consistency Checking Across the Corpus

Using Claude to check for consistency across your world notes can be really useful in a few situations.

Reactive corpus sweeps

You suspect something is inconsistent, or you’re about to make a decision and want to know what’s already on a page somewhere:

Search the corpus for everywhere I describe the Storm Court. List the variants and flag any inconsistencies.

Claude reads the corpus and returns something like:

Five notes describe the Storm Court directly. Three describe it as ruled by Queen Mistral; one says “the Storm Queen” without naming her; one (drafts/courts-old.md, marked status: draft) says it’s ruled by a triumvirate. The triumvirate version is likely retconned — confirm and I’ll either remove the conflicting passage or delete the draft note.

That’s a thirty-second answer to a question that, done by hand, would mean searching the vault, hoping you caught all the mis-spellings or variations on a name, opening five files, and remembering which version you most recently committed to or actually used in your writing or your game. Bonus: If you want, you can also have Claude do the normalizing around whatever you decide.

Proactive: pre-write checks

Even more valuable, and underused, are pre-writing checks. You have an idea, but before you act on it, you check about the context:

I’m about to write a bunch of thoughts about how the Storm Court controls the eastern shipping lanes. Check the corpus — is anything there that might create contradictions or is there existing stuff I should pay attention to related to this?

Claude returns:

Two existing notes. places/Eastern Lanes.md says they’re controlled by the merchant guild “Three Anchors” and not the Storm Court at all. people/Captain Reyn.md describes Reyn as “a free trader on the eastern routes,” implying at least slightly that it is neutral territory. Adding Storm Court control would contradict these mentions.

You then either revise your plan, decide the new version supersedes the old, or pick a more careful framing. Either way, you’re not finding out about the conflict in three months when you’re rereading and notice you’ve quietly written two different things.

Periodic sweeps

For larger projects, run a full-corpus consistency check on a schedule, like monthly, or at least before any kind of publication or release. It’s a long task; let it run while you’re doing something else, and treat any reported things that aren’t directly related to your work at hand as a backlog to pick through when you have the time. Most items will be minor. The ones that aren’t are the ones you most needed to find.

Organizational Maintenance

The most boring section, maybe, and the one with the most return on investment.

These are tasks you should do regularly and almost certainly don’t, because each one is boring and you’d rather spend the time writing. Or doing… anything else. So have Claude do them instead. Task it to look for:

• Missing required properties. “List all notes in people/ missing the creature or factions field. For each, propose values based on the note content. Don’t write yet.”
• Tag drift. “Find all variants of the NPC tag, such as npc, NPC, npcs, character, characters. Show me the counts and propose a normalization.”
• Formatting inconsistency. “Some notes use ## Background, some use ## History. Show me the split and let me pick which to normalize on.”
• Orphan notes. “Find notes with no inbound links from anywhere else in the corpus. List each with a one-sentence summary so I can decide what to do.”
• Broken links after renames. “I renamed Lord Vance.md to Vance, Lord of Roost.md. Find every reference to the old name across the corpus and update.”
• Bulk properties operations. “Add region: Drowned Coast to all notes in places/Drowned Coast/ that don’t already have it.”

Scope your search precisely, ask for a report or proposal first, review the diff, make adjustments. None of these tasks are interesting. None of them produce creative output. All of them get neglected in personal projects until the corpus is unusable. This is, in my experience, the single highest-value category of Claude Code use for an active worldbuilder. Do this when you’re watching TV or something. Let it help do the housekeeping.

What to Watch For

The structural workflows above are not magic, and they have problems of their own:

• Claude can confidently misread. Especially with messy input like transcripts, half-organized brain dumps, ambiguous session notes. Review extraction output before committing it. Trust but verify and all of that.
• Subtext gets flattened. Deliberate ambiguity, tone, voice, “this is wrong on purpose because the in-world narrator is unreliable”. Claude tends to lump this stuff in as canonical information and miss the subtleties.
• Tag what’s machine-touched. Add a reviewed: false property or generated tag to properties on notes Claude has written or substantially edited. If you later discover a systematic mistake, you can find every affected note. If you review a note carefully and agree with its content, you can remove the tags.
• Commit before, diff after. Git is your safety net, if you’re using it. Use it every time you make a set of changes. If a diff ever surprises you, revert and try a smaller scope.
• The first prompt is rarely the right prompt. If Claude’s output is generic or wrong, refine the prompt with more constraints rather than accepting and editing. The prompt is part of the work; treat it that way.

None of these are reasons not to use the workflows. They’re reasons to use them with your eyes open, is all.

Conclusion

Claude Code earns its keep on worldbuilding the moment your corpus outgrows your memory of it, which for me is about five minutes after I write anything. The work it does best, like extracting structure from mess, surfacing contradictions, keeping metadata consistent across hundreds of files, is the work humans are objectively bad at staying focused on. It’s the stuff that goes undone in almost every personal worldbuilding project. None of it touches the part of worldbuilding that matters most. The vision, the choices, the voice, the writing, the ideas. You focus on those things and let Claude do the boring bits.