AI Workflow for Game Designers

No Fabricated Numbers — A Six-Month Field Manual for Claude Code, Prompts, Validation, and Production Memory

The 304 rules, 48 tools, and automation systems that a director with 24 years in the industry actually ran on a mid-sized (10–50 person) team — exactly as they were used

By Minsoo Lee · 2026

Everything in this book is current as of the first half of 2026. Pricing, models, and features of AI tools change quickly, so please check each official page for the latest figures and installation steps.

Distribution and Copyright

This book is released free of charge, in the hope that it will be read widely. But whether you are reading the Korean original or an English or Japanese translation, one fact must stay attached to it everywhere: the original author of this book is Minsoo Lee (이민수).

• License: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 (CC BY-NC-SA 4.0)
• Original author: Minsoo Lee (이민수), 2026
• Canonical edition: https://eremes81.github.io/game-design-ai-practice (the author's GitHub Pages — the canonical edition, under the author's editorial control)

You are free to do the following. Personal study, noncommercial sharing and quotation, noncommercial translation, and use in internal study groups — provided you credit the original author, include a link to the canonical edition, and state clearly if you have modified the content or carried it into another language. Derivative works must be shared under the same terms.

Please ask for permission first. Commercial publication or sale, use as course material in paid classes, inclusion in a company's products or services, and any redistribution that removes the author credit.

The knowledge in this book is complete in this one volume, and it is free as it stands. If it helps you and you would like to support the author, the official e-book and the paid kits are a way to do that.

Preface — A Book Written Three Times

This book was written three times.

The first version was not a book at all — it was an internal company manual. Over six months of running an AI workflow at work, I pinned decisions, tools, and procedures down in writing so the team would never have to ask about the same rule twice. It was not made for publication; it was an operations document, built up to cut down on daily repetition. That is where this book's concreteness comes from — it is not based on examples invented for a book, but on a manual that was actually in service.

The second was the first manuscript that turned that manual into a book. It ended up as a plausible-sounding survey of "look what AI can do." It had a lot of tables, and a lot of numbers demonstrating impact. Most of those numbers carried a note in small print: "illustrative figures." When I reread it, that was its biggest flaw. It talked about using AI without ever showing a real screen, and it talked about impact while citing made-up numbers. In moving the manual into book form, I had managed to lose the very concreteness that made it worth writing.

So I wrote the whole thing again, a third time. That is the text you are holding now. I brought back the concreteness of the internal manual, and I kept the book's principles simple.

First, every chapter shows you a real session from start to finish. The full prompt I typed, the raw output the AI produced, what I rejected in that output, and how I made it redo the work — all of it is here. No chapter ends with the sentence "AI takes care of it."

Second, every number is one of three kinds. A public standard anyone can verify (model token pricing, accessibility guidelines), a constant actually present in my system's code, or a value explicitly labeled "this is my estimate." There is not a single fabricated savings table. I made honesty the differentiator.

Third, I quote, as is, the real system I ran in production for six months. The 304 decision cards (atoms), the 48 tools (skills), the hook that automatically pulls in relevant memory on every input, the memory structure that lets one person run four people's worth of collaboration context — all of it. Not an abstract "some tool," but the actual file names, code, and scores, written down as they are. In the worked examples I masked only company and project names and the names of teammates; the concreteness of the workflow is untouched. (The company that gave permission to publish this book is named openly in the acknowledgments — because they agreed to it.)

I am a game designer with 24 years in the industry. I got my start doing QA and review on single-player games, and went on to direct an MMORPG that ran in dozens of countries, to work on the early development of a 200-person AAA MMORPG, and to handle live ops for a global mobile MMORPG — a career spent building RPGs, MMORPGs, and their variants. On projects like Ragnarok Online, Bless Online, and the MIR series, I served as director, design lead, and systems designer, and at times as PM; I also once founded a small mobile game company.

To be honest, I was made a director too early. After that came a long stretch back in the trenches: working data sheets and combat numbers hands-on as a systems designer, producing quests and NPCs line by line as a content designer, planning events, churning out new content. Many of the workflows in this book were born in that seat — the seat where you get your hands dirty rather than manage — out of the simple wish to somehow cut down on the repetition. Today I lead a mid-sized (10–50 person) team as the design director of an MMORPG in active development, but the tools in this book did not come from a director's management kit; they came from a practitioner's hands. That is why the system in this book is not theory but a working environment that runs every day. The book also covers, in exactly the same way, one small puzzle game I built alone at home — quoting that game's actual git commits and code.

AI will not replace a game designer's job. What it does is free your hands from the busywork. What you do with those hands is still up to you. I hope this book serves as a practical guide to that transition.

How to Read This Book

You do not have to read this book in order from cover to cover. Pick the route that fits your situation. If terminals and installation are new to you, open to 1.0, "Before You Begin," before anything else — it is the chapter that eases the fear of the black screen first.

Every chapter ends with a "Try It Yourself" section. The goal is not a chapter you read and close, but one that gets your hands moving at least one step in your own environment, today.

One more word for readers who work outside games. Many of this book's workflows — turning meeting notes into decisions, tracing a decision's ripple effects, verification gates (this book's term for a quality gate where a human or a checker verifies output), cost management, copyright and ethics — work as is, with no connection to games. Feel free to read "game design" as your own job. The "Beyond Games" box in each chapter is the bridge, and if you are short on time, the 90-minute express course (17.1 → 16.2 → 22.1 → 21.1) alone will let you feel the core skeleton with your own hands.

Let me draw one distinction here. In this book, "solo" is used in two senses. One is the solo director — a lead who carries several people's worth of collaboration context alone. The other is the solo or hobbyist developer making a game by themselves. The "Solo Scale-Down" at the end of each chapter is for the latter: it lays out how to take just that chapter's core with no team and no company folder.

You can read the book straight through as a single volume, or split it into two halves — Parts 1–15, "foundations and disciplines," and Parts 16–24, "process and operations" — and start with whichever you need. And most of the code in this book runs as is with no external dependencies, using only the Python standard library. Only a few tools, such as the relation graph, need packages beyond the standard library (networkx, PyYAML), and in those spots a one-line install (pip install …) sits right next to the code. Apart from those cases, there is nothing extra to download — you can copy a code block and run it right away to see for yourself.

If a term stumps you, do not stop there — move on for now. If the black terminal feels foreign, that is not a flaw in the tool but a matter of familiarity, and Chapter 1.0 and Part 1 will close that distance with you.

The Easiest Way to Use This Book

Finally, a tip on the fastest way to put this book to work: feed the book itself, whole, to an AI tool like Claude Code.

This book was not written for human readers alone. The full prompts, code, and verification procedures in each chapter are written in a form an AI can understand and reproduce directly. So, in your own project folder, you can hand this book to an AI — as a PDF or as plain text — and ask something like, "Read the consistency-check patterns in this book and build a checker that fits our data sheets." The AI will then set up that chapter's workflow adapted to your environment. Both routes are open: building along chapter by chapter with your own hands, or handing the whole book to an AI and building together.

One thing does not change, though. The final call on what to adopt and what to reject is — as this book repeats from beginning to end — still yours. Even if you have an AI read the book and install the system, the seat where a human reviews what that system produces stays occupied by a human. Even the easiest way to use this book runs on that principle.

One Promise

No table in this book contains a number inflated to persuade you. Instead of overstating the impact, I show you the structure that produces it. Move the same structure into your own project, and you will measure your own numbers. That is the most honest help this book can offer.

The Promise Behind the Word "Reconstruction"

Throughout this book, the outputs in worked transcripts often carry the label "reconstruction" — for example, "Step 3 — Claude's Output (Reconstruction)." Let me make one precise promise, just once, about what that word preserves and what it touches. A book that puts honesty on its cover must not leave this spot, of all spots, blurry.

"Reconstruction" does not mean invented; it means an actual session, edited. The boundary runs like this.

Put another way, no reconstructed output adds an inflated number or a success that never happened. It was anonymized, excerpted, and tidied for the page — nothing more. Nowhere has a failed output been rewritten as a success; if anything, I deliberately left the failures in, because they are what show you what a human rejects. (By contrast, anywhere code execution results or system logs are marked "measured" or "quoted verbatim," they were carried over without editing.)

Translator's note: In this edition, the prompts and outputs inside code blocks have been translated into English for readability. All worked transcripts in this edition are translations of the original Korean sessions — not re-runs performed in English. The verbatim Korean originals — the artifacts this book promises not to retouch — are preserved as is in the Korean edition. Code syntax, identifiers, numbers, and verification values are untouched. Currency conversions are approximate, at roughly 1,500 won to the US dollar as of mid-2026. Where the Korean text itself is the subject — dialogue registers, honorifics — or where a transcript is explicitly quoted verbatim, the original Korean is kept with an English gloss.

Part 1 · Foundation

1.0 Before You Start — Install, Account, Pricing, and the Terminal Survival Kit

Section 1.1 is the "first encounter." It is where you sit down in front of a blinking cursor and try typing something. But before you can take that seat, a few things need to be in place. The tool has to be installed, you have to be logged in, you should roughly know how the billing works, and you need to be able to type a few characters into a black screen. This chapter sits one step before 1.1.

Most introductory books skip this stage. They write a single line — "open your terminal" — and move on. But that single line is exactly where beginners get stuck. Where is the terminal? What do I need to install? What do I do when red text appears mid-install? Someone who stalls on the first line never reaches 1.1. This chapter has exactly one goal: making sure you do not get stuck on the first line.

The chapter has five parts: installation, account and login, pricing concepts, a terminal survival kit, and a "5-minute first run" checklist. Follow them in order and you will be ready to take the seat in 1.1.

flowchart LR
    A["1.0 Preparation
(this chapter)"] --> B["1.1 First encounter
(sitting at the cursor)"]
    A1["① Install"] --> A2["② Account & login"]
    A2 --> A3["③ Pricing concepts"]
    A3 --> A4["④ Terminal survival kit"]
    A4 --> A5["⑤ 5-minute first run"]
    A5 --> B
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class A1,A2,A3,A4,A5 human
    class B pass

1.0.1 Install — One Line per OS

For installation, the rule is to follow the official instructions. Tools change often, and installer files from unofficial sources are dangerous. So this book does not print download links; instead, it shows you how to find the official path. Type "Claude Code official docs" or "Claude Code install" into a search engine and Anthropic's official documentation page comes up first. The safest move is to use the install command from that page exactly as written.

Still, it helps to know the big picture. Claude Code — this book uses the official English name throughout — is a tool that runs in the terminal, and it usually installs with a single one-line command. The flow differs slightly by OS.

The flow is the same on all three: open the terminal → paste the one line from the official docs → press Enter. There is no need to memorize commands. Copying and pasting from the official docs is the standard way.

If red text (an error) appears during installation, do not panic. The install errors beginners run into are almost always one of two things: a permissions problem, or a missing prerequisite tool (a runtime like Node.js, for example). If red text appears, copy the whole message verbatim and search for it, or ask an AI — nine times out of ten that solves it. An error message is not an enemy; it is a clue.

How to check whether the install worked: type claude --version in the terminal and press Enter. If a version number appears on one line, the install succeeded. If you get something like "command not found," either it is not installed yet or you need to open a fresh terminal. Close the terminal completely, open it again, and check once more.

1.0.2 Account and Login

Finishing the install does not mean you can use it right away. Claude Code is a tool that borrows Anthropic's AI models, so there is a login step to confirm who is using it.

The flow is simple. Run claude in the terminal for the first time and a login prompt appears. Usually a web browser opens automatically, and you log in there with an Anthropic account (if you do not have one, you can create one on that screen). When the login finishes, the browser shows something like "you can return to the terminal now," and the terminal side shows a completion message as well.

Two spots trip up beginners here.

First, the browser may not open automatically. In that case the terminal prints a long address (URL) on one line. Copy that address, paste it into your browser's address bar, and go. You are not blocked — you just do one extra step manually.

Second, account types can be confusing. How the account you used in the web chat (Claude.ai) connects to Claude Code's account and billing may differ depending on the policy at the time. The most accurate guides are the login screen itself and the official docs. Follow what the first-run screen tells you and the login usually goes through without trouble.

Once you have logged in, it stays logged in on that PC. There is no need to do it every time.

1.0.3 Pricing Concepts — Flat-Rate Subscription vs. Pay-As-You-Go API

The part beginners worry about most is "how much is this going to cost?" There is a vague fear that every character you type adds to the bill. Getting the big picture first shrinks that fear. Billing comes in two broad flavors.

A flat-rate subscription means paying a fixed monthly amount and using the tool up to a limit. It is like a flat-rate mobile plan. The same amount goes out every month, so it is predictable, and you do not have to think about "how much does each line cost." That is why beginners usually find it easier on the nerves to start with a flat-rate subscription (author's estimate — exact plan tiers and limits change over time, so check the official pricing page). If you hit the limit, you wait for the next cycle or move up to a higher plan.

Pay-as-you-go API billing charges in proportion to actual usage (tokens). Like an electricity meter, you are billed for what you use. It suits bulk processing, automation pipelines, and integration with other programs. Used with care it is efficient, but at the beginner stage, before you have a feel for your usage, costs can be hard to predict.

What a token is and why billing is based on it is covered in detail in 1.2 (AI models, tokens, and the harness). For now, remember just one thing: beginners usually start with a flat-rate subscription. The monthly amount is fixed, so you can practice without the fear of "what if I get hit with a surprise bill." Plan names, prices, and limits change often, so this book does not print specific numbers. The contents of this book were written as of mid-2026, and pricing, models, and features keep changing after that. The official pricing page is the most accurate source for current values.

One-line summary: the fear that money drains every time you type → with a flat-rate subscription, it is fixed every month. Starting with flat-rate keeps a beginner's mind at ease.

1.0.4 Terminal Survival Kit — Making the Black Screen Less Scary

Now for the biggest wall: the black screen. This is why 1.1 opens with "you freeze in front of the blinking cursor." To hands that have worked in GUIs for 24 years, the terminal feels foreign. But the number of commands you need so you do not stall on the first line is small. The six below are enough.

(Windows PowerShell accepts ls, cd, and pwd as-is. So do macOS and Linux. That is why these six work regardless of OS.)

Here is what these six do, as a picture. Moving around in the terminal is ultimately just stepping in and out of folders — the same motion as double-clicking a folder or going back in a GUI.

flowchart TD
    Q["pwd
Where am I?"] --> L["ls
What is in here?"]
    L --> D{"See a folder
to enter?"}
    D -- "Yes" --> IN["cd folder-name
Go in"]
    D -- "No, go up" --> UP["cd ..
Step out"]
    IN --> L
    UP --> L
    RUN["After typing a command"] --> ENT["Enter
Run"]
    STUCK["When something seems stuck"] --> STOP["Ctrl + C
Stop and get the cursor back"]
    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    class Q,L,IN,UP,ENT,STOP code
    class D human

The real reason the black screen feels scary is the sense that "one wrong keystroke will break something." But none of the six commands above breaks anything. pwd, ls, and cd only look or move; they never delete or change files. Enter only runs, and Ctrl + C only stops. So feel free to type these six anytime, with peace of mind.

Sometimes the screen looks frozen. You typed a command and nothing happens for a while, or the cursor blinks on a different line as if waiting for something more. Press Ctrl + C once and you usually get the original prompt back. Just knowing this "stop button" exists makes the black screen far less scary. If you get stuck, escape with Ctrl + C and start again.

Finally, when typed characters pile up and the screen gets noisy, you can clear it. Windows PowerShell, macOS, and Linux all clear the screen with the clear command. Clearing does not undo anything you did; it only tidies up what is visible.

1.0.5 The "5-Minute First Run" Checklist

If you have come this far, the preparation is done. Pass the five boxes below within 5 minutes and you have earned the seat in 1.1. If any box blocks you, go back to the matching section (1.0.1–1.0.4).

flowchart LR
    C1["① The terminal
opens"] --> C2["② claude --version
shows a version"]
    C2 --> C3["③ Run claude →
login complete"]
    C3 --> C4["④ pwd & ls
show my folders"]
    C4 --> C5["⑤ Ctrl+C
gets me out"]
    C5 --> OK["✅ On to 1.1"]
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class C1,C2,C3,C4,C5 human
    class OK pass

• [ ] ① I can open a terminal (Windows: PowerShell / macOS: Terminal)
• [ ] ② Typing claude --version shows a version number on one line (install confirmed)
• [ ] ③ Running claude shows I am logged in (or I completed the login by following the prompts)
• [ ] ④ I can see my current location with pwd and the folder contents with ls
• [ ] ⑤ When something hangs, I can get out with Ctrl + C

With all five boxes checked, the black screen is no longer an unknown wall. The tool is installed, you are logged in, you know the big picture of how billing works, and you can move around the screen and stop things. 1.1 starts on top of this preparation. Go take the seat in front of the blinking cursor and, for the first time, type "summarize what's in this folder."

1.0.6 Python and pip — To Run the Tools (Only When Needed)

The early parts of this book (Parts 1 and 2) can be followed with natural-language prompts alone. From Part 4 on, however, some chapters run small Python scripts directly (e.g., pip install pyyaml, pip install pyvis). If Python is new to you, that is fine. There are two paths.

First, install it yourself. Download Python from python.org and install it (be sure to check "Add to PATH" on the install screen), then confirm with python --version in the terminal. pip is the package installer that ships with Python; you fetch the packages you need with one line, like pip install pyyaml.

Second, let the AI handle it (recommended). The easier path is to delegate the environment setup itself to the AI. Ask in the terminal like this.

Check whether Python is installed, and if not, tell me how to install it for my OS.
Then give me a one-line command to install the pyyaml package this chapter needs.

(The prompt above, kept in the original Korean, says: "Check whether Python is installed, and if not, tell me how to install it for my OS. Then give me a one-line command to install the pyyaml package this chapter needs.")

The AI inspects your environment and produces the install commands for you. If you get stuck, paste the error message right there and ask "how do I fix this error?" One round of this pattern per tool-running chapter is enough. At any stage where Python and pip feel like too much, that chapter's "Solo Scale-Down" shows a lighter path that goes without code.

Next Chapter Preview

• 1.1 A Game Designer's First Encounter with Claude Code — Sitting at the Cursor and Surviving the First 30 Minutes

Try It Yourself

setup 1. Open the terminal for your OS (Windows: PowerShell, macOS: Terminal). 2. Search for "Claude Code official docs" and keep the official install page open. 3. Set a timer for 5 minutes — the goal is to pass the five boxes of the 1.0.5 checklist.

prompt (type one line at a time, in order — these are commands, not natural-language questions; the Korean comments say: ① version shown = install succeeded, ② which folder am I in, ③ what is in this folder, ④ go up one level (then ls again), ⑤ run Claude Code (follow the login prompts if they appear))

① claude --version      # version shown = install succeeded
② pwd                   # which folder am I in
③ ls                    # what is in this folder
④ cd ..                 # go up one level (then ls again)
⑤ claude                # run Claude Code (follow the login prompts if they appear)

verify - If ① shows a version number on one line, the install is done. If you get "command not found," close the terminal, open it again, and try once more. - While looking around and moving with ②, ③, and ④, confirm for yourself that nothing breaks. These three are safe commands that only look and move. - If ⑤ seems to hang, get out with Ctrl + C. If you got out, you have confirmed with your own hands that "there is a stop button."

Solo Scale-Down

If you are an individual with no team and no company folders, start by learning just the install (①) and escaping with Ctrl + C. Confirm "the tool is installed" with claude --version and "I can get out even when stuck" with Ctrl + C, and half the fear of the black screen is settled on your own within 5 minutes. For pricing, start with a flat-rate subscription and you can practice as much as you like without worrying about cost.

1.1 A Game Designer's First Encounter with Claude Code

A black screen comes up. The cursor blinks. In front of it sits a game designer with 24 years in the industry. Hands that have spent 24 years working in PowerPoint and Excel, wikis and Figma, pause for a moment over the keyboard. It looks a little like DOS, from the days of after-school computer classes. Since then, a terminal was something you only ever saw on a programmer's desk. I don't know what to type, and it feels like typing the wrong thing will break something. That hesitation is where this book begins.

Most people close the window right there. Then, in the next meeting, they go back to repeating "we really should be doing something with this." This chapter sits with you through the first 30 minutes without closing that window. The goal is not a grand adoption strategy — it is to put into your hands what to type at that blinking cursor so the distance starts to dissolve.

When a game designer first sits down in front of an AI coding tool like Claude Code, fascination and discomfort arise at the same time, in the same seat. The fact that these two feelings collide is itself the first clue to adoption.

The fascination has clear reasons. A data-sheet consistency check that used to eat half a day finishes in minutes; sprawling meeting minutes get summarized into a table of decisions; a game design document (GDD) buried a year ago can be pulled back up with one line of natural language.

The discomfort has equally clear reasons. The black screen, the blinking cursor, the English commands — none of it looks like the everyday workspace. A game designer's day flows on top of GUIs, and typing characters into a black terminal does not sit well with the job's identity. But this discomfort is not a defect in the tool; it is the adaptation cost of a person used to GUIs. Just acknowledging that point clears half the distance already.

This book is about closing that distance. Section 1.1 sits with you at the first encounter and sorts out what to look at, what to try, and what can safely wait.

1.1.1 Why Now, and Why Game Designers Should Use AI

Game design joined the AI wave later than other roles. People who handle code went first; artists and visual designers came next. Game designers commonly fell into the pattern of repeating "we should try something" while putting it off.

The reasons for putting it off were rational. A game designer's output is not structured the way code is; it is a mix of text, tables, diagrams, meetings, and verbal agreements. AI output looked unreliable, plausible lies were dangerous, and it was doubtful whether AI really understood game systems.

But between 2024 and 2026, three things changed.

First, the reasoning ability of AI models crossed a threshold. They go beyond simple sentence generation to handle complex system design, consistency verification, and impact analysis. Recent Claude-family models can assist with a substantial share of a game design workflow. That does not mean you can hand all of it over: verification and responsibility still belong to humans. (How wide the assistance goes varies greatly by task type and team maturity — author's estimate, unverified.)

Second, the harness matured. A tool like Claude Code is not simple chat. It reads and writes files directly, runs commands, and takes the results back as input. It resembles the way a person works.

Third, operational techniques like memory, atoms, and skills have settled in. Instead of using AI once and throwing the session away, there is now a methodology for accumulating a team's knowledge so the system gets smarter over time. That accumulation is exactly what the later parts of this book cover.

Put these three together, and this becomes a rational moment for game designers, too, to adopt AI. It pays to start before falling further behind.

1.1.2 What Claude Code Is — How It Differs from Other Tools

The AI tools a game designer usually encounters come in two kinds: chatbot-style tools where you type questions into a chat window (ChatGPT, the Claude web app), and editor-integrated tools that autocomplete inside a code editor (Cursor, Copilot).

Claude Code is a third kind. It runs in the CLI (terminal) and has access to the entire environment a person works in. Here, on one page, is where the three kinds diverge.

A game designer's work is not code; it is documents, tables, and relationships. Claude Code's strength is that it sees, understands, and manipulates the entire folder a person works in. You do not have to copy and paste material into a chat window every time, the way you do with a chatbot.

In office terms, the chatbot is the front desk. One question, one answer, and you have to bring your materials out again every time. Claude Code is closer to the colleague at the next desk. It knows where the materials are, opens the files with its own hands, and puts the organized result back on your desk. The same Claude does different things well depending on which desk you seat it at.

1.1.3 The First 30 Minutes — What to Look at, What to Try

Installation and setup are covered in 1.0. Section 1.1 focuses on what to experience in the first 30 minutes to shrink the distance. The first 30 minutes split into four segments, and each segment dissolves another piece of the distance, step by step.

flowchart LR
    A["Look (5 min)
Summarize this folder
→ 'It understands natural language'"]
    B["Search (5 min)
Find keywords, recent files
→ 'It handles my daily chores'"]
    C["Convert (10 min)
Minutes→table, Excel→Markdown
→ 'It creates time'"]
    D["Verify (10 min)
Doubt the output just made
→ 'This tool must be doubted'"]
    A --> B --> C --> D
    D --> E["80% of the distance dissolved"]
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class A,B,C ai
    class D human
    class E pass

The First 5 Minutes — Look

Open a terminal and run Claude Code: a black screen appears and the cursor blinks. Many people stop right here, but stopping means missing the first chance to dissolve the distance. Type one sentence in natural language.

Summarize what's in this folder

One sentence — "Summarize what's in this folder" — neither code nor a command. Claude Code scans the folder structure and answers with a summary of what files are there and what kind of project this appears to be. Type this one line in a folder of design documents and a response comes back roughly like this.

Summarize what's in this folder


I scanned this folder. It looks like a working folder for game data and design documents.

  File type        Count   Estimated contents
  ─────────────   ────    ───────────────────────────
  .xlsm            12     Data sheets (items, quests, NPCs, etc.)
  .md              34     Design docs and meeting-minute drafts
  .png             88     UI mockups and reference images
  Subfolders        6     /data /docs /ref /meeting /export /tmp

Observations:
  - The /meeting folder has 5 meeting minutes from the past week piled up.
  - item_table.xlsm and quest_table.xlsm appear to share the same
    ID column (an FK candidate).
  - The /tmp folder holds many temporary export files — possible cleanup targets.

What would you like to look at first?

(The response, in short: it scanned the folder, identified it as a game-data and design-doc workspace, tabulated the file types — 12 .xlsm data sheets, 34 .md docs and minutes, 88 .png mockups, 6 subfolders — then observed that five recent meeting minutes have piled up, that item_table.xlsm and quest_table.xlsm appear to share an ID column (an FK candidate), and that /tmp holds stray export files; it ends by asking what to look at first.)

From this single response, the fact that this tool understands natural language, not commands, sinks in physically. Receiving an organized picture of what is where, without opening the folder yourself, cuts half the distance on the spot.

The Next 5 Minutes — Search

Give it a small search. Requests like "show me the 5 Markdown files modified in the last week," or "where are the files that mention the word 'reward'?" The work a game designer used to do daily — opening Find in Files, typing a keyword, scrolling through results — Claude Code takes in natural language and returns organized. The sense that this tool handles your daily chores settles in during the second five minutes.

The Next 10 Minutes — Convert

Give it a small conversion. Requests like "extract only the decisions from these meeting minutes into a table," or "turn rows 1–10 of this Excel sheet into a Markdown table." A conversion that takes 5–10 minutes by hand getting done in moments turns the earlier sense — the tool replaces search — into a new one: the tool creates time.

The Last 10 Minutes — Verify

Stopping here is dangerous, because AI tells plausible lies. Make it doubt the output it just produced.

Check again whether the table you just made matches the original. Anything missing?

The prompt says: "Check again whether the table you just made matches the original. Anything missing?" Claude Code then rereads the original, compares it line by line against its own output, and reports the mismatches. In practice, this segment often produces a screen like this.

Check again whether the table you just made matches the original. Anything missing?


I re-checked the original (meeting_0603.md) against the table I just made.
I found 3 mismatches.

  ⚠ Omitted    "Tutorial reward cut by 50%" — in line 12 of the original but missing from the table
  ⚠ Mistyped   Owner "Kim OO" → entered in the table incorrectly as "Lee OO"
  ⚠ Ambiguous  "Rediscuss rewards" — unclear in the source whether it is a decision or a hold.
               I placed it under 'decided' on my own judgment; it needs confirmation.

Shall I rebuild the corrected table? Tell me how to handle
the ambiguous item and I will reflect it.

(In short, it found 3 mismatches: an omission — "tutorial reward cut by 50%" is in line 12 of the original but missing from the table; a wrong entry — owner "Kim OO" mistyped as "Lee OO"; and an ambiguity — "rediscuss rewards" is unclear in the source as decision or hold; the AI says it placed it under 'decided' on its own judgment and asks for confirmation, offering to rebuild the table.)

The point of the last 10 minutes is that the tool knows how to doubt its own output — and that it does the doubting together with a person. The attitude in that third item, asking back "I made a judgment call here, please confirm," is the safeguard that keeps verification in human hands.

After 30 minutes, 80% of the distance is gone. The remaining 20% shrinks slowly across the chapters that follow.

1.1.4 Scenes from the Office — Six Months on a Mid-Size Team

On an MMORPG project I run as design director (hereafter "Project A"), the design team (4–5 people) has been running a Claude Code–centered workflow for about six months (Project A's full development team is mid-size, 10–50 people). Here are a few of the scenes.

Let me pull out the single most tangible case as an actual measurement: FK (foreign key) consistency checks across 30-odd data sheets. The task is tracing, by eye, whether the IDs in one sheet are referenced correctly in the others — and as sheets multiply, the combinations grow at a compounding rate.

• Before: One designer opens the sheets in turn and cross-checks IDs. One full pass over the 30-odd sheets takes half a day (about 4 hours). When focus breaks midway, rows get missed.
• After: A relation-detection tool cross-checks FKs between sheets automatically and outputs only the broken references as a list. One pass takes about 5 minutes.

Half a day to 5 minutes. I will not generalize from this one line. Other tasks save less, or pick up new review time instead. The other scenes from the same six months I record only as directions and ratios.

• Decision extraction from meeting minutes (5–10 items accumulating per week): work a person used to track by searching and scrolling → an automatically extracted table. The tracking burden nearly disappeared.
• GDD drafts: writing time fell to less than half, while review and polish time grew. The total goes down, but the work's center of gravity shifts from 'writing' to 'judgment.'
• Data-sheet relationship maps: a dependency structure repeatedly explained out loud in meetings → generated once as interactive HTML and shared.

My felt sense is that once each of these tools was built, the time it saved over six months accumulates in person-months, not person-weeks (the exact total is unmeasured — an estimate). That time went into deeper design work.

A tool like this works for a long time once built. But 'long' does not mean 'unattended.' It lasts only when an operator and a verification structure come with it; leave the tool in place and let the person walk away, and it rots within two quarters. The later parts of this book cover how each of the tools above gets built and operated.

1.1.5 Fears and Expectations — Dealt with Honestly

Let's be honest about the fears game designers commonly bring to an AI tool. Facing them instead of looking away is the first step of adoption.

The fear that "AI will replace my job" is half right and half wrong. AI does replace the simple chores — consistency checks, document conversion, search — but it cannot replace decisions, priorities, or the design of player emotion. If anything, the game designer who uses AI well is freed from chores to focus on the essentials. Ask yourself: "In my job, what is the ratio of chores to essence?" If chores are 70%, the 30% of essence stays yours — and the point is that that 30% becomes more important.

The question "who takes responsibility when AI is wrong" comes up just as often. Responsibility for a game designer's decisions always belongs to the game designer. Using AI output as-is without verification is the designer's mistake, not the AI's. Designing the verification procedure alongside the tool is part of adoption. The 'make it doubt its own output' move from the last 10 minutes of 1.1.3 is the smallest seed of that procedure.

The fear "I can't use it because I don't know code well" resolves quickly. Claude Code runs on natural language, so you can start without knowing code, exactly as you are. Because you read the scripts the AI writes together with it, after a few months you find yourself reading and modifying simple scripts. The learning comes along on its own.

"The tools change too fast" is another common worry. Trying to keep up with every model, feature, and trend wears you out. Learn only the one or two features that help your own workflow in depth, and look at the rest when you need it.

One thing to say in advance: even if the response screens in 1.1.3 looked smooth, the real first 30 minutes will mix in answers that miss, summaries of the wrong files, and output that stalls. That is normal. This book is not a smooth success story; it spends more pages on how to re-ask and correct output that went wrong.

1.1.6 How to Use This Book

This book is organized into 24 parts. You do not have to read it front to back. Pick whichever of the three patterns below fits your situation.

If you have no idea which path to pick, split by where you stand. If you work outside games — in a planning or product role, as a PM, or as a general office professional — instead of the three patterns above I recommend the "General-Role Path" (Parts 1–2 → Part 17 meeting minutes → Part 16 collaboration → Part 18 decision-making → Parts 21–22 self-improvement and governance) — the core skeleton stands intact even when you skip the game-domain chapters, and each chapter's "Beyond Games" box is the bridge for carrying it over to your own role (index in Appendix F.5). If you are short on time, following just four chapters — 17.1 → 16.2 → 22.1 → 21.1 — is enough. If you are a non-technical reader just starting out with AI tools, take the 'adoption pattern,' hold on to one field (your own, or the closest one) all the way through, and for the deeper field parts (4, 8, 11, and the like) just pick up the 'one line for non-specialists' at the start of each, going down into the body only when needed.

Every chapter in this book stops short of academic depth, at the level you can actually operate. The goal is to carry over, as-is, techniques that really ran for six months on a mid-size team, and to walk together the path of starting small and growing big.

1.1.7 Into the Next Chapter

1.1 was a chapter about shrinking the distance. 1.2 steps one level inside and explains the tool's basic mechanisms in language friendly to game designers. The goal of 1.2 is to make words like model, token, context, and harness nothing to fear. The full setup (memory, permissions, settings.json) comes in 1.3.

Key Takeaways

• The distance you feel at the first encounter is not a tool defect; it is the adaptation cost of someone used to GUIs
• Claude Code is not a chatbot; it is closer to a colleague at the next desk who handles your entire folder
• Run through the first 30 minutes — look, search, convert, verify — once each, and 80% of the distance disappears

Next Chapter Preview

• Chapter 2. AI Models, Tokens, and the Harness — Basic Mechanisms for Game Designers

Try It Yourself

setup 1. Open a terminal (PowerShell on Windows, Terminal on macOS). 2. Move into a folder where your design documents live, then run Claude Code (installation: 1.0). 3. Set a timer for 30 minutes — 5 min (look), 5 min (search), 10 min (convert), 10 min (verify).

prompt (one line per segment, in order)

① Summarize what's in this folder
② Where are the files that mention the word 'reward'?
③ Extract only the decisions from these minutes into a table
④ Check again whether the table you just made matches the original. Anything missing?

(In order: ① "Summarize what's in this folder" ② "Where are the files that mention the word 'reward'?" ③ "Extract only the decisions from these minutes into a table" ④ "Check again whether the table you just made matches the original. Anything missing?")

verify - For ①, check with your own eyes that the folder summary matches the actual folder. - If ④ reports even one mismatch, that is a success. It means you watched the AI doubt its own output, live. - An answer that misses is not a failure either. Re-asking — "that answer was wrong, look at just this file again" — is part of the first 30 minutes of practice.

Solo Scale-Down

If you have no team and no company folder, pick any working folder on your own PC (say, your Downloads folder, or a notes folder) and try just prompts ① and ④ above. Confirm "it understands natural language" with ① and "it can doubt its own output" with ④, and you will have felt this chapter's two core points by yourself, within 5 minutes.

1.2 Model, Token, Harness — The Path a Task's Tokens Travel

It starts the moment I finish a task and look at the usage. Five meeting notes from this week have piled up in a folder, and before Monday morning's stand-up I have to distill them into a single page of "only what was decided." I type one line into the Claude Code window: "Pull only the decisions from the meeting notes in this folder and make them into a table." About 0.4 seconds after I press Enter, small gray text flickers near the bottom of the screen.

Reading meeting-2026-05-25.md ... (1,840 tokens)
Reading meeting-2026-05-27.md ... (2,310 tokens)

That gray text is the subject of this chapter. I toss in a single sentence in Korean; the tool chops it into tokens, reads files into tokens and feeds them to the model, takes the model's answer, and writes it to a file. Every time this round trip runs, a cost is charged, and material piles up in the model's "field of view." This chapter breaks down what happens behind that gray text in a game designer's language. Four words are enough: model, token, context, harness.

Terminology Notes - Model: the brain that produces answers. It comes in kinds with different sizes and characters, such as Opus, Sonnet, and Haiku. - Token: a small chunk of chopped-up text. Billing, speed, and the model's field of view are all counted in this unit. - Context window: the maximum number of tokens the model can hold in its head at once. - Harness: the chassis that puts the model to work. Claude Code is one example.

1.2.1 The Harness Loop — What That Gray Text Really Is

The gray text above is not random logging; it is one box in a fixed cycle. What a harness does, in the end, is spin the same loop fast. It reads files and feeds them to the model; when the model says "run this command," it runs it; and it feeds the result back to the model. The loop keeps spinning until the task is done.

flowchart TD
    Start([Human: one-line instruction]) --> Read[Harness: read files and materials
convert to tokens]
    Read --> Inject[Harness: inject into context
+ add to cumulative tokens]
    Inject --> Model{Model: decide next action}
    Model -->|needs a command run| Exec[Harness: run shell commands and scripts]
    Exec --> Result[Feed execution results
back in as tokens]
    Result --> Inject
    Model -->|answer is ready| Write[Harness: write files and output]
    Write --> Verify{Verification passed?}
    Verify -->|fail| Inject
    Verify -->|pass| Done([Save result])
    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class Start,Verify human
    class Read,Inject,Exec,Write code
    class Model ai
    class Result data
    class Done pass

In this diagram, the only boxes a human touches are the top one (instruction) and the bottom one (checking the verification result); the loop in the middle runs autonomously under the harness. The gray text flickered five times while the five meeting notes were being read because the Read → Inject boxes ran five laps. In a web chat, I would have had to open five files myself and copy-paste them. The harness takes over that labor — and that is the decisive difference that makes a chatbot and a CLI-style harness different tools.

Each lap of the loop adds to the cumulative token count in the Inject box. So without understanding tokens first, neither the cost nor the limits of this loop come into view. Tokens first.

1.2.2 Tokens — The Real Currency a Task Spends

A token is not a character; it is a chunk the model cuts text into. As a rule of thumb, English runs at about 4 characters per token and Korean at about 2 characters per token (this is an operational approximation, not an official conversion — the actual value is set by the model's tokenizer and varies by sentence). Twenty Korean characters including spaces come to roughly 10 tokens.

Let me follow that meeting-notes task in tokens (the figures below are a single measurement of one run of this task; they vary with the length of the notes and the summary, so read them for orders of magnitude and ratios, not as absolute values).

Two things stand out. First, the instruction I typed is 25 tokens, but the task as a whole tops 11,000 tokens of input alone. Almost all of the cost comes not from my sentence but from the material the tool read in. Second, output (1,810) is about one-sixth of input (11,225). Most design automation reads a lot and writes a little, just like this. So if you want to cut costs, taming the volume of input material works far better than polishing the output.

After the task ends, typing /context shows how much of the context that session occupied. Unwatched, tokens drain away as unconsciously as printer paper; once made visible, your posture changes. That visibility is where saving starts.

What tames tokens is not an abstract spirit of thrift but concrete techniques for handling input material in small pieces.

1. JIT injection — JIT (just-in-time): instead of loading all material up front, pull it in by keyword matching only when needed. The "\~480 tokens of classification rule injection" in the table above is an example. What came in was not the entire meeting-classification rulebook (thousands of tokens) but the single matched atom.
2. Summary cache — for long documents, keep an AI-facing summary separate from the human-facing original. The AI reads the summary.
3. Atom splitting — keep one decision per file (details in 2.2) and you can pull in exactly the pieces you need, saving tokens.
4. Context cleanup — compact when a session runs long. Claude Code supports automatic compaction.
5. Model selection — running a simple conversion on a big model makes the same tokens cost more. That is the next section's topic.

Of these, #1, JIT injection, is a device that actually runs in this book's working environment. When a line of input comes in, the inject_memory.py hook matches memory atoms by score, picks only the top few to inject, and never blocks the workflow even when it fails (implementation details in 1.3). The token-saving principle — "only the needed material, only the top few, fail quietly" — sits in that one file of code, as is.

1.2.3 Models — Same Chassis, Different Engines

A model is like a car engine: into the same chassis called Claude Code, you can fit different engines — Opus, Sonnet, Haiku. Swap the engine and the character of the work changes.

Mapped onto design work, it splits like this. Work that needs deep reasoning and consistency — reviewing a system design, or synthesizing a first draft of a game design document (GDD, the detailed spec) that pulls multiple sources together — goes to Opus. The everyday majority, like extracting decisions from meeting notes or writing daily summaries, goes to Sonnet. Work involving almost no judgment, like simple format conversion of data sheets, goes to Haiku. Running the earlier meeting-notes task on Sonnet followed this rule — picking out decisions and moving them into a table calls for balance and speed more than deep reasoning.

There is a trap everyone falls into early on: the urge to run every task on the best engine, Opus. Follow that urge, and the cost and speed load comes back as an operational burden, and the sense of matching the model to the task never takes root. The real skill of operation is not picking a model in your head every time, but hardening the pattern into automation once it has settled.

• Daily retrospective writing → automatically Sonnet
• System design review → automatically Opus
• Data sheet consistency check → automatically Haiku

These fixed choices are spelled out in settings.json or inside slash commands (details in 1.3). Harden them once, and the chore of choosing every time disappears.

Models ship a new version roughly every half year, and even under the same name, 4.5 and 4.6 are different. When a new version lands, I compare only the five core tasks of my workflow on identical inputs. Try to test everything and you wear out. The differences across five results are enough to decide whether to switch.

1.2.4 The Context Window — The Ceiling the Loop Fills Toward

I said tokens accumulate in the Inject box with every lap of the loop. The ceiling that accumulation runs into is the context window: the maximum number of tokens the model can handle at once. In human terms, it is working memory.

• Claude 4 family: 200K tokens standard, with a 1M-token extended option
• 200K tokens ≈ roughly 400 A4 pages of Korean text

The earlier meeting-notes task accumulated input in the 11,000-token range — about 6% of the 200K ceiling, with plenty of headroom. But if you never switch tasks and drag one session on in the same window, you approach the ceiling. When it fills, old content gets cut, the model starts losing its "memory" of the earlier parts, and automatic compaction kicks in, replacing the previous conversation with a summary.

Four habits keep this ceiling under control.

The heavy case game designers run into most often is work that needs meeting materials, design docs, and data sheets all at once — that is where the 1M option is useful. But 1M carries cost and speed burdens, so 200K is enough day to day; bring out 1M only when the bundle of material is genuinely large.

1.2.5 When the Harness Actually Filters Out Falsehoods — The Verification Box

Back to the Verification passed? box at the bottom of the loop diagram. Without this box, the model's plausible lies get saved straight to files. A model sometimes presents a confidently wrong answer as if it were correct (a hallucination), and while the frequency drops with each generation, it never reaches zero. So verification stays in place as a permanent box.

In design work, the dangerous hallucinations are specific: citing a data sheet column that does not exist, computing balance with the wrong formula, or summarizing something never decided in the meeting as if it had been decided. In the meeting-notes task, the third is the scariest — an item that was "only discussed and put on hold" quietly climbing into the decisions table.

There are five verification patterns.

1. Source cross-check — compare the AI output against the original material again ("check whether this was really in that document").
2. Round-trip conversion — convert A→B, then convert B→A back, and check that they match.
3. Sample review — a human directly checks 3–5 random items from the output.
4. Linter automation — automatically check whether the output violated the set format, ranges, or rules.
5. Two-model cross-check — Opus reviews Sonnet's output.

You do not run all five every time; pick one to three based on the risk level of the task. For the meeting-notes task, I paired #4, a linter ("does every decision have an owner, a description, and a deadline?"), with one round of #3, sample review. The last row of the earlier token table — "\~320 tokens of verification re-entry" — is exactly that round trip where the linter caught an omission and asked the model again; in the loop diagram, one extra lap through fail → Inject.

If a human verified everything every time, the payoff of adoption would be cut in half, so verification itself is an automation target. For meeting-decision extraction, the linter checks for format omissions; for data sheet conversion, row counts, sums, and foreign key consistency; for GDD auto-generation, missing core sections. Whatever passes, no human needs to look at; only what fails gets looked at. Picture a cabinet stuffed with paperwork where you pull out only the folders with red tags. Designing things so the human gaze lands only where the danger is — that is the purpose of verification automation.

1.2.6 Where the Four Words Tie into One Task

Now let me lay out that meeting-notes task from start to finish — how the four words string onto a single thread.

Done by hand, opening five meeting notes, reading them, picking out only the decisions, transcribing them, and fixing the format takes 30 minutes. Automated, it shrinks to 5 minutes, and within those 5 minutes the only work for human hands is skimming a verification sample once. Human time lands only where it is truly needed — checking that no deferred item wrongly climbed into the decisions. The point is not the 25 minutes saved but the change in where that gaze goes.

1.2.7 Common Misconceptions

"Opus is always better" is the most common. Ignore cost and speed and it is true, but Opus on simple work is waste. Per-task matching is the answer.

"You always need the 1M context" also comes up often. 200K is enough for most things, and 1M carries a burden, so save it for genuinely large bundles of material.

"Verification is something humans do" is half right. Most of it can be verified automatically, and humans focus on the rest.

"You don't need to mind tokens" holds up to a point for solo work, but once several people use the tool together, the cumulative cost grows fast. Settling visibility and saving patterns from the start is the safer path.

"Harnesses make no difference" is surprisingly common too. The same model splits into what feel like different tools depending on whether it sits in a chatbot or a CLI. The presence or absence of the copy-paste labor we saw earlier is that difference.

1.2.8 Try It Yourself

Run this chapter's four words yourself on one small task.

setup

• With Claude Code installed, prepare a folder holding 2–3 text notes (meeting notes, memos).
• Open Claude Code in that folder.

prompt

From the notes in this folder, pick only what was "decided"
and build a 3-column table of owner, description, and deadline.
Exclude deferred or still-under-discussion items, and for each row
in the table, also note the file name it came from.

(The prompt says: from the notes in this folder, pick only what was decided and build a three-column table of owner, description, and deadline; exclude deferred or still-under-discussion items, and note for each row which file it came from.)

verify

• When the task finishes, type /context and look at the tokens this session used (you will find the input is larger than you expected).
• Pick a line or two from the table, open the file named there, and check against the original that it really was written as a "decision" (source cross-check).
• Skim once for any deferred item that wrongly made it into the table (sample review).

Solo Scale-Down

If you are just starting with the tool, keep only two things from the above. First, hand over the notes folder whole — do not copy-paste the contents yourself (leave that to the harness loop). Second, always get the output table with file names attached, and open the original only for the suspicious lines. Model selection and token visibility can wait until you are comfortable. Not carrying material by hand, and checking output against the original — these two habits alone settle half of the adoption.

Key Takeaways

• The harness spins the read→execute→re-input loop on its own; a human touches only two boxes, instruction and verification
• Almost all of a task's cost comes from the material the tool reads in, not from the instruction I typed
• Swap models to fit the task, and keep the context ceiling and verification under control with automation

Next Chapter Preview

• Chapter 3. Memory, Permissions, and Settings Infrastructure — A Foundation That Keeps Working Once Set Up

1.3 Memory, Permissions, and Settings Infrastructure

I opened a new session and typed, "Let's take a look at skill cooldown balance." Before I pressed Enter, a small line of gray text flashed by at the bottom of the screen: [memory injected: 2 atoms, 1,842 chars]. I had not opened a single file, yet the cooldown rules document I had pinned down the week before was already attached in front of the model's input. That is the first sign of a working environment with infrastructure in place. The moment I turn the tool on, the tool remembers me.

For that scene to happen, three things must already be in position: what the AI remembers (memory), what the AI can do without human approval (permissions), and the central switch that turns both on and off (settings.json). The initial setup takes an hour at most, and that hour comes back as time saved every day for the next six months. It is an investment that recovers almost all of itself.

This chapter is a walkthrough that unfolds, in order, the single line of settings.json I actually run on my personal PC, the inject_memory.py that line calls, and the _jit_manifest.json that script reads. Read to the end and you will be able to put your finger on exactly which file and which line make "memory gets injected automatically" happen.

1.3.1 settings.json — The One Line Where Everything Starts

Conclusion first. On my personal PC, what turns on automatic memory injection is one single block inside settings.json.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python ~/.claude/hooks/inject_memory.py"
          }
        ]
      }
    ]
  }
}

Spelled out in plain language, the block says this: "Every time the event where the user submits a prompt (UserPromptSubmit) fires, run a Python script called inject_memory.py once." That is all. The AI is not being clever and remembering things on its own — a script that a human registered cuts in once every time input arrives.

settings.json is the central file that controls every behavior of Claude Code, and it splits into two layers.

• ~/.claude/settings.json — global. Applies to every session. Settings you can share with the team.
• ~/.claude/settings.local.json — local. Applies only on this PC. Settings specific to a personal machine.

The two are merged when applied. So I keep the hooks and permissions the team should share in settings.json, and the absolute paths and personal tool paths that exist only on this home PC in settings.local.json. The split avoids git conflicts when collaborating and prevents the accident of personal settings leaking into the team repository.

Besides hooks, a few other entries come up often.

• effortLevel — the model's reasoning depth: low / medium / high. For work that needs deep judgment, like drafting a game design document (GDD), I keep it at high.
• permissions — the range of commands the AI may run without approval (details in 1.3.4).
• enabledPlugins — the list of enabled plugins.

There is one operating habit here that matters more than anything else. A single small typo in settings.json can keep the tool itself from starting. One missing JSON comma breaks the parse. So a backup before every change is mandatory. These backup files actually sit on my PC.

settings.json.bak_2026-05
settings.local.json.bak_2026-05

Take one copy with a date suffix and rollback takes one second. Managing it with git is even better. Like a spare set of old keys in a drawer — you never use it day to day, but a moment always comes, in front of a locked door, when you need it exactly once.

1.3.2 inject_memory.py — What Actually Happens Inside the Hook

Now we go inside the script that settings.json calls. This is the spine of the walkthrough. The code is barely 100 lines, but the heart of it is five actions.

flowchart TD
    A["Session: user submits a prompt\ne.g. 'Review skill cooldown balance'"] --> B["UserPromptSubmit hook fires\nsettings.json runs inject_memory.py"]
    B --> C["Load _jit_manifest.json\nmetadata for 17 atoms"]
    C --> D["Sort by score, descending\n→ try regex match per atom"]
    D --> E{"Any matched\natoms?"}
    E -->|none| Z["Inject nothing\nexit 0"]
    E -->|some| F["Select only top max_matches (3)"]
    F --> G["Truncate if combined total\nexceeds 6,000 chars"]
    G --> H["Attach atom bodies\nin front of user input"]
    H --> I["Model receives atoms + prompt\ntogether → responds"]
    D -.->|any exception| Z2["Swallow every exception\nexit 0 (never blocks the flow)"]
    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    class A human
    class B,C,D,E,F,G,H code
    class I ai

Spelled out, the five actions go like this.

1) Read the manifest. The script first opens ~/.claude/projects/C--Users-user/memory/_jit_manifest.json. This file holds the metadata for each atom — name, path, matching regex, score. On my personal PC, 17 atoms are currently registered.

2) Sort by score, descending. Every atom carries a score value. The higher the score, the earlier the atom gets its matching attempt. When several atoms hit the same keyword, this score decides who gets priority.

3) Match with regex. The user's input string is checked against each atom's regex pattern. If the input contains "쿨다운" (cooldown), the atom carrying the pattern 쿨다운|cooldown|GCD fires. The comparison is case-insensitive.

4) Cut to at most three. No matter how many atoms match, anything beyond max_matches (3 in my environment) is dropped, keeping only the top three. On top of that, if the combined length of the selected atom bodies exceeds 6,000 characters, the script truncates. Two layers of ceilings serve as the safety device that keeps the input from bloating.

5) Exit 0 on every exception. This is the heart of the design. Whether the manifest is broken, the file has vanished, or a regex is malformed, the script quietly swallows the exception and finishes with exit code 0. If the hook dies with a nonzero code, the user's prompt itself can be blocked. The principle — "even if memory injection fails, never block the user's flow of work" — is written into the outermost try/except of the code.

The center of gravity sits on 4 and 5. Number 4 (the ceilings) keeps memory from exploding the token count, and number 5 (swallowing exceptions) keeps the infrastructure from getting in the way of the work. Both are two faces of the same philosophy: automation must never make itself a burden on the human.

1.3.3 _jit_manifest.json — The Keyword Dictionary That Wakes Atoms

In 1.2 I promised the token-saving principle — only the material you need, only the top few, fail quietly — and deferred the implementation details to this chapter. Those details live in the manifest that inject_memory.py reads. It is the heart of JIT (Just-In-Time — loading material only at the moment it is needed), and a single atom entry looks like this.

{
  "atoms": [
    {
      "name": "combat_cooldown_rule_v2",
      "path": "atoms/combat/combat_cooldown_rule_v2.md",
      "regex": "쿨다운|cooldown|GCD",
      "score": 80
    },
    {
      "name": "user_health",
      "path": "memory/user_health.md",
      "regex": "건강|복약|컨디션|약물",
      "score": 95
    }
  ],
  "config": {
    "max_matches": 3,
    "case_insensitive": true
  }
}

Four fields define one atom.

• name — the atom's unique name.
• path — the file path whose body gets read in on a match.
• regex — the pattern that defines which keywords in the input wake this atom.
• score — sort priority. The higher it is, the earlier the atom matches and the earlier it claims a slot.

The max_matches: 3 in the config block is the source of the "at most three" ceiling we saw in 1.3.2. Edit the manifest by hand and the behavior changes immediately.

One note on scale. My personal PC runs light: 17 atoms, one manifest. The company production environment (Project A), by contrast, has 304 team atoms and 48 skills registered as of a May 2026 backup. One hot atom has a score that has climbed to 356.53 (the view_html_filename_convention family, which covers file-naming conventions) — it did not start high; the number is a trace accumulated through repeated calls and verification.

What the gap between 17 on a personal PC and 304 at the company tells you is this: the JIT mechanism is the same, but the speed and scale at which material accumulates is proportional to project density. There is no need to build 304 from day one. Start with five core atoms, pin down one or two more each week, and before long the manifest thickens on its own.

Author's estimate (unverified): the claim that score accumulates with match and verification counts is an interpretation based on operating patterns. The scoring formula itself varies with each environment's manifest design, so an absolute value like the 356.53 above is a measured snapshot of my environment, not a general standard.

This is also the place to restate the principle that memory is kept in two layers.

Keeping global light is the safer side. When global grows heavy, that weight accumulates as a token cost on every single session. In office terms, global is the business-card holder on your desk (the lighter it is, the handier for daily use), and project memory is the folders in the cabinet beside you (it can grow thick per project without weighing on your day). So the auto-loaded global holds only the essentials, while the rich material piles up in project memory and gets woken by JIT only when needed.

1.3.4 Permissions — A Whitelist That Accumulates the Traces of Your Work

Now the third axis of the infrastructure: permissions. Claude Code can delete files, run commands, and call external APIs. Power comes with risk. The permission system manages that risk.

Permissions split into two kinds: what runs automatically without human approval, and what requires approval every time. Which side holds what is defined in the permissions block of settings.json.

{
  "permissions": {
    "allow": [
      "Bash(ls:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Read(*)",
      "Grep(*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ]
  }
}

A shift in perspective is needed here. This allow list is not a mere configuration value — it is a trace of accumulated work. At first it sits nearly empty, with only reads and searches auto-allowed. Then, after a month or two of repeating the same work, patterns emerge where you think "approving this command every single time is a chore," and you move them into allow one by one. The list that grows long is a fingerprint of what I have been repeating with this tool.

My company environment (Project A) holds about 80 auto-allow patterns. It started at 20, and 60 more attached themselves over six months — read those 60 backwards and they reveal what work got repeated over the past half year. Data sheet extraction, relation map generation, schema documentation — the tools you use often become the permissions you allow often.

Four patterns settle in for operating permissions.

• Start with a whitelist — begin auto-allow at the minimum and add only when needed. The direction is not opening wide and then narrowing; it is closing tight and then opening.
• Explicitly block dangerous commands — commands where one accident is fatal, like rm -rf and git push --force, go into deny. However wide the auto-allow grows, these two stay untouched.
• Regular cleanup — re-review allow every quarter and trim the permissions you no longer use. Traces that only ever pile up become noise.
• Separate by domain — split global permissions from project permissions. Just as a home PC and a work PC carry different policies, every environment has a different allow range.

When an approval popup appears every time, the human wears out. There are devices to cut the fatigue: bulk-registering frequent patterns with a slash command like fewer-permission-prompts, granting a temporary allow for a single session only, or — for personal work only — running a full auto-allow mode. I do not recommend that last option in a team environment, though.

The balance between fatigue and safety is yours to tune. Too strict and the work does not roll; too loose and accidents happen. Even if you start loose, with a quarterly cleanup cycle in place the balance settles on its own.

1.3.5 When a Session Starts — How Memory and Permissions Load Together

How do the three axes we have seen — settings, memory, permissions — operate at the same time in one session? Let's unfold it around a single line of input. The following is a cross-section of what actually happens when I type "Let's review skill cooldown balance."

Three lanes meet at one input. settings.json wakes the hook, the hook picks the memory and attaches it to the input, and when the response built that way calls a tool, permissions operate as the final gate. The user typed only one line — "check the cooldown" — yet three pieces of infrastructure take their turns out of sight. This is the internal structure of the moment a tool starts to feel like my tool.

1.3.6 First Setup Guide — Operational Within One Hour

We have seen the theory; now we move our hands. One hour after first installing Claude Code, you can lay the whole picture above onto your own PC. I split it into five segments.

0–10 minutes: install and confirm it runs. After installing, run Claude Code from a terminal. In some folder, ask "What's in this folder?" and confirm a response. First check that the tool is alive.

10–25 minutes: write three global memory files. For the auto-loaded global layer, three files are enough.

• MEMORY.md (5 lines) — one line of identity plus pointers to the other files.
• user-profile.md (20–30 lines) — name, role, specialty, contact.
• feedback-collaboration-style.md (20–30 lines) — collaboration rules such as language, tone, action first, concise explanations.

Copying my example verbatim is a fine way to start. Refine it as you operate.

25–40 minutes: basic settings.json setup. Set effortLevel to high, put in the starter permission set (reads and searches automatic; writes and deletes on approval), and take one backup (settings.json.bak_<date>). The backup is the single most important line in this segment.

40–55 minutes: your first five project atoms. Turn five things into atoms — the decisions you keep forgetting, the information you keep asking for. The folder is ~/.claude/projects/<project>/memory/. See Chapter 5 for the format. With five, you get results from global auto-load alone, without building a JIT manifest yet.

55–60 minutes: one test. Open a new session and throw one question from your own field. Check that global memory auto-loaded and that the response tone follows your collaboration rules.

That is the hour. The JIT manifest and the hook can wait until your atoms pass about 50, when auto-load starts to feel heavy — that is the moment to lay down the inject_memory.py from 1.3.2.

1.3.7 Common Mistakes and How to Avoid Them

The mistakes that recur in the early days group into five, and each stands on the same accident cause.

You do not need to dodge all five from day one. Global bloat and the missing backup deserve avoidance patterns within the first hour; for the other three, it is more natural to run for about a month and then fit the avoidance devices into the spots where your own accident probability runs highest.

1.3.8 Closing Part 1

1.1 was where we closed the distance to the tool, 1.2 where we grasped its minimum working mechanism, and 1.3 where we laid the first infrastructure of memory, permissions, and settings. These three chapters form the book's introduction. Finish this far and the basic skeleton for running the tool without stalling is in place.

The key point is that this skeleton is not a static configuration. The atoms in the manifest grow every week, the allow list lengthens along the traces of your work, and scores accumulate through verification. Infrastructure is not finished the moment it is laid — it grows together with its user on top of what was laid. The gap that opens between 17 on my personal PC and 304 at the company is the distance of that growth.

From Part 2 we enter information architecture proper. Chapter 4 covers YAML frontmatter, Chapter 5 atoms, Chapter 6 layers, and Chapter 7 ontology, in that order. The atom you saw in 1.3 as just one manifest entry becomes the protagonist of a whole chapter in 2.2. Only after the spine is set can the domain chapters find their own places on the same coordinates.

Key Takeaways

• Automatic memory injection is a structure where one hook line in settings.json wakes inject_memory.py
• The permissions allow list is not configuration but a trace of accumulated work, and it gets cleaned every quarter
• Infrastructure is not done once laid — it is a living skeleton where atoms, permissions, and scores grow together

Next Chapter Preview

• Part 2 begins: Chapter 4. YAML Frontmatter — Every Document as Data

Try It Yourself

setup 1. Open ~/.claude/settings.json and, before changing anything, take a backup as settings.json.bak_<date> (the suffix is today's date). 2. Put Read(*), Grep(*), Bash(ls:*), and Bash(git status:*) into permissions.allow, and enter Bash(rm -rf:*) and Bash(git push --force:*) into permissions.deny. 3. (Once you have 50 or more atoms) Register python ~/.claude/hooks/inject_memory.py under hooks.UserPromptSubmit, and write the atom entries (name, path, regex, score) plus config.max_matches: 3 into _jit_manifest.json.

prompt - In a new session, ask a question that deliberately includes a keyword from one of the manifest's atoms. Example: "Review skill balance against the cooldown rules."

verify - Check that a signal like [memory injected: N atoms] appears right after the input. - See whether the intended atom is reflected in the response. - Deliberately put broken JSON into the manifest, confirm the prompt still goes through unblocked (the exit 0 guarantee), then restore it.

Solo Scale-Down - Start with no hook and no manifest. In a single global MEMORY.md, write just 3 lines of identity and 3 lines of collaboration rules, and auto-allow only Read(*) and Grep(*). When atoms grow familiar in your hands and approach 50, that is when you add the hook from 1.3.2. Infrastructure starts small and grows along your traces — you do not begin with 304.

Part 2 · Info Architecture

2.1 YAML Frontmatter — Every Document as Data

The night before a milestone build, teammate A, a systems designer, asked me on our team messenger: "How many documents touched the reward curve this week? And how far has review gotten?" I didn't know the answer. The documents were somewhere in the folders; who had last touched them, and which milestone they belonged to, lived scattered across individual memory and file-naming conventions. What we did that night was make one convention: six lines entered at the top of every document. From the next milestone on, those six lines made it possible to answer teammate A's question without anyone opening a folder.

A few lines of YAML written between --- markers at the very top of a document. This is called frontmatter. This convention tells both humans and machines, at the same time, what a document is — without reading a single character of the body. This chapter follows how that one line becomes the entry coordinate for the entire information architecture, with a script that actually runs.

One term up front. This book divides design documents into five Layers (Chapter 6 covers them in earnest): L0 = worldview and concept, L1 = system rules, L2 = content, L3 = data, L4 = implementation coordinates. Dependencies flowing top-down is the normal direction. The layer: 2 that appears in the section below is a coordinate declaration: "this document belongs to the content Layer."

2.1.1 Why "Documents as Data" Rather Than Just "Documents"

Traditional design documents have lived in Word, PowerPoint, and Google Docs. The body text is optimized for human reading. But the metadata — a document's kind, ownership, status, location — is either dissolved into the body or delegated to folder structures and file-naming conventions. So to learn "which milestone does this document belong to, who is responsible, when was it last reviewed," you have to open the body.

Two limitations compound here. First, a document does not declare its own identity. Its identity lives in people's memory and folder conventions, and those conventions corrode over time. Second, AI has no clues for inferring context. Tell Claude Code "review this document," and it reads the body start to finish, wasting tokens, with no idea where the scope of responsibility ends.

YAML frontmatter solves both at once. Put explicit metadata in the first lines of the document, and both humans and machines can identify it without opening the body. It is like a label on the front of a filing-cabinet drawer: you know what's inside without pulling it open. And this label is more than a classification tool. As we'll see later, the single layer field becomes the entry coordinate for procedural generation and automated review.

2.1.2 A Real Frontmatter — The First 14 Lines of One Document

Instead of an abstract example, here is the frontmatter that Project A's reward-curve document actually carries at its head (only IDs and real names are pseudonymized; the structure is exactly as it runs in production).

---
title: "Main Quest Chapter 12 Reward Curve"
layer: 2
status: review
owner: teammate_a
created: 2026-04-15
updated: 2026-05-20
related:
  - quest_main_chapter12
  - reward_curve_milestone_2
affects:
  - L3_BalanceSheet_v2
ip_check: passed
---

# Main Quest Chapter 12 Reward Curve

(body begins)

The point is the separation above and below ---. Above is data the parser reads; below is body text humans read. Markdown renderers usually hide frontmatter, so it does not interrupt reading. One file holds both data (frontmatter) and content (body), becoming a single source of truth.

Watch the two lines layer: 2 and affects: [L3_BalanceSheet_v2]. They declare: "this content (L2) document affects the balance sheet in the data Layer (L3)." From that alone, a tool can draw the L2→L3 dependency as a graph without reading the body. Conversely, if an L3 data document references an L1 system rule via depends_on — a reverse dependency pointing from bottom to top — that is a design smell. A tool detects that reverse reference automatically.

Why YAML is easier to write by hand than JSON is simple: indentation expresses structure, quotes are rarely needed, and # comments are allowed. It suits designers filling it in themselves.

2.1.3 Where the Standard Lives — _NAMING_FRONTMATTER_STANDARD

Fields can multiply without limit. The more they grow, the heavier the writing burden and the faster the standard collapses. So Project A runs two tiers: a minimal set of core fields common to every document, and domain-specific extension fields.

The common core is six fields.

These six alone tell you a document's freshness, ownership, and position at a glance. Resist the urge to add more for the first month. As you operate, which fields you actually need reveals itself naturally.

Extension fields differ by domain. Systems design favors depends_on and affects; combat design, combat_phase and anim_target; narrative, world_region and chapter; balance, data_sheet and formula_id. These extension fields must not scatter freely, so a single standard document nails down each field's official name, allowed values, and examples. That document is _NAMING_FRONTMATTER_STANDARD.md. Adding a new field has to go through it. And the standard document itself is registered as an atom, managed in the same family as the rule that forces a Layer number prefix on document names (the docs_layer_numeric_prefix_naming atom).

An important shift happens here. If the standard is only a document humans read, humans will break it. Make the standard data that machines read, and machines enforce it. The next section is the actual code of that shift.

2.1.4 Worked Transcript — Enforcing the Standard in Code, and the Lesson from a datetime Bug

Now I had Claude Code build "a linter that checks whether every Markdown document in Project A follows the frontmatter standard." There were two core requirements. It had to catch the violations (missing required fields, non-standard status values, layer outside 0–4, documents in review untouched for more than 90 days), and it had to read allowed values from the standard document instead of hardcoding them. That separation is the point: change the standard, and the check criteria change without touching the code. (The full script and the steps to run it yourself are in the "Try It Yourself" section at the end of this chapter.)

Then came an incident. Claude's first version computed the date difference in the STALE check as today - fm["updated"], with a comment saying that if a file reads updated: 2026-05-20, PyYAML auto-parses it as a datetime.date. That is only half true. Run against the real documents, some files threw a traceback.

TypeError: unsupported operand type(s) for -: 'datetime.date' and 'str'

The cause was human hands. Some authors wrote updated: 2026-05-20 (parsed as a date); others wrote updated: "2026-05-20" with quotes (parsed as a string). Where the standard had not pinned down the date format, people's habits split — and Claude assumed only one side. I rejected the code and asked again: "normalize both notations safely to a date, and also handle the case where updated is missing." Claude inserted a helper that checks the input type and normalizes both to datetime.date (the fixed block is also in "Try It Yourself").

The real lesson was not the code bug. It was that people's habits split exactly where the standard had not pinned down the date format. So I added one line to _NAMING_FRONTMATTER_STANDARD.md: updated: YYYY-MM-DD (따옴표 없이) — that is, YYYY-MM-DD, without quotes. The linter, in the middle of doing its checks, ended up exposing a hole in the very standard it was checking against.

The fixed script's first output was not clean. I am leaving the messy result exactly as it came out.

[NO-FM]   manuscript/legacy/old_combat_notes.md
[MISSING] manuscript/system/quest_flag_table.md: layer
[STATUS]  manuscript/content/town_intro.md: WIP
[LAYER]   manuscript/balance/dps_v2.md: None
[STALE]   manuscript/system/inventory_rules.md: 134d

These five lines were the team's actual state in the early days of adoption. Old documents had no frontmatter at all (NO-FM), one document was missing layer, someone used the non-standard value status: WIP, one balance document left layer as None, and one system-rules document had been asleep in review for 134 days. A standard is never followed from day one. The linter merely surfaces that fact every morning.

2.1.5 From Frontmatter to Script — The Flow

Compressed into a single diagram, the worked transcript above looks like this. It shows how one line written by a human flows all the way into the machine's automated checks.

flowchart TD
    A["Author: creates a new document
template auto-inserts the 6 frontmatter fields"] --> B["Fills in only the blank values
title / layer / status / owner ..."]
    B --> C["Saved .md file
--- frontmatter --- + body"]
    C --> D["Linter script runs
rglob('*.md')"]
    D --> E["_NAMING_FRONTMATTER_STANDARD.md
allowed values read from here"]
    E --> F{"Checks
required fields / status / layer / stale"}
    F -->|"pass"| G["Feeds the relation graph
related·affects → L-coordinate dependencies"]
    F -->|"violation"| H["Daily report
auto-notifies the responsible owner"]
    H --> B
    G --> I["AI queries become possible
'Gather Layer 2 docs in review' → instant answer"]
    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    class A,B human
    class D,F code
    class C,E,G data
    class H fail
    class I ai

Two things matter. First, the standard (E) is separate from the script (D). Change the standard, and the check criteria change without touching the code. Second, a violation (H) is not a dead end but a loop back to the writing stage (B). It doesn't blame anyone; it routes the document back so its author fixes their own document.

2.1.6 A Production Case — Six Months on a Mid-Sized Team

On Project A, which I run as design director, we rolled out frontmatter to the entire design team (four to five people) about six months ago. Adoption did not happen in one stroke; it passed through four distinct stages.

The biggest pushback in week one was "you want me to write this by hand every time?" Memorizing and typing six lines for every new document is tedious. The fix was template auto-insertion. VSCode snippets, Obsidian templates, and the "New Document" button on our design portal all insert an empty YAML block automatically. Authors fill in only the blank values. The pushback disappeared within a week.

At one month, standard collisions erupted. With several people adding fields freely, owner, responsible, and author all appeared at once. Same concept, three spellings — both search and automation broke. The fix was to consolidate every field's official name, allowed values, and examples into the single document _NAMING_FRONTMATTER_STANDARD.md, and to make adding any new field go through that document as a rule. The standard stabilized within a month.

At three months, the linter from 2.1.4 came in. Even with a standard, people break it. So a consistency report began generating automatically every morning and landing in the shared channel of our team messenger. Each owner only has to look at their own documents. After automation, standard violations dropped noticeably (author's estimate, not a precise measurement — felt like half or less).

At six months, the combination with AI began to pay off. Once the standard stabilized, queries like these came back with instant answers.

• "Gather every Layer 2 document updated in the last two weeks whose status is review"
• "Draw a timeline of status changes for every document I own"
• "List the other documents this change request affects" — following the related and affects graph automatically

In the end, frontmatter became a shared vocabulary between humans and AI. When a human writes it, AI understands it; when AI writes it, a human verifies it. Both look at the same keys. But remember the week-one pushback, the one-month collisions, the three-month linter, the six-month combination — six accumulated months produced this result. It did not appear in one stroke.

2.1.7 Common Mistakes and How to Avoid Them

The mistakes that recur in early adoption group into five. All of them stand on the same root — "places where the standard was left to human willpower alone."

You don't need to block all five from day one. Set up the avoidance patterns for #1 and #3 in week one; fold in #2, #4, and #5 as you operate, starting wherever your own team stumbles most often.

2.1.8 Starting Small — Making It Stick in Three Weeks

Adopting frontmatter is lighter work than you might expect. Three weeks is enough for it to settle into one team.

In week one, define the core six fields, build the template, and apply it to new documents only, keeping the writing burden minimal. In week two, apply it by hand to the top 20 most-viewed documents, and check in real use which fields are missing. In week three, turn on the linter and the daily report — from then on, the standard is maintained by the strength of tools, not human willpower.

Do not migrate the entire backlog of documents at once. Start with frequently viewed documents and with new documents. After about six months, nearly every document carries frontmatter. Even then, 100% is not the goal. Spending time migrating old documents nobody has ever opened is waste.

Try It Yourself

Run one full cycle yourself, at the smallest possible scale.

setup - Place two or three .md documents to be checked in a working folder. Deliberately remove layer from some, or insert a non-standard value like status: WIP. - Place a minimal standard document in the same folder. status: allowed = ["draft", "review", "approved", "archived"] updated: YYYY-MM-DD (without quotes)

prompt (enter into Claude Code)

Write a Python script that checks the YAML frontmatter of every .md under this folder. Catch missing required fields title·layer·status·owner, status values outside the allowed list (read it from the standard document), layer values that violate the 0–4 integer rule, and documents in review whose updated is more than 90 days old. Handle updated safely whether it comes as a string or as a date, and print violations per file.

verify - Run the script and confirm that every violation you planted gets caught. - Add WIP to the allowed list in the standard document and run again. Confirm that status: WIP now passes even though you didn't change a single line of code. That is the proof that the standard and the code are separated. - Include one document with quotes around updated and one without, and confirm the TypeError from 2.1.4 does not appear.

Reference: The Full Linter Script

This is the code Claude first produced in 2.1.4. The STALE check line (age = (today - fm["updated"]).days) still contains the datetime bug.

import sys, datetime, pathlib, re
import yaml  # PyYAML

ROOT = pathlib.Path("manuscript")
STANDARD = pathlib.Path("_NAMING_FRONTMATTER_STANDARD.md")
REQUIRED = ["title", "layer", "status", "owner"]

def load_allowed_status(standard_path):
    # Extract the allowed `status` values from the standard document
    text = standard_path.read_text(encoding="utf-8")
    m = re.search(r"status:\s*allowed\s*=\s*\[(.*?)\]", text)
    if not m:
        return ["draft", "review", "approved", "archived"]
    return [s.strip().strip('"').strip("'") for s in m.group(1).split(",")]

def parse_frontmatter(md_path):
    text = md_path.read_text(encoding="utf-8")
    if not text.startswith("---"):
        return None
    end = text.find("---", 3)
    block = text[3:end]
    return yaml.safe_load(block)

def main():
    allowed = load_allowed_status(STANDARD)
    today = datetime.date.today()
    violations = 0
    for md in ROOT.rglob("*.md"):
        fm = parse_frontmatter(md)
        if fm is None:
            print(f"[NO-FM]   {md}")
            violations += 1
            continue
        for field in REQUIRED:
            if field not in fm:
                print(f"[MISSING] {md}: {field}")
                violations += 1
        if fm.get("status") not in allowed:
            print(f"[STATUS]  {md}: {fm.get('status')}")
            violations += 1
        if not isinstance(fm.get("layer"), int) or not (0 <= fm.get("layer") <= 4):
            print(f"[LAYER]   {md}: {fm.get('layer')}")
            violations += 1
        if fm.get("status") == "review":
            age = (today - fm["updated"]).days   # ← this is where it breaks
            if age > 90:
                print(f"[STALE]   {md}: {age}d")
                violations += 1
    sys.exit(violations)

The core block that came back after my re-request. It normalizes updated safely whether it arrives as a string or as a date.

def as_date(v):
    if isinstance(v, datetime.date):
        return v
    if isinstance(v, str):
        return datetime.date.fromisoformat(v.strip())
    return None

# Replacement for the STALE check inside main()
if fm.get("status") == "review":
    upd = as_date(fm.get("updated"))
    if upd is None:
        print(f"[MISSING] {md}: updated")
        violations += 1
    elif (today - upd).days > 90:
        print(f"[STALE]   {md}: {(today - upd).days}d")
        violations += 1

Solo Scale-Down

You don't need a team. In a personal notes folder, cut the core fields down to three — title, status, updated — and have the linter catch only one thing: "documents whose status is review and whose updated is more than 30 days old." That alone surfaces, once a week, the documents you started reviewing and then forgot. The standard–template–check triangle works at solo scale exactly as it does for a team.

Key Takeaways

• A line of frontmatter is the smallest data brick that identifies a document without reading the body
• Keep the standard in a document, separate from the code, and you can change the check criteria without touching the code
• The single layer field becomes the entry coordinate for procedural generation and automated review

2.2 Per-Page Atoms — The Anatomy of One Decision per Document

During a new hire's first week, he asked me over chat: "Is the combat cooldown 0.6 seconds? Which document says so?" I answered, "It's in the skill system GDD (Game Design Document — the detailed spec)." He asked again: "Which section of that GDD? It's 220 lines — class design, then damage curves, then even how the UI displays it." I opened the file and found it for him. Line 137. Then he asked one last question: "But why 0.6 seconds? Was 0.5 not an option?" That answer was in no document at all. I remembered we had decided it in a meeting six months earlier, but the reason was buried somewhere in the meeting notes.

That five-minute conversation contains all three failures of a 220-line consolidated document. You cannot find the location (search failure), there is no reason (lost context), and a human has to mediate every time (no automation). Ask an AI the same question and things get worse: it reads all 220 lines and then mixes damage-curve talk — irrelevant to cooldowns — into its answer.

The prescription in this chapter is simple. One document holds one decision. A decision-sized document carved out by this principle is called an atom. Split the 220-line GDD and "the cooldown is 0.6 seconds" becomes one atom, and inside that atom the location, content, reason, exceptions, and relations all sit in one place. Instead of abstractions, this chapter dissects one real atom from end to end: how to name it, what frontmatter to fill in, how to make relations explicit, and how, as a result, the AI picks out exactly that one atom and nothing else.

2.2.1 Picking One Specimen — combat_cooldown_rule_v2

The specimen on the table is one atom actually in operation on Project A. Its name is combat_cooldown_rule_v2. The full file follows. It is not long — it holds only one decision. (The file appears verbatim in its original Korean; each key line is quoted in English as the dissection proceeds.)

---
name: combat_cooldown_rule_v2
title: "Combat Cooldown Rule — v2"
type: rule
layer: 1
status: approved
owner: Lee Minsoo
created: 2026-03-10
updated: 2026-05-12
applies_to: [skill_system, item_system]
---

# Combat Cooldown Rule v2

Why: To limit the number of skills usable at once, reducing the
burden of split-second decisions and preserving the meaning of combo inputs.

Rule: Every active skill has a global cooldown of 0.6 seconds + an
individual cooldown (defined per skill). While the global cooldown is
running, no active skill can be cast.

How to apply:
- Every new skill definition must specify an individual cooldown
- A cooldown column value of 0 in L3_SkillSheet violates this rule
- The build-stage consistency check detects violations automatically

Exceptions:
- Passive skills are exempt from this rule
- Ultimates use a separate gauge system (See: [[ultimate_gauge_system]])

Relations:
- affects: [[combat_dps_calculation_v3]], [[balance_curve_v3]]
- derives_from: [[principle_decision_load_reduction]]
- conflicts_with: [[skill_cancel_rule_legacy_v1]]
- requires: [[combat_input_buffer_system]], [[skill_system_v2]]
- is_a: rule
- part_of: combat_system_master

I will cut this one file into five parts: naming, frontmatter, single decision, relations, traceability. Only when all five are in place does an AI read this atom as "a unit that makes sense on its own."

2.2.2 Part ① Naming — The Name Itself Is a Coordinate

The file name is combat_cooldown_rule_v2. It is not a name picked on a whim; it has a three-segment structure — the domain prefix, the decision body, and the version.

combat_         cooldown_rule          _v2
└ prefix        └ decision body        └ version
  (which domain)  (what it decides)      (which revision)

The prefix combat_ is a coordinate that says "this is a decision in the combat domain." Project A's rule atoms are partitioned into domains by prefix: quest_ (quests), data_ (data operations), docs_ (document operations), meeting_ (meeting notes), portal_ (the design viewer). The prefix alone tells you whose area of responsibility a decision belongs to and where its influences come from.

When naming wavers, everything wavers. If the same decision exists twice, as skill-cooldown.md and as cooldown_skill_v2.md, search breaks, and so does the JIT matching that appears later in this chapter. So Project A pinned the naming rule itself down as an atom before anything else. That atom is atom_naming_convention_v1, and it mandates snake_case, a required prefix, and a version suffix. And the rule is enforced not by human willpower but by a linter. Commit a file name without a prefix and it gets caught at the build stage.

Beneath the naming lies a larger design that runs through this whole book. The frontmatter's layer: 1 is the second coordinate. If the prefix says "which domain," the Layer says "which layer of abstraction." Only when the two coordinates combine is the atom's position fixed as a single point on a plane. Here, Layer is just a coordinate (the detailed definition of layers 0–4 is in 2.3). The cooldown rule is "an input rule that governs generation," so it sits on Layer 1. There is even a separate rule that forces this Layer coordinate onto document names as a numeric prefix — docs_layer_numeric_prefix_naming. A single name carries two explicit coordinate axes.

The essence of this design is not a compulsion to tidy up. There is a line I repeated to the team: "The Layers were split for procedural generation in the first place." When every atom carries an explicit domain coordinate (prefix) and layer coordinate (Layer), an AI can later "take every Layer 1 combat rule as input and auto-generate Layer 2 content." The name is the addressing scheme for that automation.

2.2.3 Part ② Frontmatter — The Label Machines Read

The YAML block between the --- markers above the body is the frontmatter. It applies the standard from 2.1 to atoms as-is, and it is a label read not by people but by machines — the build script, the JIT hook, the relation map generator.

With these labels filled in, automated checks become possible. For example, if a system rule declared layer: 1 directly references a data atom (Layer 3) like [[L3_SkillSheet_row_0042]] in its body, that is a reverse reference (L3→L1) — an upper layer bound to a concrete value in a lower layer. Project A detects this pattern automatically at the build stage, because a rule should reference the format of the data, not a single row of it. Without that one layer line in the frontmatter, the check itself cannot exist.

Handling status: archived is also frontmatter's job. When a decision changes, the atom is not deleted; it receives status: archived plus an archived_at date. Build and JIT exclude archived atoms. The record stays, but it leaves active duty. Over six months of operation on Project A, the archive rate was about 15% (author's own measurement). If that ratio sits close to 0%, I read it as a signal that the archival workflow is not working.

2.2.4 Part ③ Single Decision — Does It Summarize in One Sentence?

The heart of the atom dissection is confirming that the body holds only one decision. The test is simple. Try to summarize the atom's decision in one sentence.

"Every active skill has a 0.6-second global cooldown."

One sentence does it. Pass. If the summary comes out as two sentences — "the cooldown is 0.6 seconds, and during a combo it is reduced by 50%" — that is two decisions. Split it into combat_cooldown_rule_v2 (base cooldown) and combat_combo_cooldown_reduction_v1 (combo reduction).

There are two more auxiliary tests for singleness.

The independent-retirement test. If you retire this one atom, does the system stay standing? Retire the cooldown rule and combat balance wobbles, but the system still runs. The unit is right. Conversely, if retiring it brings five other atoms down with it, those five are really five fragments of one decision. Merge them into a larger atom.

The single-reference test. Can someone elsewhere link just [[combat_cooldown_rule_v2]] and have it carry meaning? If it does, the unit is right. If referencing that one line forces a reader through several parts of the body, it has not been split enough.

A body that passes these tests naturally settles into five sections — Why, Rule, How, Exceptions, Relations. Above all, do not delete the Why. The answer to the new hire's final question from the opening — "Why 0.6 seconds?" — lives here: "to reduce the burden of split-second decisions and preserve the meaning of combo inputs." When someone proposes "let's cut it to 0.5 seconds" six months from now, this one line becomes the starting point of the debate. An atom whose Why is gone becomes a fossil nobody dares to touch.

2.2.5 Part ④ Relations — Arrows Make Impact Analysis Possible

The Relations section at the bottom of the atom is what makes this specimen a node in a graph rather than an isolated memo. The key point is that it does not just say "related documents" — it states the kind of each relation.

flowchart TD
    P["Principle: reduce decision load"] -->|derives_from| C["combat_cooldown_rule_v2"]
    C -->|affects| A1["combat_dps_calculation_v3"]
    C -->|affects| A2["balance_curve_v3"]
    C -->|requires| R1["combat_input_buffer"]
    C -->|requires| R2["skill_system_v2"]
    C -.->|conflicts_with| X["skill_cancel_legacy_v1
(conflict, pending retirement)"]
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    class P,C,A1,A2,R1,R2 data
    class X fail

Six kinds of relation each do a different job.

• derives_from: which higher principle this decision derives from. The 0.6-second cooldown is a concretization of the principle "reduce decision load."
• affects: what is affected when this atom changes. Change 0.6 to 0.5 seconds and the DPS calculation and the balance curve shake. You can pull the impact scope automatically before making a change.
• requires: what must exist first for this decision to hold. Without the input buffer system, the global cooldown swallows player inputs.
• conflicts_with: what it contradicts. It conflicts with the legacy skill-cancel rule, and this link is the signal that "one of the two must be retired."
• is_a / part_of: classification (rule) and membership (combat_system_master). The skeleton of the graph.

With a plain "Related: [Document A], [Document B]" link, a human has to work everything out one item at a time. With relation types entered as an enum, the machine works it out. "Show me everything affected if I change this atom" becomes an automatic query that follows affects, and "find every pair of rules that currently contradict each other" becomes an automatic check that scans conflicts_with. The full ontology design of these six enums comes in 2.4; 2.2 only notes that the atom standard applies that enum ahead of time.

The relation arrows are also input to the relation map generator. Project A's gen_relation_map.py reads every atom's frontmatter layer and Relations section and automatically draws an interactive relation map as HTML, colored by Layer. This is possible only because each atom carries a coordinate (Layer) and arrows (Relations).

2.2.6 Part ⑤ Traceability — The 30 Minutes One Atom Saved

An atom with all five parts in place is traceable. Who made this decision, when, and why, and what counts as a violation — all in one place. The value of traceability shows most clearly not in statistics but in the incidents it actually prevented.

Project A's meeting_image_caption_standard atom is a rule that every image attached to meeting notes must carry a caption stating which screen it shows, why it was attached, and what decision it relates to. Before this atom existed, a screenshot went into a set of meeting notes without a caption, and a week later a team member who saw it spent 30 minutes checking with the author to figure out "what screen is this?" After the atom existed, when the same omission recurred, the build-stage linter caught the caption-less image automatically. Five minutes to fix. 30 minutes became 5.

Another specimen, skill_listing_budget_wrapper_only_policy, is a rule that caps global slash command slots at 12: the actual skills live in a separate directory, and only the 12 wrappers are exposed globally. Before it was codified, global slash commands had ballooned to nearly 40 and chewed into the token budget at every session start. Since the atom was defined, an automatic cleanup tool trims the excess at the start of each session. The rule is enforced by tooling, not by human memory.

Project A has about 304 of these atoms accumulated (author's own measurement, at the six-month mark of operation). Looking only at the broad strokes of the distribution, recurrence-prevention rules (rule) take the largest share, followed by one-off decisions pinned down (decision), domain concepts (concept), and collaboration corrections (feedback). One atom saves minutes, but with 304 of them the cumulative savings cross into days. That is why I call atoms an "asset," not "housekeeping."

2.2.7 From Dissection to Automatic Injection — How JIT Actually Works

So far we have dissected one atom statically. Now watch it in motion. The JIT (Just-In-Time) hook from 1.3 picks only the atoms that match keywords in the input and injects them into context on the spot. The JIT manifest is a JSON file that maps each atom to its matching keywords and a score — here the regex catches both the Korean word for "cooldown" and its English forms.

{
  "name": "combat_cooldown_rule_v2",
  "path": "atoms/combat/combat_cooldown_rule_v2.md",
  "regex": "쿨다운|cooldown|글로벌 쿨다운|GCD",
  "score": 75
}

An actual injection flows like this.

flowchart TD
    A["User input:
What if we cut the skill cooldown to 0.5s?"] --> B["JIT hook:
scans the manifest regex"]
    B --> C{"Cooldown matched?"}
    C -->|"Yes score=75"| D["combat_cooldown_rule_v2
injected in full"]
    C -->|"No"| E["No injection"]
    D --> F["AI reads Why, Rule, and Exceptions
before responding"]
    F --> G["Answer: 0.6s rests on reducing
decision load. Cutting to 0.5s
requires re-reviewing the affects
targets: DPS calc and balance curve"]
    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    class A human
    class B,C code
    class D data
    class F,G ai

The last box is the point. The AI does not merely answer "it was 0.6 seconds." Having read the atom's Why, it gives the rationale; having read affects in Relations, it flags ahead of time what will shake if the value changes (the DPS calculation and the balance curve). All five dissected parts — split small, reasons written down, relations made explicit — come alive in the response.

This is where the one-decision-per-document principle reveals itself as the precondition for automation. If this atom had been the 220-line consolidated GDD, the moment the single word "cooldown" matched, class design, damage curves, and UI would all be injected wholesale, the token budget would shrink, and the AI would lose focus over which of five decisions to answer. The smaller and clearer the atom, the higher the JIT precision. Being finely split is not a virtue of tidiness — it is the precondition for automatic injection.

The score is the device that protects the context budget. When several atoms match one input, only the top N by score are injected (default: 3). The scoring criteria get settled through operation.

• Safety, security, and health atoms = 95–99 (must never be dropped)
• Core message and philosophy atoms = 90–94
• Core domain rules = 75–89 (the cooldown rule sits here, at 75)
• Reference and history atoms = 30–50

2.2.8 Personal Atoms and Team-Shared Atoms — Separating the Two Tiers

The dissected specimen combat_cooldown_rule_v2 is a team-shared atom that earned status: approved. Not every atom starts out in that seat. Project A splits atoms into two tiers.

• Personal atoms — unconfirmed hypotheses, personal memos, point-in-time snapshots. Only you see them. The standard is loose.
• Team-shared atoms — verified rules. The whole team sees them. They must pass naming, structure, and an approval process.

The reason for the separation is psychological. Personal atoms must stay free, so that you can jot down an unverified hypothesis without pressure and retire it a week later. If everything were public to the team from the start, you would think "what if this turns out wrong" and never write it down at all. Conversely, team-shared atoms must be strict, so that everyone trusts and references them.

combat_cooldown_rule_v2, too, probably began as a one-line personal memo: "let's test a 0.6-second cooldown." After it was validated in an alpha build, it was promoted to team-shared as a change request, went through review by another designer, and became approved. This personal-to-team promotion flow is itself one axis of the self-improving loop by which an atom system gets smarter over time.

2.2.9 Five Common Mistakes

The mistakes that recur in the early days of atom operation come down to five. All of them grow from the same root: treating atoms as one-off memos instead of assets.

You do not need to dodge all five perfectly in the first month. Mistakes 1 and 4 are solved together by a single naming convention atom, and 2, 3, and 5 fall into line naturally if you run one quarterly audit around the three-month mark.

2.2.10 On to the Next Chapter

In this chapter we cut one atom into five parts: the name (coordinates), the frontmatter (a machine label), the single decision (the one-sentence test), the relations (impact analysis), and traceability (the 30 minutes it saved). And we saw how all five come alive at once in JIT automatic injection.

Of the two coordinates written into the name, 2.2 only brushed past layer: 1. 2.3 takes that Layer head-on. Give every atom a Layer coordinate and, even across disciplines, you start to see where each other's outputs sit. Then 2.4 formalizes, as an ontology, the six relations whose enum names this chapter merely borrowed (affects, derives_from, conflicts_with, requires, is_a, part_of). In the backbone of the information architecture that runs YAML (2.1) → Atom (2.2) → Layer (2.3) → Ontology (2.4), this chapter was the second vertebra.

Key Takeaways

• One atom is the sum of five parts: name, frontmatter, single decision, relations, and traceability
• The one-decision-per-document principle is not a tidying habit — it is the precondition for JIT automatic injection
• The two coordinates written into the name, domain and Layer, become the addressing scheme for procedural generation

Try It Yourself — Build One Atom and Inject It via JIT

setup. Create an atoms/ directory in your working folder, and write the naming convention atom (atom_naming_convention_v1) before anything else. Three lines are enough: snake_case, required prefix, version suffix. If you use JIT, put an empty array in _jit_manifest.json.

prompt. Pick one decision you keep forgetting, and get an atom draft with the prompt below.

"Turn the following decision into the standard atom format. Decision: 'Active skills have a 0.6-second global cooldown.' Use five sections: Why, Rule, How to apply, Exceptions, Relations. In the frontmatter, include name (snake_case + prefix), type, layer, status: draft, owner, and created. At the end, check whether the decision summarizes in one sentence."

verify. Check the atom you receive in three ways. ① Does the decision summarize in one sentence? (If not, split it.) ② Is the Why non-empty? ③ Add one {"name", "path", "regex", "score"} line to the manifest, then type that regex keyword as an actual input — does the atom get injected? Pass all three and your first atom is done.

Solo Scale-Down

If you are a solo developer with no team, no linter, and no build pipeline, this entire chapter shrinks down to a single folder in your note app.

• Naming: unify file names under one rule, domain_decision_v1. Your own eyes stand in for the linter.
• Single decision: one decision per note. If you cannot write the title as one sentence, split it into two notes.
• Why required: write one line at the top of the note — why it was decided this way. That one line rescues the you of six months from now.
• Relations: instead of a formal enum, three markers — → 영향: (affects), ↑ 근거: (basis), ✕ 충돌: (conflicts) — keep nine-tenths of impact tracing alive.
• JIT substitute: instead of a manifest, open the 1.2–1.3 relevant notes yourself before starting work and paste them in for the AI. That is manual JIT.

The point is not the tools but the habit of the five parts. The first 10 notes are the hardest; once past that hump, your hands make the next 100 on their own.

2.3 Layer Design — Abstracting Game Systems

It was the quarter our design disciplines were growing from three to eight. A combat designer locked a skill's range at 8m. The same week, a level designer locked a dungeon corridor width at 6m. Each decision was perfectly reasonable inside its own discipline. The problem surfaced three weeks later, in the build. An area-of-effect skill punched through the corridor walls, and enemies died where the player couldn't even see them. It was nobody's mistake. The two simply had no window into each other's decisions.

This chapter is about building that window: letting each discipline keep its own room while a single coordinate tells it what is happening next door. That coordinate system is what this book calls the Layer.

2.3.1 Siloing — The Enemy We Keep Meeting

Game design splits into finely specialized disciplines: systems, combat, narrative, content, level, balance, UX, QA. Each discipline has its own tools, deliverables, and meetings. As scale grows, each goes deeper into its own territory until nobody knows what the others are doing. This is called siloing.

The cost of siloing only reveals itself with time.

• The skill range decided by combat design doesn't match the corridor width from level design.
• The NPC motivations designed by narrative collide with the quest reward structure from content design.
• The economy cycle tuned by balance design drifts out of sync with the attendance-reward calendar of live operations (live ops).

Lack of skill is not the cause. Everyone made reasonable decisions within their own discipline; there was simply no channel for noticing the decisions of the others. Patch the gap with meetings and meetings explode; patch it with group chat and the signal drowns in noise. The point is not that meetings and chat are worthless — it is to draw a clear boundary between what they can patch and what they cannot.

The solution is to keep each territory intact (preserving discipline specialization) while letting everyone see each other's flow (integrated visibility). The two demands look contradictory, but align them on a shared coordinate system and you achieve both at once. That coordinate system is the Layer. In office terms: everyone keeps their own desk while looking at the same wall clock and the same calendar.

2.3.2 Defining the Layer — A 5-Tier Abstraction

The Layer this book uses is a 5-tier abstraction, numbered 0 through 4. The higher you go, the more abstract and the more rarely things change; the lower you go, the more concrete and the more often they change.

The role each of the five tiers plays in a procedural generation and automation pipeline appears in the right-hand labels of the diagram above. That mapping is the spine of this chapter. If you see the Layer as nothing more than "well-organized folders," you are seeing only half of it. Each tier corresponds to exactly one stage of the generation pipeline (anchor → rules → body → values → gate) — the last of these being the verification gate, this book's term for what the wider industry would call a quality gate: a checkpoint where a human or a checker verifies output before it moves on.

These five tiers are not a game-only concept. The same spine transfers directly to general IT product development. If you have never made a game, use the job-translation table below to map each tier onto your own deliverables (left: the Layers of game design; right: what occupies the same slot in SaaS, apps, or internal systems).

Read it exactly as you would for games. The higher tiers change rarely (product vision: once a quarter), the lower tiers change often (config values: daily). The silo accident we saw earlier — the skill range colliding with the corridor width — has exactly the same structure as the general-IT accident where "a backend field definition (L3) and a frontend screen rule (L1) drift apart and blow up right before launch." Only the discipline names differ; the spine is one.

These 5 tiers are not absolute. Depending on scale and domain, 4 tiers may be the right fit, or 6 may be needed. The point is not that the number is 5, but the act itself of defining the tiers explicitly.

A single deliverable can also straddle two Layers. A "skill system GDD (game design document — the detailed specification)" carries both system design (Layer 1) and concrete data (Layer 3) at once. In that case, either split the document, or keep its primary Layer at 1 and pull the data section out into a separate sheet — but whichever way you choose, state explicitly which Layer each part lives in.

2.3.3 The Meta-Principle — Specialization and Integration at Once

Disciplines spread horizontally; Layers stack vertically. One discipline's work spans multiple Layers. The matrix below shows the distribution's center of gravity for 11 disciplines (columns) × Layers 0–4 (rows), with cell darkness indicating weight. The darkest cell is that discipline's center-of-gravity Layer.

Read a column and you see which Layers one discipline spans; read a row and you see which disciplines gather on one Layer. In the L0 (vision) row, narrative and art direction are darkest — the two disciplines closest to the vision. In the L3 (data) row, systems, combat, level, balance, and character cluster darkly — a signal that this is where they collide with each other, in the data sheets.

Hold this distribution explicitly and another discipline instantly knows where to look — "I need to check combat's Layer 2." The silo walls don't come down; windows get cut into them.

Compress the whole matrix into one sentence: the vertical axis (Layers) was cut to automate generation, the horizontal axis (disciplines) was cut to preserve expertise — and the two meet in a single cell of the grid.

2.3.4 A Case Study — Real Measurements from an MMORPG Project

On Project A, the MMORPG where I serve as design director, the design team (4–5 people) has been running the Layer system for about six months (the full development team is mid-size, 10–50 people). Let's look at concrete examples.

First, the narrative 5 tiers. The narrative design folder itself is split by Layer.

When a narrative writer changes one branch of the main story at Layer 2, the change ripples into the Layer 3 dialogue sheets — and can have an irreversible effect on the already-recorded Layer 4 voice-overs. Because the Layers are explicit, the blast radius can be traced immediately.

A relation-map generator, gen_relation_map.py, runs alongside this. It analyzes foreign-key relations between data sheets, builds an interactive HTML relation map, and expresses each node's Layer as its color (red = L1 systems, yellow = L2 content, green = L3 data). Which Layer depends on which is visible at a glance. When a dependency flows backward — when L3 fires an arrow at L1 — it is almost always a design flaw.

The procedural level generation master document declares its Layer coordinates in its frontmatter.

---
title: Procedural Level Design Master v0.1
layer_inputs: [L1.World, L2.StoryLine]
layer_outputs: [L3.LevelData, L4.PlayCapture]
---

These two lines declare "this pipeline takes Layers 1 and 2 as input and produces Layers 3 and 4," and the impact-radius calculation on change becomes automatable. The L0 vision needs no explicit mention — it is always an input, because the vision anchor rides along with every generation.

There is also an atom rule that enforces a Layer prefix on document names. One of the team's shared atoms reads:

docs_layer_numeric_prefix_naming: Data sheet filenames must carry a Layer-number prefix (L1_, L2_, L3_). A sheet without the prefix gets a warning from the consistency check.

The simpler the rule, the more powerful it is. A plain name sort already groups files by Layer; AI tools know the Layer from the filename alone. And when a human forgets, the consistency check catches it.

2.3.5 Detecting Reverse References — A Worked Transcript

The previous section (2.3.4) said that "when L3 fires an arrow at L1, it is almost always a design flaw." What happens when you hand this detection to an AI instead of human eyes? Here is one breath of an actual run, transcribed without polish (only company-identifying information anonymized).

[Full Prompt]

Look at the two attached frontmatters and check whether the Layer dependency direction is normal.
References are only normal when they flow from higher numbers→lower numbers. Warn if reversed.

--- Document A (L1_combat_system.md) ---
title: Combat System Skeleton
layer: L1
refs: [L3_skill_damage_sheet, L2_combat_flow]

--- Document B (L3_skill_damage_sheet.md) ---
title: Skill Damage Sheet
layer: L3
refs: [L1_combat_system]

(The prompt hands Claude two frontmatter blocks and one rule — references may only flow from higher Layer numbers to lower ones — and asks it to check the dependency direction and warn on anything flowing backward.)

[Claude's Raw Output — Verbatim, No Summarizing]

I inspected both documents.

Document B (L3_skill_damage_sheet, L3):
  refs → [L1_combat_system]
  Direction: L3 → L1 (concrete → abstract)
  Verdict: Normal. A data sheet referencing the system
        skeleton it follows is the natural direction.

Document A (L1_combat_system, L1):
  refs → [L3_skill_damage_sheet, L2_combat_flow]
  - L1 → L2 : normal (design pointing at a downstream flow)
  - L1 → L3 : ⚠ reverse-direction warning
        The L1 system skeleton directly references the L3
        data sheet. This means "the design document depends
        on specific data values," creating a coupling that
        forces design-doc edits whenever the data changes.

Recommendation: Remove L3_skill_damage_sheet from document A's refs.
      If the system skeleton must know a concrete value, either
      lift that value into L1 as an abstract rule (e.g., "base
      damage = class coefficient × level"), or route via an L2 flow document.

Summary: 1 reverse reference detected (A: L1 → L3).

(Claude judges document B normal — a data sheet referencing the system skeleton it follows — and flags one reverse reference in document A, L1 → L3: a coupling that would force the design doc to change whenever the data changes. It recommends removing the ref, and either lifting the value into L1 as an abstract rule — e.g., "base damage = class coefficient × level" — or routing through an L2 flow document.)

[Human Review / Veto]

The AI's verdict is correct. But the recommendation to "route through an L2 flow document" was too much for this case. What L1 needed to know was the shape of the damage formula, not a specific cell in the sheet. So I adopted only the second recommendation (lifting it into an abstract rule) and vetoed the routing suggestion.

[Follow-Up Request]

Drop the routing suggestion, and show me only the edit diff for
L1_combat_system.md in the direction of "lift only the damage
formula's shape into L1 as an abstract rule." Clean up the refs too.

(The follow-up drops the routing suggestion and asks for only the diff to L1_combat_system.md that lifts the damage formula's shape into L1 as an abstract rule, with the refs cleaned up.)

This one cycle is the home ground of reverse-reference detection. The AI catches the direction violation (automated), a human trims the recommendation to its proper scope (review), and only the narrowed work is requested again (follow-up). On Project A, gen_relation_map.py does this at the graph level, and the portal_layer_change_impact_check atom fires at change-detection time, forcing an impact-radius check.

Had a person done this comparison by hand, opening both documents, matching the refs, and judging the direction takes several minutes. Once documents number in the hundreds, it becomes practically impossible. Reverse references always slip in quietly, one or two at a time, and only blow up in a build much later.

2.3.6 Layer Decomposition = The Precondition for Procedural Generation and Automation

The surface purpose of Layer integration is dissolving silos and unifying the language of collaboration (2.3.1–2.3.5). The essential purpose runs one level deeper. Once Layer decomposition takes root, the preconditions for procedural generation and automation are in place.

The case studies in the previous two sections were the stage where humans decide and AI assists with verification and injection. The next stage is where AI drafts a discipline's mass production itself as candidates, and humans adopt them. Layer decomposition is the precondition for that move, for three reasons. (1) AI candidate generation must be able to specify "generate what, on which Layer." (2) Automated consistency checking only works when the dependency direction between Layers is standardized (the reverse-reference detection of 2.3.5). (3) Automatic change-impact calculation requires a coordinate for which Layer a change happened on. All three converge on one statement: without Layer decomposition, automation itself is blocked. At the end of the hand that drew these coordinates, procedural generation was waiting from the very start.

There is no need to go deep before you have seen the discipline parts, so I will only sketch the two stages of application. Conservative application: humans decide, and AI automatically assists with consistency checks, change-impact calculation, and just-in-time (JIT) injection — the case studies of 2.3.4 and 2.3.5 live here. The tooling cost is small, the cumulative effect shows around month six of operation, and most mid-size (10–50 person) teams can reach it. Progressive application goes one step further: AI generates a discipline's mass production itself as candidates (narrative personas, PCG rulebooks, procedural levels, balance-change candidates, art assets, and so on), and humans decide only "which candidate to adopt." Each discipline's form and tool maturity are covered in that discipline's part.

Progressive application needs three ingredients common to every discipline: (1) Layer separation and labeling infrastructure (frontmatter, atoms, filename prefixes); (2) a candidate generation–evaluation cycle (N AI candidates → automated evaluation → ranking with a reasoned report); (3) a human review gate (only adopted results move on to the next Layer). At no point, however, does the deterministic core (simulation, physics, legal constraints) leave the hands of humans and deterministic code, and every review concludes in a reversible stage — before entering irreversible stages (recording, casting, live exposure, and so on). This reversible/irreversible boundary is a principle shared across all disciplines.

One last note on timing. Conservative application was partially possible even in the 2010s, but progressive application was blocked by three limits: the expressiveness of AI candidate generation, natural-language interpretation in automated evaluation, and the human review burden. With the advance of LLMs, all three entered practical territory, and progressive application came down from a vision on paper to working practice. Here lies the meta-message that runs through this entire book: the progress of AI has raised the feasibility of procedural generation and automation.

2.3.7 Discipline Coordinates — Where This Book's Discipline Parts Live

Each discipline part of this book states in its introduction which Layers that discipline mainly occupies, and uses Layer coordinates freely within its chapters. Here is the summary in advance (it transposes the centers of gravity from the 2.3.3 matrix into a table).

Every discipline touches other Layers too, but knowing the center of gravity reveals the collaboration channels. Balance (L3) and live ops (L2–L4) meet at L3, so they must always work closely together; the two disciplines nearest to vision (L0) are narrative and art direction. These adjacencies surface naturally on the coordinate system.

2.3.8 Start Small, Grow Big

Try to adopt the Layer system perfectly from day one and you will never start. Bringing it in gradually is the right answer.

flowchart LR
    S1["Stage 1
Single-discipline adoption
(recommended: narrative)"] --> S2["Stage 2
Adjacent-discipline expansion
(narrative + content)"]
    S2 --> S3["Stage 3
All-discipline standardization
(filename prefix, consistency checks)"]
    S3 --> S4["Stage 4
AI tool integration
(JIT, change impact, retrospective classification)"]
    S1 -.->|"Small (~10) teams"| E1["Enough up to here"]
    S3 -.->|"Mid-size (10~50) teams"| E2["Recommended up to here"]
    S4 -.->|"Large (100+) teams"| E3["Go this far for full effect"]
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class S1,S2,S3,S4 human
    class E1,E2,E3 pass

• Stage 1 (single discipline): Pick just one discipline (recommended: narrative) and split its folder by Layer. Leave the others alone; run it for a month or two while refining the Layer definitions.
• Stage 2 (adjacent disciplines): Apply it simultaneously to two disciplines whose specialization curves sit close together (e.g., narrative + content), observe the patterns where their Layers interlock, and codify one or two consistency rules as atoms.
• Stage 3 (all-discipline standardization): Give every discipline Layer coordinates, introduce the filename rule (L1_, L2_, L3_ prefixes), and automate the relation map and consistency checks.
• Stage 4 (AI tool integration): Use Layer metadata in the JIT hook, calculate change-impact radii automatically, and add Layer classification to the retrospective system.

Each stage takes at least a month, sometimes a quarter. Push too hard and people burn out. Pacing it so the operating burden never exceeds the adoption value — that is the director's job.

Small teams (\~10) need stages 1–2, mid-size teams (10–50) stage 3, and large teams (100+) must go to stage 4 for the full effect. That does not mean small teams can't use it. Only the depth differs; the core value already begins at stage 1.

2.3.9 Conclusion — The Spine of the Entire Book

The Layer is not a mere folder-organizing technique. It is the meta-principle that binds specialized game design into a single coordinate system AI can reason over — and, beyond that, the shared precondition for procedural generation and automation in every discipline.

• Specialization is preserved — each discipline keeps its expertise and its tools.
• Integration is added — every deliverable aligns on the same coordinate system.
• AI understands this coordinate system and performs automatic injection, consistency checking, and change propagation (conservative application).
• On the same coordinate system, each discipline's progressive application grows in stages.

Every remaining part of this book presupposes this chapter. The discipline parts state each discipline's Layer coordinates in their introductions; the process parts cover operating systems that cut across Layers; and the operations part covers the self-improving cycle of the Layer system itself.

The next chapter (game ontology and knowledge graphs) adds semantic relations on top of the Layers. If the Layer is the coordinate, the ontology is the semantic arrow drawn on those coordinates. Only when the two combine does AI autonomously infer that "this document affects that one."

One thing must be made clear. No automation in this chapter made a decision in anyone's place. In the reverse-reference detection, the machine merely laid out violation candidates; what to accept, and how far, was chosen by a human hand. The Layer is a coordinate system that helps people make better decisions faster — not a device for handing decisions off.

Key Takeaways

• The Layer is a coordinate system that adds integrated visibility while preserving discipline specialization — and the spine of this entire book.
• Each of the five tiers corresponds to one role in procedural generation (anchor, rules, body, values, gate).
• As in reverse-reference (L3→L1) detection, AI catches and humans trim — that is the correct shape of automation.

Key Atoms of This Chapter (Reference)

• layer_unified_design_philosophy — the parent atom of this chapter
• docs_layer_numeric_prefix_naming — the filename prefix enforcement rule
• dead_table_5layer_cleanup — the cleanup rule for sheets outside the 5 tiers
• portal_layer_change_impact_check — automatic change-impact checking

Next Chapter Preview

• Chapter 7. Game Ontology and Knowledge Graphs — Adding Semantic Arrows on Layer Coordinates
• Chapter 8. The Wikilink System — Reference Patterns Extracted from Operating Know-How

Try It Yourself

setup — Pick one discipline folder (recommended: narrative) and split it into five subfolders, from Layer0_Vision/ to Layer4_BuildVO/. Move your existing files into their Layers. For files that are hard to place, use "how often this document changes" as the criterion (the more often it changes, the lower the Layer).

prompt — Pick two data sheet frontmatters, paste in the full prompt from 2.3.5 as-is, and have the AI judge the Layer dependency direction. One precise rule is all it needs: "references must flow only from concrete to abstract (higher numbers to lower numbers)."

verify — When the AI catches a reverse reference, do not accept its recommendation wholesale; trim it to the right scope yourself (the "Human Review / Veto" of 2.3.5). Re-request a diff for only the direction you adopted. When a name sort shows your files grouped by Layer from top to bottom, the prefix rule has taken hold.

Solo Scale-Down

The Layer works even when you work alone. With no team there is no cross-discipline silo, but there is a cross-time silo: the you of three weeks ago and the you of today forget each other's decisions. Split your folders into nothing more than Layers 0–4 — one vision page, a few system skeleton pages, a progression flow, data sheets, build notes — and you instantly find which slot your past self put things in. Attach a single line for the AI, "currently working at L2," and it stops dragging in material from unrelated Layers. Trimming down to 4 or 3 tiers is fine. The number is not the point; the act of making the tiers explicit is.

2.4 Ontology and the Wikilink Graph — Verifying the Semantic Arrows

Monday morning, a change request comes in. Team member A on the combat team posts one line in the team messenger: "Changing the global cooldown from 0.5s to 0.3s. Does this affect anything?" Normally this is where a 30-minute meeting starts. The owner of the damage formula raises a hand, the owner of the combo-cancel rules cuts in, and someone asks, "Doesn't this hit the boss patterns too?" Nobody holds the whole picture in their head, so the meeting fills up with people digging through their memories.

This time is different. One second after the request goes up, a bot posts an automatic comment: "Changing this atom affects 4 atoms: skill_dps_calculation, combat_combo_cancel_v3, refgame_boss_pattern_phase2, balance_curve_v3. Owners: team member B, team member A, team member C." No meeting was held. Four people each checked their own atom, and that was the end of it. (We build this bot ourselves later — 2.4.3.)

This comment is not magic. In 2.3 we gave every atom a Layer coordinate, and in this chapter we add semantic arrows on top of it — which decision affects which. A coordinate only says "something is here." Relations like "this affects that," "that must exist first," "these two must never be enabled together" are arrows drawn on top of the coordinates. This chapter covers how to notate those arrows and how to catch broken ones automatically.

Terminology Notes - Ontology: a system that explicitly defines concepts and the relations between them. This book uses a lightweight version simplified down to 6–12 relations. - wikilink: an inter-document link in the [[atom_name]] format. The notation is borrowed from Obsidian, Roam, and similar tools. - Backlink: the list of "atoms that point at this atom" — the reverse direction of a forward reference. - Orphan node: an atom referenced from nowhere. A signal that it is a deprecation candidate. - Broken link: a wikilink pointing at an atom that does not exist. The residue of typos and renames.

2.4.1 Relations Are Arrows — Why Wikilinks Alone Are Not Enough

In 2.1 we attached metadata with YAML frontmatter, and we scattered wikilinks through atom bodies. That alone already connects the documents into a mesh. The problem is that the connections say nothing about what they mean.

This decision stands on [[skill_cooldown_rule_v2]].

This one line — "this decision stands on [[skill_cooldown_rule_v2]]" — says only that the rule is mentioned. Why is it mentioned? Does this decision need that rule (requires), was it derived from it (derives_from), or does it conflict with it (conflicts_with)? A person reading the sentence knows; a machine does not. Ask the AI "does enabling this decision break anything?" and links without meaning cannot answer.

So we put a relation type on each wikilink. The relations actually used in game design work are surprisingly few. The following six cover more than 90% of cases.

The atom that freezes these six as an enum is ontology_relation_enum_v1. Adding a new relation type means going through change-request review. Even as the set grows, 10–12 is the right ceiling, and starting with just three — affects, derives_from, requires — is plenty. The place to write relations is the atom's YAML frontmatter.

---
name: combat_combo_cancel_v3
layer: 1
affects: [skill_dps_calculation, refgame_boss_pattern_phase2]
derives_from: [vision_taste_focused_combat]
requires: [combat_input_buffer_system, skill_cooldown_rule_v2]
conflicts_with: [skill_cancel_rule_legacy_v1]
---

A person writes only the forward direction, one line. The reverse direction ("who affects me?") is computed by a tool scanning the whole folder. Write affects on both ends and the synchronization burden doubles; the moment you fix one side and forget the other, the graph starts lying. One direction by hand, the other direction by tool — that is the principle running through this entire chapter.

2.4.2 Worked Transcript — Verifying Wikilink Backlinks and Graph Integrity in One Pass

From here on I reproduce one real session in full. The situation: while replacing the combo-cancel rule v2 with v3, we decided to deprecate skill_cancel_rule_legacy_v1. But before deprecating it, we have to check whether any other atom points at this atom (backlinks) and whether the deprecation leaves broken links or conflicts behind (graph integrity). Grep by hand and you will miss things. I hand it to Claude.

The Prompt (in Full)

The attached atom folder (decisions/) contains atoms, and their frontmatter
should carry relations (affects/derives_from/requires/conflicts_with/is_a/part_of).
The bodies contain wikilinks too. I want to deprecate skill_cancel_rule_legacy_v1
— before deprecating, run 3 checks: 1) backlinks 2) broken links
3) conflicts. Don't guess; actually read the files and answer. If you can't find something, say so.
// backlinks = both YAML relations + body wikilinks / broken links = links that go stale or dangling on deprecation
// conflicts = whether any conflicts_with counterpart is still alive with status: approved

(In English: "The attached atom folder, decisions/, contains atoms; their frontmatter carries relations (affects/derives_from/requires/conflicts_with/is_a/part_of) and their bodies contain wikilinks. I want to deprecate skill_cancel_rule_legacy_v1 — before that, run 3 checks: 1) backlinks 2) broken links 3) conflicts. Don't guess; actually read the files and answer. If you can't find something, say so. // backlinks = both YAML relations and body wikilinks / broken links = links that go stale or dangling on deprecation / conflicts = whether any conflicts_with counterpart is still alive with status: approved")

Claude's Output (Raw — Not Summarized, Not Cleaned Up)

(Claude's output below is translated from the Korean original; identifiers, counts, and structure are unchanged.)

I read the 47 files in the decisions/ folder. Here are the results of the 3 checks for skill_cancel_rule_legacy_v1.

1. Backlinks (atoms that point at this atom)

Atoms pointing at it via YAML relations: - combat_combo_cancel_v3 — conflicts_with: [skill_cancel_rule_legacy_v1] - skill_cancel_rule_v2 — derives_from: [skill_cancel_rule_legacy_v1]

Atoms pointing at it via body wikilinks: - combat_combo_cancel_v3 body: "solves the input-buffer problem of the legacy [[skill_cancel_rule_legacy_v1]]" - qa_combat_regression_checklist body: "regression item 3 was written against [[skill_cancel_rule_legacy_v1]]"

So 4 atoms reference this atom. (2 via YAML + 2 via body wikilinks; since combat_combo_cancel_v3 appears on both sides, the actual atom count is 3.)

2. Broken links (what breaks on deprecation)

Deprecation by itself does not "break" any wikilink — the file stays, and only its status becomes deprecated. However: - qa_combat_regression_checklist defines a regression item against the deprecated atom, so it becomes invalid in substance. That is not a broken link, but it is a stale link. Needs review. - If you go as far as deleting the file, all 4 references above become broken links.

⚠️ One ambiguous point: the body of balance_curve_v3 contains a link [[skill_cancel_rule_legacy]] (no _v1 at the end). Whether this is a typo meant to point at _v1, or intentionally refers to a separate atom, I cannot tell from the files alone. There is no file named skill_cancel_rule_legacy in the folder. So this is most likely an already-broken link. It needs confirmation.

3. Conflict residue (is the conflicts_with counterpart alive?)

Atoms tied to skill_cancel_rule_legacy_v1 by conflicts_with: just one, combat_combo_cancel_v3. - status of combat_combo_cancel_v3: approved (alive)

→ The new rule that conflicted with the deprecation target is in normal approved status. This is fine. It is the natural replacement — the old version retires and the new one survives. Not a conflict-residue warning.

---

Summary: deprecation is safe, but handle two things first. (a) The stale link in qa_combat_regression_checklist — update regression item 3. (b) [[skill_cancel_rule_legacy]] in balance_curve_v3 — suspected typo. May already be a broken link.

Human Verification and Rejection

Here I did not take the output at face value. (a) is correct — the regression checklist is mine to update. But I stopped at (b). Claude called the [[skill_cancel_rule_legacy]] in balance_curve_v3 a "suspected typo," but I had to look at the folder myself to see whether it really was a broken link. An AI's "I cannot tell" is an honest signal, not a conclusion.

I opened the folder and checked: a file named skill_cancel_rule_legacy really did not exist. But the git log showed a commit from 6 months earlier that had done one thing — renamed skill_cancel_rule_legacy → skill_cancel_rule_legacy_v1. The body link in balance_curve_v3 never got updated then and slipped through. So this was not a typo; it was a broken link orphaned by a rename. Claude's "suspected typo" guess was only half right. The cause was not a typo but an unpropagated rename. Had I not caught that difference, I would have fixed only the regression checklist and the broken link would have stayed buried.

The Follow-Up Request (Reflecting the Confirmed Facts)

Confirmed. [[skill_cancel_rule_legacy]] was not a typo — it was a broken link
from a rename 6 months ago (_legacy → _legacy_v1) whose body link never got fixed.

So while we're at it, find every "wikilink pointing at a nonexistent atom"
across the whole folder. By body wikilinks, everything whose target file is missing from the folder.
A table of each file and the broken links inside it.

(In English: "Confirmed. [[skill_cancel_rule_legacy]] was not a typo — it was a broken link from a rename 6 months ago (_legacy → _legacy_v1) whose body link never got fixed. So while we're at it, find every wikilink in the whole folder that points at a nonexistent atom — by body wikilinks, everything whose target file is missing from the folder. A table of each file and the broken links inside it.")

I collected every [[...]] body wikilink across the 47 files and checked them against the folder's file list. Broken links whose target file does not exist: 3.

File containing the link	Broken wikilink	Suspected cause
balance_curve_v3	[[skill_cancel_rule_legacy]]	rename not propagated (→ _v1)
quest_reward_table_v2	[[concept_reward_currency]]	target atom never written (planned, but no file)
refgame_boss_pattern_phase2	[[skill_global_cooldown]]	rename not propagated (→ skill_global_cooldown_rule)

Of the 3, the 2 rename cases can be fixed by correcting the target atom name to _v1 / _rule. In the 1 remaining case (concept_reward_currency), the target atom itself does not exist — you either write it or remove the link. I did not fix anything automatically — confirm which you intended, then proceed.

All three were real. Grepping by hand, I would almost certainly have missed the broken link in quest_reward_table_v2. That link was an intentional forward reference — pointing ahead at an atom not yet written — and after 6 months in which nobody wrote that atom, it had become, in effect, a dead promise.

What this session shows is simple. Backlink detection and broken-link detection are work the AI is strong at — reading an entire folder and cross-checking it — while cause determination and intent confirmation belong to the human. The AI goes as far as "this is broken here"; the human goes as far as "why it broke and how to fix it."

2.4.3 What a Graph Makes Visible — Turning Verification Visual

You could rerun the previous section's checks as a prompt every time, but freeze the same checks into code and they become visible at a glance on a graph. On Project A, a graph tool extending the gen_relation_map.py introduced in 2.3 runs as an R&D effort. The core is to read the folder's atoms, build a networkx directed graph, and lay four check functions on top.

import networkx as nx

# build_graph(folder): reads the atom folder and builds a DiGraph
#   from nodes (=atoms) and YAML relation edges. (Full source in "Try It Yourself")

def find_cycles(G):                      # circular dependencies
    return list(nx.simple_cycles(G))

def find_orphans(G):                     # inbound 0 = orphan candidate
    return [n for n in G.nodes if G.in_degree(n) == 0]

The heart of it is two lines. simple_cycles catches circular dependencies (A requires B requires C requires A), and in_degree(n) == 0 catches orphan nodes — no need to write your own DFS. The remaining two functions are one-liners of the same grain. find_broken_wikilinks collects the body [[...]] links with a regex and picks out the ones missing from the node list, and backlinks fall out of walking the graph in reverse (full source in "Try It Yourself"). For visualization, color nodes by Layer and edges by relation type, and draw heavily referenced nodes (those with many inbound edges) larger so the hubs stand out. Like folders in a cabinet sorted with color labels, the patterns surface in your field of view before you go hunting for them.

Below is a graph of the actual relations among the atoms covered in the 2.4.2 session. The arrow direction means "the source atom asserts a relation toward the target atom."

graph LR
    combo[combat_combo_cancel_v3
L1·approved]
    legacy[skill_cancel_rule_legacy_v1
L1·deprecated]
    v2[skill_cancel_rule_v2
L1]
    dps[skill_dps_calculation
L3]
    vision[vision_taste_focused_combat
L0]
    buffer[combat_input_buffer_system
L1]
    boss[refgame_boss_pattern_phase2
L2]
    qa[qa_combat_regression_checklist
L4]
    broken[skill_cancel_rule_legacy
does not exist]

    combo -->|affects| dps
    combo -->|affects| boss
    combo -->|derives_from| vision
    combo -->|requires| buffer
    combo -->|conflicts_with| legacy
    v2 -->|derives_from| legacy
    qa -.stale.-> legacy
    balance[balance_curve_v3] -.broken.-> broken

    classDef dep fill:#eee,stroke:#999,stroke-dasharray:4
    classDef miss fill:#fff,stroke:#cc2222,stroke-dasharray:4
    class legacy dep
    class broken miss

The two dashed edges are the problems caught by human verification in 2.4.2. qa → legacy is the stale link against a deprecated atom; balance_curve_v3 → skill_cancel_rule_legacy is the broken link pointing at a node that does not exist. Drawn as a graph, those two dashed lines stand out among the solid ones. Run everything as text alone and they would have stayed buried somewhere across 47 files, never to be seen.

Four rules run automatically at the verification gate (Layer 4) — this book's term for what the industry calls a quality gate, the stage where automated checks pass or block a change.

• Circular dependency: warn when a requires chain loops back to itself. Detected with simple_cycles.
• Active conflict: warn when two atoms tied by conflicts_with are both status: approved. (The case in 2.4.2 passes because one side is deprecated.)
• Orphan nodes: an atom with zero inbound edges and no parent is a deprecation candidate, reviewed quarterly. The atom graph_orphan_detection_quarterly codifies that cadence.
• Layer inversion: an L1 → L3 affects is normal (a higher-level decision affecting lower-level data); an L3 → L1 affects is suspect. Same principle as the reverse-reference detection in 2.3. Because the atom docs_layer_numeric_prefix_naming forces a Layer-number prefix on document names, inversions get a first-pass filter from filenames alone.

Once these four rules harden into code, there is no need to write a prompt each time as in 2.4.2. The moment a change request goes up, the bot rebuilds the graph and posts the list of affected atoms plus any broken links, cycles, and conflicts as an automatic comment. The "4 atoms will be affected" comment at the top of this chapter is exactly this — the bot promised earlier.

2.4.4 Why Layers — Coordinates Drawn for Procedural Generation

Here we need to pause on why 2.3 and 2.4 belong together. Layer coordinates and relation arrows were not adopted separately; they are two faces of the same purpose.

On the surface, Layers unify the language of collaboration — call one thing "an L1 system decision" and another "L3 data," and people in different disciplines share the same coordinates. But the essential purpose lies elsewhere. Layers were coordinates drawn for procedural generation.

L0 vision is the context anchor — immutable, injected into the AI every time. L1 systems are the input rules of generation — rulebooks, relations, and tags live here. L2 content is where the generated body accumulates; L3 data is the simulation input of values, IDs, and relations; L4 build/QA is the verification gate. The relation arrows operate on these coordinates as constraints on generation. When the AI creates new content, a requires arrow becomes the precondition "this must exist first," and a conflicts_with arrow becomes the prohibition "these must not be enabled together."

Disciplines keep specializing (combat, quests, and economy each hold their own expertise), yet every artifact carries a Layer coordinate, so they stay aware of one another. Specialization and integration hold simultaneously on one coordinate system. Once this graph has grown enough, the AI generates candidates while reading the relation arrows as automatic constraints, and the human only confirms violations at the review gate. The worked transcript in 2.4.2 is the miniature of that — the AI read the graph and found the constraint violations (broken links, conflicts), and the human ruled at the gate.

2.4.5 Domain Concepts Are Nodes Too — A Small Shared Dictionary

The nodes at the start and end of relation arrows are not only decision atoms. Atoms that define domain concepts like "skill," "quest," and "reward" are first-class citizens of the graph. concept_skill_definition_v1 looks like this.

# Skill
Definition: A unit action a character triggers in combat. Comprises input, cooldown, cost, and effects.
Required Properties: input / cooldown / cost / effects
Subtypes: active_skill (is_a) / passive_skill (is_a) / ultimate_skill (is_a)
Not a skill: auto attack [[concept_auto_attack]] / transformation [[concept_transformation]]

(The definition reads: a skill is a unit action a character triggers in combat, comprising input, cooldown, cost, and effects; auto attacks and transformations are explicitly not skills.)

Write boss_skill is_a skill and the parent concept's rules are inherited automatically. Project A has about 19 of these concept-definition atoms, and every decision atom references them. When the vocabulary is unified into one dictionary, the translation burden between meetings, documents, and code disappears. It is keeping one shared dictionary instead of a different one on every desk. The concept_reward_currency caught as a broken link in the worked transcript earlier was exactly that — "an entry promised for the dictionary but never written."

2.4.6 Keep It Light — The Trap of Academic Ontologies

Read this far and the question comes up: "isn't this a formal ontology like OWL/RDF?" No. And it was deliberately built not to be one.

Academic ontologies (OWL, RDF, SKOS) are powerful, but they come with dozens to hundreds of relation types, require dedicated inference engines, and need an ontology specialist on staff to operate. In domains where precise inference is life-or-death — search engines, medicine, law — they are essential. But the inference game design actually needs is only "change impact scope," "prerequisite dependencies," and "conflict detection," and all of it ends at the level of simple traversal — BFS/DFS, walking the graph one step at a time. The previous section catching cycles with one line of networkx is the proof. A formal inference engine is overkill.

There is one criterion. Can a game designer operate it by hand? Six YAML enums, networkx processing, pyvis or D3.js visualization. The moment you cross that line, the tool stops being a tool and becomes one more burden. Lightness is not a compromise; it is design intent.

Five recurring mistakes undermine this. All of them grow from the same root: treating the ontology as an enforced standard.

Mistakes 1, 2, and 3 settle into a pattern within the first month of adoption; review 4 and 5 at the three-month retrospective and they fall into line naturally.

2.4.7 Starting Small, and the Next Chapter

The first month runs at a loss. The burden of writing relations piles up while no visible payoff arrives. So start small. In the first week, use only the three relations affects, derives_from, requires; in weeks 2–4, apply them to 20 core atoms and watch the graph grow. Build one HTML graph view at the level of the previous section in the first month, and from the second month the visualization starts showing its value; by the third month, automated verification (cycles, conflicts, orphans, broken links) is directly cutting meeting time. Enduring that one month of deficit is the fork between adoption succeeding and failing.

Chapter 8, Wikilink, digs into the [[...]] notation this chapter treated as arrows, at the operational level — how to use the backlink panel daily, how to update links in bulk on a rename (how to prevent the unpropagated rename of 2.4.2 in the first place), and how to fold the graph view of tools like Obsidian into day-to-day practice. YAML (Chapter 4) → Atom (Chapter 5) → Layer (Chapter 6) → Ontology (Chapter 7) → Wikilink (Chapter 8) — the completed pentagon of the information architecture.

Try It Yourself

setup. Pick the folder where your atoms live (e.g., decisions/) and get ready to write relation keys in each atom's YAML. Start with just three: affects, derives_from, requires. Unify body links in the [[atom_name]] format.

prompt. Before any deprecation or rename, throw this at the AI.

Read the markdown atoms in this folder. I want to deprecate/change [target_atom].
(1) backlinks: every atom that points at this atom via YAML relations or body wikilinks
(2) broken links: links that break or go stale on change/deletion
(3) conflict residue: any conflicts_with counterpart with status: approved
Check these. Don't guess — actually read the files, and if you can't find something, say so.

(In English: "Read the markdown atoms in this folder. I want to deprecate/change [target_atom]. Check (1) backlinks: every atom that points at it via YAML relations or body wikilinks, (2) broken links: links that break or go stale on change/deletion, (3) conflict residue: any conflicts_with counterpart with status: approved. Don't guess — actually read the files, and if you can't find something, say so.")

verify. Open every spot the AI marked "suspected typo" or "cannot tell" yourself. The cause of a broken link — typo, unpropagated rename, or never written — is for the human to rule on, with the git log and the actual folder. Don't let the AI auto-fix; confirm the intent, then fix it yourself.

The Graph Tool in Full (Excerpted in 2.4.3)

The body text (2.4.3) showed only the two core functions. The full version that builds the graph from the whole folder and runs the four checks follows.

import networkx as nx
import re, yaml, glob, os

REL_TYPES = ["affects", "derives_from", "requires",
             "conflicts_with", "is_a", "part_of"]
WIKILINK = re.compile(r"\[\[([a-zA-Z0-9_]+)\]\]")

def build_graph(folder):
    G = nx.DiGraph()
    files = {}
    for path in glob.glob(os.path.join(folder, "*.md")):
        name = os.path.splitext(os.path.basename(path))[0]
        text = open(path, encoding="utf-8").read()
        fm = yaml.safe_load(text.split("---")[1]) or {}
        files[name] = fm
        G.add_node(name, layer=fm.get("layer"), status=fm.get("status"))
    # YAML relation edges
    for name, fm in files.items():
        for rel in REL_TYPES:
            for tgt in (fm.get(rel) or []):
                G.add_edge(name, tgt, type=rel)
    return G, files

def find_broken_wikilinks(folder, known_nodes):
    broken = []
    for path in glob.glob(os.path.join(folder, "*.md")):
        text = open(path, encoding="utf-8").read()
        for m in WIKILINK.findall(text):
            if m not in known_nodes:
                broken.append((os.path.basename(path), m))
    return broken

def find_orphans(G):
    # inbound 0 and no part_of/is_a parent either
    return [n for n in G.nodes if G.in_degree(n) == 0]

def find_cycles(G):
    return list(nx.simple_cycles(G))

Solo Scale-Down

You don't need the tooling. One atom folder and Claude are enough. When you write a new decision, add just two YAML lines — requires and affects — and whenever a deprecation or rename comes up, run the prompt above once. Graph visualization is a problem for later. The habit of sweeping for broken links and conflicts right before a change — that single pass is what prevents the biggest deficit in solo operation.

Key Takeaways

• Only when semantic arrows are layered onto the coordinates can "what affects what" be inferred automatically
• The AI does backlink and broken-link detection; the human does cause determination and intent confirmation
• Lightness is not a compromise but design intent — a tool you cannot operate by hand becomes a burden

Part 3 · System Design

3.1 The Systems Designer's Work and Layer Coordinates

Thursday, 4:50 p.m. The skill sheet the balance designer had been filling in had just landed. 312 skills. Each skill has a column called effect_id where an effect number goes, and that number points to a row in a separate effect sheet. The two have to line up for the game to run. If they don't, the client calls an empty effect or dies quietly.

I used to check this by hand. One cell in the skill sheet, jump to the effect sheet, confirm the number, jump back. 312 times. Two hours at best. In the last 50 rows, eyes glazing over, I always missed one or two — and those one or two blew up in the QA build.

This chapter is about where those two hours went, and about which coordinate that consistency check occupies on the systems designer's map of work. If you don't fix the coordinates first, you will forever be deciding by gut feel where to plug in AI.

3.1.1 A Systems Designer Makes Four Things

The systems designer is the person who travels the widest range between the abstract and the concrete. They take the fog called vision and haul it all the way down to the hard numbers in the last cell of a data sheet. Four kinds of deliverables come out of that journey.

(1) Translating vision into structure. When the director says "action combat where every hit lands with real impact," the systems designer turns that into a skeleton of skills, combos, cancels, and hitstop. "Player agency over growth" becomes class, skill tree, and equipment systems. It is the first moment fog turns into structure.

(2) Specifying the interfaces between systems. Combat, movement, inventory, shops, quests, and guilds all run at once. Does opening the inventory mid-combat grant invincibility? What if a PvP request arrives in the middle of an enhancement? The answers to these cases add up to the feel of a "well-made" game. Every spot where an answer is missing is a spot where players feel friction.

(3) Owning the data sheets and their schemas. Coefficients for 312 skills, effects for hundreds of items, behaviors for dozens of monster types. The values they either fill in directly or hand off to the balance and content disciplines. But the column definitions (the schema) of the sheets stay in the systems designer's hands. It is the job of building labeled drawers. If the drawers are sloppy, everyone fills them differently and consistency breaks.

(4) Designing behavior logic. Character and monster AI comes out in forms like finite state machines (FSM), Behavior Trees (hereafter BT), decision tables, and procedural rules. This material goes to the programmers and becomes code.

The key point is that all four meet on one person's desk. That is why "what do I spend today on" becomes the systems designer's biggest operational decision.

3.1.2 System Deliverables Have Layer Coordinates

In 2.3 we placed every game-production artifact on a coordinate axis running from L0 (vision) to L4 (build). Now we plot the four deliverables from 3.1.1 directly onto that axis. Few disciplines scatter their deliverables across as many Layers as systems design does.

The following map shows, on a single page, where each deliverable lives on the Layers and whom you meet at each coordinate.

This map says two things. First, the systems designer is responsible for the long distance of receiving L0 and making it reach L4. Second, the segment they build with their own hands is L1–L3, and the collaboration partner changes at each of those three bands. Every band switch changes the collaboration language, so if you are not conscious of the coordinates, meetings keep spinning their wheels.

This does not mean one person touches all of L1–L3, though. On a large team, the L1–L2 owner and the L3 owner split. On a small team, one person covers it all. The coordinates are a map for dividing roles, not an order to dump everything on one person.

3.1.3 Once the Coordinates Are Set, the Slots for AI Become Visible

The map is drawn; now we color it in. Which coordinates get the biggest return on AI? Not a blanket "automate everything" — you choose by the nature of each coordinate.

flowchart TD
    L1["L1 system skeleton
(class count, combat model)"]
    L2["L2 interfaces
(interaction rules)"]
    L3["L3 schema + data
(312-row sheet)"]

    L1 -->|"tied to game identity
humans decide"| H1["AI = assists with variations/verification of human decisions"]
    L2 -->|"case explosion
wide impact"| H2["AI = automated extraction of change impact scope"]
    L3 -->|"structured, repetitive
consistency checks"| H3["AI = owns generation, verification, conversion"]

    H1 --> R["humans make the core decisions,
AI handles detail, consistency, repetition"]
    H2 --> R
    H3 --> R

    style L3 fill:#fff8e1,stroke:#f9a825
    style H3 fill:#e8f5e9,stroke:#2e7d32
    style R fill:#e3f2fd,stroke:#1565c0

The key is that the lower the coordinate, the larger the share AI can own outright. L1's "how many classes should we have" is game identity, so a human must hold it. At the other end, L3's "do all 312 rows of foreign keys line up" is structured and repetitive, so AI should take it whole. L2 sits in between — the human makes the decision, while AI backs it by extracting the impact scope: "if we change this rule, how far does it shake?"

This diagram explains why every exercise from 3.1.4 onward starts near L3. It is the spot with the biggest payoff and the smallest risk. A malfunctioning schema tool causes no accident, the relation map only draws pictures, and the consistency check can be vetoed by a human.

3.1.4 Worked Transcript: Handing the Consistency Check to AI at Coordinate L3

That is it for theory. Now back to that Thursday at the start of 3.1. We have AI check whether the effect_id of all 312 skills matches the effect sheet. No summarizing — I transcribe the exchange exactly as it happened.

Data entry follows the schema-first principle: a human first defines the spec sheet, the Enum and .proto come out of it (via a VBA — Excel's macro language — export), and the csv data is filled in last. So the verification prompt also starts with "read the schema first." And it nails down that the source of truth is not the schema document but the actually exported JSON (json_over_schema_doc_as_source_of_truth). Documents can lie; exported JSON cannot.

The Prompt (in Full)

You are our project's data consistency checker. The input is two exported JSON files. 1) skill.json — each skill object has skill_id, name, and effect_id fields. 2) effect.json — each effect object has effect_id and effect_type.

Check the following. (A) Does every effect_id in skill.json exist in effect.json (foreign key integrity)? (B) Orphan effects — present in effect.json but referenced by no skill. (C) Rows in skill.json where effect_id is empty or 0.

Rules: do not guess. If a field is not in the JSON, report it as "field missing." Output in three sections (A)(B)(C); for each violation, one line with the skill_id (or effect_id) and the reason. If a section has no violations, write only "no violations" in it.

Claude's Raw Output (Untouched, Unpolished)

I have not received the two input JSON files. No file contents are attached to the current message. Please resend one of the following: - The actual contents of skill.json and effect.json (pasted or attached as files) - Or the paths to the two files

Once I have the contents, I will check in (A)(B)(C) order. I will not fabricate results without the files.

Stopping here was, if anything, the signal of trustworthiness. If a plausible report had come back on empty input, that very neatness would be the red flag. The one that asks "give me the files first" instead of conjuring inspection results out of thin air is the one you can trust. I actually pasted the two JSONs in and asked again (only excerpts appear here, for length).

// skill.json (excerpt)
[
  {"skill_id": 1001, "name": "Heavy Strike",   "effect_id": 5001},
  {"skill_id": 1002, "name": "Spinning Slash", "effect_id": 5002},
  {"skill_id": 1003, "name": "Shield Raise",   "effect_id": 0},
  {"skill_id": 1004, "name": "Poison Coat",    "effect_id": 5099}
]

// effect.json (excerpt)
[
  {"effect_id": 5001, "effect_type": "DAMAGE"},
  {"effect_id": 5002, "effect_type": "DAMAGE"},
  {"effect_id": 5003, "effect_type": "BUFF"}
]

Claude's Second Output (on the Real Data)

(A) Foreign key integrity — 1 violation - skill_id: 1004 → effect_id: 5099 does not exist in effect.json (dangling reference)

(B) Orphan effects — 1 violation - effect_id: 5003 (BUFF) → referenced by no skill

(C) Empty/0 effect_id — 1 violation - skill_id: 1003 → effect_id: 0. Could be an intended "no effect" — needs confirmation against the schema whether 0 is a valid value.

Human Verification and Veto

Two of the three were clear bugs. 5099 was a number the balance designer had written into the skill sheet before adding the row to the effect sheet — the classic out-of-order edit. Caught.

But (C) I vetoed. In our project, effect_id: 0 is a valid agreed-upon value meaning "passive slot, no effect." The AI does not know that, so it raised "needs confirmation" — a sound judgment, but not something to count as a violation. So I moved to the next step: codify this convention as an atom, so that from the next check onward the AI knows 0 is a valid value.

The Follow-Up Request (Injecting Domain Knowledge)

Additional rule: effect_id == 0 is a valid agreed-upon value in our project, meaning "passive, no effect." Therefore effect_id == 0 is not a (C) violation. Report only empty strings, null, and negative numbers as (C) violations.

(C) Empty/0 effect_id — no violations (effect_id: 0 treated as a valid agreed-upon value. No empty/null/negative values.)

This one-line convention is exactly how domain knowledge accumulates. Systems design decisions are relatively permanent, so once you pin one down, the same check runs on the same standard a year later. One more decision card stacked in the cabinet.

In this transcript the human did only three things — (1) specified the input order: read the schema first; (2) confirmed that 5099 was a real bug; (3) knew that 0 was valid, and vetoed and corrected the AI's call. The two hours of jumping cell by cell through the other 312 rows are gone. What got automated was the labor of jumping and cross-checking; the three lines of judgment that remain are the core.

3.1.5 Accumulating Assets: Hardening the Coordinates into Code

You could order up the transcript's check by hand every time, but hardening work that repeats at L3 into tools is systems design orthodoxy. I will cite the two I actually operate — not abstract "Project A tools" but things that genuinely run on my desk.

gen_relation_map.py analyzes a sheet's column names and values, auto-detects foreign key relationships, and produces an interactive HTML relation map. Where 3.1.4 had a human drawing the arrow skill.effect_id → effect.effect_id in their head, this script draws that arrow as a picture across the entire sheet set. Spots where a dependency runs backward (the danger of L3 data reverse-referencing the L1 skeleton) jump out of the picture instantly.

The schema-doc skill parses the xlsm's $스키마 (schema) sheet and auto-generates a Markdown schema document. The very schema behind 3.1.4 (C)'s question — "needs confirmation against the schema whether 0 is a valid value" — becomes something a person can read fresh without digging through other files. When the sheet changes, the document follows, which shrinks the chronic disease of documents drifting away from the actual data.

Restating the two tools' positions in coordinates: schema-doc guards the column definitions at L3, and gen_relation_map.py guards the relationships between L2 and L3. AI-assisted prompts (verification like 3.1.4) run on top of them. The three are not separate acts — they cover different heights of the same coordinate axis.

You will walk through these tools hands-on in 3.2, 3.3, and 3.4. 3.1 was the map for deciding where to plug things in; the next three chapters do the plugging.

3.1.6 Gradual Adoption: Start from the Low-Risk Coordinates

Switch on all three tools at once, and the operating burden arrives before the benefit. In my experience the safe order starts from the coordinates where the risk is small (the lower ones).

The timeline is not an absolute standard. Depending on team size and existing infrastructure, it could take twice as long or finish in half the time (author's estimate, unverified). What does not change is the order. By putting the riskiest decision support last, you touch the most sensitive spot only after the first two tools have already built the team's verification habit.

3.1.7 Measurement — Honestly

I record the numbers without polish. What follows was observed on the design team (4–5 people; the full dev team is mid-sized at 10–50; about 6 months of operation) of the MMORPG project I run as director ("Project A" below). It is not precise automated instrumentation but the author's observation based on work logs and retrospective notes — read it for direction and rough proportions only.

• Consistency checks: the 312-row skill↔effect foreign key cross-check took two hours at best by hand (that Thursday at the start of the chapter). With AI verification, excluding input prep, the violation list came back within minutes. What shrank was the jumping-and-cross-checking labor, not the judgment.
• Onboarding new designers: with a single relation-map HTML page, we could cut out several of the meetings that used to explain the system dependency structure in words. The exact count varies by person, so I will not claim one (author's observation).
• Change impact discussions: instead of groping through meetings over "if we change this rule, what shakes," we switched to getting a draft impact scope from AI first and having a human review it. The meeting did not disappear — the meeting became a review.

The point is that the saved time is not time spent not making the game. It flows back into the deep decisions AI cannot take — things like the L1 skeleton. Cut the labor and spend it on judgment — that is this chapter's one-line recommendation.

Try It Yourself: One Consistency Check at Coordinate L3

setup. Export two sheets (say, skills and effects) to csv. If you can, convert them to JSON as well (the principle that the export artifact, not the document, is the source of truth). Pick one foreign key pair between the two sheets (e.g., skill.effect_id → effect.effect_id).

prompt. Use the full prompt from 3.1.4 as is. Do not drop the three key lines — (1) "read the schema/structure first," (2) "do not guess; report what is missing as missing," (3) "if there are no violations, write only 'no violations.'"

verify. Go through the AI's violation list line by line, as a human. Fix the real bugs; veto the false positives caused by domain conventions (e.g., 0 = 효과 없음 — "0 = no effect") and add that convention to the prompt (or an atom). If the same false positive disappears from the next check, you have banked one more asset.

Solo Scale-Down

If you are a solo developer with no team and no sheets, two Google Sheets tabs are enough. One tab is "skills," the other "effects." Link the two with a single effect_id column. Download the tabs as csv and paste them into the 3.1.4 prompt — dangling references and orphan effects get caught just the same on a 30-row sheet as on 312 rows. Only the scale differs; the coordinate is the same. Start at L3, and once it feels natural, climb one band at a time to relation maps and impact scopes.

Key Takeaways

• The four systems deliverables carry coordinates from the L1 skeleton to the L3 sheets, and the coordinate determines the collaboration partner
• The lower the coordinate (toward L3), the larger AI's share and the smaller the risk
• What gets automated is the jumping-and-cross-checking labor; confirming bugs and vetoing false positives — the judgment — stays with the human

3.2 Schema First — The $schema Sheet Comes Before the Data

Monday morning. A new designer had filled in 120 rows of the skill sheet; we built them to csv, and 28 red lines appeared in the client log. class_id references entry 47, but the class sheet has no 47. In the element column, someone wrote Fire, someone else wrote fire, and one row reads 화염 — "flame," written out in Korean. Tracing 28 red lines by hand, one at a time, eats half an afternoon.

The cause of this incident is not that the data was wrong. It is that nobody wrote down, before the data was created, the rules the data had to follow. When the rules live only in someone's head, the rules change the moment the person changes. This chapter covers a workflow that creates the rules — the schema — before the data. And it puts the enforcement of those rules into the hands of tools, as documents, not into human hands.

Terminology Notes - Schema: the column definitions of a data sheet — name, type, range, foreign keys, description. - $스키마: a dedicated column-definition sheet kept inside the Excel data file (xlsm). The name is Korean for "$schema." It holds only the rules for the columns, not data rows. - FK (foreign key): a column that references the PK (primary key) of another sheet — the way class_id points at a row in the Class sheet. - proto: a Protocol Buffers definition (.proto). The data-structure and Enum contract shared by client and server. - Single source of truth: the operating principle of managing each piece of information in exactly one place, so that everyone looks there.

3.2.1 The Input Order Is the Schema

Read "schema first" as merely "define the columns in advance" and you have caught only half of it. The heart of it is the order in which things get entered. The order in which the data-entering hand moves decides whether consistency holds or collapses.

The input order this book recommends is a four-box pipeline.

flowchart LR
    A["$스키마 sheet
(column rule definitions)"] --> B["Enum / *.proto
(code contract via VBA Export)"]
    B --> C["csv data
(rows filled within the rules)"]
    A -.->|schema-doc| D["Schema doc
(auto-generated .md)"]
    C -.->|gen_relation_map.py| E["FK relation map
(auto-generated HTML)"]
    D -.-> F(("AI / humans
read the same definitions"))
    E -.-> F
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    class A,B,C,D,E data

The solid arrows flowing left to right are the enforced input order. Define the $스키마 first, pull Enums and proto out of it with a VBA (Excel's macro language) Export, and fill in csv data only within that contract. The dotted lines are the artifacts that derive automatically from that input — the schema document (schema-doc) and the FK relation map (gen_relation_map.py) — and humans and AI read the same definitions through these derivatives.

As long as this order is enforced, most of the 28 red lines from the opening of this chapter are closed off before the data is filled in. If the fact that element is one of the four values fire/ice/lightning/none is pinned down as a proto Enum, both Fire and 화염 get caught at input time. If the fact that class_id references the Class sheet's PK is stated in the $스키마, the missing 47 is caught first by a check, not by the build.

Flip the order — fill the data first and tidy up the schema later — and the schema becomes after-the-fact cleanup. When you rework column rules on top of 1000 already-accumulated rows, the rules end up following the data, and at that moment the source of truth stands upside down.

3.2.2 Worked Transcript — From $스키마 to csv in One Pass

Instead of explaining in the abstract, I will run one sheet through the whole pipeline, start to finish. Say we are building a new skill sheet. Below is the complete record of the work, done with AI assistance. I am not summarizing; the places where things went wrong and where a human rejected the output are left in as they happened.

Step 1 — A Human Writes the $스키마 by Hand First

No tools, no AI yet. A human defines the column rules directly. This one step is never delegated.

# Skill sheet $스키마 (written by a human)
Column         Type       Range/Constraint     FK                  Description
skill_id       int        1000~9999            (PK)                Unique skill ID
name           string     1~30 chars           -                   Display name
class_id       int(FK)    -                    Class.class_id      Usable classes
cooldown       float      0.0~120.0            -                   Cooldown (sec)
damage_coef    float      0.0~10.0             -                   Attack power multiplier
element        enum       fire/ice/lightning/none  -               Element
is_passive     bool       true/false           -                   Passive flag

Step 2 — Ask the AI for a proto Enum Draft (Full Prompt)

The task: carry the element enum and the FK structure of the $스키마 over into a proto contract. This is format conversion, the kind of work you can hand to an AI.

Prompt (full text): Below is the column spec of a game data sheet. Convert this spec into a Protocol Buffers (proto3) message and Enum. Rules: (1) define each enum-typed column as a separate enum, and its first value must start with _UNSPECIFIED = 0. (2) For FK columns, leave the reference target as a comment. (3) Range constraints cannot be expressed in proto, so leave them as comments only. Do not add any column that is not in the spec.

skill_id int PK / name string / class_id int FK→Class.class_id /
cooldown float 0~120 / damage_coef float 0~10 /
element enum{fire,ice,lightning,none} / is_passive bool

Step 3 — Claude's Raw Output (As Is, Untouched)

syntax = "proto3";

// Skill sheet data contract
// Note: range constraints (cooldown 0~120, damage_coef 0~10)
//       cannot be enforced in proto. Check them in the linter.

enum SkillElement {
  SKILL_ELEMENT_UNSPECIFIED = 0;
  SKILL_ELEMENT_FIRE = 1;
  SKILL_ELEMENT_ICE = 2;
  SKILL_ELEMENT_LIGHTNING = 3;
  SKILL_ELEMENT_NONE = 4;   // ← human review marker
}

message Skill {
  int32 skill_id = 1;       // PK
  string name = 2;
  int32 class_id = 3;       // FK → Class.class_id
  float cooldown = 4;
  float damage_coef = 5;
  SkillElement element = 6;
  bool is_passive = 7;
}

Step 4 — Human Verification and Rejection

Here the human rejects one thing. The AI placed none at the end of the enum, as SKILL_ELEMENT_NONE = 4 — but in the $스키마, none is the default state meaning "no element." The point of contention is proto's value 0. In proto3, an enum's 0 is the slot that gets filled automatically when no value is provided, so the question is whether to keep 0 reserved as _UNSPECIFIED (value never entered) or to fill it with a semantic value like none (deliberately element-less). Merge the two into one slot, and a row whose cell was left blank (a mistake) and a row that deliberately chose no element (an intent) both arrive as 0, forever indistinguishable. The AI did keep _UNSPECIFIED = 0 and none separate, but it pushed none out to slot 4, leaving the most common default state far from searches and debugging.

The decisions the human made: - Keep _UNSPECIFIED = 0 (for detecting omissions). - Leave none where it is, but add to the csv authoring rules: "no-element must be written explicitly as none; blank cells are forbidden." Blank = 0 = UNSPECIFIED is treated as an input error. - Record this decision as one added line in the element row's description in the $스키마: "No element must also be explicit (none). A blank cell is an error."

The AI's output was not used as is. The format was accepted; the semantic boundary was drawn by a human.

Step 5 — Export Enum/proto from the Sheet with the VBA Export Button

The verified proto definition is emitted, consistently, by the Excel Export macro (a button on the $스키마 sheet). No human retypes it in an IDE. The sheet is the source of truth, so the proto comes from the sheet. This order is an extension of the "output is canonical" principle (json_over_schema_doc_as_source_of_truth) covered in 3.3 — the document does not explain the code; the sheet gives birth to the code.

Step 6 — Only Then Fill In the csv Data (AI-Assisted, Retry Included)

Prompt (full text): Create 5 csv rows that satisfy the Skill proto and $스키마 above. Constraints: class_id must be one of [1,2,3] (the PKs that currently exist in the Class sheet); damage_coef must be 0.0 for passives (is_passive=true); element must be the literal strings fire/ice/lightning/none; no blank cells.

One row in Claude's first output was off.

skill_id,name,class_id,cooldown,damage_coef,element,is_passive
1001,화염베기,1,3.5,2.4,fire,false
1002,빙결의손,2,8.0,3.1,ice,false
1003,체력회복,1,0.0,1.2,none,true     ← rejected: passive but damage_coef≠0
1004,번개창,3,5.0,2.8,lightning,false
1005,방어태세,2,0.0,0.0,none,true

Row 1003 violates the rule (is_passive=true requires damage_coef=0.0). The human rejected it and asked again.

Retry (full text): Row 1003 violates the rules. is_passive=true but damage_coef is 1.2. Passives must be 0.0. Fix only row 1003 and send it again.

Claude's revised output: 1003,체력회복,1,0.0,0.0,none,true

That the AI did not get everything right on the first try is not a flaw; it is simply something that happens. What matters is that because the schema was already in place, that one deviant row could be spotted by eye and corrected with a single line. Without the schema, row 1003 would have been discovered after the build, as an in-game bug where a passive skill deals damage.

The lesson of this whole transcript is simple. When the input order is fixed as $스키마 → proto → csv, the AI fills in the format fast and the human reviews only meaning and violations. When the order collapses, the human carries everything, from format all the way to meaning.

3.2.3 schema-doc — So No One Copies the Schema by Hand

Keeping the $스키마 inside Excel is convenient for designers, but to AI, git, and external tools it is a closed room. So we run a tool that automatically converts the $스키마 into Markdown. The slash skill schema-doc does this job.

It works in four steps.

1. Parse the $스키마 sheet of the Excel file (xlsm) (python-calamine, Rust-accelerated)
2. Extract the five elements of each column definition
3. Convert them into a Markdown table
4. Generate <sheet-name>_schema.md (the sheet's name plus _schema.md) in the same folder

The key point is that no human writes the schema twice. Define it once in Excel, and the Markdown is produced by the tool. The two cannot diverge. The trap covered in 3.3 — "make the schema document canonical and it drifts from the actual output" — is avoided here by flipping it: Excel is canonical, the document is derived.

What schema-doc generates (for the Skill sheet from the transcript above):

# Skill sheet schema  (auto-generated — do not edit directly)

| Column | Type | Range/Constraint | FK | Description |
|---|---|---|---|---|
| skill_id | int | 1000~9999 | (PK) | Unique skill ID |
| name | string | 1~30 chars | - | Display name |
| class_id | int(FK) | - | Class.class_id | Usable classes |
| cooldown | float | 0.0~120.0 | - | Cooldown (sec) |
| damage_coef | float | 0.0~10.0 | - | Attack power multiplier |
| element | enum | fire/ice/lightning/none | - | Element. No element must also be explicit (none); a blank cell is an error |
| is_passive | bool | true/false | - | Passive flag. If true, damage_coef=0 |

_source: Skill.xlsm / generated by schema-doc_

Notice how the boundaries the human drew in steps 4 and 6 of 3.2.2 carried straight into the description cells of element and is_passive. A human wrote one line in the $스키마, and now the document, the proto, and the validation all share the same rule. This is what a single source of truth looks like when it actually works.

Once the schema lands as Markdown, it is put to use immediately in three places.

• AI data generation: before producing rows, the AI reads this table and generates only rows that respect the seven defined columns, each constraint, and the FKs.
• Onboarding a new designer: this one table is faster than three meetings.
• The linter: it automatically checks each csv row against this table for violations.

3.2.4 gen_relation_map.py — A Graph That Shows Whether FKs Are Alive

If the schema is the rules inside a sheet, FKs are the rules between sheets. The definition that class_id references the Class sheet is written in the $스키마, but whether that reference is actually alive at this moment requires a separate check.

gen_relation_map.py automatically detects the FK relationships across the data sheets and draws them as an interactive HTML relation map. When arrows like Skill's class_id→Class and Item's set_id→ItemSet gather on one screen, an "FK whose target has disappeared" stands out as a broken arrow. An incident like the missing 47 from this chapter's opening becomes visible while the data is being filled in — as a severed line on the relation map, not as a red line in the build log.

The worked usage and visualization of this tool are covered in earnest in 3.3. From this chapter, remember one thing: if the $스키마 does not state the FKs, there is no graph for the relation map or the consistency check to draw. Stating FKs is not optional; it is a precondition of schema first.

3.2.5 The Five-Step Schema-First Workflow

Generalize the transcript of 3.2.2 and you get five steps. Separate each step's owner from its output, and it becomes clear what a human keeps in hand and what gets handed to tools.

You do not need all five steps in the first month. Running just steps 1 and 2 (schema design + automatic documentation) captures half the value. Attach steps 3–5 gradually, once the operation has settled in. Enforce all five from day one, and the authoring burden will stall the rollout before it takes root.

3.2.6 What I Measured on Project A

On an MMORPG project I run as design director (hereafter "Project A"), I ran this workflow for about six months. Of the figures below, data-sheet column consistency and new-sheet drafting time are actual measurements aggregated from tool logs and work records; FK breakage frequency is an author's estimate (unverified), back-calculated from build-failure issues.

The adoption cost was about 3 days of initial tool development plus about 1 month for the practice to settle in. The operational conclusion: against six months of accumulated benefit, the adoption cost was small. That said, the ratios above are a single case from one team on one project; there is no guarantee they transfer to another team as is.

3.2.7 The AI–Schema Synergy, and Where It Ends

Once a schema is in place, the reliability of AI data generation jumps. The reason: the schema closes off, in advance, the ambiguous input ranges that give hallucination its opening. Given "make me 20 skills" with no schema, the AI invents plausible columns and fills in values incompatible with your sheets. With a schema, the same request comes back as rows that respect the seven defined columns, each constraint, and the FKs. Even when a violation slips through, as with row 1003 in 3.2.2, you point at one line, ask again, and you are done.

But the boundary is sharp. Balance values are never delegated to the AI. If the AI picks damage_coef "reasonably," it collides with the game's intent. The AI's share ends at laying out format-correct candidates quickly; "is 2.4 the right coefficient for this skill" is answered by a human. That does not mean AI is useless for balance — curve smoothness, outliers, and range statistics are things AI catches fast. Let the tools measure the numbers; let humans judge whether the numbers are right.

3.2.8 Common Mistakes and How to Avoid Them

Try It Yourself

setup 1. Pick the single most central sheet in your area (skills, items, or monsters). 2. Add a sheet named $스키마 to that Excel file, and write one line per column with the five elements (name, type, range, FK, description). Do this step yourself, by hand.

prompt (use AI only for the proto/csv drafts)

Convert the $스키마 below into a proto3 message and Enum. The first enum value must be _UNSPECIFIED = 0. Comment the reference target for FKs. Range constraints as comments only. Do not add columns that are not in the spec. (paste your $스키마 here)

Then:

5 csv rows satisfying the proto and $스키마 above. Do not produce rows that violate the constraints. If is_passive=true, damage_coef=0.

verify 1. Check the 5 rows the AI gave you against the schema, line by line. If a row violates a rule, ask again with "row N violates the rules; fix only that row" (rejection and retry are a normal part of the process). 2. Export the $스키마 to .md with schema-doc (or an equally simple Python script of your own) and confirm that the Excel definition and the document match. 3. If there are FKs, check once that the referenced PKs actually exist.

Solo Scale-Down

If you are starting alone, with no tools and no team, one Excel file and one text editor are enough.

1. Create a $스키마 as the first tab of your sheet and write the column rules in five elements (15 minutes).
2. Copy that spec as is and ask the AI for "a proto Enum + 5 csv rows" (10 minutes).
3. Check the returned csv against the schema by eye, and fix the one violating row with a retry (10 minutes).
4. Save the $스키마 text in a text editor as skill_schema.md. This is your first single source of truth.

When you move on to the next sheet, repeat the same four steps. Once 5–10 core sheets line up in the same order within a quarter, that is when automation like schema-doc becomes worth attaching.

Key Takeaways

• Enforce the input order $스키마→Enum/proto→csv, and violations are closed off before the data is filled in
• Excel is canonical and documents are derived; schema-doc binds the two to one source, so humans and AI read the same definitions
• Balance values are decided by humans; AI handles only format-correct candidates and outlier measurement

Next Chapter Preview

• 3.3. Relation Map Visualization — Seeing FK Dependencies with gen_relation_map.py

3.3 Relation Map Visualization — Seeing Dependencies with Your Own Eyes

A new designer came to my desk during his first week at the company. "I'm about to touch the quest reward table — if I change this, what breaks?" I started to answer, pointing at my monitor, then stopped. The picture was in my head: RewardTable hooks into ItemTable, ItemTable hooks into ItemEffectTable, and above them QuestTable references the rewards... But the moment I put that picture into words, it lost its shape inside the listener's head. I drew seven boxes on a whiteboard. The arrows started to tangle. Thirty minutes later he nodded and went back to his seat — and the next day he came back with the exact same question.

That scene is what made me write this chapter. A systems designer carries a dependency graph in their head. The problem is that it exists only there. When the person changes, the picture disappears with them. I needed a tool to externalize the picture, and that is why I built gen_relation_map.py.

With 5\~10 data sheets, your head is enough. Past 30, human working memory cannot keep up. A project's sheet folder usually crosses that line early. A table that spells out in text which sheet depends on which never turns into a picture, no matter how carefully you read it. This chapter follows, start to finish, the worked process of auto-generating an interactive HTML relation map from foreign key (FK) relationships.

3.3.1 Four Problems a Relation Map Solves

Before building the tool, let me pin down what actually gets stuck when there is no relation map. Four scenes kept repeating.

Onboarding a new designer. A new designer books a meeting to learn the system structure. That is the scene above. Dependencies conveyed by mouth do not survive more than a few days in the listener's head. Click through a single relation map together, and more than half of the picture forms in the first meeting. The decisive difference from a hand-drawn whiteboard sketch is that the picture does not get erased — it stays in place.

Debating the impact scope of a change. A system change request comes in. "What does this affect?" A meeting gets scheduled, and even after a long discussion, one or two missed areas surface later. With a relation map, you click the node being changed and follow the inbound edges; the impact scope is right there in front of your eyes. The discussion only needs to settle whether each impact is real, and in what priority order.

Detecting dependency inversions. An L3 data sheet referencing an L1 system document is normal. The opposite direction — an upper Layer directly referencing a lower data sheet — is almost always a design flaw. In an FK list written out as text, humans cannot catch this inversion. In the picture, it shows up instantly as a single arrow whose Layer colors run the wrong way.

Finding orphaned sheets. Every so often you discover a sheet that nothing references. It is a leftover from an old design, or something that was retired on paper while the file stayed behind. It is like an unlabeled box rolling around in a corner of the office. You need the picture to spot that island.

What the four problems share: every one of them is only solved by seeing the structure with your eyes. Text and tables hit a wall.

3.3.2 Worked Transcript: From Data Sheets to a Relation Map

Now we follow the real thing. The input is one folder of data sheets; the output is a single interactive HTML page you open in a browser. In between, I record everything the AI did and every point where a human verified or rejected — nothing left out.

3.3.2.1 The Overall Flow

flowchart TD
    A[Data sheet folder
many xlsm/xlsx files] --> B[1. Scan: collect sheet and column headers]
    B --> C[2. Extract FK candidates
*_id / *Id / spec-sheet FK marks]
    C --> D[3. Match reference targets
column name → target sheet]
    D --> E{Human verification}
    E -->|reject false positives| C
    E -->|pass| F[4. Build graph
nodes=sheets, edges=FKs]
    F --> G[5. Assign Layer metadata
from schema-doc output]
    G --> H[6. Render HTML with pyvis]
    H --> I[relation_map.html
interactive in browser]
    I --> J{Human diagnosis}
    J -->|inversion/island/cycle found| K[Request design fix]
    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    class A,I data
    class B,C,D,F,G,H code
    class E,J,K human

The core is the human verification loop between steps 3 and 5. The machine lays down a draft of FK candidates, and a human weeds out the false positives. Skip this loop and the relation map becomes a plausible-looking but wrong picture.

3.3.2.2 Where the FKs Come From — Input Order

This tool's accuracy is decided by where it pulls its input from. The schema-first principle set in 3.2 applies as-is. The order of authority for FK information goes like this.

1. The $스키마 sheet — the first source of truth for each data sheet. Type, Enum, and FK targets are specified per column. If an FK is written here, that is first priority.
2. *.proto / Enum definitions — the schema exported via VBA (Excel's macro language). They fill in types when the spec sheet is empty.
3. The actual csv output — the real data the sheet exports. Relationships missing from the spec sheet still surface as patterns in the data (for example, if every value in an npc_id column falls inside NPCTable's key range, it is effectively an FK).

Let me make one principle explicit here. The source of truth is the actual JSON/csv output, not the schema document. Even if the spec sheet says reward_id is an FK, if that column is empty in the real data or points at nonsense values, then the spec sheet is wrong. When the two disagree, the tool trusts the data side and records the disagreement itself in a report. This is why schema-doc is not treated as the source of truth.

3.3.2.3 Step 1 — Folder Scan and FK Candidate Extraction

The tool's first move is to open every xlsm/xlsx in the folder and collect sheet and column headers. This step is mechanical and not interesting. What is interesting is the rule for picking FK candidates. At first it was simple: if a column name ends in *_id or *Id, treat it as an FK candidate. But that single rule produced both false positives and misses.

This is where I brought in the AI. I handed over the entire list of column headers and had it infer the FK target sheets. Below are the full prompt I actually sent and the raw output.

Prompt: The following is a list of sheet names and column headers from game data sheets. For each column, infer whether it is a foreign key (FK), and if so, which sheet and which column it references. The usual naming convention is <singular form of target sheet>_id. However, if you are not confident, mark it "uncertain" and state why. Do not fill gaps with guesses.

QuestTable: quest_id, title, npc_id, reward_id, prev_quest_id, region_id
NPCTable: npc_id, name, region_id, faction_id
RewardTable: reward_id, item_id, count, currency_id
ItemTable: item_id, name, item_effect_id, grade
ItemEffectTable: item_effect_id, effect_type, value
RegionTable: region_id, name, parent_region_id

Claude's raw output (PK rows omitted; FK judgments excerpted):

QuestTable - npc_id → NPCTable.npc_id (presumably the NPC who gives the quest) - reward_id → RewardTable.reward_id - prev_quest_id → QuestTable.quest_id (preceding quest, self-reference) - region_id → RegionTable.region_id

NPCTable - region_id → RegionTable.region_id - faction_id → Uncertain: FactionTable is not in the input list. By the naming convention it should reference FactionTable.faction_id, but since that sheet was not provided, the target cannot be confirmed.

RewardTable - item_id → ItemTable.item_id - currency_id → Uncertain: CurrencyTable is not in the list. Currency types may also be managed as an Enum, in which case this may not be an FK. The spec sheet needs to be checked.

ItemTable - item_effect_id → ItemEffectTable.item_effect_id - grade → Not an FK (presumed Enum: grade values)

ItemEffectTable - effect_type → Not an FK (presumed Enum)

RegionTable - parent_region_id → RegionTable.region_id (self-reference, region hierarchy)

Note: the inferences above are based on column naming conventions; actual data values were not checked. In particular, columns that do not end in _id, such as count and value, were excluded from FK inspection — if hidden references exist there, they will be missed.

The human did three things with this output.

• Rejection 1: faction_id → The AI marked it uncertain because FactionTable was missing. Correct. In reality, though, faction_id was an Enum. Factions are fixed at 6 kinds, so they are managed as an Enum with no separate sheet. Because the AI stopped its judgment instead of inventing a sheet that did not exist, a human could check the spec sheet and confirm it as an Enum. Excluded from the FKs.
• Rejection 2: currency_id → The AI left both possibilities open. Looking at the actual data, a CurrencyTable did exist (I had left it out of the input list). Confirmed as an FK. This was a human input omission — nothing to blame the AI for.
• Accepted: the self-reference detection on prev_quest_id and parent_region_id. A plain regex rule would have missed these. The AI attaching the meaning — "preceding quest," "region hierarchy" — made verification faster.

The lesson here is clear. Where the AI was most useful was not fast inference but the restraint to leave unknown slots marked "uncertain." Had it force-filled the blanks, faction_id would have been wired to some wrong sheet, and that false positive would have lived on in the relation map as a fake arrow, misleading the next new designer.

3.3.2.4 Step 2 — Graph Construction and Layer Assignment

Once the verified FK list is in hand, gen_relation_map.py builds the graph. Sheets are nodes; FKs are directed edges. Node size comes from counting inbound edges — how much do other sheets reference me. The more a sheet is referenced, the bigger the node: that is a hub of the system.

The Layer metadata is pulled from the Markdown schema documents generated by the schema-doc skill. The Layer coordinates defined in 3.1 (L0\~L4) are attached to each sheet as labels, and the tool reads them to color the nodes. This link matters. A relation map that does not know about Layers is just boxes and arrows; only when it knows the Layers can it diagnose "inversions" by color.

Here is the tool's internal structure as a code skeleton (core flow only).

# gen_relation_map.py (core flow excerpt)
from pyvis.network import Network

LAYER_COLORS = {          # Layer palette — standardized as a single atom
    "L0": "#2c3e50",      # meta/shared
    "L1": "#2980b9",      # system
    "L2": "#27ae60",      # content
    "L3": "#f39c12",      # data instances
    "L4": "#c0392b",      # derived/cache
}

def build_graph(fk_list, layer_map):
    net = Network(directed=True, height="900px")
    inbound = count_inbound(fk_list)          # aggregate inbound edges
    for sheet in all_sheets(fk_list):
        layer = layer_map.get(sheet, "L0")
        size = 10 + inbound[sheet] * 3        # bigger node for hubs
        net.add_node(sheet, color=LAYER_COLORS[layer],
                     size=size, title=sheet_tooltip(sheet))
    for src, dst, col in fk_list:
        # Detect Layer inversion: warning color when an upper Layer references a lower one
        edge_color = "#e74c3c" if is_reverse(src, dst, layer_map) else "#888"
        net.add_edge(src, dst, title=col, color=edge_color)
    return net

is_reverse is the small heart of this tool. If an edge's source sheet sits on a higher Layer than its destination (e.g., L1 → L3), the edge is treated as an inversion and painted red. When a person opens the picture and sees a red arrow, that is almost always a place that needs fixing.

3.3.2.5 Step 3 — HTML Rendering and the Resulting Structure

The last step is pyvis emitting the interactive HTML. Clicking a node pops a tooltip with that sheet's columns, Layer, and inbound count, and a search box filters by sheet name. This is exactly why it has to be HTML rather than a static PNG — once the node count passes a few dozen, the arrows in a static image tangle into something unreadable. You need to drag nodes apart with the mouse and narrow down to the area you care about by clicking before the pattern emerges.

Here is the structure of the relation map built from the example data above, redrawn as an SVG. Colors mean Layers; a red arrow (absent in this example) would mark an inversion.

Looking at node sizes, RegionTable is the most referenced (both Quest and NPC point at it). That is the hub. ItemEffectTable is a leaf node, so it stays small. For a new designer asking "where do I start if I want to understand this system," the answer is already in the picture, in node-size order.

3.3.3 What the Picture Diagnoses — Combined with Layers

We defined the Layer coordinates in 3.1. When this chapter's relation map lifts those coordinates into the visual realm, four diagnoses that were impossible with text or tables become possible on a single screen.

• Layer inversion — an arrow whose Layer colors flow backward (red). An unnatural structure where a data sheet influences the system design in reverse.
• Isolated nodes — islands connected to no edge at all. Candidates for retirement.
• Hub overload — a giant node with abnormally many inbound edges. A signal that one sheet carries too much responsibility; consider splitting it.
• Circular dependencies — places where the arrows trace a circle. Almost always a design flaw, and they lead to data-loading-order problems.

That said, this does not mean the picture catches every problem. The picture catches structural flaws. Whether a given FK is the semantically correct relationship — for example, whether npc_id really means "the NPC who gives the quest" or "an NPC who appears in the quest" — is not something the picture resolves. That is the human's domain judgment to make. The tool only sets the stage on which that judgment can operate.

3.3.4 Without Automatic Updates, It Rots

A relation map is not a make-once artifact. Sheets are added and changed every week. A relation map left to manual updates drifts from the real structure within a month or two, and a map that misleads is worse than no map at all. A team member burned once by a wrong picture stops looking at pictures — that is the most expensive failure.

So updates are wired to automatic triggers.

• Git pre-push hook — regenerates the relation map before data sheets are pushed. Always-current is guaranteed.
• At change-request time — when a data sheet change request comes in, the before/after relation maps are diffed and attached as a comment. Added edges in green, removed edges in red. The reviewer sees the impact scope as a picture.
• Nightly batch — builds a fresh relation map every night and keeps a diff against the previous day.
• Manual command — generate on the spot with the /relation-map slash command. Used to pull it up live in a meeting.

The generated HTML is auto-deployed to internal static hosting (the design portal). With nothing but a browser — no tool installs — everyone sees the same map. It is like a map kept permanently unfolded next to your desk. Whoever asks, you answer by pointing at the same picture together.

3.3.5 Common Mistakes and How to Avoid Them

In operating gen_relation_map.py, the row that burned me most often is the third one. Trust the *_id rule alone and you miss hidden references like count or value (the AI in 3.3.2.3 warned about this limit on its own), while falsely flagging the Enum grade as an FK. The verification loop that checks both the spec sheet and the real data is the answer to that row.

3.3.6 Try the Solo Scale-Down First

Trying to handle the company's entire set of data sheets at once is heavy, and you burn out before you ever get to show the value. Start small, with one folder from your own domain.

Try It Yourself

setup. 1. Pick one folder containing 5\~10 data sheets you own. 2. Install the dependencies with pip install pyvis openpyxl (for reading Excel, use the excel-reader skill or openpyxl). 3. First check whether FKs are specified in each sheet's $스키마 sheet. If not, just collect the column headers.

prompt. Gather the column header list and send the prompt from 3.3.2.3 as-is. The key is the last line — "If you are not confident, mark it uncertain, and do not fill gaps with guesses." That sentence is what blocks fake arrows.

verify. 1. Go through the AI's FK candidates line by line. Confirm the lines marked "uncertain" against the spec sheet or the real data. 2. Remove suspected Enum columns from the FKs (ones like grade and effect_type that look like FKs but carry no _id). 3. Check that the self-references (prev_*_id, parent_*_id) were caught correctly. 4. Draw the graph from the verified list, open it in a browser, and look for red arrows (inversions) and islands (isolation) with your own eyes.

Solo Scale-Down

If you have no time to build the tool, it is fine to start the first week with a single hand-written mermaid diagram. Write the FKs of 5 sheets directly into mermaid, in the format from 3.3.2.3. Take that one page into a meeting and show it — "this is our system's dependency graph" — and the value proves itself on the spot. Once the value is visible, the automation tool follows naturally. You can let go of the pressure to have a working tool from day one.

Scaling up flows naturally in this order — week 1: a hand-drawn mermaid of your own sheets → week 2: add Layer colors and clicking → month 1: automatic updates (git hook or nightly batch) → month 3: deploy to the internal portal → month 6: a unified relation map of all sheets.

3.3.7 Connecting to the Next Chapter

3.2 covered the inside of the sheets (schemas); 3.3 covered the outside (relationships). 3.4 layers AI-assisted prompt patterns on top. With schemas and relationships in place, it moves on to practical patterns for how AI assists with consistency checks and impact-scope extraction.

Key Takeaways

• Externalize the dependency graph in your head, and the same picture stays in place even when people change.
• In FK extraction, accuracy comes from the verification loop: the AI lays down a draft and a human weeds out the false positives.
• A relation map without automatic updates rots within a month or two and loses trust.

Next Chapter Preview

• 3.4. AI-Assisted System Design Prompt Patterns

3.4 Prompt Patterns for AI-Assisted Systems Design

It was the week right before the alpha build. I added one new class row to the skill sheet and saved. What I did not learn until the build broke the next morning was that the buff ID this class referenced was a row someone had deleted the day before. Tracing back through the broken build to find the cause took two hours. Two hours I would never have spent if I could simply have asked, before that row was deleted, "Is this safe to delete?"

This chapter is about putting that question in the AI's job description. The core is not a knack for writing good prompts. It is making sure you never rewrite the same question from zero — pinning it down. Section 3.2 laid the schema, 3.3 the relation map. Both were the skeleton of the data. This chapter takes the questions a human throws at AI on top of that skeleton and hardens those questions themselves into assets.

Let me nail one thing down first. What AI produces is not an answer — it is a candidate. In every pattern in this chapter, the hand that makes the final decision stays on the human side to the very end.

3.4.1 Two Places Where Ad-Hoc Prompts Leak

When you first start using AI, you type a fresh natural-language prompt on the spot every time. Something like this.

스킬 시트 한번 봐줘. 외래 키 깨진 거 없나 확인하고,
이상한 거 있으면 알려줘. 아 그리고 쿨다운 음수인 것도.

(In English: "Take a look at the skill sheet. Check whether any foreign keys are broken, and tell me if anything looks off. Oh, and negative cooldowns too.")

This prompt leaks in two places.

First, the check items change every time. Today I remembered "negative cooldowns," but tomorrow I forget. The "duplicate PK (primary key)" check I ran yesterday is missing from today's prompt. A check that depends on human memory drops items exactly as often as the human's condition dips.

Second, the output format changes every time. Write the same intent as "check it," "inspect it," or "look it over," and the AI answers with a table one day and running prose the next. When the format wobbles, you cannot feed the results into any further automated processing.

The fix is to take the prompt out of your hands and put it in a drawer. The memo you used to scribble by hand each time becomes a labeled card you pull from the same drawer. That card is what this book calls a slash command (skill) and an atom.

3.4.2 Three Forms of Codification and How to Choose

There are three containers for codifying. What goes into which is decided by call frequency and definition stability.

Work that is frequent and whose definition has hardened goes into a slash command. Work that is frequent but is really a constraint you must never forget goes into atom JIT auto-injection. Work that is occasional but large goes into a template file. And work whose definition is still shifting stays ad-hoc — do not codify it yet. You do not need all three from day one. Start with one or two slash commands and grow once the value shows.

3.4.3 Pattern ① Integrity Check — A Worked Transcript

Rather than explain in the abstract, I will walk one pattern through from start to finish: the pattern that automatically asks "Is this safe to delete?" before a single empty row gets deleted. Its name is /check-sheet. Inside it, the check items and the output format are codified.

The assets it stands on appear in the measured work logs embedded throughout this book. Data entry follows the schema-first principle (atom data_entry_schema_first). The entry order is the $스키마 (schema) sheet → Enum/*.proto (exported via VBA, Excel's macro language) → csv. And the source of truth is not the schema document but the actual JSON output (atom json_over_schema_doc_as_source_of_truth). The integrity check simply carries these two principles over into check rules.

setup — Inside the Codified Command

Open /check-sheet and this is the prompt body inside. This is the part you never have to type by hand again.

역할: 너는 게임 데이터 시트의 정합성 검사기다.

검사할 시트: {{sheet_name}}
참조 가능한 스키마: $스키마 시트 (컬럼별 타입·범위·FK 대상)
참조 가능한 정본: 같은 시트의 export JSON (스키마 문서보다 우선)

검사 항목 (이 순서로):
1. 외래 키 유효성 — FK 컬럼 값이 참조 대상 시트에 실재하는가
2. 범위 위반 — $스키마에 정의된 min/max를 벗어난 값
3. 필수 컬럼 누락 — required=true 컬럼이 빈 행
4. 중복 PK — 같은 PK가 둘 이상

출력 형식 (반드시 이 표 그대로):
| # | 행 | 컬럼 | 위반 종류 | 현재 값 | 수정 후보 | 확신도 |

규칙:
- 수정 후보는 제안만 한다. 절대 시트를 직접 고치지 않는다.
- 확신도는 높음/중간/낮음 셋 중 하나. 추측이면 낮음.
- 위반이 없으면 "위반 0건"만 출력하고 끝낸다.

(In English: the body assigns the role of an integrity checker for game data sheets, takes {{sheet_name}} as the target, points to the $스키마 sheet for per-column types, ranges, and FK targets, and to the exported JSON of the same sheet as the source of truth that outranks the schema document. It runs four checks, in this order: foreign key validity, range violations, missing required columns, duplicate PKs. The output is pinned to one fixed table — #, row, column, violation type, current value, suggested fix, confidence — and three rules close it out: suggest fixes only, never edit the sheet directly; rate confidence as one of high/medium/low, and if it is a guess, mark it low; if there are no violations, output only "0 violations" and stop.)

What matters most in this body is the final three rule lines: "do not edit directly," "rate your confidence," "confess guesses as low." Those three lines tie the AI to the seat that pushes candidates, not the seat that hands down answers.

prompt — The One Line the Human Actually Typed

/check-sheet skill_table

That is all. You pass one sheet name. You do not rewrite the four check items or the output table format. That is what codifying is worth.

Claude's Raw Output

Below is the output that came back when I actually ran it. I am not summarizing — the ambiguous parts and the spots where the AI hesitated are included as-is.

skill_table 정합성 검사 결과입니다. 총 4건의 위반을 발견했습니다.

| # | 행  | 컬럼        | 위반 종류    | 현재 값 | 수정 후보              | 확신도 |
|---|-----|------------|------------|--------|----------------------|------|
| 1 | 142 | buff_id    | 외래 키 위반 | 9007   | 9070 (오타 추정, 1글자) | 중간   |
| 2 | 142 | buff_id    | 외래 키 위반 | 9007   | 9012 (이름 "맹독" 유사) | 낮음   |
| 3 | 88  | cooldown   | 범위 위반    | -1     | 0 (음수 불가)           | 높음   |
| 4 | 215 | combo_next | 필수 누락    | (빈칸)  | 판단 보류               | 낮음   |

주의 사항 몇 가지를 덧붙입니다.

- 1번과 2번은 같은 행(142)의 같은 컬럼에 대한 서로 다른 후보입니다.
  9007이라는 ID는 buff 시트에 존재하지 않습니다. 9070은 숫자 한 자리
  차이라 오타일 가능성이 있고, 9012는 이름이 "맹독"으로 유사해서
  후보로 올렸습니다. 둘 다 확신은 낮습니다. 사람이 골라야 합니다.

- 4번(215행 combo_next 빈칸)은 애매합니다. $스키마에는 required=true로
  되어 있는데, export JSON을 보니 이 컬럼이 빈 행이 12개 더 있습니다.
  명세서가 최신이 아니거나, "콤보 종결 스킬은 combo_next를 비운다"는
  규칙이 있는데 명세서에 반영이 안 됐을 수 있습니다. 제가 단정할 수
  없어서 "판단 보류"로 두었습니다.

- cooldown 외에 범위 검사를 더 돌리고 싶으면 $스키마의 다른 컬럼
  min/max를 확인해야 하는데, 제가 받은 정보에 range_check 컬럼 일부가
  비어 있어서 cast_time 컬럼은 검사하지 못했습니다.

(In English: the check reports 4 violations. Findings 1 and 2 are two competing fix candidates for the same cell — row 142's buff_id is 9007, which does not exist in the buff sheet; 9070 differs by one digit and could be a typo (medium confidence), while 9012 is a buff with the similar name 맹독, "Deadly Poison" (low confidence) — a human has to choose. Finding 3: row 88's cooldown of -1 should be 0, negatives are not allowed (high confidence). Finding 4: row 215's blank combo_next is flagged but left as "judgment withheld" — the spec says required=true, yet the exported JSON shows 12 more rows with this column blank, so either the spec is stale or there is an unwritten rule that combo finisher skills leave combo_next empty. The AI also confesses a limit: part of the range_check information it received was blank, so it could not check the cast_time column.)

What makes this good output is not that it is tidy — it is that it is honest. It did not flatly declare finding 4 "required, so fill it in"; it exposed its own doubt — "the spec may not be current." It also confessed the limit that it could not see cast_time. If the AI had confidently said "fill it with 0," that could have been the wrong answer that breaks combo finisher skills.

verify — Human Verification and Rejection

Now the human rules on each line. "Verification comes bundled with the command" means this table comes out automatically — not that no human looks at it.

• Finding 3 (cooldown -1 → 0): Accepted. High confidence, and a negative cooldown is an obvious entry mistake. Fixed immediately.
• Findings 1 and 2 (buff_id 9007): Held. Both low confidence. I decided to open the buff sheet myself and confirm the actual IDs of the 맹독 ("Deadly Poison") family of buffs. Neither AI candidate was accepted.
• Finding 4 (blank combo_next): Rejected. The AI's suspicion was right. This skill is a combo finisher, so an empty combo_next is normal. It is not a violation. I rejected the finding — the problem is on the spec side.

That last one is the heart of it. At the exact spot where trusting the AI's output as-is would have wrecked perfectly healthy data, the human rejection kicked in. At the same time, finding 4 exposed a defect in the check rule itself: the spec's required=true was wrong.

Re-Request — The Rejection Fixes the Rule

It does not end there. A rejection is input that makes the next check smarter. The human types on.

4번은 위반이 아니야. combo_finisher=true인 스킬은 combo_next가 비는 게
정상이거든. 이 예외 규칙을 검사 항목에 넣어서, 앞으로는 finisher 행의
combo_next 빈칸은 위반으로 잡지 마. 그리고 명세서의 required 정의가
틀렸다고 보이는 항목은 따로 "명세서 의심" 섹션으로 빼서 알려줘.

(In English: "Finding 4 is not a violation. Skills with combo_finisher=true are supposed to leave combo_next empty. Add this exception to the check items, so that blank combo_next on finisher rows is no longer flagged. And when a spec's required definition looks wrong, split those items out into a separate 'spec suspect' section.")

이해했습니다. /check-sheet의 검사 규칙에 예외를 반영하겠습니다.

추가된 규칙:
- combo_next 필수 검사 시, 같은 행의 combo_finisher 값을 먼저 확인.
  combo_finisher=true이면 combo_next 빈칸은 정상으로 처리(위반 제외).

신설 섹션:
- "명세서 의심" — export JSON의 실제 분포가 $스키마 정의와 어긋날 때,
  데이터가 아니라 명세서를 고쳐야 할 후보로 분리해 보고.
  (정본은 JSON이라는 원칙에 따라, 다수 데이터가 명세서를 거스르면
   명세서 쪽을 의심합니다.)

이 변경을 /check-sheet 명령 정의 atom에 기록해 둘까요?

(In English: Claude confirms the exception — when checking combo_next as required, first check the same row's combo_finisher; if true, a blank combo_next is treated as normal — and creates a new "spec suspect" section that reports cases where the actual distribution in the exported JSON contradicts the $스키마 definition, separated out as candidates for fixing the spec rather than the data, following the JSON-is-the-source-of-truth principle. It closes by asking: "Shall I record this change in the /check-sheet command definition atom?")

That final line completes the pattern. One rejection does not end as a one-off fix; it gets recorded in the command definition atom and propagates to the next person and the next check. This is the compound interest of codifying. You never filter the same mistake twice.

3.4.4 Pattern ② Change Impact Extraction — A Worked Transcript

The second pattern erases the two hours from the opening scene. Before changing one row or one decision, it first asks, "How far does this spread?" Its name is /impact. The relation map built in 3.3 (the FK-relationship HTML that gen_relation_map.py produces) is this pattern's fuel.

setup — The Codified Search Paths

Inside /impact, the answer to "where do you have to dig to find every impact without misses?" is codified as four paths.

역할: 너는 변경 영향 범위 추출기다.

변경 대상: {{target}}  (시트명·컬럼·atom_id·시스템 결정 중 하나)

탐색 경로 (넷 다 돌 것):
1. 관계도 인바운드 — gen_relation_map.py 출력에서 {{target}}을
   FK로 참조하는 시트들 (이 시트를 가리키는 화살표)
2. 본문 언급 — sources/manuscript 안에서 {{target}}의 ID·이름이
   직접 등장하는 문서
3. atom affects 관계 — {{target}}과 affects로 연결된 atom들
4. 역참조 — {{target}}을 [[wikilink]]로 가리키는 노트

출력 형식:
| 종류 | 이름 | 연결 근거 | 영향 강도 | 담당 |

규칙:
- 영향 강도는 직접/간접/약 셋이다. 직접 FK는 '직접', 본문 언급은 '간접', 추정은 '약'.
- 누락이 두려우면 약으로라도 올린다. 빠뜨리는 것보다 낫다.
- 우선순위나 작업 지시는 하지 않는다. 목록만 만든다.

(In English: the role is a change impact extractor; the target {{target}} is one of a sheet name, a column, an atom_id, or a system decision. It must walk all four search paths: 1) relation-map inbound — sheets that reference the target as an FK in the gen_relation_map.py output, i.e., arrows pointing at this sheet; 2) text mentions — documents under sources/manuscript where the target's ID or name appears directly; 3) atom affects links — atoms connected to the target via affects; 4) reverse references — notes pointing at the target via [[wikilink]]. The output is a fixed table — type, name, evidence of linkage, impact strength, owner. Rules: impact strength is one of direct/indirect/weak — a direct FK is "direct," a text mention is "indirect," an inference is "weak"; if you fear a miss, list it at least as weak — better than dropping it; no priorities, no work orders — produce the list only.)

prompt

/impact buff_id=9012

One line asks: "I am considering replacing the Deadly Poison buff (맹독, 9012) with a different effect — what gets shaken?"

Claude's Raw Output

buff_id=9012(맹독)의 변경 영향 범위입니다. 4개 경로를 모두 탐색했습니다.

| 종류    | 이름                | 연결 근거              | 영향 강도 | 담당      |
|--------|--------------------|----------------------|---------|----------|
| 시트    | skill_table         | buff_id FK 직접 참조    | 직접       | teammate_a |
| 시트    | monster_drop        | reward_buff FK 참조     | 직접       | teammate_b |
| 시트    | set_item_effect     | proc_buff FK 참조       | 직접       | teammate_a |
| 문서    | 독계열_밸런스_노트.md  | 본문에 "9012" 직접 언급  | 간접       | (저자)     |
| atom    | poison_stack_rule   | affects: 9012          | 간접       | (저자)     |
| 노트    | 상태이상_설계.md       | [[맹독]] 역참조          | 약       | (저자)     |

몇 가지 덧붙입니다.

- skill_table에서 9012를 참조하는 행은 3개입니다(암살자 클래스 스킬).
  교체하면 이 3개 스킬의 실제 효과가 바뀝니다. 가장 강한 영향입니다.

- monster_drop의 reward_buff는 제가 확신이 좀 약합니다. 컬럼 이름이
  reward_buff인데 일부 행은 buff가 아니라 item을 가리키는 것 같은
  값이 섞여 있어서요. 이 시트는 직접 한 번 열어 확인하시길 권합니다.

- "독계열_밸런스_노트.md"는 9012를 텍스트로 언급할 뿐 FK는 아니라
  간접으로 두었습니다. 다만 밸런스 의도가 적힌 문서라 실제 영향은
  강할 수 있습니다. 강도(간접)와 중요도가 다를 수 있다는 점 유의하세요.

- set_item_effect는 세트 아이템 4종에서 proc_buff로 9012를 씁니다.
  맹독을 빼면 이 세트들의 컨셉이 바뀝니다.

(In English: all four paths were searched and six entries came back — three sheets with direct FK references (skill_table via buff_id, monster_drop via reward_buff, set_item_effect via proc_buff), one document (독계열_밸런스_노트.md, a poison-line balance note that mentions "9012" in its text — indirect), one atom (poison_stack_rule, linked via affects — indirect), and one note (상태이상_설계.md, a status-effect design note linked only by a [[맹독]] reverse reference — weak). The AI adds caveats: 3 skill_table rows (assassin-class skills) reference 9012, the strongest impact, since replacing it changes those skills' actual effects; it is less confident about monster_drop because some reward_buff values seem to point at items rather than buffs, so it recommends opening that sheet yourself; the balance note is only a text mention, but since it records balance intent, its real importance may exceed its "indirect" strength; and 4 set items use 9012 as proc_buff, so removing Deadly Poison changes those sets' concepts.)

verify — Human Verification and Rejection

• skill_table (direct, teammate A): Confirmed. Three assassin skills directly affected; needs to be shared with teammate A. Accepted.
• monster_drop (direct): The entry the AI itself doubted. I opened the sheet and checked. Result: the reward_buff column really did have item IDs mixed in, and only 1 row actually referenced 9012. The AI's "weak confidence" confession was accurate. Corrected the strength downward from direct to indirect.
• set_item_effect (direct, teammate A): Confirmed. Four sets affected. Accepted.
• 상태이상_설계.md (weak): A bare reverse reference, no impact on the body. Kept on the list, excluded from the work scope.

Here too, the AI's honesty helped the verification. Had it flatly declared monster_drop "direct," the impact would have been inflated and an unnecessary coordination meeting would have landed on the calendar. Because the AI handed the ball back to the human — "I recommend you check" — the strength got corrected on the spot.

Re-Request — From Extraction to Sharing

Once the list is verified, the next human move is delivering it to people.

직접 영향 받는 담당자별로 묶어서, teammate_a / teammate_b에게
보낼 짧은 공유 메모 초안 만들어줘. "9012 맹독을 X로 교체 검토 중,
당신 시트 N개 행이 영향" 형식으로. 결정은 아직 안 났으니 통보가
아니라 의견 요청 톤으로.

(In English: "Group the directly affected entries by owner and draft short share memos for teammate_a and teammate_b, in the form 'considering replacing 9012 Deadly Poison with X — N rows in your sheets are affected.' The decision has not been made, so set the tone as a request for opinions, not an announcement.")

담당자별 공유 메모 초안입니다. 통보가 아닌 의견 요청 톤으로 잡았습니다.

[teammate_a 앞]
맹독 버프(9012)를 다른 효과로 교체하는 안을 검토 중입니다. 확정은
아니고 의견을 먼저 듣고 싶습니다. 영향 범위:
- skill_table: 암살자 스킬 3개 행이 9012를 참조 (직접 영향)
- set_item_effect: 세트 아이템 4종이 proc_buff로 9012 사용
교체 시 이 스킬·세트들의 컨셉이 바뀝니다. 반대나 보완 의견 있으면
이번 주 안에 알려주세요.

[teammate_b 앞]
monster_drop의 reward_buff 관련해 확인 부탁입니다. 맹독 버프(9012)
교체를 검토 중인데, 영향 행이 1개로 보입니다(reward_buff 컬럼에
item ID가 섞여 있어 처음엔 더 많아 보였습니다). 실제로 이 1개 행만
맞는지 확인해 주실 수 있을까요?

두 메모 모두 "검토 중·의견 요청"으로 두었고, 확정 통보 표현은
넣지 않았습니다. 보내기 전에 교체 후보 효과(X 자리)를 채우셔야 합니다.

(In English: two memo drafts, both in opinion-request tone. To teammate_a: a replacement of the Deadly Poison buff (9012) is under review, nothing is confirmed and opinions come first; affected — 3 assassin-skill rows in skill_table referencing 9012 (direct impact) and 4 set items using 9012 as proc_buff in set_item_effect; the replacement would change those skills' and sets' concepts; please raise objections or suggestions within the week. To teammate_b: a verification request — the 9012 replacement is under review and only 1 monster_drop row appears affected (it looked like more at first because item IDs are mixed into the reward_buff column); could you confirm that this 1 row is indeed the only one? Claude notes that both memos stay at "under review, opinions requested" with no announcement phrasing, and that the replacement-candidate effect (the X slot) must be filled in before sending.)

The two hours from the opening scene disappear right here. You ask about the impact before the change, share it with the owners in advance, and coordination finishes before the next morning's build can break. And what the AI made remains, to the end, a memo draft — the finger that hits send is human.

3.4.5 The Skeleton Both Patterns Share

The two transcripts above follow the same skeleton. Every other pattern rides on it too.

flowchart LR
    A[Codified command
check items, output format, prohibitions] --> B[Human: one-line call
passes only the target]
    B --> C[Claude: raw output
candidates + confidence + self-doubt]
    C --> D{Human verification}
    D -->|accept| E[Apply]
    D -->|correct| F[Fix strength or values]
    D -->|reject| G[Rule defect found]
    G --> H[Update command definition atom]
    H -.applied to the next call.-> A
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    class A,H data
    class B,D,F human
    class C ai
    class E pass
    class G fail

The key is the dotted line at the lower right. A rejection is not the end — it loops back as input that fixes the command itself. The rejected finding 4 in the integrity check became the finisher exception rule, and that rule was recorded in the atom and propagated to the next check. Without this feedback, you re-filter the same wrong answer every week.

Human hands remain in three places: the call (choosing the target), the verification (accept, correct, reject), and the rule improvement (feeding rejections back). In between, the AI does one thing only — pushing candidates.

3.4.6 The Remaining Patterns — Variations on the Same Skeleton

Carry the same skeleton over to other work and the patterns multiply. I will only mark their places here, without transcripts. They all follow the 3.4.5 skeleton as-is, so the key when building them is not to drop the "codified check items" and the "human verification slot."

One thing to nail down about balance calculation. Even when a curve comes out numerically smooth, whether that smoothness matches the game's intent is a different question. You wanted the stretch right before the boss deliberately steep, and the AI shaves it flat as an "outlier" — that happens. So even with curve verification attached automatically, the last line of a balance calculation closes only after a human has held it up against the intent.

3.4.7 Five Operating Principles and a Convergence Point

As patterns multiply, you need operating discipline. The five principles below are not rules to memorize — they are design principles you build into the tools themselves.

One convergence point to close on. On one MMORPG project I ran, the slash commands that stayed stable in systems design converged over time to around 12. That is not a published standard — it is one project's observation (author's experience, unverified). But the direction is clear. You do not grow commands without limit; you add and remove one or two a month and stop at the number that fits in your head. A drawer with 100 labels is the same as a drawer with none.

Do not adopt everything at once. For the first month, codifying one weekly-repeated task into a slash command is enough. Once that one shows its worth, it spreads naturally to two, then three, the next month.

3.4.8 Closing Out Part 3

3.1 laid down the Layer coordinates of systems design, 3.2 the schema, 3.3 the relation map, and 3.4 put AI-assisted prompts on top of them. Here is how the week changes for a systems designer who has come through all four chapters.

flowchart LR
    M[Mon: GDD draft synthesis
4h → 1h] --> T[Tue: integrity check
half a day → 5 min]
    T --> W[Wed: onboarding with one relation map
5 meetings → 1 page]
    W --> Th[Thu: impact extraction
1h meeting → 10 min]
    Th --> F[Fri: retrospective auto-classification
manual → data-driven]
    F --> R[Reinvest the saved time
in design, review, player experience]
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class M,T,W,Th,F ai
    class R pass

Grunt-work hours shrink, and those hours flow back into deep design and thinking about the player experience. Not refilling the saved time with more grunt work — that is the real reason for bringing in the tools.

Part 4, up next, is combat design. It is systems design's closest sibling, and the tools and patterns of 3.1–3.4 carry over as-is.

Key Takeaways

• The cycle of codifying ad-hoc prompts into slash commands, atoms, and templates is where AI assistance pays back the most.
• Every pattern follows the same skeleton: one-line call → raw output → human verification and rejection → rules fed back.
• The AI pushes candidates; the final hand that accepts, corrects, or rejects stays on the human side to the end.

Try It Yourself

setup. Pick one check you repeat every week (for example, sheet integrity). Write down that task's 4 check items and an output table format, and codify them as a single slash command. Make sure the three rules ("do not edit directly / rate your confidence / confess guesses") go into the command body.

prompt. Call it by passing only the target, in one line.

/check-sheet skill_table

verify. Rule on the returned table row by row — accept, correct, or reject. When a rejection appears, that is not bad luck; it is a defect in the rule. Send one more line adding that exception to the command definition, so the next call never filters the same mistake twice.

Solo Scale-Down

If you have no team and no atom system, keep one text block in your notes app instead of a slash command. Title it "sheet check prompt." The contents: the 4 check items from setup above plus the 3 rules. Every time you run a check, copy the block, swap in the sheet name, and paste it to the AI. When something gets rejected, add the exception line to that note block yourself. Whether the tool is a slash command or a single note, the cycle — codify → call → verify and reject → update the rule — turns exactly the same.

Part 4 · Combat Design

4.1 The Combat Designer and the Layer Stack — Which Cell Does Game Feel Go In

Learning Goals for This Chapter (difficulty 🟡 practitioner · prerequisites: basic arithmetic and spreadsheet math): By the end, you will be able to decompose an abstract adjective like game feel into measurable signals, and assign coordinates for which Layer cell each of the combat designer's five deliverables sits in.

A build review meeting. The programmer pulls up the new skill they just hooked in. The character swings a sword; the enemy gets knocked back. Five people are watching. Someone says,

"Hmm... the hit feels a little weak somehow."

The person next to them nods. "Yeah, it's kind of flat."

The programmer asks, "What should I change, and by how much?"

Silence. None of the five people in the room can answer that question with a number. All five felt that "the hits feel weak," but nobody can say "take the hitstop from 3 frames to 5." The meeting spends 40 minutes trading adjectives — "make it heavier," "it lacks impact" — and ends with "let's look at it again in the next build."

This scene compresses every problem in combat design. It is the area players feel most directly, yet the moment you put that feeling into words, all you have left are adjectives. Adjectives can't be measured, and what can't be measured can't be tuned. The combat designer's first job is to pull those adjectives down into numbers.

This chapter decides which cell those numbers go in: where each of the combat designer's five deliverables sits on the Layer stack, and why those coordinates are the precondition for automation. The hands-on tools in 4.2, 4.3, and 4.4 move on top of these coordinates.

One Line for Non-Specialists. You don't need to memorize combat values or frame units in this part. The single thing to take away is this — "a request that travels as adjectives can be neither measured nor tuned." The moment you pull "make it heavier" down to "change what, to what value," collaboration starts to move — and that idea applies unchanged to vague feedback in any job outside games. Skim the five deliverables in 4.1.1 lightly; this one idea is all you need to carry forward.

4.1.1 The Five Things on a Combat Designer's Desk

Summed up in one line, the deliverables a combat designer owns cover "the entire process by which player input is converted into on-screen action." I split that into five chunks.

First, the combat Look & Feel spec. A document that translates abstractions like game feel, responsiveness, and weight into measurable values. This is the hardest deliverable in the discipline, and it becomes the yardstick by which the other four are judged.

Look & Feel breaks down into four signals.

• Hit timing — how many ms pass from the moment the input button is pressed until a visual or audio response appears on screen
• Hitstop — how many frames the screen freezes at the moment a hit lands (typically 1–6 frames)
• Camera shake — amplitude, duration, decay curve
• Effect synchronization — whether VFX, SFX, and UI feedback trigger on the same frame

Without this spec, the meeting-room scene repeats. With it, the tuning order comes out as "hitstop 3→5 frames, camera shake amplitude +20%."

Second, the skill, combo, and cancel system. The rules by which input is converted into action.

• Skill flow: input → cast → activation → recovery
• Combo rules: which skill can follow which skill, and what the bonus is
• Cancel rules: which actions can be canceled into which actions mid-motion
• Input buffer: how wide the window (ms) is for accepting the next input mid-action

Third, character and monster AI. NPC behavior logic — Behavior Trees (BT), state machines (FSM (finite state machine)/HFSM), and decision tables. Monster behavior patterns, boss phase transitions, allied NPC cooperation, and crowd simulation all live here.

Fourth, the damage, resource, and cooldown formulas. The math that converts player choices into outcomes: damage coefficients, defense mitigation, criticals, elemental modifiers; resource (MP/energy/stamina) consumption and recovery curves; cooldown distribution.

Fifth, the animation control spec. The blueprint that determines how design intent actually looks in the build — animation graphs, BTs, IK hookups. This is usually a collaboration with programmers and animators, but if the designer doesn't supply a spec of intent, the intent breaks in the build. Hand over the materials without a blueprint, and a different house gets built.

The key point here is that all five meet on the same desk. Change the combo rules (second) and the DPS in the damage formulas (fourth) shifts, which in turn changes the perceived weight in Look & Feel (first). If it isn't explicit which deliverable is the input to which, a single change shakes five places at once. That's why we need coordinates.

4.1.2 Which Layer Cell the Five Deliverables Sit In

Now I place the five combat deliverables on the L0–L4 coordinates established in 2.3. This mapping is the spine of the chapter.

flowchart TD
    L0["L0 · Vision
'Action combat where the hits feel alive'"]
    L1["L1 · System Skeleton
Combo & cancel structure / Look&Feel spec / class skeleton"]
    L2["L2 · Content Flow
Per-chapter enemy pack curves / skill unlock order"]
    L3["L3 · Data Sheets
Damage coefficients, cooldown values, resource costs"]
    L4["L4 · Build Measurement
Measured DPS / actual combo routes / player feedback"]

    L0 -->|"received"| L1
    L1 -->|"skeleton defines the flow"| L2
    L1 -->|"spec anchors the values"| L3
    L2 --> L3
    L3 -->|"lands in the build"| L4
    L4 -.->|"measurement → spec revision feedback"| L1
    L4 -.->|"outliers → sheet adjustments"| L3

    classDef vision fill:#2d3748,stroke:#1a202c,color:#fff
    classDef build fill:#c05621,stroke:#7b341e,color:#fff
    class L0 vision
    class L4 build

Restated as a table:

What makes combat design distinctive is that L4 carries more weight here than in any other discipline. In narrative design, the L1 spec is very nearly the final product; combat is different. Whether "the hits feel good" lives in the territory you can only know by picking up the controller in the build and watching the screen. Even if the spec says "hitstop: 5 frames," whether that actually feels weighty is confirmed only at L4. That's why simulation and automated measurement tools create their biggest value in this discipline (4.4).

But a large L4 doesn't make L1 any less important. Look at the dotted arrows. L4 measurements feed back into the L1 spec. Without a spec, the measurements lose their point of comparison. Only with a 5-frame spec can you get the diagnosis "measured 4 frames — 1 frame missing." The cycle of spec → build → measurement → spec revision passes through all five Layers. The combat designer keeps a hand on this entire cycle — the seat where more Layers spin simultaneously on one desk than anywhere else.

4.1.3 From Adjectives to Numbers — One Spine of the Real Work

That's enough abstraction. Let's go back to the meeting room and watch, as a worked transcript, the actual process of pulling "the hits feel weak" down into numbers. The tool is a single LLM. The output is not polished, and the parts the human rejected are left in as-is.

This is a reconstruction of the actual flow in which the combat task force (TF) of an MMORPG project I run as design director (hereafter "Project A") turned the Look & Feel of one new melee skill into a spec.

The Prompt (in Full)

Convert this skill's Look & Feel from adjectives into ms and frame values.
Five items: hit timing, hitstop, camera shake, effect synchronization, recovery.
Mark anything you're not sure of as "needs verification in this game."

Skill: greatsword overhead slash (heavy_overhead_slash)
Intent: "a heavy downward smash that staggers the enemy"
Frame rate: 60fps

(Translation: "Convert this skill's Look & Feel from adjectives into ms and frame values. Five items: hit timing, hitstop, camera shake, effect synchronization, recovery. Mark anything you're not sure of as 'needs verification in this game.' Skill: greatsword overhead slash (heavy_overhead_slash). Intent: 'a heavy downward smash that staggers the enemy.' Frame rate: 60fps.")

Claude's Raw Output (Not Summarized or Tidied)

The "weight" of the greatsword overhead slash is built mainly from the length of the hitstop and the recovery, plus the decay of the camera shake. Item by item:

1) Hit timing. The heavier the weapon, the longer the startup from input to activation needs to be for the weight to land. From input to the first visual response (the character beginning to raise the sword), 50–80ms (3–5 frames) is recommended. Note that the first visual response and the first hit response are different things. Time to impact depends on the motion length, so it can't be pinned down here — needs verification against this game's motion lengths.

2) Hitstop. The key variable for a weighty single blow. If light attacks sit at 1–2 frames, the greatsword overhead slash should be 4–6 frames (roughly 67–100ms). Past 6 frames, "weighty" tips over into "stuttery" and responsiveness suffers.

3) Camera shake. Amplitude around 1–2% of screen height, duration 0.2–0.3 seconds, and for decay, ease-out (fades quickly) rather than linear. For a heavy blow, a curve with a strong first oscillation that dies down fast feels natural.

4) Effect synchronization. VFX (hit effect), SFX (hit sound), and hitstop must all trigger on the exact same frame as the hit. Even a 1–2 frame mismatch reads as "flat." UI feedback (damage numbers) can lag 1–2 frames without harm.

5) Recovery. Weight comes at the price of long recovery. From the hit landing until the character returns to a vulnerable, actionable state, 20–30 frames (333–500ms) recommended. But this value varies widely with the game's overall combat tempo (fast action vs. deliberate soulslike) — needs verification against this game's baseline tempo.

In sum: "weight = long startup + 4–6 frames of hitstop + ease-out shake + same-frame VFX/SFX/stop + long recovery." These numbers are general recommended ranges, though — the actual sense of weight can only be finalized by testing it hands-on in the build.

Human Verification, Rejection, and Re-Request

The designer does not adopt this output wholesale. They stop at two points.

Rejection 1 — camera shake amplitude "1–2% of screen height." This game is mobile-first. On a small screen, 1–2% is barely visible, and there's the mobile motion-sickness issue on top of that. The designer rejects this recommendation and applies a house rule instead: "on mobile, express weight through emphasized hitstop, not shake." The LLM gave a general answer; it doesn't know this game's platform constraints.

Hold 2 — hitstop "4–6 frames." This is a hold, not a rejection. The range is right, but the exact value gets decided by feel in the build. The spec reads: "put 4 frames into the build as the default, create 5- and 6-frame variants, and compare all three by hand."

The re-request goes out like this.

This is a mobile-first project. Minimize camera shake and rewrite the spec
to express weight through hitstop, recovery, and SFX.
Lay out three hitstop variants — 4/5/6 frames — in a table for build comparison.

(Translation: "This is a mobile-first project. Minimize camera shake and rewrite the spec to express weight through hitstop, recovery, and SFX. Lay out three hitstop variants — 4/5/6 frames — in a table for build comparison.")

In this second output, the LLM produces a spec table that reflects the mobile constraints. That table goes into the build, and at the next build meeting the designer says, instead of an adjective, "the 4-frame variant is too light — adopt 5 frames." A 40-minute meeting becomes a 5-minute decision.

What This Transcript Shows

Three things. First, the LLM is good at producing a first draft that pulls adjectives down into numeric ranges — this is what breaks the silence in the meeting room. Second, the LLM does not know this game's constraints (mobile, tempo, motion lengths) — it can only give general recommendations, so rejecting and adjusting them is the human's job. Third, the LLM itself pinned down, twice, that "this can only be finalized by hands-on testing in the build" — even the tool knows that the final call on weight belongs to human hands at L4.

4.1.4 Four Places Where AI Recoups Its Adoption Cost

The transcript above showed only one place (spec writing). Across combat design as a whole, AI creates value in four places.

1) Simulation — the biggest value. Pre-compute DPS (damage per second) curves, combo routes, and resource consumption without a build. It is overwhelmingly faster than making a build and measuring by hand. We work through this directly with the simulate_dps simulator in 4.4.

2) Auto-generating state machines and BTs. Convert a natural-language description like "this boss enrages below 50% HP, and while enraged uses a 3-hit chain pattern" into a BT/FSM diagram. Accuracy is high — rule structures are territory LLMs handle well. It saves the time of moving the logic in your head onto a diagram.

3) Automated analysis of build captures. Automatically extract hit timing, combo success rates, and damage distribution from play footage. But this is the hardest of the four to implement (we weigh it honestly below).

4) Proposing balance adjustment candidates. Analyze each row of the data sheet, detect outliers and rough spots in the curves, and propose adjustment candidates. The human only chooses.

Of these four, automated capture analysis (3) has the widest gap between "can be done" and "can be done easily." Books often write "AI extracts everything from the footage automatically," but in practice it isn't that simple. Pixel-based computer vision on footage, off-the-shelf vision APIs, in-game telemetry logs — the accuracy and implementation-cost comparison of the three capture methods is covered authoritatively in 4.4; refer there. Here I'll state only the conclusion.

The most realistic path is in-game telemetry logs. Have the engine emit events directly, like "frame 1204: skill_overhead lands, damage 340, combo count 3." This is source data, so it's accurate, and it takes a single insertion of logging code. The LLM is used to read those logs and summarize them into natural-language reports ("resource efficiency holds up through 3-hit combos, then drops sharply from the 4th"). Footage remains a secondary aid — humans eyeball only the suspicious cases.

In other words, the realistic form of the "AI auto-analyzes the footage" vision is telemetry logs + LLM summarization, not pixel vision. That honest distinction is the starting point for the tool choices in 4.4.

And one thing that does not change across all four places: AI cannot make the final call that "the hits feel good." That belongs to the realm of player emotion, and the responsibility for that emotion stays with humans. AI only produces the supporting evidence for that emotional judgment, fast. Simulation numbers, BT diagrams, telemetry reports — all of it is material for a human to make the call by feel.

4.1.5 The Real Reason for Splitting the Coordinates — The Precondition for Automation

So far the reason given was the surface one: "split the deliverables across Layers and collaboration speaks a common language." I explained that combo rules go in L1 and damage sheets in L3 because their change frequencies differ. True, but not the whole story.

The essential reason for splitting the coordinates is that automation only works on top of them. The general thesis — Layer decomposition as the precondition for procedural generation and automation — was covered in 2.3, so here I narrow it to how that precondition plays out in three kinds of combat automation.

First, simulation only runs when "what is input and what can be changed" are kept separate. If the deterministic core (physics, hitboxes — the L1 skeleton) is mixed in with the changeable spec (damage values, cooldowns — the L3 sheets), the simulator cannot define its "space of change candidates." Core fixed, sheets variable — only with that separation can simulate_dps run a sweep like "raise the damage coefficient from 280 to 340 in steps of 20 and plot the DPS curve."

Second, automated capture analysis is only meaningful when action atoms are labeled. Only when the spec side has an atom labeled "this frame range is the hit phase of skill_overhead" can the signals extracted from telemetry logs be automatically cross-checked against the spec. Without labels, the log is a string of meaningless dots: "something landed at frame 1204."

Third, LLM combo-sequence generation only works when cancel rules and the input buffer are separated out into external documents. A bounded request like "within this character's 7 cancelable pairs and a 200ms input buffer, propose 10 five-hit combo sequences" is possible only when the cancel rules aren't frozen inside code but exist as standalone documents.

All three say the same single sentence. Mix the deterministic core with the spec and automation is blocked; separate them and automation opens up. The surface purpose of Layer decomposition is a common collaboration language; the essential purpose is to lay the preconditions for automated simulation, capture analysis, and LLM sequence exploration.

From Conservative to Progressive Application

Once this foundation is laid, combat operations evolve in two stages.

Conservative application — humans design, automation verifies. This is where most action and MMORPG combat operations are today. Humans write the combo/cancel specs directly; automation simulates DPS and resources, captures via telemetry, and produces "spec vs. measurement" comparison reports. Humans interpret the gaps, decide on spec revisions, and the cycle returns to spec writing. Design is human; simulation, capture, and comparison are automated.

Progressive application — AI proposes candidates, humans only adopt. The next stage. AI automatically enumerates 10–30 sequences within the cancel pairs and the input buffer; automation simulates each sequence's DPS and resources in parallel; the LLM attaches rankings and interpretation ("1st in resource efficiency, medium input difficulty"). What remains in human hands is one decision — "which of these sequences do we adopt as the signature?" — plus the director's calls on build integration and motion capture. Creating a sequence from zero and choosing among 30 are different orders of workload.

For progressive application to take root, three things must be in place: (1) deterministic simulation infrastructure that computes DPS, resources, and survival time in under a second without a build; (2) action atoms whose combo, cancel, and input-buffer rules are separated out into labeled external documents; (3) telemetry-based automated capture analysis. All three are direct products of the Layer decomposition described above.

Motion Capture Is an Irreversible Step — The Decision Gate

Finally, reversibility. The combat designer's review cycle mixes steps that can be undone with steps that can't, and knowing where that boundary lies matters.

Motion capture is the thickest irreversible step in combat. Capture studio scheduling, actor booking, reshoot costs — all of it is expensive. So motion capture for signature actions proceeds only after simulation and automated capture analysis have run long enough to lock the sequence. Conservative or progressive, the decision gate sits just before motion capture and the live build. Every one of the combat designer's reviews must finish in the reversible steps to the left of that gate to be safe.

4.1.6 The Scene at the Studio — What Shrank

These are the changes Project A's combat TF measured over six months of running the coordinates and tools above. The figures below are rough averages pulled from the TF's operating records; the accurate way to read them is as the direction of perceived change, not as precise measurements.

The direction matters more than the numbers themselves. All four items moved from "subjective debate, manual measurement, build iteration" to "measurements, simulation, automated diagrams." Adjectives went down in the meeting room and numbers went up. That is the one sentence this whole chapter is trying to say — the combat designer's job is to build the bridge from the subjective (game feel, fun) to the objective (numbers, simulation), and AI is the tool that lays that bridge fast. The hand that decides "this feels weighty" at the end of the bridge is still human.

Key Takeaways

• Combat design is the seat where the most Layers spin at once on a single desk, from the L1 spec through the L3 sheets to L4 build measurements.
• The surface purpose of Layer decomposition is a common collaboration language; its essence is the precondition for automation — simulation, capture, and LLM exploration.
• The final call on "the hits feel good" belongs to humans; AI rapidly produces the evidence behind that call.

Try It Yourself — Pulling Adjectives Down into Numbers

setup. All you need is one LLM. Pick one skill you have on hand (new or existing). Write its intent as a single adjective line — "heavy," "nimble," "ponderous," something like that.

prompt. Fill your skill's details into the skeleton below.

You are a combat design assistant. Convert the Look & Feel of the skill
below into a "measurable numeric spec" — in ms, frames, and %, not adjectives.
Mark any item you're not sure of as "needs verification in this game."

Skill: [name]
Intent: "[one adjective line]"
Frame rate: [60fps, etc.]
Items: 1) hit timing 2) hitstop 3) camera shake 4) effect synchronization 5) recovery

(Translation: "You are a combat design assistant. Convert this skill's Look & Feel into a 'measurable numeric spec' — in ms, frames, and %, not adjectives. Mark any item you're not sure of as 'needs verification in this game.' Skill: [name] / Intent: '[one adjective line]' / Frame rate: [60fps, etc.] / Items: 1) hit timing 2) hitstop 3) camera shake 4) effect synchronization 5) recovery.")

verify. Ask two questions of every number in the output. (1) Does this value hold under this game's constraints (platform, tempo, motion lengths)? → If not, state the constraints and re-request. (2) Does this value need to be finalized hands-on in the build? → If so, write 2–3 variants into the spec instead of a single value and compare them in the build. Never adopt as-is any item the LLM itself flagged as "needs verification."

4.1.7 Solo Scale-Down

If you're building a game alone, you don't need all five deliverables and all five Layers. Do just two things at minimum. One, a one-page Look & Feel spec — for your 3–5 core actions, write down only hitstop, recovery, and synchronization as numbers. A memo written in adjectives will be unreadable even to you six months later. Two, pull combos and cancels out of the code into a single file — once the cancel pairs live as data, you can later ask an LLM to "propose 5 combos from these pairs." These two are the minimum coordinates that keep the door to automation open even in solo development.

4.2 Combat Look & Feel — Pinning Game Feel Down in Data

Five people are gathered in front of the meeting room monitor. The same build, the same skill, the same 30-second clip is playing on screen for the third time. The client programmer speaks first. "Looks fine to me." The artist crosses their arms. "It's weak. Something's missing." The designer next to them cuts in. "The effects are good, but it doesn't stick to your hands." The director watches for a long while and makes the call. "Hmm... let's go just a bit heavier."

And the meeting ends. Nobody wrote down how many milliseconds or how many frames "just a bit heavier" actually is. In the next build, the programmer implements their own understanding of "heavier," and the artist layers on their own. And the following week, in the same meeting room, watching the same clip, the same conversation repeats.

Hit feel, game feel, Look & Feel. These are the most frequently used and least defined words in combat design. Everyone believes they know what they mean, but everyone's mental definition differs, so the discussion ends with nothing to show for it. This chapter is about decomposing that "feel" into measurable numbers — about pulling game feel down from abstraction into data.

4.2.1 Combat = Look & Feel, Systems = Behavior

Let me draw a boundary first. Combat design splits into two broad branches.

• Combat systems: how it behaves. Damage formulas, cooldowns, stack accumulation, status effect rules. That is the territory of the next chapters (4.3 combos and cancels, 4.4 AI simulation).
• Combat Look & Feel: how it feels. When the screen responds after you press the button, how long the screen freezes at the moment of impact, whether the effects, the sound, and the rumble fire at the same instant.

This chapter covers only the latter. Whether the damage is 100 or 120 has no direct bearing on game feel. What matters is how the player perceives the moment that 100 damage "lands." Even with an identical damage formula, different hit timing and hitstop make it feel like a completely different game.

Let me be honest about one thing up front. Hit feel is not completed by three numbers alone. The acceleration and deceleration curves of the attack motion (animation), the reaction on the receiving end (hit reaction, hitstun), and the squash-and-stretch deformation that Japanese action games of the '80s and '90s loved — exaggerating the character at the moment of impact with stretching, squashing, afterimages, and smears — all have to come together before "I got hit" registers as a single, unified sensation. What this chapter focuses on pulling down into measurable numbers is three of those axes. Motion, reaction, and deformation are areas where animators and artists have the bigger hand, so they belong to later chapters and the art part; here the weight is on the three axes a game designer can pin down in a spec and verify in a build. Those three axes break down like this.

When someone in the meeting room says "it's weak," that weakness comes from one of the three. Is the response late (timing)? Is there no sense of impact (hitstop)? Are things firing out of step (synchronization)? Decompose the question into the three axes, and "it's weak" finally becomes a sentence you can fix.

That said, the cause of "weak" does not always live in these three axes. Here is the full list of what makes up Look & Feel, with a line drawn around what this chapter takes responsibility for.

The top four bundle into this chapter's three axes and become the targets of measurement and specification. The middle three (motion, reaction, deformation) must not be missing, but they are art/animation territory that a designer alone cannot close out with numbers, so I only make clear that they exist. If the motion is stiff or the target just stands there unfazed, hit feel will not land even with all three axes dialed in.

4.2.2 Hit Timing — From Input to Response

There is a reason timing comes first among the three axes. When players doubt the game feel, the first thing that snags is the sense that "the response is late," and no matter how flashy everything else is, sluggish input brings it all down in that instant. So timing gets fixed first.

The first axis of game feel is time. From the instant the button is pressed (0ms) to the instant the screen first responds — how many ms does it take? Humans are astonishingly sensitive to this latency. The difference between 60ms and 120ms is something "you can't explain in words, but your hands know."

A single attack is not one simple point; it is multiple events laid out across time. Put one basic attack on a timeline and it looks like this.

The most important number in this diagram is the 100ms at which the hitbox first turns on. It means hit detection for the attack begins 100ms after the button press. This value determines the perceived speed of the game feel.

Recommended ranges vary by genre and character, but rough baselines exist.

These ranges are not absolute standards. As an author's estimate (unverified): casual mobile tends to drift about ±50ms toward input leniency, while console fighting games tend to tighten further. What matters more than the numbers themselves is that the team shares a baseline — "we agreed our light attacks are 90ms." Only with a baseline can you look at a build and call it "right" or "wrong."

But there is a trap here. The human eye cannot tell 90ms from 110ms. At 60fps one frame is about 16.67ms, and this 20ms difference is barely more than a single frame. Whether "feels a bit slow?" in the meeting room is right or wrong can never be settled by eye. That is why measurement is needed.

4.2.3 Extracting Timing from the Build — An Honest Comparison

The spec says "hitbox 100ms." How do you confirm the build actually turns it on at 100ms? Automation splits three ways (video analysis, off-the-shelf vision tools, in-game telemetry); the precision and difficulty comparison of the three is treated canonically in 4.4. Here I will state only the conclusion. The first thing to lay down in practice is in-game telemetry. The reason is simple. Rather than inferring from video which frame the VFX "appeared" on screen, having the code print a single [HITLOG] line on the frame it fires the OnHit event is incomparably more accurate and cheaper. Save video analysis for external footage with no input overlay (e.g., analyzing a competitor's game); for our own build, telemetry goes in first.

A telemetry log looks like this.

[HITLOG] frame=6  t_ms=100  evt=hitbox_on    skill=1001 char=warrior
[HITLOG] frame=6  t_ms=100  evt=vfx_trigger  skill=1001
[HITLOG] frame=6  t_ms=100  evt=sfx_trigger  skill=1001
[HITLOG] frame=7  t_ms=117  evt=damage_apply skill=1001 dmg=124
[HITLOG] frame=7  t_ms=117  evt=ui_dmgnum    skill=1001
[HITLOG] frame=6  t_ms=100  evt=cam_shake    skill=1001 amp=0.4

The designer's job is to check this log against the spec, line by line. It is mostly unit conversion and mechanical matching — a human repeating it by eye gets tired and makes mistakes, but an LLM does not tire. In the next section, I put it to work.

4.2.4 Worked Transcript — Checking the Telemetry Log Against the Spec

I pasted in both the spec yaml and the build's telemetry log, and told the AI to compare the two and find where they diverge. Below is the full prompt, Claude's raw output, and the entire human verification process. Nothing is summarized; it is reproduced as is.

First Prompt

Below are the 'hit timing spec' for one combat skill and the telemetry
log pulled from the actual build. Organize the items where the build diverges from the spec into a table.

[Spec]
character: warrior
skill_id: 1001
fps: 60
events:
  hitbox_on:    {expect_ms: 100, tol_frame: 0}
  vfx_trigger:  {expect_ms: 100, tol_frame: 0}
  sfx_trigger:  {expect_ms: 100, tol_frame: 1}
  damage_apply: {expect_ms: 110, tol_frame: 1}
  ui_dmgnum:    {expect_ms: 100, tol_frame: 2}
  cam_shake:    {expect_ms: 100, tol_frame: 1}

[telemetry log]
[HITLOG] frame=6  t_ms=100  evt=hitbox_on    skill=1001
[HITLOG] frame=6  t_ms=100  evt=vfx_trigger  skill=1001
[HITLOG] frame=8  t_ms=133  evt=sfx_trigger  skill=1001
[HITLOG] frame=7  t_ms=117  evt=damage_apply skill=1001
[HITLOG] frame=9  t_ms=150  evt=ui_dmgnum    skill=1001
[HITLOG] frame=6  t_ms=100  evt=cam_shake    skill=1001

60fps (1 frame = 16.67ms). Convert expect_ms to frames, compare against
the log's frame values, and mark anything whose difference exceeds tol_frame as FAIL.

Claude's Raw Output (Verbatim)

First, I will convert the spec's expect_ms values to frames. At 60fps, frame = round(ms / 16.67).

• hitbox_on: 100 / 16.67 ≈ 6.0 → frame 6
• vfx_trigger: 100 → frame 6
• sfx_trigger: 100 → frame 6
• damage_apply: 110 / 16.67 ≈ 6.6 → frame 7 (rounded)
• ui_dmgnum: 100 → frame 6
• cam_shake: 100 → frame 6

Here is the comparison against the actual frames in the log.

Event	Expected frame	Actual frame	Diff (frames)	Tolerance	Verdict
hitbox_on	6	6	0	0	PASS
vfx_trigger	6	6	0	0	PASS
sfx_trigger	6	8	+2	1	FAIL
damage_apply	7	7	0	1	PASS
ui_dmgnum	6	9	+3	2	FAIL
cam_shake	6	6	0	1	PASS

Two items exceeded their tolerance. - sfx_trigger: the sound is 2 frames (about 33ms) behind the visual hit. Exceeds the 1-frame tolerance. Players are likely to feel that "the sound is slightly out of sync." - ui_dmgnum: the damage number appears 3 frames (about 50ms) late. Exceeds the 2-frame tolerance. This can come across as "I landed the hit, but the number shows up late."

damage_apply at frame 7 matches the spec's frame 7 (converted from 110ms), so it is normal. However, the fact that damage_apply is 1 frame after hitbox_on (frame 6) may need confirmation as to whether this is intended design.

Human Verification — I Rejected One Cell

I did not take the output on faith. There were two verification points.

Verification 1 (rounding boundary — passed). The 110ms conversion for damage_apply looked suspicious. 110 / 16.67 = 6.598…. Rounded, 7 is correct. But what if the spec's intent had been "frame 6 — the same frame as 100ms"? I checked directly: the spec deliberately set damage_apply: expect_ms 110, a 10ms offset from vfx (100). So the frame 7 conversion was accurate. The AI passed.

Verification 2 (the last sentence — rejected). The AI's closing remark — "the fact that damage_apply is 1 frame after hitbox_on may need confirmation as to whether this is intended design" — was noise. The spec already states the intent with expect_ms 110, and the AI turned that into a "needs confirmation" question. Given the spec, the answer should be closed within the spec; instead it manufactured an unnecessary question. I did not adopt that sentence.

I re-requested, including the reason for the rejection.

Second Prompt (Re-request)

damage_apply has its intent pinned in the spec as 110, so drop the 'needs confirmation' comment.
// meaning: do not ask back about items whose answer is closed within the spec
Keep only the two FAILs (sfx, ui_dmgnum), and instead of asserting causes,
give me a checklist of 'code/resource locations to check'.

Claude's Second Output (Verbatim)

Here is the verification checklist for the two FAIL items. No causes are asserted; only the places to check are listed.

sfx_trigger (+2 frames late) - [ ] Is the sound trigger bound to the same event as hitbox_on, or is it hooked to a separate animation notify? - [ ] Does the audio asset itself have leading silence — an empty stretch at the head of the file can present as latency - [ ] Was the playback call issued on the same frame but pushed back by output latency (platform audio buffer)?

ui_dmgnum (+3 frames late) - [ ] Is the damage number UI structured to update on a separate tick after damage_apply (frame 7)? - [ ] Is UI updating batched at the end of the next frame (deferred render queue)? - [ ] Is there an extra delay value on the start frame of the number pop-up animation?

What can be asserted: both items exceed the spec's tolerance and are later than the visual hit (frame 6). What cannot be asserted: which of the causes above is responsible — unknowable until code/assets are checked.

This second output I adopted as is. Not inventing causes, and converting them into "places to check," was exactly the form I wanted. I handed the checklist directly to the sound owner and the UI owner. For sound, 33ms of leading silence in the audio asset was the culprit (checklist item 2). For UI, it was the next-frame update structure (item 1).

This is where the division of labor becomes clear. The AI mechanically compares spec against log and catches the FAILs; the human (a) rejects the unnecessary counter-questions the AI generates and (b) confirms the real cause of each FAIL in the code. Ask the AI to assert causes and it will produce plausible lies, so it is safer to stop it at "places to check."

4.2.5 Hitstop — The Weight of a Hit

The second axis is the stop. The effect of freezing — or briefly slowing — game time at the very instant a hit lands. This determines the intensity of the "I connected" sensation. It is the most powerful game-feel tool in fighting games and action RPGs. Too long and it feels sluggish; too short and there is no weight.

Recommended ranges (at 60fps) are below. These figures are rough conventions in action games; absolute values are tuned per game.

Each character and skill must get different values. Give everything the same number and the weight differences vanish — every attack eventually converges on the same tone. This is the point that leads into one of 4.2's three Key Takeaways.

"Who stops" is also a design choice.

The spec is entered like this.

character: warrior
skill_id: 1001
hit_stop:
  attacker: 2          # frames
  victim: 4
  critical_multiplier: 1.5   # 1.5x on critical (rounded)

Hitstop is the axis where game-feel verification is hardest — spec numbers alone cannot settle "right or wrong." Telemetry can catch whether it actually stopped for 4 frames, but whether 4 frames is appropriate has to be judged by a human, hands on the build. The AI guarantees conformance to the spec; the human judges whether the spec value itself is right.

4.2.6 Effect Synchronization — Does Everything Fire on the Same Frame?

The third axis is simultaneity. When VFX (visual effects), SFX (sound), UI (damage numbers), camera (shake), and rumble (controller) all start on the same frame, the player's brain binds them into "one event." Even a 1\~2 frame misalignment reads as "something's off"; at 3\~5 frames it reads as "looks like a bug." The sfx 2 frames late and the ui 3 frames late that FAILed in the earlier worked transcript were exactly this axis's problem.

The five synchronization targets and their tolerances:

The key point is that all five belong in the spec. The common mistake is to spec only the VFX and leave the other four to "they'll line up somehow." If it is not in the spec, build verification has no baseline — even if telemetry captures it, there is nothing to compare against. Only when all five are in the spec does the automated comparison close.

For the automated comparison, the worked transcript from the previous section applies as is. If the telemetry log records the trigger frames for all five, the AI checks them against the spec and reports only the items beyond tolerance. No human has to eyeball 100 skills on every build. What remains separate, though: the AI catches deviations from the spec, while the human catches the territory where "the spec all passes, but it still doesn't feel right."

4.2.7 From Spec to the Next Build — The Full Loop

Now to connect the pieces into a single flow. Once this loop starts turning, the meeting room's "just a bit heavier" gets translated into "hitstop victim 4→6 frames."

flowchart TD
    A["Write the spec
(designer: yaml)"] --> B["Implement in the build
(programmers & artists)"]
    B --> C["Run the build + telemetry log
[HITLOG] auto output"]
    C --> D["AI auto-comparison
spec yaml vs telemetry"]
    D --> E{"Any FAIL beyond
tolerance?"}
    E -->|yes| F["FAIL items + places-to-check list
(AI, no cause assertions)"]
    F --> G["Owner confirms the real cause
in code/assets (human)"]
    G --> B
    E -->|no| H["Designer: 'feel' review
spec passes, but does it feel right? (human)"]
    H -->|needs tuning| A
    H -->|OK| I["Keep as input for the next milestone retrospective"]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class C code;
    class D,F ai;
    class A,G,H human;
    class I pass;

In this loop, the boxes the AI owns (D, F) and the boxes humans own (A, G, H) divide cleanly. The AI is strong at mechanical comparison and checklist generation; humans are strong at setting baselines, confirming causes, and making the final call on feel. Automation does not remove the human — it releases them from the half-day of "counting frames by eye" they used to spend each cycle, so they can focus on the feel alone.

The last box in the loop (I) matters. This measurement data is not used once and thrown away; it feeds back in as input for the next milestone retrospective. When a pattern like "last quarter's game-feel FAILs clustered in sfx synchronization" survives as data, next quarter you fix the audio pipeline first.

4.2.8 Where Measurement Cut the Debate Short — Operational Observations

These are the changes I observed over roughly six months of running the loop above on a mobile MMORPG project where I served as director (hereafter "Project A"). The figures below are not precision instrumentation; they are the author's operational observations (estimates included), based on meeting-minute timestamps and build verification records. Read them for direction and ratio. Do not cite the absolute values as a benchmark.

The essence is the qualitative change, not the numbers. When "it's weak" came up in the meeting room, the immediate follow-up became "which axis? Timing? Hitstop? Sync?" — and when no answer came, we pulled up the telemetry together. That a measurable, objective standard gave the debate a destination is the biggest change of those six months. "Just a bit heavier" walked out of the meeting room undefined far less often.

4.2.9 Common Mistakes and How to Avoid Them

Try It Yourself

This is the procedure for laying down a minimal version of this loop in your own project.

setup 1. Pick one skill to verify (a basic attack is recommended). 2. Plant one log line at each of the six trigger points in code (hitbox_on, vfx, sfx, damage_apply, ui_dmgnum, cam_shake): [HITLOG] frame=X t_ms=Y evt=... skill=.... 3. Write the spec yaml (an events block with expect_ms + tol_frame). Use this chapter's first prompt example as a template.

prompt 4. Run the build once and collect the telemetry log. 5. Paste the spec yaml and the telemetry log together into the AI and instruct it: "Compare the build against the spec using 60fps frame conversion and give me only the FAILs as a table. Do not assert causes — give a 'places to check' checklist." (the form of this chapter's second prompt)

verify 6. Recompute one cell of the AI's frame conversion yourself (ms / 16.67, rounded). If even one cell is wrong, distrust the whole thing. 7. If the AI asks back about items closed within the spec, or asserts causes, reject and re-request. 8. Hand the FAIL checklist to the owners and confirm the real causes in code and assets.

Solo Scale-Down

If you are a solo developer with no team and no telemetry infrastructure, scale it down like this. Screen-record the build at 60fps, with a key input overlay turned on so the moment of input is visible. Record one use of the skill you want to verify, then count frames yourself in a video editor: the frame the button was pressed, and the frame the screen first changed. Give the two frame numbers and the spec's expected value to the AI and say "convert to ms at 60fps and compare against the spec" — and even without telemetry, the one core axis (hit timing) gets verified. Full five-way synchronization is out of reach, but pinning down even the single input→response axis moves half of the game-feel debate onto objective ground.

The next chapter moves from a single hit to a sequence of hits. Combos, cancels, input queues — the rules that make one hit flow naturally into the next.

Key Takeaways

• Game feel is the sum of three axes — hit timing, hitstop, and effect synchronization; fix only one and the others stay shaky.
• An in-game telemetry log is more accurate and cheaper than video analysis — for our own build, telemetry goes in first.
• The AI catches FAILs by checking against the spec; the human rejects the counter-questions and confirms causes in code.

Next Chapter Preview

• 4.3. Combos, Cancels, and the Input Queue

4.3 Combos, Cancels, and Input Queues — Enumerate the Paths and Verify Them

Combat designer B was standing at the meeting-room whiteboard, drawing boxes with a marker. Basic 1, Basic 2, Basic 3, and a heavy-attack branch peeling off to the side. Around the seventh arrow, someone asked: "So after the heavy attack into the launcher, if you cancel into dodge, can you get back to Basic 1?" B stopped the marker. The graph on the whiteboard didn't show that path. Whether it could be drawn and simply hadn't been, or whether the rules made it impossible — B couldn't answer on the spot either.

This is the real problem of combo design. In your head, a combo looks like a simple trunk: 1-2-3, then branch into the heavy attack. But once cancels and an input queue enter the picture, the trunk becomes a graph. Add just a few cancel edges to six nodes and the paths you can actually walk multiply into dozens. A human cannot unfold all those dozens of branches mentally. So the balance incident — "this path is too strong" — gets discovered only after it has gone into a build.

This chapter has one goal: a workflow that enumerates every combo path automatically, without drawing them by hand, and verifies each one. Turn rules written in natural language into a spec, enumerate the paths from the spec, and run the enumerated paths through simulation. Along the way I'll show, raw and unedited, how far the AI takes you and where it lies.

4.3.1 A Combo Is a Graph, Not a Table

Write a combo as a table and it reads like this: "Basic 2 follows Basic 1, Basic 3 follows Basic 2." Neat rows and columns. But this table lies, because a table assumes a straight line. In actual combat, the player branches from Basic 2 into the heavy attack, cancels the heavy attack into a dodge, and presses Basic 1 again right after the dodge. Those branches and cycles hide between the rows of the table.

So the true shape of a combo is a directed graph. Actions are nodes; connections are edges. Each edge carries an input window (when input is accepted) and an input key. Nodes carry a duration in frames, and some nodes carry a bonus condition (a damage multiplier that applies only if specific nodes were visited along the way).

Here is one basic combo set for a warrior character drawn as a graph — six nodes, cancel branches included.

Two things make this decisively different from the whiteboard. First, every edge carries an explicit input-window frame range. The branch label "Heavy 6\~24f" means the heavy-attack input is accepted from frame 6 through frame 24 after Basic 2 starts. Second, there is the dashed dodge-to-Basic-1 re-entry edge — the very path B couldn't answer about in the meeting room. Make it explicit in the graph, and "exists / doesn't exist" becomes unambiguous.

Drawn by hand, this graph is six nodes and seven or eight edges. With twenty characters and three or four combo sets per character, you are looking at hundreds of graphs. Hands cannot keep up. So you write the graph down as a text spec, and generate both the picture and the verification from it automatically.

4.3.2 Humans Read the Spec, Machines Parse It

Let's move the graph above into a YAML spec. The core is three blocks: nodes (nodes), edges (edges), and bonuses (bonuses). Cancel rules are treated as just another kind of edge — interrupting an action to go to a different node is, in the end, an edge.

# warrior_basic_chain.yaml
character: warrior
combo_id: basic_chain

nodes:
  - { id: basic_1,  name: 기본1,   duration_frames: 21 }
  - { id: basic_2,  name: 기본2,   duration_frames: 24 }
  - { id: basic_3,  name: 기본3,   duration_frames: 30 }
  - { id: heavy,    name: 강공격,  duration_frames: 33 }
  - { id: launch,   name: 띄우기,  duration_frames: 28 }
  - { id: dodge,    name: 회피,    duration_frames: 18, cancels_recovery: true }

edges:
  - { from: basic_1, to: basic_2, input: light, window: [10, 21] }
  - { from: basic_2, to: basic_3, input: light, window: [12, 24] }
  - { from: basic_2, to: heavy,   input: heavy, window: [6, 24] }
  - { from: heavy,   to: launch,  input: heavy, window: [10, 33] }
  - { from: heavy,   to: dodge,   input: dodge, window: [0, 33], type: cancel }
  - { from: basic_3, to: dodge,   input: dodge, window: [0, 30], type: cancel }
  - { from: dodge,   to: basic_1, input: light, window: [8, 18] }   # re-entry

bonuses:
  - { on: basic_3, requires_path: [basic_1, basic_2], damage_multiplier: 1.5 }

(The name fields keep the original Korean display names — 기본1 is Basic 1, 강공격 the heavy attack, 띄우기 the launcher, 회피 the dodge.)

This spec serves two readers at once. A human reads window: [6, 24] and understands "the heavy attack starts being accepted midway through Basic 2"; a machine parses the same line and uses it for the graph drawing and the path enumeration. One source yields both human understanding and machine verification.

The frame values above (21, 24, [6, 24]) are not measurements — they are example values I constructed for this chapter's explanation (unverified). In a real project, these values come from the lengths of the montages your animators build and the notify timings in the build. When you first write the spec, you enter the designer's intended values; once a build exists, you capture it and correct the spec with measured values — that correction loop is covered in 4.4.

4.3.3 Worked Transcript — From Natural Language to Spec

I give the rules B drew on the whiteboard to the AI in natural language and have it convert them into the spec YAML. No summarizing — the full prompt, Claude's raw output, and the human verification/rejection are reproduced exactly as they happened.

The Prompt (Full Text)

다음은 전사 캐릭터의 콤보 룰이다. 이걸 콤보 명세 YAML로 변환해라.

규칙:
- 기본 공격은 1, 2, 3타로 이어진다. 가벼운 공격 키.
- 기본2 도중에 강공격 키를 누르면 강공격으로 빠질 수 있다.
- 강공격 다음에 강공격을 한 번 더 누르면 적을 띄운다(띄우기).
- 강공격은 언제든 회피로 캔슬 가능.
- 기본3도 회피로 캔슬 가능.
- 회피 직후에는 가벼운 공격으로 기본1을 다시 시작할 수 있다.
- 기본3은 기본1과 기본2를 모두 거쳤을 때만 데미지가 1.5배.

명세 형식:
- nodes(id, name, duration_frames), edges(from, to, input, window, type),
  bonuses(on, requires_path, damage_multiplier)
- 캔슬 엣지는 type: cancel로 표시.
- 프레임 값은 내가 안 준 건 너가 정하지 말고 TODO로 비워 둬라.

(The prompt, kept in the original Korean above, says: "These are the combo rules for a warrior character. Convert them into a combo spec YAML." It then lists the rules — the 1-2-3 light-attack chain; a heavy-attack branch available during Basic 2; heavy followed by heavy launches the enemy (launcher); the heavy attack can always be canceled into dodge; Basic 3 can also be canceled into dodge; right after a dodge, a light attack restarts Basic 1; Basic 3 deals 1.5× damage only if both Basic 1 and Basic 2 were passed through — defines the spec format with cancel edges marked type: cancel, and ends with one constraint: for any frame value I didn't provide, don't decide it yourself; leave it as TODO.)

That last line is the crux. I explicitly told it not to invent frames I hadn't given. It enforces rule 3 of the v3 standards (numeric honesty) at the prompt level.

Claude's Raw Output (Unedited)

명세로 변환했습니다. 프레임 값은 제공되지 않아 TODO로 남겼습니다.

```yaml
character: warrior
combo_id: basic_chain
nodes:
  - { id: basic_1, name: 기본1, duration_frames: TODO }
  - { id: basic_2, name: 기본2, duration_frames: TODO }
  - { id: basic_3, name: 기본3, duration_frames: TODO }
  - { id: heavy,   name: 강공격, duration_frames: TODO }
  - { id: launch,  name: 띄우기, duration_frames: TODO }
  - { id: dodge,   name: 회피,   duration_frames: TODO }
edges:
  - { from: basic_1, to: basic_2, input: light, window: TODO }
  - { from: basic_2, to: basic_3, input: light, window: TODO }
  - { from: basic_2, to: heavy,   input: heavy, window: TODO }
  - { from: heavy,   to: launch,  input: heavy, window: TODO }
  - { from: heavy,   to: dodge,   input: dodge, window: TODO, type: cancel }
  - { from: basic_3, to: dodge,   input: dodge, window: TODO, type: cancel }
  - { from: dodge,   to: basic_1, input: light, window: TODO }
bonuses:
  - { on: basic_3, requires_path: [basic_1, basic_2], damage_multiplier: 1.5 }
```

확인이 필요한 부분:
1. "회피 직후 기본1 재시작"을 dodge -> basic_1 엣지로 넣었는데, 이게
   회피의 후딜 중에 입력받는 건지 회피가 완전히 끝난 뒤인지 불명확합니다.
2. 띄우기(launch) 다음에 이어지는 공중 콤보가 있는지 규칙에 없습니다.
   띄우기가 콤보의 끝인지 확인이 필요합니다.
3. 회피를 노드로 둘지 엣지(캔슬 동작)로만 둘지 모호합니다. 일단 노드로
   뒀습니다 — 회피 자체가 지속 시간을 갖는 액션이라고 봤습니다.

(In the raw output above, Claude returns the YAML with every frame value left as TODO and closes with three questions: 1 — it modeled "restart Basic 1 right after the dodge" as a dodge -> basic_1 edge, but it's unclear whether input is accepted during the dodge's recovery or only after the dodge fully ends; 2 — the rules say nothing about an aerial combo after the launcher, so is the launcher the end of the combo?; 3 — it's ambiguous whether dodge should be a node or only an edge (a cancel action); it chose node for now, on the grounds that a dodge is itself an action with a duration.)

Let's evaluate. The good: it didn't invent a single frame — everything is TODO. It honored the prompt's constraint. And the three questions at the end are all genuinely ambiguous points — especially question 1 (re-entry input timing), which is exactly the hole B couldn't answer on the spot in the meeting room. The AI found the hole before the humans did.

The debatable: making dodge a node, in question 3, is a judgment call. A dodge is both a "cancel action" and an "action with a duration," so both readings are valid. The AI picking one side and then reporting the ambiguity is honest, but this is a design decision — a human has to make it.

Human Verification/Rejection

I answer the three questions and reject part of the output.

• Question 1 (re-entry timing): Input is accepted during the dodge's recovery (8–18f). It's a recovery cancel into Basic 1, not a re-entry after the dodge plays out to the end. → Adopted, window: [8, 18].
• Question 2 (after the launcher): Within this chapter's scope, the launcher ends the combo. Aerial combos are split off into a separate set. → AI's judgment adopted.
• Question 3 (dodge = node): Keep it as a node, but add the cancels_recovery: true attribute to make explicit that it's an action that cuts recovery. → Partially adopted, attribute added.

And one thing gets rejected. The AI didn't put type: cancel on the dodge → basic_1 edge — and in nature it is a cancel, since it cuts the dodge's recovery to enter. But here I treat it as "normal entry after the dodge" and keep it a regular edge, because for this character the distinction between a recovery cancel and a normal link makes no difference in game feel. A case of a human overriding the AI's classification with a domain judgment.

The Follow-Up Request

좋다. 다음을 반영해 최종 명세를 다시 내라:
- dodge에 cancels_recovery: true 추가.
- dodge -> basic_1 엣지의 window는 [8, 18].
- 나머지 프레임은 여전히 내가 안 줬으니 TODO 유지. 단 위 그래프 예시값
  (basic_1=21, basic_2=24, basic_3=30, heavy=33, launch=28, dodge=18)을
  쓸 거니까 그 값으로 채워라. 이건 미검증 예시값이라고 주석으로 박아라.

(The follow-up, in Korean above, says: good — now produce the final spec with cancels_recovery: true added to dodge; window: [8, 18] on the dodge -> basic_1 edge; the remaining frames are still ones I didn't give, so they stay TODO in principle — but since we'll use the example values from the graph above (basic_1=21, basic_2=24, basic_3=30, heavy=33, launch=28, dodge=18), fill them in with those values and pin a comment marking them as unverified example values.)

The result of this follow-up is the YAML in 4.3.2. It wasn't done in one shot: prompt → raw output → verification/rejection → follow-up. That cycle is what gives the spec its credibility. The AI marks what's ambiguous, and the human decides with domain knowledge — neither alone is enough.

4.3.4 Enumerate the Paths Automatically

Since the spec is a graph, enumerating combo paths becomes a graph traversal problem: a depth-first search (DFS) that finds every path from the start node to an end node (or the finisher). A human can't do this in their head; code does it in an instant.

Inside my team's isolated workspace 95_BattleTF lives a small script responsible for this enumeration. It reads the spec YAML, extracts every path, and verifies that each path is legal under the rules (that every edge exists). The core logic looks like this.

# 95_BattleTF/enumerate_paths.py (excerpt)
import yaml

def load_graph(path):
    spec = yaml.safe_load(open(path, encoding="utf-8"))
    adj = {}
    for e in spec["edges"]:
        adj.setdefault(e["from"], []).append(e)
    return spec, adj

def enumerate_paths(adj, start, max_depth=8):
    results = []
    def dfs(node, path, edges):
        # end node (no outgoing edges) or depth limit: finalize the path
        outs = adj.get(node, [])
        if not outs or len(path) >= max_depth:
            results.append((list(path), list(edges)))
            return
        for e in outs:
            if e["to"] in path:        # cycle guard: each node once per path
                results.append((list(path), list(edges)))
                continue
            dfs(e["to"], path + [e["to"]], edges + [e])
    dfs(start, [start], [])
    return results

Run it starting from basic_1, and out pour the paths you could never fully unfold by hand. A sample:

Paths 3 and 4 are the important ones. Because of the dodge re-entry edge, the combo cycles. These cyclic paths are exactly what people failed to see on the whiteboard. Without the cycle guard in the DFS (each node at most once per path), the enumeration falls into an infinite loop — a trap I actually hit the first time I ran the code and it hung. If the graph has cycles, the enumerator must have a guard.

The enumeration stage produces two artifacts. First, the list of every path that is legal under the rules. Second, rule contradiction detection — if the spec has a dodge → basic_1 edge but the dodge node definition is missing, the enumerator flags it as "an edge pointing to an undefined node." That dangling reference is the single most common mistake when specs are written by hand.

4.3.5 Run the Enumerated Paths Through Simulation

A path list alone doesn't tell you which path is too strong. Each path has to go into a DPS simulator. My team's simulate_dps plays that role — it takes a path (a node sequence), each node's damage and frames, and the bonus rules; computes total damage and total elapsed frames; and produces damage per second (DPS).

# 95_BattleTF/simulate_dps.py (excerpt, assumes 60fps)
def simulate(path_nodes, node_dmg, node_frames, bonuses):
    total_dmg = 0
    total_frames = 0
    visited = []
    for nid in path_nodes:
        dmg = node_dmg.get(nid, 0)
        # bonus: apply the multiplier once every requires_path node was visited
        for b in bonuses:
            if b["on"] == nid and all(r in visited for r in b["requires_path"]):
                dmg *= b["damage_multiplier"]
        total_dmg += dmg
        total_frames += node_frames[nid]
        visited.append(nid)
    seconds = total_frames / 60.0
    return {"dmg": total_dmg, "frames": total_frames,
            "dps": round(total_dmg / seconds, 1) if seconds else 0}

Pipe the entire enumeration output from 4.3.4 through this, and per-path DPS falls out as a table. Below is a run with example node damage values (basic hit 100, heavy attack 180, launcher 140 — all unverified values constructed for illustration).

This table changes the discussion. The intuition "doesn't the heavy branch look stronger than the textbook 3-hit chain?" becomes a number: "heavy path DPS 294 vs. textbook 280 — a 5% edge." If the 5% edge is intended, it passes; if not, you lengthen the heavy attack's frames to bring the DPS down. And you make that call before a build exists, at the spec stage.

The whole workflow on one page:

flowchart LR
    A["Natural-language rules
(teammate_b's whiteboard)"] --> B["Prompt → AI"]
    B --> C{"Raw spec
with TODOs and questions"}
    C -->|human verification/rejection| D["Final spec YAML
warrior_basic_chain.yaml"]
    D --> E["enumerate_paths.py
DFS enumeration of all paths"]
    E --> F["Rule contradiction detection
dangling edges, infinite cycles"]
    E --> G["simulate_dps.py
per-path DPS calculation"]
    G --> H["Balance judgment
DPS gaps between paths"]
    F --> D
    H -->|frame adjustments| D

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    class E,F,G code;
    class B,C ai;
    class H human;
    class A,D data;

The spec (D) sits at the center, and enumeration (E), contradiction detection (F), and simulation (G) all branch off of it. When a contradiction is caught or the balance is off, you go back to the spec and fix it. The whiteboard had no such loop — which is why the whiteboard's combo turned out to be wrong only after it went into a build.

4.3.6 Cancels and Input Queues — Two Levers That Widen and Narrow the Paths

So far we've looked at the combo graph and path enumeration. Cancels and the input queue are the two levers that tune this graph — and they point in opposite directions.

Cancels add edges. Every cancel rule you add puts another edge on the graph, and the number of enumerated paths multiplies. So cancels are not "the more generous, the better." The looser the cancels, the more the paths explode, and the higher the odds that an unintended strong path (like the cyclic path in the previous section) slips in. This is why the fighting-game tradition keeps cancels strict and why action RPGs keep them generous — the genre decides how many paths to allow. There is no absolute correct window value.

When you handle cancels, always separate them explicitly. Leave them as one blanket "cancel into anything" rule, and the enumerator generates cancel edges between every pair of nodes — the paths grow out of control.

The input queue doesn't narrow the paths — it makes them actually walkable. (This is the system fighting games call input buffering.) Without the queue, the player would have to hit each edge's input window (say, [12, 24]) with frame-level precision. Human reaction times make that nearly impossible. The queue stores an input pressed before the window into a buffer, then fires it automatically the moment the window opens. In other words, the queue doesn't change the graph's paths; it puts shoes on the player so a human can walk the graph.

input_queue:
  window_start_ratio: 0.5   # buffer the next input from 50% of action progress
  expire_frames: 10         # how long a buffered input stays valid
  priority: latest          # on simultaneous inputs, the last one wins

The balance of the three parameters is the crux. If window_start_ratio is too small, inputs from early in the action get buffered too, and unintended follow-up actions pop out. If expire_frames is too short, the queue becomes meaningless and you're back to demanding precision; too long, and an input pressed ages ago fires late — the "why did my character suddenly move?" incident. A recommended starting point is expire_frames 5–15 and window_start_ratio around 0.5 — but that is a starting line to adjust for genre and character weight, not a correct answer.

One operational note: do not give every character its own input-queue parameters. Keep one global default and override only the characters whose weight is genuinely different (giant boss types and the like). Manage twenty characters' queue values separately and you can no longer tell which differences are intended and which are mistakes.

One more thing to pin down. So far we've treated edges as "exists / doesn't exist" — but even when an edge exists, how the action actually transitions from that node to the next is a separate decision. There are three core options for linking combo actions. They are beyond this book's depth, so I won't cover them in code, but leaving them unmentioned would make the spec only half the picture.

• Cancel notify: From what point do you cut the current animation and accept the next input? The edge windows above (window: [10, 21]) are exactly the expression of this notify. Move the notify earlier and the combo speeds up (you move on before the hit finishes playing); push it later and each hit lands heavier. The window's start value, in other words, is not just a number — it's a feel decision: do we show this hit through to the end, or hand off to the next one quickly?
• Anim blending: Blend smoothly between the two nodes — interpolate over a few frames from the heavy attack's end pose into the launcher's start pose. The link is smooth and natural, but the blend region tends to open gaps in hit detection, and the crisp, snappy feel disappears.
• Frame skip: Skip the remaining frames of the current animation, no blending, and start the next node immediately. The link is brisk and responsive, but poses can visibly pop. The "cancel feel" of fighting and action games is usually this one.

Given the same edge, these three produce opposite game feel. At the spec stage, you usually fix only the edge's existence and its window, and decide the transition method (blending vs. frame skip) in the build, together with the animators. Still, reserving a one-line field in the spec — transition: blend / transition: skip — means nobody has to ask "how did we decide this edge transitions, again?" at the build stage. The transition method is the combo graph's hidden third axis.

4.3.7 Build Verification Is a Separate Job (a 4.4 Preview)

Every verification so far happened on the spec. The path enumeration, the DPS simulation, the contradiction detection — all of it targeted the YAML. But the spec's frame values are the designer's intent, not measurements from the build. The actual length of the montage the animator made, the frame where the build's notify actually fires, the window where the input queue actually operates in the engine — those have to be captured and measured from the build.

Automatically extracting the five signals (hit-start frame, recovery, cancel window, input queue, hitstop) from build footage is hard to implement; realistically, the most trustworthy source is in-game telemetry — have the build log "this action accepted this input at this frame," then check that log against the spec (see 4.4 for a comparison of capture methods). That comparison loop is the subject of 4.4. When a window that was [12, 24] in the spec measures [14, 26] in the build, you correct the spec to the build's measured values.

4.3.8 Common Mistakes and How to Avoid Them

Key Takeaways

• A combo is a graph, not a line — so the paths get enumerated by code, not by a person.
• Cancels are the lever that multiplies the paths; the input queue is the shoes that let players walk them.
• The same edge produces opposite game feel depending on the transition method (cancel notify, anim blending, frame skip).
• Verifying on the spec and verifying on the build are different jobs, and for the latter, telemetry is the realistic option.

Try It Yourself — A Mini Pipeline for Combo Path Enumeration

This is the minimum procedure you can run along with by hand. All you need is Python and pyyaml.

setup. Create one working folder and put the spec file and the two scripts inside.

combo-mini/
  warrior_basic_chain.yaml   # the spec from 4.3.2
  enumerate_paths.py         # the DFS enumerator from 4.3.4
  simulate_dps.py            # the simulator from 4.3.5

After pip install pyyaml, paste the YAML from 4.3.2 into the spec file as-is.

prompt. Leave the natural-language-to-spec step to the AI. Use the prompt from 4.3.3 as-is, and make sure to include the final constraint.

프레임 값은 내가 안 준 건 너가 정하지 말고 TODO로 비워 둬라.
캔슬 엣지는 type: cancel로 표시하고, 모호한 부분은 질문으로 따로 빼라.

(The two lines say: for frame values I didn't give, don't decide them yourself — leave them as TODO; mark cancel edges with type: cancel, and pull anything ambiguous out as separate questions.)

These two lines block the AI from fabricating numbers and making arbitrary calls. A human then fills in the TODOs and the question list in the resulting spec.

verify. Once the spec is complete, verify it twice.

python enumerate_paths.py warrior_basic_chain.yaml   # all paths + contradictions
python simulate_dps.py    warrior_basic_chain.yaml   # per-path DPS table

In the enumeration output, check (1) that cyclic paths don't grow without bound, and (2) that there are no dangling edges pointing at undefined nodes. In the DPS output, check that the gaps between paths fall within your intended range. If a gap is too large, fix the frames/damage in the spec and run it again.

Solo Scale-Down

If you don't have time to build the tools, finish the spec writing and the path enumeration in a single AI conversation. Give it the natural-language rules and pack this into one prompt: "Convert these into a combo spec YAML, then list every possible path from the start node depth-first, cutting each cycle after one pass. Flag any edge that points to an undefined node." The AI does the spec conversion, the enumeration, and the contradiction detection in one go. For the DPS simulation, hand it the node damage as a table and follow up with "compute each path's total damage and frames and give me a table." You lose precision, but you see much farther than a whiteboard. The core doesn't change — don't unfold combos in your head; have them enumerated, and look.

4.4 AI-Assisted Combat Simulation and Verification

Build #234 from the combat task force (TF) has just come in. It's the first build to touch the new skill skill_thunder. The spec sheet says hit timing: 150ms. I press the input. My fingertips tell me: late. Definitely late. I call over teammate A in the next seat. "Doesn't this look a bit floaty to you?" Teammate A tries it a couple of times. "Hmm... maybe, I guess." Neither of us is sure. The spec says 150; my hands insist it's around 200. Who is right? Fingertips versus paper. In the next build, someone will again say "feels fine to me," and on that one remark another build will drift by.

The goal of this chapter is to end that fight. When the fingertips say 200, show in numbers whether it really is 200. And before a build comes in, know from the spec alone that "this skill's DPS is 30% over target." Back when I was shaping combat from the early days of a AAA MMORPG with 200 people on it, the helplessness when feel and numbers diverged was exactly the same. The only thing that has changed is that now there is a tool at hand to settle that divergence with numbers.

If 4.2 and 4.3 covered how to write a combat spec, 4.4 covers whether that spec works as intended. Verification has two axes. One is simulation — verifying by computation alone, with no build; the other is capture analysis — pulling measured values out of the actual build. When the two axes are tied into one cycle, the turnaround of combat design shrinks from days to hours.

To state the conclusion up front: the heart of this chapter is putting the number written in the spec (150ms) and the number measured from the build (220ms) side by side and reading the gap (4.4.5). The earlier sections (the simulator, combo enumeration) can be read as the preparation that makes that comparison possible.

4.4.1 The Cost of Waiting for a Build

What has to happen for a combat designer to verify one new skill?

The designer writes the spec. A programmer enters the data, an artist attaches motion and effects, a build runs, QA does a pass, and only then does the designer get hands on it. Two days if fast, usually three or four. When "the DPS is too high" is discovered at the end of that cycle, the discovery becomes an order to go back to the start. Another three or four days.

Simulation is a tool that gives an answer at the first step of this cycle. Compute from the spec alone. If the answer is bad, fix the spec and compute again. Before entering the expensive build stage, the spec itself gets filtered once. It's like putting a model car into a wind tunnel first. Before the real car ever touches the road, a suspect design fails on the desk.

Of course, the wind tunnel doesn't predict the road 100%. That's why the second axis, capture analysis, is needed. If simulation is the ideal answer, capture is the answer of what actually happened in the build. Putting the two side by side and reading the difference — that is this entire chapter.

4.4.2 simulate_dps — A Runnable Simulator

Abstract pseudocode verifies nothing. So from the start, I build code that runs. Below is the core skeleton of simulate_dps.py, the one I use in the combat TF, reconstructed for this book with company data stripped out. It runs on the Python standard library alone, with no dependencies (the full file is in "Try It Yourself").

The input is simple. A skill is a dataclass with damage, cast_sec (cast occupancy time), cooldown_sec, and resource_cost; a character has a resource pool, regen per second, a skill list, and a priority rotation. The engine running on top is a single greedy rule: "at every moment, use the highest-priority skill that's available." The point is to capture an ideal upper bound — neither smarter nor dumber than a real player. Excerpting just the spine:

# Build the timeline in 0.05s ticks. When not casting, use the first available skill in priority order.
while t < duration_sec:
    resource = min(char.max_resource, resource + char.resource_regen * tick)
    for name in cooldowns:
        cooldowns[name] = max(0.0, cooldowns[name] - tick)
    if t >= busy_until:                     # wait while the cast motion runs
        for name in char.rotation:          # in priority order
            s = skill_by_name[name]
            if cooldowns[name] <= 0 and resource >= s.resource_cost:
                total_damage += s.damage
                resource -= s.resource_cost
                cooldowns[name] = s.cooldown_sec
                busy_until = t + s.cast_sec  # no next skill until this time
                break
    t += tick
# …(for the dataclass definitions, warrior input, and output loop, see the full code in "Try It Yourself")

Running warrior for 20 seconds with skill_thunder (damage 420, cast 0.9s, cooldown 6s) at priority 1 and skill_dash and basic_1 behind it (python simulate_dps.py):

평균 DPS: 261.0
  t=  0.0s  skill_thunder  자원=60
  t=  0.9s  skill_dash     자원=47
  t=  1.3s  basic_1        자원=50
  t=  1.6s  basic_1        자원=53
  t=  1.9s  basic_1        자원=55
  ...

What does this value mean? It means that without a build, within one second, I know the warrior's ideal DPS ceiling is about 261. If the target DPS was 180, this spec is +45% over. No need to wait for a build — adjust damage or cooldown_sec right now.

I'll state the limits honestly too. This simulator does not model player input mistakes, gaps caused by movement and dodging, or enemy interference. So its number always comes out higher than the actual build. That is not a bug; it is the very definition of the simulator as an upper bound. The gap to reality gets filled by capture in 4.4.5.

A note on using AI. I wrote the skeleton above myself, but when attaching a new resource model (say, a rage gauge that fills when taking damage), I ask Claude while quoting the existing code: "Add a rule to this simulate_dps — +5 rage on getting hit. Inside the tick loop, as a separate variable from the existing resource regen." Ask it to generate a whole simulator from a blank page and you get unverifiable code. The human holds the spine; the AI grows the branches.

4.4.3 Automatic Combo Path Enumeration

A single DPS number is not enough. To verify "which combo is the intended main combo," you have to lay out every possible path. Draw the tree by hand and your head bursts at seven or eight nodes. Exhaustively unfolding paths is something a machine does overwhelmingly better than a person — provided you make it produce output a person can trace back through.

The following code takes a combo graph, enumerates all paths, and sorts them by DPS. combo_graph is an adjacency list of "which action can cancel into which action," extracted directly from the state machine spec of 4.3. The core is the all_paths generator, which recursively unfolds every path to its dead end.

# enumerate_combos.py — unfold every path in the combo graph and sort by DPS
combo_graph = {"start": ["A"], "A": ["B", "D"], "B": ["C", "E"], "D": ["C"], "C": [], "E": []}
action_stats = {  # (damage, duration in seconds)
    "A": (300, 0.8), "B": (450, 1.0), "C": (450, 1.2), "D": (600, 1.4), "E": (200, 0.6),
}

def all_paths(node="start", path=None):
    path = (path or [])
    nexts = combo_graph.get(node, [])
    if not nexts:                       # dead end = a completed combo
        yield [n for n in path if n in action_stats]
        return
    for nxt in nexts:
        yield from all_paths(nxt, path + [nxt])

results = []
for p in all_paths():
    dmg = sum(action_stats[a][0] for a in p)
    dur = sum(action_stats[a][1] for a in p)
    results.append((p, dmg, round(dur, 1), round(dmg / dur, 1)))

for p, dmg, dur, dps in sorted(results, key=lambda r: -r[3]):
    print(f"{' → '.join(p):<18} {dmg:>5} dmg  {dur:>4}s  DPS {dps}")

The output:

A → D → C            1350    3.4s  DPS 397.1
A → B → C            1200    3.0s  DPS 400.0
A → B → E             950    2.4s  DPS 395.8

The signal a designer should read here is not simply which path came first. The three paths' DPS values sit nearly on top of each other, at 396–400 — and that is a signal that "every combo is about equally efficient, so the main combo has no identity." If the intent was "A→D→C should be the high-risk, high-reward main combo," then raise D's damage or shorten its time to lift that DPS a clear step above the rest. Time to go back to the spec.

Where this automatic enumeration replaces hand calculation, even when the combo nodes grow to 20, a person only has to read the sorted table.

4.4.4 Build Capture Analysis — The Realistic Method Is Telemetry

Now the second axis: measuring what actually happened in the build. The picture that comes to mind first is "an AI watches the build footage and analyzes it automatically," but here I'll split the options honestly. There are three ways to get measurements, and their cost and accuracy differ greatly.

Option A (direct video pixel analysis) sounds attractive: automatically extract five signals from the screen — the input display, character motion changes, the first frame of an effect, the audio waveform, the damage-number UI. But build it for real and an error of ±1–2 frames is the baseline, thanks to frame compression noise, UI occlusion, and motion blur. At 60fps, one frame is about 16.7ms. For verification that argues hit timing in milliseconds, ±33ms of noise is fatal. The implementation difficulty is very high, and the accuracy doesn't repay the effort.

So the realistic answer is option C: in-game telemetry logs. The engine already knows, internally and exactly, the input time, the animation notify time, the VFX spawn time, and the damage application time. Instead of inferring those times from pixels, make the engine print them as one-line logs. Rather than reconstructing 100ms from pixels, you take down verbatim the 100ms the engine already knows.

// One line added to the combat action handling code (UE C++ pseudo-example)
// Call the same logger at input receipt / damage application
CombatTelemetry::Log("input",  SkillName, GetWorld()->GetTimeSeconds());
CombatTelemetry::Log("hit",    SkillName, GetWorld()->GetTimeSeconds());

The logger drops one JSON Lines entry per line.

{"event":"input","skill":"skill_thunder","t":12.340}
{"event":"hit",  "skill":"skill_thunder","t":12.560}
{"event":"input","skill":"basic_3","t":14.100}
{"event":"hit",  "skill":"basic_3","t":14.166}

The time difference between input and hit is the measured hit timing. 12.560 − 12.340 = 0.220 seconds = 220ms. Not the ±33ms of pixel analysis — the engine's own clock, as is. Pulling this log and checking it against the spec is the next section.

4.4.5 Worked Transcript: Spec 150ms vs. Measured 220ms

Now bring the two axes to one table. The spec promised 150ms; telemetry measured 220ms. +70ms. The fingertips were right. I'll follow, end to end with the AI, the process of narrowing down the cause of this gap. No summarizing — the scene where the AI grabs the wrong lead at first is included as is.

Prompt

The spec says hit timing 150ms; the measurement says 220ms. I paste the log below and ask at the length a person would actually type. A short request with clear intent beats elaborate formality — one line demanding the verification method and one line banning assertions are the spine of this prompt.

skill_thunder hit timing is spec'd at 150ms but measures 220ms, +70ms over. Using the telemetry below, break down the possible causes and state for each one which log confirms or rules it out. No assertions — if you're not sure, mark it 'unverified'. // The two key intents are "include the verification method" and "no assertions." Drop the rest of the formality and the result is the same.

{"event":"input","skill":"skill_thunder","t":12.340}
{"event":"anim_start","skill":"skill_thunder","clip":"cast_thunder","t":12.340}
{"event":"anim_notify","skill":"skill_thunder","notify":"HitWindow","t":12.560}
{"event":"hit","skill":"skill_thunder","t":12.560}

Per the spec, the HitWindow notify of cast_thunder is at the 0.150s mark.

Claude's Raw Output (Round 1 — Before Verification, Wrong Lead Included)

I estimate the following four causes for the +70ms overshoot.

1. Network latency. The input may have picked up 70ms on a round trip to the server. If this is a multiplayer build, check the RTT.
2. Frame rate drop. If the build runs at 30fps, one frame is 33ms, so notify timings get rounded to frame boundaries and the delay accumulates.
3. Cast motion length change. The cast_thunder clip may have become longer than spec'd, pushing the HitWindow notify back.
4. Input buffer delay. The input queue may have been processed one tick late.

The most likely cause is #1, network latency. 70ms is a typical RTT range.

Human Verification and Rejection

Stop here and reread the log. The AI's top-ranked guess (network) is already ruled out by this very log. input and anim_start are stamped at exactly the same time, 12.340. The motion started the instant the input arrived; there is no room for a network round trip. #1 is wrong.

2 (frame rate) is weak too. At 30fps you would see jitter quantized in 33ms steps, but input→hit is a clean, exact 0.220. That smells not of frame-boundary rounding but of a fixed position inside the clip.

The decisive clue is elsewhere. anim_notify fires at +0.220 relative to anim_start. The spec says HitWindow should sit at 0.150 after clip start, but in the actual clip it is fixed at the 0.220 mark. In other words, either the clip itself was authored differently from the spec, or the notify position was moved from 0.150 to 0.220. The cause is neither network nor frame rate — it is #3, the motion/notify data. The AI did include the right answer among its four candidates, but ranked them upside down.

Follow-Up Prompt

I fill in the exclusion grounds by hand and throw it back. No need for a long explanation — just nail down, briefly, what was ruled out and which facts remain.

Network and frame rate ruled out. (Grounds: input = anim_start at the identical time, so no input→motion delay / input→hit is a constant 0.220 with no frame noise.) Remaining fact: anim_notify is at anim_start +0.220; spec says +0.150. Narrow the cause from this fact alone, and state what to request from the programmer and the animator in units of actions. // The key is "in units of actions" — end not with guesses but with who gets asked for what.

Claude's Raw Output (Round 2)

Given the stated grounds, the cause narrows to the HitWindow notify in animation clip cast_thunder being placed at 0.220s instead of 0.150s. Two branches remain.

• (a) The notify is correct at 0.150, but the whole clip slowed down — if the play rate is lower than spec or the clip length grew, the 0.150 mark stretches to 0.220 in real time.
• (b) The notify position itself was moved to 0.220 — clip length unchanged, only the marker moved.

Checks that separate the two branches: 1. To the animator: request cast_thunder's HitWindow notify frame number and the clip's total frame count, plus the change history compared against the values at spec-writing time. If the marker was moved, it's (b). 2. To the programmer: confirm whether skill_thunder's montage play rate is 1.0, and whether the character's attack speed stat multiplies into this clip. If the play rate is 0.68 (=0.150/0.220), it's (a). 3. Measure the anim_start→anim_notify interval once more at a different character attack speed. If the interval changes with attack speed, it's (a); if it stays invariant, it's (b).

Recommended action: if confirmed as (b), move the notify back to 0.150 or update the spec to 0.220 (whichever was intended). If (a), inspect the play-rate application logic.

This output is worth adopting. It does not assert a guess; it splits the question into branches (a)/(b), and how to separate the branches with data and who to ask for what are written in units of actions. Check #3 in particular (re-measuring at a changed attack speed) is a decisive fork that a person easily misses. Take this report into the meeting as is, and the meeting stops being a debate over "what could the cause be" and becomes "confirm (a) or (b) within 30 minutes and pick the action."

What this worked transcript shows, above all, is that the AI does not hand you the right answer from the start. The first output was a wrong lead that ranked network first. Only when human verification — reading the log and ruling out candidates — entered the loop did the analysis converge on the answer. The AI spreads the candidates wide; the human narrows them. That division of labor is the methodology of all of 4.4.

4.4.6 Two Axes, One Cycle — The Verification Loop

If simulation (4.4.2–4.4.3) and capture analysis (4.4.4–4.4.5) run separately, you get half the value. Tied together, they form the following loop.

flowchart TD
    A["Write the spec
(designer, 4.2·4.3 templates)"] --> B["Simulation
simulate_dps · combo enumeration
(automated, 1 second)"]
    B -->|"DPS/combo anomaly"| A
    B -->|"Spec passes"| C["Build
(programmers & artists, days)"]
    C --> D["Collect telemetry logs
(input · hit · anim_notify)"]
    D --> E["Auto-compare spec vs. measurement
(detects gaps like 150ms vs 220ms)"]
    E -->|"Items over threshold"| F["AI cause-hypothesis report
(AI widens candidates → human narrows)"]
    F --> G["Designer review → decide action
(update spec vs. fix build)"]
    G --> A
    E -->|"All items match"| H["On to the next skill"]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class B,E code;
    class F ai;
    class A,G human;
    class D data;
    class H pass;

Because simulation gives its answer before the build, any spec that enters a build has already been filtered once. So a problem found after the build narrows in character: not "the spec was wrong" but "the spec and the implementation diverged." The +70ms of 4.4.5 was exactly the latter — the spec's 150 was reasonable; the implementation drifted to 220. This distinction removes blame disputes from meetings.

This loop does not cover all combat content, though. Areas where the feel is the content — a main boss's signature set piece, say — do not reduce to a DPS number. Simulation is strong on numbers-driven content; for presentation, the answer is still human eyes reviewing the footage. The loop runs in the river of numbers; the river of presentation flows on its own.

4.4.7 What Six Months of Operation Showed

These are six months of measurements from the combat TF of an MMORPG I ran (Project A, which targeted refgame-style controls). The figures below are actual measurements culled from the TF's internal records; I'll note that build counts and times are rounded to cycle units (measured in cycles and half-days, not exact minutes).

The change that matters more than the numbers is the character of the meetings. Before, half of every meeting was "this skill is too strong" versus "no, it's fine." Fingertips versus fingertips. After, that time moved to "measured DPS is +12% over target and measured hit timing is +70ms over spec — do we shorten the motion, or cut damage by 10%?" The time spent fighting over what the problem is became time spent deciding how to fix it.

I'll write down the cost of this transition honestly too. Planting the telemetry logger across the combat code took about one to two weeks of initial work, and unifying the spec schema across every character and skill took another quarter on top of that. In the first quarter, I judged it sufficient for just one of the two — simulation or telemetry — to be running. The two only meshed into a single loop from the second quarter on.

4.4.8 Common Mistakes and How to Avoid Them

Five mistakes keep repeating.

First, trusting the simulation value absolutely. simulate_dps's 261 is an upper bound, not a measurement. Without comparing against telemetry, you will always overestimate.

Second, not measuring at all. If you only simulate the spec and never look at the build through telemetry, gaps like the +70ms of 4.4.5 quietly accumulate. Telemetry logging is not an option; it is basic plumbing of combat code.

Third, not bringing the report to the meeting. Even with the automated report sitting right there, nobody looks at it if it isn't on the agenda. Make "this build's telemetry comparison table" a fixed agenda item.

Fourth, adopting AI estimates without verification. As we saw in 4.4.5, the AI's first estimate was a wrong lead. AI is a tool for widening the candidates, not for reaching the conclusion. Never skip the human step of ruling out candidates with logs.

Fifth, letting every skill have a different spec structure. If one skill writes cast_sec, another cast_time, and another castMs, both the simulator and the comparison script break every time. Enforce one common spec schema on every skill — that is the premise on which all of 4.4's tools run.

You don't need to fix all five in the first quarter. Even one or two taking root shortens the cycle visibly. The rest fill in naturally as the loop keeps turning.

4.4.9 Closing Part 4

Across 4.1–4.4 we covered, in order, the coordinates of combat design, look & feel, combos, and simulation. 4.1 covered what a combat designer treats as a measurable object; 4.2, how to measure and tune hit timing, hitstop, and effect synchronization; 4.3, how to write combos, cancels, and input queues as state machines; and 4.4, how to verify — without a build and in the build — that all those specs work as intended.

A combat designer's week after finishing Part 4 changes like this. Monday: simulate_dps auto-verification attaches to the new skill spec. Tuesday: automatic combo path enumeration checks the main combo's identity. Wednesday: when the build comes in, the telemetry comparison table appears automatically. Thursday: 30 minutes of data-driven discussion. Friday: spec revisions for the next cycle. Build cycles drop from 3–4 to 1–2, and meetings shrink to less than half. The abstraction called impact feel moves over to a measurable 220ms.

And that scene from build #234 — to the question "doesn't this look a bit floaty?", the telemetry log now answers in our place: 220ms. The fight of fingertips versus paper is over.

Next, Part 5 is narrative design. We move on to the full-scale application of the NarrativeDocs Layer 0–4 structure introduced in 2.3.

Try It Yourself

setup. 1. Create the full simulate_dps.py below, exactly as is. No dependencies; it runs immediately with python simulate_dps.py and reproduces the "평균 DPS: 261.0" output from 4.4.2.

# simulate_dps.py — compute DPS from the spec alone, no build needed
from dataclasses import dataclass

@dataclass
class Skill:
    name: str
    damage: float          # damage per hit
    cast_sec: float        # cast (motion-occupancy) time, seconds
    cooldown_sec: float    # cooldown, seconds
    resource_cost: float   # resource cost (MP/stamina)

@dataclass
class Character:
    name: str
    max_resource: float
    resource_regen: float  # resource regen per second
    skills: list           # list[Skill]
    rotation: list         # priority order (skill names)

def simulate_dps(char: Character, duration_sec: float, tick=0.05):
    cooldowns = {s.name: 0.0 for s in char.skills}   # remaining cooldowns
    skill_by_name = {s.name: s for s in char.skills}
    resource = char.max_resource
    total_damage = 0.0
    busy_until = 0.0          # when the cast motion ends
    log = []
    t = 0.0
    while t < duration_sec:
        resource = min(char.max_resource, resource + char.resource_regen * tick)
        for name in cooldowns:
            cooldowns[name] = max(0.0, cooldowns[name] - tick)
        if t >= busy_until:   # pick the next skill when not casting
            for name in char.rotation:          # in priority order
                s = skill_by_name[name]
                if cooldowns[name] <= 0 and resource >= s.resource_cost:
                    total_damage += s.damage
                    resource -= s.resource_cost
                    cooldowns[name] = s.cooldown_sec
                    busy_until = t + s.cast_sec
                    log.append((round(t, 2), name, resource))
                    break
        t += tick
    return total_damage / duration_sec, log

if __name__ == "__main__":
    warrior = Character(
        name="warrior", max_resource=100, resource_regen=8,
        skills=[
            Skill("skill_thunder", damage=420, cast_sec=0.9, cooldown_sec=6, resource_cost=40),
            Skill("skill_dash",    damage=180, cast_sec=0.4, cooldown_sec=3, resource_cost=20),
            Skill("basic_1",       damage=60,  cast_sec=0.3, cooldown_sec=0, resource_cost=0),
        ],
        rotation=["skill_thunder", "skill_dash", "basic_1"],
    )
    dps, log = simulate_dps(warrior, duration_sec=20)
    print(f"평균 DPS: {dps:.1f}")
    for t, name, res in log[:8]:
        print(f"  t={t:>5}s  {name:<14} 자원={res:.0f}")

1. Add one telemetry log line each at the input-reception and damage-application points of your combat engine code (4.4.4). The key is printing the engine clock (GetTimeSeconds and the like) as is.

prompt. Pick one item in your build telemetry that diverges from the spec and query the AI in the format of 4.4.5 — paste the log excerpt, and be sure to include "don't assert guesses; give a verification method for each cause, and mark anything uncertain as unverified."

verify. Do not adopt the AI's first output as is. Read the log yourself, strike out the candidates you can rule out by hand (like the network and frame-rate exclusions in 4.4.5), attach your grounds, and ask again. When the final report ends in units of actions — "estimated cause + who to ask for what" — take it to the meeting.

Solo Scale-Down. If installing the telemetry logger everywhere is too much, log just the two lines — input and hit — for the one skill you want to verify. Run simulate_dps for that one skill's DPS only. Don't deploy the whole toolset; run the loop once around the single most suspicious skill, then expand.

Key Takeaways

• Simulation computes the spec's ideal upper bound before a build, shrinking verification from days to hours
• For measuring builds, telemetry logs — not video — are the realistic path; take down the engine's own clock as is
• AI is the tool that widens the candidate causes; narrowing them down with logs is the human's job

Part 5 · Narrative Design

5.1 The NarrativeDocs Layer 0–4 Structure

When I walked into the meeting room, a character's name was circled in red on the whiteboard. An NPC I'll call Kim. In one designer's side quest, he was "the adoptive father who took the protagonist in as a child." In chapter 3 of another designer's main quest, he was "the old comrade who betrayed the protagonist and left." Both documents had been approved a month earlier, and both were already in the build. We had even gotten a quote for voice recording.

It was nobody's fault. Both designers had read the worldbuilding document and consulted the character's lore. The problem was that the same character's lore was scattered across three different files, and nobody could say with certainty which one was "real." The worldbuilding document was a monolithic 70-page Word file; a search turned up Kim in eleven places. There was no way to tell which lines were decisions and which were memos.

What we decided after that meeting was to split NarrativeDocs into five layers. This chapter is the story of those five layers.

5.1.1 Why Start with the Most Abstract Discipline

There is a reason the discipline-by-discipline Layer decomposition opens with narrative.

Narrative is the most abstract discipline. Worldbuilding, emotion, tone — none of it reduces to numbers. Unlike art or systems, there are no clean units like "sprite count" or "damage coefficient." If a discipline this abstract decomposes cleanly into Layers, the more concrete disciplines naturally follow the same pattern. In effect, we test whether the approach works in the hardest place first.

Narrative also has the most interfaces. Characters touch art; quests touch content and level design; dialogue touches UX and localization; rewards touch systems. It crosses more discipline boundaries than anything else, so the value of unifying the Layers shows up immediately.

Finally, natural-language deliverables make up the largest share of its output — which also makes it the discipline where AI assistance does the most work. That said, not every game is narrative-driven. For a casual or arcade genre, this chapter's depth may be overkill. Even so, the skeleton itself — split the monolithic document into Layers and narrow the interfaces — carries over to any discipline as is.

5.1.2 The Five-Drawer Chest

Here is the shape of NarrativeDocs decomposed into five layers. Vision (L0) sits at the top, build/QA (L4) at the bottom, and the passages connecting the layers are deliberately narrow.

Mapped to folders, it looks like this. Each filename below is not an abstraction invented for this book — it is a file that actually exists in that folder.

NarrativeDocs/
├── Layer0_Vision/
│   ├── world_premise.md          (worldbuilding premise — immutable)
│   ├── narrative_pillar.md       (3 emotional pillars)
│   └── tone_manifesto.md         (tone + forbidden-word list)
├── Layer1_System/
│   ├── faction_system.md
│   ├── reputation_model.md
│   ├── dialogue_branching_rule.md
│   └── lore_consistency_rule.md
├── Layer2_Content/
│   ├── main_quest/               (per chapter)
│   ├── side_quest/
│   ├── character_bible/
│   └── lore_codex/
├── Layer3_Data/
│   ├── quest_table.xlsx
│   ├── npc_table.xlsx
│   ├── dialogue_id_table.xlsx
│   └── reward_table.xlsx
└── Layer4_Build_QA/
    ├── narrative_qa_checklist.md
    ├── voice_review_log.md
    └── localization_status.md

What matters is that no single person owns all five layers. Each layer has a different primary owner, and only the passages between adjacent layers are standardized. The red arrows in the figure above are those passages. The passage between L2 and L3 is drawn deliberately as the narrowest of all (the thick red arrow) — the reason comes later.

As a chest of drawers, it is a five-drawer chest. The first drawer holds the one worldbuilding line that never moves, the second the rulebooks, the third the prose, the fourth the sheets, the fifth the review logs. The passages between the drawers are narrow, and each passage has a change-notification bell mounted on it.

5.1.3 L0 — Kept Small So It Never Changes

L0 does not change. If it changes, the game's identity changes. So it has to be small. Small is what keeps it from changing.

About 4.5 pages in total. That is the weight of L0. If it gets heavy, changing it becomes frightening; once changing it is frightening, the other layers start routing around L0. Once the routing-around begins, L0 is a dead document.

The actual skeleton of narrative_pillar.md looks like this (content abstracted).

---
title: Narrative Emotional Pillars
layer: L0
status: locked
last_updated: 2026-05-18
---

## 1. Longing for What Was Lost
- The player loses one thing at the end of every chapter.
- What is lost does not come back (flashbacks only).

## 2. The Conflict Between Duty and Freedom
- Every major NPC carries two duties.
- The player's choice can honor only one of them.

## 3. The Weight of a Small Kindness
- A small kindness yields a greater outcome than a grand heroic act.

These three pillars — longing for what was lost, the conflict between duty and freedom, the weight of a small kindness — set the direction for the hundreds of pages beneath them. And status: locked is not a mere label. One of L4's automated checks reads it: if a locked document is modified in a PR, the merge is blocked without the lead narrative designer's approval.

5.1.4 L1 — The Narrative Closest to Code

L1 can change, but changes are expensive. It is the rulebook layer. When one line of a rulebook changes, every piece of content that follows that rule is affected.

Here is the skeleton of faction_system.md.

---
title: Faction System
layer: L1
atoms:
  - faction_relation_matrix
  - faction_membership_rule
  - faction_quest_eligibility
---

## 1. Faction Concept
N factions. Each faction is defined by (ideology, resources, territory).

## 2. Inter-Faction Relations
- relation_matrix.json (-3 hostile ~ +3 allied)
- Relation change triggers: main quest decisions, reputation thresholds

## 3. Player Membership Rules
- Maximum 2 simultaneous memberships (no two hostile factions at once)
- Leaving penalty: reputation -2, allied factions -1

Look at the atoms: list in the frontmatter. These three atom names are not just memos — they are the identifiers tracked by the Part 7 ontology and the Part 11 relation map. When a quest references faction_quest_eligibility, that quest is automatically added to the impact list whenever this rule changes. L1 is the narrative deliverable closest to game code, so we write it paired with a systems designer.

5.1.5 L2 — The Thickest Layer, Where the Prose Lives

L2 is the thickest layer. Main quests, side quests, the character bible, and the lore codex all live here. The real lore for Kim — the "adoptive father vs. traitorous comrade" who collided in that meeting room — now exists only as one file inside character_bible/. That file is the single source of truth, and quests only reference it.

The main quest folder looks like this.

main_quest/
├── chapter_01_awakening/
│   ├── 00_chapter_overview.md
│   ├── 01_quest_a_call_to_arms.md
│   ├── 02_quest_b_first_choice.md
│   └── ...
├── chapter_02_road/
│   └── ...
└── _TEMPLATES/
    └── quest_template.md

Each quest file follows the standard atom format.

---
title: When You Take Up Arms
layer: L2
type: main_quest
atoms:
  - quest_chapter_01_awakening_a
related:
  affects: [reputation_model, faction_relation_matrix]
  derives_from: [narrative_pillar, world_premise]
  requires: [character_kim, faction_alpha]
  part_of: chapter_01_awakening
---

## Progression Steps
1. ...

## Branches
- If option A is chosen: ...
- If option B is chosen: ...

## Rewards (see L3)
- reward_table.xlsx → quest_001 row

The heart of it is the related: block. The moment you write requires: [character_kim], you have declared that this quest pulls Kim's lore from the character bible — it no longer defines Kim anew inside its own file. Narrative prose lives in L2; numeric rewards live in the L3 sheet. If both live in one file, every one-line sheet fix means touching the prose, and then the translation keys drift out of sync.

5.1.6 L3 — Not a Single Line of Natural Language

L3 is sheets and IDs. Not one natural-language sentence goes in.

quest_table.xlsx
| quest_id | chapter | type | unlock_level | reward_xp | reward_gold | dialogue_set_id |
|----------|---------|------|--------------|-----------|-------------|-----------------|
| q_001    | ch01    | main | 1            | 500       | 100         | ds_001          |
| q_002    | ch01    | main | 2            | 800       | 150         | ds_002          |

Even dialogue is referenced only by ID. The lines themselves live separately in dialogue_id_table.xlsx, mapped 1:1 to translation keys. The passage connecting L2 and L3 needs exactly one column: quest_id. That is why this passage alone was the thick red arrow in the earlier figure. Narrowing an interface down to a single column is the core of Layer separation. When the passage is wide, the two sides know too much about each other, and fixing one side breaks the other.

5.1.7 L4 — The Ship Gate

L4 is review and shipping. Every time new content lands, automated and manual checks run. The automated checks are scripts. The four below are the lints actually wired into CI.

Note that tone_lint.py reads L0's tone_manifesto.md directly. The topmost layer (the immutable vision) and the bottom layer (the ship gate) are wired together by automation. If a forbidden word written into the vision turns up in the prose right before release, the build is blocked.

What automation cannot catch, people review.

When the boundary between automated and manual is clear, review time becomes predictable. You can answer the question, "How many days will this chapter's review take?"

5.1.8 Putting AI to Work on the Layers — A Worked Transcript

That is the structure. But where the structure really earns its keep is in making new content. What follows is a real session, reproduced as is, in which I had Claude take a one-line side-quest idea — "a short side quest where Kim hands the player a keepsake from his late wife" — and scatter it across the Layers of a project where the five layers were already in place. Nothing is summarized; the parts that missed and the part I rejected are included. The prompt pinned the L0/L1 context as inviolable and asked for the L2 quest file (with the related: block and about 200 characters of prose), the L3 quest_table row and dialogue_id, and a tone self-check — with instructions to write only L2 first, then stop.

The prompt I sent (in full):

Do not violate the attached L0/L1 context in any way, and decompose this into our Layer structure.

[narrative_pillar.md in full — the 3 emotional pillars]
[tone_manifesto.md excerpt — forbidden words: "fate", "prophecy", "the chosen one"]
[character_bible/character_kim.md excerpt — Kim: the adoptive father who took
 the protagonist in, taciturn, trails off mid-sentence, never names his feelings]

Idea: "A short side quest where Kim hands the player a keepsake from his late wife."

The L2 quest file (with the related block, ~200 characters of prose), the L3 quest_table
row and dialogue_id, plus a tone-violation self-check. Write only L2 first, then stop.

Claude's raw output (L2):

---
title: The Faded Handkerchief
layer: L2
type: side_quest
atoms:
  - quest_side_kim_keepsake
related:
  affects: [reputation_model]
  derives_from: [narrative_pillar]
  requires: [character_kim]
  part_of: chapter_02_road
---

## Progression Steps
1. Kim quietly calls the player over. As usual, he does not state his business right away.
2. He holds out an old handkerchief. "This… I thought it might be better off in your hands."
3. When the player asks what it is, Kim looks out the window instead of answering.
4. (Choice) Accept / Decline.

## Branches
- Accept: Kim's reputation +1. Unlocks 1 handkerchief-related flashback in a later chapter.
- Decline: Kim nods and puts the handkerchief away. No reputation change.
  The handkerchief never appears again.

## Rewards (see L3)
- reward_table.xlsx → quest_side_kim_keepsake row

Claude stopped there, as asked — a quest titled "The Faded Handkerchief," in which Kim quietly calls the player over, wordlessly offers an old handkerchief, looks out the window instead of answering when asked what it is, and an accept/decline branch where declining means the handkerchief never appears again — and appended one line.

"Reflecting L0 pillar 1 (what is lost does not come back), I made the handkerchief disappear forever if the player chooses 'decline.' One thing needs confirmation, though: the dead-wife detail was not in the character_kim.md excerpt. I added it on my own, so it may conflict with the character bible."

Human verification and rejection:

The tone of this output was exactly right. Kim's reticence, his trailing-off sentences, his habit of never naming his feelings — all of it was alive. No forbidden words either. But that final self-check had put its finger on the real problem. Nothing anywhere established that Kim had a dead wife. The AI had made the natural inference from "keepsake" — the Korean word in the idea, 유품, specifically means something left behind by the dead — to a deceased spouse, and that amounts to quietly adding a new fact to the bible. This is precisely the seed of the accident from the meeting room at the start of this chapter.

So I rejected it and sent a follow-up: the tone could stay, but "dead wife" was new lore the bible does not have — Kim's past is confirmed only as far as "he left something behind when he left his hometown" — so do not specify what the keepsake is, blur it to "something left behind long ago," and since the handkerchief is not in the bible either, soften it to a scrap of cloth.

The follow-up request:

The tone is good. But "dead wife" is new lore the bible does not have, so we can't use it.
Kim's past is confirmed only as far as "he left something behind when he left his
hometown." Don't specify what the keepsake is — rewrite it blurred to no more than
"something left behind long ago." The handkerchief isn't in the bible either, so soften it to "a scrap of cloth."

Output after the follow-up (excerpt):

2. He holds out an old scrap of cloth. "There was something… I left behind,
   long ago. Let's just say this is a corner of it."
3. When the player asks what it is, Kim looks out the window instead of answering.

This time I accepted it. Kim now offers an old scrap of cloth — "There was something… I left behind, long ago. Let's just say this is a corner of it." — and again looks out the window when asked. It touches emotional pillar 1 (loss) without nailing down anything new about Kim's past. What was lost stays blurred to the very end.

This one session shows two things. First, when you inject the Layer context precisely (L0 pillars + L1 tone + L2 bible), the AI matches tone remarkably well. Second, when the AI meets a blank, it fills it in plausibly. When that filler is a new fact absent from the bible, catching it is still a human's job. Because the Layer structure's requires: [character_kim] said where to look, the verifier knew immediately which file to check against. Without the structure, it would have meant digging through 70 pages all over again.

5.1.9 Alarm Bells on the Narrow Passages

The real reason for splitting into five layers is to narrow the interfaces. And every narrow interface gets change-detection automation attached to it.

For example, when someone opens a PR on L1's faction_system.md changing "maximum 2 simultaneous memberships" to "maximum 1," the relation map sweeps the L2 quests that reference faction_quest_eligibility, builds the impact list, and attaches it to the PR as an automatic comment. Instead of "book two or three meetings to find out who is affected," the person who changed the rule reads the attached list and finishes with one 30-minute meeting.

The point is this: if you split the Layers but leave the interfaces vague, all you have added is partitions. The essence is not the Layer split itself but the interface automation.

5.1.10 Six Months of Operation: What Changed

These are the measurements after running the five layers for six months. The figures below are based on my team's operating records, but absolute values are carried over only as directions and ratios (author's estimate, unverified). One limitation: "before" comes from memory and "after" from actual measurement, so this is not the same data measured twice.

The clearest drop is localization misses. With dialogue_id tied 1:1 to translation keys in L3 and dialogue_lint.py blocking mapping gaps, the "untranslated line ships in the build" incident all but disappeared. The shorter onboarding mattered too. Instead of telling a new designer "read all 70 pages of the Word file," we could say "memorize the 4.5 pages of L0, and fill in the L2 template for your quest."

One honest addition: the effect did not arrive all at once. In the first quarter we attached only one piece of automation — the auto comment — and everything else was manual. We added interface automation one piece per quarter. Attaching the automation took longer than splitting the Layers.

5.1.11 The Deeper Reason — The Road to Procedural Generation

Everything so far is the surface reason: unify the language of collaboration across disciplines. But there is one more reason, a deeper one. Layer decomposition is the precondition that makes procedural generation possible. The general thesis — each of the five layers maps onto one role in procedural generation (L0 anchor → L1 rulebook → L2 prose → L3 numbers → L4 gate), and when they are mixed into one mass the generator collapses because it cannot decide where to read from and where to write to — was covered in full in §6.6. Here we look only at how that precondition actually operates on the five narrative layers.

On a monolithic 70-page document, a generation algorithm cannot decide where to start reading or where to write. The five narrative layers become, as they are, the five stages of a generation pipeline — L0 the anchor, L1 the input rules, L2 the place where the prose accumulates, L3 the simulation input, L4 the verification gate.

The worked transcript above was already a miniature of these five stages. The L0 pillars and L1 tone were injected as context (the anchor), prose was generated into L2, an L3 row followed, and the tone self-check stood in for the verification gate. Take what a human ran one quest at a time, move it onto the same structure with a generator mass-producing side quests, and you have procedural generation.

Taken further, the flow runs like this — accumulated player actions → state changes in world Behavior Tree (BT) nodes (above the Squad level) → NPC stat changes (reputation, interests, priorities) → NPC tags plus stats become the spawn conditions → matching quests manifest from the quest cloud. Instead of writing every quest in advance, you leave them tagged, "floating in the air like clouds"; when player actions shift an NPC's stats, the quests whose spawn conditions match those stats descend and appear. This progressive model is covered in detail in 5.3 (flow diagram included). The point to stress here is that this entire flow works only on top of the five-layer decomposition.

Conversely, a team whose Layers are mixed together cannot get to procedural generation. The moment they try, consistency accidents bring it down. Just imagine the Kim accident — adoptive father and traitor at once — mass-produced automatically by a generator.

That does not mean you need the full five-drawer chest from day one. In the first quarter, separating just the one L0 line and a single L1 rulebook is enough. Separate gradually; keep the interfaces narrow.

One last note, on timing. Layer decomposition itself is a separation that dates back to the era of deterministic PCG (procedural content generation). What is new is that an LLM now handles natural-language prose, personas, and narrative branching on top of that separation — the AI writing dialogue in Kim's voice in the transcript above was impossible with the rule tables of five years ago. This timing argument is developed further in 5.3.

The next chapter (5.2) shows how lore_consistency_rule automatically verifies worldbuilding→character→quest consistency on top of these five layers — that is, the checker that structurally prevents the Kim accident.

Try It Yourself — Your First Layer Decomposition

Assume you are starting with an existing monolithic worldbuilding document.

setup. Create five empty folders under a NarrativeDocs folder, from Layer0_Vision to Layer4_Build_QA. Leave the existing monolithic document where it is; pick out only the "one line that never changes" and move it into Layer0_Vision/narrative_pillar.md. Put status: locked in the frontmatter. Keep this one file under 4.5 pages.

prompt. When you create new content, give the AI context in this order — the pillars in full, the forbidden words, the relevant bible excerpt, then your one-line idea — and tell it to write the L2 quest file first, fill in the related: block (requires/derives_from/affects), add no lore that is not in the bible, and stop and ask when in doubt.

[narrative_pillar.md in full]
[tone_manifesto.md forbidden words]
[relevant character_bible file excerpt]

Idea: "<one-line idea>"

Do not violate this context, and write the L2 quest file first. Fill in the
related block (requires/derives_from/affects), add no new lore that is not
in the bible, and stop and ask if in doubt.

verify. Check two things in the output. (1) Actually open the files listed in requires: and confirm the AI did not invent facts that are not there. (2) Search the prose for forbidden words (automatic if you have tone_lint.py, by eye if not). If either check fails, reject, state exactly what was wrong, and re-request. Rejecting the "dead wife" in the transcript above was check (1).

5.1.12 Solo Scale-Down

If you are an indie developer working alone, five layers can look like too much. Two drawers will do.

Keep one vision.md (L0 and L1 merged), one content/ folder (L2), and one spreadsheet (L3). Instead of a separate QA layer, substitute one habit: a single requires: line in each content file's frontmatter. Each time you write a new quest, reopen only the files listed in requires: and check against them — you prevent the Kim accident without digging through 70 pages. What matters is not the number of layers but the habit of keeping "the one line that never changes" separate and showing it to the AI first, every time. That one line is your context anchor, and whether you are solo or a mid-size team, that is where you start.

Key Takeaways

• If narrative — the most abstract discipline — decomposes into Layers, the other disciplines follow the same pattern.
• L0 stays unchanged only if it stays small, and only an unchanging L0 can serve as the context anchor for generation and review.
• The essence is not splitting the Layers but attaching automation to the narrow interfaces.

5.2 Worldview → Character → Quest Consistency Verification

Just before beta, a bug report came up from QA. The title: "The king is speaking informally." The body was short. "In the 3.4 intro cutscene, K_001 (the King) says '야, 잠깐만' ('Hey, hold on') to the player. This character uses '그대' — the archaic, courtly second-person address — everywhere from 1.1 through 3.3."

I asked the writer, and the answer surprised me. "I never wrote that line." Tracing it back, an outsourced writer had hastily filled in one line of a cutscene branch. Our character bible had a voice_profile, but that outsourced writer had never seen the document. The rule lived inside the document; the line came in from outside it.

This is the essence of a consistency incident. It happens not because there is no rule, but because the rule fails to follow the text all the way down. And if that one line sits in a cutscene, it gets scarier. Cutscenes usually get voice recording. While it is still text, one fix ends it; if it is discovered after recording, the irreversible costs follow — re-booking the voice actors, re-recording, re-mixing. The real goal of consistency verification is to catch it before recording.

This chapter covers a workflow that catches that incident with a rulebook and checkers instead of human eyes. We look at the actual artifacts, as-is: how the lore_consistency_rule rulebook becomes the checker's input, how voice_lint pulls tone drift as suspect candidates, and why the final judgment must remain a human seat to the very end.

5.2.1 Where Consistency Incidents Leak From

Collect user reviews of shipped RPGs and MMORPGs and the narrative consistency incidents converge into a few patterns. The types look different, but the cause is almost always the same.

• Worldview contradiction: 1.1 says "magic is forbidden" → in 1.3 an NPC casts magic like it's nothing
• Voice drift: the same NPC's diction and honorific register change from chapter to chapter (the "king's informal speech" incident above)
• Timeline conflict: a dead NPC reappears alive and well in the late game (death-flag sync missed)
• Reward–narrative mismatch: the narrative says "a sword bestowed by the king," but in the data it's a common junk item
• Faction relation contradiction: right after the player declares hostility toward faction A, a faction A NPC offers a friendly greeting

The five look like different incidents, but trace them and they leak from the same spot. Layer 0 (world premise) or Layer 1 (rules) changed, and that change never propagated to Layer 2 (prose) and Layer 3 (data sheets). The rule got updated; the prose stayed stopped on top of the old rule.

Trying to stop this with manual review is asking too much. One chapter tangles together 50 NPCs, 2,000 lines of dialogue, and 30 quests; when one rule line changes, no human can trace 100% of where its effects spread. The missed line doesn't get caught at the review stage — it gets caught in the user reviews after launch.

That said, automated checking doesn't guarantee 100% either. The point is the division of labor. Automated checks pull suspect candidates fast; humans make the judgment. The goal of automation is to cut human review time, not to remove the human. Blur this premise and every failure covered later in this chapter follows.

5.2.2 lore_consistency_rule — The Rulebook You Feed to the Checker

One of Project A's L1 documents is lore_consistency_rule.md. The document is a guide humans read and, at the same time, input the checker parses. The atoms and affects keys in the frontmatter bind those two roles into one body.

---
title: Lore consistency rules
layer: L1
atoms:
  - lore_check_world_rule
  - lore_check_character_voice
  - lore_check_timeline
  - lore_check_faction_relation
related:
  derives_from: [world_premise, narrative_pillar]
  affects: [main_quest/*, character_bible/*, dialogue_id_table]
---

## 1. World rules
- Magic starts banned → any use must specify (when, by whom, justification)
- The gods are silent → no depictions of direct replies (dreams and visions allowed)

## 2. Character voice rules
- Referencing each character's voice_profile is mandatory
- New dialogue must follow the 5 voice_profile items (vocabulary, sentence length, honorifics, emotional expression, forbidden terms)

## 3. Timeline rules
- Every NPC gets a status_timeline (alive / injured / dead / missing / relocated)
- status_timeline checked automatically at dialogue and appearance points

## 4. Faction relation rules
- Record when the faction_relation_matrix changes
- Dialogue written after a change reflects the new relations

That one affects line defines the checker's scan scope. When world_premise changes, the checker re-sweeps all of main_quest/*, character_bible/*, and dialogue_id_table. The work a human used to do in their head — "how far does this change reach?" — is taken over by the dependency graph written in the rulebook.

voice_profile is a separate L2 asset this rulebook references. A single character's profile is entered as numbers and enumerated values, so the checker can use it as a baseline for comparison.

# character_bible/K_001_voice_profile.yaml
character_id: K_001
display_name: 국왕                       # "the King"
voice_profile:
  vocabulary_register: 고풍_격식        # vocabulary register: archaic_formal
  avg_sentence_len: 18                   # average sentence length (in characters)
  honorific: "그대"                      # fixed second-person address (archaic "thou")
  emotion_expression: 절제               # emotional exposure: restrained
  forbidden_terms: ["야", "잠깐만", "ㅋ"] # forbidden terms: casual "hey" / "wait a sec" / "lol"

Only with this yaml does "the king is speaking informally" stop being human intuition and become items a machine can compare. If honorific is fixed at "그대" and the line contains "야", that's not an opinion — it's a rule-violation candidate.

5.2.3 The Consistency Verification Flow

The moment a change occurs, the checker fires. The flow looks like this.

flowchart TD
    A[Change occurs: L0 premise / L1 rule / L2 prose] --> B{Change classifier}
    B -->|which rule's affects does it hit| C[Invoke the matching checker]
    C --> D[Scan L2 prose + L3 sheets in affects scope]
    D --> E[List of rule violation / suspect candidates]
    E --> F[Auto-attach comments to the change request]
    F --> G{Human judgment}
    G -->|genuine violation| H[Fix the prose → re-check]
    G -->|intended change| I[Update voice_profile / rulebook]
    G -->|rule too sensitive| J[Adjust the rule itself]
    H --> K{Still at the text stage}
    I --> K
    J --> K
    K -->|yes: reversible| L[Review can close]
    K -->|no: after recording| M[Irreversible — re-recording cost]
    L -.cutoff line.-> M

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    class B,C,D,F code;
    class G human;
    class A,E data;
    class L pass;
    class M fail;

The last branch is the hidden spine of this chapter. Every consistency judgment must end at the text stage — that is, the reversible stage. Once review slips past recording and casting, fixes become irreversible. That's why checkers like voice_lint and timeline_lint need to run not fast but early. A cutscene line has to pass through at least once before it enters the recording queue.

There are four checkers, each mapping one-to-one to a section of the rulebook.

• world_rule_lint.py — L1 world rules + all L2 prose → violation candidates such as magic use or direct divine responses
• voice_lint.py — voice_profile + dialogue_id_table → lines suspected of voice drift
• timeline_lint.py — npc status_timeline + every line and appearance timing → conflicts such as dead NPCs reappearing
• faction_lint.py — faction_relation_matrix + dialogue tone → lines contradicting faction relations

None of the four checkers is 100% accurate. That's why the output is named "suspect candidates," not "violations."

5.2.4 Worked Transcript: One Full Pass of voice_lint

An abstract "there is a checker" doesn't give you a feel for it. Let's actually run it once. The input reproduces the "king speaking informally" incident from the opening.

setup — Pull the two lines under inspection from dialogue_id_table.

dialogue_id_204  speaker=K_001  text="야, 잠깐만요. 그쪽이 먼저 말해 봐."
dialogue_id_217  speaker=K_007  text="...젠장, 또 실패야. 다시 처음부터."

(Line 204 has the king saying, in a casual register, "Hey, hold on. You go first." Line 217 has K_007 muttering "...Damn it, failed again. Back to the start.")

prompt — The checker itself runs on rules: regular expressions, length comparison, forbidden-term matching. The AI is attached only at one seat — explaining why something is suspect, in natural language a writer will actually read. The full LLM prompt for the inspection step follows.

voice_lint가 뽑은 의심 후보들이야. 판정은 하지 말고, 각 후보가
어떤 voice_profile 항목을 위반한 것 같은지랑 근거만 1~2문장으로 설명해줘.
"위반이다/아니다" 단정하지 말고 "~로 의심됨"까지만.

[voice_profile]
K_001: honorific="그대", avg_sentence_len=18, forbidden=["야","잠깐만"]
K_007: forbidden=["젠장"]

[의심 후보]
- dialogue_id_204 (K_001): "야, 잠깐만요. 그쪽이 먼저 말해 봐."
- dialogue_id_217 (K_007): "...젠장, 또 실패야. 다시 처음부터."

(The prompt, in brief: "These are the suspect candidates voice_lint pulled. Do not judge. For each candidate, explain in one or two sentences which voice_profile item it seems to violate and why. Do not declare 'violation / not a violation' — go no further than 'suspected.'" It then lists the two voice_profiles and the two candidate lines.)

Claude's raw output (reproduced as-is, with no summarizing or cleanup)

[dialogue_id_204 / K_001]
이 대사는 honorific 항목과 충돌하는 것으로 의심됩니다. voice_profile은
2인칭 존칭을 "그대"로 고정하고 있는데, 본 대사는 "그쪽"을 쓰고 존칭 자체가
드러나지 않습니다. 또한 forbidden_terms의 "야"와 "잠깐만"이 모두 등장하여
어휘 격(고풍_격식)에서 벗어난 것으로 의심됩니다. 평균 문장 길이 18자 기준과는
직접 어긋나 보이지 않으나, 어조 자체가 캐주얼해진 점이 위반 신호로 의심됩니다.

[dialogue_id_217 / K_007]
forbidden_terms의 "젠장"이 그대로 사용되어 금기 표현 항목 위반으로 의심됩니다.
다만 K_007(학자)의 emotion_expression 항목이 제시되지 않아, 이 표현이
의도된 감정 고조인지 단순 일탈인지는 이 정보만으로 판단하기 어렵습니다.
판정은 작가 검토가 필요합니다.

(In brief: for 204, the output suspects a conflict with the honorific item — the profile fixes the second-person address to "그대" while the line uses a casual "그쪽" — and notes that both forbidden terms "야" and "잠깐만" appear, drifting from the archaic-formal vocabulary register; it concedes the average sentence length of 18 does not directly deviate. For 217, it flags the forbidden term "젠장" but says that with no emotion_expression item provided for K_007, a scholar, it cannot tell an intended emotional peak from a simple lapse, and that the verdict needs the writer's review.)

This output carries two kinds of honesty we deliberately left in. First, on 204 the AI said the average sentence length "does not directly deviate" — it did not insist that a non-violating item was a violation. Second, on 217 it said "the emotion_expression item was not provided, so this is hard to judge" — it admitted missing information and handed the judgment to a human. If the AI had pushed every suspicion through as "confirmed violation," that would be the more dangerous checker.

verify — The writer receives these comments directly on the change request. The writer makes the judgment.

• 204: a genuine violation. The line went in because an outsourced writer never saw the voice_profile → fix the prose, re-check
• 217: an intended violation. It is the emotional-peak line in 3.4 where K_007 breaks down → add an emotion_peak_exception flag to the voice_profile and register 217 as an exception

The same checker pulled both candidates, yet the endings are opposite. One fixes the prose; the other fixes the rule. That a machine cannot make this fork automatically is the heart of the next section.

5.2.5 Why Judgment Is the Human's Seat

There are three reasons the checker stops at suspicion and hands over the judgment.

First, intended violations exist. In chapters where a character breaks down or changes, the voice drifts on purpose. 217 above is exactly that. An auto-reject checker blocks the writer's dramatic intent.

Second, the rules themselves evolve. If the same kind of suspicion keeps getting judged an "intended change," that's a signal the rule isn't keeping up with reality. Check results don't just drive fixes to the prose; they drive fixes to the rulebook too.

Third, new characters and factions need a learning period. A new NPC whose voice_profile has only two or three items filled in will naturally surface lots of suspicions. Turn on auto-reject during this period and writers start seeing the checker as the enemy.

The checker survives only when the boundary between automated checking and human judgment is sharp. Make it auto-reject and within a month the writers will say, "let's turn this off." It's like installing an oversensitive automatic sensor on the office door: the door slams shut every time someone walks through, until eventually somebody rips the sensor out. A checker should not be a device that closes the door — it should be a device that reports "someone passed through here."

One caveat to add. The principle that review must close at the text stage (the cutoff line in the flowchart above) applies to human judgment just the same. The writer's "intended violation" verdict also has to land before recording. A reversal after recording is no longer a checker problem — it turns into a production-cost problem (the full map of the reversible/irreversible boundary is in 5.4.5).

5.2.6 Measurement — Six Months Before and After

On Project A we rolled out the four checkers in stages and measured six months. The figures below are based on actual logs, expressed as direction and ratio rather than absolute values (internal measurement, not an author's estimate).

• Review time per chapter: about 5 days before → about 2 days after (less than half)
• Consistency incidents found after release: 3–5 per chapter → 0–1
• Chapter output speed per writer: 4 weeks → 2.5 weeks
• Rulebook (L1) update frequency: 1–2 per quarter → 1–2 per month

The last item is the most interesting. With checkers in place, changing rules often is safe. Change one rule line and its impact becomes visible automatically, so the fear of change shrinks and the rules evolve faster. The real effect of consistency tooling is less "we reduced incidents" and closer to "we can now change rules without fear."

One caution: the numbers above are from the point where all four checkers were running. What matters more is that in the early phase, voice_lint alone produced visible results. You don't need to switch on all four from day one.

5.2.7 Where to Put the AI

For the checker core itself, rule-based is the efficient choice. Trust builds only when the same input yields the same result, and an LLM is non-deterministic — the wrong fit for that seat. The AI goes into four other seats.

• Detecting rule-violation candidates → rules (regex, keyword, length, structure checks). Not an LLM
• Explaining why a candidate is suspect → LLM. The natural-language "why this is suspect" explanation seen in the worked transcript above
• Drafting alternative lines → LLM. Drafts for the writer's review; the writer finalizes
• Proposing voice_profile update candidates → LLM. Extracts patterns from dozens of chapters of prose and proposes item refinements

Rules are fast and deterministic; LLMs are strong at explanation and generation. Mix the two roles and both break. Hand the checking to an LLM and the same line passes yesterday and fails today; hand the explanation to a regex and all you get is machine-speak like "honorific item violation."

5.2.8 Adoption Order and Common Failures

Build all four checkers from the start and the burden arrives before the payoff. The recommended order starts with the cheapest, highest-impact pieces.

1. Standardize the five voice_profile items (about 1 month) — settle the character_bible format first. This comes before any checker
2. Minimal voice_lint (about 1 week) — forbidden-term matching only. Blocking a single word cuts post-launch social media incidents by 1–2 per quarter
3. timeline_lint (1–2 weeks) — death-flag checks. Just catching dead NPCs reappearing is a tangible win
4. world_rule_lint + faction_lint (1–2 months) — the remaining two
5. LLM assistance (1–2 more months) — integrate explanation and draft generation

I want to stress that step 2 (voice_lint) alone delivers a lot. The "king's informal speech" incident at the opening was exactly the kind this single step catches.

The failures that recur during adoption are almost fixed, too.

• Building it as auto-reject → revert to the suspect-candidate + human-judgment structure
• Running the rulebook apart from the writers → make writer agreement mandatory for rulebook changes, and let writers request rulebook changes themselves
• voice_profile filled in only for form's sake → fully complete all five items for one character, then expand
• Nobody knows where the check results live → force auto-attachment to change-request comments
• Letting the LLM do the checking itself → checks are rules; only the explanation goes to the LLM
• Reviewing after recording → review closes at the text stage. Never cross the reversible boundary

The last item costs more than all the items above it. The other failures lose you time; this one loses you the voice actors' schedule.

The next chapter (5.3) covers writing narrative prose with AI assistance, rather than checking it. We look at how to inject L0 tone and L1 rules as context, so the AI produces answers from our world instead of generic ones.

Key Takeaways

• Consistency incidents happen not because rules are missing, but because rules fail to propagate into the prose.
• A checker survives only if it stops at suspicion and leaves the judgment to humans.
• All consistency review must close at the pre-recording text (reversible) stage.

Next Chapter Preview

• 5.3. AI-Assisted Narrative Writing — Injecting L0 Tone and L1 Rule Context

Try It Yourself

setup — Pick one character from your character_bible and fully fill out the five voice_profile items (vocabulary register, average sentence length, honorific address, emotional expression, forbidden terms) in yaml. Pull 10 of that character's existing lines from dialogue_id_table and gather them in one file.

prompt — Use the inspection-assist prompt from the worked transcript above as-is. The heart of it is two constraints: "do not judge" and "go no further than 'suspected.'" Paste the voice_profile yaml and the 10 lines into the input.

verify — Judge the output's suspect candidates yourself, line by line. If it's a genuine violation, fix the prose; if it's an intended change, add an exception flag to the voice_profile. Also check whether the AI insisted that non-violating items were violations, and whether it admitted missing information. If the AI declares every item a violation, strengthen the "do not judge" constraint in the prompt.

Solo Scale-Down

If you're a solo developer with no four checkers and no rulebook, one prompt can get you the same effect without a checker core. Maintain a voice_profile yaml per character by hand, and every time you write new dialogue, paste that character's yaml plus the new lines into the assist prompt above to collect "suspect candidates." There's no automation, but the core structure — humans judge, AI explains — survives intact. There's only one line to hold: run this review once before anything goes to recording or voice synthesis. The principle of never crossing the reversible stage doesn't depend on team size.

5.3 AI-Assisted Narrative Writing

It was the day I was drafting the first lines for a new side NPC. Into an empty chat window I typed, "Give me five lines for a village blacksmith NPC." Five seconds later the screen showed, "Hero, entrust thy weapon to me." Not a sentence that merely felt familiar — a sentence I could practically name the source of. The same prompt would have returned the same answer for a different game on a different team. What I realized in that moment was not that the model was weak. It was that I had told the model nothing about our game.

AI writes generic fantasy sentences well. What it cannot write is our world's sentences. The difference comes down to one thing: context injection. Send the L0 tone and the L1 rules along with every request, and the line the AI produces shifts from "a sentence I've seen somewhere" to "a sentence from this game." This chapter covers the practice of running that injection as four layers, and at the end it marks the progressive application that lifts the same principle to world-simulation scale — the world BT (Behavior Tree) plus the quest cloud — as the front line of R&D.

5.3.1 What Happens When the Context Is Empty

In narrative work, AI assistance is the area adopted fastest and the area that loses trust fastest. The failure pattern is almost always the same.

Throw in "five quest-opening lines" and back come five generic fantasy variants starting with "Hero, our village..." Ask it to "polish this character's dialogue" and the voice flattens out — every NPC converges on a similar register. Ask for "a chapter 1 synopsis" and you get the average of every RPG synopsis the model has ever seen.

The problem is not the model; it is that the context is empty. A model outputs the average of its training data. If you don't want the average, you have to give it cues that pull it away from the average. The subject of this chapter is how to build those cues and how to inject them.

On the MMORPG project I run (Project A from here on), narrative AI assistance stacks four layers of context in order. The structure from 5.1 — NarrativeDocs decomposed into Layers 0–4 — is reused here, as is, as the unit of injection.

I don't inject all four layers every time; I pull only the layers the job needs. For a draft of one character's next line, A + B (tone only) + D (that character's 10 most recent lines) is enough. For a new side-quest synopsis, C (the quest structure rules) gets added. For four options of a branch outcome, C (the branching rules) + D (the full text leading up to the branch) gets heavy. It's like reaching into the file tray on my desk and picking out — sized to the job — a persona sheet, a one-line world premise, a page of the rulebook, and a bundle of adjacent text.

5.3.2 One Worked Transcript — K_007's First Emotional Line

Instead of explaining in the abstract, I follow one real request from start to finish. The job: draft three line options for the scene where one recurring character — a scholar-type NPC, internal ID K_007 — has to show emotion for the first time. Starting with the full prompt.

The prompt I sent (Layer A + B (tone) + D + task instruction + output format):

[System]
You are the narrative writer for Project A. No stock RPG phrases like "hero"
or "the chosen one". Follow the tone of the previous lines below. Don't invent
lore you don't know — say "can't judge from this context". You only draft; I decide.

[L0 tone — tone_manifesto excerpt]
The register of this world is restraint. Characters do not speak emotion easily.
Emotion shows as cracks, not outbursts. Ellipses and short sentences.

[Reference — K_007's previous 5 lines (chronological, verbatim)]
1. "...That's the first I'm hearing of it."
2. "Is there a record? If not, we should be skeptical."
3. "Let's not move until we're certain."
4. "That is all I have to say."
5. "...I'm sorry. Was I too cold?"

[Situation]
A fellow NPC has returned wounded. The scholar must show emotion for the first time.

Exactly 3 options, each within 25 characters. End each option with a
(reaction type: anger/sadness/denial) label, and skip explanations and preamble.

(In English, the prompt reads: the system block says — you are the narrative writer for Project A; no stock RPG phrases like "hero" or "the chosen one"; follow the tone of the previous lines below; don't invent lore you don't know — say "can't judge from this context"; you only draft, I decide. The L0 tone excerpt: the register of this world is restraint; characters do not speak emotion easily; emotion shows as cracks, not outbursts; ellipses and short sentences. Then the scholar's five previous lines, verbatim and in chronological order — 1 "...That's the first I'm hearing of it." / 2 "Is there a record? If not, we should be skeptical." / 3 "Let's not move until we're certain." / 4 "That is all I have to say." / 5 "...I'm sorry. Was I too cold?" — the situation: a fellow NPC has returned wounded, and the scholar must show emotion for the first time; and the format: exactly three options, each within 25 characters, each ending with a label (reaction type: anger/sadness/denial), no explanations or preamble.)

Claude's raw output (verbatim — no summarizing, no retouching):

1. "...Why did you carry that alone? Like a fool." (reaction type: sadness)
2. "I should have checked the records. I— I missed it." (reaction type: denial)
3. "It's okay. It's all okay. So stop—" (reaction type: denial)

The point is what happens next — we don't stop here. The writer reads the three options and verifies them. Option 1 — "...왜 그걸 혼자 떠안았어요. 바보같이." ("...Why did you carry that alone? Like a fool." — labeled sadness) — gets the tone right. The crack that previous line 5 opened with "...죄송합니다. 제가 너무 차가웠나요." ("...I'm sorry. Was I too cold?") is carried forward by a single word, "바보같이" ("like a fool"). A candidate for adoption. Option 2 ("기록을 봤어야 했는데. 제가, 제가 놓쳤어요." — "I should have checked the records. I— I missed it.") stammers, and the stammer sits slightly off from the scholar's restraint. On hold. Option 3 ("괜찮아요. 다 괜찮아요. 그러니까 그만—" — "It's okay. It's all okay. So stop—") has the wrong label: repeating "it's okay" is not denial but something closer to avoidance, and our voice_profile has no pattern of this scholar processing emotion through avoidance. Rejected.

The re-request (sent back with the rejection reason stated):

Option 3 rejected. The "it's okay" repetition isn't this scholar's pattern. This character
processes emotion not as avoidance but as 'self-blame over a failed fact-check'. Option 1 is adopted.
In place of options 2 and 3, give me two new options with a different grain from option 1. No stammering, within 25 characters.

(In English: option 3 rejected — the "it's okay" repetition isn't this scholar's pattern; this character processes emotion not as avoidance but as self-blame over a failed fact-check. Option 1 is adopted. In place of options 2 and 3, give me two new options with a different grain from option 1. No stammering, within 25 characters.)

Claude's second output:

2. "Records don't lie. I just didn't look." (reaction type: self-blame)
3. "...Sit down. The wound first. Words later." (reaction type: sadness)

This time both passed. Option 2 — "기록은 거짓말 안 해요. 내가 안 본 거예요." ("Records don't lie. I just didn't look." — labeled self-blame) — reuses the scholar's core vocabulary, "기록" ("records"; see previous line 2, "Is there a record?"), as the vehicle for self-blame. Option 3 — "...앉아요. 상처부터. 말은 나중에." ("...Sit down. The wound first. Words later.") — shows, in restrained imperatives, the scholar's pattern of pressing emotion down into action. The final picks: option 1 plus the new options 2 and 3. These three lines pass the automated voice_lint review from 5.2, get merged into the L2 text, and receive a dialogue_id from L3.

This one transcript holds everything in this chapter. Tone injection (L0) saved option 1; the verbatim adjacent text (L2) let the model pick the scholar's word "기록" back up at the re-request; the enforced output format blocked the chatter; and the writer's rejection gate caught option 3's wrong label. The AI made not a single final decision.

5.3.3 Layer A — The System Prompt: One Line Decides Everything

This is the persona definition laid down on top of everything else. Define it once and almost never change it. The system block in the transcript above is the actual artifact. Of its five lines, the last one ("you draft, the writer decides") matters most. Leave it out and the AI confidently produces sentences that pose as "final," and the writer ends up grading instead of reviewing. The third line ("don't invent lore you don't know — answer that it can't be judged from the context") matters second-most. Without it, the model fills the blanks with plausible lies. In narrative, a plausible lie comes back a few days later as a lore conflict.

5.3.4 Layer B — The L0 Vision and Where the Cache Goes

L0 is small (about 4.5 pages by the count in 5.1). Injecting all of it nearly every time is feasible. Estimated against the Korean text, world_premise.md runs about 2,500 tokens, narrative_pillar.md about 1,500, and tone_manifesto.md about 3,000 — roughly 7,000 tokens combined. (These figures are the author's estimates, unverified. They shift with the tokenizer and with document revisions.)

Sending 7,000 tokens fresh with every request adds up. So I turn on prompt caching. Both Anthropic and OpenAI support it, and on a cache hit the input-token cost drops sharply. The key is to separate, inside the message, what changes from what doesn't.

messages = [
    {"role": "system", "content": SYSTEM_PROMPT},
    {"role": "user", "content": [
        {"type": "text", "text": L0_FULL,      "cache_control": {"type": "ephemeral"}},
        {"type": "text", "text": L1_SELECTED,  "cache_control": {"type": "ephemeral"}},
        {"type": "text", "text": L2_ADJACENT},   # changes every time — not cached
        {"type": "text", "text": TASK_INSTRUCTION},  # changes every time
    ]},
]

L0 and L1, tagged with cache_control, are cache targets; the L2 adjacent text and the task instruction change every time, so they are not cached. Always grouping the cached blocks at the front of the message is what decides the hit rate. If a changing block slips in front, every cache behind it is invalidated. Getting this order wrong is the most common reason caching is on and the bill doesn't go down.

The details on cache hit rates and cost-saving figures are covered in the Part 22 chapter on cost. Here, the one principle to remember is: push what changes to the back.

5.3.5 Layer C — Don't Inject the L1 Rules Whole

The L1 rulebook is big. Put all of it in and the context blows up — and worse, the model loses the point. Pick only the rules relevant to the job, and of those, only the _summary sections.

For main-quest branch outcomes, pick dialogue_branching_rule and faction_relation_matrix. For new NPC dialogue, that NPC's voice_profile and tone_manifesto. For a new lore-dictionary entry, lore_consistency_rule and world_premise. For a side-quest skeleton, quest_template and reputation_model. Selection is done either by hand or by automatic extraction along the wikilink graph (Part 7); when extracting automatically, favor recall over precision. The damage from one missing rule is far greater than the damage from one extra rule.

Instead of injecting the full rulebook text, keep a _summary section at the head of each rulebook file and inject only that.

---
title: Branching rules
layer: L1
---

## _summary
- Branches occur only at chapter ends
- Branches have 2~3 options. 4 or more prohibited
- A branch choice affects reputation by +/-1; an ending branch by +/-3
- Every branch outcome must show its result within 24 hours
- Branches cannot be undone (expose UI recommending a separate save)

## 1. Rules for when branches occur
(detailed explanation, for operators' reference — not injected into the LLM)
...

Five lines of _summary do more for LLM output quality than fifty lines of body text. Models follow short, assertive rules better. Long explanations scatter the model's attention, and scattered attention comes back as rule violations.

5.3.6 Layer D — Never Summarize the Adjacent Text

Previous lines, adjacent quests, the synopsis of the same chapter — this is the most volatile context. For a character's new dialogue, inject that character's previous 10 lines in chronological order; for a mid-chapter quest, the chapter synopsis plus one-line summaries of the other quests in that chapter; for a branch-outcome ending, the full text leading up to the branch plus the choice text. Inject too much and the LLM outputs the average; inject too little and you get generalized output. The workable zone is somewhere between 1,500 and 3,000 tokens (author's observation, unverified).

One core rule: adjacent text goes in verbatim — never processed, never summarized. In the transcript above, the scholar's five previous lines went in untouched, and that is exactly why the model, at the re-request stage, could pick out the precise word "기록" ("records") and reuse it as the vehicle for self-blame. Had those five lines been summarized as "the scholar is cautious and cold," every one of the writer's fine-grained choices would have vanished, and the model would have drifted back to the average. Summarizing doesn't reduce information; it erases decisions the writer has already made.

5.3.7 The Writer Review Workflow — Using the Discard Rate as a Metric

AI output is always a draft. Review passes through a fixed gate.

flowchart TD
    A[N AI outputs] --> B[Pass 1: voice_lint, automated
5.2]
    B --> C[Pass 2: one writer selects and edits
about 15 min]
    C --> D{Any option adopted?}
    D -->|yes| E[Pass 3: narrative lead sign-off
when needed]
    D -->|0 adopted = all discarded| F[Re-request or write by hand]
    E --> G[Merged into L2 text
+ L3 dialogue_id issued]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    class B code;
    class A ai;
    class C,D,E human;
    class G pass;
    class F fail;

It is also normal for the writer to pick zero out of N — to discard everything. As option 3 was rejected in the transcript above, a rejection is not a failure; it is proof the gate worked. So I measure the discard rate per writer and per character, and use it as the metric for context-injection quality.

A discard rate of 0–20% means stable operation with sufficient context — leave it alone. 20–50% is the normal operating range — just monitor. If it climbs to 50–80%, recheck whether an L1 rule was left out of the selection. Past 80%, the problem is not any individual rule but the system prompt and persona themselves being off — rewrite Layer A. The discard rate is tallied per writer once a week and shared in the retrospective.

That said, the discard rate is not an absolute metric. A character changing fast (say, at a turning point like K_007's first show of emotion in the transcript above) can run a high discard rate and still be healthy. The number is the start of a conversation, not a verdict.

5.3.8 Security — How to Stop Context Leaks

L0 and L1 are the game's core IP. If sending them as is to an external LLM API feels uncomfortable, the options diverge. Using an external API as is, under a no-training agreement, is fastest but needs legal review. Swapping company names and proper nouns for placeholders before sending adds processing cost and damages naturalness. Self-hosting an open model keeps the data safe but carries a heavy quality and operations burden. A hybrid — keep L0 in-house and send only drafts outside — is complex to operate.

My Project A uses the first option (external API plus a no-training agreement). We tried the second and dropped it: placeholder substitution flattened the text into the shape of "the ○○ scholar of the ○○ kingdom spoke about ○○" and wrecked output quality. Anonymization killing quality is a trade-off that recurs throughout this book (see the anonymization chapter in Part 1). In narrative the damage is especially severe, because proper nouns are the tone.

5.3.9 Common Failures and Their Fixes

Throw a task instruction with no system prompt and you get the average. Lay down the persona and the prohibitions first. Inject all of L0 every time without caching and the cost bleeds. Group the cache blocks at the front. Stuff the whole L1 rulebook in and the model loses the point. Extract only the _summary sections. Summarize the adjacent text and the writer's choices get erased. Quote the originals verbatim. Skip the output format and a good share of responses open with "Here are three candidates:" — followed eventually by the incident where a writer mistakes that preamble for actual copy. Specify count, length, labels. Use AI output as final and the review gate collapses. Always pass it through the writer gate. Don't measure the discard rate and the tool's health depends on people's impressions. Tally it weekly and share it in the retrospective.

5.3.10 From Conservative to Progressive Application

Everything so far has been the conservative application: the writer injects context with care, and the AI only drafts, line by line. The unit of work is small — "three options for this character's next line," "a synopsis for this quest." It is stable, but it has limits in production scale and dynamic responsiveness.

One thing is worth marking first. Procedural generation, world simulation, and dynamic quests are visions game designers have been sketching on paper for the last 20–30 years. Deterministic, rulebook-driven PCG handled the numeric territory — dungeon rooms, weapon options, spawn distributions — but never reached natural-language text, character personas, narrative branching, or NPC dialogue. A large share of design stayed on paper. The advances in LLMs and image models from 2024 to 2026 pulled that territory into implementable range. The core meaning of AI progress is not model scores; it is that designs long stuck on paper became feasible. That said, a possibility opening up and a system settling into something operable are different problems.

Layer Decomposition Was the Precondition for Procedural Generation

The Layer 0–4 decomposition in 5.1 was not mere tidying; it was the precondition for procedural generation. Which stage of the generation pipeline each of the five layers maps to (L0 anchor → L1 rulebook → L2 text → L3 numbers → L4 gate) was covered in §6.6 and 5.1.11. The point is single: on top of one monolithic document, a generator cannot decide where to start reading or where to write; not knowing where L0 sits, its context blurs; L1 and L2 collide inside one file and the production line collapses. Layer decomposition comes first, and procedural generation runs on top of it. Here, that precondition is applied to the mass-production stage of narrative AI assistance.

The Skeleton of the Progressive Application — The Quest Cloud

Three elements come together. First, NPC Personas are procedurally generated. Main NPCs stay in the writer's hands, but side NPCs are mass-produced by the generator and Squad pipeline from 6.2–6.3. Each Persona carries a voice_profile plus tags (occupation, faction, disposition, role). Second, the world BT sits above Squad. Where a Squad bundles the behavior of one hunting ground's NPC group, the world BT sits above it, takes accumulated player-action metrics, and updates the state of the world as a whole. Which factions the player helped, which regions they frequented, which decisions they made — these shake the world BT's node states, and the shaken nodes propagate into the stats (reputation, interests, priorities) of the NPCs in their sphere of influence. Third, quests follow a cloud model. Every quest except the main quest is procedurally generated and floats free, each carrying tags (who, where, why, when) and manifestation conditions. No quest is pinned to a specific NPC.

Manifestation passes through five stages.

flowchart TD
    P[1. Player actions accumulate
faction support · region visits · decisions] --> W[2. World BT node states change
world state updated above Squad]
    W --> N[3. NPC stats change
reputation · interests · priorities]
    N --> M[4. NPC tags + stats == manifestation conditions
matching key generated]
    M --> Q[5. Matching quest manifests
from the quest cloud]
    Q -.->|shown after passing the writer gate| PL[Appears to the player]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class M code;
    class P,W,N,Q data;
    class PL pass;

As a metaphor: quests are not books shelved in a library but clouds drifting overhead. When an NPC reaches a certain state, the cloud that fits it descends within reach. In this structure the AI is no longer an assistant writing one line; it handles three things at once — the natural-language text (descriptions, dialogue) of the procedurally generated Personas and quests; the vocabulary shifts when world BT state lands on an NPC (the same voice_profile holds, but the topics move with the world state); and the suspicion classifier at the verification stage (should this quest be allowed to manifest on this NPC?).

The Irreversibility Boundary — Review Must End at the Text Stage

Even in the progressive application, the reversible/irreversible boundary (5.4.5) stays fully alive. If a cloud-manifested quest's dialogue flows into the voice pipeline without passing review, no code rollback can bring it back. So the safety mechanism of the progressive application is placing every review gate (voice_lint, the suspicion classifier, the writer gate) in front of the irreversibility boundary. With automated mass production added on, these gates have to be harder than in the conservative application.

Where to Stop, and Why Not to Stop

This book does not cover the finished form of the progressive application. That is a book of its own, and the infrastructure assumptions differ by company and project. Only two things need remembering. First, a team that can't run the conservative application can't run the progressive one either. If the review gate doesn't turn in the conservative application, the cloud runs away in the progressive one. For the operation to survive, five things must be in place together: procedural generation infrastructure; tooling to define and test world BT nodes; automatic suspicion classification of manifested quests plus the writer gate; simultaneous tracking of manifestation rate, discard rate, and player satisfaction; and automatic recall and replacement of wrongly manifested quests. Drop any one of the five and the system gets scrapped within a quarter — consistency incidents explode past what human review can keep up with.

Second, the progressive application is not a tool for scaling up mass production; it is a tool for scaling up dynamic responsiveness. Aim only at volume and the cloud fills up with generic-RPG average, and players meet a world that "looks more varied but is more empty." That doesn't make this road purely dangerous, either. This territory is the front line of game design R&D. The spot where procedural generation, simulation, and LLMs meet is where a genuinely new game form is most likely to appear. Few companies will adopt it tomorrow, but it is worth keeping in view as one direction for the next 5–10 years.

5.3.11 Try It Yourself: One Chapter End to End

Here is the procedure for reproducing this chapter's conservative application as is.

setup. Merge the three L0 files (world_premise.md, narrative_pillar.md, tone_manifesto.md) into one text and put it in an L0_FULL variable. Write the system prompt exactly as the five lines in the transcript above, and do not drop the last line ("you draft, the writer decides"). Collect the previous 10 lines of the character you're drafting for, verbatim, as plain text.

prompt. Assemble the message in the order [시스템] → [L0 톤] → [참고: 직전 대사 원본] → [상황] → [출력 형식] (system → L0 tone → reference: previous lines verbatim → situation → output format). In the output format, always state "exactly N options / max length per option / labels / nothing else." Put cache_control on L0 and L1 only, and push the changing blocks to the back of the message.

verify. Verify the N options you receive, line by line. Check that the tone continues from the previous lines, that the labels match the actual reactions, and that no pattern your character never uses (avoidance, stammering, and so on) has crept in. For options you reject, state the reason and re-request. Adopting zero is normal; record it in the discard rate. Only options that pass go through voice_lint, get merged into L2, and receive a dialogue_id from L3.

Solo Scale-Down. Without an API, caching, or voice_lint, the core still holds. One ChatGPT or Claude chat window is enough. Paste the character's previous 5–10 lines at the very top every time, always attach the three lines of output format, and for any answer you reject, write down the reason and re-request. Instead of caching, keep the same conversation thread and the earlier context stays in place. For the discard rate, a sheet of paper with a hand tally like "adopted 12 / out of 30 this week" is plenty. The tools are smaller, but the skeleton — four-layer injection and a review gate — works the same for a solo writer.

Key Takeaways

• Drop even one of the four context layers (system, L0, L1, adjacent text) and the output converges to the average
• Caching lives or dies on separation: group the unchanging L0 and L1 at the front and push the changing text to the back
• Only when the review gate and the discard rate are working does the progressive application (the quest cloud) stay out of runaway

Next Chapter Preview

• 5.4. Dialogue and Voice Consistency — extracting and updating voice_profile with AI, and putting the voice through review

5.4 Dialogue and Voice Consistency

A recording booth. The director, headphones on, raises a hand to give the cue. The voice actor reads a line for a scholar NPC: "와, 진짜 대박이네요" — "Wow, that's seriously awesome." The director's hand freezes. This is a character who has not used the interjection "wow" once across 5 chapters — a scholar who never utters profanity or modern slang, who trails off at the end of his sentences rather than finishing them. And yet there the line sits, right in the script.

Two costs land at the same time here. First, if the line gets fixed, the actor has to read it again — and the session fee and the studio clock are already running. Second, and scarier, is the case where the director fails to catch the line at all. Once the recording wraps and the audio goes into the build, that scholar talks that way in the game forever. Recorded audio cannot be rolled back with a one-line edit the way text can. You would need the same actor, in the same condition, in the same booth, all over again.

This chapter is about the dotted line in front of that booth. Above the line everything is text, revisable without limit; below the line everything is audio, beyond fixing. Every dialogue review must finish above that line. For that to happen, "this is how this person talks" has to be recorded in a file rather than in someone's head, and every new batch of dialogue has to be checked against that file automatically. I call the file voice_profile, and the checking tool voice_lint.

5.4.1 Where the Voice Starts to Drift

Of all narrative-consistency incidents, character voice drift blows up the most often. Only after launch do the reports arrive: "why did this NPC suddenly change the way they talk?" The cause is nearly the same every time.

When the writer changes, the same NPC becomes a different person. Even when the writer stays, six months later they forget their own tone. Writing new lines without opening the character's previous lines breaks the context. If the voice rules live only in the writer's head and never in a document, they don't transfer to the next person. And then the fifth cause — the one that has grown fastest over the past two years: throw "write some lines for this NPC" at an LLM with no character information, and the AI returns dialogue that is average, inoffensive, and therefore nobody's voice.

That fifth cause is the side effect of adopting AI. Context injection from the previous chapter (5.3) is the prescription, but if the context you inject is thin, there is nothing to inject. That context is the voice_profile. This chapter walks one full cycle: build the file, check new dialogue against it automatically, and close everything out before the recording booth.

5.4.2 voice_profile — A Voice Pinned Down in Five Fields

On Project A, every NPC has a voice_profile with five fields: vocabulary range (word groups used often / word groups never used), sentence length (average and maximum character count), forms of address (first and second person, ratio of honorific — formal — speech, titles), emotional expression (direct, indirect, or suppressed), and taboo expressions (words and phrasings never used). All five fields must carry concrete examples. An abstract description like "a grave scholar" alone gets read differently by everyone. The next writer will imagine that scholar their own way.

Here is the actual profile format for the scholar NPC K_007. This file is, directly, the input to voice_lint.

---
title: K_007 Scholar voice_profile
layer: L1
character_id: K_007
atoms:
  - voice_profile_k_007
related:
  derives_from: [character_bible/k_007.md]
  affects: [dialogue_id_table (all K_007 dialogue)]
---

## 1. Vocabulary
- Frequent: "record", "evidence", "circumstances", "inference", "data", "case"
- Never: "feeling", "gut sense", "fate", "God's will", "the heart's voice"

## 2. Sentence Length
- Average: 18 characters
- Maximum: 35 characters (anything longer splits into two sentences)
- Frequent short cutoffs: "...No." "The records first."

## 3. Forms of Address
- First person: the humble "저"
- Second person: title first ("Captain", "Commander"). Name only after closeness.
- Honorific speech 100% (except flashback scenes)
- Interjections almost never. When present: "...ah."

## 4. Emotional Expression
- Almost no direct expression (anger, joy)
- Expressed through silence and trailing off ("...if that is how it is going to be.")
- Grief: dodged by changing the subject ("...let's talk about something else.")

## 5. Taboo Expressions
- All profanity
- Modern interjections "wow", "whoa", "awesome"
- Two or more Sino-Korean terms of 3+ syllables in a single sentence
- Mysticism vocabulary such as "fate" and "prophecy"

(In English, the profile reads: 1. Vocabulary — frequent: "record," "evidence," "circumstances," "inference," "data," "case"; never: "feeling," "gut sense," "fate," "God's will," "the heart's voice." 2. Sentence length — average 18 characters, maximum 35 (anything longer splits into two sentences); frequent short cutoffs like "...No." "The records first." 3. Forms of address — first person: the humble "저"; second person: title first ("Captain," "Commander"), name only after closeness; honorific speech 100% (except flashbacks); interjections almost never, and when present, only "...ah." 4. Emotional expression — almost no direct expression of anger or joy; shown through silence and trailing off ("...if that is how it is going to be."); grief dodged by changing the subject ("...let's talk about something else."). 5. Taboos — all profanity; the modern interjections 와/헐/대박 ("wow"/"whoa"/"awesome"); two or more long Sino-Korean terms in a single sentence; mysticism vocabulary such as "fate" and "prophecy.")

The heart of this format is that every abstract slot has an example line attached. Not "suppresses emotion" but the actual line "...그런 식이라면." — "...if that is how it is going to be." That is what lets the next writer, the translator, and voice_lint all look at the same standard. Viewed again through the eyes of translation and localization, the five fields split into two kinds. Language-dependent properties (vocabulary range, sentence length, the surface forms of the address system) must be re-specified for every target language; language-independent properties (whether the character suppresses emotion or expresses it directly, what they refuse to say to the very end — attitude) must hold no matter which language the lines move into. Hand this distinction over along with the localization assignment, and you stop a translator from shaking the character's attitude while swapping out surface vocabulary.

5.4.3 The Worked Transcript: Drawing the Profile from the Lines

Writing 50 NPCs × 5 fields = 250 entries from a blank page drifts into abstraction. With not one actual line on the page, "this character is a cold scholar" tells nobody what that coldness is. So the order is flipped: only the 5–7 main NPCs get full profiles from the start; everyone else waits until 20–30 lines of dialogue have accumulated, and the profile is reverse-extracted from those lines.

Below is the actual worked transcript of pulling a profile draft after 25 lines of K_007 dialogue had piled up. Nothing is summarized, and the spots where the AI got things wrong are left in.

[The writer's prompt, in full]

The following are 25 lines of dialogue for character K_007.

1. "Let's start with the records."
2. "...The circumstances don't line up."
3. "It's only an inference. There's no evidence."
4. "I know that case as well."
5. "...No. The data says otherwise."
   (... lines 6~23 quoted in full, no omissions ...)
24. "...If that is how it is going to be, I will step out."
25. "Let's talk about something else."

From these, pull five things: frequently used vocabulary (only what actually appears),
average sentence length, honorific and address patterns, the mode of emotional
expression, and expression ranges never used once. For each item, cite 2~3 numbered
lines as evidence, and do not use subjective impressions like "grave" or "cold".

(The prompt lists K_007's 25 lines in full — "Let's start with the records." / "...The circumstances don't line up." / "It's only an inference. There's no evidence." / "...If that is how it is going to be, I will step out." / "Let's talk about something else." — then asks for five things: frequently used vocabulary (only what actually appears), average sentence length, honorific and address patterns, the mode of emotional expression, and expression ranges that never appear. Each item must cite 2–3 numbered lines as evidence, and subjective impressions like "grave" or "cold" are banned.)

[Claude's raw output — not cleaned up]

1. Frequently used vocabulary
   - "record" (line 1), "circumstances" (line 2), "inference/evidence" (line 3),
     "case" (line 4), "data" (line 5)
   → Concentrated on fact-and-evidence nouns.

2. Average sentence length
   - About 14.6 characters across the 25 lines. Longest 21 characters (line 24).
   → Mostly short declaratives.

3. Honorifics and address
   - First person "저" (lines 3, 24). Polite "-습니다/-요" sentence endings.
   - No second-person address appears in these 25 lines.
     → The address pattern cannot be determined from this sample alone. (Writer confirmation needed)

4. Emotional expression
   - No direct emotion words. Refusal handled as "I will step out" (24),
     grief/avoidance handled as the subject change "Let's talk about something else" (25).
   → Suppressed, indirect type.

5. Ranges never used once
   - Interjections, profanity, and mysticism vocabulary: all unobserved.
   ※ But "unobserved" is no guarantee of "taboo".
      The sample is small at 25 lines; the absence may be coincidental.

(The output, in English: 1. frequent vocabulary concentrates on fact-and-evidence nouns — "record," "circumstances," "inference/evidence," "case," "data" — each cited by line number; 2. average length about 14.6 characters across the 25 lines, longest 21 (line 24) — short declaratives; 3. first person "저" with polite "-습니다/-요" endings, but no second-person address appears in these 25 lines — "the address pattern cannot be determined from this sample alone (writer confirmation needed)"; 4. no direct emotion words — refusal handled as "I will step out" (24), grief/avoidance as the subject change "Let's talk about something else" (25) — suppressed and indirect; 5. interjections, profanity, and mysticism vocabulary all unobserved — with the caveat that "unobserved" is no guarantee of "taboo," since 25 lines is a small sample and the absence may be coincidental.)

Two things deserve a close look here. First, the AI stopped at item 3. It drew its own limit — "cannot be determined from this sample alone." No second-person address appeared in the 25 lines, so it refused to infer one. That is honest output. Had the AI filled in "second person: presumably 'Captain,'" that would be a hallucination, and once inside the profile, contamination. Second, in item 5 the AI attached its own disclaimer. "Unobserved ≠ taboo" is the key warning. The absence of interjections in 25 lines may be pure chance.

[The writer's verification and veto]

The writer adopted items 1, 2, and 4. For item 3, the address pattern, the writer opened the character_bible and filled in "title first ('Captain'), name only after closeness" by hand — a human fills the slot the AI left empty. For item 5, exactly as the AI warned, the writer did not promote "unobserved" straight to "taboo." Instead, checking against the character's design, the writer confirmed only "modern interjections, profanity, mysticism" as taboo and put the rest of the unobserved vocabulary on hold.

[The writer's follow-up request]

I'm confirming "fate" and "prophecy" as taboo. Pull 10 more mysticism words with overlapping meanings.
But since K_007, as a scholar, might quote them in a rebuttal or critique context,
mark that exception case in one line as well.

(The follow-up: "I'm confirming 'fate' and 'prophecy' as taboo. Pull 10 more mysticism words with overlapping meanings. But since K_007, as a scholar, might quote them in a rebuttal or critique context, mark that exception case in one line as well.")

This last follow-up is the important one. Broaden a taboo mechanically and you also block legitimate lines — the scholar deriding superstition with "fate, of all things." So the exception context is defined together with the taboo. The AI widens the candidates; the writer draws the boundary. Only after this full loop does voice_profile_k_007 get confirmed and pinned at L1.

Forcing evidence citations ("cite by line number") and banning subjective adjectives ("no 'grave'") cuts AI hallucination and gives the writer a surface to verify. The profile is not something the AI writes — the AI lays down a draft, and the writer pins it.

5.4.4 voice_lint — Automatic Checks on Every New Line

Once the voice_profile exists as a file, every new batch of dialogue can be checked against it automatically. Of the five possible checks, the two that earn their keep in practice are taboo vocabulary matching (does a word hit the taboo list?) and vocabulary range violation (does it fall into the never-used word group?). Sentence-length deviation, missing honorifics, and frequent-vocabulary ratio throw too many false positives, so they run only as auxiliary checks. Flag every flashback line that bends the average length, and the writer goes numb to warnings.

voice_lint takes a chapter's batch of new lines and produces a report like this.

voice_lint result (ch04 new dialogue: 32 lines, profile=voice_profile_k_007)
─────────────────────────────────────────────
[VIOLATION] dialogue_id_412 — K_007
  Content: "Wow, that's seriously awesome!"
  Reason: taboo words "wow", "awesome" (profile §5)
  → Writer review required

[SUSPECT] dialogue_id_421 — K_007
  Content: "That fate is hard to accept."
  Reason: taboo word area "fate" (profile §5)
        But the 'rebuttal/critique context' exception may apply — writer's call
  → Writer review required

[CLEAN] 30 lines
─────────────────────────────────────────────
Summary: 1 violation / 1 suspect / 30 clean

(The report covers 32 new lines in ch04 against voice_profile_k_007. One violation — dialogue_id_412, "Wow, that's seriously awesome!", taboo words 와 and 대박 (profile §5), writer review required. One suspect — dialogue_id_421, "That fate is hard to accept.", touching the taboo word area "fate" (profile §5) but possibly covered by the rebuttal/critique exception — writer's call, writer review required. 30 lines clean. Summary: 1 violation / 1 suspect / 30 clean.)

Violations are red, suspects are yellow. Both must pass the writer's judgment to get through. And one absolute principle applies here — voice_lint never rejects automatically (an extension of the 5.2 principle). Look at dialogue_id_421 above. "Fate" is taboo, but if the scholar is rebutting a superstition, it can be a legitimate quotation. A tool cannot make that call. An auto-rejecting lint walls off every one of these delicate spots — and robs the writer of the chance to refine the tone on top of it. Lint is a flashlight that marks the suspect spots, not a lock on the door.

5.4.5 Review Gates — The Dotted Line Between Reversible and Irreversible

The spine of this chapter is this single diagram. As one line of dialogue travels from the writer's hands to the actor's mouth, review gates are laid at every stage. And through the middle of that flow runs a thick dotted line.

flowchart TD
    A["Writer drafts lines (L2)"] --> B["voice_lint automatic
violation/suspect report"]
    B --> C["Writer self-review (15 min)"]
    C --> D["Narrative lead sample review
10% sample per chapter"]
    D --> E["L3 dialogue_id issued
+ translation key mapping"]
    E --> F["Translation/localization review"]

    F -.->|"━━━ Reversible / irreversible boundary ━━━
Above this line: text, endlessly revisable
Below this line: audio, no revisions"| G

    G["VA casting"] --> H["Dubbing session (final, irreversible)"]
    H --> I["Audio into build"]

    classDef reversible fill:#e8f4ea,stroke:#3a7d44,stroke-width:1px,color:#1b3a22;
    classDef irreversible fill:#f7e3e3,stroke:#b23b3b,stroke-width:2px,color:#5a1414;
    class A,B,C,D,E,F reversible;
    class G,H,I irreversible;

Green marks the reversible stages, red the irreversible ones. Everything above the dotted line (green) is text. If a line bothers you, fix it at the keyboard; the cost is a few minutes of the writer's time. Below the line (red) is audio. The moment the actor reads that line in the booth and the audio enters the build, the line is frozen as an asset. To change it you must rebook the same actor, the same condition, the same studio — and the session fee, the studio, and the director's time all cost exactly what they did the first time. On a tight schedule, an additional session with the same actor often cannot be booked at all.

So a single rule governs the entire workflow — every review gate finishes above the dotted line. Recording is not a review stage. It is the stage that freezes fully reviewed output into an asset. If a "this line sounds off" doubt surfaces below the line, that is not a place to review further — it is a signal that an upstream review was skipped. The flashlight must sweep everything above the line. The booth is not a place that is allowed to be dark; it is a place that must not be.

In the middle of the diagram, the lead's sample review is pegged at a "10% sample per chapter." That ratio is the balance point between review time and accuracy (the author's operating figure — an unverified estimate). Drop below 5% and incidents start leaking; push above 20% and one lead becomes the bottleneck. Because lint has already filtered out violations and suspects, the sample is drawn from the lines that passed lint — human eyes concentrate on the context errors a tool cannot catch (for example, a "fate" quotation that looks legitimate but is in fact the character breaking).

5.4.6 Characters Change — Version Control for the Profile

A character who talks the same way to the very end stalls the plot. A scholar who has lived through a comrade's death and still speaks in exactly the pre-loss tone reads as fake. When the change is intended, the voice_profile versions up along with it.

---
character_id: K_007
voice_profile_versions:
  - v1: ch01~ch05 (early — suppressed emotion, short-sentence scholar)
  - v2: ch06~ch10 (after a comrade's death — emotional expression more frequent)
  - v3: ch11~ (after the awakening — direct speech appears)
---

(The versions: v1, ch01–ch05 — the early suppressed-emotion, short-sentence scholar; v2, ch06–ch10 — emotional expression grows more frequent after a comrade's death; v3, from ch11 — direct speech appears after the awakening.)

Each version is a separate profile file, and voice_lint reads the chapter number of the dialogue under inspection to choose which version to apply. Hold ch07 dialogue up against v1's "suppressed emotion" rule and every perfectly sound change line lights up as a suspect. Change is not a bug; it is design.

Three signals raise a version. When the writer shakes the tone deliberately, they propose a new version and align with the lead. When voice_lint's suspect count keeps climbing for one character, the writer is shifting the tone without noticing — a signal that the version update is due. When a change event (death, awakening, betrayal) is added to the character_bible, a profile-update alert fires. That said, a character who changes every chapter loses coherence, so a realistic count is 2–4 versions per character.

[Directional signpost — reading the space between characters as a voice space (still premature)] Where voice_lint uses rules to protect consistency within one character, a "voice space" — embedding each character's full set of spoken lines as a single point — looks at whether the distance between characters stays wide enough. If the points drift into a cluster, that is a direct measurement of the voice flattening and convergence that §5.3.1 and §5.4.1 pointed to. But do not fix the distance threshold as an absolute number; read it only as a directional signpost that says "clustering is underway," and it is not a verdict gate that replaces voice_lint (the idea sits in the same spot as the dimensional-vector compression of §8.2.7, and the conceptual intuition is laid out as a single map in Appendix M — a signpost, not a prescription).

5.4.7 Consistency Units That Multiply with Localization and VA

Once dialogue is translated into multiple languages and voiced by actors, the units under management multiply. One Korean line splits into English and Southeast Asian languages, and each of those carries its own tone.

The most frequent leak in translation consistency is the same expression being translated differently from chapter to chapter (caught by a translation-memory consistency check). After that come the character's voice_profile not being reflected in the translation (fix: attach a per-character translation guide) and new vocabulary missing from the glossary (fix: a glossary lint). The translation guide is generated automatically from the voice_profile — "this character: 100% formal speech, no interjections, mysticism vocabulary taboo" is stamped onto the head of the translation brief. The translator carrying that scholar into English sees the same boundaries.

VA (voice actor) review is the review at the last text-reversible stage, just before the work touches what lies below the dotted line. Tone consistency (the intensity of anger and grief) is checked by the director and narrative; pronunciation accuracy (proper nouns) by the glossary owner; breathing and breaks (profile instructions like "frequent short cutoffs") by the director. Results are logged pass/reject in voice_review_log.md (L4) and consulted at the next character's casting.

Rejections are settled, wherever possible, before casting and recording. A script error discovered inside the booth collapses that day's session outright and shakes the schedule of the next one. That does not make dragging out review while postponing the recording the answer, either. If reviews keep jamming right in front of the booth, the upstream workflow (writer, lead) is what is running late — not the recording schedule.

5.4.8 Six Months of Measurement and Cost

On Project A, I tracked six months before and after introducing voice_profile + voice_lint. The absolute counts are the author's estimates (unverified); trust only the direction and the ratios.

The most meaningful row is NPCs managed per writer. "About 2.5x" does not mean writers were cut; it means the same writer can carry more NPC variety per chapter. The world gets more crowded.

Looking at the cost structure, operating cost is far smaller than adoption cost. Writing the voice_profiles took the writer 2 weeks for the 7 mains; the voice_lint tool took 1–2 weeks of development and 1 day a month of maintenance. On the operating side: 15 minutes of writer self-review per chapter, about 2 hours of lead sample review (the 10% sample), and 1–2 days per character for profile updates in change chapters. Operating cost has to stay small for a system to survive. A tool that is heavy to operate gets quietly retired within a quarter.

5.4.9 Common Failures

Try It Yourself — One voice_lint Cycle

This is the minimum procedure for one full pass with a single profile when a new chapter's dialogue comes in.

setup 1. Open the target character's voice_profile_<id>.md. If it doesn't exist, gather 20–30 of the character's existing lines. 2. Prepare the new lines as a plain-text batch in id / 캐릭터 / 내용 (id / character / content) format.

prompt

This is §5 (taboo expressions) of K_007's voice_profile.
[paste the taboo list]

32 new lines of ch04 dialogue.
[paste in id / content format]

Classify each line as [VIOLATION] (directly contains a taboo word) / [SUSPECT] (touches a
taboo area, but an exception context is possible) / [CLEAN]. Table the violations and
suspects with id, content, and reason. I make the call, so don't reject anything automatically.

(The prompt pastes the §5 taboo list from K_007's voice_profile and ch04's 32 new lines, then asks the AI to classify each line as [위반] violation (directly contains a taboo word) / [의심] suspect (touches a taboo area, but an exception context is possible) / [정상] clean — violations and suspects tabled with id, content, and reason — and ends with "I make the call, so don't reject anything automatically.")

verify 1. Look at the violations ([위반]) first. If one is clear-cut, fix the text (it is above the dotted line, so it's free). 2. Judge the suspects ([의심]) by context. A legitimate quotation passes; anything else gets fixed. 3. Send 10% of the passing lines to your lead as a sample to filter context errors once more. 4. Only after every judgment is in, issue dialogue_ids and push to the recording queue. No further checking in front of the booth.

Solo Scale-Down — If you're a solo developer who can't build the tool, write only one field of the voice_profile per character: §5 (taboo expressions). Every time you write new lines, paste that taboo list at the head of your prompt and tell the AI, "flag only the lines that hit this list." No tool, one line of prompt, and you get 80% of what lint gives you. Run this single pass before handing off to recording (or TTS), and the dotted line in front of the booth holds.

Key Takeaways

• Of the five causes of voice drift, AI flattening has grown the fastest, and the prescription is not flimsy context but a voice_profile loaded with examples.
• voice_lint only flags violations and suspects — rejection belongs to a human — and every taboo is defined together with its exception context.
• All review ends above the dotted line in front of the recording booth — audio below the line cannot be rolled back the way text can.

Next Chapter Preview

• 6.1. Procedural Content Generation and AI — Where They Meet

Part 6 · Content Design

6.1 Procedural Content Generation and AI — The One Cell Where the Two Axes Cross

Monday morning, design meeting. A single line on the whiteboard: "1,000 side quests by launch." Someone starts tapping a calculator. One writer spending a day per quest: four years. Put five writers on it and it is still close to a year. The air in the room goes heavy. I have been sitting in this room for 24 years, and I know that in front of that number, people always split into the same two camps. One side says "cut the volume"; the other says "stamp them out with tools." And almost always, the decision was both.

Procedural content generation (PCG) is the old answer on the "stamp them out with tools" side. Dungeon room layouts, weapon option combinations, and enemy spawn pools have been automated with rulebooks and probability tables for twenty years. What is new is not PCG itself — it is that large language models (LLMs) and generative models have taken the seats where natural language, images, and narrative go.

But what this book wants to say is not "attach AI to PCG." Everyone does that. The question is where you attach it. Take one piece of content: unless you pin down, in a single cell, which intensity of automation and which layer of structure it meets at, you end up with a tool that has no seat. This chapter shows how to draw that cell as a coordinate, and what it looks like when one piece of content actually makes a full lap around the pipeline on that cell.

6.1.1 Where PCG Stood Still

Traditional PCG is strong at determinism. The same input produces the same output, and you can verify it. That is why dungeon room graphs, weapon option prefixes and suffixes, and enemy spawn distributions settled in early. "Flaming Sword +5" was coming out automatically twenty years ago.

The problem was always the seat right next to it. The rooms got placed, but the names, looks, and short backstories of the NPCs inside them stayed in writers' hands. "Flaming Sword +5" came out, but the one-line hook — "the last sword the king lost" — did not. A quest generator could draw combinations of objectives and rewards, but "why am I doing this quest" was still written by a person.

On large games, this seat was always the bottleneck. The ratio of mass-producible work to work that needed human hands was roughly 4 to 6, and that 6 ate most of the schedule. Even when the production line cranked out the 4 quickly, if the 6 could not keep up, the whole cycle was capped at that speed.

That is exactly where LLMs and image models come in. The mass-producible range extends into the natural-language, narrative, and visual territory that rulebooks could never handle. That does not mean handing the seat over to AI wholesale. AI gives a slightly different answer every time, and when the context is empty, it spits out the generic-RPG average. So you need to design the junction point. And the junction point is defined by two coordinate axes.

6.1.2 The First Axis: Automation Intensity (L0–L3)

The vertical axis is the ratio in which you mix humans, rulebooks, and AI. At the MMORPG studio where I work (hereafter "Project A"), we cut it into four levels.

L0 — fully handcrafted. Every word and every decision comes from human hands. Main quest text, signature character dialogue, branching endings. The seats where consistency and narrative depth tie directly into the game's identity.

L1 — rulebook automation. Traditional PCG's seat. Deterministic algorithms — rulebooks, probability tables, BSP (binary space partitioning) — produce the output, and humans only review it. Dungeon room layout, weapon option combinations, and enemy spawns are the representatives.

L2 — rulebook + AI assist. The rulebook sets the skeleton and AI fills in the details. Side quest synopses, common-NPC names and short backstories, hunting-ground blurbs. Humans are responsible only for the input metadata and the final review gate.

L3 — AI first + human review. AI writes the body and humans step in only to review. Attractive, but non-determinism, hallucination, and the risk of consistency damage all gather here.

The key is L2. It combines L1's stability with L3's production power, and blocks the weaknesses of both with a verification gate — a quality gate where a human or an automated checker verifies the output before it moves on. L3 is the level everyone is tempted to adopt early, but I have watched it get scrapped within a quarter or two, more than once, as the review load explodes. When 70 out of 100 items come back flagged as suspect, it costs more than having a person write all 100 from scratch.

6.1.3 The Second Axis: Layer Structure (L0–L4)

The vertical axis alone will not make a production line run. The content itself has to be decomposed into layers before automation has a seat to take. This is the Layer decomposition covered in Part 5, and in the content domain it is the horizontal axis. The general explanation — that the five layers each correspond to one role in procedural generation (anchor, rulebook, body, numbers, gate) — was covered in §2.3.6; here I plug it straight into the content production line. Layer 0 vision is the tone and worldview anchor (injected on every generation); Layer 1 systems is the generation rulebook (rules, probability tables, tag taxonomy); Layer 2 content is the body where generated output accumulates (side quests, NPC backstories, city blurbs); Layer 3 data is numbers, IDs, and relations (rewards, spawns, curves); and Layer 4 build/QA is the verification gate (lint, consistency checks, writer review).

These two axes tell different stories. The vertical axis says "how much do humans touch this"; the horizontal axis says "which part of the content is this." But they only carry meaning as a product. Only when you pin a piece of content to the intersection of the two axes — to one cell — does "who makes this, which part, and how" actually get decided.

6.1.4 The Two Axes on One Page — The Automation × Layer Matrix

Now I overlay the two axes I have been describing in prose onto a single grid. Horizontal: the content's Layer. Vertical: automation intensity. The label in each cell is the content that actually occupies that cell on Project A. The darker the cell, the closer it sits to the production line's center of gravity.

This grid is the heart of this chapter. Judgments that used to be scattered through prose — "main quests are L0," "side quests are L2," "rewards belong to the rulebook" — converge into one coordinate. When a new piece of content comes up in a meeting, one question is enough: "which cell is this?" Once the cell is fixed, its vertical coordinate tells you who touches it, and its horizontal coordinate tells you which part it is.

Read the grid for a while and two things stand out. First, the center of gravity (the dark cell) sits at the L2 row × Layer 2 column. Side quest skeletons and NPC backstories live there. That is the heart of the production line. Second, a piece of content does not live in only one cell. A side quest's body (Layer 2) sits in the L2 cell, but its reward values (Layer 3) drop down to the L1 cell. Even within the same quest, different parts live in different cells. That is why the two axes are kept separate.

6.1.5 A Mini Pipeline Running on a Single Cell

Now watch one piece of content make an actual lap on the center-of-gravity cell — L2 row × Layer 2 column, the side quest skeleton. The flow looks like this.

flowchart TD
    A["Layer 0 vision injection
(tone anchor: East Asian rural village)"] --> B["Layer 1 rulebook
(generates objective/reward slot skeleton)"]
    B --> C["L2 AI assist
(fills NPC motive, one-line background)"]
    C --> D{"Layer 4 review gate
(tone/consistency lint)"}
    D -->|pass| E["Layer 3 data finalized
(rulebook computes reward values)"]
    D -->|reject| B
    E --> F["Merged into build"]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class B,D code;
    class C ai;
    class E data;
    class F pass;

Let me walk this flow once as a worked transcript. Say we are making one odd-job quest for a rural village.

Step 1 — the Layer 1 rulebook draws the skeleton. The rulebook is deterministic. It comes out with nothing but the slots filled.

[Quest skeleton — rulebook output]
Region: 향촌_3
Requester role: herbalist
Objective type: collect (medicinal herbs x6)
Obstacle: wolf spawn (night)
Reward slot: { gold: ?, exp: ?, item: gathering sickle }

Step 2 — ask the AI for the details. Here is the full prompt. (The Layer 0 vision is fed in first, as context.)

You are a quest writer for an MMORPG set in an East Asian fantasy rural village. Tone anchor: "humble countryside, with superstition and fear underneath." Take the skeleton below and write a one-line motive for the requester, an NPC name, and the two-sentence request shown to the player. Never make up reward values (the system decides them). Output JSON. Skeleton: { region: 향촌_3, requester: herbalist, objective: collect 6 medicinal herbs, obstacle: wolves at night, reward item: gathering sickle }

Step 3 — Claude's raw output. (Reproduced as-is, not summarized.)

{
  "npc_name": "삼월 어멈",
  "motive": "With wolves howling every night her herb patch is being ruined, and she cannot bring herself to go dig up the last of the herbs.",
  "quest_text": "When night falls, the wolves tear up my herb patch. I am too frightened to set foot out there, so please dig up just six roots of medicinal herb at the foot of the mountain in my stead.",
  "reward": { "gold": 120, "exp": 300 }
}

Stop here for a moment. The AI added a reward field without being asked to. This is a live demonstration of why the first and second axes have to stay separate. Reward values (Layer 3) are the L1 rulebook's seat, not the AI's (L2). Hand them to the AI and the numbers wobble on every call, and the reward curve collapses.

Step 4 — human verification and veto. The reviewer does two things. (1) Deletes the reward field — that is a cell for the rulebook to fill. (2) Checks the tone. The NPC name "삼월 어멈" (Granny Samwol), the one-line motive — wolves wreck her herb patch every night, so she cannot bring herself to go dig the last herbs — and the two-sentence player-facing request all fit the rural-village tone. Pass. If the AI had inserted an out-of-setting phrase like "a commission from the mages' guild," it would be rejected here and sent back to the skeleton stage.

Step 5 — Layer 3 data finalized. The rulebook refills the deleted reward slot. It is a deterministic formula tied to region level and objective difficulty. gold: 85, exp: 240. Not the 120 and 300 the AI emitted arbitrarily — values that sit on the curve.

This one lap is the standard cycle of the center-of-gravity cell. Rulebook for the skeleton, AI for the flesh, a human for the gate, and the rulebook again for the numbers. All 1,000 pieces of content run this same cycle. Because the cell is fixed, nobody re-litigates "who makes this" every time.

6.1.6 Five Questions for Choosing a Cell

Five questions help decide which cell of the grid a new piece of content belongs in. Write them down and answer them together every time a mass-production item comes up in a meeting, and cell placement becomes consistent within a quarter.

One: how heavy is the production load? How many do you need by launch? If N is over 100, the L0 row is close to impossible.

Two: how strong is the consistency requirement? If cross-content consistency is the core of the experience, the review gate (Layer 4) has to be strong; if variety is the core, there is room to climb to a higher automation row.

Three: can you tolerate non-determinism? Is this a domain where a slightly different result every time creates richness, or one where the same result is the core of trust?

Four: what does review cost? Whether it is 5 minutes or 30 minutes per piece sets the length of the operating cycle.

Five: what does an incident cost? Can you freely scrap and rewrite, or does one slip ship straight into a player-facing incident?

Throw these five at side quests and the answers converge in one direction: more than 1,000 needed (L0 impossible), consistency requirement lower than main quests, non-determinism acceptable, review 5–10 minutes, incident cost low (each one can be scrapped individually). With all five pointing the same way, the L2 row × Layer 2 cell is the natural fit. Throw the same five at main quests and they converge the opposite way: 50 quests, the highest demands on consistency and narrative depth, non-determinism unacceptable, review cost high, incident cost very high — that is the L0 cell.

6.1.7 Four Common Pitfalls

Even with the grid drawn, teams fall into the same traps. Four of them repeat.

First, starting from the L3 row. Set out with the expectation that "AI will just handle all 100" and review explodes. Settle the L1 cell first, climb to L2, and apply L3 carefully, to a small subset only. In the mini pipeline above, the single motion of a human deleting the reward field is a small demonstration of why the L3 row is dangerous.

Second, delegating to AI wholesale, with no rulebook. "Make me 100 side quests" summons the generic-RPG average. Only when the Layer 1 rulebook sets the skeleton first and the AI fills in the flesh on top of it do you get your game's content. Writing a rulebook is the most laborious and least fun job in PCG, but skip it and everything mass-produced above it sinks down to the average.

Third, an empty review gate (Layer 4). When AI output flows into the build automatically, consistency incidents follow directly. Whatever the cell, a human gate is mandatory.

Fourth, choosing tools on cost alone. LLM API prices drop every quarter; the cost of a consistency incident does not. A tool decision should weigh API cost plus the combined cost of consistency and review time.

6.1.8 Measurement — Six Months After Moving to the Center-of-Gravity Cell

On Project A, we moved side quests from the L0 cell to the L2 cell and measured the six months that followed. In the numbers below, the absolute values are the author's estimate (unverified); what was observed in actual measurement is the direction and ratio of the change.

The scrap rate rose to 20%, but with production speed at 6–8x, net throughput grew 4–5x. Consistency incidents rose slightly, to 5–8 per quarter, but with the review gate and the rulebook reinforced, they returned to the normal range within the quarter.

The biggest change was not in the numbers but in the people. At first the writers said they felt like "reviewers on an assembly line," and satisfaction dropped from 8 to 6. To recover it, we added a policy that explicitly guarantees writer time on main quests and on signature side quests (1–2 per city). We pinned it down so that the production line would not be a thing that sucks up writer time, but a tool that sends that time back to the main content. Six months later, satisfaction was back at 7.

One thing to take from this measurement: a decision to move cells has to carry throughput, writer-time allocation, and satisfaction together. Watch throughput alone and the production numbers succeed — and the people leave.

6.1.9 Layer Decomposition First, PCG on Top

The general thesis — that Layer decomposition is the precondition for procedural generation — is in §2.3.6. Here I only look at how it shows up on the PCG grid. On a team where the horizontal axis (Layer 0–4) is blurry, no cell runs stably. If nobody knows where the Layer 0 vision lives, every generator runs with an empty tone anchor and produces the generic-RPG average. If the Layer 1 rulebook and the Layer 2 body are mixed in one file, fixing one line of a rule means touching dozens of places in the body at the same time. If Layer 3 data is typed into the body, one reward-curve adjustment costs a writer a week — this is why the mini pipeline above keeps rewards in a separate slot.

So what to check before adopting PCG is not tool choice but whether the horizontal axis is decomposed. On a team with the five layers in place, attaching an L1 generator costs one writer one quarter. On a team where the five layers are tangled, the same adoption gets scrapped within two quarters on consistency incidents.

The five layers do not need to be perfect from day one. Separate gradually, keep the interfaces narrow. In the first quarter, splitting off just one Layer 0 tone line and one Layer 1 rulebook opens a seat for a generator to come in. That is not license to postpone forever, though. If the Layer 2 body and the Layer 3 data stay one lump to the end, even the concrete tool of the next chapter will have nowhere to sit.

6.1.10 Next Chapter Preview

The next chapter dissects one concrete tool that occupies the grid's center-of-gravity cell: proj_city_hunting_generator, which mass-produces per-city hunting grounds. We will see how input metadata, the rulebook skeleton, the AI body, and the verification gate are tied into a single cycle — and how this chapter's mini pipeline scales up to the size of a real tool.

Key Takeaways

• Automation intensity (vertical, L0–L3) and Layer structure (horizontal, 0–4) only carry meaning as a product.
• The production line's center of gravity is the L2 row × Layer 2 cell: the side quest skeleton.
• Horizontal decomposition comes first; PCG only runs on a single cell on top of it.

Try It Yourself — Putting One Piece of Content on One Cell

setup. Pick one candidate for mass production (for example, side quests). Split the Layer 0 tone line and the Layer 1 rulebook skeleton (slot definitions) into separate files. Leave the reward-value slot empty on the rulebook side.

prompt. Feed the vision in as context, then give the skeleton, and state explicitly: "do not make up reward values; output JSON." You can adapt the Step 2 prompt above as-is.

verify. Check three things. (1) If the AI inserted a reward field on its own, delete it (L3 is the rulebook's seat). (2) If there are out-of-setting words, reject back to the skeleton stage. (3) Only for what passes, let the rulebook fill in the reward values and put it in the build.

Solo Scale-Down. You do not need a team. Write one rulebook (five slots) and one tone line yourself, as plain text files. Run ten quests through the cycle above and count how many you reject in review. If the rejection rate goes past 30%, the cell is wrong — tighten the rulebook skeleton, or drop one row down (L1) and look again. When the rejection rate stabilizes, that is the signal that the cell works at your scale.

6.2 city_hunting_generator — 30 Cities in 4 Weeks

Primary readers: MMORPG designers responsible for content production at scale (mid-size team, 10–50 people) Scaled-down version for solo/hobbyist readers: §6.2.10, "If You're Solo, Just This Much"

I still remember the math I did the day the schedule first landed on my desk: 30 cities needed by launch. One city consists of a 5–10 line introduction, 3–5 hunting grounds, 5–10 NPCs and 2–3 side quests per hunting ground, 1–3 specialty items, and 1 city boss. Crafting one city by hand takes 1–2 weeks. At 30 cities, that is a single writer spending 6 solid months on nothing but cities.

We did not have those 6 months. The writers' time was tied up in the main quest and the signature characters, and the 30 cities had to be built in parallel with that work. My first impulse — "why not just ask the AI to make 30 cities?" — collapsed quickly. Hand over the whole job and you get 30 fantasy towns that all look alike. Instead of that impulse, I built a tool, city_hunting_generator. This chapter looks at how it ties input, rulebook, AI, and verification into a single cycle — and what actually comes out, and what gets discarded, when you run that cycle all the way through once.

Author's operational note The city_hunting_generator in this chapter is an anonymized version of a real tool I run in the company R&D folder. The file names, code structure, and verification items faithfully follow the real tool; city names (silvermark and so on) and company-specific names were replaced for the book. The output text is a reconstruction of actual sessions.

6.2.1 Humans Handle Only the Metadata and the Final Review

The tool runs in four stages. The key point: stages 1 and 3 are deterministic (the rulebook), and only stage 2 is AI. With the rulebook holding both the skeleton and the verification in place, the AI sandwiched in the middle can give slightly different answers every time without shaking cross-city consistency. Humans enter only at the first input (metadata) and the final gate (review).

flowchart TB
    A["Input: city metadata yaml
(human: 15~20 min/city)
3 lore_seeds · forbidden_names auto-attached"]
    A --> B["Stage 1 deterministic: rules.py
generate_skeleton()
hunting ground count · enemy distribution · reward curve · boss"]
    B --> C["Stage 2 AI: 3 prompt types
L0 vision cached + L1 rules injected
+ L2 neighboring city text
→ intro · NPCs · side quests"]
    C --> D{"Stage 3 deterministic: lint
name dupes · forbidden words · voice
· length · reward range"}
    D -->|violation alert| E["Stage 4 writer review gate
(5~10 min/city)
discard/regenerate decisions"]
    E -->|re-request| C
    E -->|pass| F["Merged into build"]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class B,D code;
    class C ai;
    class A,E human;
    class F pass;

In this diagram, human hands touch only two places: at the top, where one clean page of metadata goes in, and at the bottom, where the tone and narrative judgments lint cannot catch are made. The tedious skeleton generation and bulk text production in between are run by the rulebook and the AI. The decisive design choice is that even when lint (stage 3) finds a violation, it does not auto-discard — it only raises an alert to the writer gate (stage 4). The reason is in §6.2.5.

6.2.2 Input — One Page of City Metadata

The writer writes one page of metadata per city. It takes 15–20 minutes. Short, but this one page is the entire input for the next three stages.

# city_021_silvermark.meta.yaml
city_id: city_021_silvermark
region: west
climate: cold_arid
dominant_faction: scholar_guild
cultural_tone: scholarly_strict
level_range: [25, 30]
lore_seeds:
  - Was the center of a magic seal 100 years ago
  - The first sign of the seal weakening was observed in this city
  - Site of the scholar guild headquarters
neighbors: [city_018, city_023]
# forbidden_names: (auto-attached by script — no writer input needed)

(The three lore_seeds read: "was the center of a magic seal 100 years ago," "the first sign of the seal weakening was observed in this city," "site of the scholar guild headquarters." The final comment notes that forbidden_names is attached automatically by a script — no writer input needed.)

The most important slot is lore_seeds. 3–5 key events anchor the city's identity. Too few and the AI spits out a generic fantasy city; too many and the events contradict each other. In my experience, 3 was the most stable.

forbidden_names is not filled in by the writer. A script reads the list of existing city and character names and attaches it to the metadata automatically. Once 30 cities × roughly 50 NPCs each pile up, checking 1,500 names for duplicates in your head is impossible. There is no need to hand-write "make sure it doesn't overlap with other cities' NPCs" every single time.

6.2.3 Stage 1, the Rulebook — Building the Skeleton Deterministically

The rulebook takes the metadata and builds the city's structural skeleton. The code is simple.

# city_hunting_generator/rules.py (skeleton)
def generate_skeleton(meta):
    region_rules = REGION_RULES[meta.region]
    hg_count = region_rules.hunting_grounds_range.sample()
    enemy_dist = ENEMY_RULES[meta.climate][meta.dominant_faction]

    skeleton = {
        "hunting_grounds": [
            {
                "id": f"{meta.city_id}_hg_{i}",
                "level": meta.level_range[0] + i,
                "enemy_types": enemy_dist.sample(k=3),
                "reward_curve": calc_reward(meta.level_range[0] + i),
                "npc_count": region_rules.npc_per_hg,
                "sidequest_count": region_rules.sidequest_per_hg,
            }
            for i in range(hg_count)
        ],
        "boss": {
            "id": f"{meta.city_id}_boss",
            "level": meta.level_range[1] + 2,
            "pattern": BOSS_PATTERNS[meta.region],
        },
    }
    return skeleton

The result is deterministic. Same metadata in, same skeleton out. Whether the reward curve sits within the standard range for each region and level, and whether the enemy distribution matches the climate and faction rules, is guaranteed in code and covered by regression tests. This stage is never handed to the AI. If the AI pulled a different reward number on every call, cross-city balance would wobble on the spot.

Feed in silvermark's metadata and rules.py returns an empty skeleton: 4 hunting grounds (city_021_silvermark_hg_0 through hg_3), 6 NPC slots and 3 side quest slots per hunting ground, and 1 boss at level 32. It is a table of cells to fill — no names, no text yet. Filling those cells is the job of stage 2, the AI.

6.2.4 Stage 2, the AI — Generating Natural-Language Text

After the rulebook builds the skeleton, the AI fills in natural-language text on top of it. This is where the city introduction, the NPC names, appearances, and short backstories, the side quest synopses, and the specialty item flavor text come from.

The call pattern follows the four-layer context injection structure exactly. Cache the L0 vision (world_premise + tone_manifesto), selectively inject the L1 rules (city_naming_rule + region_west_lore), add the L2 adjacent text (NPC name lists from other cities), and attach the task instruction at the end. The city introduction prompt is in a form you can copy and use as is.

[L0 context] world_premise + narrative_pillar + tone_manifesto  (cached)
[L1 context] city_naming_rule, region_west_lore
[Input] city_021_silvermark.meta.yaml + 3 lore_seeds

Write a 6~8 line introduction for this city. Weave all three lore_seeds in naturally,
and cut RPG stock phrases like "a peaceful village." Keep the tone scholarly and strict, sentiment restrained.
Output the text only, no preamble or commentary.

(The instruction, in brief: write a 6–8 line introduction for this city; weave all three lore_seeds in naturally; cut RPG stock phrases like "a peaceful village"; keep the tone scholarly and strict, sentiment restrained; output the text only, no preamble or commentary.)

The same pattern repeats as is for the NPC batch and the side quest calls. Only the context and the output format differ. The NPC call carries the forbidden_names slot (no duplicating NPC names from other cities); the side quest call carries the constraint "pick the quest-giving NPC from the NPCs generated above."

So what actually comes out? Let's run it through once, end to end.

6.2.5 One Cycle, All the Way Through — Output, Verification, Discard

Writing only the abstraction "the AI fills in the text" tells you nothing about what this tool actually spits out. Let's follow one full cycle for the city of silvermark, from input to discard.

[Stage 2 AI output — city introduction] (reconstructed from an actual session)

Silvermark is a city of the seal. 100 years ago, seven scholars raised a sealing circle beneath this ground to hold back the flood of mana from the west, and the city grew over that circle, one stone at a time. The bell tower of the scholar guild headquarters is an observatory that reads the seal's vein, not a spire raised toward any god. For the past three years, one line has repeated in the observation logs: "The vein is cooling." The first sign of the seal's weakening trembled first on this city's gauges, nowhere else. The scholars in the streets do not say it aloud. Only the nights when the bell tower's fire never goes out have grown more frequent.

All 3 lore_seeds made it into the text (seal epicenter, first sign of weakening, scholar guild headquarters); there is no "peaceful village that welcomes adventurers" stock phrase; and the scholarly_strict tone holds (sentiment restrained, a vocabulary of observation and record). This is what a passable output looks like.

Next, the same cycle fills 3 of the 6 NPC slots in hunting ground hg_0.

[Stage 2 AI output — 3 NPCs] (reconstructed from an actual session)

1) Doren Vale — Observation assistant at the bell tower. In his 50s, a brass loupe permanently fixed over one eye. Has recorded the fine tremors of the seal's vein for 30 years. A man of few words; converses only in numbers. "Today, 12.4. Yesterday, 12.1. It's climbing. That is not a good thing."

2) Mira Kost — Archivist of the guild's document vault. In her 30s, ink stains on her fingers that never wash off. She guards the original blueprints of the sealing circle, yet believes every scholar who could actually read them is dead. Deeply wary of outsiders.

3) Grem — Furnace keeper beneath the bell tower. Identity unknown, age unknown. His only job is keeping the bell tower's fire from going out, and to anyone who asks about the seal he answers only, "Just watch the fire." (flagged as uncertain — self-reported by the AI)

Note that the AI attached an uncertainty flag to the third NPC, Grem, on its own. A good prompt makes it possible for the AI to say, "I'm not confident about this one." Now stage 3 lint runs against this output bundle.

[Stage 3 lint output] (actual format)

[PASS] Length check: introduction 7 lines (standard 6~8)
[PASS] Reward range: hg_0~hg_3 reward_curve within standard range
[WARN] Name duplication: "Mira Kost" — vs. "Mira Veldt" of city_014_riverhold,
       surname (Kost/Veldt) differs but given name (Mira) identical. Near collision in forbidden_names.
[PASS] Forbidden vocabulary: tone_manifesto violations 0
[WARN] Voice consistency: "Grem" dialogue voice_lint confidence 0.62 (below 0.70 threshold)

(The five lines read: PASS on length — introduction is 7 lines against a 6\~8 standard; PASS on reward range — hg_0 through hg_3 reward_curve within standard range; WARN on name duplication — "Mira Kost" vs. city_014_riverhold's "Mira Veldt," different surnames but the same given name Mira, a near collision in forbidden_names; PASS on forbidden vocabulary — 0 tone_manifesto violations; WARN on voice consistency — Grem's dialogue at voice_lint confidence 0.62, below the 0.70 threshold.)

Lint caught 2 violations but auto-discarded neither. It only raised them as WARN to the writer gate. This is the design core previewed in §6.2.1. Give the verifier the power of automatic rejection, and within a month or two the writers will flip that switch off. The machine kills intended variation along with the real violations, and it robs the writers of the chance to gauge that boundary for themselves. So the machine is in charge of picking out suspicious candidates, but the final call on whether a candidate lives or dies stays in human hands.

[Stage 4 writer review — verdicts and discard]

The writer handled the 2 alerts like this.

• Mira Kost → kept. Same given name as riverhold's Mira Veldt, but a different city, a different surname, no chance of appearing together. Passed as an intended variation. (Separately noted as its own item: whether to widen the forbidden_names rule from "exact given name + surname match" to "WARN on given-name-only collisions too.")
• Grem → discarded. The low voice_lint confidence was the tell. On rereading, the "Just watch the fire" furnace keeper clashed with the city's scholarly_strict tone. When an NPC in a city ruled by a scholar guild drifts into mysticism, the city's identity blurs. Discard, then re-request.

Once the writer decides to discard, one re-request goes around: "Discard the Grem slot. Regenerate a furnace keeper NPC that fits the same hunting ground's scholar guild tone (observation, records, rigor). No mysticism vocabulary." The AI answered with an old man who logs the temperature of the bell tower furnace — a man who sees even fire as data — and that output passed with voice_lint 0.81. The cycle of input → skeleton → text → verification → discard → regeneration closes here.

This one full lap is the Show standard for this entire book. Unless you watch, at least once and all the way through, what the tool spits out, what gets caught, and what a human kills, the sentence "we mass-produced it with AI" is hollow.

6.2.6 The Discard Rate Is Not Tool Failure but a Signal from the Gate

In the cycle above, 1 NPC was discarded. Across a whole city, the discards pile up further. Review time averages 5–10 minutes per city; the discard rate is about 20% for NPCs and about 33% for side quests.

Let me be honest about where these rates come from. The discard rates were counted by hand while personally reviewing 5 cities, silvermark included, in the early adoption period. For NPCs, 6 of 30 reviewed were discarded (20%); for side quests, 5 of 15 (33%). With a sample of only 5 cities, the right way to read these is not as precise population rates but as directional values — "one in five, one in three." The cumulative rate after all 30 cities are reviewed could come in lower, or higher depending on the character of the hunting grounds.

What matters is that a 0% discard rate is not the goal. Zero discards is closer to a signal that the review has become a formality. When one in five NPCs gets discarded for the wrong tone, and one in three side quests gets regenerated for failing to connect to the lore_seeds, the review gate is actually working.

6.2.7 Measurement — 30 Cities in 4–5 Weeks

Before and after the tool. The time figures below are measured averages from the early cities, silvermark included; the "before" column is the writers' estimate from the hand-crafting era before the tool. None of the numbers have been doctored.

The table makes it look like the numbers are the whole story, but the real effect came from a different cell. With writer time freed from city production, one writer could substantially increase main quest output per quarter (the exact multiple varies by quarter, so I won't pin it down — the direction is "main output clearly went up"). The production tool worked as a tool that releases writer time rather than absorbing it (the warning from §6.1.8 applies as is: if the writers feel they have been turned into "review machines," the tool gets rejected).

6.2.8 Content That Doesn't Go into the Generator

Even with automation covering more ground, the following stays outside the tool.

The fact that something can be mass-produced must not auto-convert into the decision that it should be. As the silvermark cycle showed, the tool produces 5 out of 6 NPCs well. But the one signature NPC who carries the city's core tension — "the seal is cooling" — the writer shapes by hand. When the boundary of automation is clear, the production tool becomes the very thing that protects that core territory.

6.2.9 Five Common Failures

The fifth is the one most often missed. For a writer to enjoy making calls like discarding silvermark's Grem, they need time left over to craft things themselves — not just review the mass-produced output. Measure throughput only and skip measuring writer time, and the tool succeeds on the KPIs while the people leave.

6.2.10 Try It Yourself — One Step You Can Take Today

If you're solo, just this much: You don't need rulebook code. Pick one city or region from your own game (or a game you love), hand-write the metadata in the §6.2.2 format (the 3 lore_seeds are the heart of it), and run the introduction prompt from §6.2.4 once, pasted as is. Then pick the one NPC whose tone feels off and push back: "This NPC clashes with the city's tone — discard and regenerate." That is when the review gate stops being a concept and becomes, in your own hands, the bundle of judgments it really is.

If you're on a team, start with this one step. Build the one-page metadata yaml template and the forbidden_names auto-attach script first. The rulebook skeleton (generate_skeleton) and lint come after. With just the input template and the name duplication check, you can already head off the two most common failures that collapse AI text production into "30 near-identical towns."

6.2.11 A Preview of the Next Chapter

6.3 covers the NPC Persona/Squad pipeline. Where 6.2's generator mass-produces NPCs like Doren and Mira individually, Persona/Squad binds those NPCs into groups. It is how you make the five NPCs of one hunting ground work as a small society rather than a collection of unrelated dolls.

Key Takeaways

• Stages 1 and 3 are the rulebook (deterministic); only stage 2 is AI — humans handle only the input and the review gate.
• Only after watching output, verification, and discard all the way through once does "AI mass production" stop being hollow.
• Discard rates of 20% and 33% are not tool failure — they are the signal that the gate is working.

Next Chapter Preview

• 6.3. The NPC Persona/Squad Pipeline

6.3 NPC Persona and Squad — From a Mannequin Museum to a Small Society

Primary readers: MMORPG designers who own NPC and hunting-ground content (mid-size teams of 10–50) Scaled-down version for solo/hobbyist readers: §6.3.10 "If You're Solo, Just This Much"

I remember the day I used the 6.2 generator to mass-produce five NPCs for one hunting ground and put them in the game. Names, appearances, short backstories — all filled in. I placed them by dropping coordinates. But when I actually walked through that hunting ground, it felt strangely dead. Five people shared the same space and never once mentioned each other. Two of them stood overlapping on the same rock. Someone needed to play the merchant, but all five were scholars. Doren and Mira were each perfectly fine NPCs on their own; bundled together, they were a collection of mannequins.

This is the mannequin-museum state. Every individual NPC is built, but the group is not alive. This chapter covers the pipeline that binds those five into a small society. The core decomposition is Persona and Squad. To use an office analogy: a Persona is an employee's business card, and a Squad is one team's org chart. Stack fifty business cards with no org chart and the company does not run. And the spine of this chapter is the final stage — running one full cycle with the AI to verify that the bundled group talks and moves like people who actually know each other.

Author's Operating Note The Squad pipeline in this chapter is an anonymized version of the NPC Persona/Squad tool I run in my company's R&D folder. The yaml structure, the checks, and the voice_lint thresholds faithfully mirror the real tool; the city and NPC names are swapped for the book, the same as in 6.2. The output text is reconstructed from real sessions.

6.3.1 Persona Is the Business Card, Squad Is the Org Chart

A Persona is an individual NPC's identity. It holds the name, appearance, voice_profile, and role. What the 6.2 generator produces is Personas. Doren Vale and Mira Kost are each one Persona.

A Squad is the unit that binds those Personas into a group. It defines how five people are distributed across roles in one hunting ground, how they relate to each other, and how they move.

If you do not separate the two, you get blocked in two ways at once. Mass-produce only Personas and you get a mannequin museum; try to build Squads first and you have no Personas to fill them with. Separating them keeps each unit simple to operate. Separation is not severance, though. The point is to lay reuse and verification paths between the two units, and that is the main business of this chapter.

This Persona→Squad decomposition is not mere housekeeping; it opens a longer road. Only when NPC groups are formalized into roles, relationships, and numbers can you later reach dynamic reactivity — where world state (accumulated player behavior) perturbs NPC values and those values become quest trigger conditions. This chapter only points at the entrance to that progressive application; what it covers head-on stops at conservative mass production gated by human review.

6.3.2 Input — One Page of Squad Metadata

The Squad skeleton starts from one page of metadata per hunting ground. Same philosophy as the city metadata in 6.2: a human pins down only the role distribution and the intended relationships, and the rulebook and the AI do the filling.

# city_021_hg_3.squad.yaml
squad_id: city_021_hg_3_squad
hunting_ground: city_021_silvermark_hg_3
type: hunting_ground_residents
size: 5
roles:
  - role: quest_giver
    count: 1
    voice_traits: [authoritative, scholarly]
  - role: lore_keeper
    count: 1
    voice_traits: [scholarly, withdrawn]
  - role: merchant
    count: 1
    voice_traits: [practical, dry]
  - role: bystander
    count: 2
    voice_traits: [varied]
relationships:
  - between: [quest_giver, lore_keeper]
    type: mentor_and_former_student
  - between: [merchant, bystander_1]
    type: regular_customer
movement_pattern: stationary_with_shifts

The most important slot is relationships. With zero relationships, the five stay strangers forever. With too many (five or more for a five-person squad), players have too much to keep track of and the relationships drown each other out. In my experience, 2–3 core relationships per five-person Squad is the most stable. voice_traits is the device that gives the five distinct voices. Fill all five with scholarly and the verification stage flags it as voice homogenization.

6.3.3 Stages 1 and 2 — Rulebook Skeleton and Persona Fill

The rulebook sets the standard for the Squad skeleton first. Default values for size, role distribution, relationship density, and movement pattern are coded in per hunting-ground region and type.

# npc_squad/templates.py (excerpt)
SQUAD_TEMPLATES = {
    ("west", "hunting_ground_residents"): {
        "size_range": (4, 6),
        "role_distribution": {
            "quest_giver": 1,
            "merchant": 1,
            "lore_keeper": (0, 1),
            "bystander": (1, 3),
        },
        "relationship_density": 2,        # recommended relationship count
        "movement_pattern": "stationary_with_shifts",
    },
    ("east", "outpost_squad"): {
        "size_range": (3, 4),
        "role_distribution": {
            "commander": 1,
            "scout": 1,
            "support": (1, 2),
        },
        "relationship_density": 1,
        "movement_pattern": "patrol_loop",
    },
}

This stage is deterministic. For a western-residents Squad, the accident of five quest_givers and nothing else is impossible at the code level. If a role distribution steps outside the rules, it gets blocked on the spot.

Next, each slot is filled with a Persona. There are three paths. If the pool has a Persona that fits, reuse it (appearance weight +1); if not, generate a new one with the 6.2 generator; and if it is a key figure in the main quest, a writer writes it by hand. For silvermark's hg_3 Squad, the quest_giver and lore_keeper slots were filled with Mira and Doren, already mass-produced in 6.2, and the merchant and two bystanders were newly generated. Up to this point it is the same cycle as the 6.2 generator. The real work of this chapter comes next: verifying that the bundled group actually behaves like a group.

6.3.4 One Cycle, End to End — Relationship Fill-In, Movement, and Consistency Checks

If I only wrote, abstractly, that "the AI fills in the relationships," you would have no idea what this pipeline spits out. So let us follow the back half of one cycle for the silvermark hg_3 Squad, end to end — from generating the relationship text to discarding and re-requesting.

Stage 3 — AI Relationship Fill-In

The relationship tag entered in the Squad skeleton (mentor_and_former_student) is an abstraction; it is invisible in the game. Stage 3 turns it into a one-line description to be planted in NPC dialogue and events. The prompt is in copy-paste-ready form: it hands the AI the L0/L1 context, the two Personas, and the relationship tag, then asks for a one-to-two-line background usable in game dialogue — the two speech styles must not clash, scholarly-strict tone, no mysticism, no "old friends" clichés, body text only.

[L0 context] world_premise + tone_manifesto  (cached)
[L1 context] city_021_silvermark.lore (ruled by the scholars' guild, scholarly_strict)
[Persona 1] quest_giver — Mira Kost, guild archive librarian, 30s, ink stains
[Persona 2] lore_keeper — Doren Vale, bell-tower observation assistant, 50s, speaks only in numbers
[Relationship tag] mentor_and_former_student

Describe the relationship between these two (mentor and former student) in just 1~2 lines,
as background usable in game dialogue. Doren is numbers, Mira is documents — keep the two
speech styles from clashing. Strict scholarly tone, no mysticism, no clichés like "old friends". Body text only.

[Stage 3 AI Output — Relationship One-Liner] (reconstructed from a real session)

Twenty years ago, Doren taught Mira the notation used in the seal-array observation records. Now their positions are reversed: Mira copies the readings Doren takes into the archive ledgers. Every Tuesday the two of them argue, briefly, over the one cell where the readings and the ledger disagree.

This output is good. mentor_and_former_student became concrete; Doren's "numbers" and Mira's "documents" were tied into one scene (copying readings into a ledger) without clashing; and the scholarly_strict tone held. The same prompt is repeated for the merchant–bystander_1 regular_customer relationship.

Stage 4 — Movement Synthesis

An NPC standing in one spot all day becomes a mannequin again. The rulebook fills in the movement pattern. stationary is a fixed position (guards, bosses); stationary_with_shifts nudges the position every 8 hours (the common case); routine_loop runs on a timetable (residents); event_driven moves only on triggers (quest NPCs). This is deterministic, so the AI is not called.

Stage 5 — Squad Consistency Lint (This Pipeline's Gate)

Now we test whether the five, bundled, actually behave like a group. Where the 6.2 lint looked at individual NPCs, this lint looks at group consistency.

[Stage 5 Squad Lint Output] (actual format)

[PASS] Role distribution: quest_giver 1 · lore_keeper 1 · merchant 1 · bystander 2 (rule satisfied)
[PASS] Relationship density: 2 (recommended 2, satisfied)
[WARN] Voice diversity: scholarly family 3/5 — quest_giver·lore_keeper·bystander_2
       have voice_profile cosine similarity 0.83 (exceeds 0.80 threshold). Homogenization risk.
[WARN] Movement collision: merchant·bystander_1 coordinates overlap within 1.5m radius, 14:00~16:00 window
[FAIL] Relationship visibility: 2 relationships defined, but 0 mentions of any other member in the 5 NPCs' dialogue.
       Relationships exist only in data — in-game visibility 0.

The lint caught three items: a voice-diversity WARN (3 of 5 voices in the scholarly family, cosine similarity 0.83 against a 0.80 threshold), a movement-collision WARN (merchant and bystander_1 overlapping within a 1.5m radius in the 14:00–16:00 window), and a relationship-visibility FAIL (2 relationships defined, 0 mentions of any other member in the five NPCs' dialogue — the relationships exist only in data). None of the three is discarded automatically; all three go up to the gate — the machine surfaces the suspects, but a human decides what lives and what dies. Same design as §6.2.5.

[Stage 6 Writer Review — Verdicts and Discards]

The writer handled the three alerts like this.

• Voice homogenization (WARN) → discard bystander_2. Even in a scholars' city, five people all talking like scholars makes the hunting ground monotonous. Re-generate bystander_2 as an odd-jobs worker with a practical, dry tone. (The quest_giver and lore_keeper both being scholars is the city's identity, so that stays.)
• Movement collision (WARN) → fix the rule. Push the merchant's shift start offset by +2 hours to clear the 14:00 overlap. No AI call — just a movement-parameter adjustment.
• Relationship visibility 0 (FAIL) → the one that matters most. If you define two relationships and they never show up in the game, that data is dead data. The writer decided to pick one core relationship (Doren–Mira) and plant it in dialogue.

Two of the three closed via a rule fix or regeneration; the last FAIL is the heart of this pipeline. The writer requested one additional dialogue-branch line for Doren — a single line in which the relationship with Mira slips out in passing, an aside rather than exposition, in a scholar's tone.

Insert just one line into Doren's dialogue where the relationship with Mira slips out in passing.
Not expository — as an aside. Scholarly tone, one line of dialogue only.

[Re-request Output]

"That diagram is in the archive. Ask Mira. ...Twenty years ago I was the one teaching her how to read them. These days it's the other way around."

The moment this one line goes in, the relationship between the two NPCs moves from the data sheet onto the game screen. Input (Squad metadata) → skeleton → Persona fill → relationship fill-in → movement → consistency check → discard and visibility decisions: one full cycle closes here.

This one loop is this chapter's standard of Show. The sentence "we bound the NPCs into a society with Squads" is hollow unless you have watched, at least once, a human close a relationship-visibility-0 FAIL with a single line of dialogue.

6.3.5 The Full Persona→Squad Flow

Here is the cycle above in a single diagram. The key points: stages 1, 2, 4, and 5 are deterministic (rulebook and lint), only stage 3 is AI, and human hands touch only the input at the top and the gate at the bottom.

flowchart TB
    P["Persona pool
(6.2 generator output)
Doren, Mira, ..."] --> FILL
    A["Input: Squad metadata
(human, 10–15 min per hunting ground)
role distribution + intent for 2–3 relationships"]
    A --> B["Stage 1, deterministic: templates.py
standards for role distribution, relationship density, movement"]
    B --> FILL["Stage 2: Persona fill
reuse / generator / writer-authored"]
    FILL --> C["Stage 3, AI: one-line relationship fill-in
L0 caching + voice_traits conflict check"]
    C --> D["Stage 4, deterministic: movement synthesis
shift, routine, event_driven"]
    D --> E{"Stage 5, deterministic: Squad lint
role distribution, voice diversity,
movement collisions, relationship visibility"}
    E -->|"alert"| F["Stage 6: writer review gate
(5–10 min per hunting ground)
decide: discard, rule fix, relationship exposure"]
    F -->|"re-request"| C
    F -->|"pass"| G["Into the build"]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class B,D,E code;
    class C ai;
    class A,F human;
    class P data;
    class G pass;

Human hands touch only two places: the spot at the top where role and relationship intent is set, and the spot at the bottom where someone judges the tone and narrative that lint cannot catch. In between, the rulebook runs the skeleton, the movement, and the checks, and the AI writes the relationship text.

6.3.6 Three Devices That Make Relationships Visible in the Game

The 관계 노출 (relationship visibility) item is the most frequent FAIL in the stage 5 lint, because relationships tend to live only in the data. There are three devices for pulling a relationship into the game.

First, dialogue mentions. As with Doren's line in §6.3.4, an NPC mentions another member in one line. Cheapest, and the most effective.

Second, route crossings. Every Tuesday, Doren and Mira can be observed together in the archive, inside the game. A player who happens to see it thinks, "are those two connected?" If the stage 4 movement agrees with the relationship, this comes out naturally.

Third, branch conditions. Refuse the quest_giver's request and the lore_keeper's affinity drops with it. This third device is the entrance to the progressive application mentioned in §6.3.1 — the point where a relationship goes beyond mere description and starts affecting game state.

You do not need all three. In a five-person Squad, exposing just the 2–3 core relationships through the first and second devices already changes how the hunting ground feels. Overdo it and players have too much to memorize. At review, the writer picks which relationships to expose and leaves the rest as data.

6.3.7 Measurement — Honestly

I compare before and after adopting the tool. No fabricated figures. The times and rates are values I counted while personally reviewing the first several hunting grounds, including silvermark; the "before" column is a writer's estimate from the handcraft era.

The sample is small — a handful of hunting grounds — so read these as directional values, not precise population rates. The biggest change does not fit in the table. Because the lint's 관계 노출 FAIL forcibly shoves "this hunting ground shows zero relationships" in the writer's face, mass-produced content shipping as a mannequin museum became structurally rarer. The point that 0% discards and 0 exposures are not the goal (§6.2.6) holds here as well. The Squad pipeline should absorb most of the bundling work, while leaving the writer time to shape the parts that matter by hand — like Doren's final line.

6.3.8 The Persona Pool — When the Same Character Appears in Multiple Cities

Once Squads stabilize, the Persona pool follows naturally as an operation. The same Persona can appear in multiple cities. An NPC from the scholars' guild being run into in three or four cities is, if anything, natural. The world does not look smaller; it looks connected.

persona_pool:
  - id: persona_doren_vale
    voice_traits: [terse, numeric]
    appearance_count: 3
    appearance_cities: [city_021, city_018, city_023]
    signature: false
  - id: persona_mira_kost
    voice_traits: [scholarly, withdrawn]
    appearance_count: 2
    signature: false

Reuse rates have a healthy range.

That said, put one NPC in too many cities and players go "oh, this person again." Cap a Persona's appearances at 5 cities. Boss rooms and signature characters are no-reuse (signature: true). From a Persona's second appearance on, visual variation (lighting, props) is mandatory. This 30–50% range is not a precise number but an operating guideline — adjust it for your team and game scale.

[Signpost — If You Saw the Persona Pool as a Distribution (Still Premature)] For a team whose pool has grown to hundreds of NPCs, there is one step further — a signpost in the same spirit as the "dimension vector" section in §8.2.7 (not a prescription; for the conceptual intuition, see Appendix M). The voice_lint in §6.3.4 already measures the "closeness" of two Personas via cosine similarity (values like 0.83). Put the same embeddings over the whole pool, and staleness can be diagnosed as distribution density rather than a writer's impression — "scholarly voices piled up in one corner" becomes visible as the point density of that region. That opens a path: instead of stamping yet another similar scholar into a low-density region, you fill the gap with a variation interpolated between two nearby Personas, patching diversity that way. Two cautions, in the same breath. A Persona produced by interpolation easily becomes a "dead midpoint," an awkward blend of two NPCs — in the end a human has to bring the voice back to life. And the staleness range above (30–50%) is an operating guideline, not a precise figure; the moment you convert it into embedding distance, looseness risks passing itself off as precision — the distance value is a signal that aids the writer's judgment, not the judgment itself.

6.3.9 Six Common Failures

The fourth is the one most often missed. Defining a relationship and making it visible in the game are different jobs, and without a check the latter is almost always dropped. If the lint had not shoved relationship visibility 0 in our faces as a FAIL for silvermark hg_3, Doren and Mira would have been mentor and student only on the data sheet.

6.3.10 Try It Yourself — One Step You Can Take Today

If you're solo, just this much: You don't need a rulebook or a lint. Pick 3–5 NPCs in one location of your game (or a game you love), and write down their roles and 2 relationships by hand, in the §6.3.2 format. Then paste the relationship prompt from §6.3.4 as-is to get a one-line description, and finally ask yourself: "Where in the game's dialogue is this relationship visible right now?" If the answer is nowhere, that is exactly the lint's 관계 노출 0 (relationship visibility 0) FAIL. Close that FAIL by hand — slip a one-line mention of another member into one NPC's dialogue — and what Squad verification actually catches sinks in for good.

If you're on a team, start with this one step. Build one Squad metadata yaml form and, from the stage 5 lint, just the one-line 관계 노출 check (grep each NPC's dialogue text for other members' names and roles). The role-distribution check and the movement-collision check come after. Even with only the relationship-visibility check, you block the most common failure first: a mass-produced hunting ground shipping as a mannequin museum.

To sum up as setup → prompt → verify — setup: define roles and relationships in the Squad metadata yaml and lay the skeleton with templates.py. prompt: request the one-line relationship in the §6.3.4 format, enforcing no voice_traits clashes and no stock phrases. verify: run the stage 5 lint, confirm the 관계 노출 FAIL, and close it yourself by planting one core relationship in dialogue.

Key Takeaways

• A Persona is a business card, a Squad is an org chart — only by separating them does a mannequin museum become a society.
• "We bound them into a society" stays hollow until you watch relationship fill-in, movement, and consistency verification run end to end at least once.
• The heart of this pipeline is a human closing the 관계 노출 0 FAIL with a single line of dialogue.

Next Chapter Preview

• 6.4 The Content Mass-Production Workflow — Binding Persona, Squad, and City Generation into a One-Week Cycle

6.4 Content Production Workflow — Tying Multiple Generators into One Production Line

The week all three tools were finished, I sat down in one place and ran the city generator, the NPC generator, and the item generator. Each of the three worked fine on its own. I got 7 cities, 110 NPCs, and 60 weapons. It was only a few days later, sitting down to review, that I realized I had stepped into the same trap three times.

The city port_harman had been generated as a "fallen fishing village," yet the NPCs placed in it carried personas like "wealthy merchant of a thriving trade port." The city generator and the NPC generator had each looked at different lore_seeds. The item generator had stocked the shops with a level-40 legendary weapon in a city whose recommended level range is 12–18. Each of the three tools was right on its own — and wrong because they were not tied together.

This chapter is not the story of building one tool. It is an operations story: tying the city generator from 6.2, the NPC Squad from 6.3, and the item generator into a single production line. With three tools you do not get three traps; new ones grow in the gaps between the tools.

6.4.1 The Production-Line View

Run the city, NPC, and item generators separately, and each tool's output drifts out of step with the next tool's input. The fix is not making the tools smarter. It is pinning shared metadata once, upstream, and lining the tools up beneath it. If the city generator from 6.2 (chapter 2 of this part) is the model of a single tool, this chapter is the work of demoting that tool to one station on a line.

The whole line flows like this.

flowchart TD
    SEED[Mon: lore_seeds sheet
region·climate·faction·level_range]:::human
    SEED --> CITY[Tue: city generator
L1 rulebook skeleton + L2 AI body]
    CITY -->|city_manifest.json| NPC[Tue: NPC generator
inherits city lore]
    CITY -->|level_range| ITEM[Tue: item generator
inherits level range·faction]
    NPC -->|persona_pool| SQUAD[Tue: Squad placement]
    ITEM --> SQUAD
    SQUAD --> LINT[Wed: integrated lint
cross-generator consistency]
    LINT -->|alert| REVIEW1[Wed: first-pass review
the writer]
    REVIEW1 --> REVIEW2[Thu: second-pass sample
narrative lead]
    REVIEW2 --> BUILD[Fri: merge into build
+ prep next week's seeds]
    BUILD -.feedback.-> SEED

    classDef human fill:#fde68a,stroke:#b45309,color:#000;

The key is the arrow labeled city_manifest.json. As the city generator builds a city, it drops that city's identity — fallen fishing village or thriving trade port — into a manifest, and the NPC generator and the item generator take that manifest as input. The trap I stepped into back then existed because this arrow did not. Tying tools together means putting this one line of contract between them.

6.4.2 The One-Line Contract Between Tools — The Manifest

Every time the city generator produces a city, it also emits a city_manifest.json. Here is its actual shape. This file becomes the input for the NPC and item generators.

{
  "city_id": "port_harman",
  "display_name": "하르만 항",
  "lore_seeds": ["몰락한 어촌", "옛 무역의 잔향", "소금 부족"],
  "region": "남부 연안",
  "dominant_faction": "어민 길드",
  "level_range": [12, 18],
  "tone": "쇠락·끈질김",
  "forbidden_names": ["하란", "하르멘"],
  "neighbors": ["salt_marsh", "old_pier"]
}

The NPC generator inherits lore_seeds and tone and produces "the stubborn people of a fallen fishing village." The item generator inherits level_range and stocks only level 12–18 weapons. The forbidden_names are names already used in the city next door, so both generators avoid them. Three tools read the same single page of contract.

Here is the prompt I gave Claude to build this manifest. It is the single most important call in the production line — the one that pins down the upstream — so I quote it in full. (In this edition, the Korean data values that flow into the verbatim JSON artifacts are kept in Korean, with English glosses in parentheses.)

You are the manifest writer for an MMORPG city generator. Take the writer metadata below and generate city_manifest.json.

Writer input: - city_id: port_harman - lore_seeds: 몰락한 어촌 (fallen fishing village), 옛 무역의 잔향 (echoes of old trade), 소금 부족 (salt shortage) - region: 남부 연안 (southern coast) - level_range: 12-18

Rules: 1. Infer dominant_faction from the lore_seeds, but it must not overlap with the factions of the neighboring cities (salt_marsh, old_pier). The neighboring factions are [염전 조합 (saltworks union), 밀수단 (smuggler ring)]. 2. Put NPC/place names already used in adjacent cities into forbidden_names. Provided list: [하란 (Haran), 하르멘 (Harmen)]. 3. tone must be two words at most, and must not contradict the lore_seeds. 4. Mark inferred values separately from values the writer specified.

Claude's raw output came back like this. I am quoting it as is, not summarizing. It broke a rule in one place.

{
  "city_id": "port_harman",
  "display_name": "하르만 항",
  "lore_seeds": ["몰락한 어촌", "옛 무역의 잔향", "소금 부족"],
  "region": "남부 연안",
  "dominant_faction": "밀수단",   // ← inferred: salt shortage + old trade = smuggling
  "level_range": [12, 18],
  "tone": "쇠락·탐욕",
  "forbidden_names": ["하란", "하르멘"],
  "neighbors": ["salt_marsh", "old_pier"]
}

(Inferred values: dominant_faction, tone, display_name / writer-specified: the rest) Caution: I chose "밀수단" (smuggler ring) for dominant_faction, but under rule 1 the neighboring city old_pier is already "밀수단". This violates the rule. I suggest "어민 길드" (fishers' guild) as a replacement.

What matters here is that the AI reported its own rule violation. The smuggler ring ("밀수단") is an attractive inference from the lore_seeds — salt shortage plus old trade equals smuggling — but at the line level it is a collision. The city next door is already run by smugglers. I took the AI's suggestion: dominant_faction became the fishers' guild ("어민 길드"), and tone became "쇠락·끈질김" (decline · tenacity). "Greed" ("탐욕") was a word born from the smuggler premise and did not fit a fishers' guild.

That single verify–reject–reassign protects the upstream of the line. If the manifest is wrong, the 110 NPCs and 60 weapons below it are all generated on a false premise. Five minutes spent upstream saves three hours downstream.

6.4.3 Integrated Lint — Checking the Gaps Between Tools

A single generator's lint only looks at its own output. The city lint checks whether the city followed the rulebook; the NPC lint checks whether the personas kept voice consistency. But the trap I stepped into at the start was not inside each tool — it was between the tools. So the line needs one more layer above the per-tool lints: an integrated lint that reads cities, NPCs, and items together and cross-checks them.

Here is what the integrated lint actually catches.

Here is part of the actual output from a run of this integrated lint. It does not auto-discard anything. It only raises alerts so that a human makes the call.

[integrated lint] port_harman line check — 3 alerts

ALERT-1 (lore consistency) port_harman
  city.lore_seeds = ["몰락한 어촌", ...]
  npc[merchant_04].persona = "번성하는 무역항의 부유한 상인"
  → Possible contradiction. Check whether this is an intended variation.

ALERT-2 (level-range consistency) port_harman
  city.level_range = [12,18]
  item[blade_legend_07].required_level = 40
  → Exceeds the recommended level range by 28. Re-review shop placement.

ALERT-3 (name duplication) — info
  npc[fisher_02].name = "하란"
  city.forbidden_names = ["하란", ...]
  → Collides with forbidden_names. Regenerating the NPC name is recommended.

ALERT-1 made me pause for a moment. An NPC who is a "wealthy merchant of a thriving trade port" is not automatically wrong. If the city used to thrive and has since fallen, then "a once-wealthy, now-poor merchant" is actually a good story. So I judged ALERT-1 not as a discard but as an "intended variation," and requested a one-line revision of the NPC persona to "an old merchant clinging to the traces of a once-thriving trade port." ALERT-2 was an outright accident, so I removed the weapon. ALERT-3 only needed the name regenerated.

The automated lint did not prevent the accident. The automated lint dragged the accident in front of human eyes, and a human made the call. That is the core of L2 (rulebook + AI assist) from 6.1. The AI builds the skeleton and the alerts; the human makes the final call. Telling apart "looks wrong but is good narrative," like ALERT-1 — a rulebook cannot do that.

6.4.4 Running the Line on a One-Week Cycle

Once the tools are tied together, the line needs a rhythm. A one-week cycle turned out to be the most stable. A week is short enough that review does not pile up, and long enough that the feedback loop is not sluggish. It lines up with one box of my desk calendar.

Tuesday is the heart of the line. The city generator drops a manifest, the NPC generator picks it up, the item generator picks it up, and Squad handles the placement. This chain runs in the background with no writer involvement. Meanwhile the writer writes main quests (L0, fully handcrafted). This is the real payoff of tying the tools together. With separate tools, the writer has to touch the line three times on Tuesday; tied together, not even once.

One writer mass-produces 5–7 cities a week, along with their NPCs and weapons. Four weeks gives 20–28 cities. The 30-city target was reached in six weeks.

6.4.5 Line Health — Four Metrics Checked Every Week

Whether the line is healthy is read in numbers, not impressions. Four metrics, tallied automatically every week.

The most line-like metric is the second one: the cross-generator collision count. When you run a single tool, this number does not exist. When it suddenly passes 10, it is not that one tool broke — it is that the contract between the tools (the manifest) broke. The usual case: the city generator's manifest schema was changed while the NPC generator was still reading the old schema. Without this metric, you do not see that accident until launch.

The four metrics are fed weekly into the quarterly retrospective. If the trend worsens, I cut the next week's city count from 5–7 down to 3–5 and look for the cause.

6.4.6 Three Accidents That Break the Line

Tie several tools together and you get accidents that a single tool never had. Here are the three I saw most often.

First, the contract-mismatch accident. A new field is added to the city generator's manifest, and the NPC generator does not know that field. The cross-collision metric spikes. When tools are developed separately, it is easy for only one side to get updated. The response is to put a version field in the manifest schema and have downstream generators raise an immediate alert on a version mismatch. You do not lecture people; you enforce the contract.

Second, the upstream-contamination accident. If the manifest is generated on a false premise (like the smuggler ring in §6.4.2), everything below it is contaminated. The human review discard rate passes 30%, yet when you look at the discarded output, the per-NPC quality is fine. The pieces are fine; the premise is wrong. The response is to add one more review at the manifest stage. Review one thing upstream rather than 110 things downstream.

Third, the model-drift accident. The LLM gets auto-updated and its output characteristics change. The city, NPC, and item generators all wobble at once. Check the past week's changes, analyze five discarded samples, and adjust the prompts or the context. Monitor for a week and confirm recovery.

The common response to all three is the same: do not blame the person; reinforce the contract. If the cause is that the writer wrote only one line of lore_seeds, then instead of saying "please write three lines," add a mandatory check to the manifest lint. That does not mean human responsibility is zero. Separately from reinforcing the system, accident patterns are shared in the retrospective.

6.4.7 Where the Writer's Time Goes

The real purpose of tying the line together is not to remove the writer, but to let the writer concentrate on signature content. One picture shows how writer time scatters when the tools are separate, and how it gathers once they are tied.

Main quests and signature content gather 80% of the writer's time. But this allocation does not maintain itself. Once a line is in place, writer time tends to drain into review. So I measure the time split every month, and if main-quest time falls below 50%, I reduce the number of cities produced and recover the main-quest time. The time split has to be defended as policy.

6.4.8 Extending the Line to Other Content

Once the city–NPC–item line is stable, the same skeleton extends to dungeons, collection codexes, and live events. The key is not inventing a new pattern. The temptation always comes: "dungeons are different from cities, so they need a different structure." But the skeleton of the line — shared manifest → generator chain → integrated lint → human review — is exactly the same. Only the input metadata template and the domain rulebook get swapped out.

For dungeons, a dungeon_manifest.json gains fields like boss_pattern and encounter_flow, and a domain rule such as boss routing adds one more line to the integrated lint. Same skeleton, different rules. Keeping the skeleton means the writer never has to learn yet another tool, and the integrated lint infrastructure is reused as is. That said, this is not a license to ignore domain specifics. Dungeons genuinely need routing rules that cities do not.

6.4.9 Results from Six Months of Operation

Here are the results of running this integrated line for six months on my project, compared with the period when the city, NPC, and item generators ran separately. The absolute figures below are the author's estimate (unverified), not exact tallies; the direction and the ratios follow measured trends.

The most important change is the last row. With the tools separate, upstream review was zero and downstream review was three hours. With the line tied together and the manifest reviewed upstream, five upstream minutes erased two downstream hours. And because accidents no longer leak through the gaps between tools, post-launch consistency accidents fell from 8–12 per quarter to 2–4.

The trade-off also became explicit. Before, the abstract argument "mass production is dangerous" came around every quarter. Now decisions are made on a concrete comparison: "collisions −8 / main quests +5."

6.4.10 Seven Common Failures

1) Running the tools separately instead of tying them. The traps grow not inside the tools but between them.

2) Connecting generators without a manifest. Without a shared contract, downstream drifts away from upstream.

3) Substituting per-tool lint for the integrated lint. Per-tool lint cannot see cross collisions.

4) Compressing the cycle from five days to three. Five days is the safety margin for review.

5) Reviewing downstream while skipping the upstream (the manifest). Look at one upstream item rather than 110 downstream.

6) Charging accidents to human fault alone. Contract reinforcement and rule automation are the answer.

7) Building the line and then not using it. Enforcing the one-week cycle matters as much as the tools do.

Try It Yourself

setup. Prepare the city generator (6.2) and the NPC generator (6.3). Decide on a single city_manifest.json schema the two will share. At minimum, the fields are lore_seeds·region·faction·level_range·forbidden_names·tone·version.

prompt. Use the manifest-writer prompt from the body above as is. The last two rules are the point: "do not overlap the neighboring city's faction" (cross-collision prevention) and "mark inferred values separately from specified values" (reviewability). When a city is generated, have it drop a manifest, and wire the NPC and item generators to take that manifest as their input.

verify. Run the integrated lint once. It cross-checks four things: lore consistency, level-range consistency, faction collision, and name duplication. When an alert fires, do not auto-discard — have a human judge it. Telling apart "looks wrong but is good narrative" (the old merchant of a fallen trade port) is the human's share of the work.

Solo Scale-Down. Even if your only tools are a city generator and an NPC generator, the line still holds. Put each city's lore_seeds, level_range, and forbidden_names on one row of a spreadsheet, and pasting that whole row into the NPC generator prompt already plays the manifest's role. An integrated lint with a single rule — city–NPC lore consistency — is enough to block that trap. No grand infrastructure required: one principle, "put one line of contract between the tools," is enough to start the line.

Key Takeaways

• Traps grow not inside the tools but between them — tie that gap shut with a manifest
• The integrated lint is not a discard machine; it is a device that drags accidents in front of human eyes
• Five minutes of upstream review erases two hours of downstream review — block it at the top

Part 7 · Level Design

7.1 Procedural Level Design Master

The exit of room 47 in the dungeon was sealed. The build had passed. QA had passed. It was the third day of live service when a screenshot appeared on the community boards: a player standing in front of a wall, one room short of the boss. That room had been copy-pasted from a hand-built room two quarters earlier, and somewhere in the copying, one eastern corridor kept its visuals but lost its connection data. Nobody verified it. There was no tool to verify it with.

This chapter is the story of building a structure that blocks that accident automatically, at the build stage. The heart of it is not the craft of drawing spaces — it is the practice of running the data attached to those spaces as rules.

A level design workshop is closer to a drafting room. Each blueprint comes from someone's hands, but consistency, reuse, and verification across blueprints are decided by how the blueprint cabinet is run. Anyone can build one hand-crafted dungeon. Running a hundred dungeons with a consistent difficulty curve and a graph free of dead ends is not a matter of craft — it is a systems problem.

On Project A — the MMORPG where I work as design director (targeting Korea and Southeast Asia, a mid-size team of 10–50, mobile-first) — this system has a name: a single document called Procedural_Level_Design_Master. This chapter covers what that document unifies, how far AI gets to touch it, and where AI stops. Underneath this chapter sits my experience leading design on a mobile roguelite RPG where the dungeon was generated fresh every run — running procedural space as rules.

7.1.1 Two Paths — Generate the Space, or Operate Its Metadata?

Level automation splits in two directions. One is generating the space itself procedurally. Classic PCG (Procedural Content Generation) lives here: BSP partitioning (Binary Space Partitioning, a classic technique that recursively bisects a space to place rooms), wave function collapse, drunkard's-walk grids. The other is operating the space's metadata — room tags, connectivity, difficulty labels, event slots.

Classic PCG is strong at the first. In genres where "a new map every run" is the core of the game — roguelikes, sandboxes — the first is the right answer. MMORPGs are different. Players run the same dungeon dozens of times. They run it until the route is memorized. So the dungeon needs to be a fixed, hand-polished space, and the place for automation is not the space itself but the metadata that makes that space operable.

Why metadata is the spine of operations becomes clear deliverable by deliverable.

A dungeon without metadata builds, but it cannot be operated. It is a library full of books with no index. That is why this chapter focuses on "operating spatial metadata."

7.1.2 What the Master Document Unifies

Procedural_Level_Design_Master binds four standards into one document: the room metadata format, the room tag dictionary, the connectivity rules, and the validation checklist. Start with what happens when these four are scattered. When five designers each reference the format from a different file, one writes the type field as combat, another as Combat, another as battle_room. Search breaks, statistics break, and eventually automation breaks.

Sorted by Layer, each of the four standards has an obvious home. The format, the dictionary, and the rules belong to the rulebook that governs generation (L1); the generated room bodies are content (L2); sheet values are data (L3); validation sits at the build/QA gate (L4).

When I say the master document unifies the four standards, I do not mean "cram all the body text into one file." I mean "collect the rules in the L1 slot." That is what lets the automation that comes later sit on top of the Layer boundaries (what happens when the separation collapses is covered in 7.1.11).

7.1.3 The Room Metadata Format — the Input Slot Where Automation Attaches

Each room follows the format below. This format is the input interface for automation.

room_id: dungeon_021_room_07
dungeon: dungeon_021_silvermark_library
type: combat_room          # combat / puzzle / lore / safe / boss
size: medium               # small / medium / large
difficulty_label: hard_for_level_28
tags: [scholar_theme, vertical_layout, water_hazard]
connections:
  - target_room: dungeon_021_room_06
    type: door
    direction: south
  - target_room: dungeon_021_room_08
    type: passage
    direction: east
event_slots:
  - slot: enemy_spawn_1
    constraints: [scholar_enemy, level_28]
  - slot: lore_object_1
    constraints: [scholar_lore]
movement_complexity: 4     # 1~5
estimated_clear_time_sec: 90
art_pack: scholar_library_v2

Every field has at least one automation consumer. type feeds dungeon pool statistics and difficulty calculation; tags feeds search, reuse, and art set mapping; connections feeds graph validation (dead-end checks); event_slots feeds automatic quest and boss placement. A field with no consumer does not go into the format. It only adds input cost without adding value.

7.1.4 The Room Tag Dictionary — Small and Orthogonal

Tags are the metadata's search keys. Let them multiply without limit and search breaks. Put 200 labels on a cabinet of drawers and you can no longer find what is where. So we run 5 categories × roughly 6 enums per category — about 30 in total.

A room never carries more than 5 tags; 3–4 is normal. Adding a new tag means passing a four-step gate: it must be a candidate for use in 5 or more rooms per quarter, it must be inexpressible as a combination of existing tags, its use in search or art set mapping must be clear, and it must still be on 5 or more rooms after a month in operation. The last condition is the key one. A tag created on impulse, used once, and abandoned pollutes the dictionary.

7.1.5 The Procedural Level Pipeline — From Rulebook to Validation

How the standards so far connect into one flow — that connecting line is the skeleton this chapter rests on. It is a pipeline that starts at the rulebook, passes through AI-assisted variation, and ends at guardrail validation.

flowchart TD
    A["L0 vision — dungeon concept · pacing intent"] --> B["L1 rulebook\ntag dictionary · connectivity rules · slot rules"]
    B --> C["Room skeleton layout\ndesigner handwork + editor"]
    C --> D["Automatic metadata extraction\nroom_id · connections · type · size"]
    D --> E["AI-assisted variation\ntag extraction · art_pack mapping suggestions"]
    E --> F{"Dictionary enforcement check\ntags outside the dictionary?"}
    F -->|outside dictionary| E
    F -->|pass| G["Designer review\nfinalize tags · difficulty_label"]
    G --> H["L4 graph validation\nreachability · dead ends · loops · branching"]
    H -->|violation| C
    H -->|pass| I["Difficulty curve validation\nsum of room difficulty labels"]
    I --> J["Art set consistency gate"]
    J -->|pass| K["Build — register in dungeon pool"]
    J -->|mismatch| E

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef ai fill:#f3e8ff,stroke:#9333ea,color:#3b0764;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class B,D,F,H,I,J code;
    class E ai;
    class C,G human;
    class K pass;

Three properties of this pipeline are worth pinning down. First, the rulebook (L1) sits upstream of all generation. Second, AI varies only within the dictionary the rulebook defines — the F gate sends out-of-dictionary output back. Third, validation (H, I, J) is fixed as a gate just before the build, so violations are blocked by code rather than depending on anyone's attention. The room 47 accident happened because there was no H gate.

7.1.6 Connectivity Rules — Guardrails Verified as a Graph

The connections field in the room metadata turns the whole dungeon into one directed graph. Once it is a graph, validation is automatic.

The measurement script takes the following shape: a thin wrapper that lays dungeon vocabulary over standard graph algorithms (longest path, average out-degree, loop count, shortest path).

# level_graph_metrics.py
def measure(dungeon):
    graph = build_graph(dungeon.rooms)
    return {
        "depth":            longest_path_length(graph),
        "branching_factor": avg_out_degree(graph),
        "loop_count":       count_loops(graph),
        "dead_ends":        count_dead_ends(graph),
        "boss_reachability": shortest_path(graph.start, graph.boss),
    }

The five metrics come out in a form comparable across dungeons. We use them as diversity metrics for the dungeon pool. But diverse metrics do not mean a fun dungeon. Metrics exist to block accidents, not to guarantee fun. Zero dead ends guarantees no fun at all. Fun comes from a designer's insight; graph validation just holds up the floor so that insight does not get buried under accidents.

7.1.7 Worked Example — Handing tags Extraction to AI, Rejecting It, and Asking Again

Of all the automation, the part people most often want to take their hands off is tags entry. Tagging 100 rooms is tedious, and even a human gets confused looking at room screenshots alone. Repetitive work with clear judgment criteria is exactly the kind of place where AI is good at carrying the first draft. This section lays out the workflow I actually ran — the prompt, the AI output that got rejected, and the human's follow-up request — with nothing retouched.

First prompt:

[Input]
- Room screenshot: (attached)
- Room area: 18m × 12m, ceiling height 9m (two-story vertical structure)
- Placed enemies: scholar_phantom × 3, water_elemental × 1
- Adjacent room type: lore_room (west), combat_room (east)
- A shallow pool of water inside the room

Pick 3~5 tags that fit this room, only from the dictionary below. Don't invent tags
outside the dictionary; output the tag enums only, comma-separated.

[Tag dictionary, 30 entries]
theme: scholar_theme, ruins_theme, forest_theme, cave_theme,
       crypt_theme, swamp_theme, mechanical_theme, celestial_theme
layout: vertical_layout, horizontal_corridor, open_arena,
        maze_layout, bridge_layout
hazard: water_hazard, fire_hazard, falling_hazard,
        poison_hazard, crush_hazard, dark_hazard
interaction: puzzle_required, lever_activation, key_gate, hidden_passage
narrative: flashback_trigger, dialogue_zone, lore_object_zone,
           ambush_setup, ritual_site, vista_point, rest_anchor

Claude's first output (raw, untouched):

scholar_theme, vertical_layout, water_hazard, ambush_setup, two_story_layout

Two problems are exposed right here. One: two_story_layout is not in the dictionary. The model got pulled by the input phrase "two-story vertical structure" and invented a word outside the dictionary. Two: the tags hit the cap of five, yet vertical_layout and two_story_layout overlap in meaning — two slots spent on the layout category.

The human's rejection call. two_story_layout violates dictionary enforcement, so it is an automatic reject (the pipeline's F gate). ambush_setup is a closer call — three enemies are placed, but from the screenshot it is ambiguous whether this is an ambush composition or just a combat room. The model may have over-interpreted. With the adjacent rooms both lore/combat, the case for a narrative ambush trigger is weak. Rejected.

Second request:

two_story_layout isn't in the dictionary and overlaps with vertical_layout. Drop it.
Drop ambush_setup too — having enemies doesn't make it an ambush.
// (intent: narrative tags only when narrative intent is explicit; plain combat is already expressed by type)
You don't have to fill the empty slots. 3~4 is normal. Tag it again.

Claude's second output:

scholar_theme, vertical_layout, water_hazard

This time it is down to three, all inside the dictionary, with no category duplication. The human accepted the result. That is how the room format's tags: [scholar_theme, vertical_layout, water_hazard] got finalized.

The lesson of this worked example is two lines long. First, AI overfits to one detail of the input ("two-story") and steps outside the dictionary — the dictionary enforcement gate has to catch that at the code level. Second, AI tends to fill empty slots — unless you state "you don't have to fill them," it will try to use all five. Both failures are common, and both fixes are only stable when enforced not by the prompt but by the rulebook (dictionary + cap).

7.1.8 Metadata at Scale — Who Fills It In, Who Reviews It

Filling in one room's metadata by hand takes a designer 5–10 minutes. One dungeon (20–30 rooms) is 2–5 hours; 100 dungeons is 200–500 hours (author's estimate, unverified — an upper bound computed as average entry time per room × room count). Fill it all by hand and the designer becomes a metadata entry slave.

So the work is split by area, each with its own filler.

What designers finalize by hand comes down to reviewing tags and giving final sign-off on difficulty_label. Tools fill in the rest; people review. The point of the automation is to pull designers out of data entry and send them back to the judgment calls — pacing, signature rooms, reuse policy.

7.1.9 Room Reuse and Its Pitfalls

The biggest payoff of the master standard is room reuse. With 30 rooms searchable by tag, you can assemble 5–10 dungeons out of combinations. But as the reuse ratio climbs, dungeons go stale. So reuse ships with guardrails attached.

Reuse is a means of cutting cost, not a goal. The moment the reuse rate itself becomes a KPI, the player experience flattens. At 0% (every room new), production cost explodes; past 70%, dungeons stop being distinguishable from one another. In my experience the 30–40% band is the balance point between cost and variety (a directional observation — the precise threshold differs by project).

7.1.10 Common Failures and Fixes

7.1.11 Layer Decomposition Is the Precondition for Procedural Level Generation

The structure of 7.1.2–7.1.6 — laid out so far as rulebook, generation, validation — is itself a product of Layer decomposition. The general thesis that Layer decomposition is the precondition for procedural generation and automation (L0 anchor → L1 rulebook → L2 body → L3 values → L4 gates; as one lump, generation collapses) was covered in §6.6. Here I apply it to operating level metadata.

Without this separation, room layout, BSP, pacing, and narrative triggers all mix into one file, and every time you move a single room, the pacing intent, the event slots, and the connectivity graph break together. It is the drafting room, the materials warehouse, and the inspection room piled onto one desk — pull out one blueprint and the materials invoice and the inspection sheet come out with it. The AI assist in 7.1.7 worked because of the Layers, too: room IDs and connectivity are filled from the editor (L3 auto-extraction), tags from AI (L1 dictionary enforcement), difficulty_label from summation (L3→L4). Automation sits on Layer boundaries; sit it on a single lump and accidents multiply within the first quarter and the tool itself gets thrown out.

That said, this does not mean you need the full five-drawer cabinet in perfect shape from day one. Separate gradually; keep interfaces narrow. In the first quarter, separating just the L1 rulebook (tag dictionary + connectivity rules) and the L3 sheet (room metadata sheet) already creates a place for automation to enter. The L0 pacing intent and the L4 validation gates get filled in over the quarters that follow. Once the standards are unified, automation has a place to land — and the more automation lands, the more the designer's attention shifts from hand-working one room at a time to judging pacing, signature rooms, and reuse.

Key Takeaways

• The new place for level automation is not the space itself but the operation of the space's metadata.
• Validation must be fixed as a build gate, not left to human attention, or accidents leak into live service.
• AI variation is allowed only within the dictionary the rulebook defines; out-of-dictionary output is rejected by code.

Try It Yourself

setup. Pick one dungeon and build a YAML sheet where each room carries only four fields: room_id · type · connections · tags. First pin the tag dictionary — 5 categories, about 30 enums — on a single sheet of paper.

prompt. Feed in a room screenshot + area + enemy types + adjacent room types, and ask: "pick only 3–5 tags from this dictionary, no tags outside the dictionary, don't fill empty slots" (the exact prompt from 7.1.7).

verify. (1) If the AI output contains a tag outside the dictionary, reject it and ask again. (2) Build a graph from connections and check start→boss reachability and dead ends — if even one violation turns up, mark that room as unbuildable.

Solo Scale-Down

If you are a solo developer with no tooling infrastructure, start the master document as a single markdown page. Thirty lines of tag dictionary, five lines of connectivity rules, five lines of validation checklist — that is enough. For graph validation, if you have 10 rooms or fewer, drawing arrows on paper and eyeballing for dead ends gets you 80% of the effect. The core is not the tool but the habit itself: attach data to rooms, and check that data with rules. Add the tools when you pass 50 rooms and checking by hand becomes too heavy.

Next Chapter Preview

• 7.2 Behavior Tree Editor — running AI behavior trees, the domain adjacent to levels, on rulebooks and metadata

7.2 The Behavior Tree Editor — A Worked Transcript of a Human and AI Editing and Verifying BT json Together

An apprentice mage was glued to the player, swinging a sword. I had designed that NPC as a ranged magic caster. Its HP was paper-thin — one melee hit and it was dead — yet it had no intention of keeping its distance. The build log showed no errors. I reopened the Behavior Tree in the editor; the nodes were all wired up correctly. After an hour of staring at it, I found the cause. The distance condition on the retreat branch was 0.5 instead of 5. The NPC was supposed to flee when an enemy came within 5 meters, but at 0.5 meters — practically point-blank — the retreat branch never fired.

One number. In the graphical node editor, that number was visible only when you expanded the node's inner panel, and it left nothing in the change history. There was no way to trace who changed that value, or when. From that day on, my Project A started handling Behavior Trees as json rather than graphics. This chapter is the record of one cycle in which a human and AI edit that json together and a machine verifies it automatically.

7.2.1 Where the Behavior Tree (BT) Slips Out of Your Hands

The Behavior Tree is the de facto standard structure for defining an enemy NPC's combat, movement, and reactions. A selector tries branches in priority order; a sequence chains conditions and actions in order. The structure itself is simple. The problem is scale.

On my Project A, a single enemy NPC's BT ran roughly 50–200 nodes, and we operated more than 100 NPCs. Multiply those out and the total BT node count reaches tens of thousands. At that scale there comes a moment when no human can answer the question, "If I change this retreat pattern, which NPCs are affected?" It is like having a hundred notebooks spread open on your desk: fix one line in the first volume, then try to trace by eye where it bleeds into the other ninety-nine.

When I moved from graphical BTs to json, I demanded four things.

The built-in BT editors in commercial game engines integrate easily and offer strong visual debugging. They do, however, tend to store BTs as binary assets, which weakens text diffs and change-impact tracking. Project A assumed a live game operating more than 100 BTs, so we chose to develop our own json BT format and editor. Let me be clear: this is not the right answer for every team. If you operate fewer than 50 BTs, sticking with the engine's built-in editor is almost always cheaper. I come back to the justification for in-house development at the end of this chapter.

7.2.2 BT json — One Enemy's Behavior as Text

Start with what the result looks like. Below is part of the BT for a ranged-support NPC of the Scholars' Guild. Two things are key: every behavior is text, so git can track it line by line, and common patterns are referenced via subtree_ref.

{
  "bt_id": "bt_scholar_archer_v3",
  "category": "ranged_combatant",
  "tags": ["scholar_faction", "ranged", "support"],
  "description": "Scholars' Guild ranged support type. Keep distance + retreat first.",
  "root": {
    "type": "selector",
    "children": [
      {
        "type": "sequence",
        "name": "low_hp_retreat",
        "children": [
          {"type": "condition", "fn": "hp_below", "param": 0.3},
          {"type": "subtree_ref", "id": "subtree_retreat_to_ally"}
        ]
      },
      {
        "type": "sequence",
        "name": "kite_pattern",
        "children": [
          {"type": "condition", "fn": "enemy_in_close_range", "param": 5},
          {"type": "action", "fn": "move_away", "param": {"distance": 8}}
        ]
      },
      {"type": "subtree_ref", "id": "subtree_ranged_attack_pattern"}
    ]
  }
}

Unfolded as a diagram, the tree is a selector trying three branches from the top. Note that the bug from the opening — whether the param of enemy_in_close_range is 5 or 0.5 — becomes a single line you can see at a glance in json.

flowchart TD
    R["selector
(priority from the top)"]
    R --> A["sequence: low_hp_retreat"]
    R --> B["sequence: kite_pattern"]
    R --> C["subtree_ref:
subtree_ranged_attack_pattern"]
    A --> A1["condition: hp_below 0.3"]
    A --> A2["subtree_ref:
subtree_retreat_to_ally"]
    B --> B1["condition: enemy_in_close_range 5"]
    B --> B2["action: move_away dist=8"]

    style C fill:#e8f0fe,stroke:#4285f4
    style A2 fill:#e8f0fe,stroke:#4285f4
    style B1 fill:#fce8e6,stroke:#ea4335

The node painted red, enemy_in_close_range 5, is the one that ate an hour of a human's time in the opening. In json, a single code review catches it.

7.2.3 The subtree Library — Reference Instead of Copy-Paste

Across the behaviors of more than 100 enemies, recurring chunks appear: "retreat behind an ally," "retreat to cover," "ranged attack pattern," and the like. Copy-paste those into every BT, and fixing one piece of retreat logic means hand-hunting a hundred places. So common patterns are split off into separate subtree files and only referenced via subtree_ref.

subtree_library/
├── retreat_patterns/
│   ├── subtree_retreat_to_ally.json
│   ├── subtree_retreat_to_cover.json
│   └── subtree_retreat_random.json
├── attack_patterns/
│   ├── subtree_ranged_attack_pattern.json
│   ├── subtree_melee_combo.json
│   └── subtree_aoe_attack.json
└── reaction_patterns/
    ├── subtree_react_to_ally_death.json
    └── subtree_react_to_player_taunt.json

Set up this way, "who is affected if I change this subtree?" becomes the output of a script, not a human's guess. The impact tracker is simple: open every BT and collect the bt_id of each BT that references the subtree in question.

# bt_impact_tracker.py
import json, glob

def has_subtree_ref(node, target_id):
    if isinstance(node, dict):
        if node.get("type") == "subtree_ref" and node.get("id") == target_id:
            return True
        for child in node.get("children", []):
            if has_subtree_ref(child, target_id):
                return True
    return False

def find_affected_bts(subtree_id):
    affected = []
    for bt_file in glob.glob("bts/*.json"):
        bt = json.load(open(bt_file, encoding="utf-8"))
        if has_subtree_ref(bt["root"], subtree_id):
            affected.append(bt["bt_id"])
    return affected

# usage
affected = find_affected_bts("subtree_ranged_attack_pattern")
# → ["bt_scholar_archer_v3", "bt_ranger_v2", "bt_sniper_v1", ...]

On Project A we wired this function into the pull request (PR) stage. When someone touches a subtree file, the list of affected BTs is automatically posted as a PR comment. Before the merge, the reviewer sees that "one changed line in a retreat pattern alters all 12 ranged enemies."

7.2.4 Worked Transcript — One Cycle of AI Drafting a New BT

This is where the chapter carries the most weight. I hand the BT draft for a new enemy NPC, an "apprentice mage," to AI, then reproduce — unpolished, exactly as it happened — one cycle of a human verifying, rejecting, and re-requesting that output. There is a reason I do not smooth it over: what the AI got wrong on its first output, and the texture of that failure, is everything this chapter is trying to convey.

Step 1 — The Human's Prompt (Full Text)

[Enemy NPC concept]
Apprentice mage of the Scholars' Guild. Low HP, high magic damage.
Avoiding melee comes first. Retreat behind an ally, then attack with magic.

[category] ranged_combatant

[Reference BT] bt_scholar_archer_v3
(Similar structure. But replace the bow attack with a magic attack)

[Defined function enum]
condition: hp_below, enemy_in_close_range, ally_nearby, mana_below
action: move_away, cast_spell, retreat, wait
subtree_ref id (available list):
- subtree_retreat_to_ally
- subtree_ranged_attack_pattern   # Bow-based. Not for magic
- subtree_magic_attack_pattern

Write only the BT root node json for this concept. Use subtree_ref as much as possible, keep direct nodes minimal,
functions only from the enum above. Do not add behaviors not in the concept. json only, no explanation.

Step 2 — Claude's First Output (Verbatim, Unedited)

{
  "bt_id": "bt_scholar_apprentice_v1",
  "category": "ranged_combatant",
  "tags": ["scholar_faction", "magic", "fragile"],
  "description": "Scholars' Guild apprentice mage. Avoid melee + retreat behind ally + magic attack.",
  "root": {
    "type": "selector",
    "children": [
      {
        "type": "sequence",
        "name": "low_hp_retreat",
        "children": [
          {"type": "condition", "fn": "hp_below", "param": 0.4},
          {"type": "subtree_ref", "id": "subtree_retreat_to_ally"}
        ]
      },
      {
        "type": "sequence",
        "name": "avoid_melee",
        "children": [
          {"type": "condition", "fn": "enemy_in_close_range", "param": 6},
          {"type": "action", "fn": "move_away", "param": {"distance": 10}}
        ]
      },
      {
        "type": "sequence",
        "name": "mana_recover",
        "children": [
          {"type": "condition", "fn": "mana_below", "param": 0.2},
          {"type": "action", "fn": "wait", "param": {"frames": 120}}
        ]
      },
      {"type": "subtree_ref", "id": "subtree_ranged_attack_pattern"}
    ]
  }
}

Step 3 — Human Verification and Rejection

I ran the output through lint (covered in the next section) and read it with my own eyes. Three things snagged.

1. The last branch is wrong. subtree_ranged_attack_pattern is a bow-based attack pattern. Even though the enum comment said "not for magic," the AI pulled in the bow pattern with the similar name. The apprentice mage should use subtree_magic_attack_pattern. — Rejected.

2. It added behavior not in the concept. The mana_recover branch (mana_below → wait 120frame) is a behavior with not a single line in the concept. The prompt nailed down "do not add behaviors not specified," yet the AI apparently judged that "a mage would naturally manage mana" and slipped it in. Plausible, but a spec violation. — Rejected.

3. The retreat threshold is suspect. hp_below 0.4 starts retreating earlier than the reference BT (0.3). The apprentice mage is indeed more fragile, so it could be intentional. But the AI never gave a rationale, so this is the designer's call. — On hold, pending designer confirmation.

Step 4 — The Human's Follow-Up Request

Fix just three places. The last branch, subtree_ranged_attack_pattern, is the bow pattern,
so swap it for subtree_magic_attack_pattern; the mana_recover branch is not in the concept, so delete it entirely;
and revert hp_below 0.4 to the reference BT (0.3) — if there is a rationale for 0.4, put it in the description in one line.
Keep the rest as-is, json only.

Step 5 — Claude's Second Output (Revised)

{
  "bt_id": "bt_scholar_apprentice_v1",
  "category": "ranged_combatant",
  "tags": ["scholar_faction", "magic", "fragile"],
  "description": "Scholars' Guild apprentice mage. Avoid melee + retreat behind ally + magic attack. Low HP, so retreat threshold kept at 0.3 (same as archer).",
  "root": {
    "type": "selector",
    "children": [
      {
        "type": "sequence",
        "name": "low_hp_retreat",
        "children": [
          {"type": "condition", "fn": "hp_below", "param": 0.3},
          {"type": "subtree_ref", "id": "subtree_retreat_to_ally"}
        ]
      },
      {
        "type": "sequence",
        "name": "avoid_melee",
        "children": [
          {"type": "condition", "fn": "enemy_in_close_range", "param": 6},
          {"type": "action", "fn": "move_away", "param": {"distance": 10}}
        ]
      },
      {"type": "subtree_ref", "id": "subtree_magic_attack_pattern"}
    ]
  }
}

The second output passed lint; in designer review we nudged the avoid_melee distance 6 down a notch to 5 to match the archer, then sent it on to the simulation gate. The lesson here is clear. AI fills in a BT's skeleton fast, but it commits two accidents almost every time: pulling in the wrong subtree with a similar name, and slipping in plausible extra behavior with no spec behind it. Only human eyes and the lint gate catch these two. That is why AI output is a draft, not a final.

7.2.5 Automated lint — The Machine Catches What Humans Miss, First

BTs connect directly to the player experience. Ship the bug where an enemy will not flee at point-blank range, and it comes back as review scores. So before the merge, the machine checks first.

The last row is what makes this lint unusual. If the five BTs grouped under the same ranged_combatant drift far apart in average simulated response time, that is a signal that someone silently broke one enemy's balance. It is a device that catches, with statistics, the "vibe" that static checks cannot.

After static lint comes simulation verification. Run the BT 1,000 times in a simulator — no actual game build required — and pull the statistics.

Without baking a build, you can see within 5–10 minutes whether this BT dies too fast or keeps repeating a single behavior. If an anomaly shows, fix the json and re-run the sim. The real gain of going json is that this cycle shrinks from days to minutes.

flowchart LR
    P["Human/AI
edits BT json"] --> L{"Static lint"}
    L -->|block| P
    L -->|pass| R["Designer review"]
    R -->|reject| P
    R -->|approve| S{"1,000 sim runs"}
    S -->|anomaly| P
    S -->|normal| M["Merge + build"]
    style L fill:#fef7e0,stroke:#fbbc04
    style S fill:#fef7e0,stroke:#fbbc04
    style M fill:#e6f4ea,stroke:#34a853

7.2.6 Measurement — What Shrank

Here is Project A before and after adoption, as a table. The absolute figures vary with team size and game genre, so they are the author's estimates (unverified). The direction and the ratios, however, are exactly what we observed in live operation.

What matters most is that the last two rows moved at the same time. Normally, cut headcount and quality drops. Here, the number of designers went down and incidents went down with it — because the machine took over the change-impact tracking and verification that people had been doing by hand. The value of automation lies less in "faster" than in this "smaller and better at once."

7.2.7 Build In-House, or Borrow?

If this chapter leads you to conclude "we should build a json BT editor too," that is the wrong takeaway. Project A chose in-house development because a specific set of conditions lined up.

Project A picked option 3 for four reasons.

• Diff and git tracking were mandatory — the built-in BT is a binary asset, so the "one number" incident from the opening could not be traced.
• Subtree referencing and automatic impact tracking were core to operations — features standard BT tools are weak at.
• We had to run simulation verification in a runtime decoupled from the build.
• We assumed AI-assisted authoring — a text (json) format is overwhelmingly friendlier to a large language model (LLM).

Development cost: 1–2 months. It pays back only when operated BTs reach 100–300 and the live ops period runs long. At a scale of 30–50, it does not pay back. The return on investment (ROI) of in-house development materializes only when both scale and operating period are assured. If your team is small, take only the principles from this chapter — store as json, reference via subtrees, pass AI output through the lint-plus-review gate — and run your tooling on top of the built-in editor or an external library.

7.2.8 Common Failures

Key Takeaways

• Store BTs as json so the "one number" incident lands in a git diff and can be traced.
• Subtree referencing and automatic impact tracking keep 100-NPC operation out of copy-paste hell.
• AI fills in a BT's skeleton fast, but humans catch the wrong references and the out-of-spec behaviors.

Try It Yourself

This is the smallest cycle a small team can try today.

setup — Write out the BT of one enemy NPC you currently operate as json, by hand (bt_id, category, tags, root). Pull one common retreat or attack pattern out into subtree_library/ and reference it with subtree_ref.

prompt — Hand a similar new enemy to AI. Use the prompt skeleton from the worked transcript above as-is: concept + category + reference BT + available function enum + "no behaviors not specified" + "json only."

verify — Merge AI output only after it passes three gates: (1) a lint that filters out functions outside the enum and nonexistent subtrees, (2) human eyes, (3) a simulation or a short in-game check. Always confirm whether the AI slipped in "a wrong subtree with a similar name" or "plausible out-of-spec behavior."

Solo Scale-Down

If you have no capacity to build an editor, your tools are a text editor, git, and one 30-line bt_impact_tracker.py — that is enough. Export a BT built in the engine's editor to json once, commit it to git, and split only the subtrees into separate files to reference. Hook the impact tracking script into a commit hook, and even working alone you can see which enemies change when you touch a retreat pattern — as output, not as a guess. This one habit alone shrinks the opening's "one number, one hour" down to a single line in code review.

Next Chapter Preview

• 7.3 The Dungeon and Field Pattern Library — combining room metadata with subtree patterns to bundle levels into operational units.

7.3 The Dungeon and Field Pattern Library

At a dungeon review, a junior level designer put one of their dungeons up on the screen. A narrow corridor, a fast enemy closing in from behind, a dodge decision at the junction. It was a well-made dungeon. The problem was that it was subtly different from what we had already built in eleven other dungeons. The enemy's pursuit speed, the timing of the trap going off, the moment the junction appears. Not one of them was the same. The junior designer believed they had built an experience with the same name — "pursuit dungeon" — but the sensation players received differed from dungeon to dungeon.

What we decided that day was simple. Define the "corridor pursuit" experience precisely, once, and pin that definition down. The next time someone builds a pursuit dungeon, they don't compose it from scratch — they pull out the codified definition and use it. That was the beginning of the pattern library.

If the room is the unit of space and the Behavior Tree is the unit of behavior, the pattern is the operational unit that binds space, behavior, and events into one. When a single pattern is reused across several dungeons, the production load drops — and more importantly, the experience players receive stays consistent across dungeons.

7.3.1 The Pattern as an Operational Unit

Think of a recipe in a cookbook — the analogy is exact. One recipe card holds the ingredients, the cooking steps, the heat level, and a photo of the finished dish. Even when the restaurant changes, following the same recipe produces the same taste. Each restaurant is allowed a little variation, though. A pattern is the same. Space (the rooms), behavior (the BT subtrees), incidents (the events), outcomes (reward and difficulty), and the designer's statement of intent go in as one bundle.

Once a pattern is defined, the same experience can be built consistently in every dungeon — the way a recipe proven once delivers the same taste across many restaurants. Still, even with the same recipe, each restaurant keeps a little variation. How that variation is managed is half of pattern operations. The overrides covered later are where it lives.

7.3.2 The Pattern Composition Flow

The heart of a pattern library is this: patterns are codified into a rulebook first, and dungeons are then generated by combining them. The designer does not compose a dungeon on a blank screen; they pick verified patterns, place them, and vary only a part.

flowchart TD
    A[Observe a good experience moment in the game] --> B[Decompose into space · NPCs · events]
    B --> C[Map to room templates · subtrees]
    C --> D{Pass simulation + user testing?}
    D -- No --> B
    D -- Yes --> E[Register the pattern in the library
usage_count = 0]
    E --> F[(Pattern library
5 categories · 30–50 patterns)]
    F --> G[Dungeon design: invoke pattern instances]
    G --> H[Placement + variation overrides]
    H --> I{Variation ratio 20% or less?}
    I -- Yes --> J[Dungeon complete
pattern usage_count +1]
    I -- No --> K[Consider splitting off as a separate pattern]
    K --> B
    J --> L[Pattern impact tracking
one pattern edit → auto-tally of dungeons using it]
    L --> F

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    class L code;
    class F data;
    class J pass;

The left half of this flow (observe → decompose → map → verify → register) is the process of making a pattern; the right half (invoke → place and vary → complete → track) is the process of consuming one. Making happens rarely; consuming happens often. When the library is run well, this asymmetry turns into production efficiency.

7.3.3 The Five Base Categories

My Project A is in the action-RPG lineage, so it sorts patterns into five categories. This taxonomy is genre-dependent. A horror game would weight ambushes and narrative beats differently; a puzzle game would put environment-driven combat at the center. Don't treat the taxonomy itself as absolute — decide first what your game's core experiences are, then draw the categories.

Within the five categories, the pattern count stays roughly between thirty and fifty. There is a reason for that number. Past a hundred patterns, a designer can no longer hold the whole library in their head. At that moment the library becomes a warehouse that takes time to search, and the designer chooses to compose from scratch instead. Once the library starts being shunned, the original goal — consistency — collapses. That is why consciously managing the cap on pattern count matters as much as category design.

7.3.4 The Format for Pinning a Pattern Down

A single pattern is pinned down as one YAML file. Below is the format actually used on Project A, anonymized. The company-specific asset names and dungeon numbers are masked, but the field structure and the way it is operated are unchanged.

---
pattern_id: pattern_corridor_pursuit_v2
category: pursuit
description: A fast enemy pursues from behind in a narrow corridor; the player makes a dodge decision at the junction
tags: [horizontal_corridor, scholar_theme_compatible]
rooms:
  - room_template: corridor_long
    size: medium
    connections_required: 2
  - room_template: junction_3way
    size: small
    connections_required: 3
npc_behaviors:
  - subtree_ref: subtree_aggressive_chase
    count: 2
  - subtree_ref: subtree_ranged_support
    count: 1
events:
  - type: trap_activation
    trigger: room_1_midpoint
  - type: enemy_spawn
    trigger: room_1_entry
difficulty_modifier: 1.2   # 1.2x load relative to a standard room
reward_modifier: 1.3
clear_time_estimate_sec: 60
art_pack_compatible: [scholar_library, generic_dungeon]
narrative_slots:
  - slot: dialogue_during_chase
    constraints: [short_dialogue, fear_emotion]
usage_count: 12            # used in 12 dungeons
last_modified: 2026-05-18
deprecated: false
---

This one file defines a piece of each of twelve dungeons at once. That is where the weight of the single line usage_count: 12 comes from. Editing this pattern means twelve dungeons are affected simultaneously — so touching a pattern file carries a different weight than fixing one room.

References like subtree_aggressive_chase and subtree_ranged_support point directly to subtrees defined in the Behavior Tree editor of 7.2. The key is that a pattern only references the BT rather than embedding it. Fix a BT, and every pattern referencing that BT follows automatically. Space (room templates) and behavior (subtrees) are managed in their own libraries; the pattern serves only as the combination table that ties the two together. Numbers like clear_time_estimate_sec and difficulty_modifier are operational values from my environment, not universal constants. Measure them yourself, with your own game's simulation and user testing, and fill them in.

7.3.5 Instantiating a Pattern into a Dungeon

When designing a dungeon, you do not compose patterns from scratch. You invoke one from the library, specify where it goes, and cover only what differs in this dungeon with overrides.

---
dungeon_id: dungeon_021_silvermark_library
pattern_instances:
  - instance: corridor_pursuit_1
    pattern_id: pattern_corridor_pursuit_v2
    placement:
      - room_id: dungeon_021_room_03
        as: corridor_long
      - room_id: dungeon_021_room_04
        as: junction_3way
    overrides:
      - field: npc_behaviors.0.subtree_ref
        value: subtree_scholar_chase   # scholar-theme variant
      - field: events.0.trigger
        value: room_1_2nd_third         # fine-tune trigger position
---

Here dungeon 021 uses the "corridor pursuit" pattern as is, but swaps the pursuing enemy from the generic one to a scholar-theme variant, and moves the point where the trap goes off from the middle of the corridor slightly back. 80% of the pattern stays; only 20% is varied.

That ratio has grounds drawn from operating experience. Too little variation (near 0%) and the dungeons feel stale, as if copied from one another. Too much (past 50%) and it is no longer the same pattern. You believe you invoked the same pattern, but the actual experience is completely different — right back to the situation of the dungeon that junior designer brought in. So we keep an operating rule: when one instance's overrides exceed half of the pattern's fields, that is not variation; it is the signal of a new pattern. It's time to split it off as its own.

7.3.6 What Shakes When You Change One Line

Edit pattern_corridor_pursuit_v2 and twelve dungeons are affected. Track that by hand and you will, without fail, miss one or two. So we keep a small tool that automatically sweeps the relationships between patterns and dungeons.

# pattern_impact.py
import json
from glob import glob

def find_dungeons_using(pattern_id):
    affected = []
    for d in glob("dungeons/*.json"):
        dungeon = json.load(open(d, encoding="utf-8"))
        for inst in dungeon.get("pattern_instances", []):
            if inst["pattern_id"] == pattern_id:
                affected.append({
                    "dungeon": dungeon["dungeon_id"],
                    "instance": inst["instance"],
                    "has_overrides": bool(inst.get("overrides")),
                })
    return affected

In the list this function returns, the key is the has_overrides flag. Dungeons without overrides use the pattern as is, so they are safe to update automatically. Dungeons with overrides may have variations of their own that collide with the pattern edit, so they need an additional human review.

Instead of a human feeling out the weight of each edit one by one, the tool reports within 5 minutes: "this edit affects 12 dungeons, and 4 of them carry variations, so look at those directly." Reducing the fear of changing a pattern is this tool's real value. When the blast radius is invisible, designers avoid touching patterns at all, and the library goes stagnant.

7.3.7 How Patterns Are Born, and Where AI Fits

Let me face the question I get most often here head-on. "Can't we just have AI write the patterns too?"

The answer is clear. No. Writing a single pattern has the designer's insight as its spine. What makes a good pursuit experience, why the junction has to be there, why the trap has to fire at the 2/3 point of the corridor rather than the middle for the tension to hold — these are the judgments of someone who has handled the game directly and watched how players respond. Have AI compose patterns from scratch, and every pattern converges to a bland, average shape. The library fills up with "patterns that aren't wrong" while "patterns that get remembered" disappear.

That doesn't mean AI has nothing to do. Of the five steps of pattern authoring, AI is a powerful assistant at two of them.

Step 3 is the heart of AI assistance. When a designer writes down a draft — "a fast enemy pursues from behind in a narrow corridor" — it is inefficient for a human to comb through room template and subtree libraries that have already grown to dozens of entries each to find what fits that intent. This is where you have AI recommend mapping candidates. Below is the prompt actually in use, anonymized.

[Input]
- The designer's draft pattern yaml (attached below)
- Room template library (list of names + tags + sizes)
- subtree library (list of names + behavior summaries)

Pick and recommend room templates and subtrees from the library to implement this pattern.
2~3 each, with a fitness score of 1~5 and a one-line rationale based on tags and size.
Don't invent anything that isn't in the library — recommendations only; if everything is 3 or below, tell me new authoring is needed.

Here is the output Claude actually returned for this prompt. I reproduce it without touching a single character, so you can see exactly where it hesitates and where it asserts.

Room template candidates:
1. corridor_long  (fitness 5)
   Rationale: tag horizontal_corridor matches; size medium fits the "narrow corridor" intent.
2. corridor_narrow_short  (fitness 3)
   Rationale: narrow, but too short to secure pursuit distance. Not enough room to place a junction.
3. hall_wide  (fitness 1)
   Rationale: a wide hall is the exact opposite of the "narrow corridor" intent. The pursuit pressure does not hold.

subtree candidates:
1. subtree_aggressive_chase  (fitness 5)
   Rationale: rear-pursuit behavior is defined, with a movement-speed weight.
2. subtree_ranged_support  (fitness 3)
   Rationale: not pursuit itself, but one unit can be placed as pressure support.
3. subtree_patrol_basic  (fitness 2)
   Rationale: patrol behavior does not match the pursuit intent. No pursuit-transition node after the trigger.

Junction room template:
I could not find an entry in the library that satisfies both the 3way junction
and the small size condition at the same time. junction_3way is the closest, but its size tag is empty,
so the fitness cannot be confirmed. Designer confirmation is needed.

The last paragraph is the most valuable part of this output. The AI said it was "not certain" about the junction room template, and it did not invent an answer that wasn't there. Receiving this report, the designer discovered that the size tag of junction_3way really was empty, and filled in that metadata first. Had the AI ignored the empty tag and assigned a fitness score of 5, the designer would have adopted it on misplaced trust.

This is the correct shape of AI assistance. The AI spreads out candidates and marks uncertainty; the choice and the responsibility stay with the designer. When every mapping comes back with low fitness, a separate task — writing a new template — is created, and that writing is once again a human's job.

[Directional signpost — compressing patterns into an "experience vector" (still premature)] Read this as a research trend, not a prescription. §7.3.1 already calls a pattern a "recipe." A pattern is close to a coordinate value — room meta, behavior subtree, event, difficulty/reward_modifier, and clear_time bundled as one. Compress that bundle into an "experience vector," and instead of combing through the flow above entry by entry when every fitness score comes back low, you could locate the new pattern as an empty region of the compressed space; the deprecated verdicts of §7.3.8 could likewise be reinforced by reading near-duplicates as coordinate distance. Three caveats attach. difficulty/reward_modifier are, as §7.3.4 says, my operational values — the axis scales differ per game, so the compressed space cannot be transplanted as is; interpolation goes only as far as "flagging" the blank, not "generating" the pattern; and actually composing the pattern on top of that flag still does not cross this section's principle that the designer's insight is the spine. The idea sits in the same spot as the dimensional-vector compression of §8.2.7, and the conceptual intuition is in Appendix M — left as territory for a team with foundations well laid to look into a few years from now.

7.3.8 Retiring Unused Patterns

A library is harder to empty than to fill. Operate one for about a year and patterns pile up that were made but almost never used. Leave them and the cost of searching the library climbs, and designers have to wade past dead options every time they pick a pattern. So we retire them regularly.

The key point is that deprecation is not deletion. Dungeons already using the pattern stay as they are. Touching dungeons running in a live service is riskier than blocking a new pattern. deprecated: true is only a sign that says "don't start using this from now on," not an order to erase the past.

Just as you pull the unused tools out of a desk drawer once a quarter and sort them, put a once-a-quarter retiring pass for the library on the calendar. Without that schedule, the library swells in one direction only, and at some point it becomes a warehouse designers turn away from.

7.3.9 Measuring the Effect Honestly

These are the changes I observed over one year of operating the pattern library on my Project A. The time figures in the table below are estimates from my environment (unverified); only the direction and the relative ratios were actually observed.

The most striking change is the second-to-last row: onboarding new designers. The pattern library unintentionally took on the role of a design textbook. Once a new designer could read "this is how this game builds its pursuit experience" from a single pattern file and understand it, the time a senior spent sitting beside them explaining dropped sharply. The problem of the mismatched dungeons that junior designer first brought in was, in the end, resolved by the library itself.

The figure "about 8 dungeons using each pattern on average" means the same pattern was reused eight times, and that is the honest yardstick of production efficiency. But this value of 8 is bound to my game's dungeon scale and pattern design. In a game with few dungeons, or one that demands a wholly different concept every time, this value comes out far smaller.

7.3.10 The Decision Not to Build a Library

Finally, honesty demands a point that overturns this entire chapter. A pattern library is not a cure-all. There are clearly environments where the cost of building and operating one is never recovered.

The library's ROI (return on investment) is recovered only when three conditions hold together: there is live ops, there are three or more designers, and the dungeon count passes twenty. That is why a live-service MMORPG is the archetypal fit. If your project lands on any row of the table above, stop before building a library and think again. A tool has value only where there is a problem — and for a five-dungeon project, a pattern library costs more than the problem.

7.3.11 Common Failures and Remedies

The second and fourth rows of this table trip teams up most often. Skip automating impact tracking and designers grow afraid of editing patterns, so the library hardens; delegate authoring to AI and the library converges to the average. Both failures kill the library's lifeblood — the reuse of verified experiences.

7.3.12 Closing Part 7

Part 7 stacked the level discipline up in three tiers. 7.1 set the standards for room metadata, tags, and connectivity (space); 7.2 covered the json-based Behavior Tree editor, subtrees, and simulation (behavior); and this chapter arrived at the pattern library, which bundles those two together with events for reuse (the operational unit). The through-line of all of Part 7 is this: in an operation that handled space and behavior separately, the same decision in the same place wobbled into a different shape every week — and that problem was solved by pinning it down in the bundle called a pattern.

This flow meshes directly with Layer integration. The vision — the spatial tone of the whole game — sits on top; below it sit the systems, the level generation rules and BT rules; rooms, BTs, and the pattern library form the content layer; dungeon instances and pattern usage statistics accumulate as data; and lint, simulation, and user telemetry verify it all at build/QA. Among these five layers, the pattern library is the spine of the content layer — and at the same time the connecting link that follows the system rules above it and generates the data statistics below it.

Key Takeaways

• A pattern is the operational unit that bundles space, behavior, and events; handle the three separately and the same experience wobbles differently every week
• 80% reuse + 20% variation is the recommended ratio; when variation passes half, that is the signal of a new pattern
• Pattern authoring is the place for designer insight; AI goes only as far as recommending mapping candidates and assisting simulation

Next Chapter Preview

• 8.1 Operating CombatBalance · CombatFormula — The Two-Document Split of Balance Design

Try It Yourself — Pin Down One Pursuit Pattern

setup

1. Create two directories, patterns/ and dungeons/, in your working folder.
2. Prepare a file each for your room template names and subtree names, one name per line of text. (If you don't have a library yet, starting with 5 made-up names each is fine.)
3. Save pattern_impact.py from the body text as is.

prompt

The designer writes the draft pattern yaml directly (this part is the human's job). Then hand only the mapping to the AI. Use the mapping prompt from the body text as is, attaching your own draft and the two library lists as input. Do not leave out the two key constraint lines.

- Do not invent new templates that are not in the library. Recommendations only.
- If all fitness scores are 3 or below, state explicitly that new authoring is needed.

verify

1. Check line by line that the AI did not invent template names that are not in the library.
2. See whether each fitness score carries a rationale based on tags and size. Do not trust a score without a rationale.
3. Instantiate the pattern into 2 or more dungeons, run find_dungeons_using("pattern_..."), and confirm that exactly those two dungeons are caught.

Solo Scale-Down

If you are building a small game alone, a library system is overkill. Instead, pick the one dungeon segment you like most and write that experience down as a single yaml file — that alone is enough. When you build the next dungeon, open that one file, copy it, and change only 20%. The essence of a pattern library — the reuse of verified experiences — works even in a single file. When the scale grows, add the categories and the tracking tool then.

Part 8 · Balance Design

8.1 The Combat Balance Formula — The Seat of the Rulebook Called Determinism

Learning Goals for This Chapter (difficulty 🟡 practitioner · prerequisites: basic arithmetic and spreadsheet math): Separate combat balance into a formula seat and a numbers seat, and use two properties — determinism and traceability — to tell how far AI can be trusted and where humans must lock things down as a rulebook.

At 2 a.m., an alert came in: the tank class's survival rate on the live server had hit 89%. No tank was failing to finish a boss, and far too many tanks simply weren't dying. I open the data sheet looking for traces of whoever touched it. One line of the defense factor catches my eye: DEF / (DEF + 1000). Nowhere in the sheet does it say when, by whose hand, or on what grounds that 1000 came down from 1200. A hunt begins — through chat logs, through build history — that ends only when it reaches the memory of a balance designer who left the company three years ago.

Anyone who has run combat balance on a live game goes through this scene at least once. And the real cause of the scene is not that the number 1000 was wrong. It is that the number lived in the formula's seat, while the history of the formula changing existed nowhere. The combat balance formula is the domain of a game that must be the most deterministic, and the most traceable. Why these two properties become the reason AI must not be let into this seat is the spine of this chapter.

One line for non-specialists. If the z-scores, simulations, and curves in this part feel unfamiliar, that's okay. The single thing to take away is this — "Where a rule (a formula) must return the same output for the same input, AI does not go in." The judgment that separates the seats that need determinism from the seats that need exploration carries straight over to any job that handles rules that must not be wrong — accounting policies, settlement logic, contract clauses. You can take the math itself slowly, starting at 8.1.2.

8.1.1 The Formula Is a Rulebook

Do game design long enough and two kinds of documents settle into your hands: the ones that change often, and the ones that almost never do. In combat balance, the side that almost never changes is the formula. "How is damage calculated" gets touched once or twice a quarter; "what is this character's attack power" gets touched five or six times a week. Bind two flows of such different frequency into one file, and the hands that open it daily end up tearing the paper that should only open once in a while.

On Project A, which I run, combat balance is split into two seats: the formula's seat (called CombatFormula here) and the numbers' seat (CombatBalance). Here is one line that lives in the formula's seat, quoted as is.

final_damage = base_damage × dmg_multiplier × (1 − defense_factor) × variation

  base_damage    = skill_base × ATK × skill_coeff
  defense_factor = DEF / (DEF + 1000)
  variation      = uniform(0.95, 1.05)

This formula is a rulebook. Think of a board game's rules. The rules say "move as many spaces as the die shows"; they do not say "this round, if your luck is good, you may go a bit farther." Same input, same output — always. That is determinism. Put in an attack of 180, a defense of 80, and a skill coefficient of 2.1, and the same damage must come out no matter when, where, or how many times you compute it. If the same input ever produces a different output, you don't have a balance tool — you have a slot machine.

This single property, determinism, is the first reason AI must not enter this seat. We will come back to it shortly. First, let's look at what a formula has to look like to deserve the name rulebook.

The core of a combat formula does not end with one damage line. At least three lines live as a set.

# Damage
final_damage = base_damage × dmg_multiplier × (1 − defense_factor) × variation

# Critical hit
crit_damage  = final_damage × crit_multiplier
crit_chance  = base_crit + (LUK × 0.1)            # cap 50%

# Healing
heal         = base_heal × healing_power × (1 − sickness_factor)

There is a reason these three lines are written as a code block rather than prose. Natural language leaves room for interpretation. "Higher defense reduces damage" does not say whether the reduction is linear or curved, or where it stops. DEF / (DEF + 1000) reads exactly one way. A rulebook's job is to drive the room for interpretation down to zero.

8.1.2 The Curve Defines the Determinism

The single line of the defense factor, DEF / (DEF + 1000), holds this game's entire balance philosophy. Graph it and you can see why. The horizontal axis is defense; the vertical axis is the fraction of incoming damage it removes.

The curve approaches its asymptote slowly. At 1000 defense it cuts damage exactly in half, and beyond that, no amount of defense ever reaches 100%. The impossibility of invincibility is built into this one line. Had it been linear, like the gray dashed line, 1000 defense would block all damage, and anything above that crosses into the nonsense territory of negative damage — healing from getting hit. That is why linear was not adopted.

Now go back to the 2 a.m. incident. Suppose someone raises this 1000 to 1200. The whole curve shifts right. The same defense now blocks less damage, so every tank in the game gets weaker and damage dealers' damage per second goes up. One constant in the formula shakes the entire game. The blast radius is nothing like changing a single number — one character's attack power. That difference is why formulas and numbers must live in separate seats, and why a formula change must always carry its history.

8.1.3 Every Formula Change Carries a History

The 2 a.m. hunt was hell for exactly one reason: there was no change history. On Project A, changing a formula is not the act of editing a line of code — it is the act of recording one decision. A separate document named CombatFormula_Decisions travels alongside the formula, and an entry reads like this.

## Decision D17 (2026-04-22)
- Change: defense_factor from DEF/(DEF+1000) → DEF/(DEF+1500)
- Reason: Tank survival rate 89% in the high-level range (LV40+) (live measurement). Cause of boss fights dragging on.
- Attempt 1: Simulated with 800 → tank death rate spiked, many full wipes within 1 minute of boss entry → rolled back
- Attempt 2: Simulated with 1200 → survival rate 75% → decent but above target (60~70%)
- Attempt 3: Adopted 1500 → simulated survival rate 65% (within target range)
- Affected atoms: combat_defense_formula, combat_tank_class_balance
- Follow-up measurement (1 week): live survival rate 67% (+2% vs. simulated prediction of 65%, within range)

This one entry answers the "why is it like this" question six months later. More important, attempts 1 and 2 survive. When the record shows why 800 failed and why 1200 was not adopted, the next person does not repeat the same mistakes. When a new balance designer joins, a stack of these decision logs is the best onboarding material there is.

One thing needs saying honestly here. The simulation figures in attempts 1–3 above (the death rates, the 75% and 65% survival rates) are the author's estimates (unverified), shown to illustrate the flow of operations. Every real game has its own curve and its own target range. But the structure — every change carries attempts, every attempt carries simulation evidence, every adoption is followed by a live measurement — is exactly how real operations run. Leave even one cell of that structure empty, and the empty cell comes back as a 2 a.m. hunt.

Here are the three seats — formula, numbers, history — at a glance.

8.1.4 How One Formula Change Actually Flows

Now let's follow how D17 was decided, from the beginning. This is how a deterministic rulebook moves in practice.

flowchart TD
    A["Live measurement
Tank survival rate 89% detected"] --> B["Cause hypothesis
Defense constant 1000 overprotects late game"]
    B --> C["Define change candidates
1500 / 1200 / 800"]
    C --> D["Damage Simulator
1,000 deterministic runs per candidate"]
    D --> E["Result report
Survival rate, avg combat time, win rate"]
    E --> F{"Balance designer's call
Within target 60–70%?"}
    F -->|"800: death rate spikes"| G["Rejected → log attempt 1"]
    F -->|"1200: 75%, a bit high"| H["Held → log attempt 2"]
    F -->|"1500: 65%, in range"| I["Adopted → Decision D17"]
    I --> J["Build push (irreversible)"]
    J --> K["Live follow-up after 1 week
67%, +2% vs. prediction"]

    classDef code fill:#dbeafe,stroke:#2563eb,color:#0b2545;
    classDef human fill:#fde68a,stroke:#b45309,color:#000;
    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    classDef pass fill:#dcfce7,stroke:#16a34a,color:#14532d;
    classDef fail fill:#fee2e2,stroke:#dc2626,color:#7f1d1d;
    class D code;
    class B,C,F human;
    class A,E,K data;
    class I pass;
    class G fail;

Look carefully at the simulator's role in this flow. The Damage Simulator runs each of the three candidates 1,000 times. Those 1,000 runs are not the same input repeated 1,000 times. The ±5% randomness of variation = uniform(0.95, 1.05) inside the formula, plus the separate randomness of critical hit chance, makes every round come out differently. You run 1,000 rounds to see the distribution: average survival rate, worst case, the spread of combat duration.

What matters is that the simulator itself must be deterministic. Given the same random seed, all 1,000 rounds must reproduce without a single digit out of place. Only then can D17's one line — "1500 produced 65%" — be reproduced and verified identically six months later. A simulator that returns different results every time turns the decision log into a lie.

I first built this damage simulator in 2008. Back then it was an Excel macro; on Project A today it is encapsulated as the balance-sim skill. In 18 years the tool's shell has changed, but the rulebook inside has never once been probabilistic. That is the point.

8.1.5 Why AI Is Strictly Off-Limits for Reward Curves and Formulas

Now we arrive at what this chapter most wants to say. At a time when AI is entering nearly every seat in game design, there is exactly one seat it must never enter: the deterministic core of combat formulas and reward curves.

An LLM is probabilistic by nature. Ask it the same question and the answer shifts a little every time. That is the source of its power for good writing and ideas, and it is fatal in the rulebook's seat. Make an LLM answer "how much damage does a character with 80 defense take?" and it may say 92 today and 94 tomorrow. That is a board game whose dice change meaning every time you turn a page of the rules.

Reward curves are more dangerous still. "XP required from level 30 to 31," once set, governs the progression speed of hundreds of thousands of players at once. Let even a ±2% wobble in, and some players grow slower than the person next to them doing the exact same hunts. Fairness collapses. Determinism is another word for fairness. So reward curves are set by human hands, entered into the sheet, and never again left to probability.

This does not mean banishing AI from the balance domain entirely. The boundary is the point.

The line is clear. AI lives only outside the deterministic core. The inside — computing and simulating — is the rulebook; the outside — analyzing, proposing, putting things into words — is AI's seat. Cross the line once, and the same input starts producing different results; from that moment, the balance tool loses trust.

This boundary has the same structure as the economy systems we will see in 8.2. There too, the resource production and consumption formulas are deterministic, and detecting inflation patterns is AI's seat. The entire balance discipline moves on the same skeleton.

8.1.6 One Step Further — A Progressive Setup Where z-Scores Propose Candidates

So far this has been the conservative application: humans create the candidates and the simulation verifies them. Go one step further, and even creating candidates can be handed to tools. The rulebook, though, still belongs to humans and to determinism.

Anomaly detection is the starting point. From the 1,000-round simulation results, look at the distribution of each character's win rate and survival rate, and measure how many standard deviations each sits from the mean — the z-score. Characters with z above 2 are flagged automatically as "outside normal range." The 2 a.m. tank would have been caught by this detection too.

For detection to lead to candidate proposals, two more things are needed. First, a defined change space. Put a column like tunable_range in the CombatBalance sheet to state explicitly within which range each number may be touched. Second, parallelized simulation. Running 10 candidates × 1,000 rounds = 10,000 rounds within the build gate window — the automated quality-gate step a build must pass before it ships — takes parallel infrastructure.

With these three in place — z-score detection, a defined change space, parallelized simulation — the decision left in the balance designer's hands narrows to one: which candidate to adopt. Creating candidates from zero and choosing among five are very different burdens. Here too, AI touches only candidate proposals and report interpretation; the computation inside the simulation and the adoption decision remain the seats of determinism and of humans.

One last point: reversibility. Editing the sheet and running the simulation are both reversible — you can undo them as much as you like. The single irreversible seat is the build push. The moment players see a number that went live, it lives on as community reaction; roll it back and the trace still remains. That is why every sign-off finishes just before the build push, while everything is still reversible.

Try It Yourself — Handling One Formula Change Safely

setup. Create a CombatFormula document that separates the combat formula from prose and records it only as code blocks, plus an empty CombatFormula_Decisions log document next to it. Split the numbers out into a separate sheet (CombatBalance).

prompt. Use AI only for analysis and drafts, never for the formula change itself. For example, hand it the simulation result CSV and ask like this.

From the attached 1,000-run simulation results, compute the z-score of each
character's win rate and organize characters with z>2 into a table. For each
character, estimate — with evidence — which number (attack/defense/skill coefficient)
is most likely the cause of the anomaly. Do not fix the numbers themselves — propose candidates only.

verify. Do not take AI's candidates on faith. Enter the candidate numbers into the CombatBalance sheet yourself, and rerun 1,000 rounds with Damage Simulator (or balance-sim) using the same seed. Check two things: (1) does the simulation result land in the target range, and (2) does one more run with the same seed reproduce it without a single digit out of place? If both pass, adopt — and the moment you adopt, write the rationale, the attempts (including rejected candidates), and the predicted values into _Decisions. One week after the build push, append the live measurement to that log.

Solo Scale-Down

Even as a solo developer with no team and no simulator, the same skeleton works. Record the formula as code blocks in code comments or a single .md file, and put a ## 변경 이력 (change history) section at the bottom of that file. Whenever you change even one formula constant, write one line with the date, the reason, and the value before the change. A 30-line Python loop is enough of a simulator. Fix the random seed, feed character numbers into the formula, run it 1,000 times, and print just the average win rate — that alone moves you from "I changed it on gut feel" to "I changed it on evidence." Use AI only to read that output CSV and summarize which characters look abnormal. The one thing you must never do, at any scale, is have an LLM compute a single line of the formula.

Key Takeaways

• A combat formula is a rulebook that returns the same output for the same input; the moment that determinism breaks, the balance tool becomes a slot machine.
• Every formula change must carry a decision history — rationale, attempts, follow-up measurement — or no one can answer the "why is it like this" question six months later.
• AI lives only outside the deterministic core (anomaly detection, candidate proposals, reports) and never enters formula computation or reward curves.

8.2 The Economy Model in Machinations — Catching Inflation with Simulation, Not Meetings

Primary audience: MMORPG balance/systems designers responsible for a live economy (mid-size teams of 10–50) Scaled-down version for solo/hobbyist readers: §8.2.10, "If You're Solo, Just This Much"

The first place I learned that gold was leaking was not an invoice — it was the auction house. Two months after launch, the price of enhancement stones crept up; a month later it had doubled. I called a meeting to find the cause, and everything that came out of that room was a feeling. Someone said the new dungeon rewards were too generous. Someone said hunting-ground efficiency had gone up. Someone said it was simply that we had more high-level players now. All of it was plausible, so nothing got decided. We burned an hour on guesses and ended with "let's look at more data next week."

The problem is that there is never just one resource. Gold, enhancement stones, reputation, honor, and soul stones each have sources (ways in) and sinks (ways out), and those paths feed each other. The boss that drops enhancement stones drops gold too. The gear you buy with gold burns enhancement stones. With five resources tangled into dozens of flows, no mental calculator can honestly produce even a single resource's one-week balance. This chapter is about moving that tangle into a Machinations node model, and about passing economy change decisions through a simulation gate — the economy's version of a quality gate, where the pass/fail verdict comes from a simulation run instead of meeting-room guesswork. The general theory of economy design is well covered in other books; this chapter stays focused on running that theory as an AI workflow.

Author's Note on Actual Operations The case in this chapter is an anonymized version of an economy pilot document (Economy_Machinations_Pilot) and an economy research workspace that I run in my company's R&D folder. The resource types, the source/sink structure, and the four-stage Pilot faithfully reflect actual operations; company-specific names and raw figures have been replaced for the book or stated only as ratios and directions. The AI output text is a reconstruction of real sessions.

8.2.1 An Economy Is Not 'Five Resources' but 'Dozens of Flows'

Write the economy's resources in a table and you get five rows — it looks simple. The trap is not the resources but the number of flows connecting them.

Five resources — but the sources and sinks together number twenty-some, and on top of that the resources convert into one another (the auction house where gold buys enhancement stones is both a gold sink and an enhancement-stone source). The moment flows feed each other, a question like "what happens to enhancement stone prices if we release 5% more gold" has no answer from looking at one resource alone. This is where economy balance differs decisively from character balance (8.1). Character balance closes in a single formula; an economy is a dynamic system that accumulates over time — even if the one-week balance is near zero, let it accumulate for 26 weeks and the auction house collapses.

So the essence of economy work is not "picking the numbers well" but "watching, in simulation, how the flows accumulate over time." And building and revising that simulation model by hand is tedious, and something gets missed every time. Repetitive, omission-prone drafting whose review must stay firmly in human hands — this is exactly the grain of work where the division of labor between AI and humans draws itself most cleanly.

First, the skeleton of the economic loop this chapter deals with, in a single diagram.

%%{init: {"flowchart": {"defaultRenderer": "elk"}}}%%
flowchart LR
    subgraph SRC["source (resource production)"]
        H["Hunting grounds"]
        Q["Quests"]
        B["Dungeon bosses"]
        PVP["PvP/guild wars"]
    end
    subgraph POOL["pool (resource storage)"]
        G(("Gold"))
        S(("Enhancement stones"))
    end
    subgraph SINK["sink (resource consumption)"]
        UP["Gear enhancement"]
        RP["Repairs/taxes"]
        SH["Faction/guild shops"]
    end
    H --> G
    Q --> G
    B --> S
    PVP --> SH
    G -->|Auction house conversion| S
    G --> UP
    S --> UP
    G --> RP
    UP -.->|Enhancement stone demand ↑| S
    G -.->|"when net inflow > net outflow,
inflation accumulates"| POOL

    classDef data fill:#e2e8f0,stroke:#64748b,color:#1e293b;
    class G,S data;

The dotted lines are the heart of this chapter. The enhancement sink pulls up demand for enhancement stones and pushes their price (UP -.-> S), and when gold's net inflow exceeds its net outflow, the surplus piles into the pool week after week and accumulates as inflation. Tracking these two dotted lines by hand calculation is impossible — which is why you need a model.

8.2.2 Machinations — A Tool That Turns an Economy into a Node Graph

Machinations is a tool that draws economic flows as a node graph and runs simulations on top of it. This is where the mermaid diagram of §8.2.1 becomes a model you can actually run.

Model the economy with these nodes and run the simulation 1,000 times, and you get a distribution rather than a single result — something like "median gold price at 26 weeks: +X%; top 10% of users: +Y%." That said, Machinations is no panacea, and adopting it is itself a cost.

So Machinations is not a tool you adopt unconditionally. It pays off when three conditions overlap: five or more resources + resource conversion flows + live ops. A simple economy of two or three resources is perfectly fine in Excel, and in that case the operating burden of Machinations arrives before the benefit does.

8.2.3 [Worked Transcript] Drafting a Single-Resource Gold Model with AI

A tool description alone cannot tell you what this actually produces. Here is one full cycle of moving gold — gold alone — into a Machinations model, followed from the input prompt all the way to the human veto. The input prompts can be copied and used as-is; the outputs are reconstructions of real sessions.

Stage 1 — Input: Gold Flows as a Table a Machine Can Read

First, pull gold's sources and sinks out of the data sheets into a table. This is extraction, not writing from scratch. The yaml below lists gold's three sources and four sinks; the comments note that the auction tax is the one sink that truly recovers gold, and that user-behavior distributions (kills per hour, quest completion rate) are still empty — so the AI must flag any assumptions it makes.

# gold_flows.yaml — gold single-resource flows (excerpt from the current data sheets)
resource: gold
sources:
  - id: hunting        # hunting-ground drops
    trigger: per_kill
    note: per-level-band drop curve follows the reward_curve rule
  - id: quest_reward   # quest rewards
    trigger: per_complete
  - id: market_sell    # auction house sales
    trigger: per_trade
sinks:
  - id: gear_buy       # gear purchases
  - id: enhance        # enhancement costs
  - id: repair         # repairs
  - id: tax            # auction house tax (a sink, and the key gold recovery)
# user behavior distributions (kills per hour, quest completion rate) still empty → make the AI flag any assumptions it makes

Stage 2 — The Prompt: Ask for the Model, but Force Assumptions and Format

The attached gold_flows.yaml holds the 3 sources and 4 sinks of gold as a single resource.
Draft the node specification for moving this into a Machinations model.

Rules:
1) Classify each flow by node type (Source/Drain/Pool/Converter).
2) For each node, propose a formula for 'expected weekly flow per user';
   whenever a user-behavior assumption is needed (kills per hour,
   quest completion rate, etc.), state it on its own line marked '★assumption'. Do not hide assumptions in the body.
3) Separate total source inflow from total sink outflow and compute the one-week net balance (net).
4) Reflect that the auction house tax (tax) is the only sink that permanently
   removes gold from the economy, and distinguish that the other sinks
   (enhancement, repairs) merely move gold to NPCs — not recovery.
5) ★-flag every assumption you are 'not confident' about and hand it to a human decision.

Output format: a table (node | type | weekly flow formula | assumption | confidence). No other commentary.

The prompt (in Korean above) lays down five rules: classify each flow by node type (Source/Drain/Pool/Converter); propose a formula for each node's expected weekly flow per user, putting every user-behavior assumption on its own line marked "★assumption" rather than burying it in the text; compute the one-week net balance with total source inflow and total sink outflow separated; reflect that the auction tax is the only sink that permanently removes gold from the economy, while the other sinks (enhancement, repairs) merely move gold to NPCs; and ★-flag every assumption it is not confident about, handing those to a human decision. Output format: a table only — node | type | weekly flow formula | assumption | confidence.

What actually takes up space in this prompt is not the instruction to build the model but the rules about where and how to record assumptions. Give AI free rein in economy modeling and it spits out plausible numbers with the assumptions buried. Then, when the model is wrong, you cannot point to where it is wrong. Forcing the user-behavior assumptions out of the body text and onto their own marked lines — that is where the entire weight of this request rests. An assumption you can see is an assumption you can verify.

Stage 3 — Claude's Output (Reconstructed, Excerpt)

| Node         | Type      | Weekly flow formula                     | Assumption        | Confidence |
|--------------|-----------|----------------------------------------|------------------|-------|
| hunting      | Source    | kills/h × avg drop × weekly play hours  | ★15h/wk, 80 kills/h| Mid  |
| quest_reward | Source    | daily quests × reward × 7 × completion rate | ★completion rate 0.7 | Mid |
| market_sell  | Source    | (user-to-user transfer — not net gain)  | 0 net contribution to the economy | High |
| gear_buy     | Drain     | purchase frequency × avg price           | ★1.2/wk          | Low   |
| enhance      | Drain     | enhancement attempts × cost per attempt  | ★8/wk            | Mid   |
| repair       | Drain     | hunting hours × repair rate              |                  | High  |
| tax          | Drain     | trade volume × tax rate (★only permanent recovery sink) | ★tax rate 5% | High |
| ── Net balance | net     | Σsource − Σsink ≈ +(positive for mid-activity) | with the assumptions above | ★Low |

★Assumption warning: market_sell is user↔user gold movement, contributing 0 to the economy's total.
Adding it as a source double-counts inflation. Needs separate handling in the model.
★Not confident about: the gear_buy frequency (1.2/wk) is a guess. Without real purchase telemetry
the sink may be under-/over-estimated → human decision needed.

In brief, the table classifies the seven nodes and proposes weekly flow formulas with ★ assumptions — 15 hours of play per week, 80 kills per hour, a 0.7 quest completion rate, 1.2 gear purchases per week, 8 enhancement attempts per week, a 5% auction tax — and marks the net balance itself as low-confidence. It closes with two warnings: that market_sell is user-to-user gold movement contributing zero to the economy's total (adding it as a source double-counts inflation), and that the gear_buy frequency is a guess that needs a human decision.

The most valuable part of the output is not the table but the two lines at the bottom — the "★가정 경고" (assumption warning) and "★확신 못 하는 점" (points it is not confident about). The AI reported two weaknesses in its own model on its own. A good prompt makes the AI say, "I don't trust this assumption."

Stage 4 — Verification and Veto (The Human's Seat)

Do not feed this output into the model as-is. One of the two ★ flags the AI reported was, in fact, a defect that would have broken the model.

The AI initially classified market_sell (auction house sales) as a Source. But an auction house sale is user A's gold transferring to user B — it does not create new gold in the economy. Add it to source inflow and you count inflation twice. The AI did flag this itself in the ★ assumption warning, yet in the table body it still left the node sitting in the Source column — it reported the problem without removing it from the model: an output that was only half right. This was also partly a data defect on the human side: the input yaml never specified the nature of market_sell (user-to-user transfer vs. new creation).

So I send a follow-up request.

market_sell is a user↔user gold transfer, not an economy-level source (fixing
an input omission). Remove this node from the source total and instead reflect
it in the model only as 'the auction house tax (tax) permanently recovering a
fraction of the transferred amount'. Recompute the net balance, and show in one line how excluding market_sell changed net.

(The follow-up, in Korean above, says: market_sell is a user-to-user gold transfer, not an economy-level source — an input omission, now corrected. Remove the node from the source total and reflect it in the model only as "the auction tax permanently recovering a fraction of the transferred amount." Recompute the net balance, and show in one line how excluding market_sell changed it.)

The AI answered with a revised model: market_sell removed from the sources, only the tax kept as a sink. The net balance came out lower than the first estimate — revealing that with auction house sales wrongly counted as a source, we had been overestimating inflation. This one round trip is the whole point. Build the model by hand from scratch and it takes half a day, and the person who made the node-classification mistake is the worst-placed person to catch it; with an AI draft + forced assumption disclosure + one veto, it is under an hour, and because a human adjudicates the ★ flags the AI itself reported, defects like double-counting get caught before they ever enter the model (author's estimate — the time saved varies with team and resource count, so read this less as absolute values and more as the structural difference between "by hand from scratch" and "draft + review").

8.2.4 One Resource at a Time — Rolling It In Through a Four-Stage Pilot

Closing one gold model does not license modeling every resource at once. My own rollout did not load everything in one go either. It followed four stages: start from a single resource, pass verification and calibration, then expand.

The comparison in stage 2 is the heart of these four stages. When simulation and reality disagree, what is wrong is the model, not the game. Make decisions on a misaligned model and those decisions come back as live incidents. So expansion (stage 4) happens only after the verification of stages 2 and 3 has passed. Break this order — skip single-resource verification and load all five at once — and you can no longer even isolate which resource's model is wrong.

8.2.5 The Simulation Gate — Putting a Barrier in Front of Economy Change Decisions

Once the model passes verification, stand a simulation gate in front of every change decision that affects the economy. This is where decisions that used to pass on meeting-room "feel" start passing on simulation results instead.

To see how the gate actually works, here is one decision passing through it, on the gold model verified in §8.2.3.

[Simulation Gate — Event Reward Decision] (Reconstruction of the Actual Format)

[Proposal]   Weekend event: daily login reward +500 gold
[Gate]       new source added → simulation mandatory
[Sim results, 1000 runs]
  - weekly gold net balance: +6,900 → +10,400 (+50%)
  - 26-week cumulative median gold price ~+28% (inflation warning: exceeds ±10%)
  - top 10% active users: ~+41% (large segment variance)
[Verdict]    FAIL — exceeds the stable range (±10%/long-term)
[Correction] attach a simultaneous sink to the event source: event-limited shop (gold recovery)
             re-simulate → 26-week cumulative +9% (PASS)

(The gate record, in Korean above: a weekend event proposing +500 gold in daily login rewards is a new source, so simulation is mandatory. Over 1,000 runs, the weekly gold net balance jumps from +6,900 to +10,400 (+50%); over 26 weeks the median gold price accumulates roughly +28% — an inflation warning, past the ±10% line — and the top 10% of active users reach about +41%. Verdict: FAIL. The corrected proposal attaches a simultaneous sink — an event-limited shop that recovers gold — and re-simulates at +9% over 26 weeks: PASS.)

The value of the gate is in the last two lines. If "let's hand out +500" had been a meeting-room guess, it would have passed as "probably fine." The simulation gate converts that decision into 26 weeks of +28% inflation and shows it to you, and it forces the correction: if you add a source, attach a sink along with it. Judging economy changes by simulation pass/fail instead of guesswork — that is the entire gate.

One trap worth flagging here, because people fall into it constantly: segment variance. Even when the mid-activity user sits at +28%, the top 10% sits at +41%. The users who earn the most gold accumulate inflation the fastest, so the simulation must run per segment, not just on the average. Look only at the average and you miss the price collapse driven by high-activity users.

8.2.6 The Model Evolves Monthly on Post-Launch Telemetry

For the simulation gate to be trusted, the model must not drift from the actual game. The game changes every week, so the model has to be recalibrated to keep up. After launch, check the model against real telemetry monthly (quarterly in periods with few changes).

Model calibration cycle (monthly)
─────────────────────────────────
1. Extract one month of real user telemetry (flows aggregated per resource)
2. Compute measured source/sink flows per segment (low/mid/high activity)
3. Compare item by item against the Machinations simulation
4. Items with error >15% = adjust model parameters (that item's ★assumption was wrong)
5. Re-simulate after adjustment → use as next month's gate baseline model

(The monthly cycle, in Korean above: extract one month of real user telemetry, aggregated as flows per resource; compute measured source/sink flows per segment — low/mid/high activity; compare item by item against the Machinations simulation; for any item with error >15%, adjust the model parameters — that item's ★ assumption was wrong; re-simulate and use the adjusted model as next month's gate baseline.)

Step 4 is the core. A high-error item is a signal that one of the "★ assumptions it was not confident about," which the AI reported back in §8.2.3, has diverged from reality. For instance, if the AI's guessed gear_buy frequency (1.2 per week) measures at 2 per week in telemetry, replace the assumption with the telemetry value. Stop this calibration and the model drifts slowly away from the game, until one quarter the simulation gate "passed something that inflated live anyway." At that moment, trust in the simulation itself collapses retroactively. Calibration is not a side chore of operations — it is the regular cycle that keeps the gate alive.

8.2.7 Progressive Application — Anomaly Detection, Change Spaces, Parallel Simulation

Everything up to here is the 'conservative application' of economy modeling: a human proposes a change, the model verifies it, and the result decides. One step further, the three axes of progressive application seen in 8.1.6 — z-score detection, defined change spaces, parallel simulation — open up on this economic infrastructure in exactly the same way.

First, anomaly detection. Instead of a human eyeballing the error comparison in the monthly calibration cycle (§8.2.6), code picks out and surfaces the items whose model-vs-measured deviation crosses a threshold. You no longer learn that enhancement stone prices doubled by watching the auction house; an alert saying "enhancement stone source flow has deviated +30% from the model" arrives before the meeting does.

Second, defining a change space. Instead of the binary "release +500 in rewards / don't," define the change space — a reward range (0 to +1000) and a range of accompanying sinks — and you can search that space for combinations that keep inflation within ±10%. Humans set the "from where to where"; the search for the optimal combination inside it is automated.

Third, parallel simulation. Instead of running one proposal 1,000 times, run dozens of candidates from the change space in parallel, 1,000 runs each, and compare the distributions in a single pass. The meeting room where proposals were debated one at a time becomes a comparison of simulation results across a candidate matrix.

The common idea is to move the seat where a human proposes changes to one where code searches a change space. But this is strictly for after the conservative application (§8.2.3–8.2.6) runs stably and the model has been verified against telemetry. Auto-search a change space with an unverified model, and a wrong model will confidently hand you a wrong optimum.

[Radical Application — Compressing the Economy into a 'Dimension Vector' and Searching There] (Still Premature)

This goes one step beyond progressive application. Read it as a research direction, not a claim (if dimension vectors and embeddings are new to you, look first at the one-page 'map' in Appendix M — all five 'signposts' in this book run on top of that picture, and what follows will read easily). The economy model we have built to this point is a high-complexity system — five resources tangled in dozens of flows — and even the change-space search of §8.2.7 ultimately works by pinning each of those dozens of flows as a parameter and iterating. The radical idea is to compress that complexity itself into a dimension vector, then look for solutions in the compressed space.

A seemingly distant analogy supplies the clue. Cooking recipes — a domain usually held up as qualitative and ungraspable — were handled in one study (Epicure — Radzikowski & Chen, 2026, arXiv:2605.22391; demo at epicure.kaikaku.ai) by distilling 1,790 standard ingredients from 4.14 million recipes across 11 sources and compressing the relationships between ingredients into vectors of several hundred dimensions. The point is that even a qualitative target like "taste," once the relationships between ingredients are converted into coordinates, makes similar recipes cluster close together in vector space — and you can interpolate between them to search for new combinations. Epicure itself demonstrates this kind of interpolated search in the compressed space, rotating one ingredient toward a particular cuisine to find its counterpart.

The economy works on the same principle. Express the economy's state as a vector whose dimensions are its sources, sinks, and conversion flows, and "a stable economy within ±10% inflation" becomes a region of that space. Then, instead of putting proposals through the simulator one at a time, a path opens to search for solutions directly in or near that stable region. The parallel simulation of §8.2.7, which compares candidates by running every one of them, could narrow down to a single search over the compressed space.

Why "still premature"? First, deciding what to take as a dimension (which flows are independent and which are dependent) is itself a hard domain problem. Second, compression by its nature throws information away, and a live incident can erupt in a dimension you threw away. Third, all of this means anything only when the conservative application's telemetry verification (§8.2.6) is solid — if the pre-compression model is misaligned with the game, compression will simply compress that error neatly along with everything else. So this section is a signpost, not a prescription. The work for today is to run the conservative application honestly; dimension vectors remain a research area for teams with that foundation to look into a few years from now.

8.2.8 Measurement — Where Meetings Gave Way to Simulation

Here is before-and-after, around the tool's adoption. The times and frequencies below capture the direction we felt in early operations; read them for which way things moved, not as precise absolute values.

The last row means more than the numbers. Meeting frequency dropped because simulation replaced debate. When "I think enhancement stones are headed for inflation" becomes "the simulation says +28% over 26 weeks," the hour spent arguing over guesses becomes a five-minute results share. This is exactly the concept codified in my own system's retrospectives (the atom automation_signal_value_over_time_savings — the value of automation is signal exposure, not time saved). The real output of the simulation gate is not the hours saved; it is that the seat guesswork used to occupy in meetings is now occupied by numbers.

One thing I keep honest, though. The "1–2 per quarter → 0–1" row is not a precise measurement; it is the direction of an operational impression. What counts as an inflation incident depends on definition (how many ± percent of price movement you call an incident), so read it less as absolute counts and more as the structural shift from "found after the fact" to "blocked in advance."

8.2.9 Common Failures

The second one is missed most often. As with the auction house double-counting in §8.2.3, AI will confidently produce a plausible model while merely ★-flagging the weak points of its own assumptions and leaving the defect in the body. If no human adjudicates those ★ flags, the wrong model passes — and every simulation decision built on top of it is wrong together.

8.2.10 Try It Yourself — One Step You Can Take Today

If You're Solo, Just This Much: You don't need Machinations or telemetry. Pick one resource from your own game (or a game you love), write its sources and sinks on paper, paste in the prompt from §8.2.3 as-is, and get a draft one-week net balance model. Then pick one of the assumptions the AI marked with ★ and push back: "I don't trust this assumption — justify it again." You will feel, firsthand, what an economy model really is — a bundle of assumptions — and how the conclusion flips when one of those assumptions is wrong.

If you're on a team, start with this one step. Not every resource — pick the single most troublesome resource (usually gold or enhancement stones), build only the single-resource model of §8.2.3 first, and put the simulation gate of §8.2.5 on one kind of economy change decision (say, event rewards). One resource plus one decision type is already enough to replace the argument over guesses with a single line of numbers.

Summed up as setup → prompt → verify — setup: extract one problem resource's sources and sinks into yaml. prompt: request a node model draft in the §8.2.3 format, forcing user-behavior assumptions to be marked with ★. verify: a human personally vetoes and re-requests against the ★ assumptions the AI reported and the node classifications (especially user-to-user transfer vs. new creation).

Key Takeaways

• An economy is not five resources but dozens of flows accumulating over time — which is why it needs simulation.
• Force AI model drafts to state their assumptions explicitly, and have a human veto those assumptions.
• Judge economy changes by the simulation gate's pass/fail, not by meeting-room guesswork.

Next Chapter Preview

• 8.3 Damage Simulator (2008–) — How an 18-Year-Old Simulation Tool Gets Reused in the AI Era

8.3 Damage Simulator — The Day Spec DPS and Sim Output Diverged

One early morning in 2008, I sat in front of a single Excel sheet, checking the same number for the third time. The game design document (GDD) listed a certain sword character's damage per second (DPS) as 847. But the simulator I had run for the first time that day, fed the same character with the same stats, spat out 612. A 27% difference. One of the two was lying, and I didn't yet know which.

Spec DPS is a promise on paper: arithmetic that multiplies one skill hit's damage by how often it fires. Simulator DPS is what you get when you actually swing that promise 1,000 times. Cooldowns overlap, cast animations eat up time, critical hits land less often than the expected value says — friction the paper knows nothing about creeps in. That 27% gap is exactly where a balance designer makes a living. Trust the paper and you cry after launch.

This chapter is the story of that one tool: the Damage Simulator I built in 2008 and have not put down since. How I tracked the exact point where spec and output diverge, and how, 18 years later, I attached AI to that tracking — followed through a single real worked transcript.

8.3.1 Why Spec DPS Always Lies

First, let's dissect what that 612 versus 847 really was. The junior designer who wrote the spec (Team Member A from here on) had done nothing wrong. He multiplied exactly what the skill table said.

The spec-side DPS calculation looks like this. Assume a character with three skills.

Team Member A's spec calculation rested on the ideal assumption that every skill is used the moment its cooldown comes back. Horizontal Slash deals 320 every 3 seconds, Thrust deals 540 every 6 seconds, and Basic Attack fills the empty time. The arithmetic comes out to a clean 847. On paper, the character has more than one pair of hands, so cast animations never block one another.

The simulator returned 612 for exactly one reason: the character has one pair of hands. While the 0.9-second Thrust is being cast, Horizontal Slash cannot fire even when its cooldown is up. This global cooldown (GCD) collision — cast animations devouring each other — does not exist in the spec. Paper is a frictionless vacuum; the sim is a battlefield with friction. The first truth I learned in 24 years of doing this work is this: spec DPS is an upper bound, not a measurement. And players play the game at the measurement, not the upper bound.

8.3.2 Worked Transcript — Grilling the AI About Where 612 Came From

In 2008, I closed that 27% gap by hand. I read the sim log line by line with my own eyes, counting the frames where skills got blocked. It took half a day. Eighteen years later, I throw the same log at Claude. Below is the full text of an actual session. I have not summarized it, and I include the first attempt that fell short — because that falling short is half of how to use this tool.

Here is the prompt I threw.

Attached is part of a single-character 1,000-tick combat log from our Damage Simulator (damage_sim/, Python). Per the spec, this character's DPS is 847, but the sim outputs 612. Find the cause of the 27% gap in the log. The log format is [tick] event skill=SKILL state=STATE. No guessing — cite only evidence that is in the log. If the evidence is insufficient, say it is insufficient.

[0.0] cast skill=찌르기 state=START
[0.9] cast skill=찌르기 state=HIT dmg=540
[0.9] cast skill=횡베기 state=BLOCKED reason=GCD
[1.5] cast skill=평타 state=HIT dmg=180
[1.9] cast skill=평타 state=BLOCKED reason=GCD
[3.0] cast skill=횡베기 state=HIT dmg=320
[3.6] cast skill=평타 state=HIT dmg=180
... (994 lines omitted)
[997.2] cast skill=찌르기 state=HIT dmg=540

Claude's raw output looked like this (untouched).

Facts confirmed in the log:

1. state=BLOCKED reason=GCD events appear repeatedly. At [0.9], Horizontal Slash (횡베기) was blocked by the GCD (global cooldown); at [1.9], Basic Attack (평타) was.
2. Until the Thrust (찌르기) cast finishes (0.0→0.9, 0.9s), no other skill can fire. The cast time appears to occupy the GCD.
3. Therefore the spec's assumption — "every skill fires on every cooldown" — breaks down. In practice, cast animations collide and some activations are lost.

However, the provided log is only 7 lines out of 1,000. Whether the exact 27% gap is explained by GCD collisions alone cannot be concluded from these 7 lines. To verify the 27%, we need the total count of BLOCKED events and the total damage lost because of them. If you provide the BLOCKED aggregation for the full log, I will confirm it quantitatively.

The stop here is what matters. The AI pointed at the cause but did not prove the 27%, and it stated that limit itself. Where a paper-only designer would have ended the meeting with "so it's the GCD," the tool held its ground: "seven lines aren't enough to know." I judged that demand legitimate — this is what human verification is. So I pulled the BLOCKED aggregation for the full log and threw it back.

Here is the full 1,000-tick aggregation. BLOCKED total: 412, of which 388 were due to GCD and 24 due to cooldown not yet recharged. Estimated damage lost to BLOCKED is about 19,800 in Horizontal Slash equivalents. Over the full 1,000-tick (= second) fight, spec-expected damage is 847,000 and sim-measured cumulative damage is 612,300. Re-examine the 27% gap with these numbers.

Claude's second output.

Verifying with the aggregates.

• Spec expected cumulative: 847,000
• Sim measured cumulative: 612,300
• Gap: 234,700 (27.7%)

Composition of the gap: - Directly lost to GCD collisions (388 events): the estimate of about 19,800 is in Horizontal Slash equivalents, but you also need to add the opportunity cost — higher-damage skills could have filled the lost slots. Converting the lost slots at average damage makes the loss larger than 19,800. - However, BLOCKED alone does not explain the full 234,700. The interpretation of the remaining gap changes depending on whether the spec's 847 "already folds the critical-hit expectation into the average" or is "a base value without crits." Tell me the spec's crit assumption behind 847 and I will decompose the residual gap.

It stopped again. And again it stopped in exactly the right place. How the spec's 847 handled critical hits — that information was not in the log; it existed only inside Team Member A's head. The AI knew the boundary of the data it had. When I checked, the spec's 847 had flattened a 20% crit chance at 1.5x into the expected value, and the sim was one run, seed fixed, in which the actual crit count came in below expectation. In other words, the 27% gap was a mix of GCD collision (structural, reproducible) and crit variance (statistical, this one run's luck).