第6篇：上下文文件——项目的“说明书”

上一篇我们聊了聊 CLI 的常用操作，今天来点更“硬核”的——上下文文件。

你可以把它理解成一份给 AI 看的项目说明书。每次启动 Hermes 会话时，它都会自动读取这份文件，快速了解你的项目背景、技术栈、代码规范、常用命令……然后带着这些“记忆”来回答你的问题。

为什么需要上下文文件？

想象一下：你新加入一个团队，接手一个老项目。没人告诉你项目是干嘛的、代码放哪、怎么跑测试。你只能翻文档、问同事、猜……AI 也一样。

没有上下文文件，Hermes 每次都是“失忆”状态，只能靠你反复解释。有了它，AI 一上来就“门儿清”，回答质量直接上一个台阶。

上下文文件放在哪？

Hermes 支持好几种上下文文件，按优先级从高到低排是：

.hermes.md / HERMES.md——项目说明，优先级最高
AGENTS.override.md——你自己本地的覆盖版（一般加进 .gitignore）
AGENTS.md——最常用的项目说明书
CLAUDE.md——Claude Code 的上下文文件，Hermes 也认
.cursorrules / .cursor/rules/*.mdc——Cursor 的规则文件

每次会话只会加载一个项目上下文文件（谁先匹配上就用谁）。另外还有一个 SOUL.md，它管的是 AI 的性格和说话风格，只从 HERMES_HOME 目录读取，跟项目无关，永远单独加载。

小提示：如果 AGENTS.md 旁边放了一个 AGENTS.override.md，Hermes 会加载 override 那份、忽略仓库里的 AGENTS.md。想用自己的一套指令又不想改团队共用的文件，就靠它。

里面写什么？

没有固定模板，但建议包含这些内容：

# 项目名称

## 项目简介
一句话说清楚这个项目是干嘛的。

## 技术栈
- 后端：Python 3.12 + FastAPI
- 前端：React 18 + Vite
- 数据库：PostgreSQL 15

## 常用命令
- 启动开发服务器：`make dev`
- 运行测试：`make test`
- 代码格式化：`make format`

## 代码规范
- 使用类型注解
- 提交信息遵循 Conventional Commits
- 禁止直接向 main 分支推送

上下文文件怎么用？

启动 Hermes 后，它会自动加载上下文文件。你也可以用 /context 命令手动查看或切换：

/context          # 查看当前加载的上下文文件
/context 路径     # 切换到指定文件

小技巧：多级上下文

你可以在不同层级放多个上下文文件。比如：

项目根目录：放整体介绍、技术栈
src/api/ 目录：放 API 模块的专属说明

Hermes 会合并所有找到的上下文文件，让 AI 既有全局视野，又了解局部细节。

如果项目在 git 仓库里，Hermes 会从 git 根目录一路往下，把沿途每一层的 AGENTS.md 都串起来加载，越靠近当前目录的越靠后、优先级越高。子目录里的文件则是在 AI 真正读到那个目录时才“顺手”发现并注入，不会一上来就把系统提示塞满。

注意事项

别写太长——上下文文件不是文档库，精简到 AI 一次能读完的量（几百行以内）
别放敏感信息——上下文文件会随会话发送给 AI 服务商
保持更新——项目变了，说明书也要跟着改
安全扫描——所有上下文文件都会先过一遍提示注入检查，可疑内容会被拦下。不过你自己写的 SOUL.md 是个例外：命中扫描规则不会直接封禁，只会在 /context 里标个 ⚠ 提醒你复查；但如果这个 SOUL.md 是通过 hermes profile install 之类从别人那儿装来的，那还是会照常拦截

一句话总结：上下文文件就是你和 AI 之间的“入职培训”。花十分钟写好它，之后每次会话都能省下大量解释的时间，回答质量也更高。强烈建议每个项目都配一份！