From 1a2c121220be0205604cecf2d35c7bf730eb6eb0 Mon Sep 17 00:00:00 2001
From: Taesu <166604494+bytaesu@users.noreply.github.com>
Date: Thu, 3 Sep 2026 06:36:37 +0900
Subject: [PATCH] chore: improve `AGENTS.md` (#11135)

---
 AGENTS.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 2d0dd78cde..5b6be3a2a6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,6 +18,7 @@ This is the Better Auth repository - a comprehensive authentication framework fo
 - ALWAYS use `pnpm` (never npm, yarn, or bun)
 - NEVER run `pnpm test` (runs all packages). Use `vitest path/to/test -t <pattern>`
 - Type check: `pnpm typecheck`
+- After changing a dependency version in `package.json` or `pnpm-workspace.yaml`, run `pnpm install --lockfile-only` from the affected workspace root to avoid unrelated lockfile updates. Verify with `pnpm install --frozen-lockfile`. Nested `demo/*` workspaces have separate lockfiles.
 - Formatting/linting runs automatically on commit (Lefthook + Biome). No need to run manually.
 
 ## Writing Code
@@ -67,7 +68,7 @@ When a flow must synthesize an email, use `createPlaceholderEmail` with a stable
 - NEVER create separate clients with `createAuthClient()` in tests
 - Default test DB is SQLite in-memory; use `testWith` for other databases
 - Adapter tests need Docker: `docker compose up -d`
-- Regression tests: add `@see` comment with issue URL above `it()` or `describe()`:
+- Regression tests: use `@see` for relevant issues or authoritative sources. Do not reference the current pull request or its review comments:
   ```typescript
   /**
    * @see https://github.com/better-auth/better-auth/issues/{issue_number}
@@ -76,6 +77,7 @@ When a flow must synthesize an email, use `createPlaceholderEmail` with a stable
     // ...
   });
   ```
+- Put a shared `@see` above a focused `describe()` when multiple regression tests share the same reference. For a standalone regression test, put it above `it()`.
 
 ## Important Development Notes