AGENTS.md: The Small Rule File That Sets Your AI Agent's Boundaries

I've noticed that my students are increasingly ignoring AGENTS.md and CLAUDE.md.

Everyone is busy researching how to make requests to Agent, but the long-term rules that should be followed are getting scattered across one-off chats.

Lao Jin thinks these are the core files worth maintaining carefully.

AI programming tools that support these files load the applicable rules at the start of a session and then work according to those requirements.

Which styles to use, which operations require confirmation — you don't have to explain everything from scratch each time.

The official filename is uppercase, plural AGENTS.md.

In Codex, global rules govern general habits, and project rules govern this project.

When they conflict, project rules take priority, while non-conflicting global rules continue to apply.

A complete set of rules should cover these things

First, explain what the project does and what tech stack it uses. Don't let the Agent switch languages or frameworks mid-way; before solving the problem, it shouldn't rebuild the project from scratch.
Make the real commands clear. What commands for install, start, test, check, and build, and in which directory to run them, should be confirmed from the current project, not copied from someone else's pnpm.
Look for references first, don't reinvent the wheel. Search for similar implementations in the project first; if there's nothing suitable locally, then check official documentation or public GitHub projects.
Set the scope and permissions of changes. Do what's already authorized directly; ask about anything outside that scope. Don't casually modify unrelated modules, and don't bring private code or internal data to public websites.
Don't over-engineer. A small feature shouldn't accumulate a complex system for theoretical edge cases. First state the real risk and evidence, then decide whether to add complexity; necessary security checks cannot be skipped.
Follow the good practices already in the project. Naming, directories, error handling, and testing style should stay consistent with existing code; don't invent a new style with every task.
If you get stuck, say so clearly. What information is missing, what you've tried, and what you plan to do next — report it in a timely manner. Don't quietly take a long detour and then hand over a pile of guessed changes.
Completion requires actual verification. What was changed, what checks were run, where it failed — all need to be reported clearly. Checks that weren't run cannot be reported as passed.

These are long-term agreements; there's no need to re-emphasize them each time.

Don't let the file become bloated. Project-level files can aim for about 50–100 lines, global files 30–60 lines. Put longer processes in separate documents and leave an entry point in the rule file.

Project-specific version: fill in information about the current project

The project root directory is the outermost folder of the project.

Put customized rules in AGENTS.md in this directory. Replace the square brackets with real information, delete items that don't apply.

If an AGENTS.md already exists, merge incrementally; don't overwrite old conventions with the template.

# AGENTS.md

## Project positioning and tech stack
Project purpose: [what it does, which parts main changes involve]
Tech stack: [language, framework, dependency management tool, and version basis]

## Common commands
Execution directory: [real directory]
Install dependencies: [real command]
Start dev server: [real command]
Single file or related tests: [real command and arguments]
Full test suite: [real command and prerequisites]
Code lint: [real command]
Type check: [real command, delete if not applicable]
Build: [real command]

## Structure and code patterns
Key directories: [paths and their purpose]
Reference implementations: [1–2 real files and the practices worth following]
Test reference: [real file path]
Code conventions: [the most important conventions for this project]

## Project boundaries and acceptance
Protected files or interfaces: [specific scope and reason]
Operations that require special confirmation: [permission boundaries for this project]
Acceptance requirements: [key behaviors, check scope, and pass criteria]

This template contains a lot of custom information.

If you don't know how to fill it in, or are too lazy to find each item, let the Agent that already has the project open analyze it first and then help fill it out.

Please scan the current project and complete the project-level AGENTS.md.
First read the existing AGENTS.md, CLAUDE.md, and related subdirectory rules,
then check the README, dependency config, lock files, tests, and build config.

Fill in the custom items above based on the real project, keeping valid existing conventions.
For each command, note the source, execution directory, and whether it was actually verified.
List missing information as "to be confirmed"; don't invent commands, paths, or results.
Only return the scan results and incremental merge plan. Don't modify business code,
don't install dependencies, don't read or output secrets, credentials, or private data.
After I confirm, write it into the rule file.

Global version: Lao Jin has already filled it in

The template below has no project placeholders, so you can use it directly as a global draft. It writes out common practices completely; when it encounters a different project, it first identifies the project's actual situation, then executes.

The default location for native Windows Codex is as follows; replace "username" with your Windows user directory name.

C:\Users\username\.codex\AGENTS.md

If CODEX_HOME is set, place it in that directory as AGENTS.md.

If using WSL, put it in the .codex directory under the Linux user directory; don't mix it with the Windows path.

If you already have a global file, also merge only the needed content.

# AGENTS.md

