Skip to content

CLAUDE.md

Latest commit

 

History

History
75 lines (49 loc) · 3.51 KB

CLAUDE.md

File metadata and controls

75 lines (49 loc) · 3.51 KB

CLAUDE.md

@AGENTS.md

Quick Reference

For detailed documentation beyond AGENTS.md essentials:

→ docs/KNOWLEDGE_BASE.md - Architecture, code patterns, frontend structure, testing, debugging

Claude-Specific Notes

  • Keep responses concise and action-oriented
  • Ask clarifying questions before changes that alter product behavior
  • Prefer updating shared UI code in js/packages/ui; keep js/app thin
  • Run cd js && pnpm run build before recce server when validating frontend changes

AI Agent Documentation

Use gitignored directories for temporary working documents:

  • docs/plans/ - Implementation plans and design docs
  • docs/tasks/ - Task lists and tracking
  • docs/summaries/ - Status reports and progress updates

Dependency Update Workflow

When asked to "update deps" or "check for updates":

Prerequisites: brew install dependabot + Docker running

  1. Scan: make deps-check (runs Dependabot locally, outputs deps-python.yml and deps-frontend.yml)
  2. Audit: cd js && pnpm audit && pnpm outdated
  3. Present: Group by SECURITY/MAJOR/MINOR with numbered list
  4. Apply: Update root js/package.json; add pnpm.overrides for shared packages
  5. Verify: pnpm install && pnpm lint && pnpm type:check && pnpm test && pnpm build

Packages requiring overrides (exist in multiple package.json): @emotion/react, @mui/material, @tanstack/react-query, @xyflow/react, axios, date-fns, lodash, tailwindcss, typescript, vitest

Publishing @datarecce/ui

When asked to "publish ui" or "release ui package":

  1. Node version: Use nave use $(cat js/.nvmrc) for all commands
  2. Version check: Compare local vs published (npm view @datarecce/ui version)
  3. Verify: Run all quality checks from js/ directory
  4. Publish: cd js/packages/ui && npm publish --access public
  5. Confirm: npm view @datarecce/ui version

Commit and PR Workflow

Commits: Always use --signoff and include a Co-Authored-By: Claude <noreply@anthropic.com> trailer (version pin optional — if included, use the current model)

PRs: Follow .github/PULL_REQUEST_TEMPLATE.md:

  • PR checklist (tests, DCO)
  • Type, description, linked issues
  • Reviewer notes, user-facing changes

MCP Tool Response Contracts

  • MCP tool description = LLM agent contract. Description MUST match actual response format.
  • Prefer additive changes (_meta fields) over modifying existing field types in tool responses.
  • Row count consumers: frontend (int), run.py (int comparison), summary.py (int arithmetic), RowCountDiffResultDiffer (3-format compat), MCP agents (description-guided).
  • summary.py row count gotcha: base/curr can be None (TABLE_NOT_FOUND, PERMISSION_DENIED). Guard with is None check before arithmetic — dict.get(key, 0) does NOT protect when key exists with None value. N/A display includes reason: "N/A (table_not_found)".
  • Format changes to MCP tool responses require both deterministic tests AND BQ/LLM eval to prove agent behavior unchanged.

Frontend Style Conventions

  • Storybook imports: Never import from ui/src internal paths (e.g., ../../../ui/src/...). Always use @datarecce/ui/components or other @datarecce/ui package exports. This keeps the package boundary intact.
  • CSS color format: Use space-separated rgb() syntax: rgb(255 173 21), rgb(0 0 0 / 0.45). Do not use comma-separated legacy format (rgba(0, 0, 0, 0.45)).

Individual Preferences

  • @~/.claude/recce.md