{ "schemaVersion": 1, "updatedAt": "2026-10-15", "dimensions": [ "discovery", "hierarchy", "conditionalActivation", "manualActivation", "managedEnforcement" ], "contracts": [ { "harness": "claude-code", "variant": "claude-md-and-agents-md-documented", "default": true, "versionAdded": "2.1.277", "support": { "discovery": "native", "hierarchy": "native", "conditionalActivation": "native", "manualActivation": "partial", "managedEnforcement": "partial" }, "sources": [ { "name": "managed-CLAUDE.md", "scope": "managed", "format": "markdown" }, { "name": "managed-settings-claudeMd", "scope": "managed", "format": "markdown-in-json-string" }, { "name": "user-CLAUDE.md", "scope": "user", "format": "markdown" }, { "name": "user-.claude/rules", "scope": "user", "format": "markdown-with-yaml-frontmatter" }, { "name": "project-CLAUDE.md", "scope": "project", "format": "markdown" }, { "name": "project-.claude/CLAUDE.md", "scope": "project", "format": "markdown" }, { "name": "project-.claude/rules", "scope": "project", "format": "markdown-with-yaml-frontmatter" }, { "name": "CLAUDE.local.md", "scope": "project", "format": "markdown" }, { "name": "project-AGENTS.md", "scope": "project", "format": "markdown" }, { "name": "project-.claude/AGENTS.md", "scope": "project", "format": "markdown" }, { "name": "subdirectory-CLAUDE.md", "scope": "directory", "format": "markdown" }, { "name": "subdirectory-CLAUDE.local.md", "scope": "directory", "format": "markdown" }, { "name": "subdirectory-AGENTS.md", "scope": "directory", "format": "markdown" } ], "merge": "All applicable files are concatenated into context (none replaces another); subdirectory files and path-scoped rules are appended later when Claude touches matching files.", "precedence": "Load order is managed, then user (CLAUDE.md, ~/.claude/rules), then project files from the filesystem root down to the working directory with CLAUDE.local.md after CLAUDE.md in each directory, so later (more specific) text is read last; there is no override, and conflicts are resolved arbitrarily by the model.", "instructionFiles": { "field": "pluginConfigs.cc-plugin-agents-md@builtin.options.instructionFiles", "default": "claude-md-or-agents-md", "modes": ["claude-md-or-agents-md", "claude-md-and-agents-md", "claude-md", "managed-only"], "scopes": ["user", "--settings", "managed"], "suppressesAgentsMd": ["CLAUDE.md", ".claude/CLAUDE.md", "CLAUDE.local.md"], "ignoredSources": ["AGENTS.local.md", "AGENTS.override.md", ".agents/"], "unavailableConditions": [ "client-before-2.1.277", "agents-md-plugin-disabled", "some-first-sessions-after-upgrade-from-2.1.276-or-earlier", "before-2.1.281-some-Bedrock-or-telemetry-disabled-sessions" ] }, "evidence": ["claude-memory-docs"], "reference": "https://code.claude.com/docs/en/memory#agents-md", "notes": [ "User and managed CLAUDE.md and .claude/rules do not suppress AGENTS.md fallback.", "Direct AGENTS.md loads do not fire InstructionsLoaded hooks; imports through CLAUDE.md do.", "Instructions provide context, not enforced operation policy." ], "observedVersion": "2.1.299", "answers": { "files": { "status": "supported", "answer": "Claude Code reads `CLAUDE.md`, `.claude/CLAUDE.md`, `CLAUDE.local.md` (personal, gitignored), every `.md` under `.claude/rules/` (recursively) and `~/.claude/rules/`, plus `~/.claude/CLAUDE.md` and a managed-policy `CLAUDE.md`. Since v2.1.277 it also reads `AGENTS.md` and `.claude/AGENTS.md`, by default only as a fallback when no `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` exists in the working directory or above. It never reads `AGENTS.local.md`, `AGENTS.override.md` or anything under `.agents/`.", "reference": "https://code.claude.com/docs/en/memory#choose-where-to-put-claude-md-files", "evidence": ["claude-memory-docs"], "notes": [ "`~/.claude/CLAUDE.md`, the managed CLAUDE.md and `.claude/rules/` files don't count as a CLAUDE.md for the AGENTS.md fallback check; adding a `CLAUDE.local.md` does, and stops AGENTS.md loading." ] }, "where": { "status": "supported", "answer": "At launch it loads the managed file (macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`, Linux/WSL `/etc/claude-code/CLAUDE.md`, Windows `C:\\Program Files\\ClaudeCode\\CLAUDE.md`), `~/.claude/CLAUDE.md`, and the `CLAUDE.md`/`CLAUDE.local.md` files in the working directory and every directory above it up to the filesystem root. Files in subdirectories below the working directory load on demand, the first time Claude reads, writes or edits a file in that subdirectory (including a single-file `cat`/`head` via Bash). A subdirectory `AGENTS.md` loads when Claude opens a file there with the Read tool and that subdirectory has no CLAUDE.md file of its own.", "reference": "https://code.claude.com/docs/en/memory#how-claude-md-files-load", "evidence": ["claude-memory-docs"], "notes": [ "Directories added with `--add-dir` don't contribute instruction files unless `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` is set, and even then their `AGENTS.md` doesn't load.", "Subdirectory files and path-scoped rules don't appear under Memory files in `/context`; a `Loaded` line with the path appears in the terminal when they load." ] }, "combine": { "status": "supported", "answer": "Every applicable file is concatenated into context; nothing overrides anything. Order is managed, user, then project files from the filesystem root down to your working directory, with `CLAUDE.local.md` after `CLAUDE.md` in each directory and user rules before project rules, so the most specific text comes last. If two instructions conflict, Claude may follow either one, so keep them consistent; with `claude-md-and-agents-md` mode each directory's `CLAUDE.md` files come before its `AGENTS.md`.", "reference": "https://code.claude.com/docs/en/memory#how-claude-md-files-load", "evidence": ["claude-memory-docs"], "notes": [ "CLAUDE.md content is sent as a user message after the system prompt, and Claude treats it as guidance, not enforced configuration; use hooks or permissions for hard rules." ] }, "limits": { "status": "supported", "answer": "Claude Code loads a CLAUDE.md of up to 4 MiB in full and skips any larger file entirely. Files over the recommended length (about 200 lines) trigger a startup and `/status` warning, and a second warning fires when many files and `@` imports together pass a combined limit; that threshold scales with the model's context window. A `paths` list is capped at 1,000 brace-expanded patterns / 4 MiB, and patterns past the budget are used unexpanded.", "reference": "https://code.claude.com/docs/en/memory#my-claude-md-is-too-large", "evidence": ["claude-memory-docs"], "notes": [ "The 200-line / 25KB truncation applies only to auto memory's `MEMORY.md`, not to CLAUDE.md." ] }, "shared": { "status": "supported", "answer": "Yes. With the default Project instructions mode `claude-md-or-agents-md`, a repo with only `AGENTS.md` works as-is; set `claude-md-and-agents-md` to read both, or `claude-md` to ignore AGENTS.md. Set it in `/config` or in `~/.claude/settings.json` / `--settings` / managed settings under `pluginConfigs[\"cc-plugin-agents-md@builtin\"].options.instructionFiles` (ignored in project and local settings). Alternatively put `@AGENTS.md` in a CLAUDE.md, which works on any version and never double-loads.", "reference": "https://code.claude.com/docs/en/memory#choose-which-instruction-files-load", "evidence": [ "claude-memory-docs", "memory-claude-code-code-claude-com-docs-en-settings-reference", "claude-changelog" ], "notes": [ "Direct AGENTS.md reading needs v2.1.277+ and the built-in plugin enabled; before v2.1.281 it didn't work on Bedrock/Vertex/Foundry or with telemetry off. Before v2.1.285 the plugin ID was `agents-md@builtin` (still accepted).", "Other tools' files such as `.cursor/rules`, `.github/copilot-instructions.md` or `GEMINI.md` aren't read at runtime; `/init` and `/import` copy them into CLAUDE.md once." ] }, "scoped": { "status": "supported", "answer": "Yes: a `.claude/rules/*.md` file with YAML frontmatter `paths:` (a list or comma-separated globs, brace expansion allowed, e.g. `src//*.{ts,tsx}`) loads only when Claude reads, writes or edits a matching file; `paths` is the only frontmatter field read. There's no dedicated on-demand rule mechanism; you can @-mention a rule file in your prompt to attach it like any file, and the docs point to skills for instructions loaded only when asked for.", "reference": "https://code.claude.com/docs/en/memory#path-specific-rules", "evidence": ["claude-memory-docs", "claude-changelog"], "notes": [ "If the frontmatter YAML doesn't parse, the rule loads unconditionally; `claude --debug` shows the parse error.", "Path-scoped rules that live in a symlinked directory outside the project don't load even after external imports are approved; only unscoped ones do.", "Path-scoped rules are summarized away by compaction and reload on the next matching file access." ] }, "imports": { "status": "supported", "answer": "Yes: write `@path/to/file` anywhere in a CLAUDE.md or AGENTS.md (relative to the importing file, absolute, or `@~/...`); imported files load at launch and can import further, up to four hops deep. Escape spaces with `\\ `; imports inside code spans or fenced blocks are ignored. Imports in a project file that resolve outside the working directory need a one-time approval dialog; imports in user-scope files load without it.", "reference": "https://code.claude.com/docs/en/memory#import-additional-files", "evidence": ["claude-memory-docs"], "notes": [ "Imports organize content but don't save context: imported files load in full at launch.", "An external import inside a directly-read AGENTS.md loads only if external imports were already approved for the project, with no prompt." ] }, "extra": { "status": "supported", "answer": "Use `--append-system-prompt \"...\"` or `--append-system-prompt-file ` to add system-prompt-level text, or `--system-prompt`/`--system-prompt-file` to replace the default prompt. `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1` with `--add-dir ` loads that directory's `CLAUDE.md`, `.claude/CLAUDE.md`, `.claude/rules/*.md` and `CLAUDE.local.md`, and admins can inline instructions with the managed-settings key `claudeMd`. URLs aren't supported as instruction sources.", "reference": "https://code.claude.com/docs/en/cli-reference#system-prompt-flags", "evidence": [ "claude-cli-reference-docs", "claude-memory-docs", "memory-claude-code-code-claude-com-docs-en-settings-reference" ], "notes": [ "`--append-subagent-system-prompt(-file)` adds text to subagent prompts in `-p` mode only.", "In resumed conversations the recorded system prompt is reused; pass `--system-prompt-snapshot off` while iterating on appended text." ] }, "managed": { "status": "partial", "answer": "Admins can deploy a managed `CLAUDE.md` (macOS `/Library/Application Support/ClaudeCode/CLAUDE.md`, Linux/WSL `/etc/claude-code/CLAUDE.md`, Windows `C:\\Program Files\\ClaudeCode\\CLAUDE.md`) or set `claudeMd` in managed settings. It loads before user and project files and `claudeMdExcludes` can't exclude it. Managed settings can also set `instructionFiles` to `managed-only`, which leaves out user and project CLAUDE.md, rules and AGENTS.md at launch.", "reference": "https://code.claude.com/docs/en/memory#deploy-organization-wide-claude-md", "evidence": [ "claude-memory-docs", "memory-claude-code-code-claude-com-docs-en-settings-reference", "claude-cli-reference-docs" ], "notes": [ "A user can still start with `--safe-mode` (or `CLAUDE_CODE_SAFE_MODE=1`), which skips managed CLAUDE.md along with other customizations.", "Instructions are guidance, not enforcement; use managed `permissions.deny`, sandbox settings or hooks for hard limits.", "In `managed-only` mode, subdirectory CLAUDE.md files and path-scoped rules still load on demand." ] }, "check": { "status": "supported", "answer": "Run `/context` and look under Memory files for what loaded at launch; `/memory` lists CLAUDE.md, CLAUDE.local.md and directly-read AGENTS.md paths (v2.1.280+) and opens them in your editor. On-demand files print a `Loaded ` line, and an `InstructionsLoaded` hook receives `file_path`, `memory_type` and `load_reason` (`session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact`) for each CLAUDE.md or rule load. There's no dedicated reload command; `/compact` re-reads the project-root CLAUDE.md and unscoped rules from disk, and a new session picks up all edits.", "reference": "https://code.claude.com/docs/en/debug-your-config#see-what-loaded-into-context", "evidence": [ "instructions-claude-code-code-claude-com-docs-en-debug-your-config", "claude-memory-docs", "claude-hooks-docs", "instructions-claude-code-code-claude-com-docs-en-context-window" ], "notes": [ "`InstructionsLoaded` doesn't fire for an AGENTS.md read directly through the Project instructions setting, only for one imported by or symlinked from a CLAUDE.md.", "Changing the Project instructions mode applies from your next message." ] }, "disable": { "status": "supported", "answer": "To skip instruction files for a run, use `--bare` (or `CLAUDE_CODE_SIMPLE=1`), `--safe-mode`, or `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1`; `--setting-sources user` drops project files and rules. To skip specific files, list absolute paths or globs in `claudeMdExcludes` in any settings file (arrays merge across layers), e.g. `\"claudeMdExcludes\": [\"/vendor//CLAUDE.md\"]`. Set `instructionFiles` to `claude-md` to ignore AGENTS.md, and set `omitClaudeMd` in a subagent definition to start that subagent without user, project and local CLAUDE.md.", "reference": "https://code.claude.com/docs/en/memory#exclude-specific-claude-md-files", "evidence": [ "claude-memory-docs", "claude-cli-reference-docs", "compaction-3", "memory-claude-code-code-claude-com-docs-en-settings-reference", "claude-changelog" ], "notes": [ "`claudeMdExcludes` can't exclude the managed CLAUDE.md.", "The built-in Explore and Plan subagents skip CLAUDE.md at startup." ] }, "create": { "status": "supported", "answer": "`/init` analyzes the codebase and writes a starter `CLAUDE.md`, or suggests improvements if one exists; it also folds in `.cursor/rules`/`.cursorrules` and `.github/copilot-instructions.md`. With `CLAUDE_CODE_NEW_INIT=1` it runs an interactive flow that can also set up `CLAUDE.local.md` (added to `.gitignore`), skills and hooks, and reads `AGENTS.md`, `.windsurf/rules`, `.clinerules` and `.devin/rules`. `/import [codex|gemini|cursor]` copies another agent's instruction files into CLAUDE.md, and `/doctor prompt-audit` audits existing instruction files.", "reference": "https://code.claude.com/docs/en/memory#set-up-a-project-claude-md", "evidence": ["claude-memory-docs", "claude-commands-docs"], "notes": [ "`/import` needs v2.1.213+ (Cursor v2.1.265+) and isn't available on Bedrock, Vertex, Foundry or with feature-flag fetching off; `/doctor prompt-audit` needs v2.1.283+." ] } } }, { "harness": "codex", "variant": "agents-md-current", "default": true, "support": { "discovery": "native", "hierarchy": "native", "conditionalActivation": "partial", "manualActivation": "unsupported", "managedEnforcement": "native" }, "sources": [ { "name": "global-AGENTS.override.md", "scope": "user", "format": "markdown" }, { "name": "global-AGENTS.md", "scope": "user", "format": "markdown" }, { "name": "project-AGENTS.override.md", "scope": "project", "format": "markdown" }, { "name": "project-AGENTS.md", "scope": "project", "format": "markdown" }, { "name": "nested-AGENTS.override.md", "scope": "directory", "format": "markdown" }, { "name": "nested-AGENTS.md", "scope": "directory", "format": "markdown" }, { "name": "project_doc_fallback_filenames", "scope": "project", "format": "markdown" }, { "name": "config-developer_instructions", "scope": "user", "format": "toml-string" }, { "name": "requirements-additional_developer_instructions", "scope": "managed", "format": "toml-string" } ], "merge": "The single global file (~/.codex/AGENTS.override.md or AGENTS.md) comes first, then at most one file per directory from the project root down to the working directory, all concatenated in that order into one AGENTS.md instructions message.", "precedence": "Nothing is dropped on conflict; later (deeper, closer to the working directory) files appear last and the built-in prompt tells the model that more-deeply-nested AGENTS.md files and direct prompt instructions win, while in each directory AGENTS.override.md beats AGENTS.md, which beats fallback names.", "evidence": ["codex-agents-md-docs"], "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance", "notes": [ "At each level, an override file wins over AGENTS.md and configured fallback names.", "Codex skips empty files and applies a configurable combined-byte limit.", "Instructions are persistent context, not skills and not permission grants." ], "observedVersion": "0.162.1", "answers": { "files": { "status": "supported", "answer": "Codex reads `AGENTS.md`, plus `AGENTS.override.md`, which takes the place of `AGENTS.md` in the same directory. Extra names listed in `project_doc_fallback_filenames` (e.g. `[\"TEAM_GUIDE.md\", \"CLAUDE.md\"]`) are tried only in project directories that have neither file. There is no rules directory, and it does not read `CLAUDE.md` unless you list it.", "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance", "evidence": [ "codex-agents-md-docs", "instructions-codex-codex-rs-core-src-agents-md-rs", "instructions-codex-codex-rs-codex-home-src-instructions-mod-rs" ], "notes": [ "Fallback names apply only to project directories, not to `~/.codex`.", "Fallback entries must be plain file names; entries containing `/` are ignored." ] }, "where": { "status": "supported", "answer": "Global: `~/.codex` (or `$CODEX_HOME`). Project: every directory from the project root (the nearest parent containing `.git`, or any marker set in `project_root_markers`) down to the current working directory; with no root found, only the working directory is checked. Files are read when the session starts. Files in subdirectories below the working directory are never loaded automatically. Codex's built-in prompt only tells the model to look for them itself when it works there.", "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance", "evidence": [ "codex-agents-md-docs", "instructions-codex-learn-chatgpt-com-docs-config-file-config-advanced", "instructions-codex-codex-rs-core-src-agents-md-rs", "instructions-codex-codex-rs-protocol-src-prompts-base-instructions-default-md" ], "notes": [ "In an untrusted project Codex skips project AGENTS.md files entirely and keeps only the global file.", "`project_root_markers = []` stops the upward search, so only the working directory is checked.", "Codex reads `project_root_markers` from user, system and managed config only; a project's own `.codex/config.toml` can't change it." ] }, "combine": { "status": "supported", "answer": "All applicable files are concatenated: the global file first, then project files from the root down to the working directory, separated by blank lines (with a `--- project-doc ---` marker before the first project file). Nothing is merged or deduplicated. Closer files appear later and win by convention, and in each directory only the first of `AGENTS.override.md`, `AGENTS.md` and fallback names is used.", "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance", "evidence": [ "codex-agents-md-docs", "instructions-codex-codex-rs-core-src-agents-md-rs", "instructions-codex-codex-rs-protocol-src-prompts-base-instructions-default-md" ], "notes": [ "Instructions you type in the prompt, and `developer_instructions`, take precedence over AGENTS.md according to Codex's built-in prompt." ] }, "limits": { "status": "supported", "answer": "Project files share a combined budget of `project_doc_max_bytes` (default 32 KiB = 32768 bytes). The file that crosses the limit is cut off at the byte limit, and any later, deeper files are dropped. The only notice is a warning in the log. The global `~/.codex/AGENTS.md` doesn't count toward this budget.", "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance", "evidence": [ "codex-agents-md-docs", "instructions-codex-codex-rs-core-src-agents-md-rs", "instructions-codex-codex-rs-config-src-config-toml-rs" ], "notes": [ "Raise it with `project_doc_max_bytes = 65536` in `config.toml` or `-c project_doc_max_bytes=65536`.", "Because the root file is read first, an oversized root file can push out deeper, more specific files.", "Some config docs describe the limit as per file; in 0.162.1 the budget is shared by all project files." ] }, "shared": { "status": "partial", "answer": "Codex natively reads only `AGENTS.md`, which other harnesses also read. To reuse another tool's file, add it to `project_doc_fallback_filenames` (e.g. `project_doc_fallback_filenames = [\"CLAUDE.md\"]`); it is used only in directories without an `AGENTS.md`. `/import` can also make a one-time copy of `CLAUDE.md` into `AGENTS.md`, renaming Claude references to Codex.", "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#customize-fallback-filenames", "evidence": [ "codex-agents-md-docs", "codex-developer-commands-docs", "instructions-codex-codex-rs-external-agent-migration-src-service-rs" ], "notes": [ "`/import` writes only if the target `AGENTS.md` is missing or empty, and it doesn't keep the files in sync afterwards." ] }, "scoped": { "status": "partial", "answer": "The only scoping is by directory: put an `AGENTS.md` or `AGENTS.override.md` in a subdirectory and it applies when you start Codex in or below that directory. There are no globs, no frontmatter, and no @-mention rules that load on demand.", "reference": "https://learn.chatgpt.com/docs/agent-configuration/agents-md#layer-project-instructions", "evidence": [ "codex-agents-md-docs", "instructions-codex-codex-rs-core-src-agents-md-rs", "instructions-codex-codex-rs-protocol-src-prompts-base-instructions-default-md" ], "notes": [ "Files deeper than the working directory are not injected; the model is only told to look for them itself." ] }, "imports": { "status": "unsupported", "answer": "No. Codex inserts each file's text exactly as written, so `@path` or include lines are not expanded. You can still tell the model to read another file, and it will do so with its normal tools.", "reference": "https://github.com/openai/codex/blob/092d3acd6bec3e3a14bdc7e7a2810ab628ab759d/codex-rs/core/src/agents_md.rs#L145-L179", "evidence": ["instructions-codex-codex-rs-core-src-agents-md-rs", "codex-agents-md-docs"] }, "extra": { "status": "supported", "answer": "Set `developer_instructions = \"...\"` in `~/.codex/config.toml` (or a profile) to add a separate developer message, or pass it for one run with `-c developer_instructions='\"...\"'`. `model_instructions_file = \"/abs/path.md\"` replaces Codex's built-in base instructions entirely, and OpenAI strongly discourages this. `CODEX_HOME` changes which global `AGENTS.md` is used; there is no flag or URL source for instruction files.", "reference": "https://learn.chatgpt.com/docs/config-file/config-reference#configtoml", "evidence": [ "compaction-6", "instructions-codex-learn-chatgpt-com-docs-config-file-config-advanced", "instructions-codex-codex-rs-config-src-config-toml-rs", "codex-agents-md-docs" ], "notes": [ "The older `experimental_instructions_file` key is gone in 0.162.1; use `model_instructions_file`." ] }, "managed": { "status": "supported", "answer": "Yes. Admins set `additional_developer_instructions` in `requirements.toml` (`/etc/codex/requirements.toml`, `%ProgramData%\\OpenAI\\Codex\\requirements.toml`, cloud-managed requirements, or the macOS MDM key `requirements_toml_base64`). Codex adds it as its own developer message, separate from user files. Codex refuses to start if it exceeds about 10,000 estimated tokens. `managed_config.toml` can set defaults such as `developer_instructions`, but users can change those during a run.", "reference": "https://learn.chatgpt.com/docs/config-file/config-reference#requirementstoml", "evidence": [ "compaction-6", "instructions-codex-learn-chatgpt-com-docs-enterprise-managed-configuration", "instructions-codex-codex-rs-config-src-config-requirements-rs", "instructions-codex-re-src-context-world-state-managed-developer-instructions-rs" ], "notes": [ "Admins can't lock or block a repository's own AGENTS.md files; the managed text is added alongside them." ] }, "check": { "status": "supported", "answer": "Run `/status` in the TUI; its `Agents.md` line lists the loaded files (e.g. `~/.codex/AGENTS.md, AGENTS.md`). You can also ask Codex to list its instruction sources, or check the TUI log or session `.jsonl`. Edits to `~/.codex/AGENTS.md` are picked up on the next turn, but project files are only re-read when the working directory or trust level changes (e.g. `/cd`). Otherwise restart Codex.", "reference": "https://learn.chatgpt.com/docs/developer-commands#inspect-the-session-with-status", "evidence": [ "codex-developer-commands-docs", "codex-agents-md-docs", "instructions-codex-codex-rs-tui-src-status-card-rs", "instructions-codex-codex-rs-core-src-agents-md-manager-rs", "steering-codex-codex-rs-core-src-session-mod-rs" ], "notes": [ "When instructions change mid-session, Codex sends the model a note that the new AGENTS.md text replaces the old one.", "The docs say to restart Codex to pick up changes; there's no reload command." ] }, "disable": { "status": "partial", "answer": "There's no dedicated flag. `-c project_doc_max_bytes=0` turns off all project AGENTS.md files for a run, and leaving a project untrusted also skips them. The global file still loads; to avoid it, point `CODEX_HOME` at another directory or remove/rename `~/.codex/AGENTS.md`. You can't exclude individual files or directories.", "reference": "https://github.com/openai/codex/blob/092d3acd6bec3e3a14bdc7e7a2810ab628ab759d/codex-rs/core/src/agents_md.rs#L64-L72", "evidence": [ "instructions-codex-codex-rs-core-src-agents-md-rs", "codex-agents-md-docs", "instructions-codex-codex-rs-codex-home-src-instructions-mod-rs" ], "notes": [ "`--ignore-user-config` skips `config.toml` but still loads `~/.codex/AGENTS.md`." ] }, "create": { "status": "supported", "answer": "Yes: `/init` in the TUI asks Codex to write a contributor-guide `AGENTS.md` (\"Repository Guidelines\") in the current directory. It won't overwrite an `AGENTS.md` that already exists there. `/import` can also create `AGENTS.md` from a Claude Code `CLAUDE.md`.", "reference": "https://learn.chatgpt.com/docs/developer-commands#generate-agentsmd-with-init", "evidence": [ "codex-developer-commands-docs", "codex-slash-source-0-162-1", "instructions-codex-codex-rs-tui-assets-prompt-for-init-command-md" ], "notes": [ "`/init` only asks the model to write the file, so the result varies; review it before committing." ] } } }, { "harness": "cursor-agent", "variant": "rules-current", "default": true, "support": { "discovery": "native", "hierarchy": "native", "conditionalActivation": "native", "manualActivation": "native", "managedEnforcement": "native" }, "sources": [ { "name": "team-rules", "scope": "team", "format": "text (optional globs)" }, { "name": "project-.cursor/rules", "scope": "project", "format": "mdc" }, { "name": "nested-.cursor/rules", "scope": "directory", "format": "mdc" }, { "name": "project-AGENTS.md", "scope": "project", "format": "markdown" }, { "name": "nested-AGENTS.md", "scope": "directory", "format": "markdown" }, { "name": "CLAUDE.md / CLAUDE.local.md", "scope": "project", "format": "markdown" }, { "name": "legacy-.cursorrules", "scope": "project", "format": "text" }, { "name": "user-rules (account)", "scope": "user", "format": "text" }, { "name": "user-~/.cursor/rules", "scope": "user", "format": "mdc" }, { "name": "plugin-rules", "scope": "user", "format": "mdc" } ], "merge": "Every applicable rule (always-apply rules, glob- or description-matched rules, @-mentioned rules, AGENTS.md/CLAUDE.md files, team and user rules) is added to the start of the model context together; nothing is replaced by file name.", "precedence": "On conflicting guidance Team Rules win over Project Rules, which win over User Rules; among AGENTS.md files the one nearest the files being worked on takes precedence over its parents.", "evidence": ["cursor-rules-docs"], "reference": "https://cursor.com/docs/rules#how-rules-work", "notes": [ "Enforced team rules cannot be disabled by users.", "AGENTS.md is the plain-Markdown alternative to structured project rules." ], "observedVersion": "2026.10.12-d47ca18", "answers": { "files": { "status": "supported", "answer": "Project rules are `.mdc` files under `.cursor/rules/` (subfolders allowed; plain `.md` files there are ignored). The CLI also reads `AGENTS.md`, `CLAUDE.md` and `CLAUDE.local.md`, the legacy `.cursorrules` file at the repo root, user rule files in `~/.cursor/rules/`, plus User Rules and Team Rules stored on your Cursor account.", "reference": "https://cursor.com/docs/cli/using#rules", "evidence": [ "cursor-cli-using-docs", "cursor-rules-docs", "instructions-cursor-agent-cursor-com-help-customization-rules" ], "notes": [ "`.cursorrules` is deprecated; it is still loaded as an always-applied rule.", "`~/.claude/CLAUDE.md`, `.claude/rules/` and `GEMINI.md` are not read." ] }, "where": { "status": "supported", "answer": "At startup the CLI walks from the workspace directory up to the filesystem root, loading `.cursor/rules/`, `AGENTS.md`, `CLAUDE.md` and `CLAUDE.local.md` from each directory, so `~/.cursor/rules/` and `~/AGENTS.md` apply when you work under your home folder. It also scans subdirectories at startup for nested `.cursor/rules/`, `AGENTS.md` and `CLAUDE.md` (skipping folders such as `node_modules`, `dist` and `build`); nested files apply when the agent works with files in that directory or below. `.cursorrules` is read only from the git repo root.", "reference": "https://cursor.com/docs/cli/changelog#may-14-2026", "evidence": ["cursor-cli-changelog", "cursor-rules-docs", "cursor-cli-using-docs"], "notes": [ "The docs describe CLAUDE.md and AGENTS.md at the project root and in subdirectories; the CLI's walk up through parent directories is wider than the editor docs suggest." ] }, "combine": { "status": "supported", "answer": "All applicable rules are merged into the context; none replaces another. When guidance conflicts, Team Rules beat Project Rules, which beat User Rules, and a nested `AGENTS.md` takes precedence over the ones in its parent directories. Two rule files with the same name in different folders both apply.", "reference": "https://cursor.com/docs/rules#format-and-how-team-rules-are-applied", "evidence": [ "cursor-rules-docs", "instructions-cursor-agent-cursor-com-help-customization-rules" ] }, "limits": { "status": "partial", "answer": "There is no hard size limit or truncation of rule bodies; Cursor recommends keeping each rule under 500 lines and splitting larger ones. A rule's `description` is cut at 1,536 characters.", "reference": "https://cursor.com/docs/rules#best-practices", "evidence": ["cursor-rules-docs"], "notes": [ "Every always-applied rule, AGENTS.md and CLAUDE.md uses context window on every request, so long files cost tokens." ] }, "shared": { "status": "supported", "answer": "Yes. The CLI reads `AGENTS.md`, `CLAUDE.md` and `CLAUDE.local.md` alongside `.cursor/rules`, so one `AGENTS.md` or `CLAUDE.md` can serve Cursor, Codex, Claude Code and others. `CLAUDE.md` is always applied, ignoring any `alwaysApply` frontmatter. The CLI reads `CLAUDE.md` and `CLAUDE.local.md` only while its third-party configuration support is on, which is the default; `AGENTS.md` is always read.", "reference": "https://cursor.com/help/customization/rules#how-does-claudemd-work-in-cursor", "evidence": [ "instructions-cursor-agent-cursor-com-help-customization-rules", "cursor-cli-using-docs", "cursor-rules-docs" ], "notes": [ "Claude Code's `@path` imports inside CLAUDE.md are not expanded; Cursor treats them as plain text." ] }, "scoped": { "status": "supported", "answer": "Yes. In a `.mdc` rule, `alwaysApply: true` applies it always; `globs` (comma-separated, e.g. `src//*.tsx`) attaches it when a matching file is in context; a `description` alone lets the agent pull it in when relevant; with none of these it applies only when you `@`-mention it (e.g. `@my-rule`). Team Rules can also carry glob patterns.", "reference": "https://cursor.com/docs/rules#rule-anatomy", "evidence": ["cursor-rules-docs", "cursor-cli-changelog"], "notes": [ "`AGENTS.md` and `CLAUDE.md` have no frontmatter scoping; use their directory placement instead." ] }, "imports": { "status": "unsupported", "answer": "No. Writing `@file.ts` in a rule only tells the agent where to look; it reads the file with its tools when needed and the contents are never inlined. Put anything that must always be in context directly in the rule body.", "reference": "https://cursor.com/docs/rules#referencing-files-from-a-rule", "evidence": ["cursor-rules-docs"] }, "extra": { "status": "partial", "answer": "There is no flag or environment variable that injects instruction text. You can load extra rules with `--plugin-dir `, which loads a local plugin whose `rules/` folder holds `.mdc` rules, or by installing plugins from a marketplace; `--workspace ` chooses which project's rules load.", "reference": "https://cursor.com/docs/reference/plugins#rules-format", "evidence": [ "instructions-cursor-agent-cursor-com-docs-reference-plugins", "cursor-cli-parameters-docs", "cursor-plugins-docs" ] }, "managed": { "status": "supported", "answer": "Yes, on Team and Enterprise plans. Admins create Team Rules in the dashboard and tick Enforce this rule so members cannot turn them off; enforced and enabled Team Rules apply to every repository, including CLI sessions. Admins can also mark a plugin that ships rules as Required so it cannot be uninstalled.", "reference": "https://cursor.com/docs/rules#activation-and-enforcement", "evidence": ["cursor-rules-docs", "cursor-plugins-docs", "cursor-cli-changelog"], "notes": ["Non-enforced Team Rules can be switched off by each member in Customize."] }, "check": { "status": "partial", "answer": "Run `/rules` in a session to browse, open and edit the `.mdc` files in the project's `.cursor/rules/` and in `~/.cursor/rules/`. It does not list `AGENTS.md`, `CLAUDE.md` or Team Rules, and there is no view of which rules were applied to a turn. Rule files are read when the CLI starts, so restart it to pick up edits; there is no reload command.", "reference": "https://cursor.com/docs/cli/changelog#january-2026", "evidence": ["cursor-cli-changelog"], "notes": ["In the editor, Customize → Rules shows every rule and its status."] }, "disable": { "status": "partial", "answer": "There is no flag to skip instruction files for a run. To exclude a file, list an `AGENTS.md` or `CLAUDE.md` path in `.cursorignore`, or change a `.mdc` rule to manual (remove `alwaysApply`, `globs` and `description`). Non-enforced Team Rules can be turned off under Customize → Rules.", "reference": "https://cursor.com/docs/rules#activation-and-enforcement", "evidence": ["cursor-rules-docs"] }, "create": { "status": "supported", "answer": "`cursor-agent generate-rule` (alias `rule`) asks for a description, a scope (project `.cursor/rules/` or user `~/.cursor/rules/`) and a name, then writes a starter `.mdc`. In a session, `/rules` has a \"Create new rule\" entry where you pick the rule type and globs, and the built-in `/create-rule` skill has the agent write the rule for you. There is no `/init` that generates an `AGENTS.md`.", "reference": "https://cursor.com/docs/cli/reference/parameters#commands", "evidence": ["cursor-cli-parameters-docs", "cursor-rules-docs"] } } }, { "harness": "opencode", "variant": "1.x", "default": false, "support": { "discovery": "native", "hierarchy": "native", "conditionalActivation": "partial", "manualActivation": "partial", "managedEnforcement": "native" }, "sources": [ { "name": "global-AGENTS.md", "scope": "user", "format": "markdown" }, { "name": "global-CLAUDE.md-fallback", "scope": "user", "format": "markdown" }, { "name": "project-AGENTS.md", "scope": "project", "format": "markdown" }, { "name": "project-CLAUDE.md-fallback", "scope": "project", "format": "markdown" }, { "name": "project-CONTEXT.md-deprecated", "scope": "project", "format": "markdown" }, { "name": "nested-AGENTS.md", "scope": "directory", "format": "markdown" }, { "name": "config-instructions", "scope": "project", "format": "markdown" }, { "name": "managed-config-instructions", "scope": "managed", "format": "markdown" } ], "merge": "Every applicable file is concatenated into the system prompt as its own `Instructions from: ` block; nothing is overridden or deduplicated beyond identical paths.", "precedence": "Load order is the global file, then project AGENTS.md files nearest-first up to the git root, then `instructions` files, then `instructions` URLs; for each slot the first file name found wins (AGENTS.md over CLAUDE.md, ~/.config/opencode/AGENTS.md over ~/.claude/CLAUDE.md), but there is no conflict resolution between the blocks.", "observedVersion": "1.19.0", "answers": { "files": { "status": "supported", "answer": "OpenCode reads `AGENTS.md`. If no `AGENTS.md` is found it falls back to `CLAUDE.md` in the project (and the deprecated `CONTEXT.md` after that), and globally it reads `~/.config/opencode/AGENTS.md`, falling back to `~/.claude/CLAUDE.md`. Any other file (for example `CONTRIBUTING.md` or `.cursor/rules/*.md`) is only read if you list it in `instructions` in opencode.json.", "reference": "https://opencode.ai/docs/rules/#precedence", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "memory-opencode-packages-opencode-src-session-instruction-ts" ] }, "where": { "status": "supported", "answer": "At startup it loads the global file from `~/.config/opencode/AGENTS.md` (or `$OPENCODE_CONFIG_DIR/AGENTS.md`) plus every `AGENTS.md` from the current directory up to the git repository root; outside a git repo the walk goes all the way to `/`. `AGENTS.md` files in subdirectories below the current directory are attached when the agent uses the read tool on a file there, appended to that tool result.", "reference": "https://opencode.ai/docs/rules/#types", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "memory-opencode-packages-opencode-src-session-instruction-ts", "instructions-opencode-packages-core-src-fs-util-ts", "instructions-opencode-packages-opencode-src-project-project-ts", "instructions-opencode-packages-opencode-src-tool-read-ts", "instructions-opencode-packages-core-src-global-ts" ], "notes": [ "The docs say the first matching file wins, but every ancestor `AGENTS.md` up to the repo root is loaded; only the AGENTS.md-versus-CLAUDE.md choice is first-match.", "Nested files are only picked up by reading a file, not by listing a directory, and only for directories below where OpenCode was started." ] }, "combine": { "status": "supported", "answer": "All applicable files are concatenated into the system prompt, each prefixed with `Instructions from: `: the global file first, then the project `AGENTS.md` files nearest-first, then files and URLs from `instructions`. There is no override or conflict resolution, so contradictory rules are all sent to the model.", "reference": "https://opencode.ai/docs/rules/#custom-instructions", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "memory-opencode-packages-opencode-src-session-instruction-ts", "steering-opencode-packages-opencode-src-session-prompt-ts" ] }, "limits": { "status": "supported", "answer": "There is no size limit or truncation; whole files are included. Remote URLs in `instructions` are fetched with a 5-second timeout, and a URL that fails or times out is silently skipped.", "reference": "https://opencode.ai/docs/rules/#custom-instructions", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "memory-opencode-packages-opencode-src-session-instruction-ts" ] }, "shared": { "status": "supported", "answer": "Yes. `AGENTS.md` is the native file, and Claude Code's `CLAUDE.md` (project) and `~/.claude/CLAUDE.md` (global) are used when no `AGENTS.md` exists. Other tools' rules, such as `.cursor/rules/*.md` or `.github/copilot-instructions.md`, can be pulled in through the `instructions` array.", "reference": "https://opencode.ai/docs/rules/#claude-code-compatibility", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "instructions-opencode-packages-opencode-test-session-instruction-test-ts" ], "notes": [ "`OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1` (or `OPENCODE_DISABLE_CLAUDE_CODE=1`) turns off both the project `CLAUDE.md` and the `~/.claude/CLAUDE.md` fallbacks, not only the global one as the docs say." ] }, "scoped": { "status": "partial", "answer": "There are no glob or frontmatter rules. A nested `AGENTS.md` effectively applies only to its subtree, because it is attached only when the agent reads a file in that directory. For on-demand rules you can `@`-mention a file in the prompt, or tell the agent in `AGENTS.md` to read referenced files when relevant.", "reference": "https://opencode.ai/docs/rules/#manual-instructions-in-agentsmd", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "opencode-tui-docs", "memory-opencode-packages-opencode-src-session-instruction-ts" ] }, "imports": { "status": "unsupported", "answer": "No. OpenCode does not expand `@path` references inside `AGENTS.md`. To include more files, list them (globs allowed, e.g. `packages/*/AGENTS.md`) in the `instructions` array of opencode.json, or tell the agent in `AGENTS.md` to read them with its Read tool.", "reference": "https://opencode.ai/docs/rules/#referencing-external-files", "evidence": ["memory-opencode-opencode-ai-docs-rules"] }, "extra": { "status": "supported", "answer": "Yes, through the `instructions` array in global or project opencode.json: relative paths and globs, absolute or `~/` paths, and `http(s)://` URLs. Relative entries are matched in the current directory and every parent up to the repo root. There is no CLI flag, but config can be supplied with `OPENCODE_CONFIG`, `OPENCODE_CONFIG_DIR` or inline JSON in `OPENCODE_CONFIG_CONTENT`; per-agent text goes in the agent's `prompt`.", "reference": "https://opencode.ai/docs/config/#instructions", "evidence": [ "instructions-opencode-opencode-ai-docs-config", "memory-opencode-opencode-ai-docs-rules", "memory-opencode-packages-opencode-src-session-instruction-ts", "opencode-cli-stable-docs", "opencode-agents-docs" ], "notes": [ "`instructions` arrays from every config layer are merged as a union, so a project config adds to the global list rather than replacing it." ] }, "managed": { "status": "supported", "answer": "Yes, through managed config. Put an `instructions` array in `opencode.json` in the system directory (`/Library/Application Support/opencode` on macOS, `/etc/opencode` on Linux, `%ProgramData%\\opencode` on Windows) or in an MDM profile for the `ai.opencode.managed` domain. `instructions` arrays are merged as a union, so users can add rules but cannot remove managed entries.", "reference": "https://opencode.ai/docs/config/#managed-settings", "evidence": [ "instructions-opencode-opencode-ai-docs-config", "instructions-opencode-packages-opencode-src-config-config-ts" ], "notes": [ "Use absolute paths or URLs in managed `instructions`; relative entries resolve against the user's current project.", "Users can still write contradicting rules in their own files, since all instructions are just concatenated." ] }, "check": { "status": "partial", "answer": "There is no command that lists loaded instruction files. `opencode debug config` shows the resolved `instructions` list, and each loaded file appears in the model context as an `Instructions from: ` block. Files are re-read before every model request, so edits apply on the next step without a restart.", "reference": "https://github.com/anomalyco/opencode/blob/733b2c627e5aec39cb33cc22373bdce33053ef2c/packages/opencode/src/session/prompt.ts#L1257-L1266", "evidence": [ "steering-opencode-packages-opencode-src-session-prompt-ts", "memory-opencode-packages-opencode-src-session-instruction-ts", "opencode-cli-stable-docs" ] }, "disable": { "status": "partial", "answer": "`OPENCODE_DISABLE_PROJECT_CONFIG=1` skips project `AGENTS.md`/`CLAUDE.md` discovery and project config. `OPENCODE_DISABLE_CLAUDE_CODE_PROMPT=1` or `OPENCODE_DISABLE_CLAUDE_CODE=1` stops the `CLAUDE.md` fallbacks. There is no exclude list and no switch for the global `~/.config/opencode/AGENTS.md`; you have to remove or rename it.", "reference": "https://opencode.ai/docs/rules/#claude-code-compatibility", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "memory-opencode-packages-opencode-src-session-instruction-ts", "instructions-opencode-packages-opencode-src-effect-runtime-flags-ts", "opencode-cli-stable-docs" ], "notes": [ "Nested `AGENTS.md` files are still attached when the agent reads files in subdirectories, even with `OPENCODE_DISABLE_PROJECT_CONFIG=1`." ] }, "create": { "status": "supported", "answer": "Yes. `/init` scans the repo, may ask a few questions, and creates `AGENTS.md` at the project root, or improves an existing one in place. Text typed after `/init` is passed as extra focus.", "reference": "https://opencode.ai/docs/rules/#initialize", "evidence": [ "memory-opencode-opencode-ai-docs-rules", "opencode-tui-docs", "memory-opencode-packages-opencode-src-command-index-ts" ] } }, "evidence": [ "memory-opencode-opencode-ai-docs-rules", "memory-opencode-packages-opencode-src-session-instruction-ts", "instructions-opencode-packages-core-src-fs-util-ts", "instructions-opencode-packages-opencode-src-project-project-ts", "instructions-opencode-packages-opencode-src-tool-read-ts", "instructions-opencode-packages-core-src-global-ts", "steering-opencode-packages-opencode-src-session-prompt-ts", "instructions-opencode-packages-opencode-test-session-instruction-test-ts", "opencode-tui-docs", "instructions-opencode-opencode-ai-docs-config", "opencode-cli-stable-docs", "opencode-agents-docs", "instructions-opencode-packages-opencode-src-config-config-ts", "instructions-opencode-packages-opencode-src-effect-runtime-flags-ts", "memory-opencode-packages-opencode-src-command-index-ts" ], "reference": "https://opencode.ai/docs/rules/#precedence", "sourceRevision": "733b2c627e5aec39cb33cc22373bdce33053ef2c" }, { "harness": "opencode", "variant": "2.x", "default": true, "support": { "discovery": "native", "hierarchy": "native", "conditionalActivation": "partial", "manualActivation": "partial", "managedEnforcement": "unsupported" }, "sources": [ { "name": "global-AGENTS.md", "scope": "user", "format": "markdown" }, { "name": "ancestor-AGENTS.md", "scope": "project", "format": "markdown" }, { "name": "nested-AGENTS.md", "scope": "directory", "format": "markdown" } ], "merge": "The global file and every upward AGENTS.md are concatenated as `Instructions from: ` blocks; nested files found later are appended to session history; nothing is overridden.", "precedence": "Order is global first, then project files nearest-first (workspace directory, then its parents up to home or the project root); OpenCode does not resolve conflicts between them.", "observedVersion": "2.0.29", "answers": { "files": { "status": "supported", "answer": "Only `AGENTS.md`. V2 reads `~/.config/opencode/AGENTS.md` and `AGENTS.md` files in the project; it has no `CLAUDE.md` fallback.", "reference": "https://opencode.ai/v2/docs/instructions/#scope", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "memory-opencode-packages-core-src-config-plugin-instruction-ts", "instructions-opencode-opencode-ai-v2-docs-migrate-v1" ] }, "where": { "status": "supported", "answer": "At startup it loads `~/.config/opencode/AGENTS.md` (or `$OPENCODE_CONFIG_DIR/AGENTS.md`) and every `AGENTS.md` from the workspace directory up to your home directory, or up to the project root if the workspace is outside home. `AGENTS.md` files below the workspace are added during the session when the agent reads a file or lists a directory in that area.", "reference": "https://opencode.ai/v2/docs/instructions/#scope", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "memory-opencode-packages-core-src-config-plugin-instruction-ts", "instructions-opencode-packages-core-src-tool-plugin-read-ts", "instructions-opencode-packages-util-src-global-ts" ], "notes": [ "If the workspace is outside the project root, only the global file is loaded.", "Inside home the walk can go past the repository root, so an `AGENTS.md` in `~/code/` or `~` is loaded too." ] }, "combine": { "status": "supported", "answer": "All applicable files are combined, not overridden: the global file first, then project files nearest-first, each as an `Instructions from: ` block after the agent prompt and environment context. Nested files found later are added to the session history in discovery order, and OpenCode does not resolve conflicts between them.", "reference": "https://opencode.ai/v2/docs/instructions/#ordering", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "instructions-opencode-packages-core-src-instruction-discovery-ts", "memory-opencode-packages-core-src-config-plugin-instruction-ts" ] }, "limits": { "status": "supported", "answer": "There is no size limit or truncation. Each file is included whole.", "reference": "https://opencode.ai/v2/docs/instructions/#ordering", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "memory-opencode-packages-core-src-config-plugin-instruction-ts" ] }, "shared": { "status": "partial", "answer": "`AGENTS.md` is the shared convention and V2 reads it, so one `AGENTS.md` can serve OpenCode and other agents. V2 does not read `CLAUDE.md` or other tools' rule files; move that guidance into `AGENTS.md`.", "reference": "https://opencode.ai/v2/docs/instructions/#scope", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "instructions-opencode-opencode-ai-v2-docs-migrate-v1" ] }, "scoped": { "status": "partial", "answer": "There are no glob or frontmatter rules. A nested `AGENTS.md` effectively applies to its subtree because it is loaded only when the agent reads or lists something in that directory. Otherwise, reference a file in the prompt to pull it in on demand.", "reference": "https://opencode.ai/v2/docs/instructions/#discovery", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "instructions-opencode-packages-core-src-tool-plugin-read-ts" ] }, "imports": { "status": "unsupported", "answer": "No. `AGENTS.md` content is sent as-is; `@path` references are not expanded, and the `instructions` config array that 1.x used for extra files is not applied in V2.", "reference": "https://opencode.ai/v2/docs/instructions/#configuration", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "memory-opencode-packages-core-src-config-plugin-instruction-ts" ] }, "extra": { "status": "partial", "answer": "Not from config yet: the `instructions` array in opencode.json is accepted but its files, globs and URLs are not loaded. Clients can attach per-session instruction entries through the server API (`PUT /api/experimental/session/{sessionID}/instructions/entries/{key}`), and an agent's `system` field sets its own system prompt. There is no CLI flag.", "reference": "https://opencode.ai/v2/docs/instructions/#configuration", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "instructions-opencode-opencode-ai-v2-docs-api", "instructions-opencode-opencode-ai-v2-docs-config", "memory-opencode-opencode-ai-v2-docs-agents" ] }, "managed": { "status": "unsupported", "answer": "No. Managed config in `/Library/Application Support/opencode`, `/etc/opencode` or `%ProgramData%\\opencode` and the macOS `ai.opencode.managed` profile can enforce settings and policies, but V2 ignores the `instructions` array and does not read an `AGENTS.md` from the system directory, so admins cannot push mandatory instructions.", "reference": "https://opencode.ai/v2/docs/instructions/#configuration", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "instructions-opencode-opencode-ai-v2-docs-config", "memory-opencode-packages-core-src-config-plugin-instruction-ts" ] }, "check": { "status": "partial", "answer": "There is no command that prints the loaded files; each one appears in the model context as an `Instructions from: ` block, and clients can see which sources changed but not their contents. Edits to the global or upward `AGENTS.md` files are detected while a session runs and sent as an update (with a diff) before the next model request; edits to a nested file after it loaded need a new session.", "reference": "https://opencode.ai/v2/docs/instructions/#updates", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "memory-opencode-packages-core-src-config-plugin-instruction-ts", "instructions-opencode-packages-core-src-instruction-discovery-ts" ] }, "disable": { "status": "partial", "answer": "Set `OPENCODE_DISABLE_PROJECT_CONFIG=1` (also read as `OPENCODE_CONFIG_PROJECT_DISABLE`) to skip project `AGENTS.md` discovery while keeping the global file. There is no switch for the global file and no exclude list.", "reference": "https://opencode.ai/v2/docs/instructions/#scope", "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "instructions-opencode-packages-cli-src-server-process-ts", "instructions-opencode-packages-server-src-routes-ts" ], "notes": [ "Nested `AGENTS.md` files are still added when the agent reads files below the workspace." ] }, "create": { "status": "supported", "answer": "Yes. `/init` runs a guided setup that creates or improves `AGENTS.md` for the project; text after `/init` is passed as extra focus.", "reference": "https://github.com/anomalyco/opencode/blob/042d0832f5f3a73eaa039a58a7d565776f6d4290/packages/core/src/plugin/command.ts#L28-L40", "evidence": [ "memory-opencode-packages-core-src-plugin-command-ts", "memory-opencode-opencode-ai-docs-rules" ] } }, "evidence": [ "memory-opencode-opencode-ai-v2-docs-instructions", "memory-opencode-packages-core-src-config-plugin-instruction-ts", "instructions-opencode-opencode-ai-v2-docs-migrate-v1", "instructions-opencode-packages-core-src-tool-plugin-read-ts", "instructions-opencode-packages-util-src-global-ts", "instructions-opencode-packages-core-src-instruction-discovery-ts", "instructions-opencode-opencode-ai-v2-docs-api", "instructions-opencode-opencode-ai-v2-docs-config", "memory-opencode-opencode-ai-v2-docs-agents", "instructions-opencode-packages-cli-src-server-process-ts", "instructions-opencode-packages-server-src-routes-ts", "memory-opencode-packages-core-src-plugin-command-ts", "memory-opencode-opencode-ai-docs-rules" ], "reference": "https://opencode.ai/v2/docs/instructions/#scope", "sourceRevision": "042d0832f5f3a73eaa039a58a7d565776f6d4290" }, { "harness": "pi", "variant": "current", "default": true, "support": { "discovery": "native", "hierarchy": "native", "conditionalActivation": "unsupported", "manualActivation": "unsupported", "managedEnforcement": "unsupported" }, "sources": [ { "name": "user-AGENTS.md", "scope": "user", "format": "markdown" }, { "name": "ancestor-AGENTS.md", "scope": "project", "format": "markdown" }, { "name": "AGENTS.override.md", "scope": "directory", "format": "markdown" }, { "name": "CLAUDE.md-fallback", "scope": "project", "format": "markdown" }, { "name": "user-APPEND_SYSTEM.md", "scope": "user", "format": "markdown" }, { "name": "project-.pi/APPEND_SYSTEM.md", "scope": "project", "format": "markdown" }, { "name": "user-SYSTEM.md", "scope": "user", "format": "markdown" }, { "name": "project-.pi/SYSTEM.md", "scope": "project", "format": "markdown" } ], "merge": "Every applicable context file is included in full, each wrapped in its own `` block in the system prompt's project-context section; APPEND_SYSTEM.md text goes in a separate addendum section and SYSTEM.md replaces only Pi's base prompt.", "precedence": "There is no override between directories: the agent-directory file comes first, then one file per directory from the filesystem root down to the working directory (closest last); within one directory only the first of AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, CLAUDE.MD is used, and a trusted project `.pi/SYSTEM.md`/`.pi/APPEND_SYSTEM.md` replaces the agent-directory file of the same name.", "observedVersion": "1.2.0", "answers": { "files": { "status": "supported", "answer": "Pi reads context files named `AGENTS.override.md`, `AGENTS.md`, `AGENTS.MD`, `CLAUDE.md` or `CLAUDE.MD`, using only the first one it finds in each directory, in that order. Separately, `SYSTEM.md` replaces Pi's default system prompt and `APPEND_SYSTEM.md` adds to it; both live in `~/.pi/agent/` or the project's `.pi/` folder. There is no rules directory.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/resource-loader.ts#L184-L203", "evidence": [ "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "memory-pi-packages-coding-agent-docs-configuration-md" ], "notes": [ "`AGENTS.override.md` only replaces the other file in the same directory. Context files in other directories still load." ] }, "where": { "status": "supported", "answer": "At startup Pi loads one file from the agent directory (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`), then one from the working directory and from every parent directory up to the filesystem root. Files in subdirectories below the working directory are never loaded, not even when Pi works on files there. `SYSTEM.md` and `APPEND_SYSTEM.md` are read only from `/.pi/` and `~/.pi/agent/`, not from parent directories.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/resource-loader.ts#L232-L274", "evidence": [ "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "memory-pi-packages-coding-agent-docs-configuration-md", "instructions-pi-packages-coding-agent-docs-environment-variables-md" ], "notes": [ "If a linked git worktree sits inside its main checkout, the worktree's own context file replaces the main repo's copy so the same instructions don't load twice." ] }, "combine": { "status": "supported", "answer": "Every context file found is added in full to the system prompt, each in its own block labelled with its path, in this order: agent-directory file first, then from the filesystem root down to the working directory. Pi does not resolve conflicts, so the model sees all of them; the file closest to the working directory comes last. A trusted project `.pi/SYSTEM.md` or `.pi/APPEND_SYSTEM.md` replaces the user file of the same name rather than being combined with it.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/system-prompt.ts#L79-L86", "evidence": [ "instructions-pi-packages-coding-agent-src-core-system-prompt-ts", "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "memory-pi-packages-coding-agent-docs-configuration-md" ] }, "limits": { "status": "supported", "answer": "There is no size limit. Each file is read in full and pasted into the system prompt without truncation, so very large files use up the model's context window.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/resource-loader.ts#L184-L203", "evidence": [ "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "instructions-pi-packages-coding-agent-src-core-system-prompt-ts" ] }, "shared": { "status": "supported", "answer": "Yes. Pi reads `AGENTS.md`, so a file written for Codex or other AGENTS.md tools works as is, and it falls back to `CLAUDE.md` in any directory that has no `AGENTS.md`. No setting is needed. If a directory has both, only `AGENTS.md` is used. Pi does not read `~/.claude/CLAUDE.md`, `.cursor/rules`, `GEMINI.md` or similar files.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/resource-loader.ts#L184-L185", "evidence": [ "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "memory-pi-packages-coding-agent-docs-configuration-md" ], "notes": [ "Pi also discovers skills in a project's `.agents/skills` directory, which other harnesses share. Skills are loaded on demand, not as instruction files." ] }, "scoped": { "status": "unsupported", "answer": "No. Context files have no globs or frontmatter and always apply to Pi runs in their directory or below it. For guidance that should load only when it's relevant, write a skill: the model loads it on demand, or you can force it with `/skill:name`. Setting `disable-model-invocation: true` in a skill's frontmatter means it loads only when you call it explicitly.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/configuration.md#L43", "evidence": [ "memory-pi-packages-coding-agent-docs-configuration-md", "instructions-pi-packages-coding-agent-docs-skills-md" ] }, "imports": { "status": "unsupported", "answer": "No. Context files are inserted as plain text, so `@path` lines and links are not expanded. The model can still read a linked file with its tools if the instructions tell it to.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/resource-loader.ts#L184-L203", "evidence": ["memory-pi-packages-coding-agent-src-core-resource-loader-ts"] }, "extra": { "status": "supported", "answer": "`--append-system-prompt ` adds text or a file's contents and can be repeated; it replaces any discovered `APPEND_SYSTEM.md` for that run. `--system-prompt ` replaces Pi's base prompt, but context files are still added after it. Extensions can add or change prompt sections in a `before_agent_start` handler, and SDK users can add virtual context files with `agentsFilesOverride`. There is no settings key or environment variable for instruction text, and no way to load it from a URL.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/cli.md#L229-L232", "evidence": [ "pi-docs-1-2-0", "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "steering-pi-packages-coding-agent-docs-extensions-md", "instructions-pi-packages-coding-agent-examples-sdk-07-context-files-ts" ] }, "managed": { "status": "unsupported", "answer": "No. Pi has no managed or admin policy layer. Every instruction source is a user-editable file or a command-line flag, and any of them can be switched off with `--no-context-files` or replaced with `--system-prompt`.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/configuration.md#L1-L5", "evidence": ["memory-pi-packages-coding-agent-docs-configuration-md"] }, "check": { "status": "supported", "answer": "The interactive startup header has a Context section listing every file loaded: `SYSTEM.md`, `APPEND_SYSTEM.md`, then the context files. It is hidden when `quietStartup` is `true` or `\"header\"`, and `--verbose` shows it anyway. Edits are not picked up automatically; run `/reload` to re-read context files and update the system prompt in the current session.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/modes/interactive/interactive-mode.ts#L1846-L1863", "evidence": [ "steering-pi-kages-coding-agent-src-modes-interactive-interactive-mode-ts", "instructions-pi-packages-coding-agent-docs-slash-commands-md", "steering-pi-packages-coding-agent-docs-settings-md", "memory-pi-packages-coding-agent-docs-configuration-md" ] }, "disable": { "status": "supported", "answer": "Run `pi --no-context-files` (`-nc`) to skip every `AGENTS.md`/`CLAUDE.md` file for that run. You can't exclude a single file or directory, but adding an `AGENTS.override.md` to a directory replaces that directory's file. Project `.pi/SYSTEM.md` and `.pi/APPEND_SYSTEM.md` load only in trusted projects, so `--no-approve` (`-na`) skips them; context files load whether or not you trust the project.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/cli.md#L214-L215", "evidence": [ "pi-docs-1-2-0", "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "instructions-pi-packages-coding-agent-docs-security-md" ], "notes": ["`--no-context-files` does not affect `SYSTEM.md` or `APPEND_SYSTEM.md`."] }, "create": { "status": "unsupported", "answer": "There is no `/init` or similar command. Create `AGENTS.md` by hand, or ask Pi to write one with its file tools.", "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/docs/slash-commands.md#L44-L52", "evidence": ["instructions-pi-packages-coding-agent-docs-slash-commands-md"] } }, "evidence": [ "memory-pi-packages-coding-agent-src-core-resource-loader-ts", "memory-pi-packages-coding-agent-docs-configuration-md", "instructions-pi-packages-coding-agent-docs-environment-variables-md", "instructions-pi-packages-coding-agent-src-core-system-prompt-ts", "instructions-pi-packages-coding-agent-docs-skills-md", "pi-docs-1-2-0", "steering-pi-packages-coding-agent-docs-extensions-md", "instructions-pi-packages-coding-agent-examples-sdk-07-context-files-ts", "steering-pi-kages-coding-agent-src-modes-interactive-interactive-mode-ts", "instructions-pi-packages-coding-agent-docs-slash-commands-md", "steering-pi-packages-coding-agent-docs-settings-md", "instructions-pi-packages-coding-agent-docs-security-md" ], "reference": "https://github.com/earendil-works/pi/blob/06a466935536f8c9bcacb2d5efc0fc021be1bdff/packages/coding-agent/src/core/resource-loader.ts#L184-L203", "sourceRevision": "06a466935536f8c9bcacb2d5efc0fc021be1bdff" } ] }