Agent 改完代码，仓库里到底该多留下什么

以前一轮开发结束仓库里多出来的东西很清楚diff、测试运气好还有一份设计说明。现在 Agent 也能交差而且通常更快。真正麻烦的是另一面会话一关贵的判断跟着蒸发。为什么这么改、踩过什么坑、哪条红线不能碰、验收到底跑过哪些命令聊天里都说过仓库里常常没有。代码还在。上下文没了。Anthropic 后来把这个尴尬说透了。长任务要跨好几个上下文窗口每个新窗口都像换班工程师对上一班毫无记忆。他们不指望把聊天记全而是要求每一班结束时留下下一位能立刻上手的东西清楚的 commit、进度文件、能拉起环境的脚本、带状态的功能清单。我现在看一个仓库也不再只问「这波功能交了没」。更想问Agent 跑完一轮后有没有留下下一轮还能用的东西。下面按这个标准把官方文档、开源仓库和我自己踩过的坑收一收。仓库续航资产分层知识记忆决策技能按需加载规则与验收每次会话必留知识记忆决策技能按需加载规则与验收每次会话必留一、大家其实在说同一件事名字五花八门指向差不多会话会断仓库得接得住。Anthropic 那篇《Effective harnesses for long-running agents》写得很具体。coding agent 要做增量结束时工作区要接近可合主线描述清楚的 git commit、进度文件、init.sh再加一份带passes字段的功能清单。半成品丢给下一班去猜不行没做端到端验证就把功能标绿也不行。配套例子在anthropics/claude-quickstarts。OpenAI Codex 拆得更直白AGENTS.md管规则Memories 管学到的上下文Skills 管可复用流程。你纠正 Agent 一次最好当场让它写回AGENTS.md。反馈环进仓库别只活在对话里。Claude Code 的记忆文档则分两层。你写的CLAUDE.md是指令auto memory 是它根据纠正自己攒的偏好。多步流程别塞常驻文件该进 Skill真想拦住某类操作用 Hook别指望「它记住了就会听话」。开源这边AGENTS.md已经像默认约定agents.mdREADME 给人看AGENTS.md 给 Agent 看内容通常是构建命令、怎么测、项目约定、安全注意事项。GitHub 扫了 2500 多个仓库好用的文件几乎同款命令靠前给真实代码示例写清边界和技术栈常见六块是 commands、testing、structure、style、git、boundaries。Taiizor/agents-md-cookbook和vltansky/agents-md-evals更狠一点写短只写代码里读不出来的规则最好用 eval 验一下是不是真改变行为别越写越长。Agent Skills 标准agentskills.io则把「怎么做」拆成可加载包SKILL.md外加可选的scripts/、references/、assets/。用到再读省得每次会话都吞一本手册。我自己判断要不要沉淀只剩一个问题关掉当前会话换个模型换个人接手。哪些信息还成立而且还能约束下一次改动答得上再写进仓库。答不上归档就行别占常驻上下文。二、八类资产比「知识 记忆 E2E」多出来的那些很多人已经会留三类知识、记忆、端到端测试。这三类对但还不够。Agent 最容易弄丢的是中间那些「为什么」和「怎么验」。类型回答的问题常见落点知识是什么docs/、模块说明AGENTS 里只留不可推断事实记忆谁 / 偏好 / 不变量Claude auto memory、Codex Memories决策为何如此短 ADR功能清单里的取舍与否决项规则必须 / 禁止AGENTS.md/CLAUDE.md、目录级覆盖、Hook技能怎么做SKILL.md、Playbook、scripts契约边界在哪模块边界、Never touch、接口与目录约定测试与 Eval怎样算对单测/契约/E2Efeatures.json规则 A/B eval状态与承诺现在卡在哪progress 文件、git log、未完成 feature 列表几条细则我反复撞上也在上述材料里反复出现。规则要短而且尽量写「代码读不出来」的东西。ETH Zurich 的 AGENTbench 和不少 AGENTS 实践都警告过LLM 自动生成的超长指令可能把成功率打下去还抬成本。栈和风格代码里看得见就少写耦合关系、工作流硬要求、领域红线才值得占位置。验收别靠自称完成。Anthropic 观察到单元测试或curl绿了端到端照样可能坏。做 Web 时他们甚至要求浏览器自动化像真人一样点一遍。开源 eval 仓库把同一逻辑用到规则本身这条AGENTS.md有没有改变行为要测不要猜。Skill 和规则别混。每次都要遵守的放常驻文件多步、局部、能脚本化的进 Skill。OpenAI、Anthropic、agentskills.io 在这点上差不多。真硬的约束进 Hook 或 CI。Claude 文档写得很清楚memory 是上下文不是强制配置。想做到「无论模型怎么想都不能碰」靠 PreToolUse Hook 或流水线别只写进 Markdown 自我安慰。如果只能先补一类我会补可执行规则和可重跑验收。官方材料里这两样出现最多也最容易在聊天里说完就丢。一轮结束后的留痕闭环纠正写入规则补验收更新进度留给下一班纠正写入规则补验收更新进度留给下一班三、一轮结束至少留下这个最小包八类不用一次建齐。更接近 Anthropic 实验的做法是有价值的会话结束时强制留下一个最小包。进度和 git 先写清楚。progress 文件加描述性 commit下一班先读这两样别猜半成品。口头纠正过、而且还会再发生的写进最近的AGENTS.md或目录级覆盖。Codex 的说法很实用同一类 PR 反馈出现第二次就该成文。再留至少一条机器能判定的验收。测试、脚本、类型检查、浏览器 E2E 都行。换会话后还能重跑对错不靠嘴辩。未完成项也要看得见。哪些功能还是passes: false哪些假设没验证哪些 workaround 有过期日。Anthropic 用 JSON feature list就是为了压「过早宣布胜利」。最后看一眼工作区干不干净。他们说的 clean state大致等于接近可合主线没有明显烂尾文档跟得上下一个人能直接开新功能。这比生成一份很长的NOTES.md有用得多。我现在会贴这么一张卡Agent 任务收工检查最小包 □ Why决策/取舍/不做项短笔记即可 □ Rule本次纠正是否写入 AGENTS.md / Hook □ Proof至少一条可重跑验收涉及 UI 就补 E2E □ Scar若翻车失败样本或禁令已落盘 □ Nextprogress / feature 状态 / 未验证假设 □ Clean工作区接近可合入不留半截工程比例还是要克制。改一行文案不必写 ADR动了共享模块却只留一句update那是在欠下一位的债。四、同样改完仓库里差很多先说糟糕的那种。Agent 改完packages/paymentPR 写着「支持新折扣字段」测试全绿。第二天packages/checkout编译挂了。聊天里其实说过要同步改调用方结束前还要跑跨包 typecheck。会话一关这些话全没了。再看留得住的那种。同一轮结束后多了几样不显眼的东西短决策说明字段为什么放在 payment以及明确不做顺手重构AGENTS.md加一条触及 payment 导出就要跑 payment 和 checkout 的 typecheck一条契约测试锁住字段形状若已经翻过车Hook 在相关 diff 上强制检查。下一班不必靠记性。它读规则跑闸门撞测试。人审 PR 时也能看见取舍而不只看见一片绿色 diff。还有一种空忙我见得最多把整段对话摘要塞进常驻NOTES.md。文件很大检索很吵错总结还会被当成事实。更干净的拆法是偏好进记忆红线进规则流程进 Skill过程进可搜索历史。摘要若要留得能指回 commit 或 issue并且允许删。别追求沉淀体积。密度够用就行。五、今天就能动手的顺序先写短AGENTS.md。命令、边界、测试怎么跑对照 GitHub 说的那六块百行量级差不多只写代码读不出来的。再加收工约定。Agent 声称完成前对照上面的最小包勾选勾不上就明说缺什么。然后补验证。老模块至少写清验收命令UI 路径补一条真人视角检查有余力再拿agents-md-evals这类工具给规则瘦身。Skill 放最后。同一条路径成功走通几次再抽成SKILL.md。太早技能化容易把偶然 workaround 焊成标准。优先级先留什么为什么先做P0命令 红线 可重跑验收立刻减少假完成和越界P1进度/状态 规则反馈环下一班不用猜同类错少交第二次学费P2窄 Skill 模块边界提高跨会话起点P3记忆治理与规则 eval长期有用但先防污染六、收工时多问一句就够Agent coding 有没有做完别只盯着「功能有了吗」。再问一句如果现在清空会话只留这个仓库下一个 Agent 还会不会再踩这次的坑会少踩说明你留下了续航物。不会多半只是把生产 diff 的速度加快了。今天就能做的最小动作翻开最近一个由 Agent 主导的 PR补三行 Why补一条验收命令再往AGENTS.md里加一条禁令或必跑检查。八类资产不用一次建齐先让教训离开聊天框。学习资源推荐如果你想更深入地学习大模型以下是一些非常有价值的学习资源这些资源将帮助你从不同角度学习大模型提升你的实践能力。一、全套AGI大模型学习路线AI大模型时代的学习之旅从基础到前沿掌握人工智能的核心技能​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取二、640套AI大模型报告合集这套包含640份报告的合集涵盖了AI大模型的理论研究、技术实现、行业应用等多个方面。无论您是科研人员、工程师还是对AI大模型感兴趣的爱好者这套报告合集都将为您提供宝贵的信息和启示​因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取三、AI大模型经典PDF籍随着人工智能技术的飞速发展AI大模型已经成为了当今科技领域的一大热点。这些大型预训练模型如GPT-3、BERT、XLNet等以其强大的语言理解和生成能力正在改变我们对人工智能的认识。 那以下这些PDF籍就是非常不错的学习资源。因篇幅有限仅展示部分资料需要点击文章最下方名片即可前往获取四、AI大模型商业化落地方案作为普通人入局大模型时代需要持续学习和实践不断提高自己的技能和认知水平同时也需要有责任感和伦理意识为人工智能的健康发展贡献力量。