# AG-02｜Agent 怎样理解项目并验证结果

核验日期：2026-10-10。目标是把陌生仓库变成可执行任务环境，保留支持结论的事实，并能在中断后继续。

![项目理解与验证逻辑架构图](<../../图表/AG-02_架构.svg>)

## 1. 先补齐项目事实

通用模型不知道项目当前代码、资产数据和未提交改动。项目事实至少包括目标、目录、技术栈、入口、依赖、数据格式、当前问题、允许改动范围和验收方式。目录存在不等于文件已读；README 的架构意图也不等于实现已经符合。

本版本分析 Aipcg 时，同时读取学习文档、当前调用代码和历史产物；分析 Cindy 时，同时读取规范索引、仓库地图、package 清单和调用链。这样才能区分“规则要求”“源码支持”“历史运行”和“本次实测”。

## 2. 沿任务建立阅读路线

从根说明和项目地图开始，找到运行入口；再追调用方、参数结构、配置、结果与错误分支；最后看相关测试和日志。阅读范围由问题驱动，而不是一次把全仓复制进对话。

例子是“资产清单增加缺列报错”。先读 CLI 的 CSV 入口，再看字段检查和问题返回，最后运行缺列样本。不需要同时读取所有材质导出器。若入口调用其他模块，继续追踪直到能够解释行为。

| 阅读位置 | 要回答的问题 | 证据产物 |
|---|---|---|
| 入口 | 谁发起动作？参数从哪里来？ | 函数与调用位置 |
| 数据 | 字段、单位、默认值是什么？ | schema／样例 |
| 依赖 | 哪个环境实际执行？ | 解释器、包、配置 |
| 返回 | 完成与失败怎样表达？ | 结果字段与错误 |
| 验证 | 哪些检查能发现问题？ | 命令、答案、结果 |

## 3. 上下文分层

稳定规则说明长期边界；任务说明记录这次目标；按需资料保存详细事实；当前状态保存已经做过什么；工具结果保存实际观察。各层更新频率不同，不宜混为一份长提示。

例如资产命名规范可长期保留，某次扫描输出不该成为长期规则；一条“模型经常搞错目录”的反馈需要写明事件与适用范围，而不是永久禁止所有目录操作。项目源代码通常仍是实现事实，应保持从摘要回到代码的路径。

压缩上下文时保留目标、约束、已确认事实、失败尝试和未完成项。删除冗长重复日志通常合理；删除“只读输入”“单位厘米”会改变任务含义。原始记录留在文件里便于回查。

## 4. 搜索与确认

文件名搜索适合已知模块；符号搜索适合已知函数；全文搜索适合错误消息、字段和规则；语义检索适合没有精确词的资料发现。命中只是线索，还要打开上下文并核对调用关系。

常用本地命令是 `rg --files` 找文件和 `rg -n 'inspect_csv' 路径` 查符号。执行前确认当前目录与目标机器；远程路径不能直接交给本机读取器。对于相同名字的旧版本，比较修改日期、HEAD、文件哈希与运行配置，不凭第一个搜索结果下结论。

文档说 device-link “零依赖”，而 package 清单含协议包依赖时，可以保留“宿主能力注入”的结构判断，并登记导航措辞与实现差异。这比删除其中一项证据或照抄结论更便于后续维护。

## 5. 记忆的用途与更新

会话摘要帮助接续当前讨论；项目知识保存稳定事实与决定；用户偏好描述持续要求；任务进度属于本次工作状态。知识项应有出处、核验日期与失效条件。

“当前默认重试次数为 2”需要配置依据，配置变化时更新；“用户要求 V2.0 独立完整”属于范围约束，不能因后续局部任务自动丢掉。数据库、文件、向量库都是存储形式，形式本身不能保证记忆准确。

新资料与旧记忆冲突时，确定适用版本，回读事实来源，更新派生知识。不要以旧摘要优先覆盖当前代码，也不要把一次成功尝试自动推广成通用规则。

## 6. 拆分长任务

每步写输入、输出、依赖和完成条件。先处理能暴露主要不确定性的步骤：Aipcg 坐标不明时先核对单位；PPT 内容未成稿时先完成学习稿；外部模型能力未核验时先查官方文档。

独立资料读取可以同时进行；同一函数的设计与修改通常有顺序；多个入口依赖同一协议时要统一接口后再分开。任务完成比例最好按已交付成果判断，不按工具调用数判断。

一份计划要能直接告诉读者会得到什么，例如“生成每视频一份双语 Markdown 并核对段落完整性”。“做必要修改、完成验证”缺少对象和结果，不能帮助接手者判断。

## 7. 验证选择要对应目标

语法和类型检查发现结构错误；单元样本验证局部规则；集成检查验证数据交接；浏览器与引擎检查验证界面和实际场景；人工评审判断可读性、美术质量与取舍。

资料整理要核对来源和时间戳，不能只运行格式检查。UE 场景需要几何与视觉两类证据，不能只看 JSON。字幕要核对原文、翻译、时间和段落完整性，机器流程成功也不等于翻译准确。

本版本的 [学习实验结果](<../../检查记录/学习实验结果.json>) 是确定性执行证据；[仓库版本](<../../资料记录/仓库版本.json>) 是静态分析定位；[Aipcg 历史报告](<../../sources.html#ref-59ea71868f8fca>) 是旧任务证据。不同证据不能相互冒充。

## 8. 一份可接续任务包

任务包可由三份短文构成。项目导读：目标、入口、数据和运行方法。任务说明：具体改动、范围和接受标准。交接：完成项、检查命令与结果、未验证内容和下一步。

教学任务包如下：

```text
项目：CSV 资产检查器；入口 示例/学习实验/lab.py。
任务：缺少 kind 列时给出明确错误，保持中文路径与输入文件。
依据：inspect_csv 的 required 集合；missing_columns.csv。
验收：缺列必须失败；正常样本问题行号和规则保持符合答案。
交接：实际运行命令、结果文件、行为变化、尚未运行的模型对照。
```

中断后先读交接，再确认文件与环境是否变化。结果缓存是旧观察，不能自然替代当前执行。若产物变了，需要判断旧检查是否仍适用。

## 9. 练习与验收

使用 [任务与交接模板](<../../模板/任务与交接.md>)，为自己项目完成导读、任务和交接各一份。另一位读者应能找到入口、解释目标、运行检查并看懂尚未完成项。练习不要求改真实生产项目。

检查四个常见失败：读错版本；只列目录没有追调用；把进度写成长久规则；没有对应成果的验证。改进时补充缺失事实，不必增加无关文档或角色。

![本章思维导图](<../../图表/AG-02_思维导图.svg>)

## 来源与衔接

依据 [Cindy 仓库地图](<../../sources.html#ref-ad87aa7fb2d489>)、[开发工作流](<../../sources.html#ref-fe7e6901ae6eb1>)、[Aipcg 导读](<../../sources.html#ref-2655b311ab2b9c>) 与本地设计资料归纳。具体 Claude Code 载体见 [CC-02](<../ClaudeCode/CC-02_项目上下文与扩展.md>)，项目数据见 PCG-01，运行时见 CY-02。