AI Agent 的失忆症：每个新 session 都要重新认识你的项目

Claude Code / Codex / Cursor 每次启动都是一张白纸。 这不是模型不够强，是你没有给它一套「上下文工程」机制。

我用 AI 编码助手快一年了。最开始惊艳，后来逐渐烦躁。

不是它写不了代码，而是每次新开一个 session，它都像第一天入职的新人：

• 不知道项目结构 → 先 grep 半小时
• 不知道技术选型 → 写出来的代码跟现有风格对不上
• 不知道上次改了啥 → 重复造轮子，甚至把修过的 bug 重新引入
• 不知道跨项目依赖 → 改了后端 API 但前端没同步，CI 挂了

直到我发现：问题不是 AI 不够聪明，是我没有给它一套「上下文工程」机制。

为什么 Agent 记不住？

2026 年的两篇研究给出了答案。

ETH Zurich 在 ICSE 2026 的论文发现：给 agent 一个又长又泛的 AGENTS.md，反而让任务成功率降低了 2-3%，成本增加了 20%+。 原因是启动时塞入太多信息，其中大部分是"应该知道的"而不是"当下要用的"——模型分不清优先级。

GitHub 分析了 2500+ 仓库的 AGENTS.md 文件，结论是：大多数 AGENTS.md 失败不是因为技术限制，而是写得太模糊。

// ❌ 反模式：散文段落
"我们重视代码质量，遵循 TDD 原则，希望所有修改都经过充分测试。"

// ✅ 正确：命令优先
// 测试
uv run pytest tests/ -v --cov=80%

// 格式化
uv run ruff format . && ruff check --fix

第一条 agent 读了等于没读。"重视代码质量"是人类的价值观，不是 agent 的可执行指令。第二条才是 agent 能理解的——一个确切的 shell 命令。

三层记忆架构

基于这些发现，我搭了一套三层工作区记忆架构——从被动到主动，逐层解决 agent 失忆问题。

Layer 1: 静态文件
  AGENTS.md + HANDOVER.md + ADR
  → 给 agent 读的，告诉它项目背景

Layer 2: 知识图谱引擎
  CodeGraph / GitNexus (MCP)
  → 让 agent 自己查代码间的依赖关系

Layer 3: 生命周期 Hooks
  SessionStart → PreToolUse → SessionEnd
  → 自动执行，agent 不需要"记得"去做

Layer 1：静态文件

每个项目放三份文件：

多项目工作区再多一层索引：

workspace/
├── AGENTS.md          ← 项目地图：有哪些项目、依赖方向
└── shared/            ← 跨项目 API 契约
    ├── api-contracts.md
    └── architecture-overview.md

service-a/
├── AGENTS.md          ← 技术指南
├── HANDOVER.md        ← 会话日志（跨 session 记忆）
└── docs/decisions/    ← ADR 架构决策

AGENTS.md 的关键写法：命令优先，不用散文，约束按优先级编号。

// ❌ 错误（agent 会忽略）
"我们倾向于使用异步编程模式，注意异常处理。"

// ✅ 正确（agent 会执行）
## 约束（按优先级）
1. 所有密钥从 .env 读取，禁止硬编码
2. 数据库迁移只能 ADD，不能 DROP/RENAME
3. 测试覆盖率不低于 80%

HANDOVER.md 是 agent 的跨 session 记忆：

# HANDOVER
 
## 当前目标
实现用户注册 API
 
## 变更记录
| 日期 | 类型 | 范围 | 描述 |
|------|------|------|------|
| 2026-06-25 | Added | auth | 邮箱验证逻辑 |
 
## 已完成
- [x] 2026-06-25 用户注册 API — 含邮箱验证
 
## 进行中
- [ ] 2026-06-26 OAuth 登录 — token 刷新待做
 
## 关键决策
| 日期 | 决策 | 原因 |
|------|------|------|
| 2026-06-25 | 用 FastAPI | 原生 async + 自动 OpenAPI |

Layer 2：知识图谱

