fix(shared): reject inherited keys in isClerkAgentRulesSdk and clarify when agent rules are skipped

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: royanger

.changeset/shared-agent-rules.md

@@ -2,4 +2,4 @@
 '@clerk/shared': minor
 ---
 
-Add `@clerk/shared/agentRules`, `@clerk/shared/agentRulesWriter`, and `@clerk/shared/vite` for writing Clerk sections to a project's `AGENTS.md`. Add `isClerkAgentRulesWriteAllowed()` to `@clerk/shared/utils`, which returns `false` in production, in tests, in CI, or when `CLERK_AGENTS_MD=false`.
+Add `@clerk/shared/agentRules`, `@clerk/shared/agentRulesWriter`, and `@clerk/shared/vite` for writing Clerk sections to a project's `AGENTS.md`. Add `isClerkAgentRulesWriteAllowed()` to `@clerk/shared/utils`, which returns `false` when `NODE_ENV=production`, in tests, in CI, or when `CLERK_AGENTS_MD=false`. Deployments that don't set `NODE_ENV=production` should set `CLERK_AGENTS_MD=false` to turn writes off.

.changeset/write-agents-md-in-dev.md

@@ -11,4 +11,4 @@
 '@clerk/tanstack-react-start': minor
 ---
 
-When your app runs in development, Clerk now adds a Clerk section to the project's root `AGENTS.md`, creating the file if needed. It also creates a `CLAUDE.md` that imports `AGENTS.md`, or adds an `@AGENTS.md` import to an existing `CLAUDE.md` that doesn't load it. The section tells the agent to read `node_modules/@clerk/<sdk>/AGENTS.md` before writing auth code and recommends the Clerk plugin (`npx plugins add clerk/skills`). Nothing is written in production, tests, or CI, and setting `CLERK_AGENTS_MD=false` turns it off. The section is written by the Astro and Nuxt dev servers, the Expo config plugin, the first `auth()` call or `clerkMiddleware()` request in Next.js, TanStack React Start's `clerkMiddleware()`, `clerkMiddleware()` in Express, Hono, and React Router, Fastify's `clerkPlugin`, and `createClerkBridge()` in an unpackaged Electron app.
+When your app runs in development, Clerk now adds a Clerk section to the project's root `AGENTS.md`, creating the file if needed. It also creates a `CLAUDE.md` that imports `AGENTS.md`, or adds an `@AGENTS.md` import to an existing `CLAUDE.md` that doesn't load it. The section tells the agent to read `node_modules/@clerk/<sdk>/AGENTS.md` before writing auth code and recommends the Clerk plugin (`npx plugins add clerk/skills`). Nothing is written when `NODE_ENV=production`, in tests, or in CI, and setting `CLERK_AGENTS_MD=false` turns it off. If your deployment doesn't set `NODE_ENV=production`, set `CLERK_AGENTS_MD=false` there. The section is written by the Astro and Nuxt dev servers, the Expo config plugin, the first `auth()` call or `clerkMiddleware()` request in Next.js, TanStack React Start's `clerkMiddleware()`, `clerkMiddleware()` in Express, Hono, and React Router, Fastify's `clerkPlugin`, and `createClerkBridge()` in an unpackaged Electron app.

packages/shared/src/__tests__/agentRules.spec.ts

@@ -4,6 +4,7 @@ import {
   CLERK_SDK_PLUGIN_END,
   CLERK_SDK_PLUGIN_START,
   type FileSystemAdapter,
+  isClerkAgentRulesSdk,
   logClerkAgentRulesResult,
   renderClerkAgentRulesBlock,
   renderClerkSdkPluginBlock,
@@ -280,6 +281,17 @@ describe('writeClerkAgentRules with an existing CLAUDE.md', () => {
   });
 });
 
+describe('isClerkAgentRulesSdk', () => {
+  it('accepts supported SDKs', () => {
+    expect(isClerkAgentRulesSdk('nextjs')).toBe(true);
+  });
+
+  it('rejects inherited object keys', () => {
+    expect(isClerkAgentRulesSdk('constructor')).toBe(false);
+    expect(isClerkAgentRulesSdk('toString')).toBe(false);
+  });
+});
+
 describe('logClerkAgentRulesResult', () => {
   it('logs the files that changed', () => {
     const log = vi.spyOn(console, 'log').mockImplementation(() => undefined);

packages/shared/src/agentRules/index.ts

@@ -81,7 +81,8 @@ const appendAgentsImport = (content: string) => {
   return content.trim() ? `${content.trimEnd()}${eol}${eol}@AGENTS.md${eol}` : `@AGENTS.md${eol}`;
 };
 
-export const isClerkAgentRulesSdk = (value: string): value is ClerkAgentRulesSdk => value in SDK_LABELS;
+export const isClerkAgentRulesSdk = (value: string): value is ClerkAgentRulesSdk =>
+  Object.prototype.hasOwnProperty.call(SDK_LABELS, value);
 
 export const clerkAgentRulesSdks = Object.keys(SDK_LABELS) as ClerkAgentRulesSdk[];