场景 / 目的
用 AI 做项目时，与其每次会话重新交代一遍规则，不如在仓库里维护两类信息：一条能被当前工具发现的入口加载链（通常从 CLAUDE.md / AGENTS.md 开始），说明项目是什么、怎么跑、哪些是红线；一份交接文件（SESSION_HANDOFF.md），记录当前状态，供下一次会话接手。
下面两段骨架可以直接复制到新项目里，把尖括号部分替换成自己的内容。
使用时有三点值得注意：先确认工具的发现、导入和路径规则，确保必读内容都在同一条可验证的加载链上；能变成 lint、hook、CI 或测试的约束就迁过去，并标清它是可运行检查、本地护栏还是远端硬门禁；交接文件每次覆盖写，不要追加成日志。这三条的来龙去脉，写在《AI 协作项目该写几份文档》里。
入口文件骨架（可复制）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
| # 项目名 — Agent 入口文件
## 这是什么
一句话说明项目做什么、给谁用。
## 怎么跑
- 安装：<命令>
- 开发：<命令>
- 测试：<命令> # 改完必须跑通这条
- 构建：<命令>
## 红线（触碰前先停下来问）
- <例：不直接提交到 main，走分支 + PR>
- <例：不修改 migrations/ 下已合并的文件>
- <例：不新增运行时依赖，除非先确认>
## 自动化检查与门禁
- 可运行检查：<命令及配置路径，例如 make test>
- 本地护栏：<hook 路径；说明它可能被绕过>
- 远端硬门禁：<CI workflow 与分支保护 / ruleset 配置>
## 约定
- <例：新组件放 src/components/，一个文件一个组件>
- <例：错误信息面向用户，不暴露堆栈>
## 深入了解（按需查阅，不必默认读取）
- 架构说明：docs/ARCHITECTURE.md
- 部署流程：docs/DEPLOYMENT.md
|
交接文件骨架（可复制）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| # 会话交接 — 更新于 <YYYY-MM-DD>，对应 commit <short-sha>
## 当前目标
<这一阶段要做成的一件事>
## 已完成
<只写 git log 里看不出来的部分：当时为什么这么选>
## 下一步
<具体到可以直接开工的粒度，并说明为什么是这一步>
## 卡在哪
<当前阻塞，以及需要什么条件才能解开>
## 已否掉的方案
- <方案> —— 否掉原因：<原因>
|
备注（可选）
交接文件顶部的日期和 commit 不要省。它成本极低，也是让下一次会话主动检查文档新鲜度最简单的机制之一——一份过期的交接文档可能比没有更糟，因为 agent 可能直接采信它。