Agent Rules

English | 简体中文

Strict, copy-ready rule files for AI coding agents: Codex and Claude Code.

This repository helps turn AI coding agents from fast autocomplete tools into more reliable long-running engineering collaborators. It provides:

• AGENTS.md for Codex;
• CLAUDE.md for Claude Code.

The rules focus on context-first work, minimal necessary changes, root-cause debugging, reproducible verification, long-task anti-drift checks, and explicit confirmation before risky operations.

Why Agent Rules

AI coding agents are useful, but real engineering sessions fail when the agent:

• edits before reading project rules;
• guesses commands, files, APIs, or test results;
• rewrites unrelated code;
• hides bugs behind defensive patches;
• claims success without reproducible checks;
• drifts away from the original goal during long tasks.

Agent Rules turns those failure modes into reusable operating rules.

Supported Agents

Agent	File	Typical Location	Notes
Codex	AGENTS.md	Global or repository-level AGENTS.md	Use as a global baseline, then override with project-specific rules.
Claude Code	CLAUDE.md + AGENTS.md	./CLAUDE.md, ./.claude/CLAUDE.md, or ~/.claude/CLAUDE.md	CLAUDE.md imports AGENTS.md and adds Claude-specific notes. Use hooks/settings if you need hard command blocking.

What The Rules Enforce

Risk	Rule
The agent skips context	Read project rules, README, plans, logs, source, tests, and build files before editing.
The agent invents facts	Do not fabricate files, commands, test output, interfaces, official claims, or hardware behavior.
The agent changes too much	Make the minimal necessary change and avoid unrelated refactors.
The agent patches symptoms	Reproduce, isolate, explain, fix root cause, and verify.
The agent claims success too early	Report exact checks, results, unverified items, and remaining risks.
Long tasks drift	Run anti-drift checks and maintain progress logs.
Dangerous operations happen casually	Require explicit confirmation for deletion, push, deployment, database writes, system config, and hardware-impacting code.

Quick Start

Codex

Copy AGENTS.md into your Codex global config directory.

Windows PowerShell:

mkdir "$env:USERPROFILE\.codex" -Force
Copy-Item .\AGENTS.md "$env:USERPROFILE\.codex\AGENTS.md" -Force

macOS / Linux:

mkdir -p ~/.codex
cp AGENTS.md ~/.codex/AGENTS.md

Restart Codex after replacing the global file so future sessions load the new instructions.

Claude Code

Use CLAUDE.md as your Claude Code instruction file. This repository's CLAUDE.md imports AGENTS.md, so copy both files together.

For a project:

cp AGENTS.md ./AGENTS.md
cp CLAUDE.md ./CLAUDE.md

For a user-level setup:

mkdir -p ~/.claude
cp AGENTS.md ~/.claude/AGENTS.md
cp CLAUDE.md ~/.claude/CLAUDE.md

Important: CLAUDE.md is persistent context. If you need to hard-block specific commands or paths, use Claude Code hooks/settings in addition to this file.

Who Should Use This

Use these rules if you:

• run AI coding agents on real repositories;
• want the agent to inspect local context before acting;
• care about reproducible verification;
• often work across multi-step tasks;
• prefer conservative edits over broad rewrites;
• want explicit confirmation before risky operations.

You may want a lighter setup if you only use coding agents for quick snippets, throwaway prototypes, or casual brainstorming.

How To Customize

Keep the strict structure, then adapt:

• language preference;
• planning format;
• progress log path;
• safety confirmation list;
• build, test, lint, training, or deployment conventions;
• repository-specific overrides.

For real projects, keep a local project-level rule file. More specific project instructions should override this global baseline.

Design Philosophy

This project is intentionally small. It is not a framework, package, or prompt library.

It is a safety rail for agentic engineering:

1. Read before acting.
2. Plan before editing.
3. Change only what matters.
4. Verify before claiming success.
5. Keep long tasks anchored to the goal.

If these rules help your AI coding sessions feel more like working with a careful senior engineer, please star the repository.

Repository Contents

• AGENTS.md: Codex rules template.
• CLAUDE.md: Claude Code rules template.
• LICENSE: MIT license.

Contributing

Issues and pull requests are welcome.

Good contributions should keep the templates:

• concise enough to be followed;
• strict enough to prevent common agent failures;
• practical for real engineering workflows;
• easy to copy into the target agent's rule file.

Please avoid adding broad prompt-library features unless they directly strengthen the core operating discipline.

License

MIT.

---

简体中文

English | 简体中文

面向 AI 编码助手的严格规则模板，当前支持 Codex 和 Claude Code。

这个仓库的目标，是把 AI 编码助手从“很快的补全工具”，变成更可靠的长期工程协作助手。仓库提供：

