diff-computation — Claude Code rule: what it does, how to install
The diff-computation rule sets the order for code review: build the diff before reading files. Findings stay on changed lines, and large patches are read in chunks.
MIT ★ 1,627 updated 2026-10-25
.github/instructions/diff-computation.instructions.mdWhat diff-computation does
The rule fixes the order of work: build the diff, then open source files. The agent runs git branch --show-current and git status --short and matches the first applicable case: a branch or PR, uncommitted edits on main, a code selection, a single commit, or nothing to review. Branch work goes through the pr-reference skill, which writes the patch to .copilot-tracking/pr/pr-reference.xml, lists changed files, and reads the diff in chunks with read-diff.sh --chunk N.
Findings stay inside the lines the diff adds or changes. Whole files are read for context only, and problems in untouched code go into a separate out-of-scope table that stays out of the verdict. Volume is handled in tiers: under 20 files analysed whole, 20 to 50 grouped by directory, above 50 in batches of 5-10 files. Past 2000 changed lines, or 500 in one file, commits get reviewed one at a time.
Lock files, minified bundles, source maps, binaries and build directories never enter the diff. All of it leans on the pr-reference scripts; when those are missing or fail, the rule falls back to git merge-base and git diff. A copy in .claude/rules/ does nothing by itself: code-review.agent.md has to pull the rule in with a #file: import, otherwise the agent never sees it.
What it helps with
- compute a branch diff before the agent reads any source file
- split a 2000-line diff into analysable chunks
- keep lock files and minified bundles out of the review
- separate feature-branch commits from uncommitted work on
main - hold findings to changed lines only
Example prompts for the agent
- Review the
feature/loginbranch — compute the diff first, then read files. - Review my uncommitted changes on
main, untracked files included. - This diff is huge; walk it chunk by chunk with
read-diff.sh --chunk Nand skip lock files.
How to install diff-computation
Manually: put the files in place
.github/instructions/diff-computation.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.claude/rules/diff-computation.mdThe paths frontmatter field limits the files: move applyTo from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/diff-computation.mdcFrontmatter: description, globs, alwaysApply. Move applyTo from the source into globs, or the rule will not attach on its own
Manually: put the files in place
.devin/rules/diff-computation.mdManually: put the files in place
.clinerules/diff-computation.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about diff-computation
How do I install diff-computation in Claude Code?
Place the file at .claude/rules/diff-computation.md in your project. For the review agent to pick it up, add a #file: import to code-review.agent.md.
What does diff-computation do?
It sets how a review agent obtains its diff: branch or commit detection, a scope locked to changed lines, chunked handling of large patches, and skipping of non-source files.
Does diff-computation need the pr-reference skill?
Branch reviews call its generate.sh and list-changed-files.sh scripts. If those are missing or fail, the rule computes the diff by hand with git merge-base and git diff.
Source text
diff-computation.instructions.md · MIT
--- description: "Code review diff computation: branch detection, scope locking, large-diff handling, and non-source filtering" --- # Diff Computation Protocol > Delivery: this file is delivered via the explicit `#file:` import in code-review.agent.md, not via `applyTo`. Plugin and extension distributions omit the repository artifact-root prefix, so a source-tree-qualified `applyTo` glob would match nothing once distributed. Future coding-standards agents or prompts that need this guidance must import it with `#file:` rather than relying on `applyTo`. Obtain the diff before reading any source files. Use the decision tree below to determine the appropriate method, then apply scope rules and large diff handling. ## Decision Tree Run `git branch --show-current` and `git status --short` to determine context. Match the first applicable case: 1. **Branch review** (user explicitly requests a specific branch or PR, or is on a feature branch that is not `main` and not detached HEAD): follow the Feature Branch Diff section. The pr-reference skill captures committed changes; a working-tree supplement captures staged, unstaged, and untracked changes. If the user says "review the PR" while on `main` or detached HEAD without naming a branch, PR, or commit, ask which branch or PR they want reviewed, then route to this case or to the Specific Commit section as appropriate. 2. **Local uncommitted changes on `main` or detached HEAD** (not on a feature branch, but edits exist that are not yet committed): follow the Uncommitted Changes section. 3. **Selected code or `#file` references** (user selects code in the editor or references `#file:path/to/file.ext`): follow the Selected Code section. 4. **Specific commit review** (user asks to review a particular commit): follow the Specific Commit section. 5. **No reviewable content**: inform the user that no diff could be determined and stop. ## Feature Branch Diff Invoke the **pr-reference** skill to compute the diff. The skill handles branch detection, merge-base resolution, file listing, non-source exclusions, and large diff chunking. 1. Generate the structured diff to an explicit output path so that path is a single source of truth the review agent reuses for `diffPatchPath` (overridable, not implicitly coupled to the skill default): ```bash generate.sh --base-branch auto --merge-base --exclude-ext min.js,min.css,map --output .copilot-tracking/pr/pr-reference.xml ``` ```powershell generate.ps1 -BaseBranch auto -MergeBase -ExcludeExt min.js,min.css,map -OutputPath .copilot-tracking/pr/pr-reference.xml ``` 2. Get the changed file list: ```bash list-changed-files.sh --exclude-type deleted --format plain ``` ```powershell list-changed-files.ps1 -ExcludeType Deleted -Format Plain ``` 3. For large diffs, use chunk planning and batched analysis: ```bash read-diff.sh --info # chunk count and size summary read-diff.sh --chunk N # read chunk N ``` ```powershell read-diff.ps1 -Info # chunk count and size summary read-diff.ps1 -Chunk N # read chunk N ``` If the changed-file list (`list-changed-files.sh` or `list-changed-files.ps1`) returns an empty list, stop and report "no reviewable content" per Decision Tree case 5. Pass the diff output and file list as pre-computed input to the review agent so it skips its own scope detection. ## Uncommitted Changes * Unstaged: `git diff HEAD` * Staged: `git diff --cached` * Untracked (new files not yet staged): enumerate with `git ls-files --others --exclude-standard`, then read the full content of each file as the review input. ## Selected Code Use the provided code as the review input; no git diff is needed. Apply all loaded skills or review logic to the selected code. Skip artifact persistence since there is no branch context. ## Specific Commit ```bash git diff <commit>^..<commit> ``` ## Scope Rules * Do not enumerate, list, or read source files before obtaining the diff or review input. * Only lines present in the diff (added or modified lines) are in scope for findings. * For selected code reviews (no diff context), all provided code lines are in scope. * Read full file contents only for contextual understanding of diff lines, never as a source of findings. * Pre-existing issues in unchanged code go in the **Out-of-scope Observations** table, clearly labelled and excluded from the verdict. ## Large Diff Handling Use the `timeout` parameter on terminal commands to prevent hanging on large repositories. | Changed Files | Strategy | |---------------|----------------------------------------------------------------| | Fewer than 20 | Analyze all files with full diffs. | | 20 to 50 | Group files by directory and analyze each group. | | More than 50 | Progressive batched analysis, processing 5-10 files at a time. | When a diff exceeds 2000 lines of combined changes or 500 lines in a single file, review the most recent commits individually using `git log --oneline` and `git show --stat`. ## Non-Source Artifact Skip List Skip these artifacts when computing and analyzing diffs: * Lock files: `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` * Minified bundles: `.min.js`, `.min.css` * Source maps: `.map` * Binaries * Build output directories: `/bin/`, `/obj/`, `/node_modules/`, `/dist/`, `/out/`, `/coverage/` ### Fallback (pr-reference skill unavailable) If the pr-reference skill scripts are not found or fail, compute the diff manually: 1. Resolve the merge-base: `git merge-base origin/<default-branch> HEAD` 2. Generate the diff: `git diff <merge-base>...HEAD` 3. List changed files: `git diff <merge-base>...HEAD --name-only` 4. For uncommitted changes, supplement with `git diff HEAD`, `git diff --cached`, and `git ls-files --others --exclude-standard` Apply the Non-Source Artifact Skip List and Large Diff Handling rules to the manual output.
© microsoft · MIT · microsoft/hve-core