160 lines
11 KiB
Markdown
160 lines
11 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with this repository.
|
|
|
|
## Purpose and status
|
|
|
|
This repository is the Python-first AI Platform workspace. Lead Scoring is the first service; related systems are `DotB-Omni`, `lead-scoring-agent`, and `aihub` under `/home/hung/code/dotb_workspace/`.
|
|
|
|
The repository contains specifications, project documentation, and the initialized baseline for the Lead Scoring service (`src/lead_scoring/`).
|
|
|
|
Before implementing or changing Lead Scoring Customer Pilot behavior, read:
|
|
|
|
- `docs/specs/lead-scoring-customer-pilot.md`: authoritative product behavior, scope, invariants, acceptance boundaries, and cross-service ownership.
|
|
- `stack.md`: technology decisions, candidates, evidence, and unresolved stack questions. It does not override the approved specification.
|
|
|
|
The DotB Vault RFC, initial brief, Grill Brief, legacy reports, drafts, and agent messages are historical/supporting context rather than implementation authority. Exact wire formats become authoritative through released Pydantic models, generated OpenAPI/JSON Schemas, and shared fixtures.
|
|
|
|
## Communication
|
|
|
|
- Keep responses short, specific, and decision-oriented.
|
|
- Put the decision or conclusion first, followed by only the evidence and next action needed.
|
|
- Keep the main context high-signal. Put raw logs, scratch data, and long intermediate reports in `/tmp/` or the appropriate durable document.
|
|
- Use lists and compact structure when they make the result easier to scan.
|
|
- State assumptions, unresolved decisions, and verification status explicitly.
|
|
|
|
## Writing
|
|
|
|
- Write directly and precisely. Avoid buzzwords, filler, and repeated explanations.
|
|
- Comments explain intent, invariants, trade-offs, or non-obvious constraints, not syntax or line-by-line behavior.
|
|
- Do not add speculative documentation, abstractions, or metadata that the repository does not need.
|
|
- Do not use emoji or em dashes in new prose, comments, or reports. Preserve emoji and punctuation that are part of existing paths or quoted source text.
|
|
|
|
## Delegation
|
|
|
|
- Use the configured `researcher` agent for read-only exploration and research.
|
|
- Use the configured `primary-engineer` agent for implementation, debugging, and multi-step engineering work. If it is unavailable, use the narrowest suitable implementation agent.
|
|
- Implementation agents own TDD tests; use the `tester` agent for independent verification before completion.
|
|
- Delegate context-heavy or tool-heavy work with a clear scope, completion criteria, and evidence requirements.
|
|
- Require condensed handoffs containing conclusions, changed paths, verification, and uncertainty. Do not paste raw logs into the main context.
|
|
- The main context retains final decisions and integration responsibility. Agent messages are evidence, not user approval.
|
|
|
|
## Project knowledge
|
|
|
|
- `CLAUDE.md` is the project map for conventions, verified commands, boundaries, and gotchas.
|
|
- `docs/specs/lead-scoring-customer-pilot.md` is the approved source of truth for Lead Scoring Customer Pilot product behavior and build boundaries.
|
|
- `stack.md` is the primary record for technology decisions and unresolved stack questions; it cannot override the approved spec.
|
|
- `docs/` contains shared project knowledge intended for version control.
|
|
- `/tmp/` is for scratch data, raw logs, and temporary handoffs.
|
|
- Released Pydantic models, generated OpenAPI/JSON Schemas, tests, and shared fixtures become the exact executable contract when they exist.
|
|
|
|
## Documentation
|
|
|
|
- Put temporary reports, raw logs, and scratch material in `/tmp/`.
|
|
- Put durable team knowledge in `docs/` and include it in version control.
|
|
- Use `vault/` only for durable project-local knowledge that must not be committed.
|
|
- New durable Markdown documents under `docs/` or `vault/` use minimal YAML frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
title: Document title
|
|
description: A short description of what the document contains and when it is useful.
|
|
status: draft
|
|
tags: []
|
|
---
|
|
```
|
|
|
|
- `title` and `description` are required. For governed specs, `status` may be `draft`, `review_ready`, `approved`, or `deprecated`; other existing document schemas keep their established status vocabulary. `tags` is optional.
|
|
- Do not add metadata that Git, the filesystem, or existing tooling can derive.
|
|
- Preserve the format and metadata schema of existing documents. Do not add frontmatter, reformat, move, or normalize existing files unless the task explicitly requests migration.
|
|
- `CLAUDE.md`, README files, and files with an existing schema keep their established format.
|
|
|
|
## Repository structure
|
|
|
|
- `src/lead_scoring/`: Lead Scoring production service package and CLI tools.
|
|
- `alembic/`: database migrations for PostgreSQL.
|
|
- `tests/`: test suite including health check, OpenAPI CLI, and migration lifecycle.
|
|
- `docs/specs/lead-scoring-customer-pilot.md`: approved Lead Scoring Customer Pilot specification.
|
|
- `docs/`: durable shared project documentation.
|
|
- `stack.md`: technology decisions and unresolved stack questions.
|
|
- `.claude/settings.json`: project hook configuration.
|
|
- `.claude/hooks/post-edit-check.py`: Python-only PostToolUse feedback hook.
|
|
|
|
## Product and frontend boundary
|
|
|
|
The frontend boundary is approved for Customer Pilot: DotB-Omni owns all customer-facing Lead Scoring configuration and HITL UI. AI Platform may provide only an internal Dev Console for fixtures, contract testing, failure testing, and allowlisted integration verification; it must not duplicate Omni business UI.
|
|
|
|
When the internal Dev Console is implemented:
|
|
|
|
- Use Svelte 5 and TypeScript with Bun, Vite, and Vitest. Add SvelteKit only when routing, SSR, or deployment requires it.
|
|
- Generate types from backend OpenAPI and consume them through `openapi-fetch`.
|
|
- Keep shared transport concerns such as authentication and error handling outside generated code.
|
|
- Use the official Svelte tooling, including `@sveltejs/mcp` autofixer feedback and `svelte-check`.
|
|
- Use Playwright only for important end-to-end user flows.
|
|
|
|
TypeScript 7 native compiler and language server are pilot candidates, not the adopted project default. Test them project-locally before changing global runtimes or the shared `mcpls` configuration.
|
|
|
|
## Engineering principles
|
|
|
|
- Follow YAGNI. Implement only what the current requirement needs; do not add speculative abstractions, extension points, compatibility layers, or infrastructure.
|
|
- Prefer the simplest design that preserves clear boundaries and can be changed safely.
|
|
- Reuse the standard library and established, actively maintained packages when they reduce code and operational burden. Avoid dependencies for trivial behavior.
|
|
- Keep code explicit. Use precise names, short control flow, and direct data transformations. Avoid cleverness, hidden side effects, global mutable state, and premature optimization.
|
|
- Prefer composition over inheritance and functions over classes. Introduce a class only when state, lifecycle, or a framework contract genuinely requires one.
|
|
- Keep a functional core with side effects at the boundaries. Isolate I/O, persistence, network calls, clocks, and environment access.
|
|
- Organize modules by capability or domain responsibility, not by arbitrary technical layers.
|
|
- Avoid wrappers that only rename another API. Every abstraction must remove meaningful complexity or enforce a real boundary.
|
|
- Preserve one clear source of truth for contracts, configuration, and domain rules.
|
|
|
|
## AI-native code
|
|
|
|
Write code that humans and coding agents can understand with minimal hidden context:
|
|
|
|
- Make dependencies, inputs, outputs, errors, and side effects explicit.
|
|
- Use typed, stable contracts at module and service boundaries.
|
|
- Keep related implementation and tests easy to locate.
|
|
- Prefer deterministic behavior and small composable functions.
|
|
- Document decisions and non-obvious constraints, not syntax or line-by-line behavior.
|
|
- Match existing conventions before introducing a new pattern.
|
|
- Make the smallest coherent change and remove superseded code instead of leaving parallel implementations.
|
|
|
|
## Verified commands
|
|
|
|
- `uv sync`: sync workspace dependencies and environment.
|
|
- `uv run pytest`: run pytest test suite against Python 3.13.
|
|
- `uv run ruff check src tests`: run lint checks across source and tests.
|
|
- `uv run ruff format --check src tests`: check code formatting.
|
|
- `uv run pyright`: run Pyright static type checker.
|
|
- `uv run ty check`: run project-local ty type checker.
|
|
- `uv run generate-openapi`: deterministically generate root `openapi.json`.
|
|
- `uv run generate-openapi --check`: verify that `openapi.json` is present and matches the current backend contract.
|
|
- `uv run generate-webhook-contract`: deterministically generate terminal webhook contract pack.
|
|
- `uv run generate-webhook-contract --check`: verify that webhook contract pack is present and matches current models.
|
|
- `uv run generate-polling-contract`: deterministically generate scoring run polling contract pack.
|
|
- `uv run generate-polling-contract --check`: verify that polling contract pack is present and matches current models.
|
|
- `uv run alembic upgrade head`: apply database migrations up to head.
|
|
- `uv run alembic downgrade base`: revert all database migrations.
|
|
|
|
## Deterministic generation
|
|
|
|
- When a verified project generator exists, use it instead of manually editing derived files.
|
|
- Treat OpenAPI output and generated frontend types as derived artifacts. Regenerate them from the backend contract and require the authoritative verification command to detect drift.
|
|
- Do not edit generated files manually unless the project workflow explicitly requires it.
|
|
|
|
## Safety and scope
|
|
|
|
- Inspect a path before overwriting or deleting it. Preserve existing configuration, documentation, code, and data unless the task explicitly authorizes removal or migration.
|
|
- Do not expose secrets in logs, reports, handoffs, or generated artifacts.
|
|
- Do not install packages, modify system configuration, or create permissions and background services without explicit approval.
|
|
- Bootstrap production code only after the relevant product and implementation decision. Customer-facing Lead Scoring UI remains owned by DotB-Omni.
|
|
|
|
## Tooling and verification gotchas
|
|
|
|
- Generated OpenAPI and frontend build output must remain covered by the existing ignore policy and should not be edited manually.
|
|
- The project PostToolUse hook is configured in `.claude/settings.json` for `Write` and `Edit`. It currently handles Python files only and invokes the existing `ruff` and `ty` tools. Preserve the pre-existing working-tree modification to `.claude/hooks/post-edit-check.py` unless explicitly asked to change or reset it.
|
|
- Do not modify `/etc`, package-manager state, system services, drivers, kernel settings, global Node/TypeScript versions, or the shared `mcpls` configuration as part of repository work unless explicitly approved.
|
|
|
|
## Quality of life
|
|
|
|
Pyright LSP is available for semantic navigation. Use it for definitions, references, hover types, document and workspace symbols, and call hierarchy; then read the relevant implementation to understand business rules and side effects.
|