修改现有项目之前，先整理这五类信息

AgentField 编辑整理｜现有项目交接工作流。文中的 AgentField 文件关系来自 2026 年 9 月 15 日的本地源码核对；任务示例用于说明方法，本轮没有执行功能修改或宣称测试通过。

接手已有项目时，先把“要改哪里”查清楚，通常比直接列改动方案更有用。同一个列表可能既接收页面首次加载的数据，又在点击筛选后重新请求；只找到画卡片的文件，还不足以判断问题发生在哪一步。

准备一页交接说明即可，不必把整个仓库复制给协作者。下面五类信息的重点，是让每个判断都能回到文件、配置或一次实际观察。

一、用户从哪里进入，代码从哪里开始

先记录页面地址、进入路径和触发动作。例如，本次要处理的是“从首页进入列表后切换分类”，还是“直接打开文章详情”？它们可能共用组件，却不一定走相同的数据流程。

以本站源码为例，apps/web/app/page.tsx 在首页加载时调用 listPosts('')，并把结果交给 HomeFeed。这说明入口不只有视觉上最像列表的组件。此处是源码关系核对，不能据此断言线上请求已经正常。

交接时写清“已确认入口”和“仍待确认的入口”，不要把根据文件名作出的猜测写成结论。

二、怎样运行，当前基线是什么

从项目现有说明和配置中找启动、构建、检查命令，记录用途及需要的前置条件，再按本次任务选择要运行的检查。

本站当前根目录 package.json 中，npm run dev 并行启动 Web 与 API 的开发脚本；npm run build 先生成数据库客户端，再构建 API 和 Web。名字相近的命令不一定做同一件事，其他项目应读自己的配置。

交接记录至少区分三种情况：“未运行”“已经运行但失败”“运行通过”。若本来就存在错误，保留相关输出和发生条件，后续才能判断它是不是本次修改引入的。这里列出命令用途，不代表本文已执行这些命令。

三、哪几份文件决定这次行为

沿着“入口—显示—数据”画一条短路径，并给每份文件写一句职责。本站首页列表可以这样记录：

apps/web/app/page.tsx
  首页首次获取列表，传给 HomeFeed
apps/web/components/home-feed.tsx
  保存筛选与页码，筛选变化后调用列表函数
apps/web/lib/api.ts
  组装列表请求参数，把响应转换为页面使用的数据

这是核对过的文件职责，不是要求三份一起修改。若现象是切换分类后内容不对，就分别检查筛选状态、请求参数和返回数据；不能仅因为卡片显示在某个组件里，就认定原因一定在那个组件。

把“已确认相关”“可能相关”“本次无需涉及”分开，能够减少范围不断扩大的情况。

四、改变之后，哪条行为必须成立

为具体状态转换写验收条件，而不只写最后一张页面长什么样。下面是交接格式示例，不是本次测试结果：

起点：列表位于后续页码，尚未选择目标分类
动作：切换到另一分类
预期：页码回到第一页，列表对应新分类
检查：核对界面页码、请求参数和返回内容
边界：新分类无内容或请求失败时，分别检查相应提示

若看不到请求或缺少数据条件，就把对应项记为待验证。界面文字变化和数据变化要分别检查，不能用其中一项替代另一项。

五、哪些约束必须一起交接

记录已有修改归属、可改范围、不可改的接口约定，以及是否允许安装依赖、改数据或发布。把回退所需的原始文件或版本位置写清楚，但不要把账号、密钥和环境文件全文放进交接稿。

这些约束要能约束实际动作。例如“仅处理列表筛选，不改文章正文格式；先在本地验证，发布另按已确认流程执行”，比一句“谨慎修改”更容易遵守。

最后，把五类信息压成一页：

入口与触发动作：
运行方式与已有基线：
相关文件及依据：
必须成立的状态转换：
范围、已有修改和执行约束：
仍待确认：

先解决会改变实施方向的未知项，再开始修改。你最近接手的项目里，哪一类信息最难找到？可以留下查找过程和依据，帮助下一位从正确入口开始。