AGENTS.md 解决的是"项目背景"，但对于"改这个函数会影响 47 个调用方"这种问题，静态文件没用。

CodeGraph（47.4k ★, MIT）和 GitNexus（42k ★）是 2026 年爆发的两个开源项目。它们的做法是：用 tree-sitter 解析整个代码库，把 imports、calls、class 继承预索引到一个本地数据库，通过 MCP 暴露给 agent。

实测数据：

• CodeGraph 减少 58-70% agent tool calls
• GitNexus 在一项 17-agent 生产审计中减少 88%

agent 接到任务：修改 handleLogin 函数
  → 调用 CodeGraph 查"谁调用了 handleLogin？"
  → 发现 3 个路由 + 1 个中间件依赖它
  → 规划修改顺序 → 改后跑测试
  → 一次通过，没炸

Layer 3：生命周期 Hooks（最关键）

前两层是告诉 agent"你应该做什么"——agent 可能遵守，也可能不。Hooks 是确定性的：它们一定执行。

Claude Code 支持 6 种 hook 事件（SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SessionEnd）。我们只用了 3 个就解决了大多数问题：

SessionStart hook — Agent 启动时自动运行。

• 读 HANDOVER.md 显示上次做到了哪里
• 检查环境：AGENTS.md 存在？CLAUDE.md 符号链接完整？
• 如果 HANDOVER.md 超过 14 天未更新，提醒可能过期

PreToolUse hook — 写入文件前自动触发。

• 检测到要改多个文件 → 提醒先查 CodeGraph 影响范围
• 检测到 .env 文件操作 → 阻止密钥泄漏

SessionEnd hook — Session 结束时自动执行。

• 从 git diff 提取本次修改摘要
• 追加到 HANDOVER.md 的变更记录
• 包含分支名、文件列表、修改统计

这意味着：agent 不需要"记住"更新手账，SessionEnd hook 会自动写。

# HANDOVER.md 的 SessionEnd 自动追加内容
 
## Session End: 2026-06-26 15:30
- 分支: feat/user-auth
- 未提交文件数: 5
- 本次修改:
   src/api/auth.py     | 45 +++++++++++++++++++
   tests/test_auth.py  | 78 +++++++++++++++++++++++++++++++++++++

防腐措施

AGENTS.md 会过期。代码在演化，但 AGENTS.md 可能还写着"用 Jest"但实际项目已经换成了 Vitest。

agents-lint 是一个轻量工具，专门检测 AGENTS.md 的腐败程度：

• 检查每个引用路径是否还存在（目录改名了？文件移走了？）
• 检查 npm scripts 是否还有效（npm run test 但 package.json 里早删了？）
• 检测框架模式是否过时（AGENTS.md 还写着 Angular @NgModule 但项目已升级到 standalone？）
• 跨文件一致性检查（AGENTS.md 说用 yarn，CLAUDE.md 说用 npm——冲突了）

我们在 CI 中加了每周自动检查，因为代码会变，但 AGENTS.md 不会——如果没有自动检测，它在两个月后就会悄悄变成一张废纸。

一套组合拳的效果

初始化一个工作区只需要一行命令：

$ pnpm create agent-workspace ./project api-gateway user-service --hooks --ci

做完之后的日常：

Agent 再也不是"每次白纸一张"，而是每次带着上次的记忆工作。

开始使用

完整的参考架构已开源：

• GitHub 模板仓库: github.com/lennney/agent-workspace-refarch
• npm 包: npx create-agent-workspace@latest

包含：

• 工作区 + 子项目的 AGENTS.md 模板（中文）
• HANDOVER.md 会话日志模板（80 行自动归档）
• ADR 架构决策模板（日期编号，多项目不冲突）
• 5 个 Claude Code 生命周期 hooks 脚本
• agents-lint 集成 + GitHub Actions CI
• validate.sh + pre-commit hook
• CodeGraph / GitNexus / Repomix 集成指南

AI agent 的能力已经够用了，瓶颈在于上下文工程。
与其等模型变大，不如把现有的上下文管好。