Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(cli): don't create AGENTS.md when CLAUDE.md exists (#461)

Cindy Zhang10a2616df52c
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index c95780738d..c3432b0f44 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -165,12 +165,26 @@ export function removeAgentDocs(targetDir) {
/**
* Programmatic entry point for installing agent docs.
* Used by the init wizard.
+ *
+ * Strategy:
+ * - If CLAUDE.md exists, inject there (don't create AGENTS.md)
+ * - If only AGENTS.md exists (or neither), inject into AGENTS.md
+ * - If both exist, inject into both
*/
export function installAgentDocs(targetDir) {
const coreDir = findCoreDir(targetDir);
const version = getXdsVersion(coreDir);
- injectAgentsMd(targetDir, version);
- injectClaudeMd(targetDir, version);
+ const hasClaudeMd = fs.existsSync(path.join(targetDir, CLAUDE_MD));
+ const hasAgentsMd = fs.existsSync(path.join(targetDir, AGENTS_MD));
+
+ if (hasClaudeMd) {
+ injectClaudeMd(targetDir, version);
+ if (hasAgentsMd) {
+ injectAgentsMd(targetDir, version);
+ }
+ } else {
+ injectAgentsMd(targetDir, version);
+ }
}
export function registerAgentDocs(program) {
@@ -192,18 +206,30 @@ export function registerAgentDocs(program) {
console.log(`\nπŸ“š Installing XDS agent docs (v${version})...\n`);
- injectAgentsMd(targetDir, version);
- console.log(`βœ“ Injected compressed index into ${AGENTS_MD}`);
+ const hasClaudeMd = fs.existsSync(path.join(targetDir, CLAUDE_MD));
+ const hasAgentsMd = fs.existsSync(path.join(targetDir, AGENTS_MD));
+ const targets = [];
- if (injectClaudeMd(targetDir, version)) {
+ if (hasClaudeMd) {
+ injectClaudeMd(targetDir, version);
console.log(`βœ“ Injected compressed index into ${CLAUDE_MD}`);
+ targets.push(CLAUDE_MD);
+ if (hasAgentsMd) {
+ injectAgentsMd(targetDir, version);
+ console.log(`βœ“ Injected compressed index into ${AGENTS_MD}`);
+ targets.push(AGENTS_MD);
+ }
+ } else {
+ injectAgentsMd(targetDir, version);
+ console.log(`βœ“ Injected compressed index into ${AGENTS_MD}`);
+ targets.push(AGENTS_MD);
}
console.log(`
βœ… XDS agent docs installed!
Your AI coding agent will now:
- β€’ See the XDS component index in AGENTS.md${fs.existsSync(path.join(targetDir, CLAUDE_MD)) ? ' and CLAUDE.md' : ''}
+ β€’ See the XDS component index in ${targets.join(' and ')}
β€’ Run \`npx xds component <name>\` to read detailed docs
β€’ Run \`npx xds docs principles\` for design principles
β€’ Run \`npx xds docs tokens\` for design token reference
diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjs
index 735fbe2bdf..313916373c 100644
--- a/packages/cli/src/commands/agent-docs.test.mjs
+++ b/packages/cli/src/commands/agent-docs.test.mjs
@@ -5,6 +5,7 @@ import * as os from 'node:os';
import {
generateCompressedIndex,
getXdsVersion,
+ installAgentDocs,
injectAgentsMd,
injectClaudeMd,
injectXdsBlock,
@@ -250,3 +251,49 @@ XDS index stuff
expect(claudeContent).not.toContain('<!-- XDS:START -->');
});
});
+
+describe('installAgentDocs', () => {
+ function setupCorePackage(dir, version = '1.0.0') {
+ // Create a minimal @xds/core so getXdsVersion works
+ const coreDir = path.join(dir, 'node_modules', '@xds', 'core');
+ fs.mkdirSync(coreDir, {recursive: true});
+ fs.writeFileSync(
+ path.join(coreDir, 'package.json'),
+ JSON.stringify({version}),
+ );
+ }
+
+ it('creates AGENTS.md when neither file exists', () => {
+ setupCorePackage(tmpDir);
+
+ installAgentDocs(tmpDir);
+
+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
+ expect(fs.existsSync(path.join(tmpDir, 'CLAUDE.md'))).toBe(false);
+ });
+
+ it('injects into CLAUDE.md and skips creating AGENTS.md when only CLAUDE.md exists', () => {
+ setupCorePackage(tmpDir);
+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');
+
+ installAgentDocs(tmpDir);
+
+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
+ const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+ expect(claudeContent).toContain('<!-- XDS:START -->');
+ expect(claudeContent).toContain('Project rules.');
+ });
+
+ it('injects into both when both files exist', () => {
+ setupCorePackage(tmpDir);
+ fs.writeFileSync(path.join(tmpDir, 'AGENTS.md'), '# Agents\n\nAgent rules.\n');
+ fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nClaude rules.\n');
+
+ installAgentDocs(tmpDir);
+
+ const agentsContent = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+ const claudeContent = fs.readFileSync(path.join(tmpDir, 'CLAUDE.md'), 'utf-8');
+ expect(agentsContent).toContain('<!-- XDS:START -->');
+ expect(claudeContent).toContain('<!-- XDS:START -->');
+ });
+});