ARTICLE · 999194
讲清楚Agent的规则文档是什么,为什么重要,该怎么写.让Agent越用越顺手.
multica-ai/andrej-karpathy-skills
这个公开仓库在 GitHub 上一直有很高的关注，你可能也从别的博主那里看到过这个仓库的推荐。
截至 2026 年 9 月 1 日，GitHub API 返回的 Star 数是 209,207。
仓库由 multica-ai 社区维护，内容来自 Andrej Karpathy 对大模型编码问题的公开观察。它的核心很短，一份规则文件，四条原则。内容围绕如何确认假设和控制复杂度，也要求修改范围与验收方式明确。
一份这么短的文件，为什么会得到 20 多万人的认可？
很多人使用 Agent 一段时间后都会碰到类似的问题。模型会写代码，也会调工具，可它经常自作主张。你明明只让它修一个按钮，它顺手改了旁边的结构。你希望它先问清楚，它却选了一个理解直接往下做。能力很强，工作方式却不稳定。
一句话概括了这种感受。
模型决定它能不能干，规则决定它会不会乱干。 |
热门仓库值得参考。我不建议把它整份复制进自己的项目。规则是否有用，要看它能不能改变 Agent 在你的工作里做出的下一步选择。
图 1 仓库示意
规则文档到底是什么
最粗略的理解，规则文档是一组会被 Agent 自动加载的长期工作说明。
在 Codex 里，常见的项目规则文件叫 AGENTS.md。Cursor 的项目规则可以放在 .cursor/rules 中，并使用 .mdc 文件。不同产品的文件名、发现顺序和作用范围并不完全相同，共同点是产品会把这些规则加入任务上下文，用户不需要每次都从聊天框重新输入。
可以把一次响应简化成下面这组关系。
系统或产品指令 + 自动加载的规则文件 + 当前任务与上下文 → Agent 本次响应 |
我做过一个很直观的测试。
第一次，我直接问 Agent “你是谁”，它给出正常回答。随后我把规则文件改成“你是猪”，再开启一个新任务问同样的问题，它马上开始哼哼唧唧。聊天框里没有重新输入这条设定，规则文件已经跟着任务一起被加载。
这个测试只用来说明自动加载。真实运行时还可能加入开发者指令、工具说明、文件内容和聊天记录，具体组成要看产品与当前任务。
图 2 简化示意。系统或产品指令、规则文件、当前问题会共同影响 Agent 的回答。
长任务更容易看出规则的影响
短任务里，用户通常可以在一条消息中把要求交代完整，规则带来的差别可能不明显。任务一旦变长，情况会迅速改变。
假设我只给 Agent 一句话。
帮我把这份内容做成一期视频。 |
这句话后面会展开很多决定。Agent 先核对资料，再决定哪些内容保留。进入制作后，它还要选择工具，并判断怎样修改和验收画面。
任何一步选错方向，后面的工作都会继续建立在这个选择上。一个任务里出现十几次甚至几十次判断并不稀奇。最开始加载的规则会持续参与这些判断，所以长任务更能看出它的作用。
图 3 一句“做成一期视频”会展开为资料核对、内容取舍、工具调用、修改和验收。
聊天记录、文件内容和工具输出会随着任务推进不断增加。产品可能压缩或整理早期内容，模型也更容易漏掉埋在长对话里的细节。规则文件通常由 Agent 产品按专门的发现与加载方式处理，因此更适合放反复使用的工作约定。
这里不能把所有 Agent 说成同一种机制。Codex 会沿项目目录查找并组合适用的 AGENTS.md。Cursor 会根据规则类型、路径匹配或调用方式决定是否加入某条规则。它们都在处理长期约定，具体位置和优先关系仍以各自文档为准。
图 4 普通工作内容越积越多，当前任务和重要要求会争夺注意力。
20万 Star 也不适合整份照抄
这个热门仓库主要处理大模型写代码时容易出现的问题。它强调谨慎确认、控制复杂度和限制修改范围。这些原则很有参考价值，但你的工作可能是视频制作，也可能长期围绕某个具体项目展开。需要约束的动作自然不同。
整份复制还会带来两个直接问题。
第一，与你无关的规则也会占用上下文。Codex 当前对项目规则文件设有默认合并上限，project_doc_max_bytes 默认是 32 KiB，并且可以配置。规则链过长时，后面的内容可能无法完整进入任务上下文。不同版本的处理细节可能变化，使用时应查看当前官方文档。
第二，多来源规则可能互相冲突。一个仓库要求遇到歧义立即提问，你自己的项目规则又允许 Agent 在低风险情况下自行判断。Agent 同时收到两种做法后，需要额外判断该听哪一条，执行反而更不稳定。
规则数量本身不能证明质量。适用范围清楚、动作具体、结果可检查，才方便 Agent 执行。
坏规则写价值观，好规则写动作
下面两句话经常出现在规则文件里。
你是一位经验丰富的设计师。 设计要高级，要有审美。 |
它们听起来没有问题，Agent 看完以后却不知道应该查哪份参考，也不知道下一步做什么。作品交回来以后，用户仍然只能凭感觉判断“够不够高级”。
把同一个要求改成下面这样，Agent 才能执行。
当任务涉及设计时，先读取项目知识库中已经确认的画风和构图参考。发现两者互相冲突时，列出冲突点，等待用户选择后再制作。验收时检查主标题层级、角色身份和画面隐喻是否与已确认参考一致。 |
这条规则写清了触发场景和具体动作，后面还附着可检查的结果。它可以直接改变 Agent 的下一步行为。
图 5 口号只表达期待，可执行规则会告诉 Agent 做什么、参考什么以及怎样判断。
规则从反复出现的问题里整理出来
第一次打开规则文件时，很容易想把所有经验一次写完。结果通常是一份很长的清单，里面混着网上抄来的原则和自己猜测的问题。等到真正执行，很多条目从来不会触发，重要要求反而被挤到后面。
更稳妥的做法来自真实任务。
Agent 第一次没按你的想法来，先在当前任务里纠正。相同问题再次出现时，把原因和有效改法记下来。等它连续发生到第三次，你已经掌握了出错条件和正确动作，验收方式也来自刚刚完成的修改。
这里的“第三次”是一条实用判断，不属于产品机制。复杂度高、后果明显的问题可以更早写入；偶发问题则继续观察。
正式加入规则前，我会再看两件事。
1.Agent 读完后能否直接采取一个明确动作。
2.任务结束时能否用具体结果判断它做对了。
两项都答得出来，这条规则才适合长期保留。
图 6 第一次先纠正，重复出现时记录，确认规律后再写进规则文件。
规则还要放在合适的范围
一条适用于所有工作的约定，可以放在全局规则里。只服务当前项目的要求，应留在项目规则中。某个子目录有特殊限制时，再让规则跟随该目录生效。
范围划分以后，同一任务仍可能收到多层规则。它们发生冲突时，产品的加载顺序和作用域会影响最终结果。下一期会继续拆解全局规则、项目规则和子目录规则之间的工作边界。
图 7 规则进入不同工作范围后，同一件事可能同时收到多条要求。
现在可以先做一件很小的事。下次 Agent 重复犯同一个错，把你纠正它的动作和验收方法留下来。相同问题再次出现时，就把这条记录写进规则文件。
先解决自己工作里最常见的一个问题，往往比复制一整套热门规则更有效。
资料链接
https://github.com/multica-ai/andrej-karpathy-skills
https://api.github.com/repos/multica-ai/andrej-karpathy-skills
https://learn.chatgpt.com/codex/agent-configuration/agents-md
https://docs.cursor.com/context/rules