Every task you hand to Claude Code starts from zero. You type the same preamble again — "this repo
uses pytest, keep the public API stable, don't touch the migrations folder" — then the actual
request, then you spend three turns correcting the part the preamble forgot.
The fix is boring and it works: keep the preamble. Write it once, per recurring task, and paste it
every time. The thing people usually get wrong is the shape of that text. A good prompt has two
blocks, and the first one does most of the work.
Two blocks, not one
Block 1 — "context to provide": the facts the model cannot guess from the files it can see.
Language and version, the test command, the style rules, the invariant that must not change, the
directories that are out of scope, and the definition of "done". This is where your knowledge of
the codebase goes. It is boring, specific, and reusable.
Block 2 — the body: one task, written once, so it can be pasted unchanged. Not a conversation
starter, not a question — a specification.
The order matters. Context first, task second: the model reads the constraints as constraints, not
as a preamble it has to reconcile with the request.
Worked example: a rename that must not break the public API
Context to provide:
- Python 3.11, pytest, ruff (line length 100).
- Public API of `src/pkg/__init__.py` must not change: the module exports are a contract.
- Only `src/` and `tests/` are in scope. Do not touch `migrations/` or `docs/`.
- Done = `pytest -q` green, no new public export, and the diff contains only the rename.
Body:
Rename the internal helper `loadConfig` to `readConfig` across src/ and tests/.
Keep the old name as a deprecated alias in __init__.py so external imports do not break.
Show me the list of call sites you changed, then run pytest -q and paste the summary.
Two things make this prompt reusable. The context block changes when the repo changes, not when the
task changes. The body is fixed. So the only thing you rewrite between the 20th refactor and the
21st is the task — and often you don't even rewrite that.
Worked example: the flaky test
Flaky tests are a context problem, not a magic problem. The model needs to know what "flaky" means
here: the seed, the marker, the retry setting, the timing assumption.
Context to provide:
- Test runner: pytest-xdist, tests run in parallel on CI.
- The failing test is `tests/test_sync.py::test_retry_backoff`; it fails ~1 in 5 on CI and never
locally. Suspect: it asserts a wall-clock delay, and CI runners are slow.
- Do not disable the test, do not add sleep(), do not mark it xfail.
- Done = the test is deterministic without weakening the assertion.
Body:
Read tests/test_sync.py and find what makes this test non-deterministic.
Propose a fix that removes the timing dependency, keep the assertion as strict as it is now,
and explain in two sentences why the original passed locally and failed on CI.
The "do not disable / do not add sleep()" line is the part people forget, and it is the part that
prevents the most common failure: a model that solves a flaky test by deleting the test.
Why the context block is the whole trick
The same task asked with and without the context block produces different work, not just different
wording. Without it, the model has to guess the test command, the scope, the style, and the
definition of done — and each guess is a place where you will spend a correction turn. With it, the
first answer is usually close to final, which is where the time saving actually comes from.
This is also why the context block should not be written as prose. Short lines, one fact per line.
A fact you can read at a glance in six months is worth more than a paragraph you wrote once.
What a reusable set covers
Eighteen recurring workflows come up week after week in real repositories, and each one is worth
its own prompt file rather than a paragraph of instructions you keep re-deriving:
refactor, code review, debug flaky tests, write tests, generate docs, database migration, API
design, postmortem, feature flag, commit message, PR description, dependency upgrade, performance
investigation, CLI spec, README, RFC, dependency audit, changelog.
Each prompt in the set has the same two blocks: a "context to provide" section listing the facts to
paste in, and a single ready-to-paste body. They are MIT licensed, so you can edit them until they
match your repo's conventions — which is the only way they stay useful.
Honest limits
A prompt file does not know your codebase. The context block is where that knowledge goes, and if
your repo's conventions change every quarter, the context block has to change with them. Treat a
prompt set as a starting contract that you edit, not as a magic incantation that works forever.
They also do not replace reading the code. They remove the repeated typing, not the repeated
thinking. The prompts that pay off most are the ones where the "done" condition was written down
somewhere but never applied to the request.
The set
Claude Code Prompt Pack — 18 prod-ready prompts
— 18 prompt files, each with a "context to provide" section and one ready-to-paste body, MIT
licensed. One-time purchase, and the files are yours to edit.
Disclosure: this article was written with the help of AI and reviewed before publication.
Top comments (0)