Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

docs: add team code review policy (#18091)

Max Deichmann42e67c96c6f4
diff --git a/.agents/README.md b/.agents/README.md
index 3c93d87646..402e451d79 100644
--- a/.agents/README.md
+++ b/.agents/README.md
@@ -136,6 +136,12 @@ Project-local `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` files can
disable the fallback; remove local compatibility files or choose the mode
that loads both formats. See the [instruction loader documentation](https://github.com/anthropics/claude-code/blob/main/mods/agents-md/README.md).
+## Hosted Claude Code Review
+
+Root [`REVIEW.md`](../REVIEW.md) defines review rules, severity, and reporting.
+It references domain skills for technical guidance. Claude's hosted reviewer
+loads it automatically; request it explicitly for local `/code-review` runs.
+
## Validation
Two levels, deliberately separated:
diff --git a/REVIEW.md b/REVIEW.md
new file mode 100644
index 0000000000..1b170a4a6f
--- /dev/null
+++ b/REVIEW.md
@@ -0,0 +1,116 @@
+# Code review
+
+Review new or worsened code. Do not require unrelated legacy cleanup.
+New violations of team rules must be fixed before merge, even without a bug.
+Exceptions need explicit human approval.
+
+## References
+
+Read the applicable `AGENTS.md` files and references below. Report unavailable
+references. This file overrides conflicting guidance for reviews.
+
+- [Backend](.agents/skills/backend-dev-guidelines/SKILL.md)
+- [Security](.agents/skills/security-review/SKILL.md): auth, RBAC, tenant isolation,
+ outbound requests, secrets, and telemetry
+- [ClickHouse](.agents/skills/clickhouse-best-practices/SKILL.md)
+- [React](.agents/skills/react-component-guidelines/SKILL.md) and
+ [design system](web/src/components/design-system/README.md)
+- [Frontend data and state](.agents/skills/frontend-large-feature-architecture/SKILL.md)
+- [Storybook](.agents/skills/storybook/SKILL.md)
+- [Architecture](.agents/ARCHITECTURE_PRINCIPLES.md)
+
+Use their technical rules, not their implementation or handoff workflows.
+
+## Team rules
+
+### Architecture
+
+- One responsibility and abstraction level per function. The main export reads
+ as a linear sequence of named calls. Extract dense branches, even if that adds lines.
+- Group components, hooks, and helpers under `features/<feature>/`, not top-level
+ folders grouped by kind.
+- Return results instead of mutating inputs.
+- Inject dependencies through constructors. Call ordinary helpers directly.
+- Reuse and extend existing functionality. Keep solutions simple. When flagging
+ complexity, show a simpler alternative that meets the same requirements.
+
+### Components and state
+
+- Use `web/src/components/design-system/` primitives and their styling rules.
+ Add variants instead of custom `className` values.
+- Export one component per file. Match the filename to the component and name
+ its props type `<ComponentName>Props`.
+- Use `children` or conditionals, not `renderX` props. Extract nested JSX-returning
+ functions into components. Use a store when extracted components share state.
+- Name action handlers; no inline functions in JSX.
+- Fetch data in custom hooks, not UI components. Use `react-hook-form` for forms.
+- No `useEffect`, including integration exceptions in older guidance. Do not
+ hide effects in new wrappers or replace them with `useLayoutEffect`.
+- Use the router for navigation. Preserve existing URL state and local/session
+ storage settings.
+
+### Control flow and files
+
+- No nested ternaries, including JSX. Use guards or separate components.
+ Replace conditionals deeper than two levels with early returns.
+- Handle every switch variant explicitly. Compare `.length` explicitly.
+- Comments must add information beyond the name. Keep them terse, without
+ commentary or speculation, using `/** X does Y [for Z] */`.
+- Put callers above callees. Order `.ts`/`.tsx` files: imports, module constants
+ or lookup tables, main export, private subcomponents, custom hooks, helpers,
+ helper types, then `export const __test = { ... }` if needed.
+
+### Tests
+
+- One representative input per code path, plus each boundary. Remove redundant
+ cases; retain distinct contracts and paths.
+- Tests must fail when the behavior breaks or its implementation is deleted.
+ No mocks that just return the expected answer or always-true assertions.
+- Remove regression tests when types, schemas, or deleted paths prevent the bug.
+ Check that runtime inputs cannot bypass those protections.
+- Test components only through Storybook. Use `.clienttest.ts` for frontend unit
+ tests, not in-source tests. Keep backend and worker conventions.
+- No dependencies on other tests, execution order, or another test's seeding.
+
+### Security and performance
+
+- Verify auth and RBAC on every changed read/write path. Check for bypasses and
+ privilege escalation through roles, resource IDs, and tenant context.
+ Upstream checks must cover every entry point.
+- Ingestion changes must not worsen throughput, latency, or resource cost per
+ event, including downstream jobs and writes. Check per-event work, batching,
+ concurrency, and backpressure. Compare changed execution under equivalent,
+ representative loads: throughput, tail latency, CPU, memory, and I/O as relevant.
+- ClickHouse queries must be fast at representative volumes and cardinalities.
+ Follow the ClickHouse skill. Check schema and query plans; measure runtime,
+ rows/bytes read, and peak memory, including broad supported filters.
+ Tiny fixtures or cached results are insufficient.
+- Compare performance before/after; assess new queries against documented
+ budgets. Do not invent budgets or results. Missing measurements require
+ verification before merge, not an unsupported claim of safety or regression.
+
+## Findings
+
+- **Important:** verified bug, harmful design, or new team-rule violation.
+ Fix before merge unless a human explicitly accepts it.
+- **Nit:** useful but optional improvement beyond team rules. At most two.
+- Omit preferences, speculation, duplicates, and mechanical failures reported by CI.
+
+Before reporting, compare with the PR base and read callers, safeguards, and tests.
+Look for evidence that disproves the finding. Bugs need a reachable trigger and
+consequence, supported by code, a reproducer, test, or execution trace. Rule
+violations need the rule and offending code. State assumptions; separate
+measurements from estimates. Unresolved risks belong in verification questions,
+not assertions or Nits.
+
+Put correctness, security, and performance risks first, ordered by impact and
+recoverability, then rule violations. Report serious pre-existing bugs separately;
+they do not block this PR. Prefer local fixes over redesigns.
+
+Give each finding a short title, precise location, evidence, and fix or next check.
+Group repeated causes or rule violations. Report every Important finding.
+Review generated code and dependency changes for bugs; fix their source.
+
+On re-review, verify fixes and report newly verified Important findings. Do not
+repeat resolved feedback or add Nits. End with unresolved questions and checks
+actually run. Say when there are no findings; do not claim that proves safety.