cratis-performance-review
Perform a focused scalability review of changed code in a Cratis application — Chronicle observers and replay, read-model query shape, command and query payloads, .NET enumeration, and React render cost — and report findings by risk. Use when asked to check for performance or scalability problems. Do not use for ordinary implementation and do not override the authoritative paging guidance.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- cratis-performance-review
- license
- MIT
- description
- Perform a focused scalability review of changed code in a Cratis application — Chronicle observers and replay, read-model query shape, command and query payloads, .NET enumeration, and React render cost — and report findings by risk. Use when asked to check for performance or scalability problems. Do not use for ordinary implementation and do not override the authoritative paging guidance.
02 资源文件 1
- 许可证LICENSE204 B
03 SKILL.md 正文
<!-- cratis-ai-managed: skills/cratis-performance-review/SKILL.md -->
Cratis performance review
Most performance findings in a Cratis application are shape problems, not hot-loop problems: a projection that has to re-read, a query that materializes before it filters, a payload nobody uses. They are cheap to fix while the change is open and expensive once data has grown behind them.
Two things make this stack different. A projection must be able to replay the entire history — a cost that is invisible at development volumes and fatal at production ones. And an event is permanent, so an oversized event is a storage and replay cost that never goes away.
Verified product sources
| Package | Purpose |
|---|---|
Cratis.Chronicle |
Observers, projections, reducers, reactors, replay |
Cratis.Arc.Core |
Query return shapes and server-side paging |
@cratis/components |
DataTable paging surface |
Paged MongoDB observations re-read page and total on each change; see the read-model query reference for the distinction from unpaged retained sets.
Reverify against the owning product repository before asserting a framework behavior this file does not already state.
Route near misses
- General correctness and maintainability: use
cratis-code-review. Its performance section is the pass-by list; this skill is the focused one. When both have run, do not restate the same finding twice. - Adding paging to a query rather than judging one: use
cratis-arc-query-paging. That skill is authoritative on the mechanism; this one does not override it. - Security or data exposure: use
cratis-security-review. An over-fetching payload is a finding for both — say which lens produced it.
Step 1 — Chronicle and event sourcing
- A projection joins on events, never on a read model. A read-model join forces a re-read the projection engine cannot optimize, and it makes the projection depend on another observer's position.
- A reactor does not re-query the event log inside its handler. The event it
received already carries what it needs. (Reactor dispatch is by the handler's
first parameter type — the method name is free, so look for the event-typed
parameter, not for a method called
On.) - A new projection can replay all earlier events without failing. Ask it explicitly: at production volume, does this projection complete a full replay?
- Events are small. No large blob and no base64 payload embedded in an event; put the content elsewhere and carry a reference.
- No eager load of a whole event sequence without paging or filtering.
- AutoMap is on by default. Hand-mapping every property is both a maintenance and a cost problem — and, since AutoMap runs anyway, it does not save the work it appears to.
Step 2 — Read models and their store
- Queries filter on indexed fields. An unintentional full-collection scan is the most common finding here.
- A list that can grow returns a shape Arc pages —
IQueryable<T>for a LINQ-native provider,collection.Observe(...)for MongoDB — so Arc applies server-side paging and sorting. A query that writes its ownSkip/TakeorOrderByfor the client's page or sort is a finding, as is MongoDBAsQueryable()(translation failures at request time). Materializing and then slicing in memory reads the whole collection every request. - No N+1: one query returns what the caller needs.
- A count is a count. Hydrating the collection to measure its length is the same finding as an unpaged list, wearing different clothes.
- Prefer slim projection-backed summaries over repeatedly assembling broad collections. Query composition is supported; one collection per query is not a framework requirement. Bound each input and measure recomputation.
- Embed bounded related state, not growing histories; page timelines separately. Evaluate variants for divergent lifecycle shapes, not every status field.
- Preserve reducer admission and ordering guards when proposing a projection conversion; an unconditional setter may resurrect or prematurely create state.
- Count passive models as inventory, not a smell. Assess history length and read
frequency against consistency/security needs. Requires Chronicle 19.77.3 for
per-key strongly consistent projection reads to fold from the start each time;
repeated reads are O(key history), not incremental cache hits. Prefer a
materialized projection for frequent long-history reads when freshness permits.
IMongoCollection<T>cannot read passive computed state; never materialize secrets to make that query work. - Distinguish retained
Observestate and in-memory emissions from explicit recompute queries. Narrow source filters and inspect page-refill/membership lookups; do not claim every change re-queries the entire collection. See the cratis-chronicle-read-model query reference for versioned behavior.
Step 3 — Commands and queries
- A response payload carries only fields the client uses.
- Command validators are synchronous and in-memory. Validation is on the hot path of every attempt, including the ones that will be rejected — an I/O call there is paid on every request.
- No
await Task.Run(() => syncWork)wrapping for work that is naturally asynchronous.
Step 4 — .NET
- No
.ToList()before.Where(). Filter before materializing. - An
IEnumerable<T>is not enumerated more than once — materialize once when it must be reused. - Large-object logging uses the destructuring form only at
Debuglevel, so a production log level does not pay to serialize it.
Step 5 — React
- A
DataTableover a growable collection uses lazy loading and a paginator rather than rendering every row. - No inline object or array literal passed as a prop: it is a new identity every render and defeats memoization downstream.
useEffectdependencies are correct — neither missing nor over-broad. An over-broad dependency array is a re-run per render, which reads as a correctness bug and behaves as a performance one.- Components over large collections hold stable references or are memoized.
- No
JSON.parse(JSON.stringify(x))deep cloning.
Step 6 — Report
Read and use .cratis/ai/rules/review-reports.md when writing the report.
Keep the performance risk label on each finding:
| Risk | Shared classification |
|---|---|
| High | Blockers: degradation at moderate load requiring correction before merge |
| Medium | Suggestions: degradation under load or as data grows |
| Low | Suggestions: minor inefficiency |
Use the shared verdict vocabulary, not a separate performance verdict. If a scale-dependent degradation must be corrected before merge, classify it as High and state the relevant scale rather than leaving a blocker under Medium.
Say what the finding costs and at what scale. "This is slow" is not actionable; "this scans the whole collection on every page load, so it is fine at hundreds of rows and not at tens of thousands" is. Distinguish measured cost from code-shape inference; use the shared scope line to name unmeasured behavior.
What breaks
- A shape finding is reported as a measurement. Reading code tells you the shape; only running it tells you the cost. Say which one you have.
- The paging advice contradicts the paging skill.
cratis-arc-query-pagingis authoritative on the mechanism. Report the missing paging; do not invent an alternative to it. - A replay cost is judged at development volume. A projection over a hundred seeded events proves nothing about a replay over a production history.
- Every finding is High. The classification is the value; when all findings are urgent, none are.
How it is proven
The build and specifications are green before the report is written; each finding cites the file and line and states the scale at which it bites; and the report says plainly that it reviewed code shape rather than measured behavior, naming anything that would need a benchmark to settle.
04 同仓库更多 Skills
spf13-go
Review Go library APIs, package boundaries, tests, iterators and standard-library choices. Load for broad design or idiom reviews after the repository-owned Go skills.
samber-golang-error-handling
Review Go error creation, wrapping, inspection and logging boundaries. Load when changing caller-visible failures after go-errors-and-context.
samber-golang-context
Design Go context propagation, cancellation, deadlines and request metadata. Load for operation-lifetime changes or context-related leaks after go-errors-and-context.
jetbrains-go-modern-guidelines
Choose version-compatible modern Go syntax and standard-library APIs. Load when modernizing touched Go code after reading go.mod and build constraints.
go-testing
Write and review Go unit, contract, transport, race, fuzz, and deterministic concurrency tests. Use for new behavior, bug fixes, flaky tests, and public API parity evidence.
go-release-modules
Review Go module dependencies, minimum versions, compatibility, semantic labels, release-action tags, and proxy discoverability. Use for release preparation, retractions, and major-version migration planning.