Neode Audit
Audit Neo4j codebase usage, detect inefficiencies, and generate optimization recommendations.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up — so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/neode-audit-adam-cowley/— the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
skills/neode-audit, fromgithub.com/adam-cowley/neode(branchmain), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/neode-audit-adam-cowley/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates — they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description — no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the “What this skill does” section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
Audit how a codebase uses neode/Neo4j — inventory every query and CRUD operation, map the graph model, detect N+1s / find-feeders / check-then-create / guard-write pairs / re-read tax / row plumbing, project the after-state, and triage findings into library issues vs adoption tasks vs bugs. Use when asked to audit, inventory, review or reduce Neo4j/OGM usage.
What this skill does
neode-audit — audit runbook
Audit how a codebase uses neode / Neo4j: inventory the queries, map the graph model, detect the inefficiencies mechanically, project the after-state, triage the findings. The audit is read-only — its deliverables are one report document and Linear issues.
API facts come from the generated docs, never from training data: the
neode skill, llms-full.txt and the
per-area pages under docs/agent/. This file is
hand-maintained — the generated outputs regenerate with pnpm docs:agents;
this one you edit.
Phase 0 — scope the data access
- The audit is read-only. It writes exactly two kinds of artifacts: the report document and Linear issues. No source changes, ever — findings become tasks, not edits.
- Exclude the library's own source, node_modules, lockfiles; include app service/domain code and (only if asked) tests.
- Locate: model definition package(s), the raw-Cypher entry points (
db.cypher/writeCypheror equivalents), the connection setup (real driver vs embedded engine), and how the DB handle reaches call sites (context object? singleton?). - Disclose the backend dialect: record which engine the audit's claims were checked against (embedded Relate vs real server) — several behaviours differ (e.g. pattern expressions rejected in RETURN projections on the embedded engine) and every projection inherits that caveat.
Phase 1 — inventory
- Count call sites per file: raw reads, raw writes, and each OGM method
(
create/merge/update/find/all/relate/delete). - List every exported function that touches the DB: CRUD classification (C/R/U/D, note multi-step), one-line purpose, and a query-count note when it runs several (e.g. "5 queries", "N+1 per row").
- Note model registry order and decorators of consequence:
unique/index/@Filter/ cascade / soft-delete.
Phase 2 — graph model
- Extract node labels and relationship types from BOTH the Cypher strings and the model declarations; mark which relationships are declared vs edge-only (written via relate() / matched in raw Cypher only).
- Note self-referential edges and declared-but-unused models.
- Render a mermaid diagram grouped by domain subgraphs; solid arrows = declared, dotted = edge-only.
Phase 3 — mechanical inefficiency scan
Run each detector and record counts with file:line anchors on every finding (unanchored findings waste review time):
- Loop-nested queries —
await cypher(...)/find(...)within a few lines after afor/forEachopener. Classify: per-row enrichment (→ with-specs orIN $idsbatch), per-spec validation loops (→ batchINread), seed loops (→ mergeOn). - Create-paired relates — relate() within ~8 lines after create() → nested-create candidates (NTS-627: pk values relate in the root statement).
- Find-before-relate feeders — a find whose result only feeds relate() → die with nested create.
- Check-then-create probes — existence
MATCH … countbefore create → mergeOn / conditional create (the outcome'screatedflag reports which happened, NTS-630). - Read→validate→write pairs — a read gating a guarded write → single
guard statement (
MATCH … WHERE … SET … RETURN n, zero rows → 404); removes the TOCTOU race. - Write re-read tax — check whether the library re-hydrates writes (FindByIdService or similar); if so every write is ≥2 statements (fixed by RETURN hydration, NTS-633).
- Row plumbing — count
.get('col')calls, inline{ get: … }casts,records[0]scalar probes → rows() / recordTransformer candidates (NTS-632). - Compute-then-write patterns — head-of-chain reads (
ORDER BY … LIMIT 1before create),SET copy = properties(src)clones, derived-stamp follow-up updates → write-time expression candidates (NTS-629). - Quirks — writes executed through the read API, queries missing the
tenancy predicate, deletes without guards (NTS-634's
where+ifExists), missing indexes on hot lookup properties.
Phase 4 — decision rules
- Fold a probe into the main read UNLESS: it is per-request security revalidation (keep); JS-side validation needs more than a predicate (keep separate); folding changes failure semantics (404 vs 403); or ordering/idempotency requires per-iteration queries.
- Convert to eager with-spec UNLESS: JS-side post-filters dominate (reveal
gating, per-row redaction); the read is a variable-length path; it is a
tenant-wide aggregate. Prerequisite: the many-sides must be declared
(
@OneToMany) first — list declaration-only work separately. Respect deliberate modelling (e.g. a primary-owner@OneToOnewith multi-owner reads kept in Cypher). - Always raw Cypher, name them in the report so nobody "fixes" them: GROUP BY aggregates, variable-length walks, reveal/redaction post-filtering, per-request session checks.
- Never recommend folding a hash-chain head read into application JS; that is a write-time-expression candidate (NTS-629).
Phase 5 — projection
- Per-file call-site table: before → after, with the per-issue mechanics that produce each delta.
- Statements-per-key-operation table (today → after) for the hot paths — call sites understate the win.
- Separate three metrics: call sites, statements per operation, round trips (parallel()/batching reduces the third only — NTS-631).
- Mark everything as derived estimates with noise bounds; list what deliberately does not change.
Phase 6 — triage & deliverable
- Classify every finding: library gap (file upstream: problem, proposal, acceptance ideas) / adoption task (feature exists, app hasn't used it) / app bug (unscoped reads, read-API writes, missing indexes, non-idempotent seeds).
- Tag each finding quick win vs structural (guard-updates and indexes are quick wins; with-spec conversions are structural — the report should let the reader start with the quick wins).
- Write ONE report document mirroring this layout: 1 architecture · 2 per-module CRUD · 3 labels+rels · 4 counts · 5 notable patterns · 6 graph-model diagram · 7 follow-ups in the three buckets · 8 projected before/after. End with the exact paths written.
- Emit the counts machine-readably too (a JSON sidecar: per-file/method counts, detector hits) — so a re-run of the audit after changes is diff-able and shows what actually moved. The report is a baseline, not a one-off.
Phase 7 — review artifacts (produce these for every library gap filed)
- Expected-Cypher snapshots: for each proposal, render the target Cypher as it should read after implementation (before/after pairs where the change rewrites a statement). Reviewers argue with Cypher, not prose. Label them review targets, not contracts — real aliasing/WITH-bridging may differ.
- Statement-count meter: the library emits QUERY_EXECUTED per statement —
propose/ship a test helper (
expectStatements(runner, n)) and assert it in every acceptance idea that claims "reduces queries". One small file; the objective meter for the whole issue family. - Spike protocol: any design with an unresolved risk gets a spike BEFORE implementation, or the issue is labelled needs-spike. Typical spike triggers: atomicity across sessions (two-phase commit), hydration from RETURN on ON CREATE/ON MATCH branches, engine-dialect support for write-side expressions.
- Evidence bundle: the report lives in the consumer's repo — maintainers can't see it. Produce a sanitized excerpt (counts tables, detector hits, worked example) attachable to the issues or a gist.
- Reference conversion: for adoption tasks, convert ONE function end-to-end (declarations + eager read + test reshape) as the pattern PR the rest follows.
Detection commands
Adapt <db> / entry-point names to the consumer before running:
# N+1 detector: query sites inside loop bodies
grep -rn -B6 "await <db>.cypher(" --include='*.ts' src | grep -E "for ?\(|forEach"
# proximity pairs (create→relate, find→relate): run the python proximity pass shown in the worked example's report
Agent notes
Worked example (the consumer audit that produced this runbook): a repo of ~340 raw + ~360 OGM call sites yielded 118 relate sites of which 87 create-paired; 49 of 122 find sites were relate-feeders; 33 loop-nested query sites; ~70–90 DB-hitting auth probes; ~270 lines of row plumbing; read projection 277 → ~232 conservative / ~170 with the full pass.
Related library issues: NTS-627 (nested create), NTS-628 (edge properties), NTS-629 (write-time expressions), NTS-630 (mergeOn summary), NTS-631 (parallel), NTS-632 (rows/recordTransformer), NTS-633 (RETURN hydration), NTS-634 (single-statement deletes).
Related skills
Generative Code Art
anthropics
Create algorithmic art with p5.js using randomness and interactive parameters.
Poster & Visual Design
anthropics
Create original posters and visual art in PNG and PDF formats.
Claude API Helper
anthropics
Build, debug, and optimize Claude API applications with caching and model migration support.
MCP Server Builder
anthropics
Build protocol servers that connect language models to external APIs and services.