nuxt-agent-md 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # nuxt-agent-md
 
-Generate `AGENTS.md` with Nuxt documentation for AI coding agents (Cursor, Copilot, Claude, etc.).
+Generate `AGENTS.md` and `CLAUDE.md` with Nuxt documentation for AI coding agents (Cursor, Copilot, Claude Code, etc.).
 
 Gives your AI assistant instant access to accurate Nuxt API references, reducing hallucinations and improving code quality.
 
@@ -18,15 +18,14 @@ nuxt-agent-md
 ## What it does
 
 1. Detects your Nuxt version from `package.json`
-2. Downloads the corresponding `@nuxt/docs` documentation (~1.5 MB)
-3. Generates a minified index (~20 KB) of all documentation files
-4. Creates/updates `AGENTS.md` with the index
+2. Downloads the corresponding `@nuxt/docs` documentation (~1.5 MB) to `.nuxt-docs/`
+3. Generates a compact pipe-delimited index pointing to the downloaded docs
+4. Creates/updates `AGENTS.md` with a directive instruction and the index
+5. Creates `CLAUDE.md` that references `@AGENTS.md`
 
-The index format is pipe-delimited for minimal token usage:
+The generated `AGENTS.md` is intentionally minimal — a short directive telling the agent to read the docs, followed by a file index. No inline API summaries or pattern guides are included, so the agent is forced to consult the actual documentation files rather than relying on stale training data.
 
-```
-CATEGORY|path/to/file.md|keyword1,keyword2,keyword3
-```
+This follows [Vercel's finding](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) that passive context with retrieval-led reasoning outperforms both skills and inline knowledge.
 
 ## Options
 
@@ -61,15 +60,22 @@ nuxt-agent-md -d .docs -o CLAUDE.md
 The tool generates:
 
 1. `.nuxt-docs/` - Directory containing markdown documentation (auto-added to `.gitignore`)
-2. `AGENTS.md` - File with minified index pointing to the docs
+2. `AGENTS.md` - File with documentation index (wrapped in `<!-- BEGIN:nuxt-agent-rules -->` markers)
+3. `CLAUDE.md` - File that references `@AGENTS.md` for Claude Code/Cursor compatibility
 
-## Why?
+## How it works
 
-AI coding agents work better when they have access to accurate documentation rather than relying on training data that may be outdated. By providing a compact index in `AGENTS.md`, the agent can quickly find and read the relevant documentation files for any Nuxt API.
+The key insight from [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) is that agents perform best when given a directive to read docs rather than inline knowledge they can use as a shortcut. The generated `AGENTS.md` contains:
 
-## Credits
+```markdown
+# Nuxt: ALWAYS read docs before coding
+
+This project uses Nuxt v4.x.x. Before any Nuxt work, find and read
+the relevant doc in `.nuxt-docs/`. Your training data may be outdated
+— the docs are the source of truth.
+```
 
-Inspired by [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) showing that documentation indexes in `AGENTS.md` significantly improve agent accuracy.
+Followed by a compact index mapping categories to doc file paths. The agent sees the index, knows where to find specific docs, and reads the actual files when needed.
 
 ## License
 

package/dist/cli.js

@@ -236,17 +236,23 @@ function generateFullIndex(entries, docsDir) {
 }
 
 // src/inject.ts
+import { dirname, join as join4 } from "node:path";
 import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync } from "node:fs";
