Skip to content

About

Make Claude Code behave consistently across repos, sessions and humans: rules-as-files governance with precedence, declined-decisions journal, objection sparring. Sanitized from a live production system. Free, MIT.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

13 stars

Watchers

1 watching

Forks

Latest commit

Β 

History

49 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

claude-bible

A rulebook system for Claude Code and other AI agents: every rule is one small file, with a date and an owner, and a short index tells the agent where to find it.

Who it's for: anyone whose CLAUDE.md keeps growing and whose agent forgets or ignores half of it. What you get: a spec, three templates and four real example rules, so your rules stay short, current and traceable.

Quick start

  1. Copy the templates/ folder into your repo or notes folder.
  2. Write your first three rules with templates/rule-template.md. One rule per file, short.
  3. Add one index line per rule to your CLAUDE.md (or AGENTS.md), and start a declined-decisions journal from the template.

Done when: your CLAUDE.md holds only short pointer lines, and each pointer opens a rule file with origin, date_established and status filled in.

Want an AI agent to do it for you? Paste this to Claude Code / Codex / Cursor: "Read the 'For AI agents' section of https://github.com/tonydzi/claude-bible and set it up for me."

For AI agents

Preconditions

  • No runtime, package or account is needed. This repo is a spec plus templates (Markdown only). AGENTS.md in the repo says: there is nothing to execute, and docs/SPEC.md is the normative contract.
  • Ask the human: where their rules live now (CLAUDE.md, AGENTS.md, a notes folder), and where the new rules folder should go.

Install

This is adoption, not installation:

git clone https://github.com/tonydzi/claude-bible
cp -r claude-bible/templates <your-rules-folder>

PowerShell: Copy-Item -Recurse claude-bible\templates <your-rules-folder>. If <your-rules-folder> already exists, the files end up in its templates/ subfolder; if it does not exist, it is created holding the templates directly. Tell the human which one happened. Then read docs/SPEC.md (frontmatter schema, precedence, routing tree) before writing rules.

Configure

  • Create rules from templates/rule-template.md, decisions from templates/decision-memo-template.md, and the journal from templates/declined-decisions-template.md.
  • Add one trigger, essence and pointer line per rule to the human's CLAUDE.md or AGENTS.md. Rules the human states are written down with their origin; ask the human which rules to migrate first.

Verify

