Your Repo Already Knows How To Build Itself. Put That In the CLAUDE.md.

The most useful line in a CLAUDE.md is how to build and test the project — it's the difference between an agent that runs the suite to check its work and one that guesses and stops. It's also the line people most often leave out, because when you sit down to write a context file you reach for conventions ("use strict mode," "prefer named exports") and forget the basics the agent actually needs to be effective.

Here's the thing: you don't have to remember it, because your repo already declares it. package.json has a scripts block. There's a Makefile, a go.mod, a pyproject.toml, a Cargo.toml. The build and test commands are sitting right there in machine-readable form. So instead of writing a CLAUDE.md from a blank page, generate the factual part from what the repo already says, and spend your effort only on the judgment part. That's claude-md-gen.

What it does

$ claude-md-gen -o
wrote ./CLAUDE.md  (3 command(s), 1 source dir(s) detected). Refine it, then context-lint it.

$ cat CLAUDE.md
# svc

TypeScript/JavaScript project.

## Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

## Layout
- Source: `src/`

## Conventions
- _Add only universally-applicable rules here. Keep this file lean — it loads
  into every session. Put task-specific detail in your prompt, and deeper docs
  under docs/ or a skill._

It reads the real signals and writes a short, correct starting point:

• Commands — from package.json scripts (and it picks the right runner — pnpm/yarn/bun/npm — by which lockfile is present), or pytest from a pyproject.toml, go test ./... from a go.mod, cargo test from a Cargo.toml, bundle exec rspec from a Gemfile, make test from a Makefile target. The exact commands the project already defines.
• Layout — the top-level source directories that actually exist (src/, cmd/, internal/, …).
• Conventions — left as a clearly-marked placeholder, because this is the part only you can write.

The one rule: it doesn't make things up

The fastest way to make a tool like this useless is to have it fabricate. If a repo declares no build or test command, claude-md-gen does not invent a plausible-looking npm test — it writes an honest placeholder:

## Commands
- Build/test: _add the commands here — this is the most useful line for the agent._

A CLAUDE.md that confidently states a wrong test command is worse than one that admits it doesn't know — the agent will trust it and run the wrong thing. So the tool only ever states what the repo actually says, and flags the gap when the repo says nothing. (A test pins exactly that: a repo with no signals produces the placeholder, never a fabricated command.)

It pairs with the auditor

claude-md-gen writes the file; context-lint checks it. Run them back to back and the loop closes:

$ claude-md-gen -o && context-lint
context-lint — CLAUDE.md  (6 instructions · ~87 tokens/session)
  ✓ lean and current — nothing to trim.

That clean result isn't a coincidence — generate-then-lint is a tested invariant: a freshly generated file is lean, current, and has the build/test commands, which is exactly what the auditor wants to see. Generate to get a correct skeleton; lint to keep it correct as the repo evolves.

Using it

claude-md-gen              # print a starter to stdout (review before committing)
claude-md-gen -o           # write ./CLAUDE.md (refuses to clobber an existing one)
claude-md-gen path/to/repo # point it anywhere

It refuses to overwrite an existing CLAUDE.md — it's for bootstrapping, not for stomping the file you've already tuned. The intended flow is: generate the skeleton, fill in the conventions that matter, and from then on let the linter keep it honest.

The honest limits

It generates a correct skeleton, not a finished context file. It knows the commands and the layout because the repo states them; it knows nothing about your team's actual conventions, the gotchas, the one service that needs a special env var — that's the part it deliberately leaves for you. And the detection is signal-based: an unusual build setup it doesn't recognize lands in the placeholder, which is the right failure mode (a gap you fill, not a wrong answer you have to notice). Treat the output as a first draft that gets the boring, factual 60% right so you can spend your attention on the 40% that needs a human.

The real lesson

A blank CLAUDE.md is intimidating in exactly the wrong way: it makes you reach for opinions and skip facts. But the highest-value content isn't opinions — it's the build and test commands, and those are already written down in your repo. Generate that part, keep it lean, lint it as it ages, and put your actual effort into the judgment a generator can't have. The file gets better, and writing it stops being a chore you avoid.

We build and run autonomous agent fleets on Claude Code in production. If you're standardizing agent setup across repos, talk to us.

---

Get the tool → claude-md-gen in agent-ops — open source (MIT), a single dependency-free script, part of our toolkit for running coding agents in production.