Railpack Agent Rules

A BuildKit-based builder that turns application source into runnable container images.

Overview

Railpack's CLAUDE.md follows a project from language detection through build planning and container execution. It uses mise tasks, explains what integration fixtures prove, and names generated files and unsafe cleanup commands to leave alone.

Verification by change type Behavioral framing Hard prohibitions Generated file guards

Documents

├──  · imports images/debian/runtime/Dockerfile, mise.toml, docs/src/content/docs/guides/developing-locally.md
├── 
├── docs
│   └── src
│       └── content
│           └── docs
│               └── guides
│                   └── 
├── examples
│   └── tanstack-latest
│       └── 
├── images
│   └── debian
│       └── runtime
│           └── 
└──

Techniques in this file

01 / Verification by change type

Distinguish a successful build from a working application

The integration-test section limits build-only fixtures because they skip output and other assertions. It directs server projects toward HTTP checks, making the required evidence match the application behavior.

72* In `test.json` we should avoid using `justBuild` for all but the most simple projects. `justBuild` does not test `expectedOutput` or any other assertions.

02 / Behavioral framing

Choose defaults that users can override

Mise settings belong in a generated TOML file instead of environment variables. The guide gives user override behavior as the reason for choosing that configuration channel.

30- When configuring Mise settings, prefer TOML settings in the generated31  `mise.toml` (via `AddMiseSetting`) over environment variables, so users can32  override defaults with their own `mise.toml`.

03 / Hard prohibitions

Protect shared container state from cleanup

The guide forbids broad Docker pruning even when the cache behaves unexpectedly. A commonly suggested cleanup command becomes an explicit boundary.

42- Do not worry about docker cache, etc. Never run `docker system prune` or other similar commands.

04 / Generated file guards

Identify generated fixture metadata

The test description separates hand-authored test and service configuration from generated size data. It explicitly forbids creating or editing that generated record manually.

66* The `size.json` is auto-generated and should never be manually created or updated.

Ideas for your repo

Define runtime assertions for integration fixtures.
Put defaults in a configuration layer users can override.
Name destructive cleanup commands that are outside the workflow.
Label generated test metadata beside editable fixture files.