Claude Code First Task Runbook: Safe Prompts, Checks, and Pre-Commit Review

The first task decides whether Claude Code feels safe

Right after installing Claude Code, it is tempting to ask for a whole feature, a full refactor, or “fix everything in this repo.” That is where many first sessions go wrong. The problem is usually not that Claude Code cannot help. The problem is that scope, verification, permissions, and project context have not been agreed yet.

This runbook is for the first practical task in a real repository. A runbook is a repeatable operating checklist. Here, the first task is not “build the feature.” It is a small workflow: ask well, confirm the plan, make one bounded change, review the diff, and leave a handoff note.

If the basics are still new, start with the Claude Code getting started guide. When you are ready to capture project rules, pair this with 7 CLAUDE.md templates for Claude Code. For official references, use Claude Code overview, memory and CLAUDE.md, permission modes, common workflows, and the CLI reference.

flowchart LR
  A["Read the repository"] --> B["List 3 safe options"]
  B --> C["Choose 1 task"]
  C --> D["Review the plan first"]
  D --> E["Make the smallest diff"]
  E --> F["Verify tests and diff"]
  F --> G["Write a handoff note"]

What makes a good first task

The first task is not mainly about output size. It is about whether you can keep trusting the workflow. The best first tasks have five traits.

Trait	Plain meaning	Good example
Local	No production, customer data, or outbound side effects	Check README commands or add one test assertion
Bounded	The files and stopping point are visible	One component, one test, one document
Verifiable	A command, page, or diff proves success	npm.cmd run test, git diff --check
Reversible	A bad result can be discarded quickly	Normal source files, not generated exports
Explainable	A human can follow why the change exists	Reason, risk, and remaining uncertainty are written down

Requests like “redo authentication,” “modernize the whole codebase,” or “fix CI and deploy it” are poor first tasks. They combine missing context, permission prompts, weak tests, and unreadable diffs in one session.

Safe first-task menu

For team onboarding, pick from this menu before inventing a task.

Task	Why it helps	Success condition
Map the repository	Tests understanding before edits	Entry points, commands, and risky directories are identified
Summarize one failing test	Shows debugging granularity	Failure point, hypothesis, and smallest next move are clear
Fix one stale README command	Tries a low-risk real edit	Command runs and diff stays tiny
Add one assertion to an existing test	Tests intent and test judgement	The assertion protects a clear behavior
Change one UI copy string	Checks search and minimal edits	Only the target component changes
Fix one lint warning	Measures local change discipline	One warning disappears without behavior change
Create a minimal CLAUDE.md	Improves future sessions	Commands, boundaries, and review rules are concise

The key is “small but real.” The task should connect to onboarding, bug diagnosis, documentation, tests, or review quality.

Copy-paste prompt templates

Start by asking Claude Code to read and propose, not edit.

Read this repository and do not edit yet.

Return:
1. main entry points
2. common build/test/lint commands
3. risky directories or generated files
4. 3 safe first-task options for a 30-minute session
5. how to verify and roll back each option

After it proposes options, choose one and require a plan.

Proceed with option 2 only. Do not edit yet.
First write the files you would touch, reason for the change, expected diff,
verification command, and risks. If the scope is expanding, propose a smaller option.

Only then allow the edit.

Follow the approved plan and make the smallest diff.
Do not touch files outside the request.
After editing, summarize verification commands run, checks that failed or were skipped,
and remaining risks.

Use a separate prompt for pre-commit review.

Run a pre-commit review.

1. Read git diff and find changes outside the request
2. Find missing tests or weak verification
3. Check security, data loss, and config risks
4. Find files that should not be committed
5. Identify decisions still requiring a human

End with exactly one verdict: "commit ready", "fix first", or "stop".

The 30-minute flow

Spend the first five minutes freezing the current state before handing work to Claude Code. On Windows PowerShell:

Get-Location
git status --short
git branch --show-current
rg --files | Select-Object -First 40

On macOS or Linux:

pwd
git status --short
git branch --show-current
rg --files | head -n 40

If the worktree is dirty, tell Claude Code which changes are human-owned and must not be touched. Otherwise the final diff becomes impossible to judge.

Use the next ten minutes to choose one task. Good first choices are a stale README command, one test assertion, or one failing test summary. Avoid new features for the first session.

