Prisma Repository – Agent Field Notes

Meta note: This is the primary agent knowledge base file. CLAUDE.md and GEMINI.md are symlinks to this file—always edit AGENTS.md directly. When learning something new about the codebase that would help with future tasks, update this file immediately.

• Repository scope: Monorepo for Prisma ORM, CLI, client, tests, etc. Many packages use TypeScript, Rust and WebAssembly (via engines), TSX, and Jest; automation relies on pnpm. Expect large fixture directories and generated files.

• Workspace layout: Managed via pnpm workspaces and Turborepo (turbo.json). Node ^20.19 || ^22.12 || >=24.0 and pnpm >=10.15 <11 are required (see root package.json). Top-level scripts (pnpm build, pnpm dev, pnpm test) delegate into scripts/ci/publish.ts; package-specific commands run with pnpm --filter @prisma/<pkg> <script>. Turborepo caches builds; run pnpm build from root to build all packages in dependency order.

• Key packages: packages/cli (Prisma CLI entry point), packages/migrate (migrate/db namespace + fixtures), packages/client (client runtime), packages/client-generator-ts (new prisma-client generator), packages/client-generator-js (traditional prisma-client-js generator), packages/client-generator-registry (generator registry for managing generators), packages/client-engine-runtime (the core part of the new Rust binary free client based on Wasm query compiler, used by ClientEngine class in packages/client), packages/client-common (shared client utilities), packages/client-runtime-utils (utility types and singletons for Prisma Client), packages/config (PrismaConfigInternal + loader), packages/internals (shared CLI + engine glue), packages/engines (Rust binaries download wrapper), packages/integration-tests (matrix suites), packages/query-plan-executor (standalone query plan executor service for Prisma Accelerate), packages/credentials-store (credential storage utilities), sqlcommenter packages under packages/sqlcommenter*, and numerous driver adapters under packages/adapter-*.

• Driver adapters & runtimes: packages/bundled-js-drivers plus the adapter-* packages ship JS driver adapters: adapter-pg, adapter-neon, adapter-libsql, adapter-planetscale, adapter-d1, adapter-better-sqlite3, adapter-mssql, adapter-mariadb, adapter-ppg (Prisma Postgres Serverless). These are built on helpers in driver-adapter-utils; migrate/client fixtures exercise them, so adapter changes typically require fixture/test updates. CI tests driver adapters with flavors: js_pg, js_neon, js_libsql, js_planetscale, js_d1, js_better_sqlite3, js_mssql, js_mariadb, js_pg_cockroachdb.

• Build & tooling: Typescript-first repo with WASM/Rust assets (downloaded by @prisma/engines). Multiple tsconfig.* drive bundle vs runtime builds. Lint via pnpm lint, format via pnpm format. Maintenance scripts live in scripts/ (e.g. bump-engines.ts, bench.ts, ci/publish.ts orchestrates build/test/publish flows). Build configuration uses esbuild via helpers/compile/build.ts with configs in helpers/compile/configs.ts. Most packages use bundledConfig which bundles to both CJS and ESM with type declarations.

• Benchmarking: Comprehensive performance benchmarks using Benchmark.js with CodSpeed integration. See docs/benchmarking.md for full documentation. Key commands:

  • pnpm bench - Run all benchmarks (outputs to output.txt)
  • pnpm bench <pattern> - Run benchmarks matching pattern
  • Benchmark locations:
    • End-to-end query performance: packages/client/src/__tests__/benchmarks/query-performance/query-performance.bench.ts
    • Query compilation: packages/client/src/__tests__/benchmarks/query-performance/compilation.bench.ts
    • Query interpreter/data mapper: packages/client-engine-runtime/bench/interpreter.bench.ts
    • Client generation: packages/client/src/__tests__/benchmarks/huge-schema/, packages/client/src/__tests__/benchmarks/lots-of-relations/
  • Benchmarks run automatically on CI via .github/workflows/benchmark.yml; CodSpeed tracks performance over time and alerts on >100% regression.

• Testing & databases: TESTING.md covers Jest/Vitest usage. Most suites run as pnpm --filter @prisma/<pkg> test <pattern>. DB-backed tests expect .db.env and Docker services from docker/docker-compose.yml (docker compose up -d). Client functional tests sit in packages/client/tests/functional—run them via pnpm --filter @prisma/client test:functional (with typechecking) or pnpm --filter @prisma/client test:functional:code (code only); helpers/functional-test/run-tests.ts documents CLI flags to target providers, drivers, etc. Client e2e suites require a fresh pnpm build at repo root, then pnpm --filter @prisma/client test:e2e --verbose --runInBand. The legacy pnpm --filter @prisma/client test command primarily runs the older Jest unit tests plus tsd type checks. Migrate CLI suites live in packages/migrate/src/__tests__, the CLI runs both Jest (legacy suites) and Vitest (new subcommand coverage) via pnpm --filter prisma test, and end-to-end coverage lives in packages/integration-tests.

