Hermes Agent 文件约定：SOUL.md vs .hermes.md vs AGENTS.md

如果你在使用 Hermes Agent 开发项目，可能会对这几个文件感到困惑：SOUL.md、.hermes.md、AGENTS.md——它们分别干什么？该放哪里？能不能混用？

本文将一次性理清它们的定位、用法和最佳实践。

一、三份文件的核心定位

Hermes Agent 设计了三种不同粒度的上下文文件，各有用途，不建议混用。

文件	用途	推荐位置
`SOUL.md`	Agent 的人格、行为风格、长期身份	`~/.hermes/SOUL.md`（全局）
`.hermes.md` / `HERMES.md`	项目最高优先级规则	项目根目录
`AGENTS.md`	项目开发规范、架构说明、编码规则	项目目录，可递归

SOUL.md —— 全局人格文件

SOUL.md 定义的是 你希望 AI 助理如何与你沟通和工作 的全局偏好，而不是某个项目的技术规则。

适合放的内容：

你的工作习惯（如"使用简洁的中文回复"）
回复风格偏好（如"直接给命令，不要解释"）
代码偏好（如"优先用 TypeScript"）
跨项目的通用原则

⚠️ 不要把项目规则写入 SOUL.md。SOUL 是人格，不是项目配置。混入项目规则后，切换项目时会让 agent 行为混乱。

.hermes.md —— 项目宪法

.hermes.md 是项目的最高优先级规则文件，放在项目根目录。它类似一份"AI 项目宪法"，定义不可违反的事项。

适合放的内容：

项目总体目标和范围
不可违反的安全规则
必须遵守的架构决策
技术栈约束

# Matrix Manager 项目规则

这是一个 Matrix 运维管理平台。

目标：
- 保持代码简洁
- 优先使用 TypeScript
- 所有 API 必须有类型定义
- 修改数据库结构必须同步 migration

禁止：
- 不允许直接修改生产配置
- 不允许删除测试

Hermes 会在加载项目上下文时优先加载 .hermes.md / HERMES.md。

AGENTS.md —— 开发规范

AGENTS.md 更接近传统开发文档，包含架构说明、编码规范、构建和测试流程。

适合放的内容：

项目架构描述
编码规范（格式、命名、类型要求）
构建与测试流程
子目录的专项规则

# Development Guide

## Architecture

frontend: React + Vite + Zustand
backend: FastAPI + PostgreSQL

## Coding Style

Python: black format, type hints required
Typescript: eslint required

## Testing

Before commit: npm test && pytest

Hermes 支持递归发现子目录的 AGENTS.md，可以逐层细化规范。

二、推荐目录结构

~/projects/
├── matrix-manager/
│   ├── .hermes.md          ← 项目总规则
│   ├── AGENTS.md           ← 架构 + 开发规范
│   ├── backend/
│   │   └── AGENTS.md       ← 后端细节规范
│   └── frontend/
│       └── AGENTS.md       ← 前端细节规范
│
└── sing-box-panel/
    ├── .hermes.md
    └── AGENTS.md

分层细化示例

frontend/AGENTS.md：

Frontend rules:
- 使用 React hooks
- 禁止 class component
- UI 使用 shadcn
- API 调用统一放 src/api

backend/AGENTS.md：

Backend rules:
- FastAPI router 分离
- SQLAlchemy model 不直接返回
- 使用 pydantic schema

三、最佳实践要点

✅ 推荐的职责分离

~/.hermes/SOUL.md       → 你的个人 AI 工程师偏好（全局）
项目根目录 .hermes.md   → 每个项目的总体目标
项目目录 AGENTS.md      → 技术规范（可递归）

❌ 不建议的做法

全部写到一个巨大的 AGENTS.md：每次加载浪费 token，AI 容易抓不到重点，项目变化难维护。官方对上下文文件大小有限制，超出后会截断。
把项目规则放 SOUL.md：切换项目后 agent 仍然记着上一个项目的规则，导致行为混乱。
文件命名混淆：注意是 SOUL.md（灵魂/人格），不是 soud.md。

关于 HERMES.md

实际上 .hermes.md 和 HERMES.md 功能相同，都是项目最高优先级规则文件。但注意 .hermes.md 是隐藏文件（Unix 点文件），HERMES.md 是普通可见文件。选择哪个取决于你的习惯——有些人喜欢点文件表示 AI 配置文件，有些人喜欢可见文件方便团队成员发现。

四、适用场景总结

场景	推荐文件	理由
设定 AI 回复风格	`SOUL.md`	全局人格，跨项目生效
定义项目目标和约束	`.hermes.md`	最高优先级，不可违反
描述架构和编码规范	`AGENTS.md`	可递归，适合分层细化
子目录专项规则	`AGENTS.md`（子目录）	递归发现，自动加载
多个长期项目同时维护	三份文件各司其职	切换项目时行为清晰

五、实际工作流示例

假设你同时维护 Matrix 运维 UI 和 Sing-box 面板 两个项目：

SOUL.md 写好你的通用偏好（简洁回复、命令行优先等）
进入 matrix-manager/ 时，.hermes.md 告诉 agent 这是 Matrix 项目
AGENTS.md 告诉 agent 前端用 React，后端用 FastAPI
切换到 sing-box-panel/ 时，替换的只有 .hermes.md 和 AGENTS.md
SOUL.md 始终不变——agent 的沟通方式保持一致

这样你换项目、开多个 agent 或者与人协作时，每种文件的职责都非常清晰，互不干扰。