CLAUDE.md Cowork Context File

Depends on: FTR-06 — File Storage & Transfer Rules. Soft links, used when installed: FTR-15 — Project Cache (cache index), FTR-23 — Agent Instructions Sync (version-stamp comparison)

What this is

A CLAUDE.md file at the project root is the entry file that Cowork sessions and Claude Code read automatically at the start of every session. It is not a copy of the agent instructions. It is a short entry file (at most 200 lines) generated from admin\AGENT_INSTRUCTIONS.md by a defined conversion: it says what the project is, lists the rule files, shows the folder map and routes each kind of task to the procedure that handles it, so the agent loads only what the task needs. The whole instructions stay, unchanged, in admin\AGENT_INSTRUCTIONS.md. That file is the source of truth and is also pasted in full into the Project Instructions field; an agent never loads it to get its instructions, it is named only as the source for regeneration and audit.

Why it is not a mirror: a mirror loads everything at the start of every session (a 190,000-byte set of instructions is about 47,600 tokens); it does not separate rules from procedures from reference, so a hard rule is no more visible than a change-log row; it cannot be checked for loss, because every line is trivially "there"; and a mirror rule inside the instructions ("regenerate CLAUDE.md after every edit") makes an agent overwrite the sliced file on the next edit and undo the structure.

What this means when you add something later: a new rule, procedure or feature goes into admin\AGENT_INSTRUCTIONS.md and nowhere else. CLAUDE.md is never edited by hand and is never regenerated just because the instructions changed. It changes only when the owner approves a deliberate re-run of the conversion (see step 7 under Write). Where another installed feature says to produce, update or regenerate CLAUDE.md every time the instructions change, or calls it a verbatim clone, this feature's rule wins.

Assess first

• Check whether CLAUDE.md exists at the project root (NOT in admin\), and whether admin\AGENT_INSTRUCTIONS.md exists. The instructions are the source; if only CLAUDE.md exists, say so before doing anything else.
• Decide which state the project is in:
  • None: no CLAUDE.md.
  • Full copy (the old mirror): CLAUDE.md opens with an intro block saying it mirrors the instructions, or is about as large as the instructions. Leave it in place until a conversion passes its audit; it is a "temporary full copy" (step 8).
  • Entry file (converted): at most 200 lines, a routing table, and a last line Instructions version synced: <version> (<date>).
• Read every section of admin\AGENT_INSTRUCTIONS.md before classifying any of it. Never judge a section by its heading: a procedure can hide a hard rule, and a section titled as reference can hold a procedure.
• List every mirror or clone line in the instructions (the words and places are in step 2). They defeat the structure and must be removed, with the owner's go-ahead, before the entry file is trusted.
• Check whether project_cache\ exists and whether it has an index (project_cache\INDEX.md). If the project cache feature is installed, a cache with no index is a defect to fix first. Never index keys or credential files.
• If a person asks for a project update and both files are present, treat admin\AGENT_INSTRUCTIONS.md as the file to update. CLAUDE.md is not edited on its own and is not regenerated as part of the edit.

Ask, only if needed

Proceed without asking when the project has no CLAUDE.md and the instructions carry no mirror lines. Otherwise ask the owner once, in one message, for the go-ahead that is needed:

1. Remove the mirror or clone lines from the instructions (back up first, bump the version or date, add a change-log row, re-paste the Project Instructions field).
2. Replace an existing CLAUDE.md. A differing CLAUDE.md is reported as a conflict, never replaced silently.
3. Which is master for structure-first additions (step 7): the instructions or the structure. Default: the instructions (source first).
4. A claude.ai-only section the owner wants left out of the entry file: ask for sign-off and a reason. A rule inside such a section is extracted first. Do not ask about anything else.

Write

Work through these steps in order. The work is additive: nothing is overwritten without the owner's go-ahead.

1. Where the instructions are stored

• admin\AGENT_INSTRUCTIONS.md is the source of truth, whole and unchanged by the conversion. An agent never loads it and never reads it for instructions.
• The same text, in full, is pasted into the claude.ai Project Instructions field. The file governs when the two differ.
• It is never registered in the project cache. Backups: the newest beside it in admin\, older ones in admin\backups\ or admin\_archive\; nothing is deleted.

2. What the instructions say about CLAUDE.md Add this section to admin\AGENT_INSTRUCTIONS.md (replacing any older CLAUDE.md section), filled in for the project:

◆ CLAUDE.MD — ENTRY FILE FOR COWORK AND CLAUDE CODE