• Client functional tests structure:

  • Each test lives in its own folder under packages/client/tests/functional/ (or issues/ for regression tests).
  • Required files: _matrix.ts (test configurations), test.ts or tests.ts (test code), prisma/_schema.ts (schema template).
  • _matrix.ts defines provider/adapter combinations using defineMatrix(() => [[{provider: Providers.POSTGRESQL}, ...]]).
  • prisma/_schema.ts exports testMatrix.setupSchema(({ provider }) => ...) returning a Prisma schema string.
  • Test file uses testMatrix.setupTestSuite(() => { test(...) }, { optOut: { from: [...], reason: '...' } }).
  • Run specific adapter: pnpm --filter @prisma/client test:functional:code --adapter js_pg <pattern> (adapters: js_pg, js_neon, js_libsql, js_planetscale, js_d1, js_better_sqlite3, js_mssql, js_mariadb, js_pg_cockroachdb).
  • For error assertions, use result.name === 'PrismaClientKnownRequestError' and result.code (not instanceof).
  • Use idForProvider(provider) from _utils/idForProvider for portable ID field definitions.

• Docs & references: ARCHITECTURE.md contains dependency graphs (requires GraphViz to regenerate), docker/README.md explains local DB setup, docs/benchmarking.md covers performance benchmarking, examples/ provides sample apps, and sandbox/ hosts debugging helpers like the DMMF explorer.

• Client architecture (Prisma 7):

  • ClientEngine in packages/client/src/runtime/core/engines/client/ orchestrates query execution using Wasm query compiler.
  • Two executor implementations: LocalExecutor (driver adapters, direct DB) and RemoteExecutor (Accelerate/Data Proxy).
  • QueryInterpreter class in packages/client-engine-runtime/src/interpreter/query-interpreter.ts executes query plans against SqlQueryable (driver adapter interface).
  • Query flow: PrismaClient → ClientEngine.request() → query compiler → executor.execute() → QueryInterpreter.run() → driver adapter.
  • ExecutePlanParams interface in packages/client/src/runtime/core/engines/client/Executor.ts defines what's passed through the execution chain.
  • TransactionManager in packages/client-engine-runtime/src/transaction-manager/transaction-manager.ts owns interactive transaction IDs and implements nested transactions using savepoints. Savepoint SQL is provider-specific (e.g. PostgreSQL uses ROLLBACK TO SAVEPOINT <name>, MySQL/SQLite use ROLLBACK TO <name>, SQL Server uses SAVE TRANSACTION <name> / ROLLBACK TRANSACTION <name> and has no release statement).
  • Transaction in packages/driver-adapter-utils models savepoint behavior as async methods (createSavepoint, rollbackToSavepoint, optional releaseSavepoint) instead of returning SQL via savepoint(action, name). TransactionManager expects adapter methods for savepoints and does not synthesize provider fallback SQL.
  • Fluent API dataPath is built in packages/client/src/runtime/core/model/applyFluent.ts by appending ['select', <relationName>] on each hop; runtime unpacking in packages/client/src/runtime/RequestHandler.ts currently strips 'select'/'include' segments before deepGet.
  • In extension context resolution, dataPath should be interpreted as selector/field pairs (select|include, relation field). Do not strip by raw string value or relation fields literally named select/include get dropped.

