Make CLAUDE.md point to AGENTS.md via @AGENTS.md directive

Copilot · lmajano · Copilot · commit 8d9e4e102123 · 2026-03-27T10:27:07.000Z
Agent-Logs-Url: https://github.com/ColdBox/coldbox-cli/sessions/785ea4ed-69ec-4c40-9eb3-3ed6e0ae4012 Co-authored-by: lmajano <137111+lmajano@users.noreply.github.com>
diff --git a/AI_INTEGRATION.md b/AI_INTEGRATION.md
@@ -202,10 +202,10 @@ graph LR
 
 Additionally, agent configuration files are created for you (paths defined in `AgentRegistry.cfc`):
 
-* `CLAUDE.md` - Claude Desktop/Code assistant
+* `CLAUDE.md` - Claude Desktop/Code assistant (points to `AGENTS.md` via `@AGENTS.md`)
 * `.github/copilot-instructions.md` - GitHub Copilot
 * `.cursorrules` - Cursor IDE
-* `AGENTS.md` - Codex & OpenCode (shared file)
+* `AGENTS.md` - Codex, OpenCode & Claude (shared file)
 * `GEMINI.md` - Gemini CLI
 
 ### Keeping Resources Updated
@@ -894,7 +894,7 @@ ColdBox AI Integration supports **6 major AI agents** with automatic configurati
 
 | Agent              | Config File                       | Description                    |
 | ------------------ | --------------------------------- | ------------------------------ |
-| **Claude**         | `CLAUDE.md`                       | Claude Desktop and Claude Code |
+| **Claude**         | `CLAUDE.md` → `AGENTS.md`         | Claude Desktop and Claude Code |
 | **GitHub Copilot** | `.github/copilot-instructions.md` | VS Code Copilot integration    |
 | **Cursor**         | `.cursorrules`                    | Cursor IDE rules               |
 | **Codex**          | `AGENTS.md` (shared)              | Codex AI assistant             |
diff --git a/README.md b/README.md
@@ -546,7 +546,7 @@ coldbox ai agents remove cursor       # Remove an agent
 coldbox ai agents refresh             # Regenerate all configurations
 ```
 
-**Supported Agents**: Claude (CLAUDE.md), GitHub Copilot (.github/copilot-instructions.md), Cursor (.cursorrules), Codex (AGENTS.md), Gemini (GEMINI.md), OpenCode (AGENTS.md)
+**Supported Agents**: Claude (CLAUDE.md → AGENTS.md), GitHub Copilot (.github/copilot-instructions.md), Cursor (.cursorrules), Codex (AGENTS.md), Gemini (GEMINI.md), OpenCode (AGENTS.md)
 
 #### Guidelines
 
diff --git a/changelog.md b/changelog.md
@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+- `CLAUDE.md` now contains `@AGENTS.md` to point Claude to the shared `AGENTS.md` file, avoiding duplicate content
+
 ## [8.8.0] - 2026-03-12
 
 - Fix invalid aliases
diff --git a/models/AgentRegistry.cfc b/models/AgentRegistry.cfc
@@ -153,6 +153,14 @@ component singleton {
 			directoryCreate( configDir )
 		}
 
+		// For Claude, write the full content to AGENTS.md and make CLAUDE.md point to it
+		if ( arguments.agent == "claude" ) {
+			var agentsFilePath = getDirectoryFromPath( configPath ) & "AGENTS.md"
+			fileWrite( agentsFilePath, content )
+			fileWrite( configPath, "@AGENTS.md" )
+			return
+		}
+
 		// Write agent config file
 		fileWrite( configPath, content )
 	}

Original file line number	Diff line number	Diff line change
`@@ -153,6 +153,14 @@ component singleton {`
`153`	`153`	`directoryCreate( configDir )`
`154`	`154`	`}`
`155`	`155`
	`156`	`+ // For Claude, write the full content to AGENTS.md and make CLAUDE.md point to it`
	`157`	`+ if ( arguments.agent == "claude" ) {`
	`158`	`+ var agentsFilePath = getDirectoryFromPath( configPath ) & "AGENTS.md"`
	`159`	`+ fileWrite( agentsFilePath, content )`
	`160`	`+ fileWrite( configPath, "@AGENTS.md" )`
	`161`	`+ return`
	`162`	`+ }`
	`163`	`+`
`156`	`164`	`// Write agent config file`
`157`	`165`	`fileWrite( configPath, content )`
`158`	`166`	`}`