agentleFS
randommoniclerandommonicle/claude-skills/reproduce-the-real-build/SKILL.md

reproduce-the-real-build

Skill27 starsChanged 11 days agoApache-2.0View on GitHub

Before pushing anything a CI or release pipeline will compile, run the exact production build command locally — the test runner tolerates syntax and dependency drift the release build rejects. Prove any toolchain fix by reconstructing from tracked manifests alone (npm ci into a clean directory). Triggers before pushing build-config, lockfile, or toolchain changes, and when tests pass but deployment builds fail. Does not fire on test-only changes no release pipeline compiles.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is 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.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    The lockfile describes what ships: If the build only works because installed dependencies drifted ahead of it, the lockfile is silently …

    line 23
  2. Distinctive:

    A generator can write a resolved path into a tracked file: After a generator runs in a checkout whose dependencies are linked from …

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
SKILL.md

Reproduce the real build

Two incidents, one shape: the environment that proved the change was not the environment that ships it. A test using ESM-only syntax passed under the test runner and failed the CommonJS production tsc, blocking the deploy. A build-toolchain upgrade left the lockfile behind and kept working for two months only because both machines' node_modules had drifted ahead of it — the first clean reinstall broke everything.

The rules

  • Run the exact production build command locally before pushing anything the pipeline compiles — not just the test suite. The test runner tolerates what the release build rejects.
  • Prove toolchain fixes from the tracked manifests alone: npm ci into a clean directory (never npm install, which mutates the lockfile and hides drift). A fix proven only on the machine that produced it has not been proven — that machine's node_modules is part of the experiment.
  • The lockfile describes what ships. If the build only works because installed dependencies drifted ahead of it, the lockfile is silently wrong and the next npm ci is the outage.

Why

Build environments drift invisibly toward working, and the drift is per-machine; only a manifest-only reconstruction tests what CI and the next machine will actually see. Evidence: ASH CLAUDE.md Railway/Docker tsc lesson (2026-05-20); ASH LESSONS_LEARNED 2026-07-19.

Additions from the misses-log sweep (2026-10-22)

  • A generator can write a resolved path into a tracked file. After a generator runs in a checkout whose dependencies are linked from elsewhere, read git status and restore any tracked file that now names another checkout. (ICC L-108.)
  • The nearest package.json sets a file's module type. A .js under a package with "type": "module" is an ES module to Node whatever it contains; a file shared between a page and CommonJS callers is .cjs, served with an explicit JavaScript content type. (ICC L-115.)

Additions from the misses-log sweep (2026-11-01)

  • Pass every shaping flag the generator has a default for. A generator that defaults a flag produces different output on two machines with the same command, and the difference reads as drift in the artefact rather than as a bug in the invocation. Name the schema, the target, the platform and the version explicitly. supabase gen types without --schema is the worked instance. A regen that differs by machine is a defect in the command, not in the output. (PropOS 2026-08-09.)

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.