Location: [project_root]\CLAUDE.md
Source: [path]\admin\AGENT_INSTRUCTIONS.md (whole; an agent never loads it)
What it is: the entry file written by the conversion process. It is not a copy
  of these instructions, it is not regenerated when these instructions change,
  and it is never edited by hand. At most 200 lines; it points to the rule
  files, procedures, reference and the index.
Layout: [the layout from step 3]
Adding or changing something: edit this file only (back up, bump the version,
  add a change-log row). CLAUDE.md changes only when the owner approves a re-run
  of the conversion. A rule or procedure added to the structure first is listed
  in admin\state\structure-changes.md so it can be added back to this file.
State: [converted <date> | temporary full copy dated <date>, not yet converted]

The instructions must not contain a mirror or clone rule anywhere. Look for: "byte-for-byte", "exact clone", "mirror of this file", "always regenerated", a SHA-256 match between the two files, "regenerate CLAUDE.md after every edit" in the backup, change or responsibilities rules, and a "Cowork/Claude Code mirror" row in the key-documents table. Places to check: the header paragraph describing where the instructions live; the sync protocol; the backup rule; the key-documents table; the ongoing-responsibilities list; any note beside a registry or tracker saying "no CLAUDE.md clone"; the install manifest note. Removing them edits the owner's instructions, so it needs the owner's explicit go-ahead (back up first, bump the date or version, add a change-log row, remind the owner to re-paste the Project Instructions field). Old change-log rows that say "CLAUDE.md re-cloned" stay as history.

If the instructions-sync feature is installed, reword its protocol: the Project field is a full copy of the instructions; CLAUDE.md is compared by its version stamp and by the source hash recorded at conversion, not by identity.

Add to Ongoing Responsibilities (if that section exists): "When adding or changing a rule, procedure or feature: edit admin\AGENT_INSTRUCTIONS.md only (back up, bump the version, add a change-log row). Do not edit CLAUDE.md by hand and do not regenerate it as part of the edit; it changes only through an owner-approved re-run of the conversion. If asked to update the project instructions and only CLAUDE.md comes to mind first, check for admin\AGENT_INSTRUCTIONS.md before writing anywhere — that file is the source."

3. Layout of a converted project (pointers written inside CLAUDE.md use forward slashes)

<project>/
  CLAUDE.md                      always loaded, at most 200 lines
  .claude/
    rules/<concern>.md           always loaded; hard rules verbatim, one concern per file
    rules/identity-and-working-habits.md   class B, verbatim, one file
    skills/<name>/SKILL.md       description always visible; body loads when used
  admin/
    AGENT_INSTRUCTIONS.md        the whole source, never loaded
    README.md                    the index: every rule, procedure, reference and state file by name
    FOLDER_MAP.md                folder map and key documents, verbatim
    sop/<procedure>.md           procedures, verbatim
    reference/<topic>.md         reference, verbatim, found through the index
    state/<topic>.md             change log, manifest, snapshots; read only when asked
  project_cache/INDEX.md, INDEX.json   the index of the project's documents
  TODO.md

Every staged file starts with a staged-verbatim header (source file, line range, unit id, sha256 of the copied text) followed by the exact source text. The header is the proof the text was copied, not retyped. A file with that header is never hand-edited.

4. Where each kind of section goes

The only new wording in a converted tree is the pointer layer: the CLAUDE.md summaries, skill descriptions and the index. Everything else is the source text, copied. Report the size of the always-loaded layer (CLAUDE.md plus all rules); above about 10,000 tokens, review which units can move to routed files. Never shrink by condensing.

5. Populate the structure (the conversion)

1. Scan, read-only: list every unit (section) of the instructions, with its byte size.
2. Review: read every unit, confirm or override its class, split mixed sections, extract embedded rules, list any mirror or clone lines (step 2). Keep the review keyed by the hash of the source, so a re-run with unchanged headings carries it over.
3. Stage the verbatim tree (step 3), every unit accounted for.
4. Author the pointer layer: what the project is (five lines at most), one line per rule file, the folder table, and one skill per procedure. A skill description is about 300 characters, quoted, begins "Use when" and names the trigger phrases in the user's words. A skill's folder name equals its procedure file name (at most 30 characters).
5. Index the project cache, if there is one (the project cache feature, if installed): project_cache/INDEX.md first. Its documents are not context; the index is.
6. Verify yourself: every unit present, every pointer resolves. Then have a reviewer who did not do the conversion audit it: built from this exact source, every substantive line present, every section accounted for, every strong rule (never, must, non-negotiable) in a loaded file or in a procedure the routing row sends the agent to first, every name, path, number and id kept, a chain of pointers from CLAUDE.md reaches every section. Then run a live check: start a real agent in an isolated copy and ask it, in several phrasings, to find and state the instructions for each section; the files it opens must be the right ones. A replay test (the same frozen tasks given to the claude.ai Project and to an agent in the converted project) has not yet been run.
7. Apply only on the owner's go-ahead, additively. Replacing an existing CLAUDE.md is a separate yes.

