Content
86%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A strong, highly actionable conventions guide: every rule is repo-specific and backed by executable examples, exact paths, and commands, with detail properly externalized to two well-signaled reference files. The only gaps are minor — a few trimmable rationale sentences and the absence of an explicit fix-and-retry loop in the verification workflow.
Suggestions
Trim one-line rationales that restate the rule (e.g. 'Explicit imports make dependencies visible and simplify TypeScript types') and cut 'Key points' bullets that duplicate content in the reference files, linking to the references instead.
Add a feedback loop to 'After Writing Tests': after step 1-3, instruct Claude to fix any failures/warnings found and re-run until clean before committing.
Consider moving the compact 'Notifications Tests (NestJS)' and 'E2E / Playwright Tests' bullet lists into the reference files to further slim the body, keeping only a one-line pointer each.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with repo-specific, non-inferable knowledge (e.g. vi.mock OOM behavior, the fake CASL ability in job workers) and never explains generic testing concepts. However, a few one-line rationales ('Explicit imports make dependencies visible and simplify TypeScript types') and 'Key points' bullets that restate reference-file content could be trimmed, matching the 'minor instances of over-explanation' anchor rather than the every-token-earns-its-place anchor. | 4 / 5 |
Actionability | Copy-paste-ready TypeScript examples (the full setup() pattern with real types), exact file paths (apps/api/test/services/job-queue-harness.ts, apps/api/test/mocks/config-service.mock.ts), exact commands (npx tsc --noEmit, npm run lint -- --quiet), and Good/Bad code contrasts cover the common cases. Fully executable with no pseudocode. | 5 / 5 |
Workflow Clarity | The decision table cleanly sequences 'which test level to write' and the numbered 'After Writing Tests' checklist provides explicit validation checkpoints (run suite, typecheck, lint, review output, coverage). It falls short of the score-5 anchor only because there is no explicit error-recovery loop telling Claude what to do when a verification step fails, matching 'clear sequence with most checkpoints present; minor validation gaps'. | 4 / 5 |
Progressive Disclosure | Both referenced files (@references/frontend-patterns.md, @references/api-patterns.md) exist, are one level deep, and are clearly signaled with a summary of what each contains; the body keeps universal conventions inline while externalizing the bulk pattern detail (345 and 231 lines respectively). Navigation is easy and the split is appropriate to the monorepo's scope. | 5 / 5 |
Total | 18 / 20 Passed |