How to Write a Brief for Claude Code's First Task

“Hey, just clean up the README stuff in this repo.”

Thirty minutes after installing it, that was the first thing I handed to Claude Code. What came back was a diff that touched the README, sure, but also renamed a script in package.json. It still ran, but three files had changed in places I never meant to touch. I sat there staring at the screen, thinking: “Can I actually ship this?”

So why does a supposedly smart tool reach into files nobody asked it to touch? It is not a capability problem. I just never said a single word about how far it was allowed to go. It is like telling a new hire “make the shop look nice” and walking out the door, then coming back to find every shelf rearranged.

This article is about writing down that “how far” on a single page. I call it the first-task brief.

Key takeaways

• Your first request blows up because you say “make it nice” without ever fixing the goal, the allowed scope, the proof, and the rollback.
• A brief names nine fields: goal, reader’s situation, may read, may edit, may run, do not touch, proof, rollback, next step.
• Hand Claude Code “read, fix, run the check command” and no further. Deletion, shipping to production, and anything that costs money stay with you.
• Below are a copy-paste brief template and a short JavaScript checker that flags missing fields automatically.
• The fastest first win is picking one small task you can undo with git if it goes wrong.

Why the first task goes off the rails

Right after installing Claude Code, most people reach for a broad request. “Tidy up the repo.” “Fix the README.” I get the urge; you want to see what it can do.

But a broad request burns the first ten minutes on exploration. Claude Code reads files all over the place, fixes whatever looks related on its own initiative, and signs off with a vague “this should work.” Now you are re-reading the entire diff, and you end up muttering, “I’d have been faster doing it myself.”

The cause is not the model’s intelligence. It is that you never handed over a goal and a boundary. Even a sharp new hire, told “do whatever” on day one, either freezes or runs wild. Deciding the boundary up front makes this kind of accident almost disappear.

If the basic mechanics still feel shaky, skim the Claude Code getting started guide first, then come back. The brief will click a lot faster.

The nine fields a brief should contain

Here is what I write on one page every single time. No jargon needed: fill in one answer per line.

Field	What to write	Bad → good
Goal	What “done” looks like	”Fix the README” → “Match the README steps to package.json”
Reader’s situation	Who this is for	(blank) → “Beginner, wants one clean success”
May read	Files it may reference	(everything) → “Only README.md and package.json”
May edit	Files it may rewrite	(everything) → “README.md only”
May run	Commands it may run	(anything) → “Only npm run build”
Do not touch	Places it must never change	(unspecified) → “package-lock, deploy config, pricing”
Proof	Evidence of success	”Works for me” → “build passes / diff is README only”
Rollback	How to undo on failure	(none) → “Restore README from git”
Next step	One place the reader goes next	(three options) → “Just the free intro guide first”

The lines that matter most are “do not touch,” “proof,” and “rollback.” The moment you write those, the request stops being a wish and becomes a job you can safely delegate.

A copy-paste brief template

Here is a template you can use as-is. It is a code block so you can paste it straight into Claude Code. Swap in your own repo name and the spot you want fixed.

# First-task brief

Goal: Match the README setup steps to the contents of package.json.
Reader's situation: Beginner. Wants one clean success.
May read:
- README.md
- package.json
May edit:
- README.md only
May run:
- npm run build
Do not touch:
- package-lock.json
- Deploy config (env vars, publish settings)
- Pricing or signup links
Proof:
- npm run build passes
- git diff shows changes in README.md only
Rollback:
- If proof fails, restore README.md from git
Next step:
- Point the reader only to the free intro guide

In a concrete case, if all you are doing is matching the README steps to package.json, you read the README and package.json, edit only the README, and the evidence is npm run build. At that granularity, a failure is reversible with a single git checkout -- README.md. The first run should be this narrow. In fact, narrower is better, because it lets you judge whether it actually worked.

What to delegate to Claude Code, and what you decide

When I write a brief, this is the line I draw in my head. When the boundary is fuzzy, Claude Code crosses it “to be helpful.”

Safe to hand Claude Code	You decide (do not automate)
Read the named files	Which files it is allowed to touch
Fix only the named files	Deleting a file
Run check commands like npm run build	Shipping or deploying to production
Return a summary of the diff	Anything that incurs a charge
Report why something failed	Irreversible commands like git push --force

Hand off the left column. For the right column, set everything to “confirm with a human before running” at first. Only after an action has proven safe do you slide it over to the automatic side, one at a time. Just keeping that order cuts down the number of midnight cold sweats dramatically.

When you pass the brief over, add one line:

Do exactly one small task, staying within this brief.
If you judge something to be out of scope, do not run it; just suggest it.

First, return these five things:
1. The files you are about to read
2. The files you are about to edit
3. The check commands you will run before and after
4. A summary of the planned diff
5. How to roll back if it fails

The key is asking for the plan and the proof before the implementation. If the returned plan goes beyond the brief, you can stop it right there. Stop it before any hands move and there is nothing to clean up.

A script that flags a broken brief

