Agent.md 与 Memory.md 规范

一句话定义：Agent.md 是描述 Agent 身份/能力/边界的配置文件；Memory.md 是 Agent 持久化记忆的 Markdown 存储——两者都是用 Markdown 组织 Agent 元信息的轻量实践。

1. Agent.md

1.1 定义

Agent.md 是一个 Markdown 文件，用结构化文本描述一个 Agent 的身份、职责、能力、边界、工具、行为规范、输出格式、失败处理，作为 Agent 的"配置 + 说明 + 系统提示来源"。

它本质上是声明式 Agent 定义：把原本散落在系统提示、配置文件、代码硬编码里的 Agent 行为约束，统一收敛到一个可读、可版本化、可评审的 Markdown 文件中。

1.2 典型内容（完整模板）

# Agent: 代码审查员

## 身份
你是资深代码审查员，专注代码质量与安全。
风格：直接、有依据、分级清晰，避免空泛评价。

## 职责
- 审查代码变更（PR diff）
- 指出 bug、安全、性能、可维护性问题
- 给出可执行的改进建议

## 能力 / 工具
- 静态分析工具（eslint/semgrep）
- 代码库检索（grep/语义检索）
- 规范知识库（团队编码规范）

## 边界
- 不直接修改代码，只给建议
- 不审查超出本仓库的代码
- 不对业务正确性做最终裁决（需人工确认）

## 输入约定
- 输入：PR diff + 上下文文件路径
- 不接受：二进制文件、超 10k 行的单次输入

## 输出格式
按严重程度分级，每条附位置与示例：
- [critical] 路径:行号 — 问题描述 — 建议
- [major]    ...
- [minor]    ...
末尾给一句总体结论。

## 行为规范
- 每条建议必须可执行（给出代码或具体步骤）
- 不确定时明确标注"需人工确认"，不臆测
- 优先级：安全 > 正确性 > 性能 > 风格

## 失败处理
- 工具调用失败：重试 1 次，仍失败则降级为人工提示
- 输入不完整：先请求补全，不自行假设

1.3 字段规范建议

字段	必填	作用	写作要点
身份	✅	定调语气与视角	一句话角色 + 风格描述
职责	✅	划定做什么	用动词开头，可枚举
能力/工具	✅	声明可用手段	列具体工具名，避免"各种工具"
边界	✅	划定不做什么	与职责对称，显式否定
输入约定	⭐	约束入口	格式、规模、不接受项
输出格式	⭐	约束出口	结构化、可解析
行为规范	⭐	细化风格	可量化优先级与规则
失败处理	⭐	健壮性	降级、重试、人工兜底

✅ = 强烈建议，⭐ = 进阶建议

1.4 价值

声明式配置：用 Markdown 声明 Agent 行为，易读易改，无需改代码。
可版本化：随代码库管理，可追溯 Agent 行为演进。
团队共享：非工程人员（PM/法务/安全）也能读懂与评审 Agent 行为。
可组合：多个 Agent.md 定义不同角色，配合多 Agent 系统。
可测试：Agent.md 即"行为契约"，可据此做回归评测。
可移植：跨 IDE/框架复用（VS Code、Cursor、Claude Code 等都支持类似约定）。

1.5 最佳实践

写作层面

身份要"窄"：一个 Agent 只扮演一个清晰角色，避免"全能助手"式定义。
职责与边界对称：每条职责尽量配一条"不做"，防止越界。
用动词、可量化：写"按严重程度分级并附行号"，而非"认真审查"。
显式否定：把常见误用写成边界，如"不臆测业务逻辑"。
输出可解析：约定结构化格式（JSON/分级列表），便于下游消费。
示例驱动：复杂规范附 1-2 个正例/反例，比纯描述更有效。

工程层面

分层组织：根目录放全局 Agent.md，子模块放局部覆盖；遵循"就近原则"。
applyTo 精确：若平台支持作用域（如 VS Code applyTo），按文件模式精确匹配，避免污染无关场景。
与系统提示解耦：Agent.md 是"源"，系统提示由它生成/注入，不要反向在提示里硬编码。
纳入评审：Agent.md 变更走 PR 评审，像改代码一样改 Agent 行为。
加版本与变更日志：文件头注明版本与最后更新日期，便于追溯。
做评测：用 Agent.md 作为行为契约，构建回归用例集，防止行为漂移。

