ARTICLE · 1198540

让 Agent 理解产品:记忆、设计文档与产品上下文

发布时间：2026-10-17 13:42:47 最近访问：2026-10-17 13:42:49

一个界面问题，Agent 很快就能给出几种改法。更难的是：改完之后，怎么判断它还像不像 Magpie？

Magpie 是一款本地网关。作者说，Agent 做产品决策时会参考 Claude Code 的记忆系统和仓库设计文档。开发初期的讨论与头脑风暴被记进记忆文件；据他描述，这让一些决策和设计「比较契合」自己的偏好。

他把这套记忆称为「简陋但有效」。这里的「有效」仍是作者自己的感受；公开材料没有展示记忆内容，也没有独立验证。

根据作者自述与公开仓库文档整理；记忆文件未公开，「比较契合」尚无第三方核验。

一、两种知识，放在两个地方

沿着这条自述，可以看到两类产品知识：一类解释「为什么」，一类说明「是什么」。

记忆文件保存的是「为什么」：为什么做这个产品、讨论过哪些方案、维护者偏好什么。这些是维护者的个人积累，由 Claude Code 的记忆系统保存。公开材料没有披露文件内容；从作者的说法看，它提供的是决策背景，而不是逐条指令。

仓库文档说明的是「是什么」。Magpie 为各个子系统维护设计参考，写明职责、运行路径、状态和接口约定。对应的行为或接口发生变化时，必须在同一个提交里更新文档，尽量避免说明落后于代码。

两类知识各有边界。记忆文件未公开，外界无法核对；设计参考虽然公开，却不能证明实现正确。参考页明确要求，行为变化还要有测试和运行证据。文档负责保存契约，验证仍要看代码和实际运行。

仓库根目录的 AGENTS.md 很短，主要负责指路。它按任务告诉 Agent 先读哪些规范和设计资料：改子系统前先看对应参考并核对源码；准备或审查 PR 时按文档更新与审查规则处理；审社区 PR 前先读贡献者规则；改代码前先读教训文件。

社区有人把它比作「路由表」，作者转发了这条评述。这个比喻说的是它的结构：AGENTS.md 不复制每条规则，而是把任务映射到需要查阅的文档。规则本身更新时，入口映射可以保持不变。

因此，让 Agent 参与产品工作，不一定从编写更多规则开始。先说明每类任务开工前该读什么，就能为规则提供稳定入口；这份指路文件本身也是产品上下文的一部分。

第三类知识来自开发过程中的复盘。教训文件记录返工和验证不足，并按「规则、原因、证据」组织；同一条教训在三个不同日期出现，才会升级进代码规范。规范开篇说明，许多条目来自 PR 审查中反复提出的要求，并附有真实失误案例和对应提交号。

规范不是一次性设计好的，而是从开发过程中逐步沉淀出来：教训文件负责收集，三次不同日期的门槛筛掉偶发问题，代码规范保存反复出现的经验。公开记录显示，十天里至少有六条教训通过这道门槛。沉淀下来的不只是操作步骤，也包括哪些改动算完成、哪些验证不可省。

按公开文件中写明的记录与维护规则整理；图示概括文件关系，不代表每次执行的审计结果。

设计系统也不是维护者一人搭建的。作者提到，社区成员参与了 design system 的构建。产品上下文因此不只来自维护者的记忆与仓库文档，也有社区贡献。

效果边界同样要说清楚。「比较契合」是作者自评；记忆文件没有公开，外界无法判断其中保存了多少产品判断、传递了多少偏好，也没有量化指标或第三方审计。

公开仓库能看到的是维护机制：教训记录持续更新，设计参考随相关代码变动而维护。但这些材料不能证明 Agent 每次都做对了；文档也没有替代审查，代码仍须通过测试、运行验证和 PR 审查。

让 Agent 理解产品，不是把所有判断一次性塞进提示词，而是把背景、契约和经验放到它能按任务读取的地方：记忆保存讨论与偏好，设计文档说明行为和接口，规范沉淀重复教训。审查与验证继续负责把关。

Agent 知道了该做成什么样，接下来还要回答：一条具体的用户建议，怎样从讨论走到版本号？下一篇继续追踪这条路径。