fix(shared): import AGENTS.md from an existing CLAUDE.md

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

Author: royanger

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

@@ -6,4 +6,4 @@
 '@clerk/tanstack-react-start': minor
 ---
 
-When your app runs in development under an AI coding agent (such as Claude Code, Cursor, or GitHub Copilot), Clerk now adds a Clerk section to the project's root `AGENTS.md`, creating the file if needed, plus a `CLAUDE.md` that imports it when none exists. 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 or CI. The section is written by the Astro and Nuxt dev servers, the Expo config plugin, the first `auth()` call in Next.js, and TanStack React Start's `clerkMiddleware()`.
+When your app runs in development under an AI coding agent (such as Claude Code, Cursor, or GitHub Copilot), 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 or CI. The section is written by the Astro and Nuxt dev servers, the Expo config plugin, the first `auth()` call in Next.js, and TanStack React Start's `clerkMiddleware()`.

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

@@ -120,6 +120,99 @@ describe('writeClerkAgentRules', () => {
   });
 });
 
+describe('writeClerkAgentRules with an existing CLAUDE.md', () => {
+  it('adds an @AGENTS.md import when CLAUDE.md does not load AGENTS.md', () => {
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': 'Agent rules\n',
+      '/repo/CLAUDE.md': 'Claude rules\n',
+    });
+
+    const result = writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+    expect(result.claudeMd).toBe('updated');
+    expect(memory.read('/repo/CLAUDE.md')).toBe('Claude rules\n\n@AGENTS.md\n');
+    expect(memory.read('/repo/AGENTS.md')).toContain('<!-- BEGIN:clerk-agent-rules:nextjs -->');
+  });
+
+  it('adds the import only once across runs', () => {
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': 'Agent rules\n',
+      '/repo/CLAUDE.md': 'Claude rules\n',
+    });
+
+    writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+    const result = writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+    expect(result.claudeMd).toBe('unchanged');
+    expect(memory.read('/repo/CLAUDE.md')).toBe('Claude rules\n\n@AGENTS.md\n');
+  });
+
+  it.each(['@AGENTS.md', '@./AGENTS.md'])('leaves CLAUDE.md alone when it already imports %s', importLine => {
+    const claude = `Claude rules\n\n${importLine}\n`;
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': 'Agent rules\n',
+      '/repo/CLAUDE.md': claude,
+    });
+
+    const result = writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+    expect(result.claudeMd).toBe('unchanged');
+    expect(memory.read('/repo/CLAUDE.md')).toBe(claude);
+  });
+
+  it('leaves CLAUDE.md alone when it mirrors AGENTS.md, as a symlink does', () => {
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': 'Shared rules\n',
+      '/repo/CLAUDE.md': 'Shared rules\n',
+    });
+
+    const result = writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+    expect(result.claudeMd).toBe('unchanged');
+    expect(memory.read('/repo/CLAUDE.md')).toBe('Shared rules\n');
+  });
+
+  it('writes the Clerk block into CLAUDE.md and skips the import when only CLAUDE.md exists', () => {
+    const memory = createMemoryFs({ '/repo/CLAUDE.md': 'Claude rules\n' });
+
+    const result = writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+    expect(result.agentsMd).toBe('updated');
+    expect(memory.read('/repo/AGENTS.md')).toBeUndefined();
+    expect(memory.read('/repo/CLAUDE.md')).toContain('<!-- BEGIN:clerk-agent-rules:nextjs -->');
+    expect(memory.read('/repo/CLAUDE.md')).not.toContain('@AGENTS.md');
+  });
+
+  it('keeps CRLF line endings in CLAUDE.md', () => {
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': 'Agent rules\r\n',
+      '/repo/CLAUDE.md': 'Claude rules\r\n',
+    });
+
+    writeClerkAgentRules({ cwd: '/repo', fs: memory.fs, path: pathAdapter, sdks: ['nextjs'] });
+
+    expect(memory.read('/repo/CLAUDE.md')).toBe('Claude rules\r\n\r\n@AGENTS.md\r\n');
+  });
+
+  it('reports the import but does not write it in dry-run mode', () => {
+    const memory = createMemoryFs({
+      '/repo/AGENTS.md': 'Agent rules\n',
+      '/repo/CLAUDE.md': 'Claude rules\n',
+    });
+
+    const result = writeClerkAgentRules({
+      cwd: '/repo',
+      dryRun: true,
+      fs: memory.fs,
+      path: pathAdapter,
+      sdks: ['nextjs'],
+    });
+
+    expect(result.claudeMd).toBe('updated');
+    expect(memory.read('/repo/CLAUDE.md')).toBe('Claude rules\n');
+  });
+});
+
 describe('Clerk plugin rules', () => {
   it('recommends the Clerk plugin and keeps the ask-before-changes rule in the root block', () => {
     const block = renderClerkAgentRulesBlock();

packages/shared/src/agentRules/index.ts

@@ -40,7 +40,7 @@ export interface WriteClerkAgentRulesOptions {
 export type WriteClerkAgentRulesResult = {
   targetDir: string;
   agentsMd: 'created' | 'updated' | 'unchanged';
-  claudeMd: 'created' | 'unchanged' | 'skipped';
+  claudeMd: 'created' | 'updated' | 'unchanged' | 'skipped';
 };
 
 const GENERIC_START = '<!-- BEGIN:clerk-agent-rules -->';
@@ -73,6 +73,13 @@ const uniqueSdks = (sdks: ClerkAgentRulesSdk[]) => [...new Set(sdks)].sort();
 const detectEol = (content: string) => (content.includes('\r\n') ? '\r\n' : '\n');
 const normalizeEol = (content: string, eol: string) => content.replace(/\r?\n/g, eol);
 
+const CLAUDE_AGENTS_IMPORT = /^\s*@(?:\.\/)?AGENTS\.md\s*$/m;
+
+const appendAgentsImport = (content: string) => {
+  const eol = detectEol(content);
+  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 clerkAgentRulesSdks = Object.keys(SDK_LABELS) as ClerkAgentRulesSdk[];
@@ -248,7 +255,15 @@ export function writeClerkAgentRules(options: WriteClerkAgentRulesOptions): Writ
   }
 
   const targetStatus = fs.existsSync(targetFile) ? (next === existing ? 'unchanged' : 'updated') : 'created';
-  const shouldCreateClaude = targetFile === agentsPath && !fs.existsSync(claudePath);
+  const claudeExists = fs.existsSync(claudePath);
+  const shouldCreateClaude = targetFile === agentsPath && !claudeExists;
+  const claudeContent =
+    targetFile === agentsPath && claudeExists ? fs.readFileSync(claudePath, { encoding: 'utf8' }) : null;
+  const shouldImportAgentsInClaude =
+    claudeContent !== null &&
+    claudeContent !== existing &&
+    !claudeContent.includes(GENERIC_START) &&
+    !CLAUDE_AGENTS_IMPORT.test(claudeContent);
 
   if (!dryRun) {
     fs.mkdirSync?.(targetDir, { recursive: true });
@@ -258,11 +273,20 @@ export function writeClerkAgentRules(options: WriteClerkAgentRulesOptions): Writ
     if (shouldCreateClaude) {
       fs.writeFileSync(claudePath, '@AGENTS.md\n', { encoding: 'utf8', mode: 0o644 });
     }
+    if (shouldImportAgentsInClaude && claudeContent !== null) {
+      fs.writeFileSync(claudePath, appendAgentsImport(claudeContent), { encoding: 'utf8', mode: 0o644 });
+    }
   }
 
   return {
     targetDir,
     agentsMd: targetStatus,
-    claudeMd: shouldCreateClaude ? 'created' : fs.existsSync(claudePath) ? 'unchanged' : 'skipped',
+    claudeMd: shouldCreateClaude
+      ? 'created'
+      : shouldImportAgentsInClaude
+        ? 'updated'
+        : claudeExists
+          ? 'unchanged'
+          : 'skipped',
   };
 }