AGENTS.md and rules files: set a coding agent’s scope

AGENTS.md is a Markdown file for giving a coding agent project instructions: what to change, which conventions to follow, and how to verify the result. CLAUDE.md and Cursor rules serve similar purposes, but each client decides which files it loads and how they combine. These files guide behavior; they do not themselves restrict filesystem or network access. See the AGENTS.md convention and the distinction between instructions and permissions.

What it can do

Put project knowledge where a compatible agent can find it: directory responsibilities, established test commands, generated files to avoid, and review expectations. AGENTS.md uses ordinary Markdown rather than a required configuration schema; the convention guide describes its purpose and placement.

For a shopping-cart fix, replace a vague request to improve checkout with a small task contract. Here is an example policy to adapt, rather than a universal default:

# Project rules

- For the cart fix, edit only src/cart/ and tests/cart/.
- Before editing, record git status and preserve existing changes.
- Do not modify dependency manifests, lockfiles, billing or deployment files.
- Do not read credential files or send project code to external services.
- If another path is needed, explain why and request a scope change.
- Run the repository's existing cart tests; report the command and result.
- Finish with changed paths, remaining uncertainty and a reviewable diff.

The useful distinction is between the standing rule and the current assignment. Keep reusable project conventions in the file; put the specific bug, allowed paths and acceptance example in the task brief. For example, require that removing the final item leaves an empty cart without changing checkout behavior.

Review the policy as code. Ask whether each sentence names an observable action, a path, or evidence the reviewer can inspect. Replace instructions such as be careful with a concrete boundary. More introductions to these concepts are in AI agents explained.

Which tools read which files?

As of 30 Oct 2026, use this compatibility guide, then confirm the behavior in your installed client:

Treat this as a representative comparison, not a promise that every editor extension recognizes every filename. For another client, check the current documentation before choosing its rules entry point.

Which rules take precedence?

There is no shared precedence order across these products:

• Codex: global guidance comes first, followed by project files from the root toward the working directory. Within a directory, AGENTS.override.md is checked before AGENTS.md; only one file is included. Later, more local guidance overrides earlier guidance. Codex discovery.
• Cursor: nested AGENTS.md instructions combine with parent instructions, with the more specific guidance taking precedence. Its separate rules hierarchy puts Team Rules before Project Rules before User Rules. Cursor precedence.
• Claude Code: CLAUDE.md files concatenate rather than replace each other. Where direct AGENTS.md support is available, the default selects it only without a relevant CLAUDE.md or CLAUDE.local.md. Contradictory instructions need reconciliation. Claude Code loading.

For example, keep shared testing expectations at the root and cart-specific conventions under src/cart/. Before assigning a cross-directory change, review both instruction sets. Avoid a child rule that casually weakens a repository-wide data boundary.

How to connect it safely

Here, connecting means making instructions available to the coding client, not installing a server.

1. Open the intended project in VS Code or your editor. Confirm the workspace and terminal directory. Record existing modified and untracked paths before requesting edits; use a separate working copy for an experiment involving uncertain code.
2. Inspect existing instruction files. Read the root policy and relevant directory policies. Preserve local additions. Resolve contradictory scope statements before letting the agent write.
3. Use the client's documented entry point. Add shared guidance to AGENTS.md where supported. For Claude Code, an explicit @AGENTS.md import can share the file. For Cursor, choose plain Markdown or structured project rules deliberately; their formats differ. Follow the linked client documentation above.
4. Verify loading before requesting changes. In Claude Code, inspect Memory files with /context. For Codex, ask it to list active instruction sources from the target directory; restart after instruction changes. These checks are documented in the Claude Code guide and Codex guide.
5. Configure real access controls separately. Prefer a restricted work area and explicit approval for sensitive tools. Claude Code exposes tool controls through /permissions; prose in CLAUDE.md does not grant or revoke access. Permission documentation. For connected tools, also review MCP permissions.
6. Run a bounded trial and inspect evidence. Request the cart fix with the allowlist above. Check the actual changed paths and test output. If the task expands beyond the allowlist, agree on a revised scope before continuing. Keep the diff available for human review.

When this does not work

A prohibition is only text. Writing that deployment is forbidden does not remove a deployment tool or revoke its credentials. Permission settings and sandboxing belong to the execution environment; check their actual coverage. The Claude Code permissions guide distinguishes these enforcement mechanisms from instructions.

The intended file never loads. A wrong launch directory can change Codex discovery. In Cursor, a project rule may depend on a matching path or manual application. Check the Codex discovery rules and Cursor application modes before diagnosing disobedience.

The policy is inconsistent or obsolete. Review test commands and directory names after refactoring. Keep security boundaries clear, and resolve conflicts instead of relying on the agent to infer your intent. A short policy with verifiable boundaries is easier for a human reviewer to maintain.

A convincing summary replaces verification. Require the diff and relevant command output, then inspect them. A statement that tests passed is not the test result. The related guide to task receipts and their limits explains why evidence needs a defined scope.

Where Tvijo fits

Write the project rules into the Tvijo task brief: describe the permitted work, tools and acceptance criteria before execution. For the cart task, include the allowed paths above and require a scope change before touching billing. This is a practical task boundary, not a claim that naming AGENTS.md automatically creates an enforced file allowlist. See Tvijo permissions and data flow.

As of 30 Oct 2026, distinguish the entry points. The DSHREM VS Code extension brings selected context into a Tvijo task; the published editor comparison describes local tools and approval modes. Confirm the installed channel and mode. TvijoCode bundles the extension in an editor test build; its published guide describes unsigned Windows builds without automatic updates.

Tvijo MCP makes Tvijo callable from a compatible client. Published consultation, prepared supplied-diff review awaiting package publication, and planned editor integration and delegation are separate capabilities. Do not assume an MCP connection gives Tvijo general control of the client's workspace.

On the Tvijo workspace, as of 31 Oct 2026, Try costs $0: up to 50 tasks, 100,000 tokens or $0.05 of sponsored usage, whichever is reached first, from a shared $1 daily pool funded by TVIJO. Service credit is shown as $10 for requesting prepaid credit; usage is metered with an 8% service markup. Payment collection is not activated, and an order is not a charge.

FAQ

Is AGENTS.md a security policy?

It can describe your policy, but does not enforce access. Pair it with tool permissions and environment controls; review the resulting changes.

Should I keep both CLAUDE.md and AGENTS.md?

If your clients need them, keep shared instructions in one place and use the documented import mechanism. Verify what loads; avoid contradictory copies.

Can a nested rules file widen the task scope?

Treat scope expansion as a separate decision. Resolve it before editing, and update the real permissions separately when the authorized work requires that.