Skip to content

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

TypeScript

feat(cli): default agent docs to AGENTS.md unless --agent claude (#4216)

Joey5a134892a63a
diff --git a/.changeset/agent-docs-default-agents-md.md b/.changeset/agent-docs-default-agents-md.md
new file mode 100644
index 0000000000..82af67211b
--- /dev/null
+++ b/.changeset/agent-docs-default-agents-md.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[feat] `astryx init --features agents` now defaults to creating root `AGENTS.md` — the tool-agnostic standard that Codex/Copilot, Cursor, and most agents read — instead of the Claude-specific `.claude/CLAUDE.md`. Claude output is now opt-in via `--agent claude` (→ `.claude/CLAUDE.md`), and `--agent all` still writes both. Projects with existing agent-doc files are unaffected: init still discovers and updates every file already present, so this only changes the from-scratch default. (#4216)
+
+@josephfarina
diff --git a/packages/cli/docs/working-with-ai.doc.mjs b/packages/cli/docs/working-with-ai.doc.mjs
index 3d8f2c6d25..e43042bfbc 100644
--- a/packages/cli/docs/working-with-ai.doc.mjs
+++ b/packages/cli/docs/working-with-ai.doc.mjs
@@ -42,13 +42,13 @@ export const docs = {
},
{
type: 'prose',
- text: 'If you prefer to target a specific file format:',
+ text: 'By default this creates `AGENTS.md` (the tool-agnostic standard most agents read). To target a specific tool\'s file instead:',
},
{
type: 'code',
lang: 'bash',
label: 'Manual options',
- code: `npx @astryxdesign/cli init --features agents --agent claude # CLAUDE.md
+ code: `npx @astryxdesign/cli init --features agents --agent claude # .claude/CLAUDE.md
npx @astryxdesign/cli init --features agents --agent cursor # .cursorrules
npx @astryxdesign/cli init --features agents --agent codex # AGENTS.md (Copilot, Codex, etc.)`,
},
diff --git a/packages/cli/src/commands/agent-docs.mjs b/packages/cli/src/commands/agent-docs.mjs
index 257078ec9a..48fbc13917 100644
--- a/packages/cli/src/commands/agent-docs.mjs
+++ b/packages/cli/src/commands/agent-docs.mjs
@@ -12,7 +12,7 @@
* - Hermes Agent: .hermes.md or HERMES.md (existing), else AGENTS.md
*
* Auto-detect: discovers existing files and updates them in place.
- * Default (no existing files): creates .claude/CLAUDE.md.
+ * Default (no existing files): creates AGENTS.md (the tool-agnostic standard).
*
* --agent <tool>: target a specific tool preset (claude, cursor, codex, hermes, all)
* --agent-docs-path <path>: explicit file path(s)
@@ -511,7 +511,7 @@ export function removeAgentDocs(targetDir) {
*
* Strategy (when no agent/paths specified):
* - Discover all existing agent doc files and update them
- * - If nothing found, create .claude/CLAUDE.md as default
+ * - If nothing found, create AGENTS.md as default (tool-agnostic standard)
*
* @param {string} targetDir
* @param {object} [options]
@@ -586,14 +586,16 @@ export function installAgentDocs(targetDir, {zh = false, lang, agent, paths, onl
return written;
}
- // Nothing exists — create .claude/CLAUDE.md as default (skip if onlyReplace)
+ // Nothing exists — create root AGENTS.md as the default (skip if onlyReplace).
+ // AGENTS.md is the tool-agnostic standard (Codex/Copilot, Cursor, and most
+ // agents read it), so it's the safe default. Claude-specific output is opt-in
+ // via `--agent claude` (→ .claude/CLAUDE.md); `--agent all` writes both.
if (onlyReplace) return written;
- const defaultPath = CLAUDE_DIR_MD;
- fs.mkdirSync(path.join(targetDir, '.claude'), {recursive: true});
+ const defaultPath = AGENTS_MD;
injectXdsBlock(path.join(targetDir, defaultPath), compressedIndex, {
createIfMissing: true,
- header: `# CLAUDE.md\n\nProject-specific guidance for AI coding agents.`,
+ header: `# AGENTS.md\n\nProject-specific guidance for AI coding agents.`,
});
written.push(defaultPath);
return written;
diff --git a/packages/cli/src/commands/agent-docs.test.mjs b/packages/cli/src/commands/agent-docs.test.mjs
index da254035ca..812d5981cf 100644
--- a/packages/cli/src/commands/agent-docs.test.mjs
+++ b/packages/cli/src/commands/agent-docs.test.mjs
@@ -398,18 +398,37 @@ describe('installAgentDocs', () => {
);
}
- it('creates .claude/CLAUDE.md when no agent docs exist', () => {
+ it('creates AGENTS.md when no agent docs exist (tool-agnostic default)', () => {
setupCorePackage(tmpDir);
const written = installAgentDocs(tmpDir);
- expect(written).toEqual(['.claude/CLAUDE.md']);
- expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(true);
- expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
- const content = fs.readFileSync(path.join(tmpDir, '.claude', 'CLAUDE.md'), 'utf-8');
+ expect(written).toEqual(['AGENTS.md']);
+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(true);
+ // Must NOT create the Claude-specific file by default.
+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+ const content = fs.readFileSync(path.join(tmpDir, 'AGENTS.md'), 'utf-8');
+ expect(content).toContain('# AGENTS.md');
expect(content).toContain('<!-- ASTRYX:START -->');
});
+ it('defaults to AGENTS.md but writes .claude/CLAUDE.md only when --agent claude is explicit', () => {
+ // Default (no agent): tool-agnostic AGENTS.md, never the Claude file.
+ setupCorePackage(tmpDir);
+ expect(installAgentDocs(tmpDir)).toEqual(['AGENTS.md']);
+ expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
+
+ // Explicit Claude: the Claude-specific file, in a fresh project.
+ const claudeDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-agent-docs-claude-'));
+ setupCorePackage(claudeDir);
+ try {
+ expect(installAgentDocs(claudeDir, {agent: 'claude'})).toEqual(['.claude/CLAUDE.md']);
+ expect(fs.existsSync(path.join(claudeDir, 'AGENTS.md'))).toBe(false);
+ } finally {
+ fs.rmSync(claudeDir, {recursive: true, force: true});
+ }
+ });
+
it('injects into CLAUDE.md at root when it exists', () => {
setupCorePackage(tmpDir);
fs.writeFileSync(path.join(tmpDir, 'CLAUDE.md'), '# Claude\n\nProject rules.\n');
@@ -526,12 +545,13 @@ describe('installAgentDocs', () => {
expect(content).toContain('Other rules.');
});
- it('onlyReplace: does not create default .claude/CLAUDE.md when nothing exists', () => {
+ it('onlyReplace: does not create the default AGENTS.md when nothing exists', () => {
setupCorePackage(tmpDir);
const written = installAgentDocs(tmpDir, {onlyReplace: true});
expect(written).toEqual([]);
+ expect(fs.existsSync(path.join(tmpDir, 'AGENTS.md'))).toBe(false);
expect(fs.existsSync(path.join(tmpDir, '.claude', 'CLAUDE.md'))).toBe(false);
});
});
diff --git a/packages/cli/src/commands/interactive-guard.test.mjs b/packages/cli/src/commands/interactive-guard.test.mjs
index fba41b09ed..2fd85690b6 100644
--- a/packages/cli/src/commands/interactive-guard.test.mjs
+++ b/packages/cli/src/commands/interactive-guard.test.mjs
@@ -50,7 +50,7 @@ describe('init is non-interactive by default (no TTY needed)', () => {
it('writes an agent-doc file containing the ASTRYX cheat-sheet marker', () => {
runCli(['init']);
- // init injects into AGENTS.md/CLAUDE.md if present, else creates .claude/CLAUDE.md
+ // init injects into existing agent-doc files if present, else creates AGENTS.md
const candidates = ['AGENTS.md', 'CLAUDE.md', '.cursorrules', path.join('.claude', 'CLAUDE.md')];
const doc = candidates.find(f => fs.existsSync(path.join(tmpDir, f)));
expect(doc).toBeTruthy();
diff --git a/packages/cli/src/commands/json-contract.test.mjs b/packages/cli/src/commands/json-contract.test.mjs
index 72e6c0cf8d..73364d58f7 100644
--- a/packages/cli/src/commands/json-contract.test.mjs
+++ b/packages/cli/src/commands/json-contract.test.mjs
@@ -61,7 +61,7 @@ afterEach(() => {
});
describe('--json contract: rejects before side effects', () => {
- it('astryx init --json --features agents does not write .claude/CLAUDE.md', () => {
+ it('astryx init --json --features agents does not write agent docs', () => {
const before = fs.readdirSync(tmpDir);
expect(before).toEqual([]);
diff --git a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx
index db7fe8a4c0..9c51c2c7e6 100644
--- a/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx
+++ b/packages/cli/templates/blocks/components/CodeBlock/CodeBlockTerminal.tsx
@@ -7,7 +7,7 @@ import {githubDark} from '@astryxdesign/core/theme/syntax';
import {CodeBlock} from '@astryxdesign/core/CodeBlock';
const commands = `$ astryx init --features agents
-✓ AI agent docs installed → .claude/CLAUDE.md
+✓ AI agent docs installed → AGENTS.md
$ pnpm astryx component CodeBlock --dense`;
export default function CodeBlockTerminal() {