agentleFS
sheldor26sheldor26/whatloads/CLAUDE.md

whatloads

CLAUDE.md0 starsChanged 56 days agoMITView on GitHub

Audit the agent setup in a repository: what your instructions cost every session, which skills can never fire, which hooks write where nobody reads. Node 18+, ESM, zero dependencies, no build step — details in ARCHITECTURE.md. 1. No new dependency without asking. If you think one is needed, stop and say why. 2. Simple beats clever. Two ways to do it? Take the obvious one. Do not abstract for a future that has not arrived. 3. Do not touch the…

  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

6 rules. About 0 are common, 5 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No new dependency without asking: If you think one is needed, stop and say why.

    line 11
  2. Distinctive:

    Read before you plan: Not before the first edit — before the plan.

    line 34
  3. Distinctive:

    Write as you go: Do not save it for the end of the session:

    line 48
  4. Distinctive:

    No emojis in code or files unless asked.

    line 79
  5. Very specific:

    No new .md files at the repo root.

    line 80
  6. Distinctive:

    Do not mock behaviour that can be tested against real data.

    line 82

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 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

whatloads

Audit the agent setup in a repository: what your instructions cost every session, which skills can never fire, which hooks write where nobody reads.

Stack in one line

Node 18+, ESM, zero dependencies, no build step — details in ARCHITECTURE.md.

Non-negotiables

  1. No new dependency without asking. If you think one is needed, stop and say why.
  2. Simple beats clever. Two ways to do it? Take the obvious one. Do not abstract for a future that has not arrived.
  3. Do not touch the base stack silently. Build config, tsconfig, package manifests, CI, headers — say what and why first.
  4. Do not commit unless asked. Show the diff and wait.
  5. Do not clean up code unrelated to the task at hand.
  6. Write the record in English. Talk with me in whatever language I use, but CLAUDE.md, the logbook, code comments and commit messages are written in English. They outlive the conversation and are read by people who were not in it.

The loop

This project keeps a logbook. It is not documentation — it is working memory that survives between sessions.

FileWhat it holdsWhen you touch it
STATE.mdWhere the project is right now. A snapshot, not a diary.End of every session
MISTAKES.mdSomething broke. What, why, and the guardrail that stops it recurring.The moment it happens
LEARNINGS.mdSomething worked unusually well and is worth reusing.The moment it happens
DECISIONS.mdA choice made, with the alternatives considered.When the choice is made
ARCHITECTURE.mdHow the thing is built and why.When the shape changes

Read before you plan. Not before the first edit — before the plan. A plan written without the history bakes the repeat mistake into it, and implementation then carries it out faithfully. Pull the relevant history instead of reading whole files:

node .bitacora/cli.mjs recall <tag>        # prints the matching entries in full
node .bitacora/cli.mjs stats               # where the recurring friction is

This is deliberate. The logs are never @-imported into this file: an @MISTAKES.md would burn thousands of tokens on every session for history that is irrelevant 90% of the time. Retrieve by tag, pay only for what you use.

Write as you go. Do not save it for the end of the session:

node .bitacora/cli.mjs new mistake  "Short, specific title" --tags area,failure-mode --severity high
node .bitacora/cli.mjs new learning "Short, specific title" --tags area
node .bitacora/cli.mjs new decision "Short, specific title" --tags area

The command scaffolds the entry and assigns the id; you write the prose. doctor rejects an entry whose sections are unfilled, and rejects a mistake whose Guardrail says nothing — naming a check, a test, a type or a refusal in the code, not an intention to be more careful next time.

Commands

npm run test  # test suite
node .bitacora/cli.mjs doctor  # is the logbook healthy?

Before closing a session

  1. The build passes (see Commands above). If it does not, say so in STATE.md under In flight rather than closing quietly on red.
  2. STATE.md reflects reality, and its updated: line is today.
  3. Anything that broke is in MISTAKES.md, with a guardrail — not just a description.
  4. node .bitacora/cli.mjs doctor is green.

What not to do

  • No git push, no --force, no branch deletion unless asked explicitly.
  • No emojis in code or files unless asked.
  • No new .md files at the repo root. The logbook has a place for everything; if something genuinely has no place, say so instead of inventing a file.
  • Do not mock behaviour that can be tested against real data.

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.