---
title: "项目指引文件"
description: "用 AGENTS.md 或 CLAUDE.md 为 Peri 提供项目规则、任务入口和验证命令"
---

> Documentation Index
> Fetch the complete documentation index at: https://konghayao.github.io/peri-cool/llms.txt
> Use this file to discover all available pages before exploring further.

# 项目指引文件

项目指引文件用于告诉 Peri：这个仓库如何构建、模块边界在哪里、哪些规则不能破坏，以及完成修改后如何验证。Peri 把选中的内容加入系统提示词，但它仍是提示上下文，不是编译器或强制策略引擎。

## 主会话加载规则

创建会话时，冻结入口只检查当前工作目录下的以下候选，并读取第一个存在的文件：

1. `{cwd}/AGENTS.md`
2. `{cwd}/CLAUDE.md`
3. `{cwd}/.claude/AGENTS.md`

它不会向父目录递归，也不会合并多个主文件。如果第一个存在的文件内容为空，冻结入口不会继续尝试后面的候选。`~/.claude/AGENTS.md` 属于普通 middleware 查找路径，不是主会话冻结入口的候选；不要依赖它向项目主会话提供规则。

如果 `{cwd}/CLAUDE.local.md` 存在且非空，其内容会追加到冻结内容后。这个文件适合不入库的本机说明，但仍应避免写入真实密钥。

> **Caution**
>
> 从仓库子目录启动 Peri 时，父目录的 AGENTS.md 或 CLAUDE.md 不会自动继承。需要这些规则时，应从包含指引文件的目录启动，或在当前目录提供明确的路由文件。

## 冻结语义

选中的项目指引在会话创建时读取并冻结。同一会话后续不会因磁盘文件变化自动更新；从该会话派生的子代理复用同一份冻结数据。

修改指引文件后，新建会话才能可靠看到新内容。这个稳定前缀也有利于 provider 的 prompt cache，但实际命中率和费用取决于 provider、模型、请求前缀与服务端策略，Peri 不承诺固定比例。

## `@import`

只有选中的 CLAUDE.md 系列主文件会展开以下语法：

```md
<!-- @import docs/rust-rules.md -->
```

路径相对于包含该 import 的文件。解析器有递归深度限制和循环检测；AGENTS.md 不解析 `@import`。导入适合拆分必须随会话加载的小段规则，不适合把整套长文档默认塞进上下文。

## 推荐内容

| 类别 | 应写内容 |
| --- | --- |
| 仓库路由 | 模块职责、稳定入口、应先读的模块指引 |
| 架构不变量 | 不能跨越的边界、唯一事实源、事件或数据流契约 |
| 任务路由 | 修改某类功能时应查看的路径、symbol 或测试 |
| 验证命令 | 有范围的 build、test、lint、doc test 命令 |
| 项目差异 | 通用知识无法推断的约定、平台限制和已知陷阱 |
| 安全边界 | 凭据处理、危险操作和需要用户确认的动作 |

规则应能执行和验证。例如：

```md
- 修改 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 的区别

项目指引描述“这个仓库是什么、在这里必须遵守什么”；[Skills](/peri-cool/docs/features/skills/)描述“某类任务按什么流程完成”。跨项目可复用的研究、调试或发布流程更适合 Skill，仓库特有的模块入口和验证命令更适合 AGENTS.md 或 CLAUDE.md。

Source: https://konghayao.github.io/peri-cool/docs/features/claude-md/index.mdx