Blastdoor
CLAUDE.md0 starsChanged 57 days agoMITView on GitHub
A snapshot of your working tree taken the moment before a coding agent runs something destructive, and a way back. Node 18+, ESM, zero dependencies, git plumbing — 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 base stack silently. Build config,…
- Commits and pushes
In this repository3 other files it gives its agents.
- close-sessionSkill
- log-mistakeSkill
- recallSkill
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
- Distinctive: line 11
No new dependency without asking: If you think one is needed, stop and say why.
- Distinctive: line 34
Read before you plan: Not before the first edit — before the plan.
- Distinctive: line 48
Write as you go: Do not save it for the end of the session:
- Distinctive: line 79
No emojis in code or files unless asked.
- Very specific: line 80
No new .md files at the repo root.
- Distinctive: line 82
Do not mock behaviour that can be tested against real data.
≈ “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.
Files
blastdoor
A snapshot of your working tree taken the moment before a coding agent runs something destructive, and a way back.
Stack in one line
Node 18+, ESM, zero dependencies, git plumbing — details in ARCHITECTURE.md.
Non-negotiables
- No new dependency without asking. If you think one is needed, stop and say why.
- Simple beats clever. Two ways to do it? Take the obvious one. Do not abstract for a future that has not arrived.
- Do not touch the base stack silently. Build config, tsconfig, package manifests, CI, headers — say what and why first.
- Do not commit unless asked. Show the diff and wait.
- Do not clean up code unrelated to the task at hand.
- 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.
| File | What it holds | When you touch it |
| STATE.md | Where the project is right now. A snapshot, not a diary. | End of every session |
| MISTAKES.md | Something broke. What, why, and the guardrail that stops it recurring. | The moment it happens |
| LEARNINGS.md | Something worked unusually well and is worth reusing. | The moment it happens |
| DECISIONS.md | A choice made, with the alternatives considered. | When the choice is made |
| ARCHITECTURE.md | How 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 isThis 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 areaThe 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
- The build passes (see Commands above). If it does not, say so in
STATE.mdunder In flight rather than closing quietly on red. STATE.mdreflects reality, and itsupdated:line is today.- Anything that broke is in
MISTAKES.md, with a guardrail — not just a description. node .bitacora/cli.mjs doctoris 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
.mdfiles 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.
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.

