langfuse/langfuse

# Agent Guidelines for Langfuse

This is the canonical root agent guide for the repo. The root `AGENTS.md`
should remain only as a discovery symlink so tools that require that filename
continue to work while `.agents/` stays the source of truth.

Langfuse is an open source LLM engineering platform for developing, monitoring,
evaluating, and debugging AI applications.

## Maintenance Contract

- `AGENTS.md` is a living document.
- Keep this file concise and router-like. Push narrow or conditional workflows
  into package-local `AGENTS.md` files or shared skills under `.agents/skills/`.
- Update this file in the same PR when monorepo-level architecture, workflows,
  dependency boundaries, mandatory verification commands, or release/security
  processes materially change.
- Update this file and the relevant shared skills when user feedback introduces
  a durable repo-level default for future agents. Do not edit this file for
  one-off task preferences.
- For package-local material changes, update the nearest package `AGENTS.md` in
  the same PR.

## Start Here By Task

- Repo-wide agent setup, `.agents/**`, provider shims, or MCP/bootstrap config:
  `.agents/README.md`,
  `.agents/skills/agent-setup-maintenance/SKILL.md`
- Langfuse Cloud cost structure, infra spend, AWS/ClickHouse cost splits, or
  Metabase cost marts:
  `.agents/skills/analyze-cloud-costs/SKILL.md`
- Backend/API work in `web/src/server/**`, `web/src/pages/api/public/**`,
  `worker/src/**`, or `packages/shared/src/**`:
  `.agents/skills/backend-dev-guidelines/SKILL.md`
- Model pricing work in `worker/src/constants/default-model-prices.json`,
  `packages/shared/src/server/llm/types.ts`, or related pricing files:
  `.agents/skills/add-model-price/SKILL.md`
- Code review tasks:
  `.agents/skills/code-review/SKILL.md`
- Debugging a Linear issue, GitHub issue, or incident report using Datadog
  (APM, logs, metrics) to establish a root cause:
  `.agents/skills/debug-issue-with-datadog/SKILL.md`
- Measured bug or regression evidence that needs Linear deduplication, evidence
  comments, or Triage bug issue creation:
  `.agents/skills/linear-bug-triage/SKILL.md`
- Proactive production regression sweeps across Datadog errors, logs, spans, and
  API latency with Linear handoff:
  `.agents/skills/detect-prod-regressions/SKILL.md`
- Changelog drafting for completed feature branches:
  `.agents/skills/changelog-writing/SKILL.md`
- ClickHouse schema/query review:
  `.agents/skills/clickhouse-best-practices/SKILL.md`
- Monorepo/Turbo task graph changes:
  `.agents/skills/turborepo/SKILL.md`
- pnpm dependency upgrades, package-version bumps, or `minimumReleaseAgeExclude`
  decisions in `pnpm-workspace.yaml`:
  `.agents/skills/pnpm-upgrade-package/SKILL.md`
- User-visible frontend changes, Playwright review, or browser signoff:
  `.agents/skills/frontend-browser-review/SKILL.md`
- Web UI and frontend entry points:
  `web/AGENTS.md`
- Worker queues and processors:
  `worker/AGENTS.md`
- Shared contracts, exports, schema, and migrations:
  `packages/shared/AGENTS.md`
- EE-only work:
  `ee/AGENTS.md`

Read the minimal set required for the task. More-specific package guides and
shared skills take precedence over this root file for their scoped areas.

## Project Structure

```text
langfuse/
├─ web/                     # Next.js app (UI + tRPC + public REST)
├─ worker/                  # Queue consumers and background processing
├─ packages/shared/         # Shared domain, DB, queue contracts, repositories
├─ ee/                      # Enterprise package consumed by web
├─ generated/               # Generated API clients (do not hand-edit)
├─ fern/                    # API definition sources
└─ scripts/                 # Repo scripts
```

- Dependency direction:
  - `web` -> `@langfuse/shared`, `@langfuse/ee`
  - `worker` -> `@langfuse/shared`
  - `@langfuse/ee` -> `@langfuse/shared`
  - `@langfuse/shared` -> no imports from `web`, `worker`, or `ee`
- Queue payload schemas and queue-name contracts are owned by
  `packages/shared/src/server/queues.ts`.
- High-signal shared entry points:
  - Domain models: `packages/shared/src/domain/{observations,traces,scores}.ts`
  - Postgres schema: `packages/shared/prisma/schema.prisma`
  - ClickHouse migrations:
    `packages/shared/clickhouse/migrations/{clustered,unclustered}/*.sql`