• Adding PrismaClient constructor options:

  • Runtime types: PrismaClientOptions, PrismaClientBaseOptions, PrismaClientOptionsWithAdapter, PrismaClientOptionsWithAccelerateUrl in packages/client/src/runtime/getPrismaClient.ts. PrismaClientOptions is a discriminated union (PrismaClientOptionsWithAccelerateUrl | PrismaClientOptionsWithAdapter) where each branch is PrismaClientBaseOptions & { ... discriminator }. Avoid going back to the older (A | B) & C shape: TypeScript reports errors against the named branches with the new layout (not assignable to type 'PrismaClientOptionsWithAccelerateUrl') instead of expanding anonymous types like { accelerateUrl: string; adapter?: never; } & PrismaClientBaseOptions.
  • Validation: packages/client/src/runtime/utils/validatePrismaClientOptions.ts (add to knownProperties array and validators object).
  • Engine config: EngineConfig interface in packages/client/src/runtime/core/engines/common/Engine.ts.
  • Generated types: Update both packages/client-generator-js/src/TSClient/PrismaClient.ts (buildClientOptions method) and packages/client-generator-ts/src/TSClient/file-generators/PrismaNamespaceFile.ts (buildClientOptions function). The TS generator mirrors the runtime layout, emitting four exported types (PrismaClientBaseOptions, PrismaClientOptionsWithAdapter, PrismaClientOptionsWithAccelerateUrl, PrismaClientOptions); the JS generator keeps a single flat PrismaClientOptions interface for legacy compatibility.
  • Use @prisma/ts-builders for generating TypeScript type declarations.
  • Current known options: errorFormat, adapter, accelerateUrl, log, transactionOptions, omit, comments, __internal.
  • The generated constructor parameter type is Prisma.PrismaClientConstructorArgs<Options> (defined in packages/client-generator-js/src/TSClient/common.ts for the JS generator, and emitted by packages/client-generator-ts/src/TSClient/file-generators/PrismaNamespaceFile.ts for the TS generator). It resolves to a plain PrismaClientOptions when Options defaults to PrismaClientOptions (the case when the user passes nothing or {}), and falls back to Subset<Options, PrismaClientOptions> otherwise. This keeps the "missing adapter" TypeScript error readable (not assignable to parameter of type 'PrismaClientOptions' instead of Subset<...>) while still rejecting unknown properties at the type level for the literal-argument case.
  • Union order matters. PrismaClientOptions lists PrismaClientOptionsWithAccelerateUrl first and PrismaClientOptionsWithAdapter second. When // @ts-nocheck is present on the file that declares the union (and the generated prismaNamespace.ts does keep @ts-nocheck for type-check performance), TypeScript's missing-property error elaboration for a discriminated union reports against the second union member. Putting the adapter branch second makes new PrismaClient({ log: [...] }) say Property 'adapter' is missing in type ... but required in type 'PrismaClientOptionsWithAdapter' (the recommended option for most users) instead of suggesting accelerateUrl. Keep the same order in both the runtime types (getPrismaClient.ts) and the generator (PrismaNamespaceFile.ts).
  • JSDoc on individual constructor option properties shows up via autocomplete (TypeScript's getCompletionEntryDetails) but not via hover on an already-written property name when the parameter type is generic. This is a TypeScript limitation that also affects query args like where / select / take (see microsoft/TypeScript#32542). Do not try to "fix" it by removing the generic parameter from the constructor signature — doing so breaks log/omit type inference.
  • The "missing driver adapter" runtime error is raised from both validatePrismaClientOptions (constructor-level, primary user-facing message) and ClientEngine (defense-in-depth). When updating the wording, also update the inline snapshot in packages/client/src/__tests__/validatePrismaClientOptions.test.ts.

• Creating new packages:

  • Create directory under packages/, add package.json, tsconfig.json, tsconfig.build.json, and helpers/build.ts.
  • Package is auto-discovered via pnpm-workspace.yaml glob packages/*.
  • For type-only packages, use bundledConfig from helpers/compile/configs.ts.
  • Add as dependency to consuming packages using "workspace:*" version.
  • Important: Add resolution path to tsconfig.build.bundle.json under compilerOptions.paths for go-to-definition to work in editors.
  • Important: If the package has tests, add it to .github/workflows/test-template.yml. Utility packages typically go in:
    • others job (Linux, no Docker): includes debug, generator-helper, get-platform, fetch-engine, engines, instrumentation, instrumentation-contract, schema-files-loader, config, dmmf, generator, credentials-store, sqlcommenter-* packages.
    • client-packages job: includes client-common, client-engine-runtime, ts-builders, client-generator-js, client-generator-ts, client-generator-registry.
    • driver-adapter-unit-tests job: includes adapter-libsql, adapter-mariadb, adapter-d1, adapter-pg, adapter-planetscale, adapter-mssql, adapter-neon.
    • no-docker job (Windows/macOS): mirrors the others and client-packages jobs for cross-platform testing.

• Prisma 7 direction: Migration from schema.prisma datasource URLs / env() to prisma.config.ts. Commands, tests, and fixtures should read connection settings from PrismaConfigInternal.datasource (or driver adapters) rather than CLI flags or environment loading. SQLite datasource URLs now resolve relative to the config file and not to the schema.

• Test helpers: ctx.setConfigFile('<name>') (from __helpers__/prismaConfig.ts) overrides the config used for the next CLI invocation and is automatically reset after each test, so no explicit cleanup is needed. Many migrate fixtures now provide one config per schema variant (e.g. invalid-url.config.ts next to prisma/invalid-url.prisma) and tests swap them via ctx.setConfigFile(...). ctx.setDatasource/ctx.resetDatasource continue to override connection URLs when needed.

• CLI commands: Most commands already accept --config for custom config paths. Upcoming work removes --schema / --url in favour of config-based resolution. When editing CLI help text, keep examples aligned with new config-first workflow.

  • For isolated Studio verification, you can run packages/cli/src/Studio.ts directly via pnpm exec tsx and pass a config object that preserves loadedFromFile; this keeps SQLite URLs resolving relative to the config file while avoiding unrelated packages/cli/src/bin.ts imports.
  • Studio is now pre-bundled into packages/cli/build/studio.js and packages/cli/build/studio.css, served only through explicit routes in packages/cli/src/Studio.ts via the runtime-specific packages/cli/src/studio-server.ts bindings, and should keep listener-level coverage in packages/cli/src/__tests__/studio-server.vitest.ts because a past Node regression dropped GET bodies by treating them like HEAD.
  • If Enter or click does not open a cell editor in Studio, verify that the current table and column are writable before assuming a keyboard regression; views/system tables and read-only columns legitimately stay non-editable.

• Driver adapters datasource:

  • Helper ctx.setDatasource() in tests overrides config.datasource for connection-specific scenarios.

• Testing patterns:

  • Tests rely on fixtures under packages/**/src/__tests__/fixtures; many now contain prisma.config.ts.
  • Default Jest/Vitest runner is invoked via pnpm --filter @prisma/<pkg> test <pattern>; it wraps dotenv and expects .db.env.
    • Some packages already use Vitest, packages/cli uses both for different tests as it's in the process of transition, older packages still use Jest.
  • Functional generated clients in packages/client/tests/functional/**/.generated import packages/client/runtime/client.js directly; runtime changes in src/runtime may need corresponding runtime bundle updates to be exercised by functional tests.
  • Client e2e _steps.ts files run inside packages/client/tests/e2e/_utils/standard.dockerfile; the startup script exports NODE_PATH for CommonJS and symlinks globally installed zx into /test/node_modules because ESM package resolution ignores NODE_PATH. Linux Docker runs may need SELinux-compatible bind mounts (:z) for mounted e2e files to be readable in the container.
  • Inline snapshots can be sensitive to formatting; prefer concise expectations unless the exact message matters.

• Environment loading: Prisma 7 removes automatic .env loading.

• Driver adapter error handling:

  • Database errors are mapped in each adapter's errors.ts (e.g., packages/adapter-pg/src/errors.ts).
  • MappedError type in packages/driver-adapter-utils/src/types.ts defines all known error kinds.
  • Known error kinds include: GenericJs, UnsupportedNativeDataType, InvalidIsolationLevel, LengthMismatch, UniqueConstraintViolation, NullConstraintViolation, ForeignKeyConstraintViolation, DatabaseNotReachable, DatabaseDoesNotExist, DatabaseAlreadyExists, DatabaseAccessDenied, ConnectionClosed, TlsConnectionError, AuthenticationFailed, TransactionWriteConflict, TableDoesNotExist, ColumnNotFound, TooManyConnections, ValueOutOfRange, InvalidInputValue, MissingFullTextSearchIndex, SocketTimeout, InconsistentColumnData, TransactionAlreadyClosed, and database-specific kinds (postgres, mysql, sqlite, mssql).
  • convertDriverError() in each adapter maps database-specific error codes to MappedError kinds.
  • rethrowAsUserFacing() in packages/client-engine-runtime/src/user-facing-error.ts maps MappedError kinds to Prisma error codes (P2xxx).
  • To add a new error mapping: (1) add kind to MappedError in driver-adapter-utils, (2) map database error code in relevant adapter(s), (3) add Prisma code mapping in getErrorCode() and message in renderErrorMessage().
  • Raw queries ($executeRaw, $queryRaw) use rethrowAsUserFacingRawError() which always returns P2010; regular Prisma operations use rethrowAsUserFacing().
  • When no specific mapping exists for a database-specific kind (postgres, mysql, sqlite, mssql) — i.e. the adapter didn't recognize the underlying DB error code — rethrowAsUserFacing() falls back to a P2039 UserFacingError with the message Database error. Code: <originalCode>. Message: <originalMessage> carrying the raw originalCode / originalMessage. This keeps the DB error surface as PrismaClientKnownRequestError locally and as an HTTP 400 from the query plan executor (instead of HTTP 500, which Accelerate strips), so that schema-drift-style failures (stale migrations, stale generated client, etc.) remain debuggable. Raw queries keep the historical P2010 (Raw query failed. Code: <originalCode>. Message: <originalMessage>) via rethrowAsUserFacingRawError(); P2039 is used for non-raw queries so the message doesn't claim a regular Prisma operation was a raw query. Truly unknown kind values still fall through to assertNever so new driver-adapter variants surface clearly during development.
  • Prisma error codes currently assigned outside the documented public Error Reference (P2000–P2037) are: P2038 — used for the PrismaClientInitializationError raised by ClientEngine when no driver adapter is configured (see CLIENT_ENGINE_ERROR in packages/client/src/runtime/core/engines/client/ClientEngine.ts); P2039 — used for unmapped database-specific driver-adapter errors as described above. Pick the next available code (P2040, …) for any new additions and document it here.

• SQL Commenter packages:

  • @prisma/sqlcommenter: Core types (SqlCommenterPlugin, SqlCommenterContext, SqlCommenterQueryInfo, SqlCommenterTags) for building sqlcommenter plugins.
  • @prisma/sqlcommenter-query-tags: AsyncLocalStorage-based plugin for adding ad-hoc tags via withQueryTags() and withMergedQueryTags().
  • @prisma/sqlcommenter-trace-context: Plugin for adding W3C Trace Context traceparent header to queries.
  • @prisma/sqlcommenter-query-insights: Plugin for adding parameterized query shapes to comments (format: Model.action:base64Payload).
  • Plugins are registered via PrismaClient({ comments: [plugin1(), plugin2()] }).
  • E2E tests for sqlcommenter plugins live in packages/client/tests/e2e/sqlcommenter* directories.
  • SqlCommenterQueryInfo distinguishes type: 'single' (single query) vs type: 'compacted' (batched queries merged into one SQL statement). For non-raw client-engine queries, the SQL commenter context should receive parameterized query payloads so plugins such as query-insights never see user data values.

• Codebase helpers to know:

  • @prisma/internals exports CLI utilities: arg, loadSchemaContext (less used now).
  • packages/migrate/src/__tests__/__helpers__/context.ts sets up Jest helpers including config contributors.
  • packages/config defines PrismaConfigInternal; inspect when validating config assumptions.
  • @prisma/ts-builders provides a fluent API for generating TypeScript code (interfaces, types, properties with doc comments).
  • @prisma/driver-adapter-utils defines core interfaces: SqlQuery, SqlQueryable, SqlDriverAdapter, SqlDriverAdapterFactory, SqlMigrationAwareDriverAdapterFactory, MappedError for error handling, ConnectionInfo, Provider type ('mysql' | 'postgres' | 'sqlite' | 'sqlserver').
  • @prisma/client-engine-runtime exports query interpreter, transaction manager, and related utilities.
  • @prisma/client-common provides shared client utilities used by both generators and runtime.
  • @prisma/client-runtime-utils provides utility types and singletons for Prisma Client.

• Coding conventions:

  • Use kebab-case for new file names (e.g., query-utils.ts, filter-operators.test.ts).
  • Avoid creating barrel files (index.ts that re-export from other modules). Import directly from the source file (e.g., import { foo } from './utils/query-utils' not import { foo } from './utils'), unless ./utils/index.ts file already exists (in which case use it for consistency with surrounding code).
  • Avoid adding useless code comments that do not add new information for the reader. Inline code comments can be broadly categorized as answering one of the three questions:
    • What does this code do? — never write these because they do not and cannot convey any new information that's not obvious from the code. Not only they don't add value, they are actively harmful (getting out of sync with code, distracting human readers, wasting LLM tokens etc). Descriptions of units of code like functions, classes and methods must be limited to doc comments (and describe the contract of this unit and not the internal implementation details), never inline comments.
    • Why was this code written (in this particular way or at all)? — this is what inline comments are for. Only use them to include relevant context, background, GitHub issues, reasons behind decisions etc.
    • How does this code work? — these comments should be exceedingly rare and may indicate poorly written or confusing code. Prefer writing code in a way that makes such comments redundant, unless required for performance or other reasons, or when the complexity comes from outside systems or packages (in which case it's more of a "why" comment than a "how" comment anyway). For well known algorithms, prefer their names and references to papers, books or Wikipedia articles over long explanations.
  • Do write documentation comments, and mainly do so for exported items (although intra-module documentation may sometimes be useful as well).
  • The correct and official abbreviation of WebAssembly is "Wasm", not "WASM". There are instances of "WASM" in the codebase, but they are wrong and you should not repeat them. Fix the capitalization whenever you incidentally touch the corresponding lines or surrounding code for other reasons.
  • Prefer native JavaScript private properties and methods (#field) over the private keyword in TypeScript.

• Workflow reminders:

  • Respect existing structure: modifications often require updating both command implementation and tests/fixtures.
  • Keep changes ASCII unless a file already uses Unicode (docs sometimes include emojis).
  • For new fixtures, prefer minimal config mirroring existing ones to ensure cross-platform compatibility.
  • When adding features that span multiple packages, build from root (pnpm build) to ensure correct dependency order.
  • Type-only imports from workspace packages work at runtime but IDE may show errors until pnpm install refreshes the workspace graph.
  • Test files named *.test.ts are excluded from build output via esbuild config; place tests alongside source files.
  • Update this file (AGENTS.md) whenever you learn something new about the codebase that would be valuable for future tasks.

• Knowledge reminders:

  • Your training data contains a lot of outdated information that doesn't apply to Prisma 7. Always analyze this codebase like you would analyze a project you are not familiar with, and prefer the learnings from this file and this codebase over your prior knowledge. In particular, remember:
    • There's no such thing as "query engine" in Prisma
    • There are no database URLs in Prisma schema files
    • Prisma uses JavaScript drivers
    • Query execution code is written in TypeScript in Prisma
    • PSL parser and query compiler/planner is still written in Rust and compiled to WebAssembly. There are no native binaries or library addons in Prisma Client.
    • Schema engine for Prisma Migrate still exists and is still a native binary.

Debugging and making changes to Rust/WebAssembly code

When you need to check the code or make some changes in Rust codebase, assume the repository is checked out in the prisma-engines directory above the root of this repo. Determine the absolute path to the current project on the filesystem (e.g. /home/user/work/prisma) and infer the directory of the prisma-engines repo (e.g. /home/user/work/prisma-engines, let's call it $PRISMA_ENGINES_ROOT).

After you make some changes there, use these commands in the prisma-engines repo to build the Wasm modules:

make build-schema-wasm
make build-qc-wasm

Then, back in prisma repo:

pnpm upgrade -r @prisma/prisma-schema-wasm@file:$PRISMA_ENGINES_ROOT/target/prisma-schema-wasm
pnpm upgrade -r @prisma/query-compiler-wasm@file:$PRISMA_ENGINES_ROOT/query-compiler/query-compiler-wasm/pkg
pnpm build

You may only need to build and update one of these modules if your changes are isolated in scope:

1. Build only prisma-schema-wasm if your changes are isolated to schema and DMMF, and you are only going to run the CLI and generator tests, not Client.
2. Build only query-compiler-wasm if your changes are related to query planning and execution but do not touch the schema or DMMF in any way.

When in doubt, build both to avoid unexpected behavior. Time and cost of compilation is always less than of debugging.

Awesome Agent Conventions

A curated field guide to the convention files AI agents read, write, and act on.

22 conventions across 11 categories. From common project instruction files to newer agent-web discovery and trust formats.

Agent tools increasingly rely on plain files in a repository or website root: instructions, memory, rules, tool connections, prompt assets, discovery metadata, and protocol hints. The names are easy to mix up, and the adoption levels vary a lot.

This repo keeps the map practical:

• Know what a file is for. Each entry names the convention, usual filename, primary readers, and spec or source.
• Study real examples. Examples are fetched from public repositories by script, with provenance kept at the top of each file.
• Separate practice from proposal. Maturity labels show what is widely used, what is early, and what is still only proposed.

Contents

• Instruction & context · category page
  • 🟢 AGENTS.md
  • 🟢 CLAUDE.md
  • 🟢 Tool-specific instruction files
  • 🟠 OKF (Open Knowledge Format)
• Memory & state · category page
  • 🟢 MEMORY.md
  • 🟢 Memory Bank
• Spec-driven development · category page
  • 🟢 Spec Kit
  • 🟢 Kiro steering files
• Skills & prompt assets · category page
  • 🟢 SKILL.md
  • 🟢 Prompt asset files
  • 🟢 Claude Code commands
  • 🟢 Copilot prompt & instruction files
• Tooling & connections · category page
  • 🟢 MCP server config
• Rules & ignore files · category page
  • 🟢 Rules files
  • 🟢 AI ignore files
• Design · category page
  • 🟢 DESIGN.md
• Web & discoverability · category page
  • 🟢 llms.txt
  • 🟢 pricing.md
• Agent-web trust · category page
  • 🟠 auth.md
  • 🔵 ai.txt
• Identity & protocols · category page
  • 🟠 Agent Cards (A2A)
• Proposed namespace · category page
  • 🔵 The protocols.md namespace

What counts

This list is intentionally narrow. A file belongs here when it is a convention for agent behavior or agent-readable metadata: instructions, memory, skills, rules, tool config, prompt assets, or web-discovery hints.

Any file type can qualify - .md, .txt, .prompty, .json, dotfiles, or a directory pattern. Human-first project docs such as README.md, CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md stay out unless the file has become an agent convention in its own right.

Maturity tiers

The badge is a claim about adoption, not quality. It keeps a proven convention from being presented the same way as a new idea.

Badge	Tier	Meaning
🟢	Adopted	Used in production by multiple tools, projects, or teams.
🟠	Emerging	Published by a real organization, but still early or limited in adoption.
🔵	Proposed	Publicly described, but without clear adoption beyond the proposal.

Instruction & context

Standalone page: categories/instruction-context.md

	Convention	Files	Read by	Spec
🟢	AGENTS.md	AGENTS.md	Most coding agents - OpenAI Codex, Cursor, Jules, Aider, Gemini CLI, Zed, and others	spec ↗
🟢	CLAUDE.md	CLAUDE.md	Claude Code, and tools that read the Claude memory convention	spec ↗
🟢	Tool-specific instruction files	GEMINI.md AGENT.md QWEN.md WARP.md CONVENTIONS.md copilot-instructions.md	Each file is read by its namesake tool - Gemini CLI, Amp, Qwen Code, Warp, Aider, GitHub Copilot - often alongside or as a bridge to AGENTS.md	spec ↗
🟠	OKF (Open Knowledge Format)	.md	Agents over MCP (okfy, openknowledge, superops okf CLIs); Google's knowledge-catalog ingests bundles	spec ↗

• AGENTS.md - A plain-Markdown "README for agents" - build/test commands, conventions, and gotchas an agent needs before touching the code. The most widely adopted cross-tool instruction file.
• CLAUDE.md - Anthropic's memory file for Claude Code - loaded automatically at session start to carry project commands, style rules, and standing instructions across turns.
• Tool-specific instruction files - Per-tool instruction files that predate or coexist with AGENTS.md. Some tools now default to AGENTS.md while keeping legacy filenames alive, so these variants still matter when auditing real repositories.
• OKF (Open Knowledge Format) - A machine-first organizational knowledge base: a version-controlled folder of typed Markdown files (one concept per file) that any agent reads as ground-truth context. Open-sourced by Google Cloud in 2026 as the content layer to MCP's transport.

Memory & state

Standalone page: categories/memory-state.md

	Convention	Files	Read by	Spec
🟢	MEMORY.md	MEMORY.md	Claude Code's auto-memory - the per-project MEMORY.md index it writes and re-reads each session	spec ↗
🟢	Memory Bank	projectbrief.md productContext.md activeContext.md systemPatterns.md techContext.md progress.md	Cline, Roo Code, and Cursor (via the Memory Bank custom-instructions pattern)	spec ↗

• MEMORY.md - A persistent, agent-maintained index of durable facts - written and re-read across sessions so an agent accumulates project memory instead of relearning each time.
• Memory Bank - Cline's structured memory system - a set of Markdown files an agent reads at the start of every task to reconstruct full project context after its session memory resets. The six files shown are Cline's set; tools like Roo Code use an overlapping but different variant.

Spec-driven development

Standalone page: categories/spec-driven-development.md

	Convention	Files	Read by	Spec
🟢	Spec Kit	constitution.md spec.md plan.md tasks.md	GitHub Spec Kit's slash-command agents (Copilot, Claude, Gemini, Cursor, and more)	spec ↗
🟢	Kiro steering files	product.md structure.md tech.md	AWS Kiro (steering files are largely Kiro-specific)	spec ↗

• Spec Kit - GitHub's spec-driven workflow - a constitution plus per-feature spec → plan → tasks files that drive an agent through structured, reviewable implementation.
• Kiro steering files - Kiro's always-on steering docs - product, structure, and tech files that give the agent persistent project context outside of any single spec.

Skills & prompt assets

Standalone page: categories/skills-prompt-assets.md

	Convention	Files	Read by	Spec
🟢	SKILL.md	SKILL.md	Claude Agent Skills, Claude Code, Amp, Agent Skills-compatible tools	spec ↗
🟢	Prompt asset files	.prompty .prompt system_prompt.txt	Prompty tooling, Azure AI / Semantic Kernel, and apps that load externalized prompts	spec ↗
🟢	Claude Code commands	.md	Claude Code - project .claude/commands/ and user ~/.claude/commands/	spec ↗
🟢	Copilot prompt & instruction files	.prompt.md .instructions.md	GitHub Copilot in VS Code / Copilot CLI	spec ↗

• SKILL.md - A self-contained, model-invoked capability file that tells an agent when to load a reusable procedure and how to execute it.
• Prompt asset files - Externalized prompt files - Prompty's YAML-front-mattered .prompty, plain .prompt templates, and system_prompt.txt - that pull the prompt out of source code so it can be versioned and edited on its own. Only .prompty has a formal spec (prompty.ai); .prompt and system_prompt.txt are ad-hoc externalized-prompt filenames.
• Claude Code commands - A Markdown file Claude Code exposes as a /slash-command - a reusable, version-controlled prompt workflow, with optional frontmatter (allowed-tools, model, argument-hint) and $ARGUMENTS and shell placeholders (@file references are a general Claude Code prompt feature, not command-specific). Now converging with Agent Skills, but still widely committed in its own right.
• Copilot prompt & instruction files - Modular, path-scoped Copilot context: *.instructions.md auto-attach to matching files via an applyTo glob, while *.prompt.md are reusable prompts you invoke by name - the granular cousins of a single .github/copilot-instructions.md.

Tooling & connections

Standalone page: categories/tooling-connections.md

	Convention	Files	Read by	Spec
🟢	MCP server config	.mcp.json	Claude Code, Cursor, VS Code / Copilot, and Claude Desktop - every MCP host reads the same mcpServers schema, though the filename and path differ per tool	spec ↗

• MCP server config - A JSON file that tells an agent which Model Context Protocol servers to launch and how (command, args, env) - making a project's tool and data integrations portable, shareable, and version-controlled across every MCP-capable client.

Rules & ignore files

Standalone page: categories/rules-ignore-files.md

	Convention	Files	Read by	Spec
🟢	Rules files	.cursorrules .mdc .clinerules .clinerules/ (pattern) .windsurfrules	Cursor (.cursorrules / .mdc), Cline (.clinerules/ and legacy .clinerules), Windsurf (.windsurfrules)	spec ↗
🟢	AI ignore files	.aiignore .cursorignore .codeiumignore .aiexclude	JetBrains Junie (.aiignore), Cursor (.cursorignore), Codeium/Windsurf (.codeiumignore)	spec ↗

• Rules files - Per-tool rule files that scope agent behavior - older single-file forms (.cursorrules, .clinerules, .windsurfrules) and newer directory-based, glob-scoped forms (.cursor/rules/.mdc, .clinerules/, .windsurf/rules/.md).
• AI ignore files - gitignore-syntax files that fence an AI agent out of paths - secrets, vendored code, generated output - so they're never sent to the model as context.

Design

Standalone page: categories/design.md

	Convention	Files	Read by	Spec
🟢	DESIGN.md	DESIGN.md	Google Stitch natively; and coding agents (e.g. Claude Code) when pointed at it as design context	spec ↗

• DESIGN.md - A structured, machine-readable design specification - tokens, components, and layout intent - that an agent reads to generate or keep UI consistent with an established system. Open-sourced by Google Labs in 2026 as a cross-tool draft spec.

Web & discoverability

Standalone page: categories/web-discoverability.md

	Convention	Files	Read by	Spec
🟢	llms.txt	llms.txt llms-full.txt (pattern)	Docs sites publish it for LLM tools and crawlers - though no major provider has confirmed reading it	spec ↗
🟢	pricing.md	pricing.md	Agents and LLM browsers fetching a clean, parse-able pricing page	spec ↗

• llms.txt - A proposed-turned-widely-published standard: a root-level Markdown file giving LLMs a curated, link-rich map of a site's docs. Published across hundreds of developer-docs sites - though whether the major LLM providers actually read it remains unproven.
• pricing.md - The Markdown twin of a pricing page - same URL with a .md suffix - so an agent gets structured plans and numbers instead of scraping marketing HTML. A concrete, shipping instance of the page.md pattern.

Agent-web trust

Standalone page: categories/agent-web-trust.md

	Convention	Files	Read by	Spec
🟠	auth.md	auth.md	Agents discovering how to authenticate to a service (early adopters)	spec ↗
🔵	ai.txt	ai.txt	AI training/data-mining crawlers that voluntarily honor AI usage preferences; crawler support is not yet reliable	spec ↗

• auth.md - A Markdown file that tells an agent how to authenticate with a service - discovery of auth endpoints and flows. Shipped by WorkOS as a real, working convention, but adoption beyond it is still early.
• ai.txt - A text file declaring machine-readable consent, licensing, or policy preferences for AI training and data-mining. Spawning popularized the deployed root-file pattern, and a 2026 Internet-Draft now proposes a well-known URI; adoption and crawler obedience are still thin, so it stays 🔵.

Identity & protocols

Standalone page: categories/identity-protocols.md

	Convention	Files	Read by	Spec
🟠	Agent Cards (A2A)	agent-card.json agent.json (pattern)	A2A-compatible agents discovering another agent's capabilities	spec ↗

• Agent Cards (A2A) - The Agent2Agent (A2A) capability card - a JSON document at a well-known path advertising an agent's skills, endpoints, and auth so other agents can discover and call it. Now a Linux Foundation project at v1.0; adoption is growing but early.

Proposed namespace

Standalone page: categories/proposed-namespace.md

	Convention	Files	Read by	Spec
🔵	The protocols.md namespace	proof.md	- (no demonstrated readers; aspirational)	spec ↗

• The protocols.md namespace - A single maintainer's pre-registered namespace of ~74 aspirational .md "protocols" (proof.md, signature.md, reputation.md, …) staked as Schelling points for a future agent web. Published concept, no demonstrated adoption - see the page for the audited, honest caveats.

Maintaining examples

Example files are fetched, not invented. The extractor pulls them from public sources, stores them under conventions/<slug>/examples/<source>/<filename>, and adds a line-1 provenance comment. The examples remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md before reusing them.

To refresh everything:

pip install -r scripts/requirements.txt
python scripts/extract.py          # fetch real files + rebuild each convention's README
python scripts/build_readme.py     # rebuild this README from scripts/targets.json

Re-running is idempotent. A missing target prints a miss and is skipped. Examples are representative samples: any file over 256 KB (for example, a multi-MB llms-full.txt) is truncated with a marker pointing back to the full source. scripts/targets.json remains the source of truth for conventions that have not been migrated yet; the skill-md pilot uses local convention metadata instead. Edit the relevant source and re-run both scripts.

Shortcut targets are available in the Makefile:

make verify          # schema + generated files + example provenance + links
make extract         # refetch public examples and rebuild generated docs
make license-report  # summarize upstream licenses for vendored examples

CI keeps the generated files and links honest. The verify workflow checks that generated docs match catalog metadata and migrated local metadata, and that every spec, example, and instance URL still resolves on each pull request and weekly. Run the same link check locally with python scripts/check_links.py.

Contributing

Read CONTRIBUTING.md. In short: an entry must pass the filter above and carry evidence for its maturity tier. Add sources to scripts/targets.json for non-migrated conventions, run the scripts, and open a PR. The skill-md pilot uses local convention metadata instead. Do not hand-write example files.

Before proposing adjacent standards, check WATCHLIST.md. Project direction lives in ROADMAP.md.

License

The curation, scripts, and original prose in this repository are MIT. Vendored example files remain under their upstream owners' licenses and terms; see THIRD_PARTY_EXAMPLES.md.