agentleFS
developerz-aideveloperz-ai/gold-standards-in-ai/CLAUDE.md

gold-standards-in-ai

CLAUDE.md2 starsChanged yesterdayMITView on GitHub

Knowledge base for AI coding agents — Markdown only, no code to build, no tests to run. Run from the repo root; each script resolves the repo root itself.

  • Reads credentials

The file

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

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run from the repo root; each script resolves the repo root itself.

    line 27

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

Gold Standards in AI

Knowledge base for AI coding agents — Markdown only, no code to build, no tests to run.

What this is

QuestionAnswer
WhatKnowledge base for AI coding agents — how developerz-ai builds software fast with agents
Who reads itAn agent, before it starts a project: conventions, stack, infra, how to set a repo up so agents thrive
What is insidedocs/**/*.md — self-contained, dense, copy-paste oriented
What it is notA codebase — no runtime, no dependencies, no build step
One brainAGENTS.md points here — a pointer, never a second copy

Stack

PieceReality
ContentMarkdown only — no runtime, no dependencies
Scriptsbash under bin/
Gatebin/check — the same gate CI runs
CI.github/workflows/ci.yml — bin/setup + bin/check on push and pull_request
Pre-commit.githooks/pre-commit → bin/check; activate once per clone: git config core.hooksPath .githooks

Commands

Run from the repo root; each script resolves the repo root itself.

CommandDoesRun
bin/setupmise install when mise is present; echoes gold-standards-in-ai: markdown only, no dependencies to installonce, after clone
bin/devechoes gold-standards-in-ai: no app to run - read README.md for the mapevery session
bin/checkthe gate — bin/check-docs + bin/test; silent on success; exit 0 pass, exit 75 an unmet precondition, any other nonzero redbefore every commit
bin/check-docsmap + relative-link validation, including #fragment resolution against the target's headings and a docs/README.md row per section directory; one line per finding; exit 1 on a finding, exit 75 when it cannot grade — a missing docs/ treewhile editing docs
bin/testregression fixtures for the validator; no downloaded dependencieswhen bin/check-docs changes
bin/stopno-op — nothing to stop, never removes datasession end (the platform runs it)

Structure

PathWhat
README.mdthe map — every doc is linked from it
AGENTS.mdpointer to this file — one brain, never two
docs/README.mddocs index
docs/00-philosophy.mdthe core thesis; indexed in the root README.md and in docs/README.md — its section index, both required indexes
docs/<section>/README.mdindex for each section
docs/<section>/<topic>.mdone topic per file
docs/<section>/8 sections — ai-agents, architecture, developer-experience, frontend-craft, infrastructure, stack, workflow, writing-for-agents
.claude/agents/specialists — writing-rules.md, readme-index.md, link-integrity.md, dated-claims.md
.claude/commands//feature — the doc workflow · /planx — plan slices
.claude/skills/verify-change · stale-claims · plan-slices
.dz/maintainer bot — maintainer/maintainer.yml, briefs/, onboarding/
.mcp.jsonMCP servers — sentry-mcp, codegraph, developerz
.env.examplenames only — copy to .env; never commit .env
bin/the scripts above

Writing rules

RuleFails when
Lead with the rule, not the reason. Fragments over sentences. Tables over paragraphs.a section opens with a tour of the repo
Keep file paths, commands, env vars and model IDs verbatim — compress prose only.a path or a command is paraphrased
One topic per file. Keep each file scannable in one pass.a file answers two questions
Use a table for any list of three or more rows.rows are flattened into prose
No meta-framing, no rhetoric, no trailing summary paragraph."This section covers…" appears
Use emojis in headings/READMEs for navigation; keep code blocks clean.a heading loses its marker
Cross-link a sibling with a relative link instead of restating it.the same text is copied twice
Date load-bearing claims (As of 2026-06).a load-bearing claim carries no date
Keep examples vendor-neutral and reusable. Prefer the latest Claude models when showing model IDs.an example names a client
Index rows carry a link + a one-line hook; a section row uses the bare filename, relative to the section directory.a section row spells its own section path

Long form and self-check list: docs/writing-for-agents/compressed-config.md.

Hard rules

RuleFails when
No secrets, no private hostnames/IPs, no client names.a doc names a token, an internal host or a customer
Every doc is linked from README.md and its section README.md.bin/check-docs prints the path for a doc missing from either index
Delete stale docs rather than let them rot — a wrong doc costs more than a missing one.a doc contradicts the tree it describes
Never --force, never git stash; one checkout per team, never a worktree inside it — this repo is the one-checkout row of worktrees: when.another writer's checkout moves under them

Where to look

NeedRead
The map of every docREADME.md
The thesisdocs/00-philosophy.md
The house writing rules, long formdocs/writing-for-agents/compressed-config.md
How to write a project braindocs/writing-for-agents/claude-md.md
The doc workflow, end to end.claude/commands/feature.md
Plan slices for a doc set.claude/commands/planx.md
Prove a change before committing.claude/skills/verify-change/SKILL.md
Monthly upkeep of dated claims and links.claude/skills/stale-claims/SKILL.md
House style specialist.claude/agents/writing-rules.md
README map specialist.claude/agents/readme-index.md
Link resolution specialist.claude/agents/link-integrity.md
Claim freshness specialist.claude/agents/dated-claims.md
The policy the maintainer bot obeys.dz/maintainer/maintainer.yml

Git rules

RuleFails when
One checkout, many hands — work in this checkout; split a team into disjoint path sets so no two agents touch the same file.two writers meet in one file
Name the paths on git add; never git add -A.an editor's scratch file ships
Wait for every writer before committing.a half-written doc lands
git fetch before each slice; a file that moved on main is three-way merged, never overwritten wholesale.main's index rows vanish silently
One PR in flight; cap a PR at ~25–30 changed files — the docs-repo row of PR cap by repo kind.review becomes a formality
Scratch notes, draft plans and agent summaries never ship.the PR carries files nobody meant to add
Merge only on a green gate — bin/check local, CI green, review approved.a red check is merged around

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.