Files

check / check (push) Successful in 7s

Details

Bust the Docker check-layer cache with a per-invocation CHECK_EPOCH (closes #26 )

script/cibuild was a plain `docker build .`, and the Dockerfile does
`COPY . .` followed by `RUN make check`. Docker invalidates a COPY layer
only when the copied content changes, so on an unchanged tree the check
layer was served from cache, the suite never ran, and the build still
exited 0. Measured here: run 1 took 18.5s and ran the suite; run 2 on a
byte-identical tree took 0.286s with `RUN make check` CACHED.

script/cibuild and script/docker now assign a per-invocation nonce on its
own line and pass it as --build-arg CHECK_EPOCH. The Dockerfile declares
ARG CHECK_EPOCH, guards it with `[ -n "$CHECK_EPOCH" ] || exit 1`, and
expands it into the check command. Post-fix, two consecutive runs both
execute make check (17.4s / 8.1s) with `RUN script/bootstrap` still
CACHED, so dependency layers are untouched and the build ceiling is not
at risk.

The guard is what makes a bare `docker build .` — the command
REPO_POLICIES named verbatim — fail closed rather than reuse the empty
and therefore stable cache key; verified failing in 0.455s. Holding the
epoch constant restores the false green (run 2 fully CACHED), which pins
the varying value as the operative mechanism rather than a coincidence.

Because the guard references $CHECK_EPOCH it is itself value-keyed:
BuildKit renders the epoch into that layer's description and re-runs the
layer when the value changes. Each stage therefore has two independent
invalidation points, the guard and the expansion, and the guard always
precedes the check RUN. Both are kept and the prose now records this;
the expansion remains defence in depth and is what puts the epoch in the
build log.

The false guarantee was org-canonical text in more than one document, so
it is corrected everywhere it appeared rather than only where the issue
first found it. REPO_POLICIES.md carried it in two places, and its Go
multistage template had check steps in two stages; ARG is stage-scoped,
so both stages get the treatment or the fleet inherits the half-fixed
shape. CODE_STYLEGUIDE_GO.md restated the guarantee for the bare command
this change makes fail closed. NEW_REPO_CHECKLIST.md specified the
pre-fix script/cibuild verbatim, so every new repo would have been born
with the false green, and EXISTING_REPO_CHECKLIST.md ended on a
`docker build` acceptance item that the guard makes unsatisfiable by
design — an agent working that checklist would have been led to delete
the guard to tick the last box. Both checklists' Dockerfile criteria were
also satisfiable by a Dockerfile whose check layers are still frozen, and
now require the ARG and guard in every check-running stage.

REPO_POLICIES.md's own Dockerfile criterion carried that same incomplete
form; it is tightened by cross-reference to the CHECK_EPOCH rule rather
than by duplicating the canonical block. The Go template's Key points
gain a caveat that the cache-bust turns the `COPY --from=lint` no-op into
a content-cache hit, so a repo using a file-dependency trick for stage
ordering must re-prove that ordering on a warm cache after adopting it.
That was re-proved in another repo in the org which uses the trick with a
marker file, where the ordering held; the caveat states explicitly that
it was not verified here, this repo being single-stage with no lint stage
to order against.

2026-08-09 15:15:03 +00:00

7.7 KiB

Raw Blame History

prompts

prompts is an MIT-licensed collection of LLM prompts by @sneak, including development policy prompts and other useful prompts for working with large language models.

Quick Start

Existing Repo

Run from within the repo you want to bring up to standards. Clone the prompts repo once, then run both commands in order.

export TD="$(mktemp -d)"
git clone --depth 1 https://git.eeqj.de/sneak/prompts.git "$TD"

Repository structure and policies:

claude "Read $TD/prompts/REPO_POLICIES.md and
$TD/prompts/EXISTING_REPO_CHECKLIST.md, then bring this repo up to those
standards. Your scope is repo scaffolding and policy compliance:
Makefile, Dockerfile, .dockerignore, .gitignore, .editorconfig, CI
workflow, README sections, LICENSE, REPO_POLICIES.md, and any
language-specific config files (.golangci.yml, .prettierrc, etc.).
You must also run the formatter (make fmt) and fix any linter errors
(make lint) so that make check passes — this will touch source code,
but do not restructure, refactor, or rewrite any application logic.
Follow the policies yourself: work on a feature branch, never git add -A,
and make each logical change a separate commit (e.g. one commit for
formatting, one for linter fixes, one for README updates, one for each
new repo file added, etc.)."

Code style and conventions:

claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
language-specific styleguides in $TD/prompts/ apply to this repo
(CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
GO_HTTP_SERVER_CONVENTIONS.md). Then review the application code in this
repo and bring it into compliance with those coding standards. Your scope
is application code structure and style: naming, patterns, error
handling, project layout, and conventions described in the styleguides.
Do not modify repo scaffolding (Makefile, Dockerfile, CI workflow,
.gitignore, .editorconfig, etc.) — only application code. Work on a
feature branch, never git add -A, and make each logical change a
separate commit."

New Repo

Run from inside the directory where you want to create a new repo. Clone the prompts repo once, then run both commands in order.

export TD="$(mktemp -d)"
git clone --depth 1 https://git.eeqj.de/sneak/prompts.git "$TD"

Repository scaffolding:

claude "Read $TD/prompts/REPO_POLICIES.md and
$TD/prompts/NEW_REPO_CHECKLIST.md, then set up this new repo according
to those standards. Your scope is repo structure and required files:
README.md, LICENSE, REPO_POLICIES.md, Makefile, Dockerfile, .dockerignore,
.gitignore, .editorconfig, CI workflow, and language-specific config.
Run the formatter (make fmt) and fix any linter errors (make lint) so
that make check passes — this will touch source code, but do not
restructure, refactor, or rewrite any application logic. Follow the
policies yourself: work on a feature branch, never git add -A, and make
each logical change a separate commit (e.g. one commit for formatting,
one for linter fixes, one for README, one for each new repo file, etc.)."

Code style and conventions:

claude "Read $TD/prompts/CODE_STYLEGUIDE.md and whichever
language-specific styleguides in $TD/prompts/ apply to this repo
(CODE_STYLEGUIDE_GO.md, CODE_STYLEGUIDE_JS.md, CODE_STYLEGUIDE_PYTHON.md,
GO_HTTP_SERVER_CONVENTIONS.md). Then review the application code in this
repo and bring it into compliance with those coding standards. Your scope
is application code structure and style: naming, patterns, error
handling, project layout, and conventions described in the styleguides.
Do not modify repo scaffolding (Makefile, Dockerfile, CI workflow,
.gitignore, .editorconfig, etc.) — only application code. Work on a
feature branch, never git add -A, and make each logical change a
separate commit."

Getting Started

git clone https://git.eeqj.de/sneak/prompts.git
cd prompts

Prompts are stored as Markdown files in prompts/. Copy or reference them as needed in your projects.

Entrypoints

This repository adheres to the Scripts to Rule Them All standard: normalized scripts in script/ are the entrypoints for the development workflow, and the Makefile targets are thin shims that call them. The scripts are POSIX sh (not bash) so they run in minimal containers such as alpine. We provide:

script/bootstrap — install all dependencies (yarn install)
script/setup — set up the repo for development after a fresh clone: runs script/bootstrap, then script/install-precommit
script/projectname — output the project name (our own extension); used by script/docker for the image tag
script/test — run the test suite (no tests defined here)
script/lint — lint the markdown files with prettier
script/fmt — format all markdown files with prettier (writes)
script/fmt-check — check formatting (read-only)
script/check — run all checks: test, lint, fmt-check (our own extension)
script/docker — build the Docker image, tagged via script/projectname (byte-identical across repos); passes the same CHECK_EPOCH nonce as script/cibuild
script/cibuild — cd to the repo root, assign epoch="$(date +%s%N)$$", then docker build --build-arg CHECK_EPOCH="$epoch" . (what CI runs; the image build runs script/check, and the per-invocation CHECK_EPOCH nonce is what stops Docker serving that check from cache on an unchanged tree — a bare docker build . fails closed on purpose)
script/precommit — run by the git pre-commit hook (our own extension); calls script/check
script/install-precommit — installs the git pre-commit hook (our own extension); make hooks shims to it

make hooks installs the pre-commit hook that runs script/precommit.

Rationale

LLM prompts, especially development policies, benefit from version control and a single authoritative source. This repo provides a central place to maintain, share, and evolve prompts across projects.

Design

The repository is a collection of Markdown files organized in the prompts/ subdirectory. Each file contains one or more related prompts or policy documents. There is no build step or runtime component; the prompts are consumed by copying them into other projects or referencing them directly.

Template Repos

These template repositories implement the policies defined in this repo and serve as starting points for new projects. They must be kept in sync when policies change.

template-app-go — Go HTTP server template (Uber fx, chi, SQLite, session auth, Prometheus metrics)
template-app-js — JavaScript SPA template (Vite, Tailwind CSS v4, nginx Docker deployment)
template-app-python — Python web application template (FastAPI, uvicorn, pytest, black, ruff)

When updating policies in this repo, also update the template repos to match (Makefile targets, Dockerfile conventions, CI workflows, required files, etc.).

TODO

Add more prompt templates for common development tasks

License

MIT. See LICENSE.

Author

@sneak

7.7 KiB Raw Blame History