claude-longrun
CLAUDE.md2 starsChanged 4 months agoMITView on GitHub
This is a working template. Copy it to the root of your project and fill in the <> blanks. It is loaded automatically at the start of every session, so keep it to rules, protocols and behavioural requirements — not project trivia, which belongs in the files it points at. Length discipline matters: this file is paid for on every single session. Under ~200 lines. Anything longer is a pointer, not a paste. Other context to read at session start:
In this repository2 other files it gives its agents.
- day-closeSkill
- session-closeSkill
The file
We split this CLAUDE.md into the rules it gives an agent
11 rules. About 0 are common, 3 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 35
Run the "Session start" section of protocols/session-protocol.md.
- Very specific: line 40
Read OWNER.md — who, active phases, goals, explicit non-goals
- Very specific: line 41
Read CONTEXT.md — the current focus
- Very specific: line 42
Read PROJECTS.md — which project is active
- Very specific: line 43
Read projects/<active>/STATE.md + the newest file in SESSIONS/
- Very specific: line 44
Read the last 20 entries of logs/corrections.json
- Very specific: line 59
Run the "Session end" section of protocols/session-protocol.md: step 0 is the session digest + drift check (a git window across your repos …
- Very specific: line 80
Deduplicate before writing: Before creating a new note, search for an existing one on the topic.
- Distinctive: line 83
An index is the first lookup: Keep a catalogue of your notes with one-line descriptions and read *that* before grepping the whole base.
- Distinctive: line 131
Every note starts with YAML frontmatter.
- Distinctive: line 148
Document work as a real project: README + STATE + SESSIONS + DECISIONS.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md — agent instructions
This is a working template. Copy it to the root of your project and fill in the
<>blanks. It is loaded automatically at the start of every session, so keep it to rules, protocols and behavioural requirements — not project trivia, which belongs in the files it points at.Length discipline matters: this file is paid for on every single session. Under ~200 lines. Anything longer is a pointer, not a paste.
Other context to read at session start:
OWNER.md— who the owner is, what they are working on, where it is goingarchitecture.md— the static structural model: folder layout, key decisions, how it fits together (optional in ordinary work; read it for onboarding sessions)GLOSSARY.md— terms, abbreviations, project vocabulary
architecture.md(the static model) is notCONTEXT.md(the current, moving focus). Two different things. Conflating them is howCLAUDE.mdgrows to 600 lines.
Language and style
- Communication language:
<your language> - Style: concrete, to the point, no filler
- Ask, don't guess — when something is ambiguous, ask before building
- Corrections get recorded in
logs/corrections.jsonpercorrection-protocol
Session start
Run the "Session start" section of
protocols/session-protocol.md. In short:
git pull --ff-onlybefore reading anything — otherwise you may be working from a stale tree. (Automated by theSessionStarthook.)- Read
OWNER.md— who, active phases, goals, explicit non-goals - Read
CONTEXT.md— the current focus - Read
PROJECTS.md— which project is active - Read
projects/<active>/STATE.md+ the newest file inSESSIONS/ - Read the last 20 entries of
logs/corrections.json - Check
inbox/queue.md
Light start (the newest session log for the active project is from today, or under 12
hours old): git pull → the NOW block in STATE → today's session logs → corrections.
Skip steps 1–3 and 6.
Reactive triggers — add your own:
<trigger phrase>→<skill name>
Session end
Run the "Session end" section of
protocols/session-protocol.md: step 0 is the session
digest + drift check (a git window across your repos plus token spend — that is the draft
material for the log; fix drift findings immediately), then write the session log, update
STATE, move ideas out, update CONTEXT, and commit.
Intermediate session-end (the day continues): digest + log + the NOW block + commit. Full ritual — only on an explicit "let's close the day".
Trigger semantics: "let's close" / "save this" / "session-end" / "we're done" =
INTERMEDIATE. FULL only on an explicit "close the day" / "end of day" / "that's it
for today". The UserPromptSubmit hook decides the mode; echo it back before acting.
Commands: /session-close · /day-close.
Principles
Files over context. Anything longer than a passing thought becomes a file. Cross-link between files wherever a relationship exists.
Deduplicate before writing. Before creating a new note, search for an existing one on the
topic. If one exists, decide explicitly: skip / new / replace / append.
An index is the first lookup. Keep a catalogue of your notes with one-line descriptions and read that before grepping the whole base. Generate it with a script; a hand-maintained index rots.
Archive, don't delete. Replacing a note moves the old one to _archive/ with a date.
Deletion happens only on an explicit request.
Preserve sources. Raw material is kept whole. Distillations live separately, next to it.
ADRs for decisions. Any non-trivial decision — architecture, tool choice, a change of
approach — is recorded as an ADR in the relevant project's DECISIONS/.
An event log as a second view. Files describe the state of the project; an append-only event stream describes the process. Log each significant pipeline step. Optional, but cheap and occasionally decisive when reconstructing what happened.
Visualization convention
Optimize for the agent reading it, not for a human admiring it. That changes the priorities:
Default — Mermaid (```mermaid blocks): renders natively in most markdown
viewers, the agent reads and writes the syntax fluently, git diffs stay readable, and it is
greppable. Use for flows, sequences, hierarchies, state machines, dependency graphs.
Inline ASCII for genuinely simple flows (two or three steps).
Binary drawing formats (Excalidraw and friends) only for freeform layouts Mermaid cannot express. The agent can read the exported PNG but writing the source is painful — a rare case, never the default.
Apply: new ADRs with a flow → Mermaid. Project READMEs with architecture → Mermaid. Process docs → a Mermaid sequence diagram.
Naming conventions
- Dates —
YYYY-MM-DD - Slugs —
lower-kebab-case - ADRs —
NNN-short-name.md(001, 002, …) <your own conventions here>
Frontmatter
Every note starts with YAML frontmatter. Minimum:
---
type: <note type>
created: YYYY-MM-DD
tags: [tags]
---Type-specific fields live in the matching template under templates/.
Active project
The current active project and phase live in OWNER.md. The full list is in PROJECTS.md.
Document work as a real project: README + STATE + SESSIONS + DECISIONS.
External code repos — this repo as home base
Working model: you always open Claude Code from this repo and work on code projects that
live in separate repos, wired in through permissions.additionalDirectories in
.claude/settings.local.json. That gives file access without prompts.
additionalDirectoriesgives file access ONLY — it does not load the other repo'sCLAUDE.mdor its skills. So the external project's entrypoint must be read explicitly.
When a session is about an external code project, add one step at the start:
- Read that repo's
CLAUDE.mdfirst — it is the working entrypoint (mode, deploy, gotchas, tests, orchestration). - Then the project's state here:
projects/<slug>/STATE.md(NOW block at the top).
Git: separate repos, separate commits. Never mix changes across them in one commit.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