Even when you think you wrote a complete brief, a field slips through. I check field presence with a machine instead of my eyes. This is copy-paste JavaScript; run it with node check-brief.mjs.

// Mechanically check that the brief has every required field
const requiredFields = [
  "Goal",
  "May read",
  "May edit",
  "May run",
  "Do not touch",
  "Proof",
  "Rollback",
  "Next step",
];

export function validateFirstTaskBrief(markdown) {
  // List the fields that are missing
  const missing = requiredFields.filter((field) => !markdown.includes(field));

  // Also check whether a proof command (here, npm run build) is present
  const hasProofCommand = markdown.includes("npm run build");

  return {
    ok: missing.length === 0,
    missing,
    readyForClaudeCode: missing.length === 0 && hasProofCommand,
  };
}

// Quick sanity check
const sample = `
Goal: Match the README to package.json
May read: README.md
May edit: README.md
May run: npm run build
Do not touch: package-lock.json
Proof: npm run build passes
Rollback: Restore README.md from git
Next step: Free intro guide
`;

const result = validateFirstTaskBrief(sample);
console.log(result);
// -> { ok: true, missing: [], readyForClaudeCode: true }

Run the brief through this before you hand it over, and the forgotten “do not touch” and “rollback” lines stop happening. Rely on your eyes alone and you will drop a field on a busy day. Let the machine handle what the machine can see; it is easier.

Three situations where this pays off

1. Fixing a README or a how-to doc “Bring the docs up to date” has infinite scope. “Match only the setup section of the README to the script names in package.json” keeps the diff to a single file and lets you confirm it with npm run build. This is the best possible first task.

2. A first-pass review of a pull request Not “look at this PR,” but “read only the files under src/ in this change and point out where tests might break. Do not fix the code, just flag it.” Delegate the reading; keep the fixing decision with the human. That prevents the “it quietly fixed something and introduced a new bug” accident.

3. Swapping out a CTA link Even swapping a single button under a popular article, “find the related component and fix it” is too broad. Decide up front in the brief which files it may touch, which published URL you will check, and which link gets swapped. Your after-the-fact check turns from “seems roughly fine” into “with this evidence, I can ship it.”

Three mistakes I made myself

Honestly: before I started using briefs, I kept making the same mistakes.

First, not writing “do not touch.” I only wanted the README fixed, but Claude Code helpfully tidied up package.json too, and build stopped passing. Adding three lines, Do not touch: package-lock.json, deploy config, made it never happen again.

Second, settling for “works for me” as proof. Since I had not defined what “works” meant, I chased the whole diff by eye every time. Once I made it a concrete command, Proof: npm run build passes / diff is README only, the check started taking ten seconds.

Third, listing three next steps. When I pasted a free PDF, a course, and a consultation all under one article, reader response went fuzzy. Narrowing to one option matched to the reader’s situation got that one option actually clicked. What belongs in each project is worth recording as a rule in your CLAUDE.md best practices so it never drifts.

FAQ

Q. Isn’t writing all nine fields every time a hassle? Only the first few times. Make one template, save it as first-task-brief.md, and from then on you just swap three or four lines. The time spent writing it is far shorter than the time spent re-reading a runaway diff.

Q. Do I need a brief even for trivial work? For a one-file typo fix, a spoken request is plenty. A brief earns its keep when the work might touch multiple files, or when production, billing, or deletion is anywhere nearby. When in doubt, write one; you lose nothing.

Q. Should I write the keys in English (Goal, May edit, and so on)? If your team lines up logs side by side to compare, consistent English keys help. Working solo, your own language is fine. Claude Code understands either. What matters is not the language but that no field is missing.

Q. Can people who do not code use this? Yes. For writing articles or organizing materials, the “may read / may edit / do not touch” thinking is identical. The on-ramp for non-coders is in Claude Code for non-engineers.

Q. What if Claude Code ignores the brief and touches something out of scope? First, ask it to “return the plan and proof before doing anything” and stop it before any hands move. If it still crosses the line, your “do not touch” is probably not specific enough. Spelling out folder and file names by name fixes it.

What happened when I actually tried it

The clearest test was the small job of matching the README to package.json. With May edit: README.md only written down up front, Claude Code’s drift toward package-lock and config files got stopped at the plan stage, before it ran anything. The big win was that the chore of re-reading the diff simply vanished.

Putting two items in Proof, npm run build and git diff, mattered too. The after-work judgment shifted from “feels okay” to a flat statement: “build is green, the diff is README only, so I can ship it.” Conversely, the run where I left Next step blank left even me wondering “wait, what do I point people to next,” and the link at the end of the article went fuzzy.

What it all came down to: handing Claude Code lots of freedom is not the value. Cut the first task small, and keep success, failure, and the next action visible to your own eyes. That is the fastest path. The hassle of writing one boundary page is nothing next to the hassle of re-reading a runaway diff later.

If you want to tighten the outer machinery, check the permission behavior in Anthropic’s official Claude Code documentation; it makes the split of duties between the brief and the settings clear. If you want to roll Claude Code into your company’s workflow and set the operating rules at the same time, our training and consultation can build brief templates fitted to your actual work together.