docs: add CLAUDE.md/AGENTS.md guidance to AI tooling page

Add a section recommending project-level instruction files to prevent
LLMs from using nargo compile/test instead of aztec compile/test.
Includes a copy-paste template and explanation of the training data gap.

Applied to both nightly source and devnet.2 versioned docs.

Author: critesjosh

docs/developer_versioned_docs/version-v4.0.0-devnet.2-patch.1/ai_tooling.md

@@ -11,6 +11,32 @@ Aztec is new, rapidly evolving, and spans novel concepts like private state, not
 LLMs have limited training data for zero-knowledge circuit development. Noir and Aztec.nr are newer languages with smaller codebases than mainstream languages, so AI tools will make more mistakes than you might be used to. The tools on this page help by providing up-to-date context, but you should always verify generated code and test thoroughly.
 :::
 
+## Project-level instructions (CLAUDE.md / AGENTS.md files)
+
+MCP servers and skills provide context on demand, but AI tools don't always invoke them at the right time. The most reliable way to prevent common mistakes is to add **project-level instruction files** that your AI tool reads automatically at the start of every conversation. You can add to these files over time as you discover new gotchas or best practices. They ensure your AI tool always has the critical context it needs, without relying on you to remember to invoke the right skills or MCP servers.
+
+For Claude Code, create a `CLAUDE.md` file in your project root. For Codex, create an `AGENTS.md` file in your project root. For other tools, check their documentation for equivalent configuration.
+
+### Recommended CLAUDE.md / AGENTS.md
+
+```markdown
+# Aztec Project
+
+## Critical: Use `aztec` CLI, not `nargo` directly
+
+This is an Aztec smart contract project. Always use the `aztec` CLI wrapper instead of calling `nargo` directly:
+
+- **Compile**: `aztec compile` (NOT `nargo compile`). Using `nargo compile` alone produces incomplete artifacts.
+- **Test**: `aztec test` (NOT `nargo test`).
+- **Other nargo commands** like `nargo fmt` and `nargo doc` are fine to use directly.
+```
+
+This prevents the most common AI mistake: using `nargo compile` and `nargo test` instead of their Aztec wrappers.
+
+### Why this matters
+
+LLMs have extensive training data for `nargo` (the standalone Noir compiler) but limited exposure to the `aztec` CLI wrapper. Without explicit instructions, they default to `nargo compile`, which produces artifacts missing the AVM transpilation step.
+
 ## MCP servers
 
 The highest-leverage tools are the Aztec and Noir MCP servers. They clone reference repositories locally and give your AI tool code search, documentation search, and example discovery across the Aztec and Noir ecosystems. They work with any AI coding tool that supports MCP (Claude Code, Cursor, Windsurf, Codex, and others).

docs/docs-developers/ai_tooling.md

@@ -11,6 +11,32 @@ Aztec is new, rapidly evolving, and spans novel concepts like private state, not
 LLMs have limited training data for zero-knowledge circuit development. Noir and Aztec.nr are newer languages with smaller codebases than mainstream languages, so AI tools will make more mistakes than you might be used to. The tools on this page help by providing up-to-date context, but you should always verify generated code and test thoroughly.
 :::
 
+## Project-level instructions (CLAUDE.md / AGENTS.md files)
+
+MCP servers and skills provide context on demand, but AI tools don't always invoke them at the right time. The most reliable way to prevent common mistakes is to add **project-level instruction files** that your AI tool reads automatically at the start of every conversation. You can add to these files over time as you discover new gotchas or best practices. They ensure your AI tool always has the critical context it needs, without relying on you to remember to invoke the right skills or MCP servers.
+
+For Claude Code, create a `CLAUDE.md` file in your project root. For Codex, create an `AGENTS.md` file in your project root. For other tools, check their documentation for equivalent configuration.
+
+### Recommended CLAUDE.md / AGENTS.md
+
+```markdown
+# Aztec Project
+
+## Critical: Use `aztec` CLI, not `nargo` directly
+
+This is an Aztec smart contract project. Always use the `aztec` CLI wrapper instead of calling `nargo` directly:
+
+- **Compile**: `aztec compile` (NOT `nargo compile`). Using `nargo compile` alone produces incomplete artifacts.
+- **Test**: `aztec test` (NOT `nargo test`).
+- **Other nargo commands** like `nargo fmt` and `nargo doc` are fine to use directly.
+```
+
+This prevents the most common AI mistake: using `nargo compile` and `nargo test` instead of their Aztec wrappers.
+
+### Why this matters
+
+LLMs have extensive training data for `nargo` (the standalone Noir compiler) but limited exposure to the `aztec` CLI wrapper. Without explicit instructions, they default to `nargo compile`, which produces artifacts missing the AVM transpilation step.
+
 ## MCP servers
 
 The highest-leverage tools are the Aztec and Noir MCP servers. They clone reference repositories locally and give your AI tool code search, documentation search, and example discovery across the Aztec and Noir ecosystems. They work with any AI coding tool that supports MCP (Claude Code, Cursor, Windsurf, Codex, and others).