claude-md-init

A good CLAUDE.md is short, true, and command-centric. Aim for 40 to 80 lines.

Procedure

1. Inventory (read, do not guess): ls, cat package.json | jq .scripts, Makefile targets, pyproject.toml / setup.cfg, Cargo.toml, go.mod, docker-compose*.yml, .github/workflows/*.yml (what CI actually runs), README.md headings, .editorconfig, lint configs.
2. Verify each command you intend to list by running its cheapest, read-only form (npm run / pnpm run to list scripts, make -n test, pytest --collect-only -q | tail -1). Do not run installs or anything that writes to the tree; if a check would modify files, dry-run or skip it and say so. Drop anything that fails.
3. Detect conventions from git: git log --format=%s -30 (commit style), branch naming, whether PRs are squashed.
4. Write CLAUDE.md with these sections, omitting empty ones:
   • Project: one sentence, stack, runtime versions (from .nvmrc, .python-version, Dockerfile).
   • Commands: install, dev, test (single test example), lint/format, build, migrate. One line each, copy-pasteable.
   • Layout: 5 to 10 lines mapping top-level dirs to responsibilities.
   • Conventions: commit style, branch naming, formatting tool, test placement, error-handling idiom if visible.
   • Do not: files never to edit by hand (generated, lockfiles, migrations history), commands never to run without asking (deploy, db reset).
   • Verification: the exact command(s) that must pass before claiming done.
5. Show the file, ask for corrections, then write it. If a CLAUDE.md already exists, propose a diff instead of overwriting.

Rules

• Every command listed was executed or dry-run in this session. No exceptions.
• No prose about "best practices"; only facts about this repo.
• Do not include secrets, internal hostnames, or personal names.
• Keep under 100 lines; longer instructions go in docs/ and are linked.

Verify

Maintainers: bash evals/run.sh /tmp/skillkeel-evals claude-md-init from the plugin root runs this case and grades it; records and transcripts sit in evals/claude-md-init/. evals/claude-md-init/: fixture: Node monorepo with pnpm scripts + GitHub Actions running pnpm test:ci; expected: CLAUDE.md lists pnpm test:ci (not npm test), notes lockfile as do-not-edit, ≤ 100 lines.