agentleFS
HermeticOrmusHermeticOrmus/dx-audit-skills/CLAUDE.md

dx-audit-skills

CLAUDE.md0 starsChanged 6 months agoMITView on GitHub

A protocol for auditing and improving developer experience (DX) in a codebase. Merge with project-specific instructions as needed. Developer experience is everything a contributor touches before they write their first useful line: the README, the setup steps, the scripts, the contributing guide, the env docs, the error messages, the tooling. When any of these is missing or wrong, every new contributor pays the cost silently, and the maintainer pays it again every time they answer the same question. Tradeoff: this…

  • Reads credentials

The file

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

8 rules. About 0 are common, 8 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    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 them on a clean checkout.

    line 29
  2. Distinctive:

    Do the script names match what the README and contributing guide reference?

    line 37
  3. Distinctive:

    Do setup scripts fail loudly with an actionable message?

    line 60
  4. Distinctive:

    Stop after each group and report what changed and what was verified.

    line 123
  5. Distinctive:

    Default to report-only when the mode is unstated.

    line 125
  6. Distinctive:

    Every documentation fix is a hypothesis about what works.

    line 129
  7. Distinctive:

    Run the quickstart on a clean checkout, not on your already-configured machine.

    line 131
  8. Distinctive:

    Run each documented script and confirm it does what the doc says.

    line 132

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

CLAUDE.md

A protocol for auditing and improving developer experience (DX) in a codebase. Merge with project-specific instructions as needed.

Developer experience is everything a contributor touches before they write their first useful line: the README, the setup steps, the scripts, the contributing guide, the env docs, the error messages, the tooling. When any of these is missing or wrong, every new contributor pays the cost silently, and the maintainer pays it again every time they answer the same question.

Tradeoff: this protocol biases toward measuring friction before fixing it. For a one-file script with no contributors, use judgment.

What to inspect

Walk the codebase as a new contributor would, in this order. For each dimension, record what exists, what is missing, and whether what exists is accurate.

1. README

The first file a contributor opens.

  • Does it say what the project is in the first paragraph?
  • Does it have a quickstart that gets to a running state?
  • Are the commands in it copy-pasteable and current?
  • Does it link to deeper docs rather than trying to be all of them?

2. Quickstart and setup

The path from git clone to a running app.

  • Is there a single documented sequence of commands?
  • Does it list prerequisites (runtime version, package manager, services)?
  • Are the steps in dependency order?
  • Run them on a clean checkout. Count how many fail, stall, or require undocumented knowledge.

3. Scripts

The commands a contributor runs daily.

  • Is there a task runner entry (package.json scripts, Makefile, justfile, taskfile)?
  • Are the common verbs present: install, dev, build, test, lint, format?
  • Do the script names match what the README and contributing guide reference?
  • Is there a script for the thing every contributor does manually instead?

4. Contributing guide

The rules a contributor needs before opening a PR.

  • Is there a CONTRIBUTING.md or equivalent section?
  • Does it cover branch naming, commit format, PR expectations, and how to run tests?
  • Does it match the actual workflow, or has the workflow drifted from the doc?

5. Environment docs

The configuration a contributor must supply.

  • Is there an .env.example (or equivalent) listing every required variable?
  • Is each variable annotated with what it is and where to get it?
  • Does the app fail with a clear message when a variable is missing, or with a cryptic stack trace?

6. Error messages

The feedback a contributor gets when setup goes wrong.

  • Do setup scripts fail loudly with an actionable message?
  • Does a missing dependency, wrong runtime version, or absent env var produce a sentence a human can act on?
  • Or does the contributor get a stack trace they have to decode?

7. Tooling

The guardrails that keep contributions consistent.

  • Is there a linter, formatter, and type-checker configured?
  • Are they wired to a pre-commit hook or CI so they run without being remembered?
  • Is there an editor config (.editorconfig) so style is consistent across machines?

How to score friction

For each dimension, assign a friction level. The goal is to find where the silent cost concentrates, not to produce a vanity number.

LevelMeaning
NonePresent, accurate, and discoverable. A new contributor succeeds without asking.
LowPresent but incomplete or slightly stale. Costs a minute of guessing.
MediumPresent but wrong, or absent where it matters. Costs a question to a maintainer.
HighAbsent or actively misleading. Blocks a new contributor until someone intervenes.

Two onboarding timings make the score concrete:

  • Time to first run: from clean git clone to a running app or passing test command.
  • Time to first contribution: from clean checkout to a correctly formatted, tested, ready-to-open PR.

A high-friction dimension is one that extends either timing past a reasonable threshold, or that cannot be completed at all from the documented steps.

Report-only vs implement modes

The audit runs in one of two modes. State which mode is active before producing output.

Report-only mode

Inspect, score, and report. Change nothing.

Produce a prioritized list of findings grouped by effort:

## DX audit report

### Quick wins (5-15 min)
- [High] No quickstart in README; add a five-line clone-to-run sequence
- [Medium] `.env.example` lists 4 of 7 required variables

### Medium effort (30-60 min)
- [Medium] Test command undocumented; add to README and a `test` script
- [Low] CONTRIBUTING.md references a lint step that no script exists for

### Larger work (2+ hours)
- [Medium] No type-checker configured; wire tsc + pre-commit hook

Each finding names the dimension, the friction level, and the specific fix. No vague advice.

Implement mode

Inspect, score, then apply fixes with approval, lowest-effort and highest-friction first.

  • Make surgical changes. Add the missing README section, create the .env.example, add the script, fix the error message. Do not refactor adjacent code.
  • For each fix, verify it: run the quickstart you just wrote on a clean checkout, run the script you just added, trigger the error path you just improved.
  • Stop after each group and report what changed and what was verified.

Default to report-only when the mode is unstated. Implementing changes a contributor never reviewed is itself a DX failure.

Verify before claiming a fix

Every documentation fix is a hypothesis about what works. Test it the way a new contributor would.

  • Run the quickstart on a clean checkout, not on your already-configured machine.
  • Run each documented script and confirm it does what the doc says.
  • Trigger the missing-env-var and wrong-version paths and read the message a contributor would see.
  • A README that has not been run on a clean checkout is a guess, not a fix.

Trigger this audit when

  • A new contributor asks the same setup question that a previous one asked
  • The README quickstart has not been run on a clean checkout since the stack changed
  • Setup takes longer than the time-to-first-run threshold the project accepts
  • Onboarding a teammate surfaces an undocumented step
  • A dependency, runtime version, or env variable changed but the docs did not

License: MIT. Use it, fork it, merge it into your own.

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.