题目 1:AGENTS.md、Skill、Memory、System Prompt 分别解决什么问题?
请分别用一个 Coding Agent 例子说明。
AGENTS.md 保存当前项目自己的规则,例如 Python 3.9、禁止修改 tests/;Skill 保存通用任务方法,例如 python-debug 的“先复现、看 traceback、最小修改”;Memory 保存历史确认事实,例如曾经决定不升级某个依赖;System Prompt 保存 Agent 长期角色和底线,例如不得伪造 Tool Result、必须遵守 Middleware。四者作用域和生命周期不同。
题目 2:为什么 Coding Agent 应该在开始修改代码前尽早读取 AGENTS.md?
请从依赖、测试、可修改范围和完成条件四个角度说明。
项目规则会直接决定修复方案是否有效。例如不允许新增依赖会影响技术选型,禁止修改 tests/ 会影响可改范围,指定 pytest 决定验证方式,而“修改后必须全量测试”决定完成条件。如果 Agent 先修改再读规则,可能已经产生违规副作用。因此进入 workspace 后应尽早读取项目规则,再进行代码探索和执行。
题目 3:编程实现——写一个最小 AGENTS.md Loader
要求读取 workspace 根目录的 AGENTS.md,没有文件时返回 None。
from __future__ import annotations
from pathlib import Path
from typing import Optional
def load_agents_md(
workspace: Path,
) -> Optional[str]:
root = workspace.resolve()
file_path = (
root
/ "AGENTS.md"
)
if not file_path.exists():
return None
return file_path.read_text(
encoding="utf-8"
)
if __name__ == "__main__":
workspace = Path(
"demo_project"
)
result = load_agents_md(
workspace
)
print(result)
#真实系统还应该进一步校验 workspace、记录规则来源,并把内容交给 ContextBuilder。
题目 4:为什么多层 AGENTS.md 需要“作用域”概念?
请结合 Monorepo 中 backend 与 frontend 使用不同运行环境的例子解释。
Monorepo 根目录可能只有全局规则,而 backend 和 frontend 可能分别使用 Python/pytest 与 Node/pnpm。修改 backend 文件时应该应用根规则加 backend 局部规则,修改 frontend 文件时应用根规则加 frontend 局部规则。如果只读取根文件,Agent 会缺少模块细节;如果无条件使用所有子目录规则,又会把不相关规则混在一起,因此必须按目标路径计算生效作用域。
题目 5:为什么“禁止修改 tests/”最好不仅写进 Context,还要进入 Middleware?
请说明软约束与硬约束的区别。
AGENTS.md 注入 Context 后,模型大多数时候会遵守,但模型仍可能因为复杂推理、错误理解或上下文冲突生成修改 tests 的 Tool Request。若规则被解析为
allow_modify_tests=False并接入 Middleware,则edit_file("tests/...")可以在执行前确定性拒绝。前者减少违规意图,后者阻止真正副作用,两层配合更可靠。
题目 6:用户明确要求“修改 tests/”,但 AGENTS.md 写着禁止修改,系统应该怎么处理?
请说明为什么不应该静默选择其中一边。
这是一个显式规则冲突。系统应该告诉用户当前项目规则禁止修改 tests/,并说明用户请求与项目约束不一致。后续是否允许覆盖,应由更高层策略决定:有些规则永久 DENY,有些需要特定权限或人工批准。无论如何都不应该偷偷忽略 AGENTS.md,也不应该默默拒绝而不给原因,冲突应被记录进 Run 与 Trace。
题目 7:如何判断 AGENTS.md 写得好不好?
请给出至少五个检查标准。
可以检查:规则是否直接影响 Agent 行为;是否具体而不是模糊口号;是否可以验证,例如明确测试命令;是否区分禁止、要求和建议;是否避免把大量背景知识塞进去;是否明确完成条件;是否与实际项目 CI、版本和目录结构一致;关键规则能否进一步结构化并被 Middleware 执行。好的 AGENTS.md 应短、清晰、稳定、可操作。
题目 8:一次任务同时修改 backend 与 frontend,规则应该怎样加载?
先按每个目标路径分别收集从 workspace 根到目标目录的 AGENTS.md。根规则对两边生效,backend 和 frontend 局部规则只进入各自操作的 Context 与 Policy。若测试命令、运行环境或约束差异明显,可以拆成两个 Task;跨目录移动则同时检查源与目标作用域,不能把所有子目录规则无差别拼接。
题目 9:为什么一次 Run 要记录规则文件 digest 和组合 fingerprint?
文件名不能说明内容是否变化。digest 能标识每份实际读取的规则,组合 fingerprint 能标识当时按顺序生效的整体快照。它们让 Trace 可以复现决策,也能在副作用执行前发现规则已经改变,避免模型使用旧规则而执行层使用新规则。
题目 10:为什么修改 AGENTS.md 应使用独立授权路径?
如果普通 Agent 可以先删掉禁止条款再继续执行,它就能通过修改 Policy 来源给自己扩大权限。独立入口可以要求审批,记录旧内容、新内容、摘要和理由,并让新规则从明确的后续 Run 生效。这样规则仍可维护,但不能被受约束的动作偷偷绕过。
进一步阅读
- Project-level Agent Instructions:理解项目规则如何影响 Coding Agent 行为。
- Rule Precedence:研究 System、Project、User、Skill 之间的优先级。
- Policy as Code:把“禁止修改 tests/”从文字规则升级为可执行策略。
- Monorepo Scoping:大型仓库中如何按目录应用局部规则。
- ContextBuilder:把项目规则与 Skills、Memory、Conversation 组合。
- Middleware:关键项目规则如何在 Tool Execution 前二次校验。
- Trace:记录规则加载、冲突和拦截结果。
- Configuration Management:规则文件如何随项目版本管理和审查。
术语表
- AGENTS.md:位于项目或子目录中的 Agent 规则文件,用于描述当前项目的运行环境、测试方式、修改限制和完成条件等。
- Project Rules:只对当前项目或目录作用域生效的规则,与跨项目复用的通用 Skill 不同。
- Rule Scope:某条规则适用的目录、模块或资源范围,例如 backend/AGENTS.md 只对 backend 子树生效。
- Rule Precedence:多个规则来源发生冲突时采用的优先级体系,例如安全硬规则、项目规则、局部规则与 Skill 的关系。
- ProjectPolicy:把 AGENTS.md 中关键自然语言规则解析成结构化字段后形成的可执行项目策略对象。
- Rule Conflict:不同规则来源对同一动作给出不一致要求的情况,例如用户要求修改 tests/,但项目规则明确禁止。
- Rule Discovery:Agent 进入 workspace 或处理某个目标文件时,自动查找对应 AGENTS.md 的过程。
- Rule Source:组成当前规则集合的具体 AGENTS.md 文件及其路径、内容和摘要信息。
- Rule Snapshot:某次 Run 实际使用的有序规则集合,执行期间应保持可复现,并在规则变化时显式刷新。
- Rule Fingerprint:根据各规则来源摘要计算出的组合标识,用来检测规则集合是否发生变化。
- Policy Self-modification:执行者通过修改约束自己的规则文件来放松权限,应由独立授权路径阻止。
- Policy Enforcement:不仅把规则展示给模型,还在 Middleware、ToolExecutor 等确定性执行层真正阻止违规动作。
本章总结
这一节,我们把 Coding Agent 最重要的“项目意识”补上了。
前面 Skill 解决:
这类任务一般怎么做
例如:
python-debug
flask-project
data-analysis
但进入真实代码仓库以后,Agent 还必须知道:
这个项目自己要求怎么做
所以我们引入,AGENTS.md。
例如:
Python 3.9
不允许修改 tests/
使用 pytest
修改代码后必须执行测试
不允许新增第三方依赖
这些规则会直接改变:
修复方案
可修改范围
Tool 选择
验证方式
完成条件
这一章最重要的第一条原则是,进入项目,先读规则,再动代码。
因为如果 Agent 已经:
改了 tests/
升级了依赖
删了文件
再发现项目规则禁止这些动作,已经太晚。
第二条原则是,AGENTS.md 不是 Skill。
可以直接记住:
Skill
→ 通用方法
AGENTS.md
→ 当前项目特殊规则
一个 python-debug Skill 可以在几十个项目复用。
但
Python 3.9
禁止修改 tests/
只属于当前项目。
第三条原则是,项目规则应该尽量具体、可验证。
例如:
使用 pytest
最终执行 pytest -q
不允许新增第三方依赖
都比:
代码要规范
修改要谨慎
更有执行价值。
我们实现了:
AgentsMdLoader
ProjectRules
RuleSource
find_agents_files()
让 Agent 能够:
进入 workspace
↓
发现 AGENTS.md
↓
读取规则
↓
按目标目录计算作用域
校验路径、符号链接与内容大小
保存来源 digest 与组合 fingerprint
↓
注入 ContextBuilder
配套 Live Coding 入口不再只读取布尔字段,而是把完整适用规则注入真实模型请求;关键的 tests/ 写入限制同时落在 Middleware 和 Workspace Tool。AGENTS.md 自身也不能通过普通编辑路径悄悄改写,需要单独授权。
对于 Monorepo,还可以:
root/AGENTS.md
+
backend/AGENTS.md
共同作用于 backend 文件。
这让项目规则从:
一个静态文件
升级成,有作用域的规则系统。
第四条原则是,关键规则不能只停留在 Prompt。
例如:
不允许修改 tests/
如果只告诉模型:
不要改 tests/
仍然是软约束。
更稳的做法:
AGENTS.md
↓
解析
↓
ProjectPolicy
↓
Middleware
↓
真正阻止 edit_file("tests/...")
这就形成:
行为层规则
+
执行层规则
双重保障。
第五条原则是,规则冲突必须显式处理。
如果用户说:
“帮我改 tests/。”
但 AGENTS.md 说:
“禁止修改 tests/。”
Agent 不应该偷偷选一边。
而应该:
明确提示冲突
记录 Trace
根据策略决定 DENY / Approval / 覆盖
这才是真实工程该有的规则治理。
到这里,第6部分的高级能力已经形成:
Planner
→ 复杂任务先规划
SubAgent
→ 复杂任务拆给多个自治执行单元
Skills
→ 通用能力模块化
AGENTS.md
→ 项目规则模块化
这四个能力放在一起以后,一个 Coding Agent 已经不再只是:
LLM + Tool
而开始真正像一个:
能理解项目
能按计划执行
能调用专门 Agent
能加载相关能力
能遵守项目规则
的工程执行系统。
下一部分,我们会进入,Observability 与 AgentOps。
下一节首先要解决,Tracing:完整记录 Agent 每一步。
因为系统越复杂,越必须知道:
到底发生了什么
哪一步出错
用了哪个 Tool
为什么失败
花了多少时间
没有 Trace,复杂 Agent 出问题以后基本只能靠猜。

















请登录后查看评论内容