Around minute twenty, prioritize proof over more edits. One correct, explained change is more valuable than three unverified changes.

git diff --stat
git diff --check
git diff
git status --short

Use the last five minutes for a handoff note. A handoff note is a short note for the next person or the next Claude Code session. It matters because long conversations can lose boundaries, and future sessions need a clean starting point.

Four concrete use cases

Use case 1: New developer onboarding

Do not hand a new developer a large issue on day one. Ask Claude Code to produce a repo map, key commands, dangerous directories, and the first files to read.

Prompt: “Create an onboarding note for a new developer. Separate facts from guesses. Include command output when you can.” Success means the note adds practical context beyond the README, such as generated files, local-only settings, or CI versus local differences.

Use case 2: Reproduction note for a visible bug

If the bug is “it sometimes breaks,” do not start with a fix. Ask for a reproduction note: conditions, expected result, actual result, relevant files, and missing logs. This pairs well with the Claude Code bug report template.

Success is not a patch. Success is a note that a human can verify. If the bug cannot be reproduced, the output should say so and list the next logs or data needed.

Use case 3: Documentation or UI copy change

Marketing sites, admin tools, and internal dashboards often make good first sessions because a single copy change is visible and reversible. Keep it narrow: one CTA, one settings explanation, or one paragraph.

Success means only the target files changed, the meaning stayed intact, and the result can be checked locally. On multilingual sites, also check that you did not update one locale while leaving the others inconsistent.

Use case 4: One small test improvement

If the project already has tests, adding one assertion is safer than adding a feature. Add a boundary case, an error-message expectation, or an empty-list case.

Passing tests are not the only success condition. Claude Code should explain what behavior the assertion protects. An assertion that cannot be explained becomes future maintenance noise.

Pre-commit diff review

After Claude Code edits files, return to human review. For the first task, avoid automatic commits and pushes. Permission modes trade convenience for oversight, so start with normal review or plan mode. Avoid powerful modes such as bypass permissions unless you are in an isolated environment.

Pre-commit checklist

[ ] Only requested files changed
[ ] No generated files, secrets, or local settings slipped in
[ ] A test or substitute verification result is recorded
[ ] Failed or skipped checks are disclosed
[ ] No unexplained diff remains
[ ] The handoff note contains the next TODO

Start with git diff --stat to see the spread. Run git diff --check for whitespace and patch hygiene. Then read the diff itself for surprise refactors, naming changes, or behavior changes without tests.

Common failure cases

The first failure is oversized scope. Say “verify the login error message with one test,” not “fix login.” Give Claude Code autonomy after it has earned trust on smaller tasks.

The second failure is accepting “done” without proof. If tests do not exist, define substitute proof first: rendered page, type check, git diff --check, log comparison, or a command from the README.

The third failure is approving permission prompts casually. When a prompt appears, ask what command is running, which paths it touches, and whether it includes network access or deletion. If repeated prompts are painful, pre-approve only narrow commands rather than loosening everything.

The fourth failure is context loss. Long conversations blur the original boundary. Keep the task boundary, commands run, and remaining risk in the handoff note. Do not mix permanent CLAUDE.md rules with one-session notes.

The fifth failure is damaging existing uncommitted work. In shared repositories, another developer or agent may already have changes. Start with git status --short and explicitly protect unrelated changes.

Handoff note template

Paste this at the end of the first task.

## Handoff note

- Task:
- Changed files:
- Verification run:
- Verification not run:
- Important diff points:
- Remaining risks:
- Do not touch next time:
- Suggested next smallest task:

This note is broader than a commit message. Before a commit, it becomes PR description material. Without a commit, it becomes the starting point for the next session.

Next steps and paid paths

After the first task succeeds, build repeatability. Solo users should turn recurring rules into CLAUDE.md templates. If approvals and sandboxing are still unclear, read the Claude Code approval and sandbox guide.

For ready-to-use templates, checklists, and onboarding material, see /products/. For team rollout, repository-specific onboarding, permission design, and review workflows, use /training/. One safe first task can be handled with this article. A team rollout needs rules, proof, and training before usage expands.

In Masa’s actual trial, the most stable pattern was: read the repo first, edit one file only, review git diff together, and leave a handoff note. Sessions that began with a large request created more review work than they saved. Sessions that succeeded on a 30-minute task made the second task easier to scope and much easier to explain to teammates.