You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/docs/practical-techniques/lesson-6-project-onboarding.md
+25-11Lines changed: 25 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -17,34 +17,48 @@ This lesson covers context files and how to structure them across user, project,
17
17
18
18
## The Context File Ecosystem
19
19
20
-
Context files are markdown documents that inject project-specific knowledge between the system prompt and your input, giving AI agents "project memory" without requiring repeated explanations of your tech stack, conventions, and architecture. The industry has converged on two approaches: `AGENTS.md` (vendor-neutral standard working across all AI tools) and tool-specific extensions like `CLAUDE.md` (for advanced features like hierarchical context).
20
+
Context files are markdown documents that inject project-specific knowledge between the system prompt and your input, giving AI agents "project memory" without requiring repeated explanations of your tech stack, conventions, and architecture. The industry has converged on two approaches: `AGENTS.md` (vendor-neutral standard working across most major AI tools like Cursor, Windsurf, and GitHub Copilot) and tool-specific extensions like `CLAUDE.md` (for advanced features like hierarchical context in Claude Code).
`AGENTS.md` is the vendor-neutral standard adopted by 20,000+ open-source projects, working across OpenAI Codex, GitHub Copilot, Cursor, and other AI coding tools. Keep it minimal—your README should contain 90% of what AI needs; AGENTS.md adds only AI-specific operational context like MCP server configurations, environment variables, modified test commands for non-interactive execution, and warnings about non-obvious dependencies. Place it in your repository root for maximum compatibility.
25
+
`AGENTS.md` is the vendor-neutral standard adopted by 20,000+ open-source projects, working across GitHub Copilot, Cursor, Windsurf, and most other AI coding tools (note: Claude Code does not support AGENTS.md—use CLAUDE.md instead). Keep it minimal—your README should contain 90% of what AI needs; AGENTS.md adds only AI-specific operational context like MCP server configurations, environment variables, modified test commands for non-interactive execution, and warnings about non-obvious dependencies. Place it in your repository root for maximum compatibility.
Claude Code's `CLAUDE.md` uses hierarchical context where multiple files from different directories (global `~/.claude/CLAUDE.md`, project root, subdirectories) are automatically loaded and merged based on your working directory, with more specific instructions overriding general ones while non-conflicting rules from all levels remain active. This layered system lets you define universal preferences globally, project standards at the root, and module-specific overrides in subdirectories—without duplicating rules. Reference `AGENTS.md` from `CLAUDE.md` to maintain cross-tool compatibility (see Cross-Referencing section below).
30
+
Claude Code's `CLAUDE.md` uses hierarchical context where multiple files from different directories (global `~/.claude/CLAUDE.md`, project root, subdirectories) are automatically loaded and merged based on your working directory, with more specific instructions overriding general ones while non-conflicting rules from all levels remain active. This layered system lets you define universal preferences globally, project standards at the root, and module-specific overrides in subdirectories—without duplicating rules.
|**File location**| Single file at repository root | Multiple files at any level |
40
+
|**Context loading**| One file only | All applicable files merged |
41
+
|**Hierarchy**| No | Yes (global → root → subdirs) |
42
+
|**Override behavior**| N/A (single file) | Specific overrides general |
43
+
|**Merge behavior**| N/A (single file) | All files injected together |
44
+
|**Tool support**|GitHub Copilot, Cursor, Windsurf, etc. (not Claude Code)| Claude Code only |
45
45
46
46
**Key takeaway:** AGENTS.md is one universal file. CLAUDE.md is a hierarchical system where multiple files are loaded and merged based on your working directory.
47
47
48
+
:::tip Mixed Ecosystem: Using Claude Code with AGENTS.md
49
+
Claude Code is the only major AI coding assistant that doesn't support AGENTS.md natively. If you're working in a mixed-tool environment (e.g., team members use Codex/Copilot while you use Claude Code), avoid duplicating content by using **@linking** in your `CLAUDE.md` to reference the shared `AGENTS.md`:
50
+
51
+
```markdown
52
+
# CLAUDE.md - Claude-specific configurations
53
+
54
+
@/AGENTS.md
55
+
56
+
# Additional Claude Code-specific context below
57
+
```
58
+
59
+
This imports the entire AGENTS.md content into Claude's context, maintaining a single source of truth while supporting both file formats.
60
+
:::
61
+
48
62
:::warning Security Consideration
49
63
Context files are injected directly into system prompts. Security researchers have identified "Rules File Backdoor" attacks where malicious instructions are injected using Unicode characters or evasion techniques. Keep context files minimal, version-controlled, and code-reviewed like any other code.
0 commit comments