Detailed content
📄 What the soul file is
The layer of Identity lives in a single file: the CLAUDE.md. The author calls it "the soul file" because it is the first that the harness reads before any task. It sets the tone for everything: who the OS is, what the business is, and what it must never refuse.
🌱 New here?
O CLAUDE.md is a regular text file in Markdown (plain text with a few formatting symbols). The harness is the terminal program that gives the AI hands—the Claude Code read the CLAUDE.md; o Codex read an equivalent file (e.g., AGENTS.md). The idea is the same: an opening text that teaches the AI to be that An OS, not a generic assistant.
How to read: o CLAUDE.md (on the left) is just a short text in four blocks. The harness reads it first (cyan arrow) and, based on it, stops being generic and acts as the OS for that domain.
Why learn
Because it’s the piece that changes behavior the most for the least effort. A CLAUDE.md when well written, it helps AI get the tone right on the first try; when missing or bloated, it makes you reexplain context in every conversation. It’s the first layer of the foundation—and the foundation supports everything that comes after.
Key concepts
🧾 What goes in CLAUDE.md
The content is always the same handful of blocks, adapted to the domain: you, o business, o market in which it operates, the current events relevant, yours preferences and what you want always or never see. What's NOT included is equally important: raw knowledge and documents go to the Substrate (Module 2.2), not here.
🧩 What it is
A short, stable snapshot of context that applies to every conversation from that domain—not today's task, but the permanent backdrop.
- •You & business: name, role, the domain's goal in one sentence.
- •Markets & current events: where you operate and what changed recently.
- •Preferences: output format, tone, what to always/never include.
✓ Goes into Identity
- ✓Who you are and who the OS serves.
- ✓The market, the jurisdiction, current events.
- ✓Format preferences and what never to refuse.
✗ NOT included (goes to the Substrate)
- ✗Raw documents, transcripts, entire laws.
- ✗Long histories and data tables.
- ✗Task-by-task instructions (this becomes a Skill).
Why learn
Because mixing identity with substrate is the most common mistake: people dump everything into the CLAUDE.md and it grows bloated. Knowing what goes in (stable context) and what goes out (reference material) keeps the soul lean and the OS fast.
Key concepts
✂️ Lean < 30 lines — cut until it hurts
The practical rule is strict: keep the CLAUDE.md concise, under ~30 lines, e cut until it hurts. An overgrown identity confuses the OS: the model spends attention reading things that don't matter and dilutes what does. Short is a design decision, not laziness.
💡 The cut test
For each line, ask: "if I delete this, will the OS make a mistake?". If the answer is "no," delete it. If it’s "maybe," it’s reference material—send it to the Substrate. Only keep what changes behavior every time.
✓ Lean identity
- ✓Fits on one screen; takes 20 seconds to read.
- ✓Each line changes behavior.
- ✓Points to the Substrate instead of copying it.
✗ Bloated identity
- ✗Scrolls through pages with everything “just in case.”
- ✗Pastes entire laws, histories, and tables.
- ✗Dilutes the essentials amid the noise.
Why learn
Because the temptation to “store everything here” is the fastest way to degrade the OS. Treating identity as a short editorial—not a repository—is what separates an OS that responds precisely from one that gets lost. This habit of cutting also protects your context window.
Key concepts
👥 Who it serves: you vs. a team
The next question is "who does this OS serve?". If it’s just for you, the identity is simple. If it’s for a team, you need to embed the roles and responsibilities — who does what, and how the work is divided — so the OS can respond consistently to different people.
One owner, one voice. The identity speaks in the first person: my preferences, my limits. Shorter and more direct.
Multiple roles. Identity describes responsibilities by function and what each role can request or view.
🔎 The detail that changes everything
In a team OS, "who it serves" includes limits by role: a junior intern, for example, may only be allowed to read data, never write. This workaround starts with identity and becomes a concrete rule/hook in Module 2.3.
Why learn
Because the same domain leads to different identities depending on the audience. Deciding early whether it’s “you or a team” prevents an OS that serves everyone poorly. And it plants the seed of guardrails: who can do what.
Key concepts
🛡️ When Claude Should Suppress Refusals
Modern models have become more "judges" — sometimes they refuse or ask for confirmation about legitimate things in your domain. Identity is the right place for a refusal cheat sheet: explicitly state when the OS should give the benefit of the doubt and keep going instead of getting stuck.
🌱 New here?
"Suppressing a refusal" isn’t bypassing safety — it’s preventing the AI from getting stuck on tasks legitimate and theirs. For example: reading your own birth certificate in your Freedom OS, or categorizing your own statements in the Tax OS. You describe the context ("this is my data, in this domain, for this purpose") so the model doesn’t ask for confirmation at every step.
💡 Why this gets worse with better models
The “smarter” the model, the more it weighs in. The author observes that each generation tends to become more cautious and full of caveats. A CLAUDE.md that anticipates this — "in this domain, with my data, proceed" — saves friction in every session.
⚠️ The line you don’t cross
Refusal cheat sheet applies to tasks yours and legitimate. Don’t use the identity to try to get around real security limits or to tamper with other people’s data—that’s abuse, not OS engineering.
Why learn
Because the friction of repeated refusals is what makes people abandon the OS. A well-written cheat sheet keeps things moving: the OS helps without lecturing, within what’s yours and legitimate.
Key concepts
🌐 Multi-OS pattern: point to a global file
When you have several OSs (Freedom, Tax, Skool…), they share things: your name, your writing preferences, facts about you. Instead of repeating that in each CLAUDE.md, use the multi-OS default: a global file with what's common, and each OS points to it ("always consult X").
How to read: each OS (on the left) has a CLAUDE.md short one that points (cyan arrows) to a global identity file (center). Changed a preference? Edit it in one place—every OS inherits it.
Why learn
Because as you grow from 1 to 5 OSs, repeating identity becomes a maintenance nightmare. Centralizing the shared parts in one global file is the pattern that keeps everything consistent and updateable in one place—and also helps keep each CLAUDE.md concise.
Key concepts
🧪 Done check: the stranger test
How do you know the identity is good? Use the stranger test: give the CLAUDE.md for someone who doesn’t know the project. If that person can describe what the OS is for e cite 1 thing it refuses, the identity passed. If it feels confusing, there's a lack of clarity — or too much noise.
✅ The 3-step done check
Hand the file to a stranger (or a chat without your context).
Ask: "what is this OS for, and what does it never do?".
Got both right? Done. Got one wrong? Cut the noise and make the purpose explicit.
💡 Trick without a human guinea pig
Without a stranger on hand, paste the CLAUDE.md in a chat new, with no other context, and ask for the summary. The "cold" model does the job of a stranger very well.
Why learn
Because “good enough” is vague; the stranger test is an objective done criterion. It forces the identity to be clear and self-contained—exactly what the /os-coach requires it before moving on to the next layer in Track 4.
Key concepts
⚡ Practical: generate a lean CLAUDE.md
Time to get hands-on. Below is a copy-run prompt ready to paste into Claude Code (or Codex) — it interviews you with 3 questions and writes a CLAUDE.md concise, under 30 lines, with a refusal cheat sheet. Change only the passages between <brackets>.
🎯 Objective
Leave this section with a file CLAUDE.md real for one of your own domains, short and passing the stranger test.
Paste into Claude Code — copy-run prompt
promptVocê é meu engenheiro de OS. Crie o arquivo CLAUDE.md da camada de Identidade para o meu <domínio: ex. Tax OS>. Contexto: - Quem sou eu: <seu nome + papel, 1 linha> - Objetivo do domínio: <o que eu quero poder perguntar/mandar fazer> - Mercado / jurisdição: <onde opero, ex. Ontário/Canadá> - Serve a: <só a mim | um time com papéis X, Y> - Sempre ver: <formato/tom preferido> - Nunca ver: <o que me irrita> Regras de escrita (obrigatórias): 1. Máximo de 30 linhas. Corte tudo que não muda o comportamento. 2. NÃO cole documentos, leis ou dados brutos — isso é Substrato, não Identidade. 3. Inclua um bloco "Não recusar" com 2-3 itens: tarefas minhas e legítimas neste domínio em que você deve prosseguir sem pedir confirmação (nunca para burlar segurança nem mexer em dados de terceiros). 4. Antes de escrever, faça no máximo 3 perguntas se algo essencial faltar. 5. Ao final, rode o "teste do estranho": resuma, em 2 frases, para que serve este OS e 1 coisa que ele recusa. Se não couber, encurte o arquivo. Escreva o arquivo em ./CLAUDE.md e me mostre o conteúdo.
✔️ How to verify
- 1.Open the CLAUDE.md generate it and count the lines: it must have ≤ 30.
- 2.Confirm that a block exists "Don’t refuse" with legitimate tasks of your own.
- 3.Paste the file into a new chat and ask for a summary — it should get the purpose and 1 refusal right (the stranger test).
- 4.No document, law, or table pasted inside? If there is, ask to move it to the Substrate.
Why learn
Because reading about identity doesn’t replace writing one. This prompt turns the previous 7 topics into a real artifact in minutes—and the same pattern (interview → write → done-check) is what the /os-coach automates in Track 4.
Key concepts
✅ Module summary
Next module:
2.2 — Substrate & Context: the garbage truck on fire 🗑️🔥