AGENTS.md · git:20260316.87d43d6 · 2026-03-16 · sha256 7a97c293b1220c31
AGENTS.md git:20260316.87d43d6A
Immutable. This exact content never changes and is served at /api/v1/blob/7a97c293b1220c31.
# Codex Guidelines for Langfuse Langfuse is an open source LLM engineering platform for developing, monitoring, evaluating, and debugging AI applications. Langfuse monorepo guidance for fast, safe code changes. ## Maintenance Contract - `AGENTS.md` is a living document. - Update this file in the same PR when monorepo-level architecture, workflows, dependency boundaries, mandatory verification commands, or release/security processes materially change. - For package-local material changes, update the package-local `AGENTS.md` in the same PR. - If no material guidance changed, do not edit AGENTS files. ## Project Structure & Module Organization ```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 ``` - Package guides: - `web/AGENTS.md` - `worker/AGENTS.md` - `packages/shared/AGENTS.md` - `ee/AGENTS.md` - 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`. ## Build, Test, and Development 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` - Codex environment bootstrap: `bash scripts/codex/setup.sh` - Codex environment maintenance: `bash scripts/codex/maintenance.sh` - Lint all: `pnpm run lint` - Typecheck all: `pnpm run typecheck` / `pnpm tc` - To try running build, always run `pnpm run build:check` and verify that it succeeds. This does not impact running web servers - If you have to rebuild all for testing, run: `pnpm run build` - Full reset/bootstrap (destructive): `pnpm run dx` 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 | ## Coding Style & Naming Conventions - Keep changes scoped; avoid unrelated refactors. - Prefer package-local implementation details in package AGENTS files. - Do not hand-edit generated/build artifacts: - `generated/*` - `web/.next/*` - `web/.next-check/*` - `*/dist/*` - `packages/shared/prisma/generated/*` ## Testing Guidelines - Keep each test independent and parallel-safe. - `web/src/__tests__/server`: avoid `pruneDatabase` calls. - Client tests contain `....clienttest.ts` - When you write a test for a bug or similar, write the test that fails first. Check that it fails. Only then fix the bug. Otherwise, the test is not good! ## Commit & Pull Request Guidelines - 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`. - Include AGENTS.md updates in the same PR when guidance materially changes. - In PR descriptions, list impacted packages and executed verification commands. ## Docs Linking - Public API contract changes must update Fern sources in `fern/apis/**` and regenerated outputs; do not hand-edit `generated/**`. - Use repo-relative file paths in docs and runbooks. - Our docs live in `../langfuse-docs/` which is a different repo. You may always access this. ## Agent-specific Notes - Root `AGENTS.md` is monorepo-level only. - Package-local runbooks, commands, and entry points belong in package `AGENTS.md` files. - Keep guidance DRY: canonicalize to the most specific file. - Repo-owned Codex cloud bootstrap lives in `scripts/codex/setup.sh` and `scripts/codex/maintenance.sh`; contributors still configure the actual environment in the Codex UI. ## Release Channel - Release workflow is managed at root (`pnpm run release`). - Langfuse Cloud deployments are triggered by pushes to `production` (`.github/workflows/deploy.yml`). - Promote `main` to `production` via `.github/workflows/promote-main-to-production.yml` (manual `workflow_dispatch`). - Use `pnpm run release:cloud` for CLI-triggered Cloud promotions with preflight branch/migration checks. - Do not change release/versioning flow without updating this file and impacted package guides. ## GitHub Search - use the github cli `gh search issues` to search github. ## GitHub Issues and Pull Requests - Placeholder: add issue triage and PR hygiene conventions used by maintainers. ## Security and Configuration Tips - Never commit secrets or credentials. - Keep examples in `.env*.example` files in sync with required env vars. - Follow `SECURITY.md` for vulnerability reporting/handling. ## Troubleshooting - Lint/typecheck failures: run `pnpm run lint` and `pnpm run tc`. - Schema/client drift: run `pnpm run db:generate`. - Local infra issues: run `pnpm run infra:dev:up`; use `pnpm run dx` only when destructive reset is intended. ## Git Notes - Do not use destructive git commands (for example `reset --hard`) unless explicitly requested. - Do not revert unrelated working-tree changes. - Keep commits focused and atomic. ## Cursor Rules - Additional folder-specific rules live in `.cursor/rules/`.