Make your agent talk like a senior engineer.
Every instruction you give Claude Code lands in one of two places. The user prompt is the task at hand — read once, then gone. The system prompt is standing instruction that shapes every task, every response, every session. Most engineers pour everything into the first and never touch the second, which is exactly backwards: the system prompt is where one sentence gets multiplied across all of your work.
Verbosity is a cost center.
Frontier models ship with a default communication style, and it is rarely the one you want. They recap work you watched them do, pad answers with stock phrases, flag problems nobody asked about, and restate the same point three ways. Each of those habits costs you twice: once in output tokens — the expensive kind, the ones that dominate an agent bill — and once in your attention, because you are the one who has to read it all.
You can fight this one user prompt at a time (“be concise”, again, forever), or you can fix it once at the level where it applies to everything. A well-built system prompt turns the model you have into the collaborator you want: concise, direct, scoped to the request — and it keeps working when the underlying model changes, because you tuned the communication contract, not the model.
One flag, one file.
Claude Code takes a system-prompt supplement at launch. Keep your rules in a markdown file and append it — appending adds your instructions on top of the built-in system prompt, so the agent keeps its tool-use ability and gains your communication standards:
claude --append-system-prompt "$(cat agent-style.md)"Write the file by hand. This is worth saying explicitly in the dictation era: anything that gets multiplied over every future run of an autonomous tool deserves deliberate, word-by-word attention. Slow down here so you can go fast everywhere else. Then check the file into your repo — more on why at the end.
A complete agent-style.md with all six sections below, ready to edit and append.
Six sections that earn their place in the file.
Add them one at a time and test between each — the failure mode is pasting in a wall of rules you can't attribute results to.
State the working relationship
Open the file by telling the agent what kind of collaboration this is — and why. Not a role-play persona, just the standard you'd set with a new teammate: we keep communication clear, concise and actionable, because we're here to solve problems, not to have a nice conversation. Everything below this line is read in that light.
# Purpose
We maintain a direct, concise, actionable working
relationship. Every response should move the work
forward. Why: we ship for a team, a business and
its customers — our communication reflects that.Positive and negative patterns
Two lists: replicate these, avoid those. The positive list is what a good response looks like — plain language, each fact stated once, detail matched to the size of the task, wrong assumptions challenged directly. The negative list is where you ban the model's verbal tics by name. Every model has a set of stock phrases it leans on; list the ones that grate on you and they largely disappear.
## Positive patterns
- Put the most important information last —
it's the first thing I see.
- State each fact once. Never repeat.
- If one paragraph carries the idea, don't
write two.
- Challenge incorrect assumptions and say why.
## Negative patterns
- Avoid these phrases: "load-bearing",
"worth stating plainly", "the honest truth".
- No flattery, praise or agreement without
reason. No decorative headings or emoji.
- Don't chain em dashes.Reference points
Give the agent a shared shorthand. When a response contains three or more decisions, risks, findings or actions, have it number them with short codes — D1, R3, F2 — and keep those codes stable for the rest of the session. Now a follow-up prompt is just “expand on R3” instead of a paragraph re-describing which risk you meant. You've built a compressed language between you and the agent.
## Reference points
When presenting 3+ findings, decisions, risks
or actions, assign short codes:
D1, D2 ... for decisions
R1, R2 ... for risks
F1, F2 ... for findings
Keep codes stable across the conversation.
Skip codes for short, simple answers.Hard operational boundaries
Frontier models are trained to be maximally helpful, which in practice means they widen the job: unrequested refactors, drive-by cleanup, documentation nobody asked for, and confident completion claims with no evidence behind them. Boundaries fix scope creep at the source — one section that says exactly where the work ends.
## Operational boundaries
- Deliver only what was requested, at the
requested scope.
- No widening into cleanup, refactoring or
docs unless asked.
- Never claim completion without evidence
(test output, a diff, a running command).
- Never add a co-author to a commit message.Aliases
Define micro-commands the agent expands on sight. Type STR after a long response and it simplifies, compresses and restates it. FOCUS boils an answer down to the one thing that matters. These are the highest-frequency follow-ups you type every day, reduced to three keystrokes — and because they live in the system prompt, they work in every session without any setup.
## Aliases
When you see these exact tokens alone in a
prompt, act on their expansion:
STR = simplify, compress and restate
your previous response
ELI = re-explain in plain language
FOCUS = what single thing matters most
here? Answer only that.
REF = rewrite your previous response
using reference pointsTeach with examples
The oldest prompt-engineering technique there is, and still the strongest: show, don't describe. Pair a user request with the response you want and the response you don't. Better yet, harvest them — when any model gives you an answer whose shape you like, trim it, fix its formatting, and paste it in as a do-this example. You're distilling the communication style you want directly into context.
## Examples
User: "Is legacy.json still referenced?"
Do: "No. The only match is the file itself —
no imports, no docs links. Safe to remove."
Don't: "Great question! I'll thoroughly
investigate the repository to determine
whether this file is referenced anywhere..."Test it like an engineer.
Don't take the file's word for it. Run two Claude Code instances side by side on the same task — one stock, one with your file appended — and compare. You're looking for three things: shorter responses (watch the output-token count and response time), the banned phrases actually gone, and the structure you asked for (reference codes, importance-last ordering) actually present.
These are non-deterministic systems, so judge over several runs, not one. And when a response is still too long despite the rules, that's what the aliases are for — a STR costs three keystrokes and gives you the compressed version on demand.
A personal trick becomes infrastructure when you commit it.
One engineer with a tuned system prompt has a nicer terminal. A team with a shared, versioned one has agents that all communicate the same way — consistent review, compounding improvements, and an output-token bill that drops across every seat at once. Rolling out standards like this across an engineering org is precisely the work we do.
- One agent-style file, versioned in the repo
- Communication rules every agent follows
- Shared aliases the whole team knows
- Operational boundaries that stop scope creep
- A banned-phrase list updated per model release