agentleFS
toper2525ua-engtoper2525ua-eng/claude-longrun/CLAUDE.md

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:

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
  1. Very specific:

    Run the "Session start" section of protocols/session-protocol.md.

    line 35
  2. Very specific:

    Read OWNER.md — who, active phases, goals, explicit non-goals

    line 40
  3. Very specific:

    Read CONTEXT.md — the current focus

    line 41
  4. Very specific:

    Read PROJECTS.md — which project is active

    line 42
  5. Very specific:

    Read projects/<active>/STATE.md + the newest file in SESSIONS/

    line 43
  6. Very specific:

    Read the last 20 entries of logs/corrections.json

    line 44
  7. Very specific:

    Run the "Session end" section of protocols/session-protocol.md: step 0 is the session digest + drift check (a git window across your repos …

    line 59
  8. Very specific:

    Deduplicate before writing: Before creating a new note, search for an existing one on the topic.

    line 80
  9. Distinctive:

    An index is the first lookup: Keep a catalogue of your notes with one-line descriptions and read *that* before grepping the whole base.

    line 83
  10. Distinctive:

    Every note starts with YAML frontmatter.

    line 131
  11. Distinctive:

    Document work as a real project: README + STATE + SESSIONS + DECISIONS.

    line 148

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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 going
  • architecture.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 not CONTEXT.md (the current, moving focus). Two different things. Conflating them is how CLAUDE.md grows 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.json per correction-protocol

Session start

Run the "Session start" section of protocols/session-protocol.md. In short:

  1. git pull --ff-only before reading anything — otherwise you may be working from a stale tree. (Automated by the SessionStart hook.)
  2. Read OWNER.md — who, active phases, goals, explicit non-goals
  3. Read CONTEXT.md — the current focus
  4. Read PROJECTS.md — which project is active
  5. Read projects/<active>/STATE.md + the newest file in SESSIONS/
  6. Read the last 20 entries of logs/corrections.json
  7. 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.

additionalDirectories gives file access ONLY — it does not load the other repo's CLAUDE.md or 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:

  1. Read that repo's CLAUDE.md first — it is the working entrypoint (mode, deploy, gotchas, tests, orchestration).
  2. 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.