安全层面

最小工具集：只声明真正需要的工具，避免过度授权。
敏感操作显式约束：如"删除/部署类操作必须人工确认"。
不存密钥：Agent.md 是公开配置，绝不放密钥/Token。

1.6 反模式

❌ 全能 Agent：一个文件塞满所有职责，边界模糊。
❌ 空泛形容词："认真、专业、友好"——不可执行、不可测试。
❌ 隐藏硬编码：行为约束散落在代码里，Agent.md 形同虚设。
❌ 从不更新：Agent.md 与实际行为脱节，变成过期文档。
❌ 过度授权：为图方便给所有工具权限，放大风险。

1.7 实践生态

VS Code Copilot：.instructions.md / copilot-instructions.md / .prompt.md
通用约定：AGENTS.md（多 Agent 协作中的 Agent 描述文件）
Cursor：.cursorrules
Claude Code：CLAUDE.md
本质相同：用 Markdown 组织 Agent 元信息。

2. Memory.md

2.1 定义

Memory.md 是用 Markdown 文件持久化 Agent 记忆的轻量实践——把关键事实、决策、偏好以结构化文本存盘，跨会话复用。

它解决的是 LLM 无状态问题：每次会话默认"失忆"，Memory.md 让 Agent 能"记住"跨会话的关键信息，而无需数据库。

2.2 典型内容（分层模板）

# Memory

> 维护人：Agent 自动写入 + 人工定期整理
> 最后更新：2026-06-27
> 注入策略：用户偏好全量注入；项目事实按需；历史决策摘要注入

## 用户偏好（高频硬约束，全量注入）
- 偏好简洁回答，少用客套
- 代码风格：TypeScript + 2 空格 + 单引号
- 回答语言：中文

## 项目事实（稳定硬事实，按需注入）
- 主分支: main
- 测试命令: npm test
- 部署: vLLM on k8s
- 关键依赖: React 18 / Node 20

## 历史决策（低频参考，摘要注入）
- 2026-06-20: 选 vLLM 部署，因成本与吞吐（详见 ADR-001）
- 2026-06-25: 弃用 X 工具，因不稳定

## 待办 / 临时（短期，定期清理）
- [ ] 待确认：API 限流策略
- [ ] 临时：本周用 staging 环境测试

## 过期归档（保留但不再注入）
- 2026-05-01: 旧部署方案（已废弃）

2.3 记忆分层模型

层级	内容	更新频率	注入策略	示例
L1 用户偏好	稳定个人/团队偏好	低	全量注入	"用 TypeScript"
L2 项目事实	稳定项目硬事实	低	按需注入	"主分支 main"
L3 历史决策	关键决策与理由	中	摘要注入	"选 vLLM 因成本"
L4 待办/临时	短期任务状态	高	按需注入	"待确认限流"
L5 过期归档	历史但不再活跃	极低	不注入	"旧部署方案"

原则：越稳定越靠前，越易变越靠后；越靠前越全量注入，越靠后越按需/不注入。

2.4 价值

轻量持久化：无需数据库，Markdown 即可。
人可读：人与 Agent 都能读写，可人工纠错。
可版本化：随仓库管理，记忆演进可追溯。
可检索：可配合向量检索或直接全文注入。
低成本：相比向量库，无嵌入/检索开销，适合少量关键事实。

2.5 与向量记忆的关系

维度	Memory.md	向量记忆库
适合内容	结构化、少量、高频硬约束	大量、非结构化、按语义检索
检索方式	全量注入 / 关键词	语义相似度 Top-K
成本	低（无嵌入）	高（嵌入+检索）
精确度	高（显式事实）	近似（语义召回）
更新	直接编辑	重新嵌入
可读性	人可读	需工具查看

协同模式：

Memory.md 放"必读硬约束"（偏好、项目事实、当前决策）。
向量库放"按需召回的历史"（过往对话、长文档片段）。
注入时：Memory.md 全量/分层注入系统提示，向量库按 query 召回补到上下文。

2.6 最佳实践

写入层面