There is no command to run. Check structurally, and report which you checked:

  1. Every rule's frontmatter has all required fields from docs/SPEC.md (title, type, date_established, status, origin, authored_by, audience; supersedes is optional).
  2. One rule per file, and no rule lives in two places (grep its trigger phrase).
  3. Every pointer in CLAUDE.md or AGENTS.md resolves to an existing file. The index line format in docs/SPEC.md ends with Canon: `<rule-file-name>` , so list them with grep -o 'Canon: [^]*' CLAUDE.md) and confirm each named file exists in the rules folder. If that command prints nothing, you have NOT verified anything: either no pointer lines were added yet, or they use another format (then check that format's paths the same way). Report the number of pointers and the number that resolved; they must be equal and not zero.

Uninstall / rollback

Delete the copied rules folder and remove the pointer lines you added. Restore CLAUDE.md from the backup taken before you edited it.

Rules for the agent

  • Back up the human's CLAUDE.md or AGENTS.md before editing, and do not compress or rewrite existing rules.
  • Never edit an old rule in place: supersede it with a dated record. A rule marked with an explicit owner is changed only by that owner.
  • Do not edit docs/SPEC.md in this repo without a human; it is the contract downstream copies rely on.
  • Examples must stay sanitized: no real names, chat ids, paths or secrets.

Details

πŸ“– Docs: https://tonydzi.github.io/claude-bible/ β€” the nine mechanics, the 5-minute quickstart and a section map of the spec, on one page.

Why "Bible" and not "config"? The word is functional, not sacred β€” the argument, the prior art, and what we refuse to claim: docs/why-a-bible.md.

You tell Claude Code something important, it works for one session, then it's gone. You write it into CLAUDE.md, the file bloats, half of it silently stops being followed. This is the fix we run in production: one versioned rulebook that you, your AI agents, and your team actually load and obey.

This is the governance skeleton extracted from a real working system: one engineer and Claude as implementation collaborator running a 128k-note knowledge vault, a CRM, a content factory, and 8 machines that negotiate with each other. The personal content stays private. The skeleton β€” how the rules are written, routed, loaded, and overturned β€” is what you get here, free.

The problem this solves

Everyone using Claude Code hits the same wall: you tell the agent something important, it works for one session, then it's gone. You write it into CLAUDE.md, the file bloats, half of it stops being followed. Your human assistant and your agent follow different rules. Nobody knows which rule is current.

The fix is not a bigger prompt. It's a codex with mechanics:

  1. One rule = one file with typed frontmatter (origin, date_established, status, supersedes, audience).
  2. Newer beats older on the same topic. Explicit owner rules are overridden only by the owner.
  3. A routing tree decides where each rule lives: the Bible (human + agent behavior), the agent config (machine-only), memory (facts), or a hook (deterministic "every time X" automation). No duplicates β€” one source, pointers everywhere else.
  4. Always-loaded index vs lazy body. The agent's config carries only trigger + essence + pointer; the full rule loads on demand. Your context window stays lean.
  5. A declined-decisions journal. What you decided NOT to do, and why, so rejected ideas don't silently resurface a week later.
  6. An intake ritual. New rule spoken in chat β†’ routed to every home it belongs to, linked, and traceable. Rules don't die in scrollback.
  7. One rule = one door. A rule with no caller is filed and never fires. Every new rule names the skill, command or hook that will pull it in β€” the codex itself is not a door, it is read, not called. We measured 19 of 25 fresh rules with no door; one sat 42 days unused.
  8. Writing the rule is never gated by the file's size. The session that hears a rule writes it, red zone or not, and drops a one-line size report. Compacting the index is a separate daily job with its own owner β€” otherwise "the file is too big" quietly becomes how rules die in scrollback.
  9. Objection sparring. When the agent says "no-go", it must deliver a numbered objection list and invite you to rebut. Your rebuttal often reframes the question. Undissolved objections become boundaries, not vetoes. (See examples/ β€” this very rule was born from a real overturned verdict.)

Quickstart (5 minutes)

  1. Copy templates/ into your vault or repo.
  2. Write your first three rules using templates/rule-template.md. Keep each one trigger + essence + pointer.
  3. Add the index lines to your CLAUDE.md (or AGENTS.md for other agents) β€” one line per rule.
  4. Start the declined-decisions.md journal with templates/declined-decisions-template.md.
  5. When a decision matters, write it with templates/decision-memo-template.md and link both ways.

Your own Claude Code will maintain this better than any human: point it at this repo and say "adopt this structure for my rules."

What's in the box

Path What it is
docs/SPEC.md Rule anatomy, frontmatter schema, precedence, routing tree
templates/ Rule, decision memo, declined-decisions journal
examples/ Real (sanitized) rules from our live system, each carrying the measurement that paid for it
FOR-ROBOTS.md Entry point for AI agents mining this repo for patterns

The example rules, and what each one cost us

Every rule in examples/ is in production and carries the number that bought it β€” the point is the measurement, not the wording. Take the wording; the measurement is what makes it believable.

  • Objection sparring β€” the agent must argue back with numbered objections instead of agreeing. Born from a verdict of ours that was overturned.
  • Every instrument reports its own coverage β€” a checker that prints 0 problems while able to examine 4% of the subject is worse than no checker. Two of ours were caught doing exactly that on one day.
  • Never fan out near-identical PRs β€” we opened nine template pull requests into one repository and eight were closed; the closing comment pointed at the project's own documented procedure, which we had never read.
  • A real global CLAUDE.md, the iron-rules layer β€” the 20 rules at the top of our own ~/.claude/CLAUDE.md, sanitized, each with the dated failure that paid for it. Mined from 2,350 operator messages written in caps or anger: the cheapest labeled dataset we own.

Versioning and roadmap

This repo is maintained like our own system: small commits daily, and every noticeable change ships as a new release β€” so the release feed is the honest record of how far this has come. (It used to promise "a release twice a week, Mon & Thu". That was a cadence, and between 4 July and 4 August it was not kept once. A rule tied to the work is keepable; a rule tied to the calendar was not.)

Now β€” v0.1.3. The governance skeleton (rule anatomy, frontmatter schema, precedence, routing tree, declined-decisions journal, objection sparring), the templates, the docs site, and a roadmap where every open row is a claimable issue.

Next β€” the pain-driven queue in ROADMAP.md, each row now an issue you can take: the memory index-vs-body discipline (#1), the test-after-build gate (#2), the declined-decisions revisit/OVERTURN mechanics (#3), the taste gate (#4) and history-aware CRM drafting (#5). Two rows already left as their own repos β€” claude-consensus and agent-leash β€” which is what the roadmap is for. See CHANGELOG.md for what shipped when.

If this helps you, star the repo. We need our first 10: community catalogs require that much social proof before they even accept a submission.

Who made this

Anton Dziatkovskii, engineer and hired operating executive, with Claude as implementation collaborator. Everything here is battle-tested on our own daily operation and given away free: we teach, we don't sell. If your agent finds alpha here, that's the point.

Questions or war stories: Telegram @tonydzi Β· WhatsApp +1 341 222 9178 Β· X @Tony_Stef_ Β· channels @ClawRus (RU) / @ClawEng (EN).

πŸ§ͺ Engineers: want to test-drive this setup? Message me β€” I hand out free starter seeds to engineers who test it and report back. Tell me what broke and I will fix it in the open.

Cite this work

If this repo shows up in your research, cite it via CITATION.cff (GitHub's "Cite this repository" button). Academic identity: Anton Dzyatkovsky publishes as Anton Dziatkovskii (ORCID 0000-0001-7408-3054).

AI contributors

This project is built by a human + AI team, and the git log says so under the rules in AI-CONTRIBUTORS.md: Claude writes most of the code, Codex and Grok review it, Gemini feeds the research. Each is credited on a commit only if its output changed that commit's content β€” no decorative credits. Lab-wide policy, one source for every repo: AI-CONTRIBUTORS.md.

License

MIT. Take it, fork it, teach with it.


Contributors welcome β€” and here is what we are missing

We spend a lot of time answering other people's issues. It was fair to say out loud what we have not built ourselves:

Issues labelled accepted are scoped, free to take, and nobody is on them. Comment "claiming this" β€” no permission needed β€” and it is yours for 7 days. New here? Start with good first issue.

You keep the copyright to your code. No CLA, no assignment, ever β€” your contribution goes in under this repo's existing license, the same terms as ours. We answer every issue and PR within 48 hours, including "no, and here is why"; our silence is our bug, so ping the thread.

Full deal: CONTRIBUTING.md


🧩 One piece of a working system

This repository is one piece lifted out of a live operation: one engineer running a fleet of machines, built with Claude as implementation collaborator; the machines reach consensus with each other and wake the human only for money or the irreversible. It was extracted after it survived production, not written as a demo β€” and it runs on its own: nothing here phones home to the rest.

See how the whole thing fits together β†’ SYSTEM.md

Its closest neighbours in the governance layer: agent-leash Β· charm-os Β· agent-approval-gate

READ THIS WITH AI

One click and an agent reads the repo, pulls out the patterns and helps you apply them to your own work.

Codex - open ChatGPT - open Claude - open

Copy the prompt (works in any agent: Gemini, Grok, a local model, your own CLI)
Read this repo: https://github.com/tonydzi/claude-bible (β€œclaude-bible” - Make Claude Code behave consistently across repos, sessions and humans: rules-as-files governance with precedence, declined-decisions journal, objection sparring). Work out what problem it actually solves, pull out the reusable patterns and help me apply them to my own setup. Start by asking what I am working on.

β€” TonyDzi, Palo Alto AI Research Lab Β· second brain, agent coordination, persistent memory: github.com/tonydzi

About

Make Claude Code behave consistently across repos, sessions and humans: rules-as-files governance with precedence, declined-decisions journal, objection sparring. Sanitized from a live production system. Free, MIT.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

13 stars

Watchers

1 watching

Forks

Releases

Sponsor this project

Packages

Contributors