• AGENTS.md：给 Codex 使用；
• CLAUDE.md：给 Claude Code 使用。

这些规则重点约束：先读上下文、最小必要修改、根因调试、可复现验证、长时任务防漂移，以及危险操作前必须明确确认。

为什么需要 Agent Rules

AI 编码助手很有用，但真实工程会话里常见的问题是：

• 没读项目规则就开始改代码；
• 猜测命令、文件、API 或测试结果；
• 重写无关代码；
• 用防御性补丁掩盖真实 bug；
• 没有可复现检查就声称成功；
• 长任务中逐渐偏离原始目标。

Agent Rules 把这些失败模式转成可复用的工作规则。

支持的助手

助手	文件	常见位置	说明
Codex	AGENTS.md	全局或仓库级 AGENTS.md	作为全局基线使用，再用项目规则覆盖。
Claude Code	CLAUDE.md + AGENTS.md	./CLAUDE.md、./.claude/CLAUDE.md 或 ~/.claude/CLAUDE.md	CLAUDE.md 导入 AGENTS.md 并添加 Claude 专用说明。如需强制拦截命令，请结合 hooks/settings。

这些规则约束什么

风险	规则
助手跳过上下文	修改前先读项目规则、README、计划、日志、源码、测试和构建文件。
助手编造事实	不得虚构文件、命令、测试输出、接口、官方结论或硬件行为。
助手改得太多	只做最小必要修改，避免无关重构。
助手只补症状	先复现、隔离、解释，再修根因并验证。
助手过早宣布完成	汇报具体检查、结果、未验证项和剩余风险。
长时任务漂移	执行防漂移检查，并维护进度日志。
危险操作被随意执行	删除、推送、部署、数据库写入、系统配置、硬件相关代码必须先明确确认。

快速开始

Codex

把 AGENTS.md 复制到 Codex 全局配置目录。

Windows PowerShell:

mkdir "$env:USERPROFILE\.codex" -Force
Copy-Item .\AGENTS.md "$env:USERPROFILE\.codex\AGENTS.md" -Force

macOS / Linux:

mkdir -p ~/.codex
cp AGENTS.md ~/.codex/AGENTS.md

替换全局文件后，重启 Codex，让之后的会话加载新规则。

Claude Code

把 CLAUDE.md 作为 Claude Code 的指令文件使用。本仓库的 CLAUDE.md 会导入 AGENTS.md，所以请两个文件一起复制。

项目级使用：

cp AGENTS.md ./AGENTS.md
cp CLAUDE.md ./CLAUDE.md

用户级使用：

mkdir -p ~/.claude
cp AGENTS.md ~/.claude/AGENTS.md
cp CLAUDE.md ~/.claude/CLAUDE.md

注意：CLAUDE.md 是持久上下文。如果你需要强制拦截特定命令或路径，请在本文件之外结合 Claude Code hooks/settings。

适合谁使用

如果你符合这些情况，这组规则会比较适合：

• 用 AI 编码助手处理真实仓库；
• 希望助手先检查本地上下文再执行；
• 重视可复现验证；
• 经常处理多轮、多文件、多阶段任务；
• 更偏好保守修改，而不是大范围重写；
• 希望删除、推送、部署等危险操作前有明确确认。

如果你只把编码助手用于快速代码片段、一次性原型或轻量头脑风暴，可以选择更轻的模板。

如何定制

建议保留严格结构，然后按自己的工作流调整：

• 语言偏好；
• 计划格式；
• 进度日志路径；
• 安全确认清单；
• 构建、测试、lint、训练或部署约定；
• 仓库级覆盖规则。

真实项目中建议保留项目级规则文件。更具体的项目规则应该覆盖这个全局基线。

设计理念

这个项目刻意保持很小。它不是框架、软件包，也不是提示词库。

它是给 agentic engineering 的一组安全护栏：

1. 先读，再执行。
2. 先计划，再编辑。
3. 只改真正相关的内容。
4. 验证之后再声称完成。
5. 让长时任务始终贴着目标走。

如果这组规则让你的 AI 编码会话更像在和一位谨慎的资深工程师协作，欢迎给仓库点一个 star。

仓库内容

• AGENTS.md：Codex 规则模板。
• CLAUDE.md：Claude Code 规则模板。
• LICENSE：MIT 许可证。

贡献

欢迎提交 issue 和 pull request。

好的贡献应该让模板保持：

• 足够简洁，能被实际遵守；
• 足够严格，能防止常见 agent 失误；
• 对真实工程工作流有用；
• 容易复制到目标助手的规则文件。

请避免加入泛化提示词库功能，除非它能直接加强这组规则的核心工作纪律。

许可证

MIT.