If .claude/skills/review-conventions/SKILL.md.disabled exists, stop before reading a fallback.
Project configuration: If the current project contains .claude/skills/review-conventions/SKILL.md, read and apply it instead of this bundled default. The project copy is the capability source of truth.
Repository context: Read ../setup/references/task-context.md when resolving a task, project commands, named agent roles, or legacy .claude/ resource paths. Use repository evidence and applicable project instructions; a missing local workflow copy does not require setup. Resolve bundled resources from the installed skill, never from the target cwd.
Review Conventions
Shared knowledge preloaded into review agents. Apply these conventions when reviewing code.
Project context
This reference stays generic so it can run in any repository. Read an
applicable CLAUDOPS.md, manifests, CI configuration, source layout, and
existing code before applying project-specific review rules. Use the project's
own language, framework, layers, test commands, and documentation locations;
leave unknowns explicit. {{...}} markers are historical template notation,
never runtime defaults or executable paths.
Architecture Rules
Review boundaries and dependencies as the target project defines them. Use its
architecture vocabulary where it already has one; do not rename service,
API, module, or similar identifiers merely to fit this reference.
Code Standards
- Prefer project-established type/interface conventions
- Preserve local naming and type conventions; apply language-specific rules such
as underscore prefixes or
any only when the repository's tooling establishes
them.
- Secrets never logged; environment vars flow only through config providers
- Database queries use parameter binding — no dynamic SQL or string interpolation
Review Quality Rules
Reviews run in two stages so we get recall AND precision:
Find stage (this skill) — report every issue you notice, including low-severity
and uncertain ones. For each finding, include:
severity: CRITICAL | MAJOR | MINOR | INFO
confidence: high | medium | low
location: file:line
suggestion: concrete fix or next step
Do not self-censor based on severity or confidence — a later verification pass
will filter before anything reaches the user.
Presentation — consolidate repeats ("5 functions missing error handling" with
a list, not 5 separate findings). Explain why each issue matters. Highlight
positive practices alongside problems.
Sizing & Comment Hygiene
Norms from Google's engineering practices guide:
Change sizing — a reviewable change is small (~100 lines is a healthy target). If the diff is large and not mechanically generated, flag it and suggest splitting; a 1000-line PR gets a worse review, not a better one.
The standard is "improves code health" — approve a change that improves the codebase even if it isn't perfect. Don't block on personal preference; block on real problems.
Mark non-blocking comments — prefix advisory notes (Nit:, Optional:, FYI:) so the author can tell what must change from what's a suggestion. Severity inflation trains authors to ignore you.
Primary scope: only review files in changed_files
Use full_diff to focus on changed lines
You may read unchanged files for context (interfaces, contracts), but don't raise
findings against unchanged code — the author isn't touching it in this PR.
Skip pre-existing issues unless the current changes make them worse (e.g., a bug
that used to be in dead code is now reachable).
Ownership Boundaries
Each agent owns specific concerns — do not duplicate other agents' work:
| Concern |
Owner |
| Spec requirements match |
spec-compliance-reviewer |
| Architecture fit, layers, module boundaries |
senior-architecture-reviewer |
| Security, auth, injection, OWASP |
security-code-reviewer |
| Code quality, naming, DRY, complexity |
code-quality-reviewer |
| Test coverage and quality |
test-coverage-reviewer |
| Documentation accuracy |
documentation-accuracy-reviewer |
| Performance, N+1, memory |
performance-reviewer |
If you spot something outside your scope, note it as a one-line INFO finding with
the likely owner (e.g. "possible security concern — flag for security-code-reviewer")
and move on.
Project File Locations
- Architecture docs: resolve from the repository's documented location or
changed-file references; do not assume a
docs/ subdirectory.
- Product docs (PRDs, JTBDs):
product-docs/
- Task documents: resolve through
../setup/references/task-context.md; preserve
repository conventions such as tasks/<task-dir>/tech-decomposition*.md
- Test structure: infer from the repository's existing test layout and CI.
1---2name: review-conventions-43description: Internal reference skill — shared conventions for all code review agents. Not user-invocable.4compatibility: Portable clients may not enforce Claude Code invocation guards or project setup behavior.5metadata:6 source: https://skillmd.com/skills/alexandrbasis/review-conventions-47---89<!-- claudops-build: project-config-pointer -->10> If `.claude/skills/review-conventions/SKILL.md.disabled` exists, stop before reading a fallback.11> **Project configuration:** If the current project contains `.claude/skills/review-conventions/SKILL.md`, read and apply it instead of this bundled default. The project copy is the capability source of truth.12> **Repository context:** Read `../setup/references/task-context.md` when resolving a task, project commands, named agent roles, or legacy `.claude/` resource paths. Use repository evidence and applicable project instructions; a missing local workflow copy does not require setup. Resolve bundled resources from the installed skill, never from the target cwd.1314# Review Conventions1516Shared knowledge preloaded into review agents. Apply these conventions when reviewing code.1718## Project context1920This reference stays generic so it can run in any repository. Read an21applicable `CLAUDOPS.md`, manifests, CI configuration, source layout, and22existing code before applying project-specific review rules. Use the project's23own language, framework, layers, test commands, and documentation locations;24leave unknowns explicit. `{{...}}` markers are historical template notation,25never runtime defaults or executable paths.2627## Architecture Rules2829Review boundaries and dependencies as the target project defines them. Use its30architecture vocabulary where it already has one; do not rename `service`,31`API`, `module`, or similar identifiers merely to fit this reference.3233## Code Standards3435- Prefer project-established type/interface conventions36- Preserve local naming and type conventions; apply language-specific rules such37 as underscore prefixes or `any` only when the repository's tooling establishes38 them.39- Secrets never logged; environment vars flow only through config providers40- Database queries use parameter binding — no dynamic SQL or string interpolation4142## Review Quality Rules4344Reviews run in two stages so we get recall AND precision:45461. **Find stage (this skill)** — report every issue you notice, including low-severity47 and uncertain ones. For each finding, include:48 - `severity`: CRITICAL | MAJOR | MINOR | INFO49 - `confidence`: high | medium | low50 - `location`: `file:line`51 - `suggestion`: concrete fix or next step52 Do not self-censor based on severity or confidence — a later verification pass53 will filter before anything reaches the user.54552. **Presentation** — consolidate repeats ("5 functions missing error handling" with56 a list, not 5 separate findings). Explain why each issue matters. Highlight57 positive practices alongside problems.5859## Sizing & Comment Hygiene6061Norms from Google's [engineering practices guide](https://google.github.io/eng-practices/):6263- **Change sizing** — a reviewable change is small (~100 lines is a healthy target). If the diff is large and not mechanically generated, flag it and suggest splitting; a 1000-line PR gets a worse review, not a better one.64- **The standard is "improves code health"** — approve a change that improves the codebase even if it isn't perfect. Don't block on personal preference; block on real problems.65- **Mark non-blocking comments** — prefix advisory notes (`Nit:`, `Optional:`, `FYI:`) so the author can tell what must change from what's a suggestion. Severity inflation trains authors to ignore you.6667- Primary scope: only review files in `changed_files`68- Use `full_diff` to focus on changed lines69- You may read unchanged files for context (interfaces, contracts), but don't raise70 findings against unchanged code — the author isn't touching it in this PR.71- Skip pre-existing issues unless the current changes make them worse (e.g., a bug72 that used to be in dead code is now reachable).7374## Ownership Boundaries7576Each agent owns specific concerns — do not duplicate other agents' work:7778| Concern | Owner |79|---------|-------|80| Spec requirements match | `spec-compliance-reviewer` |81| Architecture fit, layers, module boundaries | `senior-architecture-reviewer` |82| Security, auth, injection, OWASP | `security-code-reviewer` |83| Code quality, naming, DRY, complexity | `code-quality-reviewer` |84| Test coverage and quality | `test-coverage-reviewer` |85| Documentation accuracy | `documentation-accuracy-reviewer` |86| Performance, N+1, memory | `performance-reviewer` |8788If you spot something outside your scope, note it as a one-line INFO finding with89the likely owner (e.g. "possible security concern — flag for `security-code-reviewer`")90and move on.9192## Project File Locations9394- Architecture docs: resolve from the repository's documented location or95 changed-file references; do not assume a `docs/` subdirectory.96- Product docs (PRDs, JTBDs): `product-docs/`97- Task documents: resolve through `../setup/references/task-context.md`; preserve98 repository conventions such as `tasks/<task-dir>/tech-decomposition*.md`99- Test structure: infer from the repository's existing test layout and CI.