- Architecture handbook:
  [langfuse.com/handbook/product-engineering/architecture](https://langfuse.com/handbook/product-engineering/architecture)
  with source markdown in the sibling docs checkout at
  `../langfuse-docs/content/handbook/product-engineering/architecture.mdx`

## Core Commands

- Install deps: `pnpm install`
- Dev all packages: `pnpm run dev`
- Dev web only: `pnpm run dev:web`
- Dev worker only: `pnpm run dev:worker`
- Lint all: `pnpm run lint`
- Typecheck all: `pnpm run typecheck` / `pnpm tc`
- Build check: `pnpm run build:check`
- Full build: `pnpm run build`
- Full reset/bootstrap (destructive): `pnpm run dx`
- Environment/worktree bootstrap: `bash scripts/codex/setup.sh`
- Environment/worktree maintenance: `bash scripts/codex/maintenance.sh`
- Install Playwright Chromium for agent browser review: `pnpm run playwright:install`

Minimum verification matrix:

| Change scope | Minimum verification |
| --- | --- |
| `web/**` only | `pnpm --filter web run lint` + targeted web tests |
| `worker/**` only | `pnpm --filter worker run lint` + targeted worker tests |
| `packages/shared/**` (non-schema) | `pnpm --filter @langfuse/shared run lint` + one targeted web check + one targeted worker check |
| `packages/shared/prisma/**` or `packages/shared/clickhouse/**` | `pnpm --filter @langfuse/shared run lint` + `pnpm run db:generate` + targeted web/worker regressions |
| Public API contract (`web/src/pages/api/public/**`, `web/src/features/public-api/types/**`, `fern/apis/**`) | web lint + targeted server API tests + Fern update/regeneration; never hand-edit `generated/**` |
| Cross-package refactor (`web` + `worker` + `shared`) | `pnpm run lint` + `pnpm run typecheck` + targeted tests per impacted package |

## Repo Rules

- Keep changes scoped; avoid unrelated refactors.
- Prefer package-local implementation details in package `AGENTS.md` files.
- Do not hand-edit generated/build artifacts:
  - `generated/*`
  - `web/.next/*`
  - `web/.next-check/*`
  - `*/dist/*`
  - `packages/shared/prisma/generated/*`
- Public API contract changes must update Fern sources in `fern/apis/**` and
  regenerated outputs. Never hand-edit `generated/**`.
- Before adding constants, value lists, or display mappings, search for an
  existing owner and reuse or extend that source of truth.
- Keep tests independent and parallel-safe.
- For bug fixes, write the failing test first, confirm it fails, then fix the
  bug.
- For user-visible frontend changes in `web/**`, review the affected flow in a
  real browser with the Playwright MCP server before signoff. Use
  `.agents/skills/frontend-browser-review/SKILL.md` and `web/AGENTS.md` for the
  browser-review loop.
- Never commit secrets or credentials. Keep `.env*.example` files in sync with
  required env vars.

## Shared Agent Setup

- `.agents/AGENTS.md` is the canonical root guide.
- Root `AGENTS.md` is a symlink to `.agents/AGENTS.md`.
- Root `CLAUDE.md` is a compatibility symlink to `AGENTS.md`.
- Shared agent/tool config lives in `.agents/config.json` and shared skills
  live in `.agents/skills/`.
- Project-scoped provider discovery files are generated local artifacts. Edit
  the canonical files under `.agents/` instead of editing generated tool
  directories by hand.
- If you change `.agents/config.json`, `.agents/skills/**`, or the
  shim-generation workflow, run:
  - `pnpm run agents:sync`
  - `pnpm run agents:check`
- Do not commit generated provider config or shim outputs under `.claude/`,
  `.cursor/`, `.codex/`, `.vscode/`, or `.mcp.json`.
- Durable cross-tool guidance belongs in root/package `AGENTS.md` files or
  `.agents/skills/**`, not only in tool-specific config directories.

## Commit, PR, and Release Rules

- Commit messages and PR titles must follow Conventional Commits:
  `type(scope): description` or `type: description`.
- PR titles are validated by `.github/workflows/validate-pr-title.yml`.
- In PR descriptions, list impacted packages and executed verification commands.
- Release workflow is managed at root with `pnpm run release`.
- Promote `main` to `production` via
  `.github/workflows/promote-main-to-production.yml` or
  `pnpm run release:cloud`.
- Do not change release/versioning flow without updating this file and impacted
  package guides.

## Git and Tooling Notes

- Use `gh search issues` for GitHub issue search.
- Do not use destructive git commands such as `reset --hard` unless explicitly
  requested.
- Do not revert unrelated working-tree changes.
- Keep commits focused and atomic.
- Remaining `.cursor/rules/*.mdc` files should stay thin wrappers around shared
  docs or skills rather than owning durable repo guidance directly.