## Project positioning and tech stack
Before starting work, read the applicable project rules, README, and dependency config.
Understand the project's purpose, scope of changes, language, framework, and tool versions.
Follow the existing tech stack; don't switch languages, frameworks, or dependency management tools on your own.
When global and project rules conflict, follow the more specific applicable rules.

## Real commands
Confirm actual commands from the README, dependency config, lock files, and scripts.
Find out the install, start, test, lint, type check, and build entry points.
Before executing, confirm the working directory, arguments, and prerequisites; don't guess commands from habit.
If the project has no corresponding command, say so honestly; don't fabricate one or improvise.
Only install dependencies or change the environment when a task truly requires it and you have authorization.
If you confirm the project uses pnpm and the package.json scripts and arguments match, you may use:
Install: pnpm install. Start: pnpm dev.
Unit test example: pnpm test -- <real test file>. Full tests: pnpm test.
Lint: pnpm lint. Type: pnpm typecheck. Build: pnpm build.
If there is no matching script or arguments, check the project's real entry point; don't copy blindly.

## Look for references before acting
First check the project's existing similar features, components, error handling, and tests.
If there's no suitable local reference, then check official documentation or public GitHub projects.
Choose the most relevant 1–3 references and explain which approach you're adopting. Don't search just to pad the count.
Use only generic keywords for external searches; don't upload private source code, logs, or customer data.
Before adopting external code, check version, compatibility, and license.

## Scope and permissions
Keep changes focused; don't refactor unrelated modules or overwrite uncommitted user changes.
Before adding dependencies, deleting, pushing, publishing, or changing the database, confirm existing authorization.
Do what's in scope directly; if new risks or scope creep arise, ask first.
Don't commit or leak keys, credentials, .env, or private data.
Don't modify already-applied migrations or hand-edit generated files.
For authorized dependency changes that need a lock file update, generate it with the project's original tool.
When touching production or external writes, first confirm the target, impact, and authorization.

## Don't over-design or over-defend
Implement the current requirement; don't add abstraction, config, or fallbacks for hypothetical future needs.
Before adding complexity, state the specific failure scenario, existing evidence, and maintenance cost.
If you don't know a risk or probability, say so clearly; don't invent percentages or fictional code sizes.
Keep necessary permission checks, input validation, and data consistency protections.
Prefer the simplest solution that meets the current need and is easy to verify and maintain.

## Code patterns
Reuse existing components, utility functions, naming, and error handling.
Reference nearby good implementations and tests; keep directory and code style consistent.
Add comments only when they help explain intent, constraints, or complex logic.
Don't manufacture passing results by deleting tests, loosening assertions, or suppressing errors.

## Communication and blockers
Communicate in Chinese by default; keep commands, code, and technical identifiers as-is.
For multi-step tasks, give a short plan first; report progress or blockers promptly.
If missing a key condition, first check existing files; if still unclear, ask a concrete question.
If you find rule conflicts, scope changes, or higher risks, state them first; don't make big changes by guessing.

## Actual acceptance
Choose checks based on the risk of the change; prioritize running the smallest effective scope covering this change.
Expand checks when touching public interfaces, dependencies, config, or cross-module behavior.
For high-cost or externally side-effecting checks, first confirm scope and authorization.
Report actual changes, commands run, results, and exit codes.
Distinguish new errors, pre-existing issues, and environmental blockers.
For parts that weren't run, failed, or are still incomplete, say so honestly; don't falsely claim completion.

Claude Code also supports it; wire it up like this

The new version of Claude Code also supports AGENTS.md.

If the project already has CLAUDE.md, add the following line to import the rules from the same directory, while preserving valid existing content.

@AGENTS.md

Claude's personal global rules go in ~/.claude/CLAUDE.md; it won't automatically read Codex's global file.

After making the change, start a new session and use /context to check whether CLAUDE.md appears in the Memory files list.

Then run a small task to see whether the Agent follows the rules.

Conclusion

Everyone is busy studying stronger models and more complex workflows, but the most basic rule file is easy to overlook.

It looks like just a small file, but it determines how the Agent starts each time, what requirements it works to, and when it's considered done.

Lao Jin thinks the more unremarkable and easily ignored something is, the more worth investing time to get it right.

Thank you for reading my article.

If you think it's good, a like, a "watching", and a share — the three-click combo — would be appreciated :)

If you want to receive updates as soon as they're posted, you can also give me a star ⭐. Thanks for reading.

Open source knowledge base (real-time updates, discussion group): https://my.feishu.cn/wiki/OhQ8wqntFihcI1kWVDlcNdpznFf