---
title: "Agent 入口文件与会话交接骨架"
url: https://lingming.blog/prompts/agent-entry-and-handoff-templates/
date: 2026-07-27
lastmod: 2026-07-27
tags: ["提示词","AI 编程","软件工程"]
categories: ["人工智能","软件工程"]
---

# Agent 入口文件与会话交接骨架


## 场景 / 目的

用 AI 做项目时，与其每次会话重新交代一遍规则，不如在仓库里维护两类信息：一条能被当前工具发现的**入口加载链**（通常从 `CLAUDE.md` / `AGENTS.md` 开始），说明项目是什么、怎么跑、哪些是红线；一份**交接文件**（`SESSION_HANDOFF.md`），记录当前状态，供下一次会话接手。

下面两段骨架可以直接复制到新项目里，把尖括号部分替换成自己的内容。

使用时有三点值得注意：先确认工具的发现、导入和路径规则，确保必读内容都在同一条可验证的加载链上；能变成 lint、hook、CI 或测试的约束就迁过去，并标清它是可运行检查、本地护栏还是远端硬门禁；交接文件每次覆盖写，不要追加成日志。这三条的来龙去脉，写在[《AI 协作项目该写几份文档》]({{< relref "/posts/2026/how-many-docs-for-ai-projects.md" >}})里。

## 入口文件骨架（可复制）

```prompt
# 项目名 — Agent 入口文件

## 这是什么
一句话说明项目做什么、给谁用。

## 怎么跑
- 安装：<命令>
- 开发：<命令>
- 测试：<命令>          # 改完必须跑通这条
- 构建：<命令>

## 红线（触碰前先停下来问）
- <例：不直接提交到 main，走分支 + PR>
- <例：不修改 migrations/ 下已合并的文件>
- <例：不新增运行时依赖，除非先确认>

## 自动化检查与门禁
- 可运行检查：<命令及配置路径，例如 make test>
- 本地护栏：<hook 路径；说明它可能被绕过>
- 远端硬门禁：<CI workflow 与分支保护 / ruleset 配置>

## 约定
- <例：新组件放 src/components/，一个文件一个组件>
- <例：错误信息面向用户，不暴露堆栈>

## 深入了解（按需查阅，不必默认读取）
- 架构说明：docs/ARCHITECTURE.md
- 部署流程：docs/DEPLOYMENT.md
```

## 交接文件骨架（可复制）

```prompt
# 会话交接 — 更新于 <YYYY-MM-DD>，对应 commit <short-sha>

## 当前目标
<这一阶段要做成的一件事>

## 已完成
<只写 git log 里看不出来的部分：当时为什么这么选>

## 下一步
<具体到可以直接开工的粒度，并说明为什么是这一步>

## 卡在哪
<当前阻塞，以及需要什么条件才能解开>

## 已否掉的方案
- <方案> —— 否掉原因：<原因>
```

## 备注（可选）

交接文件顶部的日期和 commit 不要省。它成本极低，也是让下一次会话主动检查文档新鲜度最简单的机制之一——一份过期的交接文档可能比没有更糟，因为 agent 可能直接采信它。