AGENTS.md · diff

git:20260316.87d43d6 to git:20260322.393dab7

56 added, 3 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

# 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.
+ - Update this file when user feedback adds a durable repo-level instruction that
+ future agents should follow. Update the relevant shared skill files under
+ `.agents/skills/` as well when that feedback changes a reusable workflow,
+ checklist, or decision rule that those skills should teach. Treat feedback as
+ durable when it changes the default workflow, review expectations, naming
+ rules, verification rules, or handoff conventions for future tasks. Do not
+ edit `AGENTS.md` or shared skills for one-off task preferences.
- 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.
+ - If no material guidance changed, do not edit AGENTS files or shared skills.
## 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`.
+ - Shared package import surfaces:
+ - `@langfuse/shared`: client-safe/shared contracts, types, schemas, and
+ reusable utilities
+ - `@langfuse/shared/src/server`: server-only shared services, repositories,
+ queue helpers, logging, ingestion, auth, and runtime helpers
+ - `@langfuse/shared/src/db`: Prisma client singleton plus Prisma types
+ - `@langfuse/shared/src/env`, `@langfuse/shared/encryption`: focused env and
+ encryption helpers
+ - See `packages/shared/AGENTS.md` for the full export map and when to use
+ each entrypoint
+ - Architecture handbook:
+ [langfuse.com/handbook/product-engineering/architecture](https://langfuse.com/handbook/product-engineering/architecture)
+ with source markdown in
+ `../langfuse-docs/content/handbook/product-engineering/architecture.mdx`
+ (GitHub mirror:
+ [architecture.mdx](https://github.com/langfuse/langfuse-docs/blob/4188c1ba453240c90a763a8067ef442d68839323/content/handbook/product-engineering/architecture.mdx#L4))
## 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.
+ - Implement automated tests for every new feature and for material feature
+ behavior changes. If a test is genuinely not feasible, document the reason in
+ the PR description.
- 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`.
+
+ - Commit messages and PR titles must follow Conventional Commits:
+ `type(scope): description` or `type: description`.
+ - Use a lowercase conventional type such as `feat`, `fix`, `docs`, `refactor`,
+ `chore`, or `test`; keep the description concise and imperative.
- PR titles are validated by `.github/workflows/validate-pr-title.yml`.
+ - Reference: https://www.conventionalcommits.org/en/v1.0.0/
- 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.
+ - `CLAUDE.md` is the Claude Code entrypoint for this repo and should stay as a thin shim that points back to this 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.
+ - Codex may create or refine shared skills under `.agents/skills/` when a repeated repo-specific workflow would help future agents. Keep shared skills tool-neutral and scoped to durable guidance.
+ - Shared skill index: [`.agents/skills/README.md`](.agents/skills/README.md)
+ - Shared skills use a short `SKILL.md` entrypoint and should prefer focused `references/` docs and `scripts/` helpers over large compiled guides. Keep any local `AGENTS.md` concise and use it as a router, not a dump of all details.
+ - If a task matches one of the shared skill scopes below, read the linked `SKILL.md` before editing code, then follow its local references as needed:
+ - Backend and API work in `web/src/server/**`, `web/src/pages/api/public/**`, `worker/src/**`, or `packages/shared/src/**`: [`.agents/skills/backend-dev-guidelines/SKILL.md`](.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`](.agents/skills/add-model-price/SKILL.md)
+ - If more than one skill matches, read the minimal set required.
+ - For completed feature branches that need a changelog entry, use [`.claude/agents/changelog-writer.md`](.claude/agents/changelog-writer.md).
## 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/`.