docs(opencode): steer ask-claude skill toward repo access for reviews

Add a "Code review pattern" section that tells the opencode agent to give
claude read-only access to the repo (Read/Grep/Glob plus a narrow git
allowlist) instead of gathering a full `git diff` and piping it in. The
piped-diff form loses surrounding-file context, bloats the prompt, and
falls over on large branches. Also adds a matching entry to "Don'ts" and
caveats the existing pipe-stdin example.

Motivated by an opencode run that collected the entire branch diff as
stdin instead of pointing claude at the working tree.
This commit is contained in:
Harald Hoyer 2026-05-05 13:56:40 +02:00
parent 425ee187cf
commit 5d0e1fcdd6

View file

@ -42,6 +42,40 @@ cat path/to/file.rs | claude -p "Review this for race conditions; explain any yo
git diff main...HEAD | claude -p "Spot bugs or risky changes in this diff." git diff main...HEAD | claude -p "Spot bugs or risky changes in this diff."
``` ```
Only pipe when the context is small and self-contained. For anything that
spans multiple files, prefer giving Claude repo access (next section) so it
can read surrounding code, not just the patch.
## Code review pattern
For a review of the current branch / working tree, **do not** gather diffs
yourself and stuff them into the prompt. Point Claude at the directory and
let it run `git` and read files on its own — it sees more context (full
files, history, neighbouring code) than a piped diff alone can provide,
and it will only fetch what it actually needs.
Recommended invocation, run from the repo root:
```bash
claude -p --permission-mode dontAsk \
--allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git status:*) Bash(git show:*)" \
"Review the changes on this branch vs main. Flag bugs, risky changes,
and anything that violates the project's conventions. Read whatever
files you need for context."
```
Why this is better than `git diff … | claude -p`:
- Claude can open the *full* file around a hunk, not just the ±3 lines of
context in the patch.
- Claude can follow references — call sites, tests, related modules.
- The prompt stays small, so the model spends its tokens on reasoning
instead of re-reading a diff you already had on disk.
- Works for large diffs that would otherwise blow the context window.
Use the piped form only for a tiny, self-contained snippet where extra
repo context genuinely adds nothing.
## Permissions ## Permissions
In `-p` mode there is no human to approve prompts, so anything not explicitly In `-p` mode there is no human to approve prompts, so anything not explicitly
@ -143,6 +177,9 @@ with `jq`.
- Don't call `claude -p` in a loop or for trivial questions — it is expensive. - Don't call `claude -p` in a loop or for trivial questions — it is expensive.
- Don't pass the entire conversation history; distill the question first. - Don't pass the entire conversation history; distill the question first.
- Don't gather a giant `git diff` and pipe it in for code review — give
Claude read-only repo access (see "Code review pattern") and let it pull
exactly the context it needs.
- Don't ask Claude to "do" multi-step refactors with file writes — collect its - Don't ask Claude to "do" multi-step refactors with file writes — collect its
recommendations and apply them yourself, so you stay in control. recommendations and apply them yourself, so you stay in control.
- Don't forget that Claude has no memory between calls — every invocation - Don't forget that Claude has no memory between calls — every invocation