AGENTS.md是Hermes启动时加载的运行时规则文件，必须置于项目根目录并以纯Markdown格式编写，首行为#项目名称，按项目定位、技术栈声明、禁区清单、交付要求顺序组织；子目录AGENTS.md仅在该目录启动时生效，不继承根目录规则；生效需满足：从根目录启动、无更高优先级.hermes.md/HERMES.md、调试日志显示Loaded project rules from AGENTS.md。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要为当前项目定义一套明确、可执行、能被Hermes自动识别的开发规范，而不是靠每次口头提醒或写在README里等它“自己猜”。AGENTS.md不是文档附件，是Hermes启动时加载的运行时规则，写错位置、格式或层级，它根本看不到。
确认AGENTS.md生效的前提条件
第一步：确保你从项目根目录启动Hermes。如果人在frontend/子目录下执行hermes，Hermes只会读取frontend/AGENTS.md，而不会向上查找根目录的同名文件——【根目录AGENTS.md不会自动继承】。
第二步：检查当前目录是否存在.hermes.md或HERMES.md。这两类文件优先级高于AGENTS.md，一旦存在，Hermes会直接加载它们并忽略AGENTS.md。
第三步：用hermes --debug启动，观察控制台输出中是否出现Loaded project rules from AGENTS.md。没这行日志，说明文件未被识别或路径不对。
AGENTS.md内容结构与必填字段
AGENTS.md必须是纯Markdown格式，不支持YAML或JSON嵌套。首行必须是项目名称（带#号），否则Hermes会跳过解析。
核心区块按以下顺序组织，顺序不可颠倒：
- 项目定位（1～2句话）：说明这是什么系统、谁在用、关键约束是什么。
- 技术栈声明（必须精确到版本）：比如
Python 3.11 + FastAPI 0.115，不能写“Python最新版”。 - 禁区清单（用-开头的无序列表）：每条必须是可执行的否定指令，例如
- 禁止提交 .env 文件，不能写“注意保护密钥”。 - 交付要求（带编号步骤）：
① 所有PR必须关联Jira任务号
② CI通过后自动触发预发环境部署
③ 部署日志需存入logs/deploy/目录
不要写解释性文字、背景故事或欢迎语。Hermes只提取带动作动词的句子，其余内容会被压缩丢弃。
子目录AGENTS.md的渐进加载实操
方法一：前端专用规则
在frontend/目录下新建AGENTS.md，内容只需聚焦局部约束：
这是React 19项目，使用Vite构建。<br>- 所有组件必须用TypeScript编写<br>- CSS只允许用Tailwind，禁用全局class<br>- hooks命名必须以use开头
方法二：后端专用规则
在backend/目录下新建AGENTS.md，避免和根目录重复：
这是FastAPI微服务，数据库用PostgreSQL 15。<br>- 每个路由必须有Pydantic v2模型校验<br>- 异步操作一律用async/await，禁止threading<br>- migration文件由alembic生成，禁止手改
方法三：数据库专项规则（慎用）
仅当DBA介入时才在db/migrations/下放AGENTS.md，内容必须窄：
PostgreSQL迁移脚本专属规则。<br>- 每次迁移必须包含up/down双向SQL<br>- down脚本不得删除生产数据<br>- 执行前必须人工确认
【迁移脚本执行前不弹确认，Hermes会直接跳过该规则】
验证AGENTS.md是否被正确加载
启动Hermes后，直接输入：show project rules。它会输出当前生效的所有规则条目，不含注释、空行、标题，只显示可执行语句。
接着测试一条禁区行为：git add .env。如果AGENTS.md里写了- 禁止提交 .env 文件，Hermes会立刻拦截并提示：“违反项目规则：禁止提交 .env 文件”，而不是等你git commit后再报错。
最后执行一个交付动作：deploy to staging。若AGENTS.md中定义了CI流程，Hermes会自动调用对应脚本，并把日志路径logs/deploy/写入执行上下文。