只记关键：记"会反复用到的硬事实"，不记一次性闲聊。
结构化：用分层 + 列表，避免大段散文，便于注入与检索。
带时间与来源：每条决策附日期与依据，便于追溯与过期判断。
原子化：一条记忆一个事实，避免"既…又…"的复合条目。
可证伪：写"主分支是 main"，而非"分支管理很规范"。

维护层面

定期整理：每日/每周清理 L4 待办，归档 L5 过期项。
去重：同一事实只保留一处，避免注入时冲突。
纠错：发现错误立即更新，旧值移入归档而非删除（保留审计）。
设过期：临时项标注有效期，到期自动降级到归档。
容量上限：建议单文件 < 200 行，超限则拆分或迁移到向量库。

隐私与安全

敏感信息不入：密钥、Token、个人隐私绝不写入。
脱敏：必须记的业务数据做脱敏处理。
访问控制：Memory.md 随仓库权限管理，公开仓库慎写内部信息。
审计：记忆变更走版本控制，可追溯谁改了什么。

注入层面

分层注入：L1 全量、L2 按需、L3 摘要、L4 按需、L5 不注入。
预算控制：注入总 token 不超上下文预算的 10-20%，留空间给对话。
优先级：冲突时 L1 > L2 > L3，高优先级覆盖低优先级。
可观测：记录每次注入了哪些记忆，便于调试"为什么这么回答"。

2.7 反模式

❌ 什么都记：把每次对话都塞进 Memory.md，迅速膨胀且噪声大。
❌ 从不整理：过期信息堆积，注入污染上下文。
❌ 散文式：大段叙述，难以注入与检索。
❌ 存密钥：把敏感信息当"记忆"持久化。
❌ 全量注入：不分层，把所有记忆都塞进系统提示，挤占上下文。
❌ 与向量库重复：同一事实两边都存，增加维护成本与不一致风险。

3. Agent.md 与 Memory.md 的关系

3.1 分层定位

Agent.md = 静态配置：定义"Agent 是谁、能做什么、怎么做"——相对稳定，随版本发布。
Memory.md = 动态记忆：记录"Agent 经历了什么、学到了什么"——持续演化，跨会话累积。

3.2 生命周期对比

维度	Agent.md	Memory.md
变更频率	低（随版本）	高（随会话）
变更主体	人工（PR 评审）	Agent 自动 + 人工整理
注入时机	会话开始全量注入系统提示	分层按需注入
回滚	走 Git 版本	走 Git 版本 + 归档
评测	作为行为契约做回归	作为上下文影响评测

3.3 协同工作流

会话开始：加载 Agent.md → 生成系统提示；按策略注入 Memory.md 分层内容。
会话中：Agent 根据交互判断是否写入 Memory.md（新偏好/决策/待办）。
会话结束/定期：触发整理——去重、归档过期、纠错。
评审周期：人工 review Memory.md 变更，必要时回写 Agent.md（如偏好固化为规范）。

4. 设计要点总览

分层：Agent.md 是"静态配置"，Memory.md 是"动态记忆"。
更新策略：Memory.md 需定期整理、去重、纠错、过期；Agent.md 走 PR 评审。
隐私：敏感信息不入 Memory.md，或脱敏；Agent.md 不存密钥。
注入策略：Agent.md 全量注入系统提示；Memory.md 分层按需注入。
容量：Memory.md 单文件 < 200 行，超限拆分或迁移向量库。
可观测：记录注入内容与记忆变更，便于调试与审计。
评测：Agent.md 作行为契约做回归；Memory.md 变更纳入评测影响分析。

5. 学习要点

Agent.md / Memory.md 是用 Markdown 组织 Agent 元信息的轻量实践。
声明式配置 + 人可读持久化，降低 Agent 工程门槛。
Agent.md 重"静态契约"，Memory.md 重"动态累积"，两者分层互补。
与向量记忆互补：结构化硬约束用 md，海量历史用向量库。
关键在"纪律"：定期整理、分层注入、最小授权、隐私脱敏。

6. 参考资料

VS Code Copilot .instructions.md / copilot-instructions.md 实践
AGENTS.md 约定（多 Agent 协作中的 Agent 描述文件）
Cursor .cursorrules / Claude Code CLAUDE.md
"Generative Agents"（记忆/反思机制）
ADR（Architecture Decision Records）——历史决策记录的成熟范式

02-Agent.md与Memory.md规范