Why a File-Based Rules System?

This whole site — every numbered course, every language lesson, every kanji page — is generated according to a large, growing set of conventions: how a banner comment is formatted, where a file gets saved, when a PDF gets built, what a course does once it's finished. None of that lives in Claude's own memory as the single source of truth. It lives in plain text files, on disk, inside this repository's own rules/ folder — and this chapter is about why that specific design choice matters, and how it actually works today.

The Problem: Memory Isn't Guaranteed to Persist

Claude's built-in memory is genuinely useful — it's what lets a later session recall that a particular course prefers one bundled PR over several small ones, or that a user is a technical support engineer rather than a full-time developer. But memory is a convenience layer, not a guarantee. It can be cleared. A brand-new session can start with none of it. Two different environments running the same project might not share it at all. If every one of this project's own conventions — the banner-comment format, the course-folder-naming scheme, the PDF-on-completion rule — lived only in memory, a single cleared memory store would mean losing the instructions this entire site depends on to stay consistent.

The Fix: Files as the Source of Truth

The actual conventions live as plain English instructions in markdown files — permanent_rules.md, language_rules.md, kanji_rules.md, and several others, all inside this repository's own rules/ folder. There's nothing special about the file format; the discipline is entirely in keeping every rule in one place, on disk, where it survives regardless of what happens to any one session's memory. A rules file doesn't forget anything. It's exactly as reliable as the repository itself.

The Old Way — A Manual Recovery Prompt

An earlier version of this exact system (documented in a short, single-chapter reference file dated 2026-06-21 — itself now a historical artifact) relied on a dedicated recovery rule, R1, whose entire job was reminding a fresh session to go read the rules file:

This worked, but it depended entirely on someone remembering to paste that exact prompt at the start of every single session — a manual step, easy to forget, and only as good as whoever's job it was to remember it.

The Modern Way — Automatic Inclusion via @rules/

Today, the project's own CLAUDE.md file — read automatically at the start of every session in this repository, with no prompt needed at all — contains a short block like this:

Each @rules/<filename> line is an include — the full contents of that file are pulled directly into context automatically, every single session, before a single word of the actual conversation happens. There's no equivalent of R1 needed anymore, because there's nothing left to manually remember to ask for. The rules simply arrive.

Why This Still Matters Even With a Working Memory System

This project also has a real, separate auto-memory system (covered fully in Chapter 8) — so it's worth being precise about why the file-based rules layer hasn't been replaced by it. Memory is genuinely good at the kind of thing that's specific to one conversation or slowly-learned over time: a preference confirmed once, a project fact that will be stale in a month. The rules files are for the opposite case — a convention meant to apply identically to every single course, every single session, forever, until someone deliberately edits the rule itself. Putting that second kind of instruction in memory would mean it could quietly vary session to session; putting it in a file the whole project reads the same way every time is what keeps hundreds of generated chapters actually consistent with each other.

Hands-On Exercises