- Book: AI That Answers
- The series: AI in TypeScript — 5 books, from your first LLM call to agents in production — all five here
- My project: Hermes IDE | GitHub — an IDE for developers who ship with Claude Code and other AI coding tools
- Me: xgabriel.com | GitHub
Open the Claude Code best practices page and look at the table under "Provide specific context in your prompts". The last row has a "Before" column. The prompt in it is "fix the login bug".
The "After" is longer: "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it". It names the symptom, where to look and what fixed looks like.
You have typed the "Before" version. Everyone has. The agent picks its own scope and decides on its own when it is finished. You get back a diff you now have to reverse-engineer, and whether it is mergeable depends on guesses you never saw it make.
The fix is a short brief with six fields. Each one closes a gap the agent would otherwise fill by guessing.
Three vendors, one checklist
The vendors who build these agents say the same thing in their own docs.
Anthropic's guide says to "reference specific files, mention constraints, and point to example patterns." It also describes the most useful specs as ones that "name the files and interfaces involved, state what is out of scope, and end with an end-to-end verification step" (source).
OpenAI's Codex prompting guide says a useful prompt "names the behavior you want, points to the relevant code or reproduction steps, preserves important constraints, and says how to verify the change."
GitHub's guidance for the Copilot coding agent lists what an ideal task includes: a clear description of the problem, "complete acceptance criteria on what a good solution looks like", and "directions about which files need to be changed."
Put those side by side and you get the six fields. The order matters less than having all of them.
One line leaves six decisions to the agent. Six fields hand them back to you.
The six fields, bad vs good
The running example is the login bug from Anthropic's table, in a TypeScript repo.
1. Goal
Bad: Fix the login bug.
Good: Users whose session timed out get a 401 when they log in again. After the fix, a timed-out user can log in on the first try.
Why it changes behaviour: the agent needs a stopping point it can recognise. "Fix the bug" has none. A symptom plus what fixed looks like gives it one, which is exactly the "Describe the symptom" row in Anthropic's table.
2. Files in scope
Bad: nothing. The agent greps the repo and reads whatever matches "login".
Good: Start in src/auth/session.ts and src/auth/refresh.ts. Put the new test in tests/auth/.
Why: every file the agent reads lands in its context window, and Anthropic's docs say performance "degrades as it fills" (source). Pointing at the right files saves that budget for the fix. It also tells the agent where you expect the diff to be, so a change somewhere else stands out to both of you.
3. Out of scope
Bad: nothing, or Keep it clean.
Good: Don't touch the login UI, the public API shape, package.json or the lockfile. Don't reformat files you aren't changing. If the fix seems to need any of these, stop and tell me.
Why: agents fix things they notice on the way. A renamed helper or a tidied import block turns a two-file fix into a review of everything around it. Codex's own bug-fix example carries the line "Do not change the API shape" (source). The "stop and tell me" line gives the agent a legal move other than quietly widening the change.
4. Constraints
Bad: Write good code.
Good: Keep the fix minimal. Write a failing test that reproduces the timeout first, then fix it. No new dependencies. Follow the refresh pattern already in src/auth/refresh.ts.
Why: constraints decide how the agent gets there. "Keep the fix minimal and add a regression test if feasible" is a line from OpenAI's example prompt, and Anthropic's examples say things like "avoid mocks" and "build from scratch without libraries other than the ones already used in the codebase." "Write good code" constrains nothing, because the agent already believes it does that.
5. The done-check
Bad: Make sure it works.
Good: Done means npm test -- tests/auth passes and npm run lint exits 0. Run both before you tell me you are done.
Why: in Anthropic's words, "Claude stops when the work looks done. Without a check it can run, 'looks done' is the only signal available, and you become the verification loop" (source). A command with a pass or fail result lets the agent run, read and retry on its own. If you only add one field, add this one.
6. What to report back
Bad: nothing. You get a cheerful paragraph saying the bug is fixed.
Good: When done, reply with: the root cause in one sentence, the files you changed, the commands you ran with their results, and anything you noticed but did not change.
Why: the same Anthropic guide says to have the agent "show evidence rather than asserting success", because "reviewing evidence is faster than re-running the verification yourself." OpenAI's version is "Report the commands and results." Problems the agent spotted outside its scope come back as a list you can triage, and the diff stays the size you asked for.
The whole brief, filled in
Here is the template. Keep the headings; the agent reads them as structure.
GOAL
<what is wrong, and what fixed looks like>
IN SCOPE
<files or folders to read and change>
OUT OF SCOPE
<what not to touch; stop and ask if needed>
CONSTRAINTS
<patterns to follow, deps, test-first, size>
DONE WHEN
<commands that must pass before you say done>
REPORT BACK
<what your final message must contain>
And the login bug, written out:
GOAL
Users whose session timed out get a 401 when
they log in again. After the fix, a timed-out
user logs in on the first try.
IN SCOPE
src/auth/session.ts, src/auth/refresh.ts,
new test in tests/auth/.
OUT OF SCOPE
Login UI, public API shape, package.json,
lockfile. No reformatting of other files.
If the fix needs any of these, stop and ask.
CONSTRAINTS
Minimal fix. Failing test first, then the fix.
No new dependencies. Follow the pattern in
src/auth/refresh.ts.
DONE WHEN
npm test -- tests/auth passes.
npm run lint exits 0.
REPORT BACK
Root cause in one sentence. Files changed.
Commands run and their results. Anything you
noticed but did not change.
Most of what is specific to the login bug sits in the goal and the paths. The out-of-scope list, the constraints style and the report-back lines carry over to the next task almost unchanged.
Writing it once in Hermes IDE
I build Hermes IDE, so weigh this section with that in mind. It is a free, source-available (BSL 1.1) desktop app for macOS, Windows and Linux that runs Claude Code, Codex and other CLI agents side by side, each in its own terminal. It is not affiliated with Anthropic, OpenAI or Nous Research.
Three parts of it line up with the brief.
The brief is the first prompt. Press ⌘N (Ctrl+Shift+N on Windows and Linux) and paste the brief in as the task. Each task starts on its own hermes/<name> branch in its own worktree, "with the task as the agent's first prompt" (README). The six fields go in as written, and the New task sheet previews the command under "Hermes will run" before you start it. There is no second message where you remember the constraints you forgot.
The ⌘N New task sheet (shown with a different task): Claude Code, a new hermes/ worktree, Accept edits, and the "Hermes will run" preview of the command.
Save the brief and reuse it. Prompts opens with ⌘J (Ctrl+Shift+M on Windows and Linux). It holds your own prompts next to the free Hodios library: pick one, fill in the blanks, and put it in the session or a new task (README). A prompts file can also be imported (v2.2.7 release notes). So the template above, with your usual out-of-scope list and report-back lines already in it, stays in Prompts. Next time, open it with ⌘J, rewrite only the goal and the files, and send it to a new task.
The done-check can become a Hermes check. In Hermes, your own checks "can decide when a task is done" (README), so the commands in DONE WHEN can do the deciding instead of sitting in the prompt as a request. How to set checks per repository is in the worktree recipe docs. Keep the DONE WHEN field in the brief anyway: it tells the agent which commands matter from the first turn.
Write the brief once, fill in the two fields that change, send it to whichever agent gets the task.
What the brief does not do
A brief is a request. Anthropic's docs draw the line between instructions in CLAUDE.md, which are "advisory", and hooks, which are "deterministic and guarantee the action happens" (source). The same holds for your OUT OF SCOPE field. Nothing stops an agent from crossing it, so you check.
Two cheap checks once the agent reports back:
# which files did the branch touch?
git diff --stat main...HEAD
# did the lockfile change?
git diff --name-only main...HEAD -- package-lock.json
Run the agent on its own branch or worktree so a scope miss stays on that branch. For the done-check, Claude Code's own Stop hook can block a turn from ending until your script passes, with or without Hermes.
Two more limits. First, lines that are the same in every brief (your test runner, your lint command, your style rules) belong in CLAUDE.md (Claude Code) or AGENTS.md (Codex), which your agent reads every session. The brief is for what changes per task. Second, not every task needs six fields. Anthropic's guide says that if you "could describe the diff in one sentence", you can skip the plan. A typo fix is one sentence. A login bug that crosses two files and a test is not.
If this was useful
The six fields are prompting applied to a coding agent: a clear goal, tight limits and a fixed shape for the answer. If you want to use the same habits when you call a model from your own TypeScript code, AI That Answers walks through a first LLM app in TypeScript: writing the prompts, getting structured output back instead of a cheerful paragraph, and keeping an eye on token cost. If you want the brief saved in Prompts (⌘J) and your own checks deciding when the task is done, Hermes IDE is a free download, and the code is on GitHub.
It is book 1 of AI in TypeScript, five books that go from your first LLM call to agents in production: the whole series is here.
Top comments (0)