项目指引文件
项目指引文件用于告诉 Peri：这个仓库如何构建、模块边界在哪里、哪些规则不能破坏，以及完成修改后如何验证。Peri 把选中的内容加入系统提示词，但它仍是提示上下文，不是编译器或强制策略引擎。
主会话加载规则
Section titled “主会话加载规则”创建会话时，冻结入口只检查当前工作目录下的以下候选，并读取第一个存在的文件：
{cwd}/AGENTS.md{cwd}/CLAUDE.md{cwd}/.claude/AGENTS.md
它不会向父目录递归，也不会合并多个主文件。如果第一个存在的文件内容为空，冻结入口不会继续尝试后面的候选。~/.claude/AGENTS.md 属于普通 middleware 查找路径，不是主会话冻结入口的候选；不要依赖它向项目主会话提供规则。
如果 {cwd}/CLAUDE.local.md 存在且非空，其内容会追加到冻结内容后。这个文件适合不入库的本机说明，但仍应避免写入真实密钥。
选中的项目指引在会话创建时读取并冻结。同一会话后续不会因磁盘文件变化自动更新；从该会话派生的子代理复用同一份冻结数据。
修改指引文件后，新建会话才能可靠看到新内容。这个稳定前缀也有利于 provider 的 prompt cache，但实际命中率和费用取决于 provider、模型、请求前缀与服务端策略，Peri 不承诺固定比例。
@import
Section titled “@import”只有选中的 CLAUDE.md 系列主文件会展开以下语法：
<!-- @import docs/rust-rules.md -->路径相对于包含该 import 的文件。解析器有递归深度限制和循环检测；AGENTS.md 不解析 @import。导入适合拆分必须随会话加载的小段规则，不适合把整套长文档默认塞进上下文。
| 类别 | 应写内容 |
|---|---|
| 仓库路由 | 模块职责、稳定入口、应先读的模块指引 |
| 架构不变量 | 不能跨越的边界、唯一事实源、事件或数据流契约 |
| 任务路由 | 修改某类功能时应查看的路径、symbol 或测试 |
| 验证命令 | 有范围的 build、test、lint、doc test 命令 |
| 项目差异 | 通用知识无法推断的约定、平台限制和已知陷阱 |
| 安全边界 | 凭据处理、危险操作和需要用户确认的动作 |
规则应能执行和验证。例如：
- 修改 ACP 事件时，同时检查 Agent 发射、ACP 映射和 TUI 消费。- 完成前运行 `cargo test -p peri-acp --lib mapper`。- 临时 Todo、当前 issue 叙事或很快过期的进度；
- 可从 manifest 或代码自动得到的动态数量；
- 大段 API 文档、模块 inventory 或实现细节副本；
- “写好代码”“保持质量”这类无法验证的泛化要求；
- 真实 API key、token、连接串或个人信息；
- 与更高优先级代码和契约测试冲突的历史说明。
把项目指引当作路由层，而不是知识仓库：稳定工程规则放到专门 standards，设计背景放到 design 或 ADR，当前需求放到 active spec，指引文件只告诉 Agent 去哪里读以及如何验证。
架构或命令变化时，同步检查对应路由是否仍准确。删除过时规则通常比继续追加例外更安全；固定行数上限并不通用于所有仓库，重点是每段内容是否稳定、必要且能减少错误决策。
与 Skills 的区别
Section titled “与 Skills 的区别”项目指引描述“这个仓库是什么、在这里必须遵守什么”；Skills描述“某类任务按什么流程完成”。跨项目可复用的研究、调试或发布流程更适合 Skill，仓库特有的模块入口和验证命令更适合 AGENTS.md 或 CLAUDE.md。