Content
71%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 reference with concrete executable patterns, clear sequencing, checklists, and an excellent anti-pattern table. Its weaknesses are the inlined per-ORM guides that bloat the single file, some routine command explanations Claude already knows, and one non-executable batch-backfill example.
Suggestions
Split the per-ORM sections (Prisma, Drizzle, Django, golang-migrate) into separate reference files (e.g., references/prisma.md) and keep only a one-line pointer plus the non-obvious patterns (custom SQL via --create-only, SeparateDatabaseAndState) in SKILL.md.
Fix the batched backfill example to use a CREATE PROCEDURE with CALL (which permits COMMIT) instead of a DO block, or batch via repeated statements from the migration tool.
Add an explicit post-migration validation loop (e.g., verify row counts / lock status after applying, and what to do on failure) to elevate workflow clarity to a full feedback loop.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and executable with valuable GOOD/BAD annotations and version-specific notes (e.g., "Postgres 11+ is instant, no rewrite"), but the per-ORM workflow sections restate basic commands Claude already knows (e.g., `npx prisma migrate dev`, `python manage.py makemigrations`). This is minor over-explanation that could be trimmed, matching anchor 4 rather than the fully lean anchor 5. | 4 / 5 |
Actionability | Most guidance is copy-paste-ready SQL, bash, and Python covering the common cases (add column, concurrent index, expand-contract rename, backfill, per-ORM workflows). However, the batched backfill `DO $$ ... COMMIT` block is not executable as written — PostgreSQL does not allow COMMIT inside a DO block (that requires a CREATE PROCEDURE) — a minor gap that keeps it below 'fully executable'. | 4 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced: numbered expand-contract steps with a day-by-day timeline, a pre-application safety checklist ("已针对生产数据副本进行测试", "回滚计划已记录"), a 'Verify data consistency' checkpoint, and dirty-state recovery (`migrate ... force VERSION`). It falls short of 5 because there is no explicit validate→fix→retry feedback loop after applying migrations, only implicit checkpoints. | 4 / 5 |
Progressive Disclosure | Sections are well-organized and navigable, but this is a ~330-line single file with four per-ORM guides (Prisma, Drizzle, Django, golang-migrate) fully inlined — content that clearly belongs in separate reference files per the anchor 'content that should be separate is inline'. No bundle files exist, so all detail loads into context upfront; it is not a 2 because the structure itself is genuinely clear. | 3 / 5 |
Total | 15 / 20 Passed |