메뉴
Use when reviewing dbdocs changes (a diff, branch, or PR) for consistency, Python pluggability, design-pattern alignment, the 3-tier bundle-JS contract, complexity/scale, and the generated-SPA UX & accessibility. Produces a severity-graded findings report scoped to this codebase's documented patterns — not a generic lint.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Use when changing how dbdocs assembles or presents the generated single-page-app — the project data dict, the external gzip payload (dbdocs-data.json.gz), the bundled 3-tier vanilla-JS SPA (index.html + assets/js,css,vendor), the React Flow graph bundle (frontend/), the vendored minisearch, or the versioned deploy layout.
Use when reading dbt artifacts or generating ERDs inside dbdocs — parsing manifest.json/catalog.json and producing Mermaid ERDs via the dbterd Python API for the generated Markdown pages.
Use when reviewing the generated dbdocs ERD's UI/UX against a real dbt project — the overview ERD and the model-page "Related ERD". Installs the local build into a target dbt project, generates + serves, drives a headless browser to screenshot both ERD surfaces (light/dark, default/focused), and emits a severity-graded UX findings report. ALWAYS asks for the dbt project path first.
Use when opening a pull request for dbdocs — pushes the current branch and creates a GitHub PR whose body follows .github/PULL_REQUEST_TEMPLATE.md (filled from the actual diff, with the right Type/Area boxes ticked and the checklist verified, not blindly checked). Mirrors the dbdocs-code-review skill's structure.
Use when cutting a release of the dbdocs package to PyPI. The single source of truth for the release procedure — pre-flight, version selection, GitHub Release creation, and post-publish verification.
| name | dbdocs-code-review |
| description | Use when reviewing dbdocs changes (a diff, branch, or PR) for consistency, Python pluggability, design-pattern alignment, the 3-tier bundle-JS contract, complexity/scale, and the generated-SPA UX & accessibility. Produces a severity-graded findings report scoped to this codebase's documented patterns — not a generic lint. |
This is dbdocs' opinionated review: it checks a change against this
codebase's load-bearing patterns, not generic style. The six review dimensions
below are the contract. Read the change, then report findings under each
dimension, severity-graded, with file:line evidence.
Determine what's under review and read only the relevant tiers:
git diff --stat # what changed
git status --short # incl. untracked new files
Consistency, Design patterns, and Complexity / scale apply to every change — Python, bundle JS, CSS, config, docs, tests (Complexity is scoped to the generate path). The other three dimensions are domain-scoped:
dbdocs/**/*.py).dbdocs/site/bundle/assets/{js,css}/**).dbdocs/site/bundle/**) and the React Flow graph (frontend/**).frontend/** (React Flow graph) is the compiled graph app, not the 3-tier
shell — review it as its own app, not against the shell tiers, but it is still
subject to Consistency, Design patterns, Complexity / scale, and
UX & accessibility (e.g. the committed assets/graph/ bundle must be
rebuilt when the source changes, and DAG/ERD work must respect windowing).Always run all six dimension checks; report "none" for a dimension with no findings rather than skipping it.
Authority: .claude/design_patterns.md (patterns + file:line citations) and
.claude/skills/spa-site/SKILL.md (the SPA/data-dict contract). The cited
symbol is authoritative; line numbers drift — grep the symbol.
uv run ruff format --check . && uv run ruff check .
uv run ruff check --select PLC0415 . # no inline imports
uv run pytest --cov=dbdocs --cov-report=term-missing --cov-fail-under=100
A green baseline is table stakes; the review is about what the gates don't catch. Never fix failures during a review unless the user asks.
Does the change look like the code around it, and reuse what already exists?
ruff PLC0415);
no relative imports.try/except — never bare except: /
except Exception. Fail-soft paths log via the singleton logger
(dbdocs.core.log), never a new logger.tests/conftest.py). Flag duplicated blocks and divergent values for the same
concept (e.g. two CSS colors for one status, two constants for one threshold).service accessor called repeatedly) should be cached in a local.New Python surface should extend an established seam, not invent a parallel one.
core/ → extract/ → site/, one-way. extract/
and site/ import from core/, never the reverse. A new extractor lives in
dbdocs/extract/; a feature spanning >2 modules becomes a sub-package
(extract/<feature>/) with a thin __init__.py facade (re-export only —
no implementation) and the impl in named modules (e.g. registry.py,
dimensions/). Cross-module imports use public names (no leading-underscore
symbols imported across module boundaries).register_rule-style decorator/call), discover plugins via the
dbdocs.health_rules entry-point group and/or a config rules_module
dotted path, and keep the built-in baseline restorable (reset_rules). Check:
registration is idempotent; the registry is reset between tests (an autouse
conftest fixture); thresholds/behaviour are config-driven (read from the
dbdocs.yml block via the object, not hardcoded at the call site); a bad plugin
is fail-soft (caught, logged, skipped — never sinks generate).DbDocsConfig loaded from dbdocs.yml;
build-control fields (not display metadata) go in _NON_METADATA_FIELDS; a CLI
override writes back to the config object before ReportBuilder runs (the
--dialect pattern). Document the knob in dbdocs.yml.example.Applies to every change (Python, SPA, CSS, config, docs, tests).
Cross-check the change against the full catalogue in .claude/design_patterns.md
— not just the patterns below. For each pattern the change touches, confirm it
extends the pattern rather than forking it. The patterns span all tiers:
the pipeline-stage layout, the config object, the data dict, artifact loading,
column lineage, graph rendering, the SPA modules, versioned deploy, the click
group, the singleton logger, and the always-built health section. Representative
checks:
ReportBuilder.build_data()'s single dict and is read in the SPA; no second
hand-off channel, no re-inlining the payload into index.html.schema_ gotcha — artifact access goes
through dbdocs/core/artifacts.py; read schema_ (the alias), never .schema
(a bound method) off a parsed node.extract/nodes.py) — columns come
from the manifest (manifest order), catalog only enriches type
case-insensitively; a stale/empty catalog must not drop documented columns.extract/column_lineage.py) —
per-model failures caught/logged/skipped; scope built once per model (not per
column); parallel above _PARALLEL_THRESHOLD via picklable work tuples (never
the Pydantic manifest across the process boundary).frontend/, committed assets/graph/ bundle) —
the DAG windows to a focal neighborhood before layout; over
MAX_UNFOCUSED_DAG_NODES it shows a placeholder. A graph-UI change must rebuild
task frontend:build).site/builder.py) — BUNDLE_DIR resolves
from __file__; generate() does rmtree + copytree for a clean build.
Anything new under bundle/ must be covered by the pyproject.toml artifacts
glob (dbdocs/site/bundle/**/*) or it won't ship in the wheel.site/deploy.py) — plain <version>/ dirs +
versions.json; segment validation against ^[A-Za-z0-9._-]+$. Don't
reintroduce mike/external tooling.artifact-parser for run_results, not the manifest parser); status
enums read via .value..claude/design_patterns.md
must be updated in the same change (new entry + TOC + a concrete file:line
citation). Flag a missing/stale doc update as a finding.The bundled shell SPA (dbdocs/site/bundle/assets/js/) is native ES modules in a
strict one-way ui → service → data. Verify:
data.js loads + normalize()s the payload, defaulting every top-level
key so the upper tiers never null-check the dict shape.service.js is DOM-free — pure domain logic over the normalized dict. No
document, no el(), no DOM reads/writes. Domain derivations (filtering,
grouping, scoring, lookups) belong here, exposed as accessors.ui.js is the only DOM toucher — it renders via el() and reads from
service. Flag domain logic that leaked into ui (it belongs in service) and
any DOM access that leaked into service.window.dbdocsGraph,
MiniSearch, marked); data.js re-exposes the payload on window.dbdocsData
for the graph bundle.assets/css/; the same status/concept uses one color
across pills/badges (don't introduce a divergent value).Applies to every change that touches the generate path (Python and the graph bundle). dbdocs must stay performant on 3000+ model projects — this is a load-bearing product promise (parallel column lineage + windowed graph rendering exist for exactly this). For each new or changed loop, recursion, or data structure, state its complexity in terms of N = #nodes (models+sources+tests) and flag anything worse than the budget below.
What to compute and check:
O(N) or O(N·k) for a
small constant/config k (e.g. #rules, #columns-per-model). Flag:
O(N²) — a nested loop over all nodes (e.g. "for each model, scan all
models/edges"). Almost always avoidable by indexing once (build a
dict/set adjacency up front, then O(1) lookups — see
ManifestGraph._build_adjacency). The health rules are O(N·rules) with O(1)
parents()/children() for this reason.non_physical_chain_depth caches on
_chain_cache; column-lineage builds scope once per model, not per column).RecursionErrors generate on a deep chain. Prefer an
explicit stack + a visited set (cycle guard) over def f(): ... f(parent).ProcessPoolExecutor above _PARALLEL_THRESHOLD; only picklable
work tuples cross the boundary (never the Pydantic manifest/catalog). A new
heavy per-model step should follow this, not run a serial loop.O(N) per node at worst — don't emit
O(N²) data (e.g. a full adjacency matrix). The payload is gzipped + external;
keep per-node records lean.buildDagFlow(data, keepIds)), never lay out all N nodes unfocused.generate (the per-rule try/except in
DimensionAnalyzer.analyze catches RecursionError too).When reviewing, prove it: if a change adds a graph walk or per-model loop and
you're unsure, sketch a worst-case input (a 3000-deep view chain, a 3000-wide
fanout) and reason about whether it stays linear / terminates. Cite the offending
file:line and the input that breaks it.
Scoped to changes that affect the rendered product — the bundled shell SPA
(dbdocs/site/bundle/**: js/, css/, index.html) and the React Flow graph
(frontend/**). dbdocs ships a documentation site people use; a change can be
correct, pattern-aligned, and O(N) yet still ship a page that's unusable by
keyboard, unreadable on a phone, or silently broken on an empty/error state.
Report "none" for a change that doesn't touch the rendered SPA. Cite file:line
and, where it matters, the device/AT (assistive tech) or state that exposes it.
<a href>, <button>, native <details>/<input>) — not a <div>
with an onclick. Tab order is sane; nothing is keyboard-trapped. The DAG/ERD
full-screen, the nav drawer/collapse rail, the copy-link button, the search box
and the tree filter all work without a mouse.focusColumn,
renderHealth's scroll-into-view) move/restore focus sensibly; a focused
element stays visible (don't suppress the focus ring without a replacement).
Opening the mobile drawer should not strand focus behind an overlay.copyLinkButton, full-screen,
nav-toggle/nav-collapse, the search 🔍) carry an accessible name
(aria-label/title/visually-hidden text) — an <span class="ic"> mask glyph
has no text. State toggles expose aria-expanded/aria-pressed; the nav
follows the existing aria-expanded pattern (setNavOpen/setNavCollapsed)..muted text, pills/badges in dark).
Status is never color-only — pass/warn/fail/error carry a text label too
(the health pills/badges do; flag any new color-only signal).<thead>/<th> (the health +
columns tables do); headings nest without skipping levels; target="_blank"
links carry rel="noopener" (already the convention).nav-open vs nav-collapsed) and both
behave; nothing overflows the viewport horizontally.note when run_results.json is absent. A new view that can be empty must say
so, not render blank.#/health?d=…,
#/dag?focus=&rtype=&schema=, ?col=); filter state is written back via
history.replaceState without remounting the graph (the documented
no-hashchange trick). A new shareable view should be reflected in the hash.--bg, --border, --accent, the --status-* palette) — not new
hard-coded hex/px that duplicate an existing token (this overlaps Consistency;
call it under whichever fits, not both).icon() mask + KNOWN_ICONS +
icons.css path (no inline SVG); new surfaces reuse the established
card/pill/badge/scorecard idioms rather than inventing a parallel look.Lead with a one-line verdict + the gate results, then findings grouped by the six
dimensions, severity-graded and each with file:line + a one-line description.
Do not rewrite code in the report — identify, then offer to apply.
**Verdict:** <aligned / needs work> · ruff <ok> · <N> tests <pass> at <X>% coverage
### Consistency
- 🔴/🟡/⚪ `file:line` — <finding>
### Pluggable (Python)
- ...
### Design patterns
- ...
### 3-tier bundle JS
- ...
### Complexity / scale
- 🔴/🟡/⚪ `file:line` — <finding> (state the Big-O in N + the worst-case input)
### UX & accessibility
- 🔴/🟡/⚪ `file:line` — <finding> (name the device/AT or state that exposes it)
- ...
(✓ Verified clean: <dimensions with no findings>)
Severity: 🔴 correctness/contract violation · 🟡 worth fixing (real inconsistency) · ⚪ nit/optional. Behavior-neutral findings are test-safe to apply; say so and offer to apply all, the high-severity subset, or none.