review-artifacts — правило для Claude Code
Правило review-artifacts для Claude Code сохраняет результаты код-ревью в согласованной структуре. Оно применяется к файлам в .copilot-tracking/reviews/code-reviews/.
MIT ★ 1 627 обновлён 2026-10-25
.github/instructions/review-artifacts.instructions.mdЧто делает review-artifacts
Правило задаёт структуру файлов и формат метаданных для результатов код-ревью. В папке ветки агент сохраняет review.md, metadata.json, diff-state.json и dispatch-manifest.json; имя ветки в пути формируется заменой / на -.
Для вердикта используются значения approve, approve_with_comments и request_changes. В режиме интерактивного обзора с ориентацией на человека добавляются доска разбора, walkthrough и связанные артефакты; в неинтерактивном запуске их не создают. Значения риска и глубины ревью записываются до передачи работы субагентам.
Перед записью правило требует получить SHA коммита через git rev-parse HEAD и текущую метку времени UTC. Для каждой ветки существующие review.md и metadata.json перезаписываются, так что хранится только последний обзор.
Какие задачи решает
- сохранить отчёт код-ревью и его метаданные по ветке
- нормализовать вердикт агента для последующей обработки
- передать субагентам общее состояние diff и глубину ревью
- разделить артефакты интерактивного и workflow-обзора
Примеры запросов агенту
- Сохрани результат код-ревью ветки в
.copilot-tracking/reviews/code-reviews/. - Запиши метаданные ревью с нормализованным вердиктом и списком изменённых файлов.
- Подготовь артефакты интерактивного обзора и свяжи их с
review.md.
Как установить review-artifacts
Вручную: положить файлы
.github/instructions/review-artifacts.instructions.mdПоле applyTo задаёт, к каким файлам применять
Вручную: положить файлы
.claude/rules/review-artifacts.mdПоле paths во frontmatter ограничивает файлы: applyTo из источника → paths
AGENTS.md
Codex читает AGENTS.md: вставьте текст правила туда
Вручную: положить файлы
.cursor/rules/review-artifacts.mdcВо frontmatter: description, globs, alwaysApply. applyTo из источника → globs, иначе правило само не подключится
Вручную: положить файлы
.devin/rules/review-artifacts.mdВручную: положить файлы
.clinerules/review-artifacts.mdПо шагам, с командами для каждой платформы: AGENTS.md и CLAUDE.md: что это, кто читает и какой выбрать
Вопросы о review-artifacts
Как установить review-artifacts в Claude Code?
Добавь файл правила по пути .claude/rules/review-artifacts.md.
Что делает review-artifacts?
Правило описывает, куда сохранять результаты код-ревью, как оформлять метаданные и как приводить вердикты к стандартным значениям. Оно также задаёт общие данные о diff и глубине проверки.
Какие файлы создаются только в интерактивном режиме?
В режиме интерактивного обзора создаются dispatch-board.md, walkthrough.md, пояснения, материалы исследования и emission-record.json. В неинтерактивном запуске эти артефакты пропускаются.
Исходный текст
review-artifacts.instructions.md · MIT
---
description: "Code review artifact persistence: folder structure, metadata schema, verdict normalization, and writing rules"
applyTo: "**/.copilot-tracking/reviews/code-reviews/**"
---
<!-- markdownlint-disable-file -->
# Review Artifacts Persistence Protocol
Any code review agent that produces a structured verdict follows this protocol to enable CI integration and cross-agent artifact compatibility.
## Folder Structure
```text
.copilot-tracking/
reviews/
code-reviews/
<sanitized-branch>/
review.md # full markdown review output
metadata.json # machine-readable summary (see schema below)
diff-state.json # shared subagent input (branch, base, files, depth)
dispatch-manifest.json # canonical loop state (phase gates, next actions, board items)
dispatch-board.md # human-readable enumerated dispatch board
walkthrough.md # factual Register 1 orientation narrative
emission-record.json # selected emission mode, target, status, outcome
explanations/
<board-item>-<symbol>.md # per-item Register 1 explanation artifacts
walkback/
<board-item>-research.md # per-item Register 2 investigation artifacts
```
Sanitize the branch name by replacing every `/` with `-`
(e.g. `feat/my-feature` → `feat-my-feature`).
The `review.md`, `metadata.json`, `diff-state.json`, and `dispatch-manifest.json`
artifacts are always produced. The orientation-first artifacts
(`dispatch-board.md`, `walkthrough.md`, `explanations/`, `walkback/`, and
`emission-record.json`) are produced only when the review runs in interactive
orientation-first mode; omit them in non-interactive workflow runs.
## metadata.json Schema
```json
{
"schema_version": "1",
"branch": "<original branch name, e.g. feat/my-feature>",
"head_commit": "<full SHA of HEAD at time of review>",
"reviewed_at": "<ISO 8601 UTC timestamp, e.g. 2026-02-27T10:00:00Z>",
"verdict": "<normalized verdict - see table below>",
"files_changed": ["<workspace-relative paths of source files in the diff>"],
"findings_count": {
"critical": 0,
"high": 0,
"medium": 0,
"low": 0
},
"reviewer": "<agent or prompt name, e.g. code-review>",
"artifacts": {
"dispatch_manifest": "dispatch-manifest.json",
"dispatch_board": "dispatch-board.md",
"walkthrough": "walkthrough.md",
"emission_record": "emission-record.json",
"explanations": ["explanations/<board-item>-<symbol>.md"],
"walkbacks": ["walkback/<board-item>-research.md"]
}
}
```
The `artifacts` object records the orientation-first artifacts produced during
the review. Omit any key whose artifact was not produced (for example, omit
`artifacts` entirely for a non-interactive workflow run, or omit `explanations`
when no per-item explanation was requested). The `explanations` and `walkbacks`
values are arrays of review-folder-relative paths, one entry per board item
that was explained or investigated.
## Verdict Normalization
| Agent Output Verdict | `verdict` value |
|--------------------------|-------------------------|
| ✅ Approve | `approve` |
| 💬 Approve with comments | `approve_with_comments` |
| ❌ Request changes | `request_changes` |
## Orientation-First Artifacts
Interactive orientation-first reviews persist the following artifacts alongside
`review.md` and `metadata.json`. Each is referenced from `review.md` so the
markdown report links to the supporting evidence.
* `dispatch-manifest.json` — the canonical loop state: `phaseGates`,
`currentPhase`, `nextActions`, and `boardItems`. This is the machine-readable
source of truth for the human-steered walk-back loop.
* `dispatch-board.md` — the human-readable enumerated board rendered from the
manifest `boardItems`: id, area, status, register, summary, openable links,
and selectable symbols.
* `walkthrough.md` — the factual Register 1 orientation narrative (diff summary,
runway summary, and appendices) presented before any findings register. It
contains no severity grades or verdicts.
* `explanations/<board-item>-<symbol>.md` — per-item Register 1 explanation
artifacts written by the explainer when a human asks a shallow factual
question about a symbol. Each includes the answer, source file reference,
relevant code excerpt, and follow-on symbols.
* `walkback/<board-item>-research.md` — per-item Register 2 investigation
artifacts written by the walk-back researcher when a human asks a deep
investigative question. Each is anchored to its board item.
* `emission-record.json` — the selected emission `mode` (native or canonical),
`target` (PR, MR, ADO, or review artifact), `status` (completed or skipped),
and a short outcome `summary`.
## Change-Risk Decision State
`diff-state.json` is the canonical owner of the evidence and depth decision used by every review lane:
* `reviewStateProvenance` records `human-confirmed` or `automation-derived` origins for `scope`, `changeRiskEvidence`, `recommendedDepth`, `depthTier`, and `depthRationale`. It describes origin, not confidence.
* `changeRiskEvidence` contains exactly one entry for each of `change-scope`, `path-criticality`, `history`, `test-presence`, `coverage`, and `rollback`.
* Each entry contains `signal`, `availability`, and `evidence`. The `availability` field records the evidence state, not confidence in a claim. Its value is `observed`, `unavailable`, or `qualitative`; unavailable inputs remain explicit and are never fabricated.
* `recommendedDepth` records the advisory `basic`, `standard`, or `comprehensive` recommendation. Use `standard` when evidence is incomplete or inconclusive unless observed evidence supports comprehensive review.
* In interactive mode, existing `depthTier` remains the human-selected verification depth, and `depthRationale` explains that selection and any difference from `recommendedDepth`. Mark scope, evidence, depth, and rationale as `human-confirmed`; keep the advisory recommendation `automation-derived`.
* In workflow mode, mark all five provenance values `automation-derived`. Host-supplied or default values are not represented as human-confirmed.
In interactive mode, write these values after human scope and depth confirmation. In workflow mode, write them after automated context preparation. Complete either write before perspective dispatch. Subagents consume the values and provenance as shared context but do not recalculate or overwrite them.
## Writing Rules
* Always overwrite any existing `review.md` and `metadata.json` for the branch: only the latest review per branch is retained.
* Obtain the HEAD commit SHA with `git rev-parse HEAD` immediately before writing artifacts.
* Obtain the current UTC timestamp immediately before writing artifacts:
* In POSIX-compatible shells, use `date -u +%Y-%m-%dT%H:%M:%SZ`.
* In PowerShell, use `Get-Date -AsUtc -Format "yyyy-MM-ddTHH:mm:ssZ"`.
* `files_changed` must list only source files present in the diff (additions, modifications, or deletions). Filter by relevance - e.g. `.py`, `.sh`, `.ts`, `.tf` - excluding lock files, binaries, and build output.
* Do not write artifacts if the diff was empty and the review was aborted.
* The `reviewer` field must use the kebab-case form of the agent's or prompt's `name` from its frontmatter (e.g. `Code Review` → `code-review`).
* Write orientation-first artifacts only when the review runs in interactive orientation-first mode; record each produced artifact under the `artifacts` key in `metadata.json` and link it from `review.md`.
* Keep `walkthrough.md` and `explanations/` artifacts factual (Register 1): no severity grades or verdicts. Keep `walkback/` artifacts in the structured investigation register (Register 2).
* Create the `explanations/` and `walkback/` subfolders only when at least one explanation or investigation artifact is written.
* Every `review.md` ends with a **Disclaimer and Human Review** section: the verbatim `## Code-Review` CAUTION disclaimer from `disclaimer-language.instructions.md` followed by an unchecked `- [ ] Reviewed and validated by a qualified human reviewer` checkbox. This section is always present, is always the final section, and the agent never checks the checkbox; only a human may convert `[ ]` to `[x]`.
* When the review scope targets a pull request or merge request, `review.md` includes a mandatory human-editable **PR Comment Draft** section with an unchecked posting checkbox. This section is the only place the general PR or MR comment is authored; the agent never reproduces the full drafted comment body in the conversational summary. The agent never checks the posting box; only the human may convert `[ ]` to `[x]`, and that check is the gate that authorizes posting the general PR or MR comment.
© microsoft · MIT · microsoft/hve-core