-var START_MARKER = "<!-- NUXT_DOCS_START -->";
-var END_MARKER = "<!-- NUXT_DOCS_END -->";
+var START_MARKER = "<!-- BEGIN:nuxt-agent-rules -->";
+var END_MARKER = "<!-- END:nuxt-agent-rules -->";
 async function injectAgentsMd(outputPath, index, nuxtVersion, docsDir, minify) {
   let content = "";
   if (existsSync3(outputPath)) {
     content = readFileSync3(outputPath, "utf-8");
   }
   const nuxtSection = generateNuxtSection(index, nuxtVersion, docsDir, minify);
+  const oldStartMarker = "<!-- NUXT_DOCS_START -->";
+  const oldEndMarker = "<!-- NUXT_DOCS_END -->";
   if (content.includes(START_MARKER) && content.includes(END_MARKER)) {
-    const regex = new RegExp(`${START_MARKER}[\\s\\S]*${END_MARKER}`, "m");
+    const regex = new RegExp(`${escapeRegex(START_MARKER)}[\\s\\S]*${escapeRegex(END_MARKER)}`, "m");
+    content = content.replace(regex, nuxtSection);
+  } else if (content.includes(oldStartMarker) && content.includes(oldEndMarker)) {
+    const regex = new RegExp(`${escapeRegex(oldStartMarker)}[\\s\\S]*${escapeRegex(oldEndMarker)}`, "m");
     content = content.replace(regex, nuxtSection);
   } else if (content.length > 0) {
     content = content.trimEnd() + `
@@ -256,60 +262,34 @@ async function injectAgentsMd(outputPath, index, nuxtVersion, docsDir, minify) {
     content = generateFullAgentsMd(nuxtSection);
   }
   writeFileSync(outputPath, content);
+  generateClaudeMd(outputPath);
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function generateClaudeMd(agentsMdPath) {
+  const dir = dirname(agentsMdPath);
+  const claudeMdPath = join4(dir, "CLAUDE.md");
+  const agentsMdFilename = agentsMdPath.split("/").pop() || "AGENTS.md";
+  const claudeMdContent = `@${agentsMdFilename}
+`;
+  writeFileSync(claudeMdPath, claudeMdContent, "utf-8");
 }
 function generateNuxtSection(index, nuxtVersion, docsDir, minify) {
-  const majorVersion = nuxtVersion.split(".")[0];
   return `${START_MARKER}
-## Nuxt Documentation
 
-This project uses **Nuxt ${majorVersion}** (v${nuxtVersion}).
+# Nuxt: ALWAYS read docs before coding
 
-When working with Nuxt APIs, ALWAYS read the referenced documentation files before making changes.
-
-### Quick Reference Index
+This project uses Nuxt v${nuxtVersion}. Before any Nuxt work, find and read the relevant doc in \`${docsDir}/\`. Your training data may be outdated — the docs are the source of truth.
 
 \`\`\`
 ${minify ? index.minified : index.full}
 \`\`\`
 
-### Key Nuxt ${majorVersion} Patterns
-
-#### Data Fetching
-- Use \`useFetch\` for component-level data fetching (auto-deduped, SSR-safe)
-- Use \`useAsyncData\` when you need more control over the key/handler
-- Use \`$fetch\` in event handlers and server routes (NOT in setup for SSR)
-- Always handle \`pending\` and \`error\` states
-
-#### Server Routes
-- Files in \`server/api/\` become API endpoints
-- Use \`defineEventHandler\` for all handlers
-- Access body with \`readBody(event)\`
-- Access query with \`getQuery(event)\`
-- Access params with \`event.context.params\`
-
-#### State Management
-- Use \`useState\` for SSR-friendly reactive state
-- Use \`useCookie\` for cookie-based state
-- Use \`useRuntimeConfig\` for environment variables
-
-#### Routing & Navigation
-- Use \`definePageMeta\` for page-level config
-- Use \`navigateTo\` for programmatic navigation
-- Use \`useRoute\` and \`useRouter\` for route info
-
-#### Configuration
-- \`nuxt.config.ts\` for build-time config
-- \`runtimeConfig\` for environment variables (private/public)
-- \`app.config.ts\` for public runtime config
-
 ${END_MARKER}`;
 }
 function generateFullAgentsMd(nuxtSection) {
-  return `# AGENTS.md
-
-This file provides documentation references for AI coding agents.
-
-${nuxtSection}
+  return `${nuxtSection}
 `;
 }
 
@@ -354,7 +334,8 @@ async function generateAgentsMd(options = {}) {
   if (updateGitignore(docsDir)) {
     console.log(`Added ${docsDir} to .gitignore`);
   }
-  console.log(`Generated ${outputPath}`);
+  const claudeMdPath = outputPath.replace(/[^/]+$/, "CLAUDE.md");
+  console.log(`Generated ${outputPath} and ${claudeMdPath}`);
 }
 
 // src/cli.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-agent-md",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Generate AGENTS.md with Nuxt documentation for AI coding agents",
   "type": "module",
   "bin": {