🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
docs: add team code review policy (#18091)
Max Deichmann42e67c96c6f4
diff --git a/.agents/README.md b/.agents/README.mdindex 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 candisable the fallback; remove local compatibility files or choose the modethat 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.+## ValidationTwo levels, deliberately separated:diff --git a/REVIEW.md b/REVIEW.mdnew file mode 100644index 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.