AGENTS.md、CLAUDE.md 这些项目规则该写什么？
把项目真实约定写成短而准确的说明，避免模板堆砌和过期规则。
本页目录
直接回答
项目规则应回答：这个项目做什么、关键代码在哪里、怎样运行验证、有哪些不能破坏的约束。它帮助 AI 少猜测、少重复犯错。规则内容必须来自实际项目，不是把网上的最佳实践全复制进去。不同工具读取文件的方式与优先级不同，应核对当前工具；文字规则用于引导行为，真正的文件和工具权限仍由环境控制。
适用场景
- 每次新对话都要解释技术栈、命令和目录。
- AI 经常扩展无关功能或漏掉项目要求。
一步一步做
先读现有说明与代码
检查 README、包管理文件、构建配置、关键目录和已有规则。运行命令应能在当前项目找到依据；不确定的部署或测试方式写为待核实，而不是填一个惯用答案。
保留稳定且必要的信息
写项目目标、技术栈、重要目录、开发与检查命令、数据边界、交付要求。临时排错过程放任务记录，长篇专项方法放独立参考，主文件保持容易读完。
把抽象要求换成行为
“代码质量要高”很难验收。可以改成“修改共享函数前检查调用方”“不得覆盖无关改动”“付款权限变更必须验证失败路径”。规则应与项目风险相关。
合并已有内容再检查冲突
更新前先保留旧版本并合并已有约定，说明删改依据，不直接覆盖整个配置文件。区分用户级偏好与项目硬约束，不把某个项目的规定推广成所有项目的通则。
用一次真实任务检验并维护
选择小任务看规则是否帮助完成，而不是要求 AI 表态“已遵守”。检查命令、触发范围和输出。规则造成重复审批或无效工作时精简；架构变化后同步修订。
给规则分类，给每条禁令一个理由
将内容分成四类：稳定项目事实、当前任务 SPEC、可重复流程、由权限或检查落实的约束。例如，视频渲染任务可能需要由帧状态驱动动效，某个项目也可能选定包管理器；这些都是有适用背景的决定。禁令应记录目录、触发条件、失败教训、可用替代与例外。项目不用某 API 不代表官方弃用；禁止所有 useEffect、TODO 或删除操作等宽泛约束应收窄到真实问题。
把文档漂移当成待修问题，做一次事实对照
手工改代码后，SPEC 或计划可能还描述旧状态。选一个刚变更的核心流程，对照“文档说什么、实现在哪里、验证观察是什么”，区分已实现、已决定未实现、候选与废弃。影响后续判断的冲突应修正事实所属主文档并链接依据；短暂排错放任务记录，低风险小改动无需重复生成设计文档。交付差异表，比口头承诺遵守更可核验。
跨工具共用规则前，核对加载与文件状态
使用符号链接或共享引用前，先确认各宿主实际读取的入口、路径与优先级。检查目标是否已有独有内容或已是链接，备份并合并后再调整，不能覆盖现有 CLAUDE.md 或 GEMINI.md。工具专属说明可保留薄入口，共享约定指向单一维护位置。新开会话，用无破坏的小任务核对加载效果；链接创建成功并不证明宿主已经读取。
从一次失败补一条规则，再重跑同类任务
反复犯错时，先判断是没有加载、规则冲突、描述含糊、权限缺口，还是正确规则仍被执行错。只固化可重复应用的结论，并补一项能暴露旧错误的验收。若规则带来重复审批、无必要测试或多 Agent 开销，按实际授权和风险精简。规则无法保证写过一次就不再出错。
案例拆解
假设示例：小型内容站
项目只读静态文章，没有账户和数据库。规则记录内容目录、搜索行为与检查命令即可；预设复杂的数据库迁移、微服务、计费流程，只会制造不相关约束。
行动检查
可复制模板
生成项目规则提示词
先读取本项目已有规则、README、依赖配置和关键实现。按真实情况整理项目目的、目录职责、运行检查命令和重要约束。已有规则优先合并；不要套用不属于本项目的技术栈，不确定内容标为待确认。解释新增、修改与删除的依据，并指出哪些要求需要工具权限或程序检查才能落实。
规则准入与维护台账
规则内容（具体行为）：
类别：项目事实/任务SPEC/工作流程/权限或检查
适用目录、场景、工具：
真实失败或业务约束来源：
为什么当前需要：
允许的替代做法、例外及批准来源：
如何验证执行了：
维护者、最后复核日期：
失效条件（版本/架构/业务变化）：
若只靠文字不够，对应权限或自动检查：
文档与实现漂移核对表
事实/约束 | 文档位置 | 实现位置/版本 | 实际检查 | 状态 | 修订位置
状态可选：已实现/已决定未实现/候选/废弃/待核实。
本轮需同步的决定：
已有规则冲突与处理依据：
跨工具入口、实际加载证据：
现有文件/链接状态、备份位置、合并差异：
一次真实任务结果及新出现的阻碍：
易错点
- Shell 重定向可能覆盖 settings.json；应先检查和合并现有配置，不直接照抄覆盖命令。
- 写“禁止修改”并不能自动形成文件系统只读权限。
- 规则越多越好不是目标；应该减少重复说明和真实错误。
- 把某项目不使用一种库误写成“该库/API 已被官方淘汰”。
- 创建规则符号链接前未处理已有文件，导致规则丢失或跨工具优先级冲突。
相关指南
官方参考
- Claude Code：权限配置。文档核查记录：2026-10-18；使用前确认适用版本。