6. Write CLAUDE.md At most 200 lines, no HTML comments, no @imports. In this order:

• the title with a three-line intro (project name, instructions version, date; say the source is not loaded);
• what the project is (five lines at most);
• the rule files, one line each;
• the folder map table;
• where to look: the index, reference, state, the cache index, live-project documents, TODO.md;
• the routing table, one row per skill: the task in the user's words, the procedure path, the skill name;
• how to work: pointers to the rules for session start, the stop protocol, secrets and deletion;
• last line: Instructions version synced: <version> (<date>).

Pointer rules, so an agent that starts with only CLAUDE.md, the rules and the skill descriptions can walk to every other piece:

• A pointer is the project-relative path in backticks with forward slashes. Not a bare name, not a backslash path, not a description.
• A pointer sits in text the model sees. Never only in an HTML comment (not shown to the model) or in frontmatter other than description.
• No @imports: they load in full with the importing file, so they save nothing and hide the pointer.
• The index (admin/README.md) names every rule, procedure, reference and state file by exact name, marks which procedures are skills, and lists files that exist only in the live project under their own heading.
• Every strong directive is in a loaded file, or in a procedure the routing row for that task sends the agent to first. Never only in state.
• The project cache: CLAUDE.md has one routing row for any question that needs a cached document, pointing to project_cache/INDEX.md first ("find the row for the task, open that file, a large file by the line range in the index"). No individual cache file is pointed to from a loaded file. The cache files are never moved, renamed, edited or copied into the tree.
• Do not use path-scoped rules for global rules (they load only after a matching file is read). Do not rely on subagents for rules: the built-in Explore and Plan subagents start without CLAUDE.md.
• The limits (200 lines, about 10,000 tokens for the loaded layer) are guidelines, and the loading behaviours above were tested on Claude Code 2.1.308 on 2026-10-28. Check them against the current Claude Code memory, skills and hooks documentation before relying on them.

7. Adding new items later A new item is a rule, a procedure, a reference document or a whole feature. It never means editing CLAUDE.md.

• Source first (the default). Back up admin\AGENT_INSTRUCTIONS.md, add the item there, bump the version, add a change-log row. That is the whole change. CLAUDE.md still points at the right files and is not touched. When the owner wants the new item reachable from CLAUDE.md, re-run the conversion (step 5): with unchanged headings the unit ids and the review carry over, so the re-run is quick, and the new item gets its rule file, procedure file, skill, routing row and index entry. Replacing the live CLAUDE.md is a separate go-ahead.
• Structure first (when the owner wants to add something without touching the instructions). A new hard rule is a file in .claude/rules/ with the header authored-in-structure <date>, a line in CLAUDE.md and an entry in the index. A new procedure is admin/sop/<name>.md, a skill, a routing row and an index entry. Every such file is listed in admin/state/structure-changes.md so it can be added back to the instructions. Which of the two is master is the owner's decision (see Ask).
• Installing another catalog feature is a source-first change: the feature adds its section to admin\AGENT_INSTRUCTIONS.md as it always did, and CLAUDE.md is left alone.

8. A project whose CLAUDE.md is already a mirror Leave the mirror in place until the conversion passes its audit, and mark the state "temporary full copy" with the date in the instructions section from step 2. While it is a temporary full copy, do not regenerate it when the instructions change; refresh it only if the owner asks. Then, with the owner's go-ahead, remove the mirror lines (step 2), and after that replace CLAUDE.md with the entry file, again on the owner's go-ahead. A project with a cache gets the index first.

Confirm

Confirm: CLAUDE.md is at your project root as a short entry file that points Cowork and Claude Code to your rules and procedures, and your full instructions stay whole in admin\AGENT_INSTRUCTIONS.md. From now on, adding a rule, procedure or feature means editing the instructions only; CLAUDE.md changes only when you approve a re-run of the conversion. If your project is not converted yet, say that your current CLAUDE.md is marked a temporary full copy with today's date. Want to install another, or is that everything for now?