Content
78%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 dense, highly actionable conventions guide: nearly every rule is backed by concrete good/bad code examples and project-specific gotchas Claude could not infer. Its weaknesses are minor verbosity in the SQL section, basic-Java content like immutable collections, and a Reference Files section whose links point to files missing from the bundle.
Suggestions
Ship the five referenced files (clickhouse.md, mysql.md, testing.md, migrations.md, permissions.md) in a references/ directory, or remove the Reference Files section — every link is currently dangling.
Trim or move the extended SQL-construction narrative (the 'Why' paragraph and TOKEN_USAGE example) into a reference file, keeping only the binding-vs-fragment rule table inline.
Drop or compress sections teaching knowledge Claude already has, such as the Immutable Collections (Set.of vs Arrays.asList) example.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bulk is project-specific knowledge Claude cannot know (plural/singular naming tables, StringTemplate leak, SQL construction rules, log format conventions) presented as tight good/bad pairs. Minor over-explanation of basics (e.g. Set.of vs Arrays.asList) and a wordy SQL narrative paragraph keep it below anchor 5's 'every token earns its place'. | 4 / 5 |
Actionability | Nearly every section pairs executable ✅/❌ code with exact identifiers: 'TemplateUtils.newST(QUERY)', '@RequiredArgsConstructor(onConstructor_ = @Inject)', '@Size(max = Project.NAME_MAX_LENGTH, message = "cannot exceed {max} characters")', and named exception classes. The examples are copy-paste adaptable and cover the common cases for each convention. | 5 / 5 |
Workflow Clarity | Mostly declarative conventions rather than a multi-step process, but sections are clearly organized, and the user-named-resources section is a sequenced 6-step checklist with an explicit validation step ('Test create and rename with a max + 1 name (422) and with exactly max (accepted)'). Not 5 because no other workflow offers sequencing with feedback loops; not lower because nothing risky lacks validation. | 4 / 5 |
Progressive Disclosure | The Reference Files section is clearly signaled with one-line descriptions and one-level-deep links, but none of the five cited files (clickhouse.md, mysql.md, testing.md, migrations.md, permissions.md) exist in the bundle — no references/ directory is present. Broken navigation is more than the 'minor organization gaps' of anchor 4, while the inline content itself is well structured above anchor 2's inlining problem. | 3 / 5 |
Total | 16